@botbotgo/agent-harness 0.0.129 → 0.0.130

package/README.md

@@ -109,7 +109,11 @@ Boundary documents live in:
 
 - `docs/upstream-feature-matrix.md`
 - `docs/product-boundary.md`
+- `docs/runtime-blueprint-assessment.md`
+- `docs/policy-engine-scope.md`
 - `docs/acp-support-plan.md`
+- `docs/recovery-policy-matrix.md`
+- `docs/operator-timeline.md`
 - `docs/feature-checklist.md`
 - `docs/long-term-memory.md`
 - `docs/app-task-pattern.md`

package/README.zh.md

@@ -109,7 +109,11 @@ AI 让 agent 逻辑、工具调用和工作流代码更容易生成，真正变
 
 - `docs/upstream-feature-matrix.md`
 - `docs/product-boundary.md`
+- `docs/runtime-blueprint-assessment.md`
+- `docs/policy-engine-scope.md`
 - `docs/acp-support-plan.md`
+- `docs/recovery-policy-matrix.md`
+- `docs/operator-timeline.md`
 - `docs/feature-checklist.md`
 - `docs/long-term-memory.md`
 - `docs/app-task-pattern.md`

package/dist/contracts/runtime.d.ts

@@ -40,6 +40,25 @@ export type HarnessEventProjection = {
     shouldHandle?: (event: HarnessEvent) => boolean;
     handleEvent: HarnessEventListener;
 };
+/**
+ * Operator-facing timeline item projected from persisted runtime events.
+ * This is an inspection convenience over runtime records, not a new execution protocol.
+ */
+export type RuntimeTimelineItem = {
+    eventId: string;
+    threadId: string;
+    runId: string;
+    eventType: HarnessEventType;
+    timestamp: string;
+    sequence: number;
+    source: HarnessEvent["source"];
+    kind: "run" | "queue" | "approval" | "recovery" | "artifact" | "other";
+    payload: Record<string, unknown>;
+};
+export type RuntimeTimelineProjectionOptions = {
+    threadId?: string;
+    runId?: string;
+};
 export type RuntimeEventSink = {
     publish: (event: HarnessEvent) => void;
     subscribe: (listener: HarnessEventListener) => () => void;

package/dist/package-version.d.ts

@@ -1 +1 @@
-export declare const AGENT_HARNESS_VERSION = "0.0.128";
+export declare const AGENT_HARNESS_VERSION = "0.0.129";

package/dist/package-version.js

@@ -1 +1 @@
-export const AGENT_HARNESS_VERSION = "0.0.128";
+export const AGENT_HARNESS_VERSION = "0.0.129";

package/dist/runtime/harness/events/timeline.d.ts

@@ -0,0 +1,2 @@
+import type { HarnessEvent, RuntimeTimelineItem, RuntimeTimelineProjectionOptions } from "../../../contracts/types.js";
+export declare function projectRuntimeTimeline(events: readonly HarnessEvent[], options?: RuntimeTimelineProjectionOptions): RuntimeTimelineItem[];

package/dist/runtime/harness/events/timeline.js

@@ -0,0 +1,52 @@
+function classifyTimelineItem(event) {
+    switch (event.eventType) {
+        case "run.queued":
+        case "run.dequeued":
+            return "queue";
+        case "approval.requested":
+        case "approval.resolved":
+            return "approval";
+        case "run.resumed":
+            return "recovery";
+        case "artifact.created":
+            return "artifact";
+        case "run.created":
+        case "run.state.changed":
+            return "run";
+        default:
+            return "other";
+    }
+}
+export function projectRuntimeTimeline(events, options = {}) {
+    const filtered = events.filter((event) => {
+        if (options.threadId && event.threadId !== options.threadId) {
+            return false;
+        }
+        if (options.runId && event.runId !== options.runId) {
+            return false;
+        }
+        return true;
+    });
+    return [...filtered]
+        .sort((left, right) => {
+        const timestampComparison = left.timestamp.localeCompare(right.timestamp);
+        if (timestampComparison !== 0) {
+            return timestampComparison;
+        }
+        if (left.sequence !== right.sequence) {
+            return left.sequence - right.sequence;
+        }
+        return left.eventId.localeCompare(right.eventId);
+    })
+        .map((event) => ({
+        eventId: event.eventId,
+        threadId: event.threadId,
+        runId: event.runId,
+        eventType: event.eventType,
+        timestamp: event.timestamp,
+        sequence: event.sequence,
+        source: event.source,
+        kind: classifyTimelineItem(event),
+        payload: event.payload,
+    }));
+}

package/dist/runtime/harness/index.d.ts

@@ -1,6 +1,7 @@
 export * from "./events/event-bus.js";
 export * from "./events/event-sink.js";
 export * from "./events/events.js";
+export * from "./events/timeline.js";
 export * from "./system/health-monitor.js";
 export * from "./run/helpers.js";
 export * from "./system/inventory.js";

package/dist/runtime/harness/index.js

@@ -1,6 +1,7 @@
 export * from "./events/event-bus.js";
 export * from "./events/event-sink.js";
 export * from "./events/events.js";
+export * from "./events/timeline.js";
 export * from "./system/health-monitor.js";
 export * from "./run/helpers.js";
 export * from "./system/inventory.js";

package/dist/runtime/harness/run/recovery.js

@@ -41,6 +41,17 @@ async function executeRecoveredRun(context, input) {
     }
     return true;
 }
+async function failResumingRecovery(context, thread, checkpointRef, error) {
+    await context.persistence.setRunState(thread.threadId, thread.latestRunId, "failed", checkpointRef);
+    await context.persistence.clearRecoveryIntent(thread.threadId, thread.latestRunId);
+    await context.emit(thread.threadId, thread.latestRunId, 101, "run.state.changed", {
+        previousState: "resuming",
+        state: "failed",
+        checkpointRef,
+        ...(error ? { error } : {}),
+    });
+    return true;
+}
 export async function recoverQueuedStartupRun(context, thread) {
     if (thread.status !== "queued") {
         return false;
@@ -113,9 +124,7 @@ export async function recoverResumingStartupRun(context, thread) {
         return true;
     }
     if (recoveryIntent.attempts >= context.recoveryConfig.maxRecoveryAttempts) {
-        await context.persistence.setRunState(thread.threadId, thread.latestRunId, "failed", recoveryIntent.checkpointRef);
-        await context.persistence.clearRecoveryIntent(thread.threadId, thread.latestRunId);
-        return true;
+        return failResumingRecovery(context, thread, recoveryIntent.checkpointRef, "recovery attempts exhausted");
     }
     await context.persistence.saveRecoveryIntent(thread.threadId, thread.latestRunId, {
         ...recoveryIntent,
@@ -143,14 +152,7 @@ export async function recoverResumingStartupRun(context, thread) {
     catch (error) {
         context.recordLlmFailure(startedAt);
         if (recoveryIntent.attempts + 1 >= context.recoveryConfig.maxRecoveryAttempts) {
-            await context.persistence.setRunState(thread.threadId, thread.latestRunId, "failed", recoveryIntent.checkpointRef);
-            await context.persistence.clearRecoveryIntent(thread.threadId, thread.latestRunId);
-            await context.emit(thread.threadId, thread.latestRunId, 101, "run.state.changed", {
-                previousState: "resuming",
-                state: "failed",
-                checkpointRef: recoveryIntent.checkpointRef,
-                error: error instanceof Error ? error.message : String(error),
-            });
+            await failResumingRecovery(context, thread, recoveryIntent.checkpointRef, error instanceof Error ? error.message : String(error));
         }
     }
     return true;

package/dist/runtime/harness/system/policy-engine.d.ts

@@ -4,6 +4,11 @@ export type PolicyEngineDecision = {
     reasons: string[];
 };
 export declare class PolicyEngine {
+    /**
+     * Runtime governance gate for a compiled binding.
+     * This engine may allow or block execution with reasons, but it must not
+     * redefine upstream planning or execution semantics.
+     */
     evaluate(binding: CompiledAgentBinding): PolicyEngineDecision;
 }
 export { PolicyEngineDecision as GovernanceDecision, PolicyEngine as GovernanceEngine, };

package/dist/runtime/harness/system/policy-engine.js

@@ -1,5 +1,10 @@
 import { getPolicyEvaluators } from "../../../extensions.js";
 export class PolicyEngine {
+    /**
+     * Runtime governance gate for a compiled binding.
+     * This engine may allow or block execution with reasons, but it must not
+     * redefine upstream planning or execution semantics.
+     */
     evaluate(binding) {
         const reasons = [];
         let allowed = true;

package/package.json

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