@yeaft/webchat-agent 1.0.530 → 1.0.532

package/yeaft/work-center/resource-control.js

@@ -0,0 +1,460 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { LLMAdapter } from '../llm/adapter.js';
+import { normalizeTokenUsage } from '../llm/usage-accounting.js';
+
+// Work Center-local admission limits, not Engine or Session limits. Tokens are
+// estimated before dispatch; this is not a guarantee about provider billing.
+export const DEFAULT_EXECUTION_LIMITS = Object.freeze({
+  maxRequests: 200,
+  maxTokens: 2_000_000,
+  maxRunRequests: 40,
+  maxActionAttempts: 3,
+  maxCoordinatorFailures: 3,
+});
+const TOKEN_KEYS = ['inputTokens', 'outputTokens', 'cacheReadTokens', 'cacheWriteTokens', 'totalTokens'];
+const UNKNOWN_REQUEST_TOKENS = 16_384;
+const parse = (value, fallback) => { try { return JSON.parse(value); } catch { return fallback; } };
+const count = value => Number.isFinite(Number(value)) ? Math.max(0, Number(value)) : 0;
+const emptyUsage = () => ({ llmRequestCount: 0, ...normalizeTokenUsage(), reservedTokens: 0,
+  chargedTokens: 0, unknownRequests: 0, inFlightRequests: 0 });
+
+export function estimateRequestTokens(request = {}) {
+  // UTF-8 bytes / 3 is deliberately conservative for typical code/text, but is
+  // still an estimate (images, tokenizer and reasoning behavior vary by model).
+  const input = Math.ceil(Buffer.byteLength(JSON.stringify({ system: request.system,
+    messages: request.messages, tools: request.tools }), 'utf8') / 3);
+  return input + Math.max(1, count(request.maxTokens) || UNKNOWN_REQUEST_TOKENS);
+}
+
+export class WorkCenterResourceStopError extends Error {
+  constructor(reason) {
+    super(`Work Center execution stopped: ${reason?.code || 'needs_attention'}. Explicit user resume or budget extension required.`);
+    this.name = 'WorkCenterResourceStopError';
+    this.retryable = false;
+    this.workItemFailureKind = 'resource_limit';
+    this.workItemFailureCode = reason?.code || 'execution_stopped';
+  }
+}
+
+/** SQLite owns admission and settlement. Callers may already hold BEGIN IMMEDIATE. */
+export class WorkCenterResourceControl {
+  constructor(store) {
+    this.store = store;
+    this.db = store.db;
+    this.db.exec(`
+      CREATE TABLE IF NOT EXISTS work_item_execution_controls (
+        work_item_id TEXT PRIMARY KEY REFERENCES work_items(id) ON DELETE CASCADE,
+        limits_json TEXT NOT NULL, stop_reason TEXT, coordinator_failures INTEGER NOT NULL DEFAULT 0,
+        retry_after INTEGER NOT NULL DEFAULT 0,
+        revision INTEGER NOT NULL DEFAULT 1, action_attempts_extension INTEGER NOT NULL DEFAULT 0,
+        data_revision INTEGER NOT NULL DEFAULT 1, projection_hash TEXT
+      );
+      CREATE TABLE IF NOT EXISTS work_item_action_attempt_limits (
+        action_id TEXT PRIMARY KEY REFERENCES actions(id) ON DELETE CASCADE,
+        original_max_attempts INTEGER NOT NULL
+      );
+      CREATE TRIGGER IF NOT EXISTS work_item_action_attempt_limit_insert
+      AFTER INSERT ON actions BEGIN
+        INSERT OR IGNORE INTO work_item_action_attempt_limits (action_id, original_max_attempts)
+          VALUES (NEW.id, MAX(0, NEW.max_attempts));
+      END;
+      CREATE TABLE IF NOT EXISTS work_item_resource_requests (
+        id TEXT PRIMARY KEY, work_item_id TEXT NOT NULL REFERENCES work_items(id) ON DELETE CASCADE,
+        kind TEXT NOT NULL, run_id TEXT, request_count INTEGER NOT NULL DEFAULT 1,
+        estimated_tokens INTEGER NOT NULL, charged_tokens INTEGER NOT NULL,
+        usage_json TEXT, status TEXT NOT NULL, created_at INTEGER NOT NULL
+      );
+      CREATE INDEX IF NOT EXISTS resource_requests_work_item ON work_item_resource_requests(work_item_id, run_id);
+      CREATE TRIGGER IF NOT EXISTS work_item_execution_stop_status
+      AFTER UPDATE OF status ON work_items
+      WHEN NEW.status NOT IN ('needs_attention', 'cancelled') AND EXISTS (
+        SELECT 1 FROM work_item_execution_controls c WHERE c.work_item_id = NEW.id AND c.stop_reason IS NOT NULL
+      ) BEGIN UPDATE work_items SET status = 'needs_attention' WHERE id = NEW.id; END;
+    `);
+    // Additive migration from the initial ledger schema; never change the goal
+    // contract revision to represent resource administration.
+    this.atomic(() => {
+      const columns = this.db.prepare('PRAGMA table_info(work_item_execution_controls)').all().map(row => row.name);
+      if (!columns.includes('revision')) this.db.exec('ALTER TABLE work_item_execution_controls ADD COLUMN revision INTEGER NOT NULL DEFAULT 1');
+      if (!columns.includes('action_attempts_extension')) this.db.exec('ALTER TABLE work_item_execution_controls ADD COLUMN action_attempts_extension INTEGER NOT NULL DEFAULT 0');
+      if (!columns.includes('data_revision')) this.db.exec('ALTER TABLE work_item_execution_controls ADD COLUMN data_revision INTEGER NOT NULL DEFAULT 1');
+      if (!columns.includes('projection_hash')) this.db.exec('ALTER TABLE work_item_execution_controls ADD COLUMN projection_hash TEXT');
+      this.db.exec(`INSERT OR IGNORE INTO work_item_action_attempt_limits (action_id, original_max_attempts)
+        SELECT id, MAX(0, max_attempts) FROM actions`);
+      // Snapshot pre-ledger data once. Reopening never imports a Run twice.
+      for (const item of this.db.prepare(`SELECT id FROM work_items WHERE id NOT IN
+        (SELECT work_item_id FROM work_item_execution_controls)`).all()) this.ensure(item.id);
+    });
+  }
+
+  atomic(fn) {
+    if (this.db.isTransaction) return fn();
+    this.db.exec('BEGIN IMMEDIATE');
+    try { const result = fn(); this.db.exec('COMMIT'); return result; }
+    catch (error) { this.db.exec('ROLLBACK'); throw error; }
+  }
+
+  ensure(id) {
+    const existing = this.db.prepare('SELECT * FROM work_item_execution_controls WHERE work_item_id = ?').get(id);
+    if (existing) return existing;
+    this.db.prepare('INSERT INTO work_item_execution_controls (work_item_id, limits_json) VALUES (?, ?)')
+      .run(id, JSON.stringify(DEFAULT_EXECUTION_LIMITS));
+    for (const run of this.db.prepare('SELECT * FROM runs WHERE work_item_id = ?').all(id)) {
+      const turns = this.db.prepare(`SELECT COUNT(*) AS n,
+        MAX(status IN ('dispatching', 'unknown')) AS unknown FROM engine_turns
+        WHERE run_id = ? AND status != 'prepared'`).get(run.id);
+      // Aggregate Run usage may only cover earlier responses. A later ambiguous
+      // dispatch must retain its estimate even when the Run is already terminal.
+      const unknown = ['running', 'dispatch_unknown'].includes(run.status) || !!turns.unknown;
+      const requests = Math.max(count(run.llm_request_count), count(turns.n), unknown ? 1 : 0);
+      if (!requests && !run.total_tokens) continue;
+      const usage = normalizeTokenUsage({ inputTokens: run.input_tokens, outputTokens: run.output_tokens,
+        cacheReadTokens: run.cache_read_tokens, cacheWriteTokens: run.cache_write_tokens, totalTokens: run.total_tokens });
+      const estimate = unknown ? Math.max(usage.totalTokens, requests * UNKNOWN_REQUEST_TOKENS)
+        : usage.totalTokens || requests * UNKNOWN_REQUEST_TOKENS;
+      this.insert({ id: `legacy-run:${run.id}`, workItemId: id, kind: 'action', runId: run.id,
+        requests, estimate, usage, status: usage.totalTokens && !unknown ? 'reported' : 'unknown' });
+    }
+    for (const turn of this.db.prepare(`SELECT * FROM coordinator_provider_turns WHERE work_item_id = ?
+      AND status != 'prepared'`).all(id)) {
+      const response = parse(turn.response, {});
+      const usage = response?.usage ? normalizeTokenUsage(response.usage) : null;
+      this.insert({ id: turn.id, workItemId: id, kind: 'coordinator',
+        estimate: estimateRequestTokens(parse(turn.request_body, {})), usage,
+        status: usage ? 'reported' : 'unknown' });
+    }
+    return this.db.prepare('SELECT * FROM work_item_execution_controls WHERE work_item_id = ?').get(id);
+  }
+
+  insert({ id, workItemId, kind, runId = null, requests = 1, estimate, usage = null, status = 'reserved' }) {
+    this.db.prepare(`INSERT INTO work_item_resource_requests
+      (id, work_item_id, kind, run_id, request_count, estimated_tokens, charged_tokens, usage_json, status, created_at)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`).run(id, workItemId, kind, runId, requests, estimate,
+      status === 'reported' ? usage.totalTokens : Math.max(estimate, usage?.totalTokens || 0),
+      usage ? JSON.stringify(usage) : null, status, this.store.now());
+    this.advanceDataRevision(workItemId);
+  }
+
+  advanceDataRevision(id) {
+    // Independent of the user-command CAS and goal revision. Null invalidates
+    // the projection fingerprint: this mutation already advanced its version.
+    this.db.prepare(`UPDATE work_item_execution_controls SET data_revision = data_revision + 1,
+      projection_hash = NULL WHERE work_item_id = ?`).run(id);
+  }
+
+  snapshot(id) {
+    return this.atomic(() => this.projectSnapshot(id));
+  }
+
+  projectSnapshot(id) {
+    const control = this.ensure(id);
+    const now = this.store.now();
+    const breakdown = { coordinator: emptyUsage(), actions: emptyUsage() };
+    for (const row of this.db.prepare('SELECT * FROM work_item_resource_requests WHERE work_item_id = ?').all(id)) {
+      const target = row.kind === 'coordinator' ? breakdown.coordinator : breakdown.actions;
+      const usage = parse(row.usage_json, {}) || {};
+      target.llmRequestCount += row.request_count;
+      for (const key of TOKEN_KEYS) target[key] += count(usage[key]);
+      target.chargedTokens += row.charged_tokens;
+      if (row.status !== 'reported') target.reservedTokens += row.charged_tokens;
+      if (row.status === 'unknown') target.unknownRequests += row.request_count;
+      if (row.status === 'reserved') {
+        const live = row.run_id
+          ? this.db.prepare("SELECT 1 FROM runs WHERE id = ? AND status = 'running' AND expires_at > ?").get(row.run_id, now)
+          : this.db.prepare("SELECT 1 FROM coordinator_provider_turns WHERE id = ? AND status = 'dispatching'").get(row.id.split(':retry:')[0]);
+        if (live) target.inFlightRequests += row.request_count;
+        else target.unknownRequests += row.request_count;
+      }
+    }
+    const usage = emptyUsage();
+    for (const part of Object.values(breakdown)) for (const key of Object.keys(usage)) usage[key] += part[key];
+    const limits = parse(control.limits_json, DEFAULT_EXECUTION_LIMITS);
+    const actionAttempts = this.db.prepare(`SELECT a.id, l.original_max_attempts,
+      (SELECT COUNT(*) FROM runs r WHERE r.action_id = a.id) AS attempts
+      FROM actions a JOIN work_item_action_attempt_limits l ON l.action_id = a.id
+      WHERE a.work_item_id = ? ORDER BY a.sequence, a.id`).all(id).map(row => ({
+      actionId: row.id, attempts: row.attempts, originalMaxAttempts: row.original_max_attempts,
+      effectiveMaxAttempts: Math.min(row.original_max_attempts + control.action_attempts_extension, limits.maxActionAttempts),
+    }));
+    const snapshot = { revision: control.revision, limits, usage,
+      actionAttemptsExtension: control.action_attempts_extension, actionAttempts,
+      stopReason: parse(control.stop_reason, null), breakdown,
+      coordinatorFailures: control.coordinator_failures, retryAfter: control.retry_after,
+      tokenAccounting: 'estimated_admission_reported_usage_unknown_retained' };
+    // Attempts and in-flight/unknown classification are derived from other
+    // ledgers (and lease expiry). Version each observed change durably under the
+    // same write transaction, including changes without a reserve or settle.
+    const hash = createHash('sha256').update(JSON.stringify(snapshot)).digest('hex');
+    const dataRevision = control.data_revision + (control.projection_hash != null && control.projection_hash !== hash ? 1 : 0);
+    if (control.projection_hash !== hash) {
+      this.db.prepare('UPDATE work_item_execution_controls SET data_revision = ?, projection_hash = ? WHERE work_item_id = ?')
+        .run(dataRevision, hash, id);
+    }
+    return { ...snapshot, dataRevision };
+  }
+
+  stopped(id) {
+    return !!this.db.prepare('SELECT stop_reason FROM work_item_execution_controls WHERE work_item_id = ?').get(id)?.stop_reason;
+  }
+
+  stop(id, code, details = {}) {
+    return this.atomic(() => {
+      this.ensure(id);
+      const reason = { code, at: this.store.now(), ...details };
+      const changed = this.db.prepare(`UPDATE work_item_execution_controls SET stop_reason = ?, revision = revision + 1
+        WHERE work_item_id = ? AND stop_reason IS NULL`).run(JSON.stringify(reason), id);
+      if (changed.changes) {
+        this.advanceDataRevision(id);
+        this.db.prepare(`UPDATE work_items SET status = CASE WHEN status = 'cancelled' THEN status ELSE 'needs_attention' END,
+          updated_at = ? WHERE id = ?`).run(this.store.now(), id);
+        this.store.appendEvent(id, 'work_item.execution_stopped', reason);
+      }
+      return this.snapshot(id).stopReason;
+    });
+  }
+
+  reserve({ id = randomUUID(), workItemId, kind, runId = null, request = {} }) {
+    // Return denial rather than throwing inside the transaction: the stop must
+    // commit even though the caller must throw before touching the provider.
+    return this.atomic(() => {
+      const snapshot = this.snapshot(workItemId);
+      const previous = this.db.prepare('SELECT * FROM work_item_resource_requests WHERE id = ?').get(id);
+      if (previous) return { allowed: false, reason: { code: 'request_already_reserved' } };
+      if (snapshot.stopReason) return { allowed: false, reason: snapshot.stopReason };
+      const item = this.db.prepare('SELECT status FROM work_items WHERE id = ?').get(workItemId);
+      if (['done', 'cancelled'].includes(item?.status)) return { allowed: false, reason: { code: 'work_item_inactive' } };
+      const estimate = estimateRequestTokens(request);
+      const runRequests = runId ? this.db.prepare(`SELECT COALESCE(SUM(request_count), 0) AS n
+        FROM work_item_resource_requests WHERE run_id = ?`).get(runId).n : 0;
+      const code = runId && runRequests >= snapshot.limits.maxRunRequests ? 'run_requests_exhausted'
+        : snapshot.usage.llmRequestCount >= snapshot.limits.maxRequests ? 'work_item_requests_exhausted'
+          : snapshot.usage.chargedTokens + estimate > snapshot.limits.maxTokens ? 'work_item_tokens_exhausted' : null;
+      if (code) return { allowed: false, reason: this.stop(workItemId, code, { runId, estimatedNextTokens: estimate }) };
+      this.insert({ id, workItemId, kind, runId, estimate });
+      return { allowed: true, id };
+    });
+  }
+
+  settle(id, rawUsage, complete = true) {
+    return this.atomic(() => {
+      const row = this.db.prepare('SELECT * FROM work_item_resource_requests WHERE id = ?').get(id);
+      if (!row || row.status === 'reported' || (row.status === 'unknown' && !rawUsage)) return false;
+      const usage = rawUsage ? normalizeTokenUsage(rawUsage) : null;
+      const reported = complete && usage && usage.totalTokens > 0;
+      const charged = reported ? usage.totalTokens : Math.max(row.estimated_tokens, usage?.totalTokens || 0);
+      this.db.prepare(`UPDATE work_item_resource_requests SET usage_json = ?, charged_tokens = ?, status = ? WHERE id = ?`)
+        .run(usage ? JSON.stringify(usage) : row.usage_json, charged, reported ? 'reported' : 'unknown', id);
+      this.advanceDataRevision(row.work_item_id);
+      const snapshot = this.snapshot(row.work_item_id);
+      if (snapshot.usage.chargedTokens > snapshot.limits.maxTokens) this.stop(row.work_item_id, 'work_item_tokens_exhausted');
+      return true;
+    });
+  }
+
+  coordinatorRequestIds(turnId) {
+    return this.db.prepare(`SELECT id FROM work_item_resource_requests WHERE id = ? OR id LIKE ? ORDER BY rowid DESC`)
+      .all(turnId, `${turnId}:retry:%`).map(row => row.id);
+  }
+
+  settleCoordinator(turnId, usage, complete = true) {
+    const [latest, ...earlier] = this.coordinatorRequestIds(turnId);
+    for (const id of earlier) this.settle(id, null, false);
+    return latest ? this.settle(latest, usage, complete) : false;
+  }
+
+  canAttempt(action) {
+    const entry = this.snapshot(action.workItemId).actionAttempts.find(row => row.actionId === action.id);
+    if (entry && entry.attempts < entry.effectiveMaxAttempts) return true;
+    this.stop(action.workItemId, 'action_attempts_exhausted', entry || { actionId: action.id });
+    return false;
+  }
+
+  coordinatorFailed(id, turnId) {
+    return this.atomic(() => {
+      const snapshot = this.snapshot(id);
+      const failures = snapshot.coordinatorFailures + 1;
+      this.db.prepare(`UPDATE work_item_execution_controls SET coordinator_failures = ?, retry_after = ? WHERE work_item_id = ?`)
+        .run(failures, this.store.now() + Math.min(1_000 * (2 ** Math.min(failures - 1, 8)), 300_000), id);
+      this.advanceDataRevision(id);
+      if (failures >= snapshot.limits.maxCoordinatorFailures) {
+        this.stop(id, 'coordinator_failures_exhausted', { turnId, failures });
+      }
+    });
+  }
+
+  /** Only an authenticated user command may call this; no model/tool path. */
+  extend(id, revision, additions = {}) {
+    return this.atomic(() => {
+      if (!this.store.getWorkItem(id)) throw new Error(`WorkItem not found: ${id}`);
+      this.assertRevision(id, revision);
+      if (!additions || typeof additions !== 'object' || Array.isArray(additions)
+          || Object.keys(additions).length === 0) throw new Error('Invalid execution budget additions');
+      const snapshot = this.snapshot(id);
+      const limits = { ...snapshot.limits };
+      for (const [key, value] of Object.entries(additions)) {
+        if (!Object.hasOwn(limits, key) || !Number.isSafeInteger(value) || value <= 0
+            || !Number.isSafeInteger(limits[key] + value)) throw new Error(`Invalid execution budget addition: ${key}`);
+        limits[key] += value;
+      }
+      this.db.prepare(`UPDATE work_item_execution_controls SET limits_json = ?, revision = revision + 1,
+        action_attempts_extension = action_attempts_extension + ? WHERE work_item_id = ? AND revision = ?`)
+        .run(JSON.stringify(limits), additions.maxActionAttempts || 0, id, revision);
+      this.advanceDataRevision(id);
+      this.db.prepare('UPDATE work_items SET updated_at = ? WHERE id = ?').run(this.store.now(), id);
+      this.store.appendEvent(id, 'work_item.execution_budget_extended', { additions, limits });
+      return this.store.getWorkItemDetail(id);
+    });
+  }
+
+  assertRevision(id, revision) {
+    if (!Number.isSafeInteger(revision) || this.ensure(id).revision !== revision) {
+      throw new Error('Execution control changed; refresh before changing execution budget or resuming');
+    }
+  }
+
+  resume(id, revision) {
+    if (revision !== undefined || this.stopped(id)) this.assertRevision(id, revision);
+    const snapshot = this.snapshot(id);
+    if (snapshot.usage.llmRequestCount >= snapshot.limits.maxRequests
+        || snapshot.usage.chargedTokens >= snapshot.limits.maxTokens
+        || snapshot.coordinatorFailures >= snapshot.limits.maxCoordinatorFailures) {
+      throw new Error('Extend the exhausted WorkItem execution budget before resuming');
+    }
+    if (snapshot.stopReason?.code === 'action_attempts_exhausted') {
+      const action = this.store.getAction(snapshot.stopReason.actionId);
+      if (action && !this.canAttempt(action)) throw new Error('Extend maxActionAttempts before resuming');
+    }
+    this.db.prepare(`UPDATE work_item_execution_controls SET stop_reason = NULL, retry_after = 0,
+      revision = revision + 1, data_revision = data_revision + 1, projection_hash = NULL WHERE work_item_id = ?`).run(id);
+  }
+}
+
+/** Fail-closed, Work Center-only adapter. Every native callback runs immediately
+ * before fetch; plain legacy adapters reserve at invocation/iteration instead.
+ * Reservations survive crash/abort/missing usage and never become free retries.
+ */
+export class WorkCenterResourceAdapter extends LLMAdapter {
+  constructor(adapter, store, workItemId, runId) {
+    super(adapter?.config || {});
+    this.adapter = adapter;
+    this.store = store;
+    this.workItemId = workItemId;
+    this.runId = runId;
+  }
+
+  captureRequest() {
+    const captured = this.adapter.captureRequest?.();
+    const capture = captured?.captureStream || this.adapter.captureStream?.bind(this.adapter)
+      || this.adapter.stream.bind(this.adapter);
+    const native = this.adapter instanceof LLMAdapter;
+    return { captureStream: params => this.accountStream(capture, params, native) };
+  }
+  captureStream(params) { return this.captureRequest().captureStream(params); }
+  stream(params) { return this.captureStream(params); }
+
+  request(params) {
+    let reservation = null;
+    let usage = null;
+    let suppressFirstCallback = false;
+    const settle = (reportedUsage, complete) => {
+      if (reservation?.allowed) this.store.settleWorkItemRequest(reservation.id, reportedUsage ?? usage, complete);
+    };
+    const start = () => {
+      settle(usage, false);
+      reservation = null;
+      usage = null;
+      // Admission precedes Engine dispatch marking: a denied request must not
+      // become a dispatch-unknown Run. If the subsequent lease fence fails the
+      // reservation remains conservatively charged (no free ambiguous retry).
+      if (this.store.isExecutionStopped(this.workItemId)) {
+        throw new WorkCenterResourceStopError(this.store.getExecutionControl(this.workItemId).stopReason);
+      }
+      reservation = this.store.reserveWorkItemRequest({ workItemId: this.workItemId,
+        kind: 'action', runId: this.runId, request: params });
+      if (!reservation.allowed) throw new WorkCenterResourceStopError(reservation.reason);
+      params.onRequestStart?.();
+    };
+    return { params: { ...params, onRequestStart: () => {
+      if (suppressFirstCallback) {
+        suppressFirstCallback = false;
+        if (this.store.isExecutionStopped(this.workItemId)) {
+          throw new WorkCenterResourceStopError(this.store.getExecutionControl(this.workItemId).stopReason);
+        }
+        // Early legacy admission is not the last dispatch boundary. Recheck the
+        // original EngineTurn/Run lease without reserving or counting it again.
+        params.onRequestStart?.();
+        return;
+      }
+      start();
+    } }, start: () => { start(); suppressFirstCallback = true; },
+      addUsage: event => {
+        usage ||= normalizeTokenUsage();
+        const next = normalizeTokenUsage(event);
+        for (const key of TOKEN_KEYS) usage[key] += next[key];
+      }, settle };
+  }
+
+  async *accountStream(capture, params, native) {
+    const request = this.request(params);
+    let complete = false;
+    try {
+      if (!native) request.start();
+      for await (const event of capture(request.params)) {
+        if (event?.type === 'usage') request.addUsage(event);
+        yield event;
+      }
+      complete = true;
+    } finally { request.settle(null, complete); }
+  }
+  async call(params) {
+    const request = this.request(params);
+    let usage = null;
+    let complete = false;
+    try {
+      // Side calls also count, including any future Engine helper calls.
+      if (!(this.adapter instanceof LLMAdapter)) request.start();
+      const result = await this.adapter.call(request.params);
+      usage = result?.usage;
+      complete = true;
+      return result;
+    } finally { request.settle(usage, complete); }
+  }
+  getProviderForModel(model) { return this.adapter.getProviderForModel?.(model) || null; }
+  listAvailableModels() { return this.adapter.listAvailableModels?.() || []; }
+}
+
+/** Native adapters own the last pre-fetch callback; plain legacy adapters are
+ * conservatively admitted before invocation even if they omit the callback. */
+export async function callCoordinatorWithResourceControl(adapter, store, turn, claim, params) {
+  const native = adapter instanceof LLMAdapter;
+  let suppressFirstCallback = !native;
+  const start = (revalidate = false) => {
+    const active = revalidate ? store.isActiveCoordinatorProviderTurn(turn.id, claim)
+      : store.dispatchCoordinatorProviderTurn(turn.id, claim);
+    if (!active) {
+      const error = new Error('Coordinator provider turn lost its dispatch fence or execution budget');
+      error.retryable = false;
+      throw error;
+    }
+  };
+  try {
+    if (!native) start();
+    const response = await adapter.call({ ...params, onRequestStart: () => {
+      if (suppressFirstCallback) {
+        suppressFirstCallback = false;
+        // A resumed WorkItem may be active while this pre-stop claim is stale.
+        // Revalidate it without treating the first callback as a paid retry.
+        start(true);
+        return;
+      }
+      start();
+    } });
+    // Even a late response after cancellation is real consumption. Response CAS
+    // still fences its decision, while idempotent settlement keeps its usage.
+    store.settleCoordinatorRequest(turn.id, response?.usage);
+    return response;
+  } catch (error) {
+    store.settleCoordinatorRequest(turn.id, null, false);
+    throw error;
+  }
+}

package/yeaft/work-center/runner.js

@@ -17,6 +17,7 @@ import { existsSync, lstatSync, readFileSync, realpathSync } from 'node:fs';
 import path from 'node:path';
 import { sessionMessageQuotePrompt } from '../session-message-quote.js';
 import { buildWorkItemAttachmentContext } from './attachments.js';
+import { WorkCenterResourceAdapter } from './resource-control.js';
 import { withUsageAccounting } from '../llm/usage-accounting.js';
 import {
   commitActionWorktree,
@@ -51,20 +52,7 @@ import {
   renderMainlineContextSnapshot,
 } from './mainline-projection.js';
 
-const WORK_ITEM_TOOL_NAMES = Object.freeze([
-  'FileRead',
-  'FileWrite',
-  'FileEdit',
-  'ApplyPatch',
-  'Glob',
-  'Grep',
-  'ListDir',
-  'Bash',
-  'WebSearch',
-  'WebFetch',
-  'ViewImage',
-  'Skill',
-]);
+import { WORK_ITEM_TOOL_NAMES, workItemBuiltinToolNames } from './capabilities.js';
 const WORK_ITEM_TOOL_ALLOWLIST = new Set(WORK_ITEM_TOOL_NAMES);
 const DEFAULT_PROGRESS_INTERVAL_MS = 200;
 const ACTION_INPUT_QUOTE_MAX_BYTES = 8 * 1024;
@@ -272,7 +260,7 @@ function assertToolInput(toolName, input, workDir, attachmentFiles) {
 
 export function workItemToolPolicySnapshot(workDir, attachmentRefs = [], extraToolNames = []) {
   const hasAttachments = attachmentRefs.length > 0;
-  const builtInTools = WORK_ITEM_TOOL_NAMES.filter(name => !hasAttachments || name !== 'Bash');
+  const builtInTools = workItemBuiltinToolNames(hasAttachments);
   return {
     policyVersion: 1,
     allowedToolNames: [...builtInTools, ...extraToolNames],
@@ -427,7 +415,7 @@ export function createSubmitWorkItemPlanTool({
       properties: {
         summary: { type: 'string', minLength: 1, maxLength: 2_000 },
         evidence: { type: 'array', minItems: 1, maxItems: 20, items: { type: 'string', minLength: 1, maxLength: 1_000 } },
-        acceptanceChecks: { type: 'array', items: { type: 'object', additionalProperties: false, required: ['criterion', 'status', 'evidence'], properties: { criterion: { type: 'string' }, status: { type: 'string', enum: ['passed', 'deferred', 'not_applicable'] }, evidence: { type: 'string', minLength: 1, maxLength: 1_000 } } } },
+        acceptanceChecks: { type: 'array', items: { type: 'object', additionalProperties: false, required: ['criterion', 'status', 'evidence'], properties: { criterion: { type: 'string' }, status: { type: 'string', enum: ['passed', 'failed', 'deferred', 'not_applicable'] }, evidence: { type: 'string', minLength: 1, maxLength: 1_000 } } } },
         contractPatch: { type: 'object', additionalProperties: false, required: ['title', 'goal', 'acceptanceCriteria'], properties: { title: { type: 'string', minLength: 1, maxLength: 200 }, goal: { type: 'string', minLength: 1, maxLength: 8_000 }, acceptanceCriteria: { type: 'array', minItems: 1, items: { type: 'string', minLength: 1, maxLength: 2_000 } } } },
         workItemType: { type: 'string', minLength: 1, maxLength: 64 },
         actions: { type: 'array', minItems: 1, maxItems: 8, items: { type: 'object', additionalProperties: false, required: ['id', 'name', 'type', 'objective', 'approach', 'expectedOutcome', 'candidateVpIds', 'assignmentReason', 'dependsOnActionIds', 'workspaceMode'], properties: {
@@ -483,7 +471,7 @@ function terminalPlanningFields(options = {}) {
   return {
     summary: { type: 'string', minLength: 1, maxLength: 2_000 },
     evidence: { type: 'array', minItems: 1, maxItems: 20, items: { type: 'string', minLength: 1, maxLength: 1_000 } },
-    acceptanceChecks: { type: 'array', items: { type: 'object', additionalProperties: false, required: ['criterion', 'status', 'evidence'], properties: { criterion: { type: 'string' }, status: { type: 'string', enum: ['passed', 'deferred', 'not_applicable'] }, evidence: { type: 'string', minLength: 1, maxLength: 1_000 } } } },
+    acceptanceChecks: { type: 'array', items: { type: 'object', additionalProperties: false, required: ['criterion', 'status', 'evidence'], properties: { criterion: { type: 'string' }, status: { type: 'string', enum: ['passed', 'failed', 'deferred', 'not_applicable'] }, evidence: { type: 'string', minLength: 1, maxLength: 1_000 } } } },
     ...(options.review === true ? {
       reviewDecision: { type: 'string', const: 'changes_requested' },
     } : {}),
@@ -748,7 +736,7 @@ function completionContract(action, workItem) {
       : '';
   const acceptanceChecks = (workItem?.acceptanceCriteria || []).map(criterion => ({
     criterion,
-    status: 'passed|deferred|not_applicable',
+    status: 'passed|failed|deferred|not_applicable',
     evidence: 'specific evidence reference',
   }));
   return `${toolSubmission}\n\nYou are executing one Work Center Action. Before the terminal JSON, write a concise user-facing response describing what you did and the result. Do not include raw tool output or secrets. End your response with exactly one JSON object, preferably in a json code fence:\n{
@@ -759,7 +747,7 @@ function completionContract(action, workItem) {
   "acceptanceChecks": ${JSON.stringify(acceptanceChecks)},
   "waitingReason": null,
   "error": null${reviewField}${triageField}${planField}
-}\nFor completed, provide at least one concrete evidence item and exactly one acceptanceChecks entry for every current acceptance criterion, in the same order, with status passed, deferred, or not_applicable and a non-empty evidence reference. Report every user-consumable file, URL, PR, or commit in outputs; evidence proves work, while outputs tell the user where the deliverable is. Triage must use its proposed criteria when submitting a contractPatch. An intermediate Action may defer criteria outside its task-specific expected result; the final deliver Action, and an approved review with no downstream work, require every criterion to pass. If a criterion is no longer applicable, ask the WorkItem Coordinator to revise the contract instead of pretending it passed. This is a deterministic submission gate, not independent proof: later verification and delivery Actions must verify the claims. A model turn ending is not completion. Use waiting when user or external input is required. Use retryable only for a transient failure. Do not start background jobs or delegate this Action.`;
+}\nFor completed, provide at least one concrete evidence item and exactly one acceptanceChecks entry for every current acceptance criterion, in the same order, with status passed, failed, deferred, or not_applicable and a non-empty evidence reference. Report every user-consumable file, URL, PR, or commit in outputs; evidence proves work, while outputs tell the user where the deliverable is. Triage must use its proposed criteria when submitting a contractPatch. An intermediate Action may defer criteria outside its task-specific expected result; the final deliver Action, and an approved review with no downstream work, require every criterion to pass. If a criterion is no longer applicable, request user confirmation of any contract change instead of pretending it passed. For response delivery, provide the user-facing conclusion in summary with concrete evidence; no artificial file or PR is required. This is a deterministic submission gate, not independent proof: later verification and delivery Actions must verify the claims. A model turn ending is not completion. Use waiting when user or external input is required. Use retryable only for a transient failure. Do not start background jobs or delegate this Action.`;
 }
 
 function safeCheckpointUrl(value) {
@@ -1163,6 +1151,7 @@ export class WorkItemRunner {
         )
       : null;
     const isRunActive = () => !signal.aborted
+      && !this.store.isExecutionStopped?.(workItem.id)
       && this.store.isActiveRun(run.id, ownerBootId, run.leaseEpoch);
     const workspaceRuntime = await this.#workspaceRuntime(workspaceDir, workDir, isRunActive);
     const mcpToolNames = workspaceRuntime.mcpTools.map(tool => tool.name);
@@ -1337,7 +1326,8 @@ export class WorkItemRunner {
       return onProgress(currentProgress());
     };
     if (typeof registerProgressReader === 'function') registerProgressReader(currentProgress);
-    const adapter = withUsageAccounting(runtime.adapter, usage => {
+    const adapter = withUsageAccounting(
+      new WorkCenterResourceAdapter(runtime.adapter, this.store, workItem.id, run.id), usage => {
       usageStats.inputTokens += usage.inputTokens;
       usageStats.outputTokens += usage.outputTokens;
       usageStats.cacheReadTokens += usage.cacheReadTokens;

package/yeaft/work-center/service.js

@@ -247,13 +247,16 @@ export class WorkCenterService {
             workItemId,
           });
           const shouldStart = payload.start === undefined ? settings.startImmediately : payload.start !== false;
+          const goal = requiredString(payload.goal, 'goal');
+          const requestedCriteria = Array.isArray(payload.acceptanceCriteria)
+            ? payload.acceptanceCriteria.map(value => String(value).trim()).filter(Boolean) : [];
           this.controller.create({
             id: workItemId,
             title: requiredString(payload.title, 'title'),
-            goal: requiredString(payload.goal, 'goal'),
-            acceptanceCriteria: Array.isArray(payload.acceptanceCriteria)
-              ? payload.acceptanceCriteria.map(value => String(value).trim()).filter(Boolean)
-              : [],
+            goal,
+            // With no separate criteria, the user's goal itself is the minimum
+            // contract. Do not force a follow-up or invent broader requirements.
+            acceptanceCriteria: requestedCriteria.length ? requestedCriteria : [goal],
             workflowTemplate,
             workflowSnapshot,
             coordinationMode: DYNAMIC_COORDINATION_MODE,
@@ -263,7 +266,7 @@ export class WorkCenterService {
             // browser/user request. Trusted model producers may provide
             // Session provenance, but cannot grant themselves delivery rights.
             deliveryTarget: requestContext.userOriginated === true
-              && ['workspace_files', 'pull_request', 'merge'].includes(payload.deliveryTarget)
+              && ['response', 'workspace_files', 'pull_request', 'merge'].includes(payload.deliveryTarget)
               ? payload.deliveryTarget : null,
             reuseMemory: payload.reuseMemory !== false,
             origin: payload.origin && typeof payload.origin === 'object'
@@ -320,9 +323,21 @@ export class WorkCenterService {
         this.#emit({ type: 'work_item.cancelled', workItem: detail });
         return detail;
       }
+      case 'extend_budget': {
+        if (requestContext.userOriginated !== true) throw new Error('Only explicit user requests can extend execution budget');
+        const id = requiredString(payload.id, 'id');
+        const detail = this.controller.extendBudget(id, payload);
+        this.#emit({ type: 'work_item.execution_budget_extended', workItem: detail });
+        return detail;
+      }
       case 'resume': {
+        if (requestContext.userOriginated !== true) throw new Error('Only explicit user requests can resume execution');
         const id = requiredString(payload.id, 'id');
-        const detail = this.controller.resume(id, { revision: payload.revision });
+        if (!Number.isSafeInteger(payload.executionControlRevision)) {
+          throw new Error('executionControlRevision is required to resume a WorkItem');
+        }
+        const detail = this.controller.resume(id, { revision: payload.revision,
+          executionControlRevision: payload.executionControlRevision });
         this.watcher.abortInvalidWorkItemRuns(id);
         if (detail.coordinationMode === DYNAMIC_COORDINATION_MODE) {
           this.#queueDynamicCoordinatorWake(id);
@@ -633,7 +648,8 @@ export class WorkCenterService {
     const entry = entries.find(candidate => candidate.payload?.turnId) || entries[0];
     if (!entry) return null;
     const detail = this.store.getWorkItemDetail(workItemId);
-    if (detail?.actions?.some(action => action.status === 'running')) return null;
+    if (!this.store.canAutomaticallyCoordinate(workItemId)
+        || detail?.actions?.some(action => action.status === 'running')) return null;
     let turn;
     try {
       turn = this.coordinator.advance(entry.id, {
@@ -673,6 +689,7 @@ export class WorkCenterService {
     this.store.recoverCoordinatorProviderTurns();
     this.store.recoverCoordinatorMailbox();
     for (const recoverable of this.store.getRecoverableCoordinatorTurns?.() || []) {
+      if (!this.store.canAutomaticallyCoordinate(recoverable.workItemId)) continue;
       const claim = this.store.claimCoordinatorTurn(
         recoverable.workItemId, recoverable.turnId, this.ownerBootId,
       );
@@ -717,6 +734,10 @@ export class WorkCenterService {
     let next = null;
     for (const [key, entry] of this.recoveryQueue) {
       const detail = this.store.getWorkItemDetail(entry.workItemId);
+      if (!this.store.canAutomaticallyCoordinate(entry.workItemId)) {
+        this.recoveryQueue.delete(key);
+        continue;
+      }
       const action = detail?.actions?.find(candidate => candidate.id === entry.actionId);
       if (!detail || ['done', 'cancelled'].includes(detail.status)
           || action?.status !== 'failed'