@danypops/vehicle-core 0.17.1 → 0.18.0

package/dist/jobs/grant.d.ts

@@ -0,0 +1,36 @@
+/**
+ * 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 declare function grantBudgetExhausted(remaining: VehicleGrantBudget): boolean;
+/**
+ * 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 declare function mergeGrantBudget(current: VehicleGrantBudget, additional: VehicleGrantBudget): VehicleGrantBudget;

package/dist/jobs/grant.js

@@ -0,0 +1,31 @@
+/**
+ * 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) {
+    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, additional) {
+    const merged = { ...current };
+    for (const key of ["maxTurns", "maxToolCalls", "maxTokens", "maxWallClockMs"]) {
+        const addition = additional[key];
+        if (addition === undefined)
+            continue;
+        merged[key] = (current[key] ?? 0) + addition;
+    }
+    return merged;
+}

package/dist/jobs/index.d.ts

@@ -1,3 +1,4 @@
+export * from "./grant.js";
 export * from "./identity.js";
 export * from "./replay.js";
 export * from "./retention.js";

package/dist/jobs/index.js

@@ -1,3 +1,4 @@
+export * from "./grant.js";
 export * from "./identity.js";
 export * from "./replay.js";
 export * from "./retention.js";

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@danypops/vehicle-core",
-	"version": "0.17.1",
+	"version": "0.18.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/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/index.ts

@@ -1,3 +1,4 @@
+export * from "./grant.js";
 export * from "./identity.js";
 export * from "./replay.js";
 export * from "./retention.js";