@danypops/vehicle-core 0.17.0 → 0.18.0

package/src/jobs/grant.ts

@@ -0,0 +1,53 @@
+/**
+ * The Grant primitive's own wire-neutral shape: a resource budget bounding how much an
+ * already-authorized, already-running long-running operation may still do before it must ask
+ * for more. Mirrors VehicleJobWakeBudget's own convention (a plain, optional-per-dimension
+ * object, not a class) -- see wake-log.ts's own doc comment for that precedent. Every dimension
+ * is independently optional: a caller states only the ceilings that matter for its own operation
+ * (an operation with no real notion of "tokens" simply never sets maxTokens).
+ *
+ * Deliberately agent-flavored (turns/tool-calls/tokens) rather than a generic {maxCount, maxBytes}
+ * pair the way VehicleJobWakeBudget is -- Vehicle was built specifically for agent consumers
+ * (vehicle-client-pi exists precisely to project operations as Pi tools), so this vocabulary
+ * belongs here rather than being reinvented per-consumer.
+ */
+export interface VehicleGrantBudget {
+	readonly maxTurns?: number;
+	readonly maxToolCalls?: number;
+	readonly maxTokens?: number;
+	readonly maxWallClockMs?: number;
+}
+
+/**
+ * True the moment any one *set* dimension reaches zero or below -- the tightest dimension
+ * governs, not an average or a sum. A dimension the caller never set imposes no ceiling of its
+ * own. An entirely empty budget ({}) is never exhausted: that's an unbounded grant (every
+ * dimension omitted), not a zero one -- a caller that wants "no more of anything" states at
+ * least one dimension as 0, it doesn't rely on {} meaning that.
+ */
+export function grantBudgetExhausted(remaining: VehicleGrantBudget): boolean {
+	return (
+		(remaining.maxTurns !== undefined && remaining.maxTurns <= 0) ||
+		(remaining.maxToolCalls !== undefined && remaining.maxToolCalls <= 0) ||
+		(remaining.maxTokens !== undefined && remaining.maxTokens <= 0) ||
+		(remaining.maxWallClockMs !== undefined && remaining.maxWallClockMs <= 0)
+	);
+}
+
+/**
+ * Adds a top-up onto the current remaining budget, dimension by dimension. A dimension absent
+ * from the top-up is left exactly as it was; a dimension the current budget never had but the
+ * top-up introduces is taken as-is (not added to an implicit 0, since the current budget's own
+ * "never set" already means unbounded for that dimension -- introducing a ceiling for the first
+ * time via a top-up is a real, deliberate narrowing a caller must do explicitly, not an artifact
+ * of the merge itself).
+ */
+export function mergeGrantBudget(current: VehicleGrantBudget, additional: VehicleGrantBudget): VehicleGrantBudget {
+	const merged: { -readonly [K in keyof VehicleGrantBudget]?: number } = { ...current };
+	for (const key of ["maxTurns", "maxToolCalls", "maxTokens", "maxWallClockMs"] as const) {
+		const addition = additional[key];
+		if (addition === undefined) continue;
+		merged[key] = (current[key] ?? 0) + addition;
+	}
+	return merged;
+}

package/src/jobs/identity.ts

@@ -0,0 +1,13 @@
+/**
+ * Vehicle Jobs run as in-process promises, not child processes -- there is
+ * no PID to reuse, but a persisted job record written by one process
+ * instance must still never be mistaken for one this (possibly restarted)
+ * instance can still resolve. Each VehicleJobStore construction gets a
+ * fresh random instanceToken; a persisted record's own stamped token only
+ * ever matches the instance that wrote it. A mismatch means "the original
+ * run is gone" -- this instance should treat the record as orphaned rather
+ * than resolve it.
+ */
+export function vehicleJobIdentityMatches(recordInstanceToken: string, currentInstanceToken: string): boolean {
+	return recordInstanceToken === currentInstanceToken;
+}

package/src/jobs/index.ts

@@ -0,0 +1,8 @@
+export * from "./grant.js";
+export * from "./identity.js";
+export * from "./replay.js";
+export * from "./retention.js";
+export * from "./steer.js";
+export * from "./termination.js";
+export * from "./wake-log.js";
+export * from "./wire.js";

package/src/jobs/replay.ts

@@ -0,0 +1,17 @@
+import type { VehicleJobWakeEntry } from "./wake-log.js";
+
+/** Read-only replay side of a wake log -- both a live VehicleJobWakeLog and a restored (no-longer-appendable) job satisfy this with the same tail() semantics. */
+export interface VehicleJobWakeLogReader {
+	since(cursor: number): readonly VehicleJobWakeEntry[];
+	readonly cursor: number;
+}
+
+/** Wraps a fixed, already-finalized list of entries (e.g. restored from disk) in the same reader shape a live VehicleJobWakeLog exposes, so VehicleJobStore.tail() doesn't need to special-case a restored job. */
+export function createStaticVehicleJobWakeLog(entries: readonly VehicleJobWakeEntry[]): VehicleJobWakeLogReader {
+	const sorted = [...entries].sort((a, b) => a.seq - b.seq);
+	const cursor = sorted.length > 0 ? sorted[sorted.length - 1]!.seq : 0;
+	return {
+		since: (cursorArg) => sorted.filter((entry) => entry.seq > cursorArg),
+		cursor,
+	};
+}

package/src/jobs/retention.ts

@@ -0,0 +1,59 @@
+import type { VehicleJobStatus } from "./termination.js";
+
+/** Minimal shape selectVehicleJobsForEviction needs from a job record -- kept separate from VehicleJobSnapshot so vehicle-server doesn't have to construct a full snapshot just to ask "should this be swept". */
+export interface VehicleJobEvictionCandidate {
+	readonly jobId: string;
+	readonly status: VehicleJobStatus;
+	readonly delivered: boolean;
+	readonly updatedAt: number;
+}
+
+export interface VehicleJobRetentionOptions {
+	/** Hard cap on total retained job records (of any status). A running job is never evicted regardless of this cap. */
+	readonly maxRetainedJobs: number;
+	/** A delivered terminal job becomes eligible for eviction once this many ms have passed since it was delivered (== updatedAt at delivery time). */
+	readonly deliveredRetentionMs: number;
+	readonly now: number;
+}
+
+/**
+ * Pure eviction-selection policy, kept separate from VehicleJobStore's own
+ * bookkeeping so the bounded-retention rule is independently testable.
+ * Preference order: (1) delivered and past deliveredRetentionMs, oldest
+ * first; (2) once still over maxRetainedJobs, any delivered terminal job,
+ * oldest first; (3) only as a last resort, an undelivered terminal job,
+ * oldest first -- a real loss (a caller may still want that result), but
+ * an unbounded store is a worse failure mode. A running job is never a
+ * candidate.
+ */
+export function selectVehicleJobsForEviction(
+	candidates: readonly VehicleJobEvictionCandidate[],
+	options: VehicleJobRetentionOptions,
+): readonly string[] {
+	const terminal = candidates.filter((candidate) => candidate.status !== "running");
+	const byAgeAscending = (a: VehicleJobEvictionCandidate, b: VehicleJobEvictionCandidate) => a.updatedAt - b.updatedAt;
+
+	const evicted = new Set<string>();
+	for (const candidate of terminal) {
+		if (candidate.delivered && options.now - candidate.updatedAt >= options.deliveredRetentionMs) evicted.add(candidate.jobId);
+	}
+
+	const remainingCount = () => candidates.length - evicted.size;
+	if (remainingCount() > options.maxRetainedJobs) {
+		const deliveredOldestFirst = terminal.filter((candidate) => candidate.delivered && !evicted.has(candidate.jobId)).sort(byAgeAscending);
+		for (const candidate of deliveredOldestFirst) {
+			if (remainingCount() <= options.maxRetainedJobs) break;
+			evicted.add(candidate.jobId);
+		}
+	}
+	if (remainingCount() > options.maxRetainedJobs) {
+		const undeliveredOldestFirst = terminal
+			.filter((candidate) => !candidate.delivered && !evicted.has(candidate.jobId))
+			.sort(byAgeAscending);
+		for (const candidate of undeliveredOldestFirst) {
+			if (remainingCount() <= options.maxRetainedJobs) break;
+			evicted.add(candidate.jobId);
+		}
+	}
+	return [...evicted];
+}

package/src/jobs/steer.ts

@@ -0,0 +1,49 @@
+/**
+ * A job's mid-flight input channel -- the "steer" primitive. Bounded FIFO:
+ * push() while a handler isn't yet reading buffers up to maxQueueSize, then
+ * refuses further input rather than growing unboundedly or silently
+ * overwriting an unread entry. A handler consumes it via `for await (const
+ * input of context.steerInputs)`, which ends cleanly once close() is
+ * called (VehicleJobStore does this at job finalization).
+ */
+export interface VehicleJobSteerPushResult {
+	readonly accepted: boolean;
+	readonly dropReason?: "queue-full" | "channel-closed";
+}
+
+export class VehicleJobSteerChannel implements AsyncIterable<unknown> {
+	private readonly buffer: unknown[] = [];
+	private readonly waiters: ((result: IteratorResult<unknown>) => void)[] = [];
+	private closed = false;
+
+	constructor(private readonly maxQueueSize: number = 64) {}
+
+	push(value: unknown): VehicleJobSteerPushResult {
+		if (this.closed) return { accepted: false, dropReason: "channel-closed" };
+		const waiter = this.waiters.shift();
+		if (waiter) {
+			waiter({ value, done: false });
+			return { accepted: true };
+		}
+		if (this.buffer.length >= this.maxQueueSize) return { accepted: false, dropReason: "queue-full" };
+		this.buffer.push(value);
+		return { accepted: true };
+	}
+
+	/** Ends every pending and future iteration with done:true; further push() calls report "channel-closed". Idempotent. */
+	close(): void {
+		if (this.closed) return;
+		this.closed = true;
+		for (const waiter of this.waiters.splice(0)) waiter({ value: undefined, done: true });
+	}
+
+	[Symbol.asyncIterator](): AsyncIterator<unknown> {
+		return {
+			next: (): Promise<IteratorResult<unknown>> => {
+				if (this.buffer.length > 0) return Promise.resolve({ value: this.buffer.shift(), done: false });
+				if (this.closed) return Promise.resolve({ value: undefined, done: true });
+				return new Promise((resolve) => this.waiters.push(resolve));
+			},
+		};
+	}
+}

package/src/jobs/termination.ts

@@ -0,0 +1,13 @@
+export type VehicleJobStatus = "running" | "succeeded" | "failed" | "canceled";
+
+/** Highest precedence first -- an explicit cancel always wins even if the handler also settled around the same time. "orphaned" is a restart-reconciliation outcome: a job that was still "running" when its process died, so nothing ever really failed or succeeded -- the record's own status just goes stale. */
+export const VEHICLE_JOB_TERMINATION_PRECEDENCE = ["canceled", "timeout", "orphaned", "failed", "succeeded"] as const;
+export type VehicleJobTerminationReason = (typeof VEHICLE_JOB_TERMINATION_PRECEDENCE)[number];
+
+export function resolveVehicleJobTerminationReason(candidates: readonly VehicleJobTerminationReason[]): VehicleJobTerminationReason {
+	if (candidates.length === 0) throw new Error("resolveVehicleJobTerminationReason requires at least one candidate");
+	for (const reason of VEHICLE_JOB_TERMINATION_PRECEDENCE) {
+		if (candidates.includes(reason)) return reason;
+	}
+	throw new Error(`Unrecognized Vehicle job termination candidate(s): ${candidates.join(", ")}`);
+}

package/src/jobs/wake-log.ts

@@ -0,0 +1,98 @@
+/** "always" keeps every notification; "transition" drops one identical to the last (hash dedup); "first-only" keeps just the first. */
+export type VehicleJobNotifyMode = "always" | "transition" | "first-only";
+
+export interface VehicleJobWakeBudget {
+	readonly maxCount: number;
+	readonly maxBytes: number;
+}
+
+export type VehicleJobWakeDropReason =
+	| "count-budget-exhausted"
+	| "byte-budget-exhausted"
+	| "deduplicated-transition"
+	| "superseded-by-first-only";
+
+export interface VehicleJobWakeEntry {
+	readonly seq: number;
+	readonly at: number;
+	readonly progress: unknown;
+}
+
+export interface VehicleJobWakeAppendResult {
+	readonly accepted: boolean;
+	readonly entry?: VehicleJobWakeEntry;
+	readonly dropReason?: VehicleJobWakeDropReason;
+}
+
+export interface VehicleJobWakeLogOptions {
+	readonly notifyMode: VehicleJobNotifyMode;
+	readonly budget: VehicleJobWakeBudget;
+	/** Defaults to Date.now. */
+	readonly now?: () => number;
+}
+
+function safeJsonStringify(value: unknown): string {
+	let serialized: string | undefined;
+	try {
+		serialized = JSON.stringify(value);
+	} catch (error) {
+		throw new Error("Vehicle job progress value is not JSON-serializable", { cause: error });
+	}
+	if (serialized === undefined) throw new Error("Vehicle job progress value is not JSON-serializable");
+	return serialized;
+}
+
+/** Non-cryptographic (FNV-1a) -- dedup only. */
+function fnv1aHash(value: string): string {
+	let hash = 0x811c9dc5;
+	for (let i = 0; i < value.length; i++) {
+		hash ^= value.charCodeAt(i);
+		hash = Math.imul(hash, 0x01000193);
+	}
+	return (hash >>> 0).toString(16);
+}
+
+/** Bounds a job's accumulated progress notifications by count+bytes, same discipline as enforcePayloadSize but across a job's whole lifetime. */
+export class VehicleJobWakeLog {
+	private readonly entries: VehicleJobWakeEntry[] = [];
+	private usedBytes = 0;
+	private nextSeq = 1;
+	private lastHash: string | undefined;
+	private acceptedFirst = false;
+	private readonly now: () => number;
+
+	constructor(private readonly options: VehicleJobWakeLogOptions) {
+		this.now = options.now ?? Date.now;
+	}
+
+	append(progress: unknown): VehicleJobWakeAppendResult {
+		if (this.options.notifyMode === "first-only" && this.acceptedFirst) {
+			return { accepted: false, dropReason: "superseded-by-first-only" };
+		}
+		const serialized = safeJsonStringify(progress);
+		if (this.options.notifyMode === "transition") {
+			const hash = fnv1aHash(serialized);
+			if (hash === this.lastHash) return { accepted: false, dropReason: "deduplicated-transition" };
+			this.lastHash = hash;
+		}
+		const bytes = new TextEncoder().encode(serialized).byteLength;
+		if (this.entries.length >= this.options.budget.maxCount) return { accepted: false, dropReason: "count-budget-exhausted" };
+		if (this.usedBytes + bytes > this.options.budget.maxBytes) return { accepted: false, dropReason: "byte-budget-exhausted" };
+
+		const entry: VehicleJobWakeEntry = { seq: this.nextSeq++, at: this.now(), progress };
+		this.entries.push(entry);
+		this.usedBytes += bytes;
+		this.acceptedFirst = true;
+		return { accepted: true, entry };
+	}
+
+	/** Entries with seq strictly greater than `cursor`. */
+	since(cursor: number): readonly VehicleJobWakeEntry[] {
+		return this.entries.filter((entry) => entry.seq > cursor);
+	}
+
+	/** Highest seq issued so far (0 if none accepted yet). */
+	get cursor(): number {
+		return this.nextSeq - 1;
+	}
+}

package/src/jobs/wire.ts

@@ -0,0 +1,51 @@
+import type { VehicleFailure } from "../errors/error.js";
+import type { VehiclePrincipal } from "../operations/context.js";
+import type { VehicleJobStatus, VehicleJobTerminationReason } from "./termination.js";
+import type { VehicleJobNotifyMode, VehicleJobWakeBudget, VehicleJobWakeEntry } from "./wake-log.js";
+
+/**
+ * The client-facing wire shapes for Vehicle Jobs -- submit/poll/tail options and results, shared by
+ * vehicle-server's VehicleJobStore (the orchestration side) and vehicle-client's job-capable clients
+ * (the calling side), so both halves of the wire agree on one definition instead of two structurally
+ * -identical copies drifting apart. Every field type referenced here already lives in vehicle-core
+ * (VehiclePrincipal, VehicleFailure, VehicleJobStatus, ...), which is what makes it safe for these
+ * shapes to live here too, alongside the rest of Vehicle Jobs' pure pieces.
+ */
+export interface VehicleJobSubmitOptions {
+	readonly permissions?: readonly string[];
+	readonly principal?: VehiclePrincipal;
+	readonly idempotencyKey?: string;
+	readonly expectedRevision?: string | number;
+	readonly approvalCapability?: string;
+	readonly correlationId?: string;
+	readonly callerSessionId?: string;
+	readonly callerProjectRoot?: string;
+	/** Defaults to "transition". */
+	readonly notifyMode?: VehicleJobNotifyMode;
+	/** Defaults to background.defaultWakeBudget; clamped to background.maxWakeBudget either way. */
+	readonly wakeBudget?: VehicleJobWakeBudget;
+	/** No default -- unset means the job runs until it settles or is canceled. */
+	readonly maxLifetimeMs?: number;
+}
+
+export interface VehicleJobSubmitResult {
+	readonly jobId: string;
+}
+
+export interface VehicleJobSnapshot {
+	readonly jobId: string;
+	readonly operationName: string;
+	readonly operationVersion: number;
+	readonly status: VehicleJobStatus;
+	readonly createdAt: number;
+	readonly updatedAt: number;
+	readonly delivered: boolean;
+	readonly terminationReason?: VehicleJobTerminationReason;
+	readonly output?: unknown;
+	readonly error?: VehicleFailure;
+}
+
+export interface VehicleJobTailResult {
+	readonly entries: readonly VehicleJobWakeEntry[];
+	readonly cursor: number;
+}

package/src/manifest/index.ts

@@ -0,0 +1 @@
+export * from "./manifest.js";

package/src/manifest/manifest.ts

@@ -0,0 +1,52 @@
+import type { VehicleManifestEvent } from "../events/event.js";
+import type { VehicleOperationDescriptor } from "../operations/operation.js";
+
+export interface VehicleManifestIdentity {
+	readonly name: string;
+	readonly version: string;
+	readonly description: string;
+	readonly guidance?: readonly string[];
+}
+
+/**
+ * A manifest's own view of an operation: the static descriptor plus
+ * whether it's currently usable on this particular server instance right
+ * now. Availability is a runtime property of a live registry (a
+ * credential got configured or removed), never baked into the static
+ * descriptor defineVehicleOperation() produces -- two manifest() calls
+ * against the same registry can report different availability for the
+ * exact same descriptor.
+ */
+export interface VehicleManifestOperation extends VehicleOperationDescriptor {
+	readonly available: boolean;
+	readonly unavailableReason?: string;
+	/**
+	 * The registry's own, live, fully-resolved answer to "does invoking this operation right
+	 * now require approval" -- accounts for the registry's current approval policy being
+	 * enabled/disabled, this operation's own `requiresApproval` override when set, and the
+	 * effect-derived default otherwise. A real VehicleRegistry.manifest() always sets this
+	 * (false when the registry never called configureApprovals() at all) -- unlike
+	 * `requiresApproval` (the static, author-declared override on the descriptor itself),
+	 * this always reflects the current instant, so a client re-fetching the manifest after a
+	 * live policy change (VehicleRegistry.updateApprovalPolicy) sees the new answer with no
+	 * separate sync mechanism needed.
+	 *
+	 * Optional purely for backward compatibility with every hand-authored VehicleManifest
+	 * test fixture across the ecosystem that predates this field (the same reason
+	 * VehicleManifest.events is optional) -- a consumer reading it should treat undefined the
+	 * same as a caller of classifyVehicleOperationSafety does: fall back to the effect-level
+	 * default, never assume false.
+	 */
+	readonly approvalRequired?: boolean;
+}
+
+/**
+ * `events` is optional purely for backward compatibility with every
+ * hand-authored VehicleManifest test fixture across the ecosystem that
+ * predates this field -- a real VehicleRegistry.manifest() always
+ * populates it (as [] when no events are declared), never omits it.
+ */
+export interface VehicleManifest extends VehicleManifestIdentity {
+	readonly operations: readonly VehicleManifestOperation[];
+	readonly events?: readonly VehicleManifestEvent[];
+}

package/src/operations/context.ts

@@ -0,0 +1,56 @@
+import type { JsonValue } from "../schemas/json.js";
+
+export interface VehiclePrincipal {
+	readonly id: string;
+	readonly claims?: Readonly<Record<string, JsonValue>>;
+}
+
+/**
+ * callerSessionId/callerProjectRoot identify the real host session (e.g. one Pi TUI process) that
+ * originated this call, and its working directory at call time -- a generic ownership/attribution
+ * hook any operation handler can read (e.g. scoping a background subscription to the session or
+ * project that created it), distinct from both:
+ *  - correlationId: a caller-CHOSEN id deliberately meant to span several separate invoke() calls
+ *    (a batch/business-transaction id), not an automatically-derived caller identity.
+ *  - principal: broader identity/claims used for permission and approval decisions, usually a
+ *    fixed per-extension value (e.g. {id: "pi-pipes"}), not a distinguishing per-session id.
+ * A Pi projection layer (see vehicle-client-pi's invokeVehicleOperation) auto-derives both from
+ * context.sessionManager.getSessionId()/context.cwd on every call, the same way it already
+ * auto-derives correlationId -- a handler that never reads them pays nothing extra.
+ */
+export interface VehicleInvocationOptions {
+	readonly operationId?: string;
+	readonly correlationId?: string;
+	readonly callerSessionId?: string;
+	readonly callerProjectRoot?: string;
+	readonly signal?: AbortSignal;
+	readonly deadline?: number;
+	readonly permissions?: readonly string[];
+	readonly principal?: VehiclePrincipal;
+	readonly idempotencyKey?: string;
+	readonly expectedRevision?: string | number;
+	readonly approvalCapability?: string;
+	readonly onProgress?: (progress: unknown) => void;
+}
+
+export interface VehicleOperationContext<Input> {
+	readonly input: Input;
+	readonly operationId: string;
+	readonly correlationId?: string;
+	/** See VehicleInvocationOptions's own doc comment. */
+	readonly callerSessionId?: string;
+	/** See VehicleInvocationOptions's own doc comment. */
+	readonly callerProjectRoot?: string;
+	readonly signal: AbortSignal;
+	readonly deadline: number;
+	readonly permissions: readonly string[];
+	readonly principal?: VehiclePrincipal;
+	readonly idempotencyKey?: string;
+	readonly expectedRevision?: string | number;
+	readonly approvalCapability?: string;
+	/** Set only for a job execution (VehicleJobStore.submit()); undefined for a plain invoke(). A handler that wants mid-flight input opts in with `for await (const input of context.steerInputs ?? [])`. */
+	readonly steerInputs?: AsyncIterable<unknown>;
+	reportProgress(progress: unknown): void;
+}
+
+export type VehicleOperationHandler<Input, Output> = (context: VehicleOperationContext<Input>) => Promise<Output>;

package/src/operations/effect.ts

@@ -0,0 +1,3 @@
+/** Canonical list VehicleEffect is itself derived from, so a runtime discriminator check (e.g. a persisted/wire VehicleApprovalRequest's own `effect` field) has one real source to check against instead of a second, driftable hardcoded list. */
+export const VEHICLE_EFFECTS = ["read", "local-write", "external-write", "destructive", "open-world"] as const;
+export type VehicleEffect = (typeof VEHICLE_EFFECTS)[number];

package/src/operations/index.ts

@@ -0,0 +1,3 @@
+export * from "./context.js";
+export * from "./effect.js";
+export * from "./operation.js";