@danypops/vehicle-core 0.14.0 → 0.16.0

package/dist/vehicle-contract.d.ts

@@ -1,4 +1,4 @@
-import type { VehicleJobWakeBudget } from "./vehicle-jobs.js";
+import type { VehicleJobSnapshot, VehicleJobSubmitOptions, VehicleJobSubmitResult, VehicleJobTailResult, VehicleJobWakeBudget } from "./vehicle-jobs.js";
 export type JsonPrimitive = string | number | boolean | null;
 export type JsonValue = JsonPrimitive | readonly JsonValue[] | {
     readonly [key: string]: JsonValue;
@@ -178,9 +178,24 @@ 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[];
@@ -194,6 +209,10 @@ 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[];
@@ -305,6 +324,24 @@ export interface VehicleClient {
     manifest(): Promise<VehicleManifest>;
     invoke<Output = unknown>(name: string, version: number, input: unknown, options?: VehicleInvocationOptions): Promise<Output>;
     close(): Promise<void>;
+    /**
+     * Vehicle Jobs -- submit a background-capable operation (one whose descriptor declares
+     * `background`, see {@link VehicleBackgroundCapability}) and get its jobId back immediately,
+     * without waiting for the operation itself to make any progress. Optional: a client that
+     * never talks to a job-capable Vehicle (or a hand-rolled test double) simply omits these five
+     * methods, exactly like this interface's own long-standing `subscribe()`-shaped extras --
+     * present on both LocalVehicleClient and RemoteVehicleClient, absent elsewhere. Feature-detect
+     * via the operation's own manifest `background` capability, not by probing for these methods.
+     */
+    submitJob?(name: string, version: number, input: unknown, options?: VehicleJobSubmitOptions): Promise<VehicleJobSubmitResult>;
+    /** Never blocks -- current status, plus output/error once terminal. */
+    pollJob?(jobId: string): Promise<VehicleJobSnapshot>;
+    /** Progress entries strictly after `cursor` (0 for everything so far), plus the next cursor. Never blocks. */
+    tailJob?(jobId: string, cursor?: number): Promise<VehicleJobTailResult>;
+    /** Pushes new input to an already-running job's handler, if it opted in via context.steerInputs. */
+    steerJob?(jobId: string, input: unknown): Promise<void>;
+    /** Best-effort cancellation of a still-running job -- a no-op against an already-terminal one. */
+    cancelJob?(jobId: string): Promise<void>;
 }
 export declare function defineVehicleOperation<Input, Output>(options: DefineVehicleOperationOptions<Input, Output>): VehicleOperation<Input, Output>;
 export declare function bindVehicleOperation<Input, Output>(operation: VehicleOperation<Input, Output>, bind: () => VehicleOperationHandler<Input, Output>): VehicleOperationBinding<Input, Output>;

package/dist/vehicle-jobs.d.ts

@@ -1,4 +1,6 @@
 /** Pure pieces of Vehicle Jobs: a termination-reason resolver and a bounded wake-log accumulator. Orchestration lives in vehicle-server's VehicleJobStore. */
+import type { VehiclePrincipal } from "./vehicle-contract.js";
+import type { VehicleFailure } from "./vehicle-errors.js";
 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 declare const VEHICLE_JOB_TERMINATION_PRECEDENCE: readonly ["canceled", "timeout", "orphaned", "failed", "succeeded"];
@@ -101,6 +103,49 @@ export interface VehicleJobRetentionOptions {
     readonly deliveredRetentionMs: number;
     readonly now: number;
 }
+/**
+ * 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;
+}
 /**
  * Pure eviction-selection policy, kept separate from VehicleJobStore's own
  * bookkeeping so the bounded-retention rule is independently testable.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@danypops/vehicle-core",
-	"version": "0.14.0",
+	"version": "0.16.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

@@ -1,4 +1,10 @@
-import type { VehicleJobWakeBudget } from "./vehicle-jobs.js";
+import type {
+	VehicleJobSnapshot,
+	VehicleJobSubmitOptions,
+	VehicleJobSubmitResult,
+	VehicleJobTailResult,
+	VehicleJobWakeBudget,
+} from "./vehicle-jobs.js";
 
 export type JsonPrimitive = string | number | boolean | null;
 export type JsonValue = JsonPrimitive | readonly JsonValue[] | { readonly [key: string]: JsonValue };
@@ -254,9 +260,24 @@ export interface VehiclePrincipal {
 	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[];
@@ -271,6 +292,10 @@ 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[];
@@ -419,6 +444,24 @@ export interface VehicleClient {
 	manifest(): Promise<VehicleManifest>;
 	invoke<Output = unknown>(name: string, version: number, input: unknown, options?: VehicleInvocationOptions): Promise<Output>;
 	close(): Promise<void>;
+	/**
+	 * Vehicle Jobs -- submit a background-capable operation (one whose descriptor declares
+	 * `background`, see {@link VehicleBackgroundCapability}) and get its jobId back immediately,
+	 * without waiting for the operation itself to make any progress. Optional: a client that
+	 * never talks to a job-capable Vehicle (or a hand-rolled test double) simply omits these five
+	 * methods, exactly like this interface's own long-standing `subscribe()`-shaped extras --
+	 * present on both LocalVehicleClient and RemoteVehicleClient, absent elsewhere. Feature-detect
+	 * via the operation's own manifest `background` capability, not by probing for these methods.
+	 */
+	submitJob?(name: string, version: number, input: unknown, options?: VehicleJobSubmitOptions): Promise<VehicleJobSubmitResult>;
+	/** Never blocks -- current status, plus output/error once terminal. */
+	pollJob?(jobId: string): Promise<VehicleJobSnapshot>;
+	/** Progress entries strictly after `cursor` (0 for everything so far), plus the next cursor. Never blocks. */
+	tailJob?(jobId: string, cursor?: number): Promise<VehicleJobTailResult>;
+	/** Pushes new input to an already-running job's handler, if it opted in via context.steerInputs. */
+	steerJob?(jobId: string, input: unknown): Promise<void>;
+	/** Best-effort cancellation of a still-running job -- a no-op against an already-terminal one. */
+	cancelJob?(jobId: string): Promise<void>;
 }
 
 export function defineVehicleOperation<Input, Output>(

package/src/vehicle-jobs.ts

@@ -1,5 +1,8 @@
 /** Pure pieces of Vehicle Jobs: a termination-reason resolver and a bounded wake-log accumulator. Orchestration lives in vehicle-server's VehicleJobStore. */
 
+import type { VehiclePrincipal } from "./vehicle-contract.js";
+import type { VehicleFailure } from "./vehicle-errors.js";
+
 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. */
@@ -212,6 +215,53 @@ export interface VehicleJobRetentionOptions {
 	readonly now: number;
 }
 
+/**
+ * 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;
+}
+
 /**
  * Pure eviction-selection policy, kept separate from VehicleJobStore's own
  * bookkeeping so the bounded-retention rule is independently testable.