@danypops/vehicle-core 0.1.1 → 0.2.0

package/README.md

@@ -13,3 +13,12 @@ descriptor kept separate from its executable handler. See the
 [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

@@ -34,6 +34,38 @@ export interface LooseObjectProperty {
 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

@@ -44,6 +44,31 @@ 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.1",
+	"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",

package/src/vehicle-contract.ts

@@ -68,6 +68,53 @@ export const passthroughVehicleSchema: VehicleSchemaCodec<unknown> = defineVehic
 	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 =