@botbotgo/agent-harness 0.0.83 → 0.0.85

package/dist/benchmark/upstream-runtime-ab-benchmark.d.ts

@@ -0,0 +1,51 @@
+export declare const DEFAULT_UPSTREAM_BENCHMARK_PATHS: readonly ["harness", "raw-langchain-v1", "raw-deepagent"];
+export declare const DEFAULT_UPSTREAM_BENCHMARK_WORKLOAD: "tool";
+export type UpstreamBenchmarkPath = (typeof DEFAULT_UPSTREAM_BENCHMARK_PATHS)[number];
+export type UpstreamBenchmarkWorkload = "tool" | "no-tool";
+export type UpstreamBenchmarkRunSummary = {
+    providerLabel: string;
+    model: string;
+    path: UpstreamBenchmarkPath;
+    runNumber: number;
+    status: "completed" | "failed";
+    totalMs: number;
+    firstTokenMs: number | null;
+    outputLength: number;
+    normalizedOutputLength: number;
+    toolCallCount: number;
+    exactOutputMatch: boolean;
+    errorMessage?: string;
+};
+export type UpstreamBenchmarkAggregateSummary = {
+    providerLabel: string;
+    model: string;
+    path: UpstreamBenchmarkPath;
+    repetitions: number;
+    successCount: number;
+    failureCount: number;
+    avgTotalMs: number | null;
+    trimmedAvgTotalMs: number | null;
+    medianTotalMs: number | null;
+    p95TotalMs: number | null;
+    avgFirstTokenMs: number | null;
+    trimmedAvgFirstTokenMs: number | null;
+    medianFirstTokenMs: number | null;
+    p95FirstTokenMs: number | null;
+    avgOutputLength: number | null;
+    avgNormalizedOutputLength: number | null;
+    avgToolCallCount: number | null;
+    exactOutputMatchCount: number;
+};
+export type UpstreamBenchmarkComparison = {
+    baselinePath: UpstreamBenchmarkPath;
+    candidatePath: UpstreamBenchmarkPath;
+    avgTotalMsDelta: number | null;
+    avgTotalMsOverheadPct: number | null;
+    avgFirstTokenMsDelta: number | null;
+    avgFirstTokenMsOverheadPct: number | null;
+};
+export declare function resolveUpstreamBenchmarkPaths(rawValue?: string): readonly UpstreamBenchmarkPath[];
+export declare function resolveUpstreamBenchmarkWorkload(rawValue?: string): UpstreamBenchmarkWorkload;
+export declare function extractLastMatchingToken(output: string, prefixes: readonly string[]): string;
+export declare function aggregateUpstreamBenchmarkRuns(providerLabel: string, model: string, path: UpstreamBenchmarkPath, runs: UpstreamBenchmarkRunSummary[]): UpstreamBenchmarkAggregateSummary;
+export declare function compareUpstreamBenchmarkPaths(baseline: UpstreamBenchmarkAggregateSummary, candidate: UpstreamBenchmarkAggregateSummary): UpstreamBenchmarkComparison;

package/dist/benchmark/upstream-runtime-ab-benchmark.js

@@ -0,0 +1,123 @@
+export const DEFAULT_UPSTREAM_BENCHMARK_PATHS = Object.freeze([
+    "harness",
+    "raw-langchain-v1",
+    "raw-deepagent",
+]);
+export const DEFAULT_UPSTREAM_BENCHMARK_WORKLOAD = "tool";
+function average(values) {
+    return Number((values.reduce((sum, value) => sum + value, 0) / values.length).toFixed(2));
+}
+function median(values) {
+    const sorted = [...values].sort((left, right) => left - right);
+    const middle = Math.floor(sorted.length / 2);
+    if (sorted.length % 2 === 0) {
+        return Number((((sorted[middle - 1] ?? 0) + (sorted[middle] ?? 0)) / 2).toFixed(2));
+    }
+    return Number((sorted[middle] ?? 0).toFixed(2));
+}
+function percentile(values, quantile) {
+    const sorted = [...values].sort((left, right) => left - right);
+    const index = Math.max(0, Math.min(sorted.length - 1, Math.ceil(sorted.length * quantile) - 1));
+    return Number(sorted[index].toFixed(2));
+}
+function averageOrNull(values) {
+    return values.length > 0 ? average(values) : null;
+}
+function medianOrNull(values) {
+    return values.length > 0 ? median(values) : null;
+}
+function percentileOrNull(values, quantile) {
+    return values.length > 0 ? percentile(values, quantile) : null;
+}
+function trimValues(values, trimFraction) {
+    if (values.length <= 2) {
+        return [...values];
+    }
+    const sorted = [...values].sort((left, right) => left - right);
+    const trimCount = Math.min(Math.floor(sorted.length * trimFraction), Math.floor((sorted.length - 1) / 2));
+    return sorted.slice(trimCount, sorted.length - trimCount);
+}
+function trimmedAverageOrNull(values, trimFraction) {
+    return values.length > 0 ? average(trimValues(values, trimFraction)) : null;
+}
+export function resolveUpstreamBenchmarkPaths(rawValue) {
+    if (!rawValue) {
+        return [...DEFAULT_UPSTREAM_BENCHMARK_PATHS];
+    }
+    const parsed = rawValue
+        .split(",")
+        .map((value) => value.trim().toLowerCase())
+        .filter((value) => value === "harness" || value === "raw-langchain-v1" || value === "raw-deepagent");
+    return parsed.length > 0 ? parsed : [...DEFAULT_UPSTREAM_BENCHMARK_PATHS];
+}
+export function resolveUpstreamBenchmarkWorkload(rawValue) {
+    return rawValue?.trim().toLowerCase() === "no-tool" ? "no-tool" : DEFAULT_UPSTREAM_BENCHMARK_WORKLOAD;
+}
+export function extractLastMatchingToken(output, prefixes) {
+    const normalized = output.replace(/\s+/g, " ").trim();
+    let matched = "";
+    for (const prefix of prefixes) {
+        let searchIndex = normalized.indexOf(prefix);
+        while (searchIndex >= 0) {
+            const suffix = normalized.slice(searchIndex);
+            const token = (suffix.split(/\s/)[0] ?? suffix).trim();
+            if (token.length > 0) {
+                matched = token;
+            }
+            searchIndex = normalized.indexOf(prefix, searchIndex + prefix.length);
+        }
+    }
+    return matched || normalized;
+}
+export function aggregateUpstreamBenchmarkRuns(providerLabel, model, path, runs) {
+    const successfulRuns = runs.filter((run) => run.status === "completed");
+    const totalValues = successfulRuns.map((run) => run.totalMs);
+    const firstTokenValues = successfulRuns
+        .map((run) => run.firstTokenMs)
+        .filter((value) => value !== null);
+    return {
+        providerLabel,
+        model,
+        path,
+        repetitions: runs.length,
+        successCount: successfulRuns.length,
+        failureCount: runs.length - successfulRuns.length,
+        avgTotalMs: averageOrNull(totalValues),
+        trimmedAvgTotalMs: trimmedAverageOrNull(totalValues, 0.1),
+        medianTotalMs: medianOrNull(totalValues),
+        p95TotalMs: percentileOrNull(totalValues, 0.95),
+        avgFirstTokenMs: averageOrNull(firstTokenValues),
+        trimmedAvgFirstTokenMs: trimmedAverageOrNull(firstTokenValues, 0.1),
+        medianFirstTokenMs: medianOrNull(firstTokenValues),
+        p95FirstTokenMs: percentileOrNull(firstTokenValues, 0.95),
+        avgOutputLength: averageOrNull(successfulRuns.map((run) => run.outputLength)),
+        avgNormalizedOutputLength: averageOrNull(successfulRuns.map((run) => run.normalizedOutputLength)),
+        avgToolCallCount: averageOrNull(successfulRuns.map((run) => run.toolCallCount)),
+        exactOutputMatchCount: successfulRuns.filter((run) => run.exactOutputMatch).length,
+    };
+}
+function computeOverhead(candidate, baseline) {
+    if (candidate === null || baseline === null) {
+        return { delta: null, pct: null };
+    }
+    const delta = Number((candidate - baseline).toFixed(2));
+    if (baseline === 0) {
+        return { delta, pct: null };
+    }
+    return {
+        delta,
+        pct: Number((((candidate - baseline) / baseline) * 100).toFixed(2)),
+    };
+}
+export function compareUpstreamBenchmarkPaths(baseline, candidate) {
+    const total = computeOverhead(candidate.avgTotalMs, baseline.avgTotalMs);
+    const firstToken = computeOverhead(candidate.avgFirstTokenMs, baseline.avgFirstTokenMs);
+    return {
+        baselinePath: baseline.path,
+        candidatePath: candidate.path,
+        avgTotalMsDelta: total.delta,
+        avgTotalMsOverheadPct: total.pct,
+        avgFirstTokenMsDelta: firstToken.delta,
+        avgFirstTokenMsOverheadPct: firstToken.pct,
+    };
+}

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.84";

package/dist/package-version.js

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

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/agent-runtime-adapter.d.ts

@@ -35,7 +35,6 @@ export declare class AgentRuntimeAdapter {
     private materializeModelStream;
     private createModelFallbackRunnable;
     private applyStrictToolJsonInstruction;
-    private synthesizeDeepAgentAnswer;
     private resolveModel;
     private buildToolNameMapping;
     private buildAgentMessages;

package/dist/runtime/agent-runtime-adapter.js

@@ -1,6 +1,4 @@
 import path from "node:path";
-import { existsSync, statSync } from "node:fs";
-import { cp, mkdir, rm } from "node:fs/promises";
 import { Command, MemorySaver } from "@langchain/langgraph";
 import { tool as createLangChainTool } from "@langchain/core/tools";
 import { HumanMessage, ToolMessage } from "@langchain/core/messages";
@@ -85,49 +83,12 @@ export function relativizeDeepAgentSkillSourcePaths(workspaceRoot, skillPaths) {
         return relative.split(path.sep).join("/");
     });
 }
-function isDeepAgentSkillDirectory(sourcePath) {
-    return existsSync(sourcePath) && statSync(sourcePath).isDirectory() && existsSync(path.join(sourcePath, "SKILL.md"));
-}
-function toWorkspaceRelativePath(workspaceRoot, targetPath) {
-    if (!workspaceRoot) {
-        return targetPath;
-    }
-    const relative = path.relative(workspaceRoot, targetPath);
-    if (!relative || relative.startsWith("..")) {
-        return targetPath;
-    }
-    return relative.split(path.sep).join("/");
-}
 export async function materializeDeepAgentSkillSourcePaths(options) {
-    const { workspaceRoot, runRoot, ownerId, skillPaths } = options;
+    const { workspaceRoot, skillPaths } = options;
     if (!skillPaths) {
         return skillPaths;
     }
-    const materialized = relativizeDeepAgentSkillSourcePaths(workspaceRoot, skillPaths) ?? skillPaths;
-    if (!workspaceRoot || !runRoot) {
-        return materialized;
-    }
-    const sourceRoot = path.join(runRoot, "deepagent-skill-sources", ownerId);
-    let wroteSyntheticSource = false;
-    const resolvedSources = [];
-    for (const [index, sourcePath] of materialized.entries()) {
-        const absolutePath = path.isAbsolute(sourcePath) ? sourcePath : path.resolve(workspaceRoot, sourcePath);
-        if (!isDeepAgentSkillDirectory(absolutePath)) {
-            resolvedSources.push(sourcePath);
-            continue;
-        }
-        if (!wroteSyntheticSource) {
-            await rm(sourceRoot, { recursive: true, force: true });
-            await mkdir(sourceRoot, { recursive: true });
-            wroteSyntheticSource = true;
-        }
-        const skillDirectoryName = path.basename(absolutePath);
-        const syntheticSourcePath = path.join(sourceRoot, `${String(index + 1).padStart(3, "0")}-${skillDirectoryName}`);
-        await mkdir(syntheticSourcePath, { recursive: true });
-        await cp(absolutePath, path.join(syntheticSourcePath, skillDirectoryName), { recursive: true });
-        resolvedSources.push(toWorkspaceRelativePath(workspaceRoot, syntheticSourcePath));
-    }
-    return resolvedSources;
+    return relativizeDeepAgentSkillSourcePaths(workspaceRoot, skillPaths) ?? skillPaths;
 }
 function buildAuthOmittingFetch(baseFetch = fetch) {
     return async (input, init) => {
@@ -673,31 +634,6 @@ export class AgentRuntimeAdapter {
         }
         return binding;
     }
-    async synthesizeDeepAgentAnswer(binding, input, result) {
-        const params = getBindingDeepAgentParams(binding);
-        if (!params) {
-            return "";
-        }
-        const toolContext = extractToolFallbackContext(result);
-        if (!toolContext) {
-            return "";
-        }
-        const model = (await this.resolveModel(params.model));
-        if (!model?.invoke) {
-            return "";
-        }
-        const synthesized = await this.withTimeout(() => model.invoke([
-            {
-                role: "system",
-                content: "The previous agent run completed tool work but did not produce a final user-facing answer. Write the final answer now using the tool results provided. Do not expose internal state, tools, or reasoning.",
-            },
-            {
-                role: "user",
-                content: `Original user request:\n${extractMessageText(input)}\n\nTool results:\n${toolContext}`,
-            },
-        ]), this.resolveBindingTimeout(binding), "deepagent synthesis invoke", "invoke");
-        return sanitizeVisibleText(extractVisibleOutput(synthesized));
-    }
     async resolveModel(model) {
         const cacheKey = this.getModelCacheKey(model);
         const cached = this.modelCache.get(cacheKey);
@@ -1166,7 +1102,7 @@ export class AgentRuntimeAdapter {
         if (!isDeepAgentBinding(binding)) {
             return [];
         }
-        return this.resolveAutomaticSummarizationMiddleware(binding);
+        return [];
     }
     async resolveMiddleware(binding, interruptOn) {
         const declarativeMiddleware = await resolveDeclaredMiddleware(getBindingMiddlewareConfigs(binding), {
@@ -1469,19 +1405,10 @@ export class AgentRuntimeAdapter {
         const visibleOutput = extractedOutput && !isLikelyToolArgsObject(tryParseJson(extractedOutput)) ? extractedOutput : "";
         const emptyAssistantMessageFailure = extractEmptyAssistantMessageFailure(result);
         const toolFallback = extractToolFallbackContext(result);
-        let synthesizedOutput = "";
-        try {
-            synthesizedOutput = await this.synthesizeDeepAgentAnswer(binding, input, result);
-        }
-        catch (error) {
-            if (!(error instanceof RuntimeOperationTimeoutError) || !toolFallback) {
-                throw error;
-            }
-        }
-        if (!visibleOutput && !synthesizedOutput && !toolFallback && emptyAssistantMessageFailure) {
+        if (!visibleOutput && !toolFallback && emptyAssistantMessageFailure) {
             throw new Error(emptyAssistantMessageFailure);
         }
-        const output = visibleOutput || synthesizedOutput || toolFallback || JSON.stringify(result, null, 2);
+        const output = visibleOutput || toolFallback || JSON.stringify(result, null, 2);
         const finalMessageText = sanitizeVisibleText(output);
         const outputContent = extractOutputContent(result);
         const contentBlocks = extractContentBlocks(result);

package/dist/runtime/harness.d.ts

@@ -5,6 +5,8 @@ import type { RequirementAssessmentOptions } from "./skill-requirements.js";
 export declare class AgentHarnessRuntime {
     private readonly workspace;
     private readonly runtimeAdapterOptions;
+    private static readonly DEFAULT_HOST_AGENT_ID;
+    private static readonly BACKGROUND_EVENT_TYPES;
     private readonly eventBus;
     private readonly persistence;
     private readonly policyEngine;
@@ -27,8 +29,10 @@ export declare class AgentHarnessRuntime {
     private readonly healthMonitor;
     private readonly recoveryConfig;
     private readonly concurrencyConfig;
+    private readonly backgroundTasks;
     private readonly workerId;
     private activeRunSlots;
+    private pendingRunInsertionOrder;
     private readonly pendingRunSlots;
     private runtimeEventSequence;
     private toPublicApprovalRecord;
@@ -37,6 +41,7 @@ export declare class AgentHarnessRuntime {
     private listHostBindings;
     private defaultRunRoot;
     private heuristicRoute;
+    private getDefaultHostAgentId;
     private buildRoutingInput;
     private resolveSelectedAgentId;
     private resolveStore;
@@ -81,6 +86,7 @@ export declare class AgentHarnessRuntime {
         threadId?: string;
     }): Promise<string>;
     private emit;
+    private trackBackgroundTask;
     private ensureThreadStarted;
     private loadPriorHistory;
     private loadRunInput;
@@ -90,11 +96,15 @@ export declare class AgentHarnessRuntime {
     private finalizeCancelledRun;
     private invokeWithHistory;
     private buildPersistedRunRequest;
+    private normalizeRunPriority;
+    private resolvePersistedRunPriority;
+    private enqueuePendingRunSlot;
     private executeQueuedRun;
     private checkpointRefForState;
     private finalizeContinuedRun;
     private emitOutputDeltaAndCreateItem;
     private createContentBlocksItem;
+    private createToolResultKey;
     private emitRunCreated;
     private setRunStateAndEmit;
     private requestApprovalAndEmit;

package/dist/runtime/harness.js

@@ -22,6 +22,14 @@ import { describeWorkspaceInventory, listAgentSkills as listWorkspaceAgentSkills
 export class AgentHarnessRuntime {
     workspace;
     runtimeAdapterOptions;
+    static DEFAULT_HOST_AGENT_ID = "orchestra";
+    static BACKGROUND_EVENT_TYPES = new Set([
+        "run.created",
+        "run.queued",
+        "run.dequeued",
+        "output.delta",
+        "reasoning.delta",
+    ]);
     eventBus = new EventBus();
     persistence;
     policyEngine = new PolicyEngine();
@@ -44,8 +52,10 @@ export class AgentHarnessRuntime {
     healthMonitor;
     recoveryConfig;
     concurrencyConfig;
+    backgroundTasks = new Set();
     workerId = `worker-${createPersistentId()}`;
     activeRunSlots = 0;
+    pendingRunInsertionOrder = 0;
     pendingRunSlots = [];
     runtimeEventSequence = 0;
     toPublicApprovalRecord(approval) {
@@ -75,6 +85,13 @@ export class AgentHarnessRuntime {
         const { primaryBinding, secondaryBinding } = inferRoutingBindings(this.workspace);
         return heuristicRoute(extractMessageText(input), primaryBinding, secondaryBinding);
     }
+    getDefaultHostAgentId() {
+        const orchestraBinding = this.workspace.bindings.get(AgentHarnessRuntime.DEFAULT_HOST_AGENT_ID);
+        if (orchestraBinding && orchestraBinding.harnessRuntime.hostFacing !== false) {
+            return orchestraBinding.agent.id;
+        }
+        return this.heuristicRoute("");
+    }
     async buildRoutingInput(input, threadId) {
         const inputText = extractMessageText(input);
         if (!threadId) {
@@ -106,7 +123,7 @@ export class AgentHarnessRuntime {
                     return thread.agentId;
                 }
             }
-            return this.routeAgent(input, { threadId });
+            return this.getDefaultHostAgentId();
         }
         return requestedAgentId;
     }
@@ -403,18 +420,29 @@ export class AgentHarnessRuntime {
     }
     async emit(threadId, runId, sequence, eventType, payload, source = "runtime") {
         const event = createHarnessEvent(threadId, runId, sequence, eventType, payload, source);
-        await this.persistence.appendEvent(event);
-        this.eventBus.publish(event);
-        if (this.threadMemorySync.shouldHandle(event)) {
-            await this.threadMemorySync.handleEvent(event);
+        if (AgentHarnessRuntime.BACKGROUND_EVENT_TYPES.has(event.eventType)) {
+            this.trackBackgroundTask(this.persistence.appendEvent(event).catch(() => {
+                // Fail open for telemetry-style event persistence.
+            }));
         }
+        else {
+            await this.persistence.appendEvent(event);
+        }
+        this.eventBus.publish(event);
         return event;
     }
+    trackBackgroundTask(task) {
+        this.backgroundTasks.add(task);
+        void task.finally(() => {
+            this.backgroundTasks.delete(task);
+        });
+    }
     async ensureThreadStarted(selectedAgentId, binding, input, existingThreadId) {
         const threadId = existingThreadId ?? createPersistentId();
         const runId = createPersistentId();
         const createdAt = new Date().toISOString();
-        if (!existingThreadId) {
+        const isNewThread = !existingThreadId;
+        if (isNewThread) {
             await this.persistence.createThread({
                 threadId,
                 agentId: selectedAgentId,
@@ -423,21 +451,23 @@ export class AgentHarnessRuntime {
                 createdAt,
             });
         }
-        await this.persistence.appendThreadMessage(threadId, {
-            role: "user",
-            content: normalizeMessageContent(input),
-            runId,
-            createdAt,
-        });
-        await this.persistence.createRun({
-            threadId,
-            runId,
-            agentId: binding.agent.id,
-            executionMode: getBindingAdapterKind(binding),
-            adapterKind: getBindingAdapterKind(binding),
-            createdAt,
-        });
-        return { threadId, runId, createdAt };
+        await Promise.all([
+            this.persistence.appendThreadMessage(threadId, {
+                role: "user",
+                content: normalizeMessageContent(input),
+                runId,
+                createdAt,
+            }),
+            this.persistence.createRun({
+                threadId,
+                runId,
+                agentId: binding.agent.id,
+                executionMode: getBindingAdapterKind(binding),
+                adapterKind: getBindingAdapterKind(binding),
+                createdAt,
+            }),
+        ]);
+        return { threadId, runId, createdAt, isNewThread };
     }
     async loadPriorHistory(threadId, runId) {
         const history = await this.persistence.listThreadMessages(threadId);
@@ -499,11 +529,11 @@ export class AgentHarnessRuntime {
             output: reason ? `cancelled: ${reason}` : "cancelled",
         };
     }
-    async invokeWithHistory(binding, input, threadId, runId, resumePayload, options = {}) {
-        const priorHistory = await this.loadPriorHistory(threadId, runId);
+    async invokeWithHistory(binding, input, threadId, runId, resumePayload, priorHistory, options = {}) {
+        const history = priorHistory ?? await this.loadPriorHistory(threadId, runId);
         const startedAt = Date.now();
         try {
-            const result = await this.runtimeAdapter.invoke(binding, input, threadId, runId, resumePayload, priorHistory, options);
+            const result = await this.runtimeAdapter.invoke(binding, input, threadId, runId, resumePayload, history, options);
             this.healthMonitor.recordLlmSuccess(Date.now() - startedAt);
             return result;
         }
@@ -512,7 +542,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 +550,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 +562,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);
@@ -559,7 +632,7 @@ export class AgentHarnessRuntime {
             });
         }
         try {
-            const actual = await this.invokeWithHistory(binding, input, threadId, runId, undefined, {
+            const actual = await this.invokeWithHistory(binding, input, threadId, runId, undefined, options.priorHistory, {
                 context: options.context,
                 state: options.state,
                 files: options.files,
@@ -639,6 +712,16 @@ export class AgentHarnessRuntime {
             contentBlocks,
         };
     }
+    createToolResultKey(toolName, output, isError) {
+        let serializedOutput = "";
+        try {
+            serializedOutput = JSON.stringify(output);
+        }
+        catch {
+            serializedOutput = String(output);
+        }
+        return JSON.stringify([toolName, serializedOutput, isError === true]);
+    }
     async emitRunCreated(threadId, runId, payload) {
         return this.emit(threadId, runId, 1, "run.created", payload);
     }
@@ -712,23 +795,30 @@ export class AgentHarnessRuntime {
         }
         await listener(value);
     }
-    async acquireRunSlot(threadId, runId, activeState = "running") {
-        if (threadId && runId) {
-            await this.persistence.enqueueRun({ threadId, runId });
-        }
+    async acquireRunSlot(threadId, runId, activeState = "running", priority = 0) {
         let stopHeartbeat = () => undefined;
-        const beginLease = async () => {
+        const beginLease = async (mode) => {
             if (!threadId || !runId) {
                 return;
             }
             const claimedAt = new Date().toISOString();
-            await this.persistence.claimQueuedRun({
-                threadId,
-                runId,
-                workerId: this.workerId,
-                claimedAt,
-                leaseExpiresAt: new Date(Date.now() + this.concurrencyConfig.leaseMs).toISOString(),
-            });
+            if (mode === "queue-claim") {
+                await this.persistence.claimQueuedRun({
+                    threadId,
+                    runId,
+                    workerId: this.workerId,
+                    claimedAt,
+                    leaseExpiresAt: new Date(Date.now() + this.concurrencyConfig.leaseMs).toISOString(),
+                });
+            }
+            else {
+                await this.persistence.renewRunLease({
+                    runId,
+                    workerId: this.workerId,
+                    heartbeatAt: claimedAt,
+                    leaseExpiresAt: new Date(Date.now() + this.concurrencyConfig.leaseMs).toISOString(),
+                });
+            }
             if (this.concurrencyConfig.heartbeatIntervalMs <= 0) {
                 return;
             }
@@ -753,14 +843,19 @@ export class AgentHarnessRuntime {
         };
         const maxConcurrentRuns = this.concurrencyConfig.maxConcurrentRuns;
         if (!maxConcurrentRuns) {
-            await beginLease();
+            await beginLease("direct-heartbeat");
             return async () => {
                 await releaseLease();
             };
         }
-        if (this.activeRunSlots < maxConcurrentRuns) {
+        const canActivateImmediately = this.activeRunSlots < maxConcurrentRuns;
+        const useDirectHeartbeatFastPath = canActivateImmediately && maxConcurrentRuns > 1;
+        if (canActivateImmediately) {
             this.activeRunSlots += 1;
-            await beginLease();
+            if (threadId && runId && !useDirectHeartbeatFastPath) {
+                await this.persistence.enqueueRun({ threadId, runId, priority });
+            }
+            await beginLease(useDirectHeartbeatFastPath ? "direct-heartbeat" : "queue-claim");
             let released = false;
             return async () => {
                 if (released) {
@@ -773,8 +868,51 @@ 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("queue-claim");
+            }
+            return "activate";
+        };
         if (threadId && runId) {
-            const queuePosition = this.pendingRunSlots.length + 1;
+            await this.persistence.enqueueRun({ threadId, runId, priority });
+            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 +920,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 () => {
@@ -922,15 +1046,19 @@ export class AgentHarnessRuntime {
         if (!policyDecision.allowed) {
             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));
-        await this.emitRunCreated(threadId, runId, {
+        const { threadId, runId, isNewThread } = await this.ensureThreadStarted(selectedAgentId, binding, options.input, options.threadId);
+        const priority = this.normalizeRunPriority(options.priority);
+        const runRequestPromise = this.persistence.saveRunRequest(threadId, runId, this.buildPersistedRunRequest(options.input, invocation, priority));
+        const runCreatedEventPromise = 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 releaseRunSlotPromise = this.acquireRunSlot(threadId, runId, "running", priority);
+        await runRequestPromise;
+        await runCreatedEventPromise;
+        const releaseRunSlot = await releaseRunSlotPromise;
         try {
             return await this.executeQueuedRun(binding, options.input, threadId, runId, selectedAgentId, {
                 context: invocation.context,
@@ -939,6 +1067,7 @@ export class AgentHarnessRuntime {
                 previousState: "running",
                 stateSequence: 6,
                 approvalSequence: 7,
+                priorHistory: isNewThread ? [] : undefined,
             });
         }
         finally {
@@ -964,21 +1093,31 @@ 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));
-        yield { type: "event", event: await this.emitRunCreated(threadId, runId, {
-                agentId: selectedAgentId,
-                requestedAgentId: options.agentId ?? AUTO_AGENT_ID,
-                selectedAgentId,
-                input: options.input,
-                state: "running",
-            }) };
-        const releaseRunSlot = await this.acquireRunSlot(threadId, runId);
+        const { threadId, runId, isNewThread } = await this.ensureThreadStarted(selectedAgentId, binding, options.input, options.threadId);
+        const priority = this.normalizeRunPriority(options.priority);
+        const priorHistoryPromise = Promise.resolve(isNewThread ? [] : undefined).then((historyHint) => historyHint ?? this.loadPriorHistory(threadId, runId));
+        const runRequestPromise = this.persistence.saveRunRequest(threadId, runId, this.buildPersistedRunRequest(options.input, invocation, priority));
+        const runCreatedEventPromise = this.emitRunCreated(threadId, runId, {
+            agentId: selectedAgentId,
+            requestedAgentId: options.agentId ?? AUTO_AGENT_ID,
+            selectedAgentId,
+            input: options.input,
+            state: "running",
+        });
+        yield { type: "event", event: await runCreatedEventPromise };
+        const releaseRunSlotPromise = this.acquireRunSlot(threadId, runId, "running", priority);
+        let releaseRunSlot = async () => undefined;
         try {
             try {
-                const priorHistory = await this.loadPriorHistory(threadId, runId);
+                const [priorHistory, acquiredReleaseRunSlot] = await Promise.all([
+                    priorHistoryPromise,
+                    releaseRunSlotPromise,
+                    runRequestPromise,
+                ]).then(([loadedPriorHistory, resolvedReleaseRunSlot]) => [loadedPriorHistory, resolvedReleaseRunSlot]);
+                releaseRunSlot = acquiredReleaseRunSlot;
                 let assistantOutput = "";
                 const toolErrors = [];
+                let lastToolResultKey = null;
                 for await (const chunk of this.runtimeAdapter.stream(binding, options.input, threadId, priorHistory, {
                     context: invocation.context,
                     state: invocation.state,
@@ -1046,6 +1185,11 @@ export class AgentHarnessRuntime {
                             continue;
                         }
                         if (normalizedChunk.kind === "tool-result") {
+                            const toolResultKey = this.createToolResultKey(normalizedChunk.toolName, normalizedChunk.output, normalizedChunk.isError);
+                            if (toolResultKey === lastToolResultKey) {
+                                continue;
+                            }
+                            lastToolResultKey = toolResultKey;
                             if (normalizedChunk.isError) {
                                 toolErrors.push(renderToolFailure(normalizedChunk.toolName, normalizedChunk.output));
                             }
@@ -1229,7 +1373,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",
@@ -1351,6 +1495,7 @@ export class AgentHarnessRuntime {
         await this.checkpointMaintenance?.stop();
         await this.runtimeRecordMaintenance?.stop();
         this.unregisterThreadMemorySync();
+        await Promise.allSettled(Array.from(this.backgroundTasks));
         await this.threadMemorySync.close();
     }
     async stop() {
@@ -1410,7 +1555,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 +1598,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/dist/runtime/thread-memory-sync.js

@@ -79,7 +79,6 @@ export class ThreadMemorySync {
             this.pending.delete(task);
         });
         this.pending.add(task);
-        await task;
     }
     async syncThread(threadId) {
         const thread = await this.persistence.getSession(threadId);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@botbotgo/agent-harness",
-  "version": "0.0.83",
+  "version": "0.0.85",
   "description": "Workspace runtime for multi-agent applications",
   "type": "module",
   "packageManager": "npm@10.9.2",
@@ -53,7 +53,8 @@
   "scripts": {
     "build": "rm -rf dist tsconfig.tsbuildinfo && tsc -p tsconfig.json && cp -R config dist/",
     "check": "tsc -p tsconfig.json --noEmit",
-    "test": "vitest run test/hello-file.test.ts test/public-api.test.ts test/runtime-health.test.ts test/memory-runtime.test.ts test/sqlite-persistence.test.ts test/runtime-queue-lease.test.ts test/runtime-cancel.test.ts test/runtime-record-maintenance.test.ts test/resource-optional-provider.test.ts test/resource-isolation.test.ts test/stock-research-app-load-harness.test.ts test/stock-research-app-run.test.ts test/stock-research-app-config.test.ts test/release-workflow.test.ts test/release-version.test.ts test/gitignore.test.ts test/package-lock.test.ts test/readme.test.ts test/product-boundary-docs.test.ts test/long-term-memory-docs.test.ts test/local-docs-persistence-inventory.test.ts test/docs-site.test.ts test/runtime-adapter-regressions.test.ts test/runtime-capabilities.test.ts test/runtime-recovery.test.ts test/tool-extension-gaps.test.ts test/checkpoint-maintenance.test.ts test/llamaindex-dependency-compat.test.ts test/skill-standard.test.ts test/routing-config.test.ts test/workspace-compat-regressions.test.ts test/upstream-compat-regressions.test.ts test/yaml-format.test.ts test/config-secrets.test.ts test/init-command.test.ts test/coding-agent-guide.test.ts",
+    "test": "vitest run test/hello-file.test.ts test/public-api.test.ts test/runtime-health.test.ts test/memory-runtime.test.ts test/sqlite-persistence.test.ts test/runtime-queue-lease.test.ts test/runtime-cancel.test.ts test/runtime-record-maintenance.test.ts test/resource-optional-provider.test.ts test/resource-isolation.test.ts test/stock-research-app-load-harness.test.ts test/stock-research-app-run.test.ts test/stock-research-app-config.test.ts test/release-workflow.test.ts test/release-version.test.ts test/gitignore.test.ts test/package-lock.test.ts test/readme.test.ts test/product-boundary-docs.test.ts test/long-term-memory-docs.test.ts test/local-docs-persistence-inventory.test.ts test/docs-site.test.ts test/runtime-adapter-regressions.test.ts test/runtime-capabilities.test.ts test/runtime-recovery.test.ts test/tool-extension-gaps.test.ts test/checkpoint-maintenance.test.ts test/llamaindex-dependency-compat.test.ts test/skill-standard.test.ts test/routing-config.test.ts test/workspace-compat-regressions.test.ts test/upstream-compat-regressions.test.ts test/upstream-runtime-ab-benchmark.test.ts test/yaml-format.test.ts test/config-secrets.test.ts test/init-command.test.ts test/coding-agent-guide.test.ts",
+    "test:upstream-ab-real": "vitest run test/upstream-runtime-ab-real.test.ts",
     "test:real-providers": "vitest run test/real-provider-harness.test.ts",
     "release:prepare": "npm version patch --no-git-tag-version && node ./scripts/sync-example-version.mjs",
     "release:pack": "npm pack --dry-run",