@free-intelligence/core 1.1.0

package/dist/index.js

@@ -0,0 +1,200 @@
+// src/agent/state.ts
+function initialAgentTurnState() {
+  return {
+    plan: null,
+    steps: [],
+    text: "",
+    sources: [],
+    meta: null,
+    status: "thinking"
+  };
+}
+function applyAgentEvent(state, event) {
+  const streamingStatus = state.status === "thinking" ? "streaming" : state.status;
+  switch (event.type) {
+    case "open":
+      return state;
+    case "plan":
+      return {
+        ...state,
+        plan: {
+          steps: event.steps.map((label) => ({ label, status: "pending" })),
+          rejection: null,
+          amended: null,
+          outcome: null
+        },
+        status: streamingStatus
+      };
+    case "plan_rejected":
+      return state.plan ? { ...state, plan: { ...state.plan, rejection: event.rejection } } : { ...state, plan: { steps: [], rejection: event.rejection } };
+    case "step_started": {
+      if (!state.plan) return state;
+      const idx = event.index;
+      if (idx < 0 || idx >= state.plan.steps.length) return state;
+      const steps = state.plan.steps.map((s, i) => {
+        if (i < idx && (s.status === "pending" || s.status === "running")) {
+          return { ...s, status: "done" };
+        }
+        if (i === idx) return { ...s, status: "running" };
+        return s;
+      });
+      return { ...state, plan: { ...state.plan, steps } };
+    }
+    case "step_done": {
+      if (!state.plan) return state;
+      const idx = event.index;
+      if (idx < 0 || idx >= state.plan.steps.length) return state;
+      const steps = state.plan.steps.map((s, i) => {
+        if (i !== idx) return s;
+        const patch = { ...s, status: event.status };
+        if (event.status === "done") {
+          if (event.summary) patch.summary = event.summary;
+        } else if (event.error) {
+          patch.error = event.error;
+        }
+        return patch;
+      });
+      return { ...state, plan: { ...state.plan, steps } };
+    }
+    case "step_noted": {
+      if (!state.plan) return state;
+      const idx = event.index;
+      if (idx < 0 || idx >= state.plan.steps.length) return state;
+      const steps = state.plan.steps.map(
+        (s, i) => i === idx ? { ...s, note: event.note } : s
+      );
+      return { ...state, plan: { ...state.plan, steps } };
+    }
+    case "plan_amended":
+      return state.plan ? { ...state, plan: { ...state.plan, amended: event.action } } : state;
+    case "plan_cancelled": {
+      if (!state.plan) return state;
+      const steps = state.plan.steps.map(
+        (s) => s.status === "pending" || s.status === "running" ? { ...s, status: "cancelled" } : s
+      );
+      return { ...state, plan: { ...state.plan, steps, outcome: "cancelled" } };
+    }
+    case "plan_completed":
+      return state.plan ? { ...state, plan: { ...state.plan, outcome: "completed" } } : state;
+    case "plan_failed":
+      return state.plan ? { ...state, plan: { ...state.plan, outcome: "failed" } } : state;
+    case "tool_call": {
+      const existing = event.call.id != null ? state.steps.findIndex((c) => c.id === event.call.id) : -1;
+      const steps = existing >= 0 ? state.steps.map((c, i) => i === existing ? event.call : c) : [...state.steps, event.call];
+      return { ...state, steps, status: streamingStatus };
+    }
+    case "text":
+      return {
+        ...state,
+        text: state.text + event.delta,
+        status: streamingStatus
+      };
+    case "result": {
+      const text = event.text.trim() ? event.text : state.text;
+      const plan = state.plan ? {
+        ...state.plan,
+        steps: state.plan.steps.map(
+          (s) => s.status === "pending" || s.status === "running" ? { ...s, status: "done" } : s
+        )
+      } : state.plan;
+      return {
+        ...state,
+        text,
+        plan,
+        sources: event.sources ?? state.sources,
+        meta: event.meta ?? state.meta,
+        status: "done"
+      };
+    }
+    case "meta":
+      return { ...state, meta: event.meta };
+    case "error":
+      return { ...state, status: "error", errorMessage: event.message };
+    case "done":
+      return state.status === "thinking" || state.status === "streaming" ? { ...state, status: "done" } : state;
+    default:
+      return state;
+  }
+}
+
+// src/agent/transcript.ts
+function makeUserMessage(text) {
+  return { role: "user", content: text, timestamp: (/* @__PURE__ */ new Date()).toISOString() };
+}
+function foldAssistantTurn(turn) {
+  const model = turn.meta?.model;
+  return {
+    role: "assistant",
+    content: turn.text,
+    timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+    ...model ? { metadata: { model } } : {}
+  };
+}
+
+// src/conversation/helpers.ts
+var CONVERSATION_SCHEMA_VERSION = 1;
+var DEFAULT_TITLE = "New chat";
+var TITLE_MAX = 60;
+var PREVIEW_MAX = 120;
+function truncate(text, max) {
+  const t = text.trim().replace(/\s+/g, " ");
+  if (t.length <= max) return t;
+  return `${t.slice(0, Math.max(0, max - 1)).trimEnd()}\u2026`;
+}
+function sanitizeConversationMessage(message) {
+  return {
+    role: message.role,
+    content: message.content,
+    timestamp: message.timestamp
+  };
+}
+function deriveConversationTitle(messages, max = TITLE_MAX) {
+  const firstUser = messages.find(
+    (m) => m.role === "user" && m.content.trim() !== ""
+  );
+  if (!firstUser) return DEFAULT_TITLE;
+  return truncate(firstUser.content, max) || DEFAULT_TITLE;
+}
+function deriveConversationPreview(messages, max = PREVIEW_MAX) {
+  for (let i = messages.length - 1; i >= 0; i--) {
+    if (messages[i].content.trim() !== "") {
+      return truncate(messages[i].content, max);
+    }
+  }
+  return "";
+}
+function createConversationRecord(args) {
+  const now = args.now ?? (/* @__PURE__ */ new Date()).toISOString();
+  const messages = (args.messages ?? []).map(sanitizeConversationMessage);
+  return {
+    id: args.id,
+    title: deriveConversationTitle(messages),
+    createdAt: now,
+    updatedAt: now,
+    messages,
+    preview: deriveConversationPreview(messages),
+    schemaVersion: CONVERSATION_SCHEMA_VERSION
+  };
+}
+function summarizeConversation(record) {
+  return {
+    id: record.id,
+    title: record.title,
+    createdAt: record.createdAt,
+    updatedAt: record.updatedAt,
+    preview: record.preview
+  };
+}
+export {
+  CONVERSATION_SCHEMA_VERSION,
+  applyAgentEvent,
+  createConversationRecord,
+  deriveConversationPreview,
+  deriveConversationTitle,
+  foldAssistantTurn,
+  initialAgentTurnState,
+  makeUserMessage,
+  sanitizeConversationMessage,
+  summarizeConversation
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/agent/state.ts","../src/agent/transcript.ts","../src/conversation/helpers.ts"],"sourcesContent":["/**\n * AgentTurnState — the reduced state the fi-glass agent panels render, plus the\n * pure `applyAgentEvent` reducer that derives it from the wire stream.\n *\n * The reducer is pure (no React, no transport, no I/O) so every app reuses the\n * same event→state logic and only supplies the transport that produces the\n * AgentStreamEvent stream. Immutable: every event returns a new state object.\n */\n\nimport type {\n  AgentStreamEvent,\n  AgentMeta,\n  GuardRejection,\n  ToolCall,\n  StepStatus,\n} from './events';\n\n/** One step of the declared plan, enriched with live status. */\nexport interface PlanStep {\n  label: string;\n  status: StepStatus;\n  summary?: string;\n  error?: string;\n  /** Free-text annotation from note_step (carried by the step_noted event). */\n  note?: string;\n}\n\n/** Terminal verdict of a whole plan (finalize_plan / cancel_plan). */\nexport type PlanOutcome = 'completed' | 'failed' | 'cancelled';\n\n/** The agent's declared plan. Guard-as-quality: rejection is woven in here. */\nexport interface AgentPlan {\n  steps: PlanStep[];\n  /** Set when a guard blocks; cleared when a fresh plan is declared. */\n  rejection?: GuardRejection | null;\n  /**\n   * Set when the agent restructures the plan mid-turn (plan_amended). 'replan'\n   * is then followed by a fresh `plan` event that reseeds steps and clears this.\n   */\n  amended?: 'insert' | 'replan' | null;\n  /** Terminal plan verdict once finalize_plan / cancel_plan settles it. */\n  outcome?: PlanOutcome | null;\n}\n\nexport type AgentTurnStatus = 'thinking' | 'streaming' | 'done' | 'error';\n\n/** The full reduced state of one agentic turn. */\nexport interface AgentTurnState {\n  plan: AgentPlan | null;\n  steps: ToolCall[];\n  text: string;\n  /** Evidence references (e.g. source URLs). App-agnostic name. */\n  sources: string[];\n  meta: AgentMeta | null;\n  status: AgentTurnStatus;\n  errorMessage?: string;\n}\n\n/** A fresh, empty turn — call at the start of each agentic turn. */\nexport function initialAgentTurnState(): AgentTurnState {\n  return {\n    plan: null,\n    steps: [],\n    text: '',\n    sources: [],\n    meta: null,\n    status: 'thinking',\n  };\n}\n\n/**\n * Pure reducer: apply one wire event to the turn state, returning a new state.\n *\n * Mirrors the universal turn lifecycle; an app's hook feeds it the events its\n * transport produces. Unknown/transport-only events (`open`) pass through\n * untouched.\n */\nexport function applyAgentEvent(\n  state: AgentTurnState,\n  event: AgentStreamEvent\n): AgentTurnState {\n  // Bump 'thinking' → 'streaming' on the first sign of activity; never regress\n  // a settled ('done'/'error') turn. Mirrors the original's status moves but is\n  // guarded against out-of-order events.\n  const streamingStatus: AgentTurnStatus =\n    state.status === 'thinking' ? 'streaming' : state.status;\n\n  switch (event.type) {\n    case 'open':\n      return state;\n\n    case 'plan':\n      // A fresh plan seeds N steps as 'pending' (index i ↔ step i) and clears\n      // any prior guard rejection (the agent is re-declaring).\n      return {\n        ...state,\n        plan: {\n          steps: event.steps.map((label) => ({ label, status: 'pending' })),\n          rejection: null,\n          amended: null,\n          outcome: null,\n        },\n        status: streamingStatus,\n      };\n\n    case 'plan_rejected':\n      return state.plan\n        ? { ...state, plan: { ...state.plan, rejection: event.rejection } }\n        : { ...state, plan: { steps: [], rejection: event.rejection } };\n\n    case 'step_started': {\n      if (!state.plan) return state;\n      const idx = event.index;\n      if (idx < 0 || idx >= state.plan.steps.length) return state; // bounds guard\n      // Catch-up sweep: starting step N implies steps 0..N-1 finished, even if\n      // their step_done events were dropped (SSE is lossy). Then mark N running.\n      const steps = state.plan.steps.map((s, i) => {\n        if (i < idx && (s.status === 'pending' || s.status === 'running')) {\n          return { ...s, status: 'done' as const };\n        }\n        if (i === idx) return { ...s, status: 'running' as const };\n        return s;\n      });\n      return { ...state, plan: { ...state.plan, steps } };\n    }\n\n    case 'step_done': {\n      if (!state.plan) return state;\n      const idx = event.index;\n      if (idx < 0 || idx >= state.plan.steps.length) return state; // bounds guard\n      const steps = state.plan.steps.map((s, i) => {\n        if (i !== idx) return s; // mutate exactly step N — no off-by-one\n        const patch: PlanStep = { ...s, status: event.status };\n        // 'done' carries a summary; 'failed'/'cancelled' carry a reason in error.\n        if (event.status === 'done') {\n          if (event.summary) patch.summary = event.summary;\n        } else if (event.error) {\n          patch.error = event.error;\n        }\n        return patch;\n      });\n      return { ...state, plan: { ...state.plan, steps } };\n    }\n\n    case 'step_noted': {\n      // Annotate exactly step N with a free-text note; never touches status.\n      if (!state.plan) return state;\n      const idx = event.index;\n      if (idx < 0 || idx >= state.plan.steps.length) return state; // bounds guard\n      const steps = state.plan.steps.map((s, i) =>\n        i === idx ? { ...s, note: event.note } : s\n      );\n      return { ...state, plan: { ...state.plan, steps } };\n    }\n\n    case 'plan_amended':\n      // Record that the plan was restructured. For 'replan' the new steps land\n      // in a following `plan` event (which clears this flag); here we only set\n      // the badge signal — the amended event carries no steps to apply.\n      return state.plan\n        ? { ...state, plan: { ...state.plan, amended: event.action } }\n        : state;\n\n    case 'plan_cancelled': {\n      // The whole plan was abandoned. Settle still-open steps as 'cancelled'\n      // (NOT 'done' — distinct from the `result` close-out sweep, which only\n      // touches pending/running and would wrongly mark these done if it ran\n      // after us). Already-settled steps keep their terminal status.\n      if (!state.plan) return state;\n      const steps = state.plan.steps.map((s) =>\n        s.status === 'pending' || s.status === 'running'\n          ? { ...s, status: 'cancelled' as const }\n          : s\n      );\n      return { ...state, plan: { ...state.plan, steps, outcome: 'cancelled' } };\n    }\n\n    case 'plan_completed':\n      // Terminal verdict. Per-step statuses already reflect reality (each\n      // step_done settled them); we only stamp the plan-level outcome. The\n      // wire counts are derivable from steps[].status, so we don't store them.\n      return state.plan\n        ? { ...state, plan: { ...state.plan, outcome: 'completed' } }\n        : state;\n\n    case 'plan_failed':\n      // Plan failed (>=1 step failed). Leave step statuses as settled — a\n      // failed plan can still have done steps — and stamp the outcome.\n      return state.plan\n        ? { ...state, plan: { ...state.plan, outcome: 'failed' } }\n        : state;\n\n    case 'tool_call': {\n      // Dedupe-on-arrival by id (DELIBERATE divergence from the original's\n      // append + replace-at-result, since the contract's `result` carries no\n      // tool_calls). id == null = still pending → append.\n      const existing =\n        event.call.id != null\n          ? state.steps.findIndex((c) => c.id === event.call.id)\n          : -1;\n      const steps =\n        existing >= 0\n          ? state.steps.map((c, i) => (i === existing ? event.call : c))\n          : [...state.steps, event.call];\n      return { ...state, steps, status: streamingStatus };\n    }\n\n    case 'text':\n      // CONCATENATE deltas (never replace) — the streaming bug that compiles\n      // identically but only shows the last fragment at runtime.\n      return {\n        ...state,\n        text: state.text + event.delta,\n        status: streamingStatus,\n      };\n\n    case 'result': {\n      // Never wipe a non-empty streamed accumulation with an empty result.text\n      // (the agent ran tools but composed no final response). Note: app-specific\n      // dedupe/source-extraction stays in the app's hook, which emits\n      // `sources` already extracted.\n      const text = event.text.trim() ? event.text : state.text;\n      // Close any plan steps left open when the turn settles.\n      const plan = state.plan\n        ? {\n            ...state.plan,\n            steps: state.plan.steps.map((s) =>\n              s.status === 'pending' || s.status === 'running'\n                ? { ...s, status: 'done' as const }\n                : s\n            ),\n          }\n        : state.plan;\n      return {\n        ...state,\n        text,\n        plan,\n        sources: event.sources ?? state.sources,\n        meta: event.meta ?? state.meta,\n        status: 'done',\n      };\n    }\n\n    case 'meta':\n      return { ...state, meta: event.meta };\n\n    case 'error':\n      return { ...state, status: 'error', errorMessage: event.message };\n\n    case 'done':\n      return state.status === 'thinking' || state.status === 'streaming'\n        ? { ...state, status: 'done' }\n        : state;\n\n    default:\n      return state;\n  }\n}\n","/**\n * Transcript bridge — fold the live agentic turn into flat chat messages.\n *\n * Pure, framework-agnostic (no React, no transport). The agent contract models\n * ONE live turn (AgentTurnState); a conversation surface needs the thread as a\n * flat list. These two helpers bridge `AgentTurnState` → `ChatMessage` so any\n * shell (fi-glass and beyond) can keep a visible transcript without re-deriving\n * the mapping. Moved here from the og118 consumer (DD-002-LESSON): a reusable\n * primitive belongs in the framework, not the app wrapper.\n */\n\nimport type { ChatMessage } from '../chat/message';\nimport type { AgentTurnState } from './state';\n\n/** A user message, ready to render optimistically the instant the user sends. */\nexport function makeUserMessage(text: string): ChatMessage {\n  return { role: 'user', content: text, timestamp: new Date().toISOString() };\n}\n\n/**\n * Fold a finished turn's answer into an assistant message. Keeps only the\n * material-agnostic content (no AgentTurnState snapshot) — a future gate can add\n * per-turn glass-box rendering without bloating the ChatMessage contract now.\n * Model provenance survives the fold: `turn.meta.model` lands in\n * `metadata.model` so a shell's badge slot (\"Powered by …\") has real data after\n * persistence, not just during the live turn.\n */\nexport function foldAssistantTurn(turn: AgentTurnState): ChatMessage {\n  const model = turn.meta?.model;\n  return {\n    role: 'assistant',\n    content: turn.text,\n    timestamp: new Date().toISOString(),\n    ...(model ? { metadata: { model } } : {}),\n  };\n}\n","/**\n * Conversation helpers — pure, deterministic primitives for building and\n * summarizing ConversationRecords. No React, no browser, no transport.\n *\n * Privacy by structure: `sanitizeConversationMessage` builds a NEW message with\n * exactly the allowed subset (role / content / timestamp). Any other field a\n * ChatMessage may carry now or later — `id`, `thinking`, `metadata`, a future\n * tool payload or token — is dropped by construction, not by an allow/deny list\n * someone must remember to update. The initial privacy guarantee is the\n * restriction, not PII heuristics.\n *\n * Determinism: helpers that stamp a time accept an optional `now` so tests are\n * reproducible; they fall back to the wall clock only when it is omitted.\n */\n\nimport type { ChatMessage } from '../chat/message';\nimport type { ConversationRecord, ConversationSummary } from './record';\n\n/** Schema version stamped on every record created here. */\nexport const CONVERSATION_SCHEMA_VERSION = 1;\n\n/** Fallback title when there is no usable user message yet. */\nconst DEFAULT_TITLE = 'New chat';\nconst TITLE_MAX = 60;\nconst PREVIEW_MAX = 120;\n\n/** Collapse whitespace and truncate to `max` chars with an ellipsis. Pure. */\nfunction truncate(text: string, max: number): string {\n  const t = text.trim().replace(/\\s+/g, ' ');\n  if (t.length <= max) return t;\n  return `${t.slice(0, Math.max(0, max - 1)).trimEnd()}…`;\n}\n\n/**\n * Reduce a ChatMessage to the only fields safe to persist: role, content, and\n * timestamp. Drops id, thinking, metadata, and anything else by construction.\n */\nexport function sanitizeConversationMessage(message: ChatMessage): ChatMessage {\n  return {\n    role: message.role,\n    content: message.content,\n    timestamp: message.timestamp,\n  };\n}\n\n/** Title from the first non-empty user message; `DEFAULT_TITLE` otherwise. */\nexport function deriveConversationTitle(\n  messages: ChatMessage[],\n  max: number = TITLE_MAX,\n): string {\n  const firstUser = messages.find(\n    (m) => m.role === 'user' && m.content.trim() !== '',\n  );\n  if (!firstUser) return DEFAULT_TITLE;\n  return truncate(firstUser.content, max) || DEFAULT_TITLE;\n}\n\n/** Preview from the last non-empty message of any role; `''` otherwise. */\nexport function deriveConversationPreview(\n  messages: ChatMessage[],\n  max: number = PREVIEW_MAX,\n): string {\n  for (let i = messages.length - 1; i >= 0; i--) {\n    if (messages[i].content.trim() !== '') {\n      return truncate(messages[i].content, max);\n    }\n  }\n  return '';\n}\n\n/** Arguments for {@link createConversationRecord}. */\nexport interface CreateConversationRecordArgs {\n  /** Stable id (doubles as the backend session_id). */\n  id: string;\n  /** Initial thread; sanitized before storing. Default: empty. */\n  messages?: ChatMessage[];\n  /** ISO timestamp to stamp createdAt/updatedAt. Default: now. */\n  now?: string;\n}\n\n/** Build a fresh, sanitized record with derived title + preview. */\nexport function createConversationRecord(\n  args: CreateConversationRecordArgs,\n): ConversationRecord {\n  const now = args.now ?? new Date().toISOString();\n  const messages = (args.messages ?? []).map(sanitizeConversationMessage);\n  return {\n    id: args.id,\n    title: deriveConversationTitle(messages),\n    createdAt: now,\n    updatedAt: now,\n    messages,\n    preview: deriveConversationPreview(messages),\n    schemaVersion: CONVERSATION_SCHEMA_VERSION,\n  };\n}\n\n/** Project a record to its light summary — excludes `messages`. */\nexport function summarizeConversation(\n  record: ConversationRecord,\n): ConversationSummary {\n  return {\n    id: record.id,\n    title: record.title,\n    createdAt: record.createdAt,\n    updatedAt: record.updatedAt,\n    preview: record.preview,\n  };\n}\n"],"mappings":"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","names":[]}

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@free-intelligence/core",
+  "version": "1.1.0",
+  "license": "PolyForm-Noncommercial-1.0.0",
+  "type": "module",
+  "description": "Material-agnostic substrate-facing layer: theme-token contract, agent event contract, fi-runner client. Consumed directly by apps and by every fi-<material> skin.",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "peerDependencies": {
+    "react": ">=18",
+    "react-dom": ">=18"
+  },
+  "devDependencies": {
+    "tsup": "^8.5.1"
+  },
+  "scripts": {
+    "build": "tsup",
+    "type-check": "tsc --noEmit",
+    "test": "vitest run"
+  }
+}

package/src/agent/events.ts

@@ -0,0 +1,121 @@
+/**
+ * AgentStreamEvent — the agent-turn wire contract.
+ *
+ * Material-agnostic, React-free, and intentionally NOT shaped to any one app's
+ * backend. Each app's hook MAPS its real stream onto this union: insult_ai maps
+ * its `/chat/stream` SSE frames; og118 maps its own transport; a fi-runner-native
+ * hook would map `turn_flow` / `ToolCall` / task_tracker stream events. The
+ * fi-glass agent panels and the pure `applyAgentEvent` reducer consume ONLY this
+ * union — never a concrete transport, endpoint, or auth.
+ *
+ * This is the neutral middle: it equals neither insult_ai's frontend shape nor
+ * fi-core's task_tracker shape; both map onto it. It is the most consequential
+ * contract in the fi-glass roadmap — og118 and every future app inherit it.
+ */
+
+/** Lifecycle status of a single planned step. */
+export type StepStatus = 'pending' | 'running' | 'done' | 'failed' | 'cancelled';
+
+/** Severity a guard can assign. Generic — each app names its own guards. */
+export type GuardLevel = 'ok' | 'warning' | 'critical';
+
+/** A tool invocation surfaced for the live audit trail. */
+export interface ToolCall {
+  /** Stable id from the provider (e.g. tool_use_id); null while pending. */
+  id: string | null;
+  /** Tool identifier as the agent named it. */
+  name: string;
+  /** Originating server/namespace, or null for built-ins. */
+  server: string | null;
+  /** null = pending, false = ok, true = errored. */
+  isError: boolean | null;
+}
+
+/**
+ * A soft guard decision against the declared plan (the stream continues).
+ *
+ * Core defines the SHAPE of the verdict — not what any guard evaluates. The
+ * `reason`/copy is owned by the app; core only carries that a guardrail
+ * assessed the plan and emitted a verdict. This is the universal agentic-safety
+ * pattern, not a domain concept.
+ */
+export interface GuardRejection {
+  /** Human-readable reason. App owns the wording/copy. */
+  reason: string;
+  /** Which plan steps tripped the guard. */
+  matched: Array<{ index: number; label: string }>;
+  /** Guard identifier (app-defined), or null. */
+  guard: string | null;
+}
+
+/** Per-turn observability. All optional; each app fills what it has. */
+export interface AgentMeta {
+  requestId?: string | null;
+  latencyMs?: number | null;
+  toolCount?: number | null;
+  tokens?: Record<string, unknown> | null;
+  /** Worst-case guard verdicts by guard name. */
+  guardLevels?: Record<string, GuardLevel> | null;
+  attempts?: number | null;
+  model?: string | null;
+}
+
+/**
+ * The discriminated union an app's hook emits as a turn unfolds.
+ *
+ * `plan` carries flat labels (the initial announcement, no status yet); the rich
+ * per-step state (PlanStep) is built by the reducer as `step_started`/`step_done`
+ * arrive — the separation between "what was announced" and "what has happened".
+ *
+ * `result.sources` is the generic name for evidence references (e.g. source URLs
+ * from RAG or web-search). Apps extract them however they like (insult_ai parses
+ * a "Receipts" markdown tail in its own hook — app-specific, stays there).
+ */
+export type AgentStreamEvent =
+  | { type: 'open'; sessionId?: string; requestId?: string }
+  | { type: 'plan'; steps: string[] }
+  | { type: 'plan_rejected'; rejection: GuardRejection }
+  | { type: 'step_started'; index: number }
+  | {
+      type: 'step_done';
+      index: number;
+      status: 'done' | 'failed' | 'cancelled';
+      summary?: string;
+      error?: string;
+    }
+  // --- Plan revision & lifecycle ------------------------------------------
+  // Faithful to fi-runner's task_tracker stream (see fi_runner/_plan_events.py).
+  // Without these variants an app's hook DROPS the signal (og118 did exactly
+  // that) — the turn re-plans or cancels and the UI never learns.
+  //
+  // A step gained a free-text annotation (note_step). Carries the note so the
+  // UI can show WHY, not merely that a note exists.
+  | { type: 'step_noted'; index: number; note: string }
+  // The agent restructured the plan mid-turn: 'insert' splices a step in;
+  // 'replan' replaces the plan (its new steps arrive in a fresh `plan` event,
+  // which clears the amended flag). The amended event itself carries no steps.
+  | { type: 'plan_amended'; action: 'insert' | 'replan' }
+  // The whole plan was abandoned (cancel_plan). `reason` is on the wire even
+  // though the reducer doesn't surface it yet — the contract equals the wire.
+  | { type: 'plan_cancelled'; reason?: string }
+  // Terminal plan verdicts (finalize_plan). Counts are derivable from
+  // steps[].status, but the backend's authoritative tallies ride the wire too
+  // (they survive lossy SSE that the per-step events may not).
+  | {
+      type: 'plan_completed';
+      completedCount?: number;
+      failedCount?: number;
+      cancelledCount?: number;
+    }
+  | {
+      type: 'plan_failed';
+      completedCount?: number;
+      failedCount?: number;
+      cancelledCount?: number;
+    }
+  | { type: 'tool_call'; call: ToolCall }
+  | { type: 'text'; delta: string }
+  | { type: 'result'; text: string; sources?: string[]; meta?: AgentMeta }
+  | { type: 'meta'; meta: AgentMeta }
+  | { type: 'error'; message: string }
+  | { type: 'done' };

package/src/agent/hook.ts

@@ -0,0 +1,27 @@
+import type { AgentTurnState } from './state';
+
+/**
+ * AgentHook — the agentic-turn contract the fi-glass agent panels consume.
+ *
+ * Dependency-inversion spine, twin of ChatHook. The app implements it against
+ * its own transport (insult_ai: POST /chat/stream SSE → applyAgentEvent;
+ * og118: its own). fi-glass NEVER imports the transport, endpoints, or auth.
+ *
+ * This is DATA + ACTIONS only. Presentation slots (renderSources /
+ * renderGuardBanner / icons) live on the AgentPanel props in fi-glass, NOT here
+ * — the hook is data, the panel is render. (Cleaner than Curio's ChatHook, which
+ * carried customEmptyState.) Because no member references a UI node type, the
+ * hook needs no `TNode` generic; only the panel is generic over its node type.
+ */
+export interface AgentHook {
+  /** Current/last turn's reduced state. */
+  turn: AgentTurnState;
+  /** Whether a turn is actively streaming. */
+  isStreaming: boolean;
+  /** Start an agentic turn. */
+  send: (message: string, metadata?: object) => Promise<void>;
+  /** Abort the in-flight turn, if supported. */
+  abort?: () => void;
+  /** Reset the session/turn. */
+  reset?: () => void;
+}

package/src/agent/state.test.ts

@@ -0,0 +1,182 @@
+/**
+ * Unit tests for the NEW reducer branches added in core v1.1.0 — the plan
+ * revision & lifecycle events (step_noted / plan_amended / plan_cancelled /
+ * plan_completed / plan_failed) and 'cancelled' in step_done.
+ *
+ * Why these exist now (and Berkelio's original branches did not get unit tests):
+ * those were battle-tested logic we MOVED, validated end-to-end via og118. These
+ * five branches are NEW logic that never ran, and a normal agentic turn does NOT
+ * reliably exercise them — og118 could run a hundred times without a single
+ * plan_cancelled/replan/note. The e2e can't be trusted to hit them; a unit test
+ * drives the event deterministically and asserts the resulting state. This is
+ * the safety net a substrate reducer consumed by multiple apps must have.
+ */
+
+import { describe, it, expect } from 'vitest';
+import {
+  applyAgentEvent,
+  initialAgentTurnState,
+  type AgentTurnState,
+} from './state';
+import type { AgentStreamEvent } from './events';
+
+/** Fold a sequence of events from a fresh turn into final state. */
+function run(...events: AgentStreamEvent[]): AgentTurnState {
+  return events.reduce(applyAgentEvent, initialAgentTurnState());
+}
+
+const plan3: AgentStreamEvent = { type: 'plan', steps: ['a', 'b', 'c'] };
+
+describe('step_done — cancelled status (#5)', () => {
+  it('attaches error (not summary) for cancelled', () => {
+    const s = run(plan3, {
+      type: 'step_done',
+      index: 1,
+      status: 'cancelled',
+      error: 'user aborted',
+    });
+    expect(s.plan!.steps[1].status).toBe('cancelled');
+    expect(s.plan!.steps[1].error).toBe('user aborted');
+    expect(s.plan!.steps[1].summary).toBeUndefined();
+  });
+
+  it('regression: done still attaches summary, failed still attaches error', () => {
+    const s = run(
+      plan3,
+      { type: 'step_done', index: 0, status: 'done', summary: 'ok' },
+      { type: 'step_done', index: 1, status: 'failed', error: 'boom' }
+    );
+    expect(s.plan!.steps[0].status).toBe('done');
+    expect(s.plan!.steps[0].summary).toBe('ok');
+    expect(s.plan!.steps[0].error).toBeUndefined();
+    expect(s.plan!.steps[1].status).toBe('failed');
+    expect(s.plan!.steps[1].error).toBe('boom');
+    expect(s.plan!.steps[1].summary).toBeUndefined();
+  });
+});
+
+describe('step_noted', () => {
+  it('annotates exactly step N without touching status', () => {
+    const s = run(plan3, { type: 'step_noted', index: 1, note: 'careful here' });
+    expect(s.plan!.steps[1].note).toBe('careful here');
+    expect(s.plan!.steps[1].status).toBe('pending'); // unchanged
+    expect(s.plan!.steps[0].note).toBeUndefined(); // no bleed
+    expect(s.plan!.steps[2].note).toBeUndefined();
+  });
+
+  it('out-of-bounds index leaves the plan untouched', () => {
+    const s = run(plan3, { type: 'step_noted', index: 9, note: 'nope' });
+    expect(s.plan!.steps.every((st) => st.note === undefined)).toBe(true);
+  });
+
+  it('no plan → passthrough (no crash, no plan invented)', () => {
+    const s = run({ type: 'step_noted', index: 0, note: 'x' });
+    expect(s.plan).toBeNull();
+  });
+});
+
+describe('plan_amended — flag set, then cleared by a fresh plan', () => {
+  it("set to 'replan'", () => {
+    const s = run(plan3, { type: 'plan_amended', action: 'replan' });
+    expect(s.plan!.amended).toBe('replan');
+  });
+
+  it("set to 'insert'", () => {
+    const s = run(plan3, { type: 'plan_amended', action: 'insert' });
+    expect(s.plan!.amended).toBe('insert');
+  });
+
+  it('a fresh plan event clears amended and reseeds steps', () => {
+    const s = run(
+      plan3,
+      { type: 'plan_amended', action: 'replan' },
+      { type: 'plan', steps: ['x', 'y'] } // the replan's real steps arrive here
+    );
+    expect(s.plan!.amended).toBeNull();
+    expect(s.plan!.outcome).toBeNull();
+    expect(s.plan!.steps.map((st) => st.label)).toEqual(['x', 'y']);
+    expect(s.plan!.steps.every((st) => st.status === 'pending')).toBe(true);
+  });
+
+  it('no plan → passthrough', () => {
+    const s = run({ type: 'plan_amended', action: 'insert' });
+    expect(s.plan).toBeNull();
+  });
+});
+
+describe('plan_cancelled — order-safe sweep vs result', () => {
+  it('cancel BEFORE result: open steps become cancelled and result cannot un-cancel them', () => {
+    const s = run(
+      plan3,
+      { type: 'step_done', index: 0, status: 'done', summary: 'ok' },
+      { type: 'plan_cancelled', reason: 'abort' }, // sweeps steps 1,2 (pending) → cancelled
+      { type: 'result', text: 'stopped' } // close-out sweep only touches pending/running
+    );
+    expect(s.plan!.steps[0].status).toBe('done'); // already settled, untouched
+    expect(s.plan!.steps[1].status).toBe('cancelled'); // cancel won; result did NOT mark done
+    expect(s.plan!.steps[2].status).toBe('cancelled');
+    expect(s.plan!.outcome).toBe('cancelled');
+    expect(s.status).toBe('done'); // result still settles the turn
+  });
+
+  it('cancel AFTER result: late cancel records plan outcome but cannot retro-cancel already-settled steps', () => {
+    const s = run(
+      plan3,
+      { type: 'step_done', index: 0, status: 'done', summary: 'ok' },
+      { type: 'result', text: 'done' }, // close-out sweeps steps 1,2 (pending) → done
+      { type: 'plan_cancelled', reason: 'late' } // sweep finds nothing open
+    );
+    expect(s.plan!.steps[0].status).toBe('done');
+    expect(s.plan!.steps[1].status).toBe('done'); // result settled them first; cancel can't undo completed work
+    expect(s.plan!.steps[2].status).toBe('done');
+    expect(s.plan!.outcome).toBe('cancelled'); // plan-level cancellation still recorded
+  });
+
+  it('no plan → passthrough', () => {
+    const s = run({ type: 'plan_cancelled', reason: 'x' });
+    expect(s.plan).toBeNull();
+  });
+});
+
+describe('plan_completed / plan_failed — stamp outcome, never lie about step statuses', () => {
+  it('plan_completed stamps outcome, leaves settled steps as-is', () => {
+    const s = run(
+      plan3,
+      { type: 'step_done', index: 0, status: 'done' },
+      { type: 'step_done', index: 1, status: 'done' },
+      { type: 'step_done', index: 2, status: 'done' },
+      { type: 'plan_completed', completedCount: 3, failedCount: 0, cancelledCount: 0 }
+    );
+    expect(s.plan!.outcome).toBe('completed');
+    expect(s.plan!.steps.every((st) => st.status === 'done')).toBe(true);
+  });
+
+  it('plan_failed keeps a done step done (a failed plan can still have completed steps)', () => {
+    const s = run(
+      plan3,
+      { type: 'step_done', index: 0, status: 'done', summary: 'ok' },
+      { type: 'step_done', index: 1, status: 'failed', error: 'boom' },
+      { type: 'plan_failed', completedCount: 1, failedCount: 1, cancelledCount: 0 }
+    );
+    expect(s.plan!.outcome).toBe('failed');
+    expect(s.plan!.steps[0].status).toBe('done'); // NOT forced to failed
+    expect(s.plan!.steps[1].status).toBe('failed');
+  });
+
+  it('wire counts are NOT stored as derivable state (only outcome is stamped)', () => {
+    const s = run(plan3, {
+      type: 'plan_completed',
+      completedCount: 3,
+      failedCount: 0,
+      cancelledCount: 0,
+    });
+    // counts are derivable from steps[].status — the reduced plan carries no count field.
+    expect(Object.keys(s.plan!)).not.toContain('counts');
+    expect(s.plan!.outcome).toBe('completed');
+  });
+
+  it('no plan → passthrough', () => {
+    expect(run({ type: 'plan_completed' }).plan).toBeNull();
+    expect(run({ type: 'plan_failed' }).plan).toBeNull();
+  });
+});