@danypops/vehicle-core 0.14.0 → 0.15.0

package/dist/vehicle-contract.d.ts

@@ -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[];

package/package.json

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

@@ -254,9 +254,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 +286,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[];