@danypops/vehicle-core 0.18.3 → 0.18.5

package/src/resource-pool/errors.ts

@@ -0,0 +1,45 @@
+/** Raised when no idle resource can be evicted to admit a new one within the current ceiling. */
+export class ResourceCapacityExceeded extends Error {
+	constructor(
+		readonly partitionKey: string,
+		readonly maxActive: number,
+		readonly partitionLimit: number,
+	) {
+		super(
+			`no idle resource can be evicted to admit partition "${partitionKey}" within global capacity ${maxActive} and partition capacity ${partitionLimit}`,
+		);
+		this.name = "ResourceCapacityExceeded";
+	}
+}
+
+/** Raised by releaseOwnerIfIdle when at least one of the owner's own resources still has an active lease. */
+export class ResourceInUse extends Error {
+	constructor(readonly ownerKey: string) {
+		super(`cannot release owner "${ownerKey}": a pooled resource for it still has an active lease`);
+		this.name = "ResourceInUse";
+	}
+}
+
+/** Raised when background admission is already waiting at maxQueuedBackgroundAdmissions -- fails fast rather than growing the wait queue without bound. */
+export class ResourceAdmissionQueueFull extends Error {
+	constructor(
+		readonly partitionKey: string,
+		readonly maxQueued: number,
+	) {
+		super(`background admission for partition "${partitionKey}" is already waiting at capacity (${maxQueued} queued); retry later`);
+		this.name = "ResourceAdmissionQueueFull";
+	}
+}
+
+/** Raised when a queued background admission waits past backgroundAdmissionQueueTimeoutMs without a slot freeing. */
+export class ResourceAdmissionQueueTimedOut extends Error {
+	constructor(
+		readonly partitionKey: string,
+		readonly timeoutMs: number,
+	) {
+		super(
+			`background admission for partition "${partitionKey}" waited ${timeoutMs}ms for a resource-pool slot and gave up -- foreground demand is holding every admittable slot`,
+		);
+		this.name = "ResourceAdmissionQueueTimedOut";
+	}
+}

package/src/resource-pool/index.ts

@@ -0,0 +1,3 @@
+export * from "./bounded-resource-pool.js";
+export * from "./errors.js";
+export * from "./resource-policy.js";

package/src/resource-pool/resource-policy.ts

@@ -0,0 +1,29 @@
+/** Which ceiling actually constrained the most recent admission decision. */
+export type ResourcePoolActiveCeilingSource = "configured" | "resource-budget" | "absolute-cap";
+
+/**
+ * Optional plug point letting a real resource budget (memory, /proc-sampled process cost, ...)
+ * drive admission and retention decisions beyond the pool's own configured counts. A pool without
+ * one falls back to its configured maxActive/absoluteMaxActive alone -- this interface exists so a
+ * caller CAN plug in something smarter, not because every caller needs to.
+ *
+ * `Status` is left to the caller (default `unknown`) rather than fixed to one shape: the pool
+ * itself never inspects or reshapes what `status()` returns, only forwards it verbatim in its own
+ * status() report -- a caller with an existing status shape (its own field names, units, wire
+ * contract) plugs it in unchanged, no adapter required.
+ */
+export interface ResourcePoolResourcePolicy<Status = unknown> {
+	canAdmit(activePartitions: readonly string[], requestedPartition: string): boolean;
+	isOverBudget(activePartitions: readonly string[]): boolean;
+	/**
+	 * A conservative, count-shaped ceiling derived from a real budget and worst-case known
+	 * per-partition cost -- lets a larger real budget actually raise how many resources the pool
+	 * will try to keep active, instead of a fixed configured count being the permanent bottleneck
+	 * regardless of how much is genuinely available. Never authoritative on its own: canAdmit's own
+	 * precise per-attempt check still gates the actual admission. Returns undefined on any metric
+	 * loss -- fails closed, never treated as "unlimited room."
+	 */
+	softActiveCeiling(activePartitions: readonly string[]): number | undefined;
+	maxIdleMs(configuredMaxIdleMs: number, activePartitions: readonly string[]): number;
+	status(activePartitions: readonly string[]): Status;
+}

package/src/schemas/presentation.ts

@@ -21,8 +21,10 @@ export function isVehicleCredentialFieldName(name: string): boolean {
 
 /**
  * JSON Schema property annotation consumed by human-facing Vehicle adapters.
- * `omit` hides the field; `summarize` may show shape/size but never its value.
+ * `omit` hides the field; `summarize` may show shape/size but never its value;
+ * `stream` exposes a string through a bounded, tail-following call preview while
+ * the host receives partial tool arguments, then collapses it to a size summary.
  * Standard `writeOnly: true` and `format: "password"` always imply omission.
  */
 export const VEHICLE_SCHEMA_PRESENTATION_EXTENSION = "x-vehicle-presentation" as const;
-export type VehicleSchemaPresentation = "omit" | "summarize";
+export type VehicleSchemaPresentation = "omit" | "summarize" | "stream";