@humwick/runner 0.0.0-stage → 0.130.0

package/src/delivery-policy.ts

@@ -0,0 +1,9 @@
+import type { ActiveTurnMessageDelivery, ProviderAdapter, ProviderConfig } from "./adapter";
+
+export function resolveActiveTurnMessageDelivery(config: ProviderConfig | undefined, adapterDefault: ActiveTurnMessageDelivery): ActiveTurnMessageDelivery {
+  return config?.activeTurnMessageDelivery ?? adapterDefault;
+}
+
+export function supportsActiveTurnSteer(adapter: ProviderAdapter, config?: ProviderConfig): boolean {
+  return adapter.supportsMidTurnSteer === true && resolveActiveTurnMessageDelivery(config, "steer") === "steer";
+}

package/src/delivery-result.ts

@@ -0,0 +1,24 @@
+import type { Message } from "@humwick/sdk";
+import type { DeliverResult } from "./adapter";
+
+/** Normalize adapter acceptance, consumption and failure outcomes. */
+export function normalizeDeliverResult(
+  result: void | number[] | DeliverResult,
+  deliverable: Message[],
+): { acknowledgedIds: number[]; terminalFailureIds: number[]; awaitingConsumptionIds: number[]; providerHeldIds: number[] } {
+  if (result === undefined) return { acknowledgedIds: deliverable.map((message) => message.id), terminalFailureIds: [], awaitingConsumptionIds: [], providerHeldIds: [] };
+  if (Array.isArray(result)) return { acknowledgedIds: result, terminalFailureIds: [], awaitingConsumptionIds: [], providerHeldIds: [] };
+  // #2397 round 4 review (F5) — adapter.ts documents terminalFailureIds as a subset of the ids NOT
+  // in acknowledgedIds, but that's only true because every adapter today always reports both
+  // together. Enforce it here too: a future adapter that reports only terminalFailureIds (omitting
+  // acknowledgedIds) must not have this default silently ack its own failures.
+  const terminalFailureIds = result.terminalFailureIds ?? [];
+  const providerHeldIds = result.providerHeldIds ?? [];
+  return {
+    acknowledgedIds: result.acknowledgedIds ?? deliverable.filter((message) => !terminalFailureIds.includes(message.id) && !providerHeldIds.includes(message.id)).map((message) => message.id),
+    providerHeldIds,
+    terminalFailureIds,
+    // #2539 Phase B — accepted-but-unconsumed soft-steer ids: recorded, not settled (see settleMessageDelivery).
+    awaitingConsumptionIds: result.awaitingConsumptionIds ?? [],
+  };
+}

package/src/effort-command.ts

@@ -0,0 +1,125 @@
+import { effortStatePending, errMessage, isRecord, type AgentEffortState } from "@humwick/sdk";
+import type { ManagedProcess, ProviderAdapter } from "./adapter";
+import { fireAndForget } from "./async-guard";
+import type { ProviderInputTicket } from "./provider-input-queue";
+
+/** #2950 — this process can switch effort: the adapter can switch and its launch allows it. */
+export function runnerEffortSwitch(adapter: ProviderAdapter, process: ManagedProcess | undefined): boolean {
+  return Boolean(adapter.setEffort) && process?.meta?.effortSwitch === true;
+}
+
+type EffortHttp = { request(method: string, path: string, body?: unknown): Promise<Response> };
+
+/** The agent's desired/observed effort record, or undefined when nobody ever changed it. */
+export async function readEffortState(http: EffortHttp, agentId: string): Promise<AgentEffortState | undefined> {
+  const response = await http.request("GET", `/api/agents/${encodeURIComponent(agentId)}/effort`);
+  if (!response.ok) throw new Error(`effort state read HTTP ${response.status}`);
+  const body: unknown = await response.json();
+  return isRecord(body) && isRecord(body.state) ? body.state as unknown as AgentEffortState : undefined;
+}
+
+export interface EffortObservedReport { instanceId: string; version: number; effort: string; previousEffort: string | null }
+
+export async function reportEffortObserved(http: EffortHttp, agentId: string, report: EffortObservedReport): Promise<void> {
+  const response = await http.request("POST", `/api/agents/${encodeURIComponent(agentId)}/effort/observed`, report);
+  if (!response.ok) throw new Error(`effort report HTTP ${response.status}`);
+}
+
+export interface EffortReconcilerDeps {
+  http(): EffortHttp;
+  agentId(): string;
+  /** The runner's launch options: its incarnation, adapter, and the effort it runs at (restart + heartbeat read it). */
+  runner(): { instanceId: string; adapter: ProviderAdapter; effort?: string };
+  process(): ManagedProcess | undefined;
+  /** Publish the confirmed level now (heartbeat). */
+  publish(): void;
+  hasProviderTurn(): boolean;
+  reserveInput(): ProviderInputTicket;
+  log(message: string): void;
+}
+
+/** A bus event announcing a new desired version (the audit row's `command.pending`). */
+export function isEffortNotice(eventType: string, data: unknown): boolean {
+  return eventType === "command.pending" && isRecord(data) && isRecord(data.command) && data.command.type === "agent.setEffort";
+}
+
+/**
+ * #2984 — converges the provider on Relay's desired effort version between turns. Triggered by the
+ * runner's existing edges (adoption, registration, the HTTP liveness pass, a bus notice, turn end);
+ * a failed read or report leaves the version pending for the next trigger. No timers of its own.
+ */
+export class EffortReconciler {
+  private running = false;
+  private again = false;
+  private done: Promise<void> = Promise.resolve();
+  /** The last read left work to do, so a turn end is worth a pass. */
+  private pending = false;
+  /** The version this runner switched, kept so a retried report still names the level it replaced. */
+  private switched?: { version: number; previousEffort: string | null };
+
+  constructor(private readonly deps: EffortReconcilerDeps) {}
+
+  trigger(): void {
+    if (this.running) { this.again = true; return; }
+    this.running = true;
+    this.done = fireAndForget("effort reconcile", () => this.loop());
+  }
+
+  /** Resolves once the current reconcile, if any, has finished. */
+  idle(): Promise<void> {
+    return this.done;
+  }
+
+  turnCleared(): void {
+    if (this.pending) this.trigger();
+  }
+
+  private async loop(): Promise<void> {
+    try {
+      do {
+        this.again = false;
+        await this.pass().catch((error) => this.deps.log(`effort reconcile: ${errMessage(error)}`));
+      } while (this.again);
+    } finally {
+      this.running = false;
+    }
+  }
+
+  /** A replacement runner verifies its predecessor's observation instead of trusting it. */
+  private needsWork(state: AgentEffortState | undefined): state is AgentEffortState {
+    return Boolean(state) && (effortStatePending(state!) || state!.observedInstanceId !== this.deps.runner().instanceId);
+  }
+
+  private read(): Promise<AgentEffortState | undefined> {
+    return readEffortState(this.deps.http(), this.deps.agentId());
+  }
+
+  private async pass(): Promise<void> {
+    const runner = this.deps.runner();
+    if (!runnerEffortSwitch(runner.adapter, this.deps.process())) return;
+    this.pending = this.needsWork(await this.read());
+    if (!this.pending || this.deps.hasProviderTurn()) return;
+    const ticket = this.deps.reserveInput();
+    try {
+      await ticket.turn;
+      // A turn that started ahead of this slot keeps the change pending until it ends too.
+      if (this.deps.hasProviderTurn()) return;
+      const state = await this.read();
+      this.pending = this.needsWork(state);
+      if (!this.needsWork(state)) return;
+      const current = runner.effort ?? null;
+      let previousEffort = current;
+      if (current === state.desiredEffort && this.switched?.version === state.desiredVersion) previousEffort = this.switched.previousEffort;
+      if (current !== state.desiredEffort) {
+        const switched = await runner.adapter.setEffort!(this.deps.process()!, state.desiredEffort);
+        this.switched = { version: state.desiredVersion, previousEffort: current };
+        runner.effort = switched.effort;
+        this.deps.publish();
+      }
+      await reportEffortObserved(this.deps.http(), this.deps.agentId(), { instanceId: runner.instanceId, version: state.desiredVersion, effort: runner.effort ?? state.desiredEffort, previousEffort });
+      this.pending = false;
+    } finally {
+      ticket.release();
+    }
+  }
+}