u-foo 3.0.0 → 3.0.2

package/src/code/protocol/controlPlane.js

@@ -0,0 +1,93 @@
+"use strict";
+
+/**
+ * Orthogonal control-plane fields (R5).
+ *
+ * planningPolicy: whether direct side-effect tools are allowed without a graph.
+ * executionOwner: who currently owns workspace / loop advancement.
+ *
+ * Dual-write with legacy planMode boolean during migration.
+ */
+
+const PLANNING_POLICIES = Object.freeze(["direct_allowed", "graph_required"]);
+
+function emptyExecutionOwner() {
+  return { kind: "none", id: "" };
+}
+
+function normalizePlanningPolicy(value = "") {
+  const raw = String(value || "").trim().toLowerCase();
+  if (PLANNING_POLICIES.includes(raw)) return raw;
+  return "";
+}
+
+function normalizeExecutionOwner(owner = null) {
+  if (!owner || typeof owner !== "object") return emptyExecutionOwner();
+  const kind = String(owner.kind || "none").trim().toLowerCase();
+  if (kind === "agent_loop" || kind === "task_run") {
+    return {
+      kind,
+      id: String(owner.id || owner.taskRunId || owner.agentLoopId || "").trim(),
+    };
+  }
+  return emptyExecutionOwner();
+}
+
+/**
+ * Sync planningPolicy ↔ planMode. Prefer explicit planningPolicy when present.
+ */
+function syncPlanningFields(executionState = null) {
+  const state = executionState && typeof executionState === "object" ? executionState : {};
+  const explicit = normalizePlanningPolicy(state.planningPolicy);
+  if (explicit) {
+    state.planningPolicy = explicit;
+    state.planMode = explicit === "graph_required";
+  } else if (state.planMode === true) {
+    state.planningPolicy = "graph_required";
+  } else {
+    state.planningPolicy = "direct_allowed";
+    state.planMode = false;
+  }
+  state.executionOwner = normalizeExecutionOwner(state.executionOwner);
+  return state;
+}
+
+function setPlanningPolicy(executionState = null, policy = "direct_allowed", {
+  reason = "",
+  source = "",
+} = {}) {
+  const state = syncPlanningFields(executionState);
+  const next = normalizePlanningPolicy(policy) || "direct_allowed";
+  state.planningPolicy = next;
+  // Dual-write legacy bool
+  const { setPlanMode } = require("../context/planMode");
+  setPlanMode(state, next === "graph_required", { reason, source });
+  state.planningPolicy = next;
+  return state;
+}
+
+function getPlanningPolicy(executionState = null) {
+  return syncPlanningFields(executionState).planningPolicy;
+}
+
+function setExecutionOwner(executionState = null, owner = null) {
+  const state = syncPlanningFields(executionState);
+  state.executionOwner = normalizeExecutionOwner(owner);
+  return state.executionOwner;
+}
+
+function getExecutionOwner(executionState = null) {
+  return syncPlanningFields(executionState).executionOwner;
+}
+
+module.exports = {
+  PLANNING_POLICIES,
+  emptyExecutionOwner,
+  normalizePlanningPolicy,
+  normalizeExecutionOwner,
+  syncPlanningFields,
+  setPlanningPolicy,
+  getPlanningPolicy,
+  setExecutionOwner,
+  getExecutionOwner,
+};

package/src/code/protocol/faultHarness.js

@@ -0,0 +1,90 @@
+"use strict";
+
+/**
+ * Minimal fault-injection harness for crash/restart tests (Phase 0 skeleton).
+ *
+ * Usage:
+ *   armFault("after_prepare_tool_calls");
+ *   await withFaultPoint("after_prepare_tool_calls", async () => { ... });
+ *
+ * Armed points throw FaultInjectedError once (or until disarmed).
+ */
+
+const armed = new Map();
+
+class FaultInjectedError extends Error {
+  constructor(point = "") {
+    super(`fault injected at ${point}`);
+    this.name = "FaultInjectedError";
+    this.code = "FAULT_INJECTED";
+    this.point = String(point || "");
+  }
+}
+
+/** Known hook names reserved for native loop / resume (R4 expands coverage). */
+const FAULT_POINTS = Object.freeze([
+  "after_prepare_tool_calls",
+  "before_tool_exec",
+  "after_tool_effect",
+  "before_result_commit",
+  "after_answer_commit",
+  "before_provider_resume",
+  "after_taskrun_acquire_lease",
+  "before_parent_node_sync",
+]);
+
+function armFault(point = "", { times = 1, error = null } = {}) {
+  const name = String(point || "").trim();
+  if (!name) throw new Error("fault point name required");
+  armed.set(name, {
+    remaining: Math.max(1, Math.floor(Number(times) || 1)),
+    error: error || null,
+  });
+  return name;
+}
+
+function disarmFault(point = "") {
+  const name = String(point || "").trim();
+  if (!name) {
+    armed.clear();
+    return;
+  }
+  armed.delete(name);
+}
+
+function isFaultArmed(point = "") {
+  return armed.has(String(point || "").trim());
+}
+
+function checkFaultPoint(point = "") {
+  const name = String(point || "").trim();
+  const entry = armed.get(name);
+  if (!entry) return;
+  entry.remaining -= 1;
+  if (entry.remaining <= 0) armed.delete(name);
+  if (entry.error) throw entry.error;
+  throw new FaultInjectedError(name);
+}
+
+/**
+ * Run fn; if point is armed, throw before invoking fn.
+ */
+async function withFaultPoint(point = "", fn) {
+  checkFaultPoint(point);
+  return typeof fn === "function" ? fn() : undefined;
+}
+
+function listArmedFaults() {
+  return Array.from(armed.keys());
+}
+
+module.exports = {
+  FAULT_POINTS,
+  FaultInjectedError,
+  armFault,
+  disarmFault,
+  isFaultArmed,
+  checkFaultPoint,
+  withFaultPoint,
+  listArmedFaults,
+};

package/src/code/protocol/index.js

@@ -0,0 +1,20 @@
+"use strict";
+
+/**
+ * Protocol layer — Tool Call Ledger, validator, ownership, transitions, fault harness.
+ *
+ * Phase 0 / R1 shadow: observe and validate; do not yet own Provider wire messages.
+ */
+
+module.exports = {
+  ...require("./toolCallLedger"),
+  ...require("./protocolValidator"),
+  ...require("./ownership"),
+  ...require("./transitions"),
+  ...require("./faultHarness"),
+  ...require("./messageFixtures"),
+  ...require("./materialize"),
+  ...require("./suspension"),
+  ...require("./controlPlane"),
+  ...require("./loopEvents"),
+};

package/src/code/protocol/loopEvents.js

@@ -0,0 +1,102 @@
+"use strict";
+
+/**
+ * Ordered Agent Loop events for UI clients (R8).
+ * Distinct from runtime/runtimeEvents.js (TaskRun wakeup mail).
+ */
+
+const LOOP_EVENT_TYPES = Object.freeze([
+  "thinking_delta",
+  "assistant_delta",
+  "tool_start",
+  "tool_result",
+  "artifact_persisted",
+  "interaction_requested",
+  "interaction_rejected",
+  "interaction_resuming",
+  "interaction_resolved",
+  "interaction_failed",
+  "plan_transition",
+  "task_run_transition",
+  "final_assistant_message",
+  "final_summary",
+  "error",
+]);
+
+function createLoopEvent(type = "", payload = {}, {
+  sessionId = "",
+  runId = "",
+  sequence = 0,
+  eventId = "",
+} = {}) {
+  const eventType = String(type || "").trim();
+  if (!LOOP_EVENT_TYPES.includes(eventType)) {
+    throw new Error(`unknown loop event type: ${type}`);
+  }
+  return {
+    eventId: String(eventId || `le_${Date.now().toString(36)}_${sequence}`),
+    sequence: Number(sequence) || 0,
+    sessionId: String(sessionId || ""),
+    runId: String(runId || ""),
+    type: eventType,
+    payload: payload && typeof payload === "object" ? payload : {},
+    timestamp: new Date().toISOString(),
+  };
+}
+
+/**
+ * UI display policy: whether to echo a final summary after streaming.
+ * Prefer final_summary / final_assistant_message events when present.
+ */
+function resolveSummaryDisplayPolicy({
+  streamed = false,
+  sawVisibleText = false,
+  finalEventType = "",
+} = {}) {
+  const finalType = String(finalEventType || "").trim();
+  if (finalType === "final_assistant_message" || finalType === "final_summary") {
+    return { echoSummary: true, reason: "explicit_final_event" };
+  }
+  if (streamed && sawVisibleText) {
+    return { echoSummary: false, reason: "already_streamed" };
+  }
+  return { echoSummary: true, reason: "fallback_summary" };
+}
+
+function createLoopEventLog({ sessionId = "", runId = "" } = {}) {
+  const events = [];
+  let sequence = 0;
+  const seen = new Set();
+
+  function push(type, payload = {}) {
+    sequence += 1;
+    const event = createLoopEvent(type, payload, {
+      sessionId,
+      runId,
+      sequence,
+    });
+    if (seen.has(event.eventId)) return null;
+    seen.add(event.eventId);
+    events.push(event);
+    return event;
+  }
+
+  function replayFrom(sequenceCheckpoint = 0) {
+    const min = Number(sequenceCheckpoint) || 0;
+    return events.filter((e) => e.sequence > min);
+  }
+
+  return {
+    push,
+    replayFrom,
+    list: () => events.slice(),
+    get sequence() { return sequence; },
+  };
+}
+
+module.exports = {
+  LOOP_EVENT_TYPES,
+  createLoopEvent,
+  createLoopEventLog,
+  resolveSummaryDisplayPolicy,
+};

package/src/code/protocol/materialize.js

@@ -0,0 +1,107 @@
+"use strict";
+
+/**
+ * Materialize Provider tool-result messages from a resolved ledger turn.
+ * Business branches must resolve on the ledger; they must not hand-write
+ * unpaired tool results.
+ */
+
+const { listCalls } = require("./toolCallLedger");
+
+/**
+ * Clip helper kept local so protocol does not depend on nativeRunner.
+ */
+function clipText(value = "", maxChars = 12000) {
+  const text = String(value == null ? "" : value);
+  if (text.length <= maxChars) return text;
+  return `${text.slice(0, maxChars)}\n...[truncated ${text.length - maxChars} chars]`;
+}
+
+function toJsonString(value) {
+  try {
+    return JSON.stringify(value);
+  } catch {
+    return String(value);
+  }
+}
+
+/**
+ * @param {object} ledger
+ * @param {{
+ *   transport: object,
+ *   messages: object[],
+ *   pendingById: Record<string, object>,
+ * }} opts
+ * @returns {{ appended: number, flushed: boolean }}
+ */
+function materializeResolvedToolResults(ledger, {
+  transport = null,
+  messages = [],
+  pendingById = {},
+} = {}) {
+  if (!ledger || !transport || typeof transport.appendToolResult !== "function") {
+    return { appended: 0, flushed: false };
+  }
+
+  const collected = [];
+  let appended = 0;
+  for (const call of listCalls(ledger)) {
+    if (call.state !== "resolved") continue;
+    const pending = pendingById[call.callId];
+    if (!pending) continue;
+    transport.appendToolResult({
+      messages,
+      collected,
+      call: pending,
+      toolResult: call.resultPayload,
+    });
+    appended += 1;
+  }
+
+  let flushed = false;
+  if (
+    collected.length > 0
+    && typeof transport.flushToolResults === "function"
+  ) {
+    transport.flushToolResults({ messages, collected });
+    flushed = true;
+  }
+  return { appended, flushed };
+}
+
+/**
+ * Append a single resume answer as a tool result (idempotent via ledger resolve).
+ */
+function materializeAnswerToolResult(messages = [], resume = null, answer = {}, {
+  clip = clipText,
+} = {}) {
+  const call = resume && resume.call ? resume.call : null;
+  if (!call || !call.source) return { ok: false, error: "missing deferred tool call" };
+  const transportName = String(resume.transport || "openai-chat");
+  const content = clip(toJsonString(answer), 12000);
+  if (transportName === "anthropic-messages") {
+    messages.push({
+      role: "user",
+      content: [{
+        type: "tool_result",
+        tool_use_id: String(call.source.id || resume.toolCallId || ""),
+        content,
+        is_error: false,
+      }],
+    });
+  } else {
+    messages.push({
+      role: "tool",
+      tool_call_id: String(call.source.id || resume.toolCallId || ""),
+      content,
+    });
+  }
+  return { ok: true };
+}
+
+module.exports = {
+  materializeResolvedToolResults,
+  materializeAnswerToolResult,
+  clipText,
+  toJsonString,
+};

package/src/code/protocol/messageFixtures.js

@@ -0,0 +1,116 @@
+"use strict";
+
+/**
+ * Golden / expected Provider message sequences derived from ledger call records.
+ * Used for fixture tests only — does not replace TRANSPORTS materialization (yet).
+ */
+
+function materializeOpenAiMessages({
+  assistantText = null,
+  calls = [],
+  results = [],
+} = {}) {
+  const messages = [];
+  const toolCalls = calls.map((call) => ({
+    id: call.callId,
+    type: "function",
+    function: {
+      name: call.name,
+      arguments: typeof call.argsJson === "string"
+        ? call.argsJson
+        : JSON.stringify(call.args == null ? {} : call.args),
+    },
+  }));
+
+  if (toolCalls.length > 0) {
+    messages.push({
+      role: "assistant",
+      content: assistantText,
+      tool_calls: toolCalls,
+    });
+  } else if (assistantText != null) {
+    messages.push({ role: "assistant", content: assistantText });
+  }
+
+  for (const result of results) {
+    messages.push({
+      role: "tool",
+      tool_call_id: result.callId,
+      content: typeof result.content === "string"
+        ? result.content
+        : JSON.stringify(result.content == null ? {} : result.content),
+    });
+  }
+  return messages;
+}
+
+function materializeAnthropicMessages({
+  assistantBlocks = null,
+  calls = [],
+  results = [],
+  assistantText = "",
+} = {}) {
+  const messages = [];
+  let content = Array.isArray(assistantBlocks) ? assistantBlocks.slice() : null;
+  if (!content) {
+    content = [];
+    if (assistantText) {
+      content.push({ type: "text", text: String(assistantText) });
+    }
+    for (const call of calls) {
+      content.push({
+        type: "tool_use",
+        id: call.callId,
+        name: call.name,
+        input: call.args == null ? {} : call.args,
+      });
+    }
+  }
+  if (content.length > 0) {
+    messages.push({ role: "assistant", content });
+  }
+
+  if (results.length > 0) {
+    messages.push({
+      role: "user",
+      content: results.map((result) => ({
+        type: "tool_result",
+        tool_use_id: result.callId,
+        content: typeof result.content === "string"
+          ? result.content
+          : JSON.stringify(result.content == null ? {} : result.content),
+        is_error: Boolean(result.isError),
+      })),
+    });
+  }
+  return messages;
+}
+
+/**
+ * Build expected messages from a simplified fixture definition.
+ * @param {{ provider: string, calls: object[], results?: object[], assistantText?: string }} def
+ */
+function materializeFromFixtureDef(def = {}) {
+  const provider = String(def.provider || "openai").toLowerCase();
+  const calls = Array.isArray(def.calls) ? def.calls : [];
+  const results = Array.isArray(def.results) ? def.results : [];
+  if (provider === "anthropic" || provider === "anthropic-messages") {
+    return materializeAnthropicMessages({
+      calls,
+      results,
+      assistantText: def.assistantText || "",
+      assistantBlocks: def.assistantBlocks || null,
+    });
+  }
+  return materializeOpenAiMessages({
+    calls,
+    results,
+    assistantText: def.assistantText != null ? def.assistantText : null,
+  });
+}
+
+module.exports = {
+  materializeOpenAiMessages,
+  materializeAnthropicMessages,
+  materializeFromFixtureDef,
+};

package/src/code/protocol/ownership.js

@@ -0,0 +1,147 @@
+"use strict";
+
+/**
+ * Session state ownership table (Phase 0).
+ *
+ * Durable fields are recovery sources. Projections may be rebuilt from durable
+ * state (or from protocolLedger + provider message checkpoint until full
+ * event-sourced rebuild exists).
+ *
+ * See docs/ucode-agent-runtime-remediation-plan.md §4.2 / R4.
+ */
+
+/** @typedef {"session"|"session/artifacts"|"checkpoint"|"runtime_events"|"execution/session"} Authority */
+
+/**
+ * @type {ReadonlyArray<{
+ *   key: string,
+ *   authority: Authority,
+ *   durable: boolean,
+ *   rebuildable: boolean,
+ *   notes?: string
+ * }>}
+ */
+const STATE_OWNERSHIP = Object.freeze([
+  {
+    key: "protocolLedger",
+    authority: "session",
+    durable: true,
+    rebuildable: false,
+    notes: "Not yet persisted; planned under DurableSessionState (R1/R4)",
+  },
+  {
+    key: "executionState",
+    authority: "session",
+    durable: true,
+    rebuildable: false,
+  },
+  {
+    key: "transcript.events",
+    authority: "session/artifacts",
+    durable: true,
+    rebuildable: false,
+  },
+  {
+    key: "providerMessages",
+    authority: "checkpoint",
+    durable: true,
+    rebuildable: true,
+    notes: "Today: nlMessages stripped on save; rebuilt from transcript when possible",
+  },
+  {
+    key: "workingSet",
+    authority: "execution/session",
+    durable: true,
+    rebuildable: true,
+  },
+  {
+    key: "artifacts",
+    authority: "session/artifacts",
+    durable: true,
+    rebuildable: false,
+  },
+  {
+    key: "rollingSummary",
+    authority: "session",
+    durable: true,
+    rebuildable: true,
+    notes: "Optional durable projection (summary field)",
+  },
+  {
+    key: "uiLogs",
+    authority: "runtime_events",
+    durable: false,
+    rebuildable: true,
+  },
+  {
+    key: "planUi",
+    authority: "execution/session",
+    durable: true,
+    rebuildable: true,
+    notes: "Band mode preferences; graph view is projection of planGraph",
+  },
+  {
+    key: "sessionStatus",
+    authority: "runtime_events",
+    durable: false,
+    rebuildable: true,
+  },
+]);
+
+const DURABLE_FIELDS = Object.freeze(
+  STATE_OWNERSHIP.filter((row) => row.durable).map((row) => row.key)
+);
+
+const PROJECTION_FIELDS = Object.freeze(
+  STATE_OWNERSHIP.filter((row) => row.rebuildable).map((row) => row.key)
+);
+
+function getOwnershipRow(key = "") {
+  const id = String(key || "").trim();
+  return STATE_OWNERSHIP.find((row) => row.key === id) || null;
+}
+
+function assertOwnershipTableInvariants() {
+  const keys = new Set();
+  for (const row of STATE_OWNERSHIP) {
+    if (!row.key) throw new Error("ownership row missing key");
+    if (keys.has(row.key)) throw new Error(`duplicate ownership key: ${row.key}`);
+    keys.add(row.key);
+    if (typeof row.durable !== "boolean" || typeof row.rebuildable !== "boolean") {
+      throw new Error(`ownership row ${row.key} has invalid flags`);
+    }
+  }
+  return true;
+}
+
+/**
+ * Atomic commit boundaries (R4). Crash between these stages must have a
+ * defined recovery; tools that are not naturally idempotent must not be
+ * blindly re-executed when stopped at `started`.
+ */
+const ATOMIC_COMMIT_BOUNDARIES = Object.freeze([
+  "assistant_tool_calls_accepted",
+  "before_side_effect_tool",
+  "after_side_effect_persisted",
+  "tool_result_committed_to_ledger",
+  "before_agent_loop_suspension",
+  "after_resume_answer_committed",
+  "after_taskrun_terminal_cas",
+]);
+
+const SIDE_EFFECT_INVOCATION_PHASES = Object.freeze([
+  "prepared",
+  "started",
+  "effect_observed",
+  "result_committed",
+]);
+
+module.exports = {
+  STATE_OWNERSHIP,
+  DURABLE_FIELDS,
+  PROJECTION_FIELDS,
+  getOwnershipRow,
+  assertOwnershipTableInvariants,
+  ATOMIC_COMMIT_BOUNDARIES,
+  SIDE_EFFECT_INVOCATION_PHASES,
+};