@danypops/vehicle-core 0.1.1 → 0.3.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/atomic-json.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Cross-platform atomic JSON persistence -- shared by every Vehicle
+ * primitive that needs durable state (Jobs' status file, Watchers'
+ * registry) so a crash or concurrent read never observes a half-written
+ * file. Lives in vehicle-core (not vehicle-server) but stays fs-free
+ * itself: every filesystem operation is injected via `AtomicJsonFsAdapter`,
+ * matching vehicle-core's own "zero runtime dependencies" invariant --
+ * the caller (vehicle-server, vehicle-client-pi) supplies real node:fs
+ * functions, this module only sequences them.
+ *
+ * Modeled on github.com/nicobailon/pi-subagents' `createAtomicJsonWriter`:
+ * a collision-safe temp filename, injectable fs/now/pid/random for
+ * deterministic tests, and explicit Windows-aware rename retry (a plain
+ * `fs.rename` onto an existing path can transiently fail on Windows if
+ * another process -- antivirus, search indexing -- has the destination
+ * briefly open; POSIX rename() has no such failure mode, so retrying by
+ * default there would only add latency for a class of error that never
+ * happens).
+ */
+export interface AtomicJsonFsAdapter {
+    writeFile(path: string, data: string): Promise<void>;
+    rename(oldPath: string, newPath: string): Promise<void>;
+    unlink(path: string): Promise<void>;
+    readFile(path: string): Promise<string>;
+}
+export interface AtomicJsonWriterOptions {
+    readonly fs: AtomicJsonFsAdapter;
+    /** Defaults to Date.now. */
+    readonly now?: () => number;
+    /** Defaults to the current process's pid, or 0 outside Node/Bun. */
+    readonly pid?: () => number;
+    /** Defaults to a short random hex string. */
+    readonly random?: () => string;
+    /**
+     * Whether a failed rename onto the destination is retried at all.
+     * Defaults to `process.platform === "win32"` -- off on Linux/macOS,
+     * where a transient rename failure isn't a real failure mode.
+     */
+    readonly retryRename?: boolean;
+    /** Error codes on `rename` worth retrying. Defaults to ["EPERM", "EBUSY", "EACCES"] (the documented Windows file-lock codes). */
+    readonly retryRenameErrors?: readonly string[];
+    /** Delay before each retry attempt, in order. Defaults to [50, 100, 200]. */
+    readonly retryDelaysMs?: readonly number[];
+    /** Injectable so a test doesn't have to sleep for real. Defaults to setTimeout. */
+    readonly sleep?: (ms: number) => Promise<void>;
+}
+export interface AtomicJsonWriter {
+    /** Serializes `value` to JSON and writes it to `filePath` atomically (temp file + rename). */
+    write(filePath: string, value: unknown): Promise<void>;
+    /** Reads and JSON.parses `filePath`. Returns undefined if the file doesn't exist (fs.readFile throws ENOENT); rethrows any other error. */
+    read(filePath: string): Promise<unknown | undefined>;
+}
+export declare function createAtomicJsonWriter(options: AtomicJsonWriterOptions): AtomicJsonWriter;

package/dist/atomic-json.js

@@ -0,0 +1,102 @@
+/**
+ * Cross-platform atomic JSON persistence -- shared by every Vehicle
+ * primitive that needs durable state (Jobs' status file, Watchers'
+ * registry) so a crash or concurrent read never observes a half-written
+ * file. Lives in vehicle-core (not vehicle-server) but stays fs-free
+ * itself: every filesystem operation is injected via `AtomicJsonFsAdapter`,
+ * matching vehicle-core's own "zero runtime dependencies" invariant --
+ * the caller (vehicle-server, vehicle-client-pi) supplies real node:fs
+ * functions, this module only sequences them.
+ *
+ * Modeled on github.com/nicobailon/pi-subagents' `createAtomicJsonWriter`:
+ * a collision-safe temp filename, injectable fs/now/pid/random for
+ * deterministic tests, and explicit Windows-aware rename retry (a plain
+ * `fs.rename` onto an existing path can transiently fail on Windows if
+ * another process -- antivirus, search indexing -- has the destination
+ * briefly open; POSIX rename() has no such failure mode, so retrying by
+ * default there would only add latency for a class of error that never
+ * happens).
+ */
+function defaultPlatformIsWindows() {
+    return typeof process !== "undefined" && process.platform === "win32";
+}
+function defaultPid() {
+    return typeof process !== "undefined" ? process.pid : 0;
+}
+function defaultRandom() {
+    return Math.random().toString(36).slice(2, 10);
+}
+function isErrnoException(error) {
+    return error instanceof Error && "code" in error;
+}
+function dirAndBase(filePath) {
+    const separator = filePath.lastIndexOf("/");
+    if (separator === -1)
+        return { dir: ".", base: filePath };
+    return { dir: filePath.slice(0, separator) || "/", base: filePath.slice(separator + 1) };
+}
+export function createAtomicJsonWriter(options) {
+    const fsAdapter = options.fs;
+    const now = options.now ?? Date.now;
+    const pid = options.pid ?? defaultPid;
+    const random = options.random ?? defaultRandom;
+    const retryRename = options.retryRename ?? defaultPlatformIsWindows();
+    const retryRenameErrors = options.retryRenameErrors ?? ["EPERM", "EBUSY", "EACCES"];
+    const retryDelaysMs = options.retryDelaysMs ?? [50, 100, 200];
+    const sleep = options.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+    async function renameWithRetry(tempPath, filePath) {
+        let attempt = 0;
+        for (;;) {
+            try {
+                await fsAdapter.rename(tempPath, filePath);
+                return;
+            }
+            catch (error) {
+                const retryable = retryRename && isErrnoException(error) && !!error.code && retryRenameErrors.includes(error.code);
+                if (!retryable || attempt >= retryDelaysMs.length)
+                    throw error;
+                await sleep(retryDelaysMs[attempt] ?? 0);
+                attempt++;
+            }
+        }
+    }
+    return {
+        async write(filePath, value) {
+            let serialized;
+            try {
+                serialized = JSON.stringify(value);
+            }
+            catch (error) {
+                throw new Error(`atomic-json: value for ${filePath} is not JSON-serializable`, { cause: error });
+            }
+            if (serialized === undefined)
+                throw new Error(`atomic-json: value for ${filePath} is not JSON-serializable`);
+            const { dir, base } = dirAndBase(filePath);
+            const tempPath = `${dir}/.${base}.${pid()}.${now()}.${random()}.tmp`;
+            await fsAdapter.writeFile(tempPath, serialized);
+            try {
+                await renameWithRetry(tempPath, filePath);
+            }
+            catch (error) {
+                try {
+                    await fsAdapter.unlink(tempPath);
+                }
+                catch {
+                    // Best-effort cleanup -- the rename failure itself is the real error to surface.
+                }
+                throw error;
+            }
+        },
+        async read(filePath) {
+            try {
+                const raw = await fsAdapter.readFile(filePath);
+                return JSON.parse(raw);
+            }
+            catch (error) {
+                if (isErrnoException(error) && error.code === "ENOENT")
+                    return undefined;
+                throw error;
+            }
+        },
+    };
+}

package/dist/index.d.ts

@@ -1,2 +1,3 @@
+export * from "./atomic-json.js";
 export * from "./vehicle-contract.js";
 export * from "./vehicle-errors.js";

package/dist/index.js

@@ -1,2 +1,3 @@
+export * from "./atomic-json.js";
 export * from "./vehicle-contract.js";
 export * from "./vehicle-errors.js";

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({
@@ -85,7 +110,8 @@ function validateOperationMetadata(options) {
     if (limits.defaultTimeoutMs > limits.maxTimeoutMs) {
         throw new Error("Vehicle operation defaultTimeoutMs must not exceed maxTimeoutMs");
     }
-    if (options.idempotency.mode === "keyed" && (!Number.isSafeInteger(options.idempotency.retentionMs) || options.idempotency.retentionMs < 1)) {
+    if (options.idempotency.mode === "keyed" &&
+        (!Number.isSafeInteger(options.idempotency.retentionMs) || options.idempotency.retentionMs < 1)) {
         throw new Error("Vehicle keyed idempotency retentionMs must be a positive integer");
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@danypops/vehicle-core",
-	"version": "0.1.1",
+	"version": "0.3.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",
@@ -19,7 +19,7 @@
 	},
 	"devDependencies": {
 		"@types/node": "^22.0.0",
-		"typescript": "latest"
+		"typescript": "^5.9.2"
 	},
 	"repository": {
 		"type": "git",

package/src/atomic-json.ts

@@ -0,0 +1,137 @@
+/**
+ * Cross-platform atomic JSON persistence -- shared by every Vehicle
+ * primitive that needs durable state (Jobs' status file, Watchers'
+ * registry) so a crash or concurrent read never observes a half-written
+ * file. Lives in vehicle-core (not vehicle-server) but stays fs-free
+ * itself: every filesystem operation is injected via `AtomicJsonFsAdapter`,
+ * matching vehicle-core's own "zero runtime dependencies" invariant --
+ * the caller (vehicle-server, vehicle-client-pi) supplies real node:fs
+ * functions, this module only sequences them.
+ *
+ * Modeled on github.com/nicobailon/pi-subagents' `createAtomicJsonWriter`:
+ * a collision-safe temp filename, injectable fs/now/pid/random for
+ * deterministic tests, and explicit Windows-aware rename retry (a plain
+ * `fs.rename` onto an existing path can transiently fail on Windows if
+ * another process -- antivirus, search indexing -- has the destination
+ * briefly open; POSIX rename() has no such failure mode, so retrying by
+ * default there would only add latency for a class of error that never
+ * happens).
+ */
+
+export interface AtomicJsonFsAdapter {
+	writeFile(path: string, data: string): Promise<void>;
+	rename(oldPath: string, newPath: string): Promise<void>;
+	unlink(path: string): Promise<void>;
+	readFile(path: string): Promise<string>;
+}
+
+export interface AtomicJsonWriterOptions {
+	readonly fs: AtomicJsonFsAdapter;
+	/** Defaults to Date.now. */
+	readonly now?: () => number;
+	/** Defaults to the current process's pid, or 0 outside Node/Bun. */
+	readonly pid?: () => number;
+	/** Defaults to a short random hex string. */
+	readonly random?: () => string;
+	/**
+	 * Whether a failed rename onto the destination is retried at all.
+	 * Defaults to `process.platform === "win32"` -- off on Linux/macOS,
+	 * where a transient rename failure isn't a real failure mode.
+	 */
+	readonly retryRename?: boolean;
+	/** Error codes on `rename` worth retrying. Defaults to ["EPERM", "EBUSY", "EACCES"] (the documented Windows file-lock codes). */
+	readonly retryRenameErrors?: readonly string[];
+	/** Delay before each retry attempt, in order. Defaults to [50, 100, 200]. */
+	readonly retryDelaysMs?: readonly number[];
+	/** Injectable so a test doesn't have to sleep for real. Defaults to setTimeout. */
+	readonly sleep?: (ms: number) => Promise<void>;
+}
+
+export interface AtomicJsonWriter {
+	/** Serializes `value` to JSON and writes it to `filePath` atomically (temp file + rename). */
+	write(filePath: string, value: unknown): Promise<void>;
+	/** Reads and JSON.parses `filePath`. Returns undefined if the file doesn't exist (fs.readFile throws ENOENT); rethrows any other error. */
+	read(filePath: string): Promise<unknown | undefined>;
+}
+
+function defaultPlatformIsWindows(): boolean {
+	return typeof process !== "undefined" && process.platform === "win32";
+}
+
+function defaultPid(): number {
+	return typeof process !== "undefined" ? process.pid : 0;
+}
+
+function defaultRandom(): string {
+	return Math.random().toString(36).slice(2, 10);
+}
+
+function isErrnoException(error: unknown): error is NodeJS.ErrnoException {
+	return error instanceof Error && "code" in error;
+}
+
+function dirAndBase(filePath: string): { readonly dir: string; readonly base: string } {
+	const separator = filePath.lastIndexOf("/");
+	if (separator === -1) return { dir: ".", base: filePath };
+	return { dir: filePath.slice(0, separator) || "/", base: filePath.slice(separator + 1) };
+}
+
+export function createAtomicJsonWriter(options: AtomicJsonWriterOptions): AtomicJsonWriter {
+	const fsAdapter = options.fs;
+	const now = options.now ?? Date.now;
+	const pid = options.pid ?? defaultPid;
+	const random = options.random ?? defaultRandom;
+	const retryRename = options.retryRename ?? defaultPlatformIsWindows();
+	const retryRenameErrors = options.retryRenameErrors ?? ["EPERM", "EBUSY", "EACCES"];
+	const retryDelaysMs = options.retryDelaysMs ?? [50, 100, 200];
+	const sleep = options.sleep ?? ((ms: number) => new Promise<void>((resolve) => setTimeout(resolve, ms)));
+
+	async function renameWithRetry(tempPath: string, filePath: string): Promise<void> {
+		let attempt = 0;
+		for (;;) {
+			try {
+				await fsAdapter.rename(tempPath, filePath);
+				return;
+			} catch (error) {
+				const retryable = retryRename && isErrnoException(error) && !!error.code && retryRenameErrors.includes(error.code);
+				if (!retryable || attempt >= retryDelaysMs.length) throw error;
+				await sleep(retryDelaysMs[attempt] ?? 0);
+				attempt++;
+			}
+		}
+	}
+
+	return {
+		async write(filePath, value) {
+			let serialized: string | undefined;
+			try {
+				serialized = JSON.stringify(value);
+			} catch (error) {
+				throw new Error(`atomic-json: value for ${filePath} is not JSON-serializable`, { cause: error });
+			}
+			if (serialized === undefined) throw new Error(`atomic-json: value for ${filePath} is not JSON-serializable`);
+			const { dir, base } = dirAndBase(filePath);
+			const tempPath = `${dir}/.${base}.${pid()}.${now()}.${random()}.tmp`;
+			await fsAdapter.writeFile(tempPath, serialized);
+			try {
+				await renameWithRetry(tempPath, filePath);
+			} catch (error) {
+				try {
+					await fsAdapter.unlink(tempPath);
+				} catch {
+					// Best-effort cleanup -- the rename failure itself is the real error to surface.
+				}
+				throw error;
+			}
+		},
+		async read(filePath) {
+			try {
+				const raw = await fsAdapter.readFile(filePath);
+				return JSON.parse(raw) as unknown;
+			} catch (error) {
+				if (isErrnoException(error) && error.code === "ENOENT") return undefined;
+				throw error;
+			}
+		},
+	};
+}

package/src/index.ts

@@ -1,2 +1,3 @@
+export * from "./atomic-json.js";
 export * from "./vehicle-contract.js";
 export * from "./vehicle-errors.js";

package/src/vehicle-contract.ts

@@ -36,7 +36,10 @@ export interface LooseObjectProperty {
  * 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>> {
+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
@@ -68,6 +71,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 =
@@ -189,12 +239,7 @@ export interface VehicleManifest extends VehicleManifestIdentity {
 
 export interface VehicleClient {
 	manifest(): Promise<VehicleManifest>;
-	invoke<Output = unknown>(
-		name: string,
-		version: number,
-		input: unknown,
-		options?: VehicleInvocationOptions,
-	): Promise<Output>;
+	invoke<Output = unknown>(name: string, version: number, input: unknown, options?: VehicleInvocationOptions): Promise<Output>;
 	close(): Promise<void>;
 }
 
@@ -242,7 +287,10 @@ function validateOperationMetadata<Input, Output>(options: DefineVehicleOperatio
 	if (limits.defaultTimeoutMs > limits.maxTimeoutMs) {
 		throw new Error("Vehicle operation defaultTimeoutMs must not exceed maxTimeoutMs");
 	}
-	if (options.idempotency.mode === "keyed" && (!Number.isSafeInteger(options.idempotency.retentionMs) || options.idempotency.retentionMs < 1)) {
+	if (
+		options.idempotency.mode === "keyed" &&
+		(!Number.isSafeInteger(options.idempotency.retentionMs) || options.idempotency.retentionMs < 1)
+	) {
 		throw new Error("Vehicle keyed idempotency retentionMs must be a positive integer");
 	}
 }