u-foo 3.0.0 → 3.0.2

package/src/code/protocol/protocolValidator.js

@@ -0,0 +1,165 @@
+"use strict";
+
+/**
+ * Protocol validator — fail-closed when STRICT; otherwise returns diagnostics.
+ *
+ * Before a Provider turn: every declared call must be resolved or legitimately
+ * deferred (ask_user). Declared/executing calls block the next turn.
+ */
+
+const {
+  listUnresolved,
+  listDeferred,
+  listCalls,
+  DEFERABLE_TOOLS,
+} = require("./toolCallLedger");
+
+/**
+ * @returns {{ ok: boolean, code?: string, errors: Array<{ code: string, message: string, callId?: string }> }}
+ */
+function assertReadyForProviderTurn(ledger = null) {
+  const errors = [];
+  if (!ledger) {
+    return { ok: true, errors: [], skipped: true };
+  }
+
+  const unresolved = listUnresolved(ledger);
+  for (const call of unresolved) {
+    errors.push({
+      code: "UNRESOLVED_TOOL_CALL",
+      message: `tool call ${call.callId} (${call.name}) is still ${call.state}`,
+      callId: call.callId,
+    });
+  }
+
+  const deferred = listDeferred(ledger);
+  for (const call of deferred) {
+    if (!DEFERABLE_TOOLS.has(call.name)) {
+      errors.push({
+        code: "INVALID_DEFER",
+        message: `tool call ${call.callId} (${call.name}) is deferred but not deferable`,
+        callId: call.callId,
+      });
+    }
+  }
+
+  // Session-level: deferred ask_user is a legal suspension — next Provider turn
+  // must not happen until resume resolves it. Treat deferred as blocking here.
+  for (const call of deferred) {
+    errors.push({
+      code: "DEFERRED_PENDING_RESUME",
+      message: `tool call ${call.callId} is deferred; resume before next provider turn`,
+      callId: call.callId,
+    });
+  }
+
+  if (errors.length > 0) {
+    return {
+      ok: false,
+      code: errors[0].code,
+      errors,
+    };
+  }
+  return { ok: true, errors: [] };
+}
+
+/**
+ * Validate that a batch of declared calls matches policy expectations.
+ * Used by tests / shadow diagnostics — does not mutate messages.
+ */
+function validateDeclaredBatch(ledger = null, {
+  requireAskUserAlone = true,
+  rejectPlanWithData = true,
+  dataPlaneTools = null,
+} = {}) {
+  const errors = [];
+  const calls = listCalls(ledger);
+  if (calls.length === 0) return { ok: true, errors: [] };
+
+  const names = calls.map((c) => c.name);
+  const hasAskUser = names.includes("ask_user");
+  const hasControlPlane = names.includes("plan_graph") || names.includes("task_run");
+  const dataSet = dataPlaneTools instanceof Set
+    ? dataPlaneTools
+    : new Set(["read", "write", "edit", "bash", "artifact_read"]);
+  const hasData = names.some((name) => dataSet.has(name));
+
+  if (requireAskUserAlone && hasAskUser && calls.length > 1) {
+    errors.push({
+      code: "ASK_USER_MUST_BE_ALONE",
+      message: "ask_user must be the only tool call in the turn",
+    });
+  }
+  if (rejectPlanWithData && hasControlPlane && hasData) {
+    errors.push({
+      code: "MIXED_PLAN_AND_DATA_TOOLS",
+      message: "Do not mix plan_graph/task_run with data-plane tools in the same turn",
+    });
+  }
+
+  return {
+    ok: errors.length === 0,
+    code: errors[0] ? errors[0].code : undefined,
+    errors,
+  };
+}
+
+/**
+ * Env: UFOO_UCODE_PROTOCOL_STRICT
+ * - unset / "1" → fail-closed (Phase 1 default)
+ * - "0" → shadow diagnose only (rollback)
+ * Owner: runtime. Remove after R1 materialize is proven stable.
+ */
+function isProtocolStrictEnabled(env = process.env) {
+  const raw = String(env && env.UFOO_UCODE_PROTOCOL_STRICT || "").trim();
+  if (raw === "0" || raw.toLowerCase() === "false" || raw.toLowerCase() === "off") {
+    return false;
+  }
+  return true;
+}
+
+/**
+ * Run validator; in shadow mode record violations on ledger, optionally throw.
+ * @returns {{ ok: boolean, errors: object[], threw: boolean }}
+ */
+function runProviderTurnGate(ledger, {
+  strict = null,
+  onViolation = null,
+} = {}) {
+  const result = assertReadyForProviderTurn(ledger);
+  if (result.ok || result.skipped) {
+    return { ok: true, errors: [], threw: false };
+  }
+
+  if (typeof onViolation === "function") {
+    try {
+      onViolation(result);
+    } catch {
+      // ignore observer errors
+    }
+  }
+
+  const { recordViolation } = require("./toolCallLedger");
+  for (const err of result.errors) {
+    recordViolation(ledger, err);
+  }
+
+  const shouldStrict = strict == null ? isProtocolStrictEnabled() : Boolean(strict);
+  if (shouldStrict) {
+    const err = new Error(
+      `protocol validator failed: ${result.errors.map((e) => e.code).join(", ")}`
+    );
+    err.code = result.code || "PROTOCOL_VIOLATION";
+    err.protocolErrors = result.errors;
+    throw err;
+  }
+
+  return { ok: false, errors: result.errors, threw: false };
+}
+
+module.exports = {
+  assertReadyForProviderTurn,
+  validateDeclaredBatch,
+  isProtocolStrictEnabled,
+  runProviderTurnGate,
+};

package/src/code/protocol/suspension.js

@@ -0,0 +1,173 @@
+"use strict";
+
+/**
+ * Unified suspension / resume entry for ask_user and plan checkpoints.
+ *
+ * UI clients (Ink, readline) should call submitUserInteractionAnswer instead of
+ * parsing answers and appending tool results themselves.
+ *
+ * Lifecycle: running → suspending → suspended → resuming → running | failed
+ */
+
+const {
+  hasPendingUserInteraction,
+  getPendingUserInteraction,
+  parseUserInteractionInput,
+} = require("../context/userInteraction");
+
+const INTERACTION_EVENTS = Object.freeze([
+  "interaction_requested",
+  "interaction_rejected",
+  "interaction_resuming",
+  "assistant_delta",
+  "interaction_resolved",
+  "interaction_failed",
+]);
+
+function emit(onEvent, type, payload = {}) {
+  if (typeof onEvent !== "function") return;
+  try {
+    onEvent({ type, ...payload, timestamp: new Date().toISOString() });
+  } catch {
+    // UI observer errors must not alter protocol state.
+  }
+}
+
+/**
+ * Application-layer answer submission shared by Ink and readline.
+ *
+ * @returns {Promise<object>} normalized resume result + display hints
+ */
+async function submitUserInteractionAnswer(answerText = "", state = {}, options = {}) {
+  const onEvent = typeof options.onEvent === "function" ? options.onEvent : null;
+  const text = String(answerText == null ? "" : answerText);
+  const trimmed = text.trim();
+
+  if (!state || typeof state !== "object") {
+    emit(onEvent, "interaction_failed", { error: "missing session state" });
+    return {
+      ok: false,
+      code: "MISSING_STATE",
+      error: "missing session state",
+      waitingUserInteraction: false,
+      shouldEchoSummary: false,
+      events: ["interaction_failed"],
+    };
+  }
+
+  if (!hasPendingUserInteraction(state.executionState)) {
+    emit(onEvent, "interaction_rejected", { code: "NO_PENDING_INTERACTION" });
+    return {
+      ok: true,
+      idempotent: true,
+      code: "ALREADY_RESOLVED",
+      error: "",
+      summary: "",
+      waitingUserInteraction: false,
+      shouldEchoSummary: false,
+      events: ["interaction_rejected"],
+    };
+  }
+
+  // Slash commands while suspended: defined behavior — reject (except empty).
+  if (/^\//.test(trimmed) && !/^\/(exit|quit)\b/i.test(trimmed)) {
+    const error = "Answer the pending question first (slash commands are paused while waiting)";
+    emit(onEvent, "interaction_rejected", { code: "SUSPENDED_BLOCKS_SLASH", error });
+    return {
+      ok: false,
+      code: "SUSPENDED_BLOCKS_SLASH",
+      error,
+      waitingUserInteraction: true,
+      shouldEchoSummary: false,
+      events: ["interaction_rejected"],
+    };
+  }
+
+  const pending = getPendingUserInteraction(state.executionState);
+  const parsed = parseUserInteractionInput(pending, trimmed);
+  if (!parsed.ok) {
+    emit(onEvent, "interaction_rejected", {
+      code: parsed.code || "INVALID_ANSWER",
+      error: parsed.error || "Invalid reply",
+    });
+    return {
+      ok: false,
+      code: parsed.code || "INVALID_ANSWER",
+      error: parsed.error || "Invalid reply",
+      waitingUserInteraction: true,
+      shouldEchoSummary: false,
+      events: ["interaction_rejected"],
+    };
+  }
+
+  emit(onEvent, "interaction_resuming", {
+    interactionId: pending && pending.id ? pending.id : "",
+    kind: pending && pending.kind ? pending.kind : "",
+  });
+
+  const { resumeAfterUserInteraction } = require("../agent");
+  let sawStreamText = false;
+  const userOnDelta = typeof options.onDelta === "function" ? options.onDelta : null;
+  const result = await resumeAfterUserInteraction(trimmed, state, {
+    ...options,
+    onDelta: (delta) => {
+      const chunk = String(delta || "");
+      if (chunk && /[^\s]/.test(chunk)) sawStreamText = true;
+      emit(onEvent, "assistant_delta", { text: chunk });
+      if (userOnDelta) return userOnDelta(delta);
+      return undefined;
+    },
+  });
+
+  if (!result || result.ok === false) {
+    emit(onEvent, "interaction_failed", {
+      error: (result && result.error) || "resume failed",
+      code: (result && result.code) || "",
+    });
+    return {
+      ...(result || {}),
+      ok: false,
+      error: (result && result.error) || "resume failed",
+      shouldEchoSummary: false,
+      events: ["interaction_resuming", "interaction_failed"],
+    };
+  }
+
+  if (result.waitingUserInteraction) {
+    emit(onEvent, "interaction_requested", {
+      interactionId: result.interactionId || "",
+    });
+    return {
+      ...result,
+      shouldEchoSummary: true,
+      echoSummaryText: "Still waiting for your reply.",
+      events: ["interaction_resuming", "interaction_requested"],
+    };
+  }
+
+  emit(onEvent, "interaction_resolved", {
+    interactionId: (pending && pending.id) || "",
+    streamed: Boolean(result.streamed),
+  });
+
+  const streamedVisible = Boolean(result.streamed && (sawStreamText || options.streamVisible));
+  const { resolveSummaryDisplayPolicy } = require("./loopEvents");
+  const display = resolveSummaryDisplayPolicy({
+    streamed: Boolean(result.streamed),
+    sawVisibleText: streamedVisible,
+  });
+  return {
+    ...result,
+    shouldEchoSummary: Boolean(result.summary) && display.echoSummary,
+    echoSummaryText: result.summary || "",
+    displayPolicy: display,
+    events: ["interaction_resuming", "assistant_delta", "interaction_resolved"].filter(
+      (name, index, all) => all.indexOf(name) === index
+    ),
+  };
+}
+
+module.exports = {
+  INTERACTION_EVENTS,
+  submitUserInteractionAnswer,
+};

package/src/code/protocol/toolCallLedger.js

@@ -0,0 +1,222 @@
+"use strict";
+
+/**
+ * Tool Call Ledger — authoritative record of declared tool calls for a turn.
+ *
+ * Shadow mode (Phase 0 / R1): ledger tracks declare/defer/resolve alongside the
+ * existing TRANSPORTS message assembly. Materialize-from-ledger comes later.
+ *
+ * Call states: declared | executing | deferred | resolved
+ */
+
+const { createHash, randomUUID } = require("crypto");
+
+const CALL_STATES = Object.freeze(["declared", "executing", "deferred", "resolved"]);
+const DEFERABLE_TOOLS = Object.freeze(new Set(["ask_user"]));
+
+function digestValue(value) {
+  const raw = typeof value === "string" ? value : stableStringify(value);
+  return createHash("sha256").update(raw).digest("hex").slice(0, 16);
+}
+
+function stableStringify(value) {
+  if (value == null) return "null";
+  if (typeof value !== "object") return JSON.stringify(value);
+  if (Array.isArray(value)) {
+    return `[${value.map((entry) => stableStringify(entry)).join(",")}]`;
+  }
+  const keys = Object.keys(value).sort();
+  return `{${keys.map((key) => `${JSON.stringify(key)}:${stableStringify(value[key])}`).join(",")}}`;
+}
+
+function createTurnId() {
+  return `turn_${Date.now().toString(36)}_${randomUUID().slice(0, 8)}`;
+}
+
+/**
+ * @param {{ provider?: string, sessionId?: string, turnId?: string, assistantMessageId?: string }} opts
+ */
+function createToolCallLedger(opts = {}) {
+  return {
+    turnId: String(opts.turnId || createTurnId()),
+    provider: String(opts.provider || "").trim(),
+    sessionId: String(opts.sessionId || "").trim(),
+    assistantMessageId: String(opts.assistantMessageId || "").trim(),
+    calls: Object.create(null),
+    violations: [],
+    createdAt: new Date().toISOString(),
+  };
+}
+
+function getCall(ledger, callId) {
+  if (!ledger || !ledger.calls) return null;
+  const id = String(callId || "").trim();
+  return id && ledger.calls[id] ? ledger.calls[id] : null;
+}
+
+function listCalls(ledger) {
+  if (!ledger || !ledger.calls) return [];
+  return Object.keys(ledger.calls).map((id) => ledger.calls[id]);
+}
+
+function listUnresolved(ledger) {
+  return listCalls(ledger).filter((call) => (
+    call.state === "declared" || call.state === "executing"
+  ));
+}
+
+function listDeferred(ledger) {
+  return listCalls(ledger).filter((call) => call.state === "deferred");
+}
+
+/**
+ * Declare one or more tool calls after prepareToolCalls.
+ * @param {object} ledger
+ * @param {Array<{ callId: string, name: string, args?: object }>} calls
+ */
+function declareCalls(ledger, calls = []) {
+  if (!ledger || !ledger.calls) {
+    return { ok: false, error: "missing ledger" };
+  }
+  const list = Array.isArray(calls) ? calls : [];
+  for (const entry of list) {
+    const callId = String(entry && entry.callId || "").trim();
+    if (!callId) {
+      return { ok: false, error: "callId required" };
+    }
+    if (ledger.calls[callId]) {
+      return { ok: false, error: `duplicate callId: ${callId}`, code: "DUPLICATE_CALL_ID" };
+    }
+    const name = String(entry.name || "").trim().toLowerCase();
+    ledger.calls[callId] = {
+      callId,
+      name,
+      argsDigest: digestValue(entry.args == null ? {} : entry.args),
+      state: "declared",
+      resultDigest: "",
+      isError: false,
+      resolvedAt: "",
+      deferredAt: "",
+      executingAt: "",
+    };
+  }
+  if (!ledger.assistantMessageId && list.length > 0) {
+    ledger.assistantMessageId = String(list[0].callId || "");
+  }
+  return { ok: true, count: list.length };
+}
+
+function markExecuting(ledger, callId) {
+  const call = getCall(ledger, callId);
+  if (!call) return { ok: false, error: "call not found", code: "CALL_NOT_FOUND" };
+  if (call.state !== "declared") {
+    return { ok: false, error: `cannot execute from ${call.state}`, code: "INVALID_STATE" };
+  }
+  call.state = "executing";
+  call.executingAt = new Date().toISOString();
+  return { ok: true, call };
+}
+
+/**
+ * Defer a call (ask_user only). Leaves assistant tool_call unpaired until resume.
+ */
+function deferCall(ledger, callId, { reason = "" } = {}) {
+  const call = getCall(ledger, callId);
+  if (!call) return { ok: false, error: "call not found", code: "CALL_NOT_FOUND" };
+  if (call.state !== "declared" && call.state !== "executing") {
+    return { ok: false, error: `cannot defer from ${call.state}`, code: "INVALID_STATE" };
+  }
+  if (!DEFERABLE_TOOLS.has(call.name)) {
+    return {
+      ok: false,
+      error: `tool ${call.name} cannot be deferred`,
+      code: "NOT_DEFERABLE",
+    };
+  }
+  call.state = "deferred";
+  call.deferredAt = new Date().toISOString();
+  call.deferReason = String(reason || "").trim();
+  return { ok: true, call };
+}
+
+/**
+ * Resolve a declared/executing/deferred call with exactly one result.
+ * Idempotent when resultDigest matches a prior resolve.
+ */
+function resolveCall(ledger, callId, {
+  result = null,
+  isError = false,
+  allowFromDeferred = true,
+} = {}) {
+  const call = getCall(ledger, callId);
+  if (!call) return { ok: false, error: "call not found", code: "CALL_NOT_FOUND" };
+
+  const resultDigest = digestValue(result);
+  if (call.state === "resolved") {
+    if (call.resultDigest === resultDigest) {
+      return { ok: true, call, idempotent: true };
+    }
+    return {
+      ok: false,
+      error: "call already resolved with different result",
+      code: "DUPLICATE_RESOLVE",
+      call,
+    };
+  }
+
+  if (call.state === "deferred" && !allowFromDeferred) {
+    return { ok: false, error: "call is deferred", code: "STILL_DEFERRED", call };
+  }
+  if (call.state !== "declared" && call.state !== "executing" && call.state !== "deferred") {
+    return { ok: false, error: `cannot resolve from ${call.state}`, code: "INVALID_STATE", call };
+  }
+
+  call.state = "resolved";
+  call.resultDigest = resultDigest;
+  call.resultPayload = result;
+  call.isError = Boolean(isError);
+  call.resolvedAt = new Date().toISOString();
+  return { ok: true, call, idempotent: false };
+}
+
+function recordViolation(ledger, violation = {}) {
+  if (!ledger) return;
+  if (!Array.isArray(ledger.violations)) ledger.violations = [];
+  ledger.violations.push({
+    code: String(violation.code || "PROTOCOL_VIOLATION"),
+    message: String(violation.message || ""),
+    callId: String(violation.callId || ""),
+    at: new Date().toISOString(),
+  });
+}
+
+function snapshotLedger(ledger) {
+  if (!ledger) return null;
+  return JSON.parse(JSON.stringify({
+    turnId: ledger.turnId,
+    provider: ledger.provider,
+    sessionId: ledger.sessionId,
+    assistantMessageId: ledger.assistantMessageId,
+    calls: ledger.calls,
+    violations: ledger.violations || [],
+    createdAt: ledger.createdAt,
+  }));
+}
+
+module.exports = {
+  CALL_STATES,
+  DEFERABLE_TOOLS,
+  digestValue,
+  createTurnId,
+  createToolCallLedger,
+  getCall,
+  listCalls,
+  listUnresolved,
+  listDeferred,
+  declareCalls,
+  markExecuting,
+  deferCall,
+  resolveCall,
+  recordViolation,
+  snapshotLedger,
+};

package/src/code/protocol/transitions.js

@@ -0,0 +1,97 @@
+"use strict";
+
+/**
+ * Current-state transition tables for Plan Mode and TaskRun (Phase 0).
+ *
+ * Documents *as-implemented* rules. R5 dual-writes planningPolicy alongside
+ * planMode; executionOwner is orthogonal to planningPolicy.
+ *
+ * NOTE: Status enums are duplicated in runtime/taskRun.js on purpose to avoid
+ * a require cycle (taskRun must not import this module).
+ */
+
+/** Mirror of runtime/taskRun TASK_RUN_STATUSES (keep in sync). */
+const TASK_RUN_STATUSES = Object.freeze([
+  "queued",
+  "running",
+  "cancelling",
+  "succeeded",
+  "failed",
+  "cancelled",
+]);
+
+const TERMINAL_TASK_RUN = new Set(["succeeded", "failed", "cancelled"]);
+
+/** Allowed TaskRun status edges (from → to[]). Terminal states have no outbound edges. */
+const TASK_RUN_TRANSITIONS = Object.freeze({
+  queued: Object.freeze(["running", "cancelled"]),
+  running: Object.freeze(["succeeded", "failed", "cancelling"]),
+  cancelling: Object.freeze(["cancelled", "failed"]),
+  succeeded: Object.freeze([]),
+  failed: Object.freeze([]),
+  cancelled: Object.freeze([]),
+});
+
+/**
+ * Plan Mode is a session posture boolean today.
+ * Combinations with TaskRun are orthogonal: /plan off does not cancel TaskRuns.
+ */
+const PLAN_MODE_FACTS = Object.freeze({
+  /** /plan on | auto after plan_graph create */
+  enterSources: Object.freeze(["user", "auto"]),
+  /** /plan off clears planMode; does not cancel graph or TaskRun */
+  exitClearsGraph: false,
+  exitCancelsTaskRun: false,
+  /** When planMode=true, side-effect direct tools may be blocked at runtime */
+  blocksDirectSideEffectsWhenOn: true,
+  /** Active plan waiting on a task can block data-plane tools even if policy differs later */
+  activePlanMayBlockDataTools: true,
+  /** TaskRun may continue after planMode is turned off */
+  taskRunSurvivesPlanOff: true,
+});
+
+/**
+ * Forward-looking orthognal fields (not yet stored on executionState).
+ * Mapped conceptually for R5 migration tests.
+ */
+const FUTURE_POLICY_OWNER = Object.freeze({
+  planningPolicy: Object.freeze(["direct_allowed", "graph_required"]),
+  executionOwnerKinds: Object.freeze(["none", "agent_loop", "task_run"]),
+  mapPlanModeOn: Object.freeze({ planningPolicy: "graph_required" }),
+  mapPlanModeOff: Object.freeze({ planningPolicy: "direct_allowed" }),
+});
+
+function isAllowedTaskRunTransition(fromStatus = "", toStatus = "") {
+  const from = String(fromStatus || "").trim();
+  const to = String(toStatus || "").trim();
+  const allowed = TASK_RUN_TRANSITIONS[from];
+  if (!allowed) return false;
+  return allowed.includes(to);
+}
+
+function assertTransitionTables() {
+  for (const status of TASK_RUN_STATUSES) {
+    if (!Object.prototype.hasOwnProperty.call(TASK_RUN_TRANSITIONS, status)) {
+      throw new Error(`missing TASK_RUN_TRANSITIONS for ${status}`);
+    }
+  }
+  for (const [from, tos] of Object.entries(TASK_RUN_TRANSITIONS)) {
+    if (TERMINAL_TASK_RUN.has(from) && tos.length !== 0) {
+      throw new Error(`terminal status ${from} must have empty outbound edges`);
+    }
+    for (const to of tos) {
+      if (!TASK_RUN_STATUSES.includes(to)) {
+        throw new Error(`invalid transition ${from} → ${to}`);
+      }
+    }
+  }
+  return true;
+}
+
+module.exports = {
+  TASK_RUN_TRANSITIONS,
+  PLAN_MODE_FACTS,
+  FUTURE_POLICY_OWNER,
+  isAllowedTaskRunTransition,
+  assertTransitionTables,
+};