@botbotgo/agent-harness 0.0.83 → 0.0.84

package/dist/contracts/types.d.ts

@@ -345,6 +345,7 @@ export type RunStartOptions = {
     agentId?: string;
     input: MessageContent;
     threadId?: string;
+    priority?: number;
     invocation?: InvocationEnvelope;
     listeners?: RunListeners;
 };

package/dist/package-version.d.ts

@@ -1 +1 @@
-export declare const AGENT_HARNESS_VERSION = "0.0.82";
+export declare const AGENT_HARNESS_VERSION = "0.0.83";

package/dist/package-version.js

@@ -1 +1 @@
-export const AGENT_HARNESS_VERSION = "0.0.82";
+export const AGENT_HARNESS_VERSION = "0.0.83";

package/dist/persistence/types.d.ts

@@ -27,6 +27,7 @@ export type PersistenceLifecycle = {
 };
 export type PersistedRunRequest = {
     input: MessageContent;
+    priority?: number;
     invocation?: InvocationEnvelope;
     savedAt: string;
 };

package/dist/runtime/harness.d.ts

@@ -29,6 +29,7 @@ export declare class AgentHarnessRuntime {
     private readonly concurrencyConfig;
     private readonly workerId;
     private activeRunSlots;
+    private pendingRunInsertionOrder;
     private readonly pendingRunSlots;
     private runtimeEventSequence;
     private toPublicApprovalRecord;
@@ -90,6 +91,9 @@ export declare class AgentHarnessRuntime {
     private finalizeCancelledRun;
     private invokeWithHistory;
     private buildPersistedRunRequest;
+    private normalizeRunPriority;
+    private resolvePersistedRunPriority;
+    private enqueuePendingRunSlot;
     private executeQueuedRun;
     private checkpointRefForState;
     private finalizeContinuedRun;

package/dist/runtime/harness.js

@@ -46,6 +46,7 @@ export class AgentHarnessRuntime {
     concurrencyConfig;
     workerId = `worker-${createPersistentId()}`;
     activeRunSlots = 0;
+    pendingRunInsertionOrder = 0;
     pendingRunSlots = [];
     runtimeEventSequence = 0;
     toPublicApprovalRecord(approval) {
@@ -512,7 +513,7 @@ export class AgentHarnessRuntime {
             throw error;
         }
     }
-    buildPersistedRunRequest(input, invocation) {
+    buildPersistedRunRequest(input, invocation, priority) {
         const envelope = invocation.invocation ?? {
             ...(invocation.context ? { context: invocation.context } : {}),
             ...(invocation.state ? { inputs: invocation.state } : {}),
@@ -520,6 +521,7 @@ export class AgentHarnessRuntime {
         };
         return {
             input: normalizeMessageContent(input),
+            priority: Number.isFinite(priority) ? Math.trunc(priority) : undefined,
             invocation: envelope && Object.keys(envelope).length > 0
                 ? {
                     ...(envelope.context ? { context: envelope.context } : {}),
@@ -531,6 +533,48 @@ export class AgentHarnessRuntime {
             savedAt: new Date().toISOString(),
         };
     }
+    normalizeRunPriority(priority) {
+        if (!Number.isFinite(priority)) {
+            return 0;
+        }
+        return Math.trunc(priority);
+    }
+    async resolvePersistedRunPriority(threadId, runId) {
+        const persisted = await this.persistence.getRunRequest(threadId, runId);
+        return this.normalizeRunPriority(persisted?.priority);
+    }
+    enqueuePendingRunSlot(entry) {
+        const previousPositions = new Map(this.pendingRunSlots
+            .filter((candidate) => Boolean(candidate.threadId && candidate.runId))
+            .map((candidate, index) => [candidate.runId, index + 1]));
+        const queuedEntry = {
+            ...entry,
+            insertionOrder: this.pendingRunInsertionOrder++,
+        };
+        this.pendingRunSlots.push(queuedEntry);
+        this.pendingRunSlots.sort((left, right) => {
+            if (right.priority !== left.priority) {
+                return right.priority - left.priority;
+            }
+            return left.insertionOrder - right.insertionOrder;
+        });
+        return this.pendingRunSlots.flatMap((candidate, index) => {
+            if (!candidate.threadId || !candidate.runId) {
+                return [];
+            }
+            const previousPosition = previousPositions.get(candidate.runId);
+            const queuePosition = index + 1;
+            if (previousPosition === undefined || previousPosition === queuePosition) {
+                return [];
+            }
+            return [{
+                    threadId: candidate.threadId,
+                    runId: candidate.runId,
+                    priority: candidate.priority,
+                    queuePosition,
+                }];
+        });
+    }
     async executeQueuedRun(binding, input, threadId, runId, agentId, options = {}) {
         const previousState = options.previousState ?? "running";
         const currentRun = await this.persistence.getRun(runId);
@@ -712,9 +756,9 @@ export class AgentHarnessRuntime {
         }
         await listener(value);
     }
-    async acquireRunSlot(threadId, runId, activeState = "running") {
+    async acquireRunSlot(threadId, runId, activeState = "running", priority = 0) {
         if (threadId && runId) {
-            await this.persistence.enqueueRun({ threadId, runId });
+            await this.persistence.enqueueRun({ threadId, runId, priority });
         }
         let stopHeartbeat = () => undefined;
         const beginLease = async () => {
@@ -773,8 +817,50 @@ export class AgentHarnessRuntime {
                 void next?.activate();
             };
         }
+        const activateQueuedRun = async () => {
+            const currentRun = runId ? await this.persistence.getRun(runId) : null;
+            if (currentRun?.state === "cancelled") {
+                return "abort";
+            }
+            this.activeRunSlots += 1;
+            if (threadId && runId) {
+                await this.emit(threadId, runId, 4, "run.dequeued", {
+                    queuePosition: 0,
+                    activeRunCount: this.activeRunSlots,
+                    maxConcurrentRuns,
+                    priority,
+                });
+                await this.setRunStateAndEmit(threadId, runId, 5, activeState, {
+                    previousState: "queued",
+                });
+                await beginLease();
+            }
+            return "activate";
+        };
         if (threadId && runId) {
-            const queuePosition = this.pendingRunSlots.length + 1;
+            const slotAcquisition = new Promise((resolve, reject) => {
+                const displacedEntries = this.enqueuePendingRunSlot({
+                    threadId,
+                    runId,
+                    priority,
+                    activate: async () => {
+                        try {
+                            resolve(await activateQueuedRun());
+                        }
+                        catch (error) {
+                            reject(error);
+                        }
+                    },
+                    abort: () => resolve("abort"),
+                });
+                void Promise.all(displacedEntries.map((candidate) => this.emit(candidate.threadId, candidate.runId, 3, "run.queued", {
+                    queuePosition: candidate.queuePosition,
+                    activeRunCount: this.activeRunSlots,
+                    maxConcurrentRuns,
+                    priority: candidate.priority,
+                })));
+            });
+            const queuePosition = this.pendingRunSlots.findIndex((entry) => entry.runId === runId) + 1;
             await this.setRunStateAndEmit(threadId, runId, 2, "queued", {
                 previousState: activeState,
             });
@@ -782,37 +868,23 @@ export class AgentHarnessRuntime {
                 queuePosition,
                 activeRunCount: this.activeRunSlots,
                 maxConcurrentRuns,
+                priority,
             });
-        }
-        const slotAcquisition = await new Promise((resolve, reject) => {
-            this.pendingRunSlots.push({ runId, activate: async () => {
-                    try {
-                        const currentRun = runId ? await this.persistence.getRun(runId) : null;
-                        if (currentRun?.state === "cancelled") {
-                            resolve("abort");
-                            return;
-                        }
-                        this.activeRunSlots += 1;
-                        if (threadId && runId) {
-                            await this.emit(threadId, runId, 4, "run.dequeued", {
-                                queuePosition: 0,
-                                activeRunCount: this.activeRunSlots,
-                                maxConcurrentRuns,
-                            });
-                            await this.setRunStateAndEmit(threadId, runId, 5, activeState, {
-                                previousState: "queued",
-                            });
-                            await beginLease();
-                        }
-                        resolve("activate");
-                    }
-                    catch (error) {
-                        reject(error);
-                    }
-                }, abort: () => resolve("abort") });
-        });
-        if (slotAcquisition === "abort") {
-            return async () => undefined;
+            const slotAcquisitionResult = await slotAcquisition;
+            if (slotAcquisitionResult === "abort") {
+                return async () => undefined;
+            }
+            let released = false;
+            return async () => {
+                if (released) {
+                    return;
+                }
+                released = true;
+                await releaseLease();
+                this.activeRunSlots = Math.max(0, this.activeRunSlots - 1);
+                const next = this.pendingRunSlots.shift();
+                void next?.activate();
+            };
         }
         let released = false;
         return async () => {
@@ -923,14 +995,15 @@ export class AgentHarnessRuntime {
             throw new Error(`Policy evaluation blocked agent ${selectedAgentId}: ${policyDecision.reasons.join(", ")}`);
         }
         const { threadId, runId } = await this.ensureThreadStarted(selectedAgentId, binding, options.input, options.threadId);
-        await this.persistence.saveRunRequest(threadId, runId, this.buildPersistedRunRequest(options.input, invocation));
+        const priority = this.normalizeRunPriority(options.priority);
+        await this.persistence.saveRunRequest(threadId, runId, this.buildPersistedRunRequest(options.input, invocation, priority));
         await this.emitRunCreated(threadId, runId, {
             agentId: binding.agent.id,
             requestedAgentId: options.agentId ?? AUTO_AGENT_ID,
             selectedAgentId,
             executionMode: getBindingAdapterKind(binding),
         });
-        const releaseRunSlot = await this.acquireRunSlot(threadId, runId);
+        const releaseRunSlot = await this.acquireRunSlot(threadId, runId, "running", priority);
         try {
             return await this.executeQueuedRun(binding, options.input, threadId, runId, selectedAgentId, {
                 context: invocation.context,
@@ -965,7 +1038,8 @@ export class AgentHarnessRuntime {
         let emitted = false;
         let streamActivityObserved = false;
         const { threadId, runId } = await this.ensureThreadStarted(selectedAgentId, binding, options.input, options.threadId);
-        await this.persistence.saveRunRequest(threadId, runId, this.buildPersistedRunRequest(options.input, invocation));
+        const priority = this.normalizeRunPriority(options.priority);
+        await this.persistence.saveRunRequest(threadId, runId, this.buildPersistedRunRequest(options.input, invocation, priority));
         yield { type: "event", event: await this.emitRunCreated(threadId, runId, {
                 agentId: selectedAgentId,
                 requestedAgentId: options.agentId ?? AUTO_AGENT_ID,
@@ -973,7 +1047,7 @@ export class AgentHarnessRuntime {
                 input: options.input,
                 state: "running",
             }) };
-        const releaseRunSlot = await this.acquireRunSlot(threadId, runId);
+        const releaseRunSlot = await this.acquireRunSlot(threadId, runId, "running", priority);
         try {
             try {
                 const priorHistory = await this.loadPriorHistory(threadId, runId);
@@ -1229,7 +1303,7 @@ export class AgentHarnessRuntime {
             return this.finalizeCancelledRun(threadId, runId, thread.status, cancellation.reason);
         }
         await this.persistence.setRunState(threadId, runId, "resuming", `checkpoints/${threadId}/${runId}/cp-1`);
-        const releaseRunSlot = await this.acquireRunSlot(threadId, runId, "resuming");
+        const releaseRunSlot = await this.acquireRunSlot(threadId, runId, "resuming", await this.resolvePersistedRunPriority(threadId, runId));
         try {
             await this.persistence.saveRecoveryIntent(threadId, runId, {
                 kind: "approval-decision",
@@ -1410,7 +1484,7 @@ export class AgentHarnessRuntime {
                     });
                     continue;
                 }
-                const releaseRunSlot = await this.acquireRunSlot(thread.threadId, thread.latestRunId);
+                const releaseRunSlot = await this.acquireRunSlot(thread.threadId, thread.latestRunId, "running", this.normalizeRunPriority(request.priority));
                 try {
                     await this.executeQueuedRun(binding, request.input, thread.threadId, thread.latestRunId, runMeta.agentId, {
                         context: request.invocation?.context,
@@ -1453,7 +1527,7 @@ export class AgentHarnessRuntime {
                     await this.persistence.releaseRunClaim(thread.latestRunId);
                     continue;
                 }
-                const releaseRunSlot = await this.acquireRunSlot(thread.threadId, thread.latestRunId, "running");
+                const releaseRunSlot = await this.acquireRunSlot(thread.threadId, thread.latestRunId, "running", this.normalizeRunPriority(request.priority));
                 try {
                     await this.emit(thread.threadId, thread.latestRunId, 100, "run.resumed", {
                         resumeKind: "startup-running-recovery",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@botbotgo/agent-harness",
-  "version": "0.0.83",
+  "version": "0.0.84",
   "description": "Workspace runtime for multi-agent applications",
   "type": "module",
   "packageManager": "npm@10.9.2",