@danypops/vehicle-core 0.1.0 → 0.2.0

package/README.md

@@ -10,6 +10,15 @@ bun add @danypops/vehicle-core
 
 `defineVehicleOperation()`/`bindVehicleOperation()` build a serializable
 descriptor kept separate from its executable handler. See the
-[workspace README](https://github.com/DanyPops/daemon-kit#readme) for how it
+[workspace README](https://github.com/DanyPops/vehicle#readme) for how it
 fits with `@danypops/vehicle-server`, `@danypops/vehicle-client`, and
 `@danypops/vehicle-client-pi`.
+
+An operation whose result should be read as a narrative rather than parsed
+as data can intersect its Output type with `WithVehicleContent` and include
+a `content: [{ type: "text", text }]` field alongside its own domain data --
+the same field name and shape MCP's `CallToolResult.content` and Pi's own
+tool-result type use, so no translation layer is needed at either boundary.
+`extractVehicleContent(output)` reads those blocks back out for a generic
+Vehicle client to prefer over raw JSON, returning undefined for absent or
+malformed content so the caller can fall back safely.

package/dist/vehicle-contract.d.ts

@@ -19,6 +19,53 @@ export interface VehicleSchemaCodec<T> {
     safeParse(value: unknown): VehicleSchemaResult<T>;
 }
 export declare function defineVehicleSchema<T>(codec: VehicleSchemaCodec<T>): VehicleSchemaCodec<T>;
+export interface LooseObjectProperty {
+    readonly type: string;
+    readonly enum?: readonly string[];
+}
+/**
+ * A 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. Every
+ * consumer projecting a plain-object input onto a VehicleOperation needs the
+ * same required/enum checks; this is that check written once.
+ */
+export declare function defineLooseObjectSchema(properties: Record<string, LooseObjectProperty>, required?: readonly string[]): VehicleSchemaCodec<Record<string, unknown>>;
+/** Accepts any value unvalidated -- for an operation whose output shape isn't worth a dedicated schema (an internal/low-stakes result, or one already validated upstream by the domain logic it wraps). */
+export declare const passthroughVehicleSchema: VehicleSchemaCodec<unknown>;
+/**
+ * A block of narrative text meant to be read by the model, not parsed as
+ * data -- same field name and shape MCP's own CallToolResult.content and
+ * Pi's own ToolDefinition.execute() return already use, so a Vehicle
+ * operation adopting this needs no translation layer at either boundary.
+ * Only the "text" variant exists here; there's no Vehicle use case yet for
+ * MCP's image/audio/resource-link block kinds.
+ */
+export interface VehicleContentBlock {
+    readonly type: "text";
+    readonly text: string;
+}
+/**
+ * An operation's Output type can intersect this to carry its own
+ * model-facing narrative alongside its structured data, e.g.
+ * `type RunOutput = { runId: string; created: Task[] } & WithVehicleContent`.
+ * The operation itself builds `content` since it's the only code that
+ * actually knows how to describe what it computed -- never a per-consumer
+ * override bolted on wherever the operation happens to get registered.
+ */
+export interface WithVehicleContent {
+    readonly content?: readonly VehicleContentBlock[];
+}
+/**
+ * Reads an operation's own `content` blocks off its output when present and
+ * well-formed, so a generic Vehicle client can prefer them over dumping raw
+ * JSON at the model -- without knowing anything about the operation's own
+ * domain shape. Returns undefined for a malformed or absent `content` field;
+ * the caller falls back to its own default (formatted JSON) rather than
+ * risk forwarding partial/garbled blocks.
+ */
+export declare function extractVehicleContent(output: unknown): readonly VehicleContentBlock[] | undefined;
 export type VehicleEffect = "read" | "local-write" | "external-write" | "destructive" | "open-world";
 export type VehicleIdempotency = {
     readonly mode: "safe";

package/dist/vehicle-contract.js

@@ -4,6 +4,71 @@ export function defineVehicleSchema(codec) {
         safeParse: codec.safeParse,
     });
 }
+/**
+ * A 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. Every
+ * consumer projecting a plain-object input onto a VehicleOperation needs the
+ * same required/enum checks; this is that check written once.
+ */
+export function defineLooseObjectSchema(properties, required = []) {
+    return defineVehicleSchema({
+        // LooseObjectProperty's named fields (type, enum) are all JSON-value-shaped
+        // at runtime, but TypeScript's structural check against the recursive
+        // JsonValue union doesn't see that through a plain interface -- the cast
+        // is a type-system limitation, not a runtime concern.
+        jsonSchema: { type: "object", properties: properties, required: [...required], additionalProperties: false },
+        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;
+            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])) {
+                    return { success: false, issues: [{ path: [key], message: `${key} must be one of ${schema.enum.join(", ")}` }] };
+                }
+            }
+            return { success: true, value: input };
+        },
+    });
+}
+/** Accepts any value unvalidated -- for an operation whose output shape isn't worth a dedicated schema (an internal/low-stakes result, or one already validated upstream by the domain logic it wraps). */
+export const passthroughVehicleSchema = defineVehicleSchema({
+    jsonSchema: { type: "object" },
+    safeParse: (value) => ({ success: true, value }),
+});
+/**
+ * Reads an operation's own `content` blocks off its output when present and
+ * well-formed, so a generic Vehicle client can prefer them over dumping raw
+ * JSON at the model -- without knowing anything about the operation's own
+ * domain shape. Returns undefined for a malformed or absent `content` field;
+ * the caller falls back to its own default (formatted JSON) rather than
+ * risk forwarding partial/garbled blocks.
+ */
+export function extractVehicleContent(output) {
+    if (typeof output !== "object" || output === null || Array.isArray(output))
+        return undefined;
+    const content = output.content;
+    if (!Array.isArray(content) || content.length === 0)
+        return undefined;
+    const blocks = [];
+    for (const block of content) {
+        if (typeof block !== "object" || block === null)
+            return undefined;
+        const { type, text } = block;
+        if (type !== "text" || typeof text !== "string")
+            return undefined;
+        blocks.push({ type: "text", text });
+    }
+    return blocks;
+}
 export function defineVehicleOperation(options) {
     validateOperationMetadata(options);
     const descriptor = Object.freeze({

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@danypops/vehicle-core",
-	"version": "0.1.0",
+	"version": "0.2.0",
 	"description": "Vehicle's runtime-neutral wire contract: operation descriptors, schema codecs, failure shapes. Zero runtime dependencies, zero Bun-specific code -- the one thing every Vehicle client and server package depends on.",
 	"license": "MIT",
 	"type": "module",
@@ -23,7 +23,7 @@
 	},
 	"repository": {
 		"type": "git",
-		"url": "git+https://github.com/DanyPops/daemon-kit.git",
+		"url": "git+https://github.com/DanyPops/vehicle.git",
 		"directory": "packages/vehicle-core"
 	},
 	"keywords": ["vehicle", "agent-tools"],

package/src/vehicle-contract.ts

@@ -23,6 +23,98 @@ export function defineVehicleSchema<T>(codec: VehicleSchemaCodec<T>): VehicleSch
 	});
 }
 
+export interface LooseObjectProperty {
+	readonly type: string;
+	readonly enum?: readonly string[];
+}
+
+/**
+ * A 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. Every
+ * consumer projecting a plain-object input onto a VehicleOperation needs the
+ * same required/enum checks; this is that check written once.
+ */
+export function defineLooseObjectSchema(properties: Record<string, LooseObjectProperty>, required: readonly string[] = []): VehicleSchemaCodec<Record<string, unknown>> {
+	return defineVehicleSchema<Record<string, unknown>>({
+		// LooseObjectProperty's named fields (type, enum) are all JSON-value-shaped
+		// at runtime, but TypeScript's structural check against the recursive
+		// JsonValue union doesn't see that through a plain interface -- the cast
+		// is a type-system limitation, not a runtime concern.
+		jsonSchema: { type: "object", properties: properties as unknown as JsonValue, required: [...required], additionalProperties: false },
+		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 };
+		},
+	});
+}
+
+/** Accepts any value unvalidated -- for an operation whose output shape isn't worth a dedicated schema (an internal/low-stakes result, or one already validated upstream by the domain logic it wraps). */
+export const passthroughVehicleSchema: VehicleSchemaCodec<unknown> = defineVehicleSchema<unknown>({
+	jsonSchema: { type: "object" },
+	safeParse: (value) => ({ success: true, value }),
+});
+
+/**
+ * A block of narrative text meant to be read by the model, not parsed as
+ * data -- same field name and shape MCP's own CallToolResult.content and
+ * Pi's own ToolDefinition.execute() return already use, so a Vehicle
+ * operation adopting this needs no translation layer at either boundary.
+ * Only the "text" variant exists here; there's no Vehicle use case yet for
+ * MCP's image/audio/resource-link block kinds.
+ */
+export interface VehicleContentBlock {
+	readonly type: "text";
+	readonly text: string;
+}
+
+/**
+ * An operation's Output type can intersect this to carry its own
+ * model-facing narrative alongside its structured data, e.g.
+ * `type RunOutput = { runId: string; created: Task[] } & WithVehicleContent`.
+ * The operation itself builds `content` since it's the only code that
+ * actually knows how to describe what it computed -- never a per-consumer
+ * override bolted on wherever the operation happens to get registered.
+ */
+export interface WithVehicleContent {
+	readonly content?: readonly VehicleContentBlock[];
+}
+
+/**
+ * Reads an operation's own `content` blocks off its output when present and
+ * well-formed, so a generic Vehicle client can prefer them over dumping raw
+ * JSON at the model -- without knowing anything about the operation's own
+ * domain shape. Returns undefined for a malformed or absent `content` field;
+ * the caller falls back to its own default (formatted JSON) rather than
+ * risk forwarding partial/garbled blocks.
+ */
+export function extractVehicleContent(output: unknown): readonly VehicleContentBlock[] | undefined {
+	if (typeof output !== "object" || output === null || Array.isArray(output)) return undefined;
+	const content = (output as { readonly content?: unknown }).content;
+	if (!Array.isArray(content) || content.length === 0) return undefined;
+	const blocks: VehicleContentBlock[] = [];
+	for (const block of content) {
+		if (typeof block !== "object" || block === null) return undefined;
+		const { type, text } = block as { readonly type?: unknown; readonly text?: unknown };
+		if (type !== "text" || typeof text !== "string") return undefined;
+		blocks.push({ type: "text", text });
+	}
+	return blocks;
+}
+
 export type VehicleEffect = "read" | "local-write" | "external-write" | "destructive" | "open-world";
 
 export type VehicleIdempotency =