ghostykit 0.4.1 → 0.5.0

package/README.md

@@ -109,10 +109,13 @@ ref.current?.send("Why did this fail?");                     // ask on the user'
 ```
 
 Other options: `strings`, `toolIcons`, `formatUserText`, `markdown`, `features`
-(`attachments`, `retry`, `copy`, `usage`, `replyOptions`, `duration`), `references` /
-`onReferencesChange`, `voiceNoteText`, `placeholder`, `avatar`, `initialTurns`, and the callbacks
-`onTurnStart`, `onTitle`, `onEvent` (every raw AG-UI event: STATE_*, CUSTOM…), `onSend`. To read the state
-outside the chat, call `usePilot(transport)` yourself and pass the result as `pilot`. Every piece is
+(`attachments`, `retry`, `copy`, `usage`, `replyOptions`, `duration`, `steer`), `references` /
+`onReferencesChange`, `voiceNoteText`, `placeholder`, `avatar`, `initialTurns`, `loadOlder` (earlier
+pages of a long thread), the slot `sidePanel`, and the callbacks `onTurnStart`, `onTitle`, `onState`,
+`onEvent` (every raw AG-UI event), `onSend`. The agent's shared state (`STATE_SNAPSHOT` +
+`STATE_DELTA`) is `pilot.state.agentState`, and each turn's `CUSTOM` events are `turn.custom` (what
+`renderDeliveries` draws). To read the state outside the chat, call `usePilot(transport)` yourself
+and pass the result as `pilot`. Every piece is
 exported (`AgentBubble`, `AgentSteps`, `Composer`, `ConfirmCard`, `Markdown`, …) if you want to build
 your own layout.
 

package/dist/chunks/{chunk-JQEB37IY.js → chunk-VK54J63C.js}

@@ -1,7 +1,120 @@
+// src/core/jsonPatch.ts
+function parsePath(path) {
+  if (path === "") return [];
+  if (!path.startsWith("/")) throw new Error(`bad path ${path}`);
+  return path.slice(1).split("/").map((k) => k.replace(/~1/g, "/").replace(/~0/g, "~"));
+}
+function get(doc, keys) {
+  let cur = doc;
+  for (const k of keys) {
+    if (Array.isArray(cur)) cur = cur[Number(k)];
+    else if (cur && typeof cur === "object") cur = cur[k];
+    else return void 0;
+  }
+  return cur;
+}
+function edit(doc, keys, fn) {
+  if (!keys.length) throw new Error("root");
+  const [k, ...rest] = keys;
+  if (!rest.length) return fn(doc, k);
+  if (Array.isArray(doc)) {
+    const i = Number(k);
+    if (!(i in doc)) throw new Error(`missing ${k}`);
+    const out = [...doc];
+    out[i] = edit(doc[i], rest, fn);
+    return out;
+  }
+  if (doc && typeof doc === "object" && k in doc) {
+    return { ...doc, [k]: edit(doc[k], rest, fn) };
+  }
+  throw new Error(`missing ${k}`);
+}
+function add(doc, keys, value) {
+  if (!keys.length) return value;
+  return edit(doc, keys, (parent, k) => {
+    if (Array.isArray(parent)) {
+      const i = k === "-" ? parent.length : Number(k);
+      if (!Number.isInteger(i) || i < 0 || i > parent.length) throw new Error(`index ${k}`);
+      const out = [...parent];
+      out.splice(i, 0, value);
+      return out;
+    }
+    if (parent && typeof parent === "object") return { ...parent, [k]: value };
+    throw new Error("not a container");
+  });
+}
+function remove(doc, keys) {
+  return edit(doc, keys, (parent, k) => {
+    if (Array.isArray(parent)) {
+      const i = Number(k);
+      if (!(i in parent)) throw new Error(`index ${k}`);
+      return parent.filter((_, j) => j !== i);
+    }
+    if (parent && typeof parent === "object" && k in parent) {
+      const { [k]: _, ...rest } = parent;
+      return rest;
+    }
+    throw new Error(`missing ${k}`);
+  });
+}
+function replace(doc, keys, value) {
+  if (!keys.length) return value;
+  return edit(doc, keys, (parent, k) => {
+    if (Array.isArray(parent)) {
+      const i = Number(k);
+      if (!(i in parent)) throw new Error(`index ${k}`);
+      const out = [...parent];
+      out[i] = value;
+      return out;
+    }
+    if (parent && typeof parent === "object" && k in parent) return { ...parent, [k]: value };
+    throw new Error(`missing ${k}`);
+  });
+}
+var equal = (a, b) => JSON.stringify(a) === JSON.stringify(b);
+function applyJsonPatch(doc, ops) {
+  let cur = doc;
+  try {
+    for (const o of ops) {
+      const keys = parsePath(o.path);
+      if (o.op === "add") cur = add(cur, keys, o.value);
+      else if (o.op === "remove") cur = remove(cur, keys);
+      else if (o.op === "replace") cur = replace(cur, keys, o.value);
+      else if (o.op === "move" || o.op === "copy") {
+        const from = parsePath(o.from ?? "");
+        const v = get(cur, from);
+        if (v === void 0) throw new Error(`missing ${o.from}`);
+        if (o.op === "move") cur = remove(cur, from);
+        cur = add(cur, keys, v);
+      } else if (o.op === "test") {
+        if (!equal(get(cur, keys), o.value)) throw new Error(`test ${o.path}`);
+      } else throw new Error(`op ${o.op}`);
+    }
+    return { doc: cur, ok: true };
+  } catch {
+    return { doc, ok: false };
+  }
+}
+
 // src/core/reducer.ts
 function createPilotState(turns = []) {
-  return { turns, busy: false, error: null, notice: null, usage: null, permissions: [], turnStartedAt: 0, runId: null, effects: [] };
+  return {
+    turns,
+    busy: false,
+    error: null,
+    notice: null,
+    usage: null,
+    permissions: [],
+    turnStartedAt: 0,
+    runId: null,
+    agentState: {},
+    step: null,
+    history: null,
+    olderCount: 0,
+    effects: []
+  };
 }
+var PROTOCOL_CUSTOM = /* @__PURE__ */ new Set(["ghosty.title", "ghosty.injected", "ghosty.history"]);
 function patchAssistant(s, patch) {
   const turns = [...s.turns];
   const last = turns[turns.length - 1];
@@ -72,9 +185,9 @@ function attachmentsOf(content) {
 function messagesToTurns(messages) {
   const turns = [];
   let cur = null;
-  const assistant = () => {
+  const assistant = (id) => {
     if (!cur) {
-      cur = { role: "assistant", text: "" };
+      cur = { ...id ? { id } : {}, role: "assistant", text: "" };
       turns.push(cur);
     }
     return cur;
@@ -82,9 +195,12 @@ function messagesToTurns(messages) {
   for (const m of messages) {
     if (m.role === "user") {
       cur = null;
-      turns.push({ role: "user", text: textOf(m.content), ...attachmentsOf(m.content) ? { attachments: attachmentsOf(m.content) } : {} });
+      turns.push({ ...m.id ? { id: m.id } : {}, role: "user", text: textOf(m.content), ...attachmentsOf(m.content) ? { attachments: attachmentsOf(m.content) } : {} });
     } else if (m.role === "assistant") {
       const t = assistant();
+      if (!t.id && m.id) t.id = m.id;
+      const custom = m.custom;
+      if (Array.isArray(custom) && custom.length) t.custom = [...t.custom ?? [], ...custom.filter((c) => c && typeof c.name === "string")];
       const text = m.content ?? "";
       if (text) t.text = t.text ? `${t.text}
 
@@ -94,11 +210,11 @@ ${text}` : text;
         if (t.text.trim() && t.cuts?.[t.cuts.length - 1] !== t.text.length) t.cuts = [...t.cuts ?? [], t.text.length];
       }
     } else if (m.role === "tool") {
-      const t = assistant();
+      const t = assistant(m.id);
       const failed = Boolean(m.error);
       t.tools = (t.tools ?? []).map((x) => x.id === m.toolCallId ? { ...x, status: failed ? "failed" : "completed" } : x);
     } else if (m.role === "reasoning") {
-      const t = assistant();
+      const t = assistant(m.id);
       t.thought = (t.thought ?? "") + textOf(m.content);
     }
   }
@@ -106,27 +222,47 @@ ${text}` : text;
 }
 function applySnapshot(s, messages) {
   const fresh = messagesToTurns(messages);
-  const old = s.turns;
+  let prefix = [];
+  if (s.olderCount && fresh[0]?.id) {
+    const at = s.turns.findIndex((t) => t.id === fresh[0].id);
+    if (at >= 0) prefix = s.turns.slice(0, at);
+  }
+  const keepOlder = prefix.length > 0;
+  const old = keepOlder ? s.turns.slice(prefix.length) : s.turns.slice(s.olderCount);
+  const lastIndex = fresh.length - 1;
   const turns = fresh.map((t, i) => {
     const o = old[i];
-    if (!o || o.role !== t.role) return t;
+    const live = s.busy && i === lastIndex && t.role === "assistant";
+    const tools = t.tools?.map((x) => {
+      const prev = o?.role === t.role ? o.tools?.find((y) => y.id === x.id) : void 0;
+      const status = x.status === "pending" && (prev?.status ?? (live ? "in_progress" : void 0));
+      return { ...prev, ...x, ...status ? { status } : {} };
+    });
+    const base = tools ? { ...t, tools } : t;
+    if (!o || o.role !== t.role) return base;
     return {
-      ...t,
+      ...base,
       ...o.seconds !== void 0 ? { seconds: o.seconds } : {},
       ...o.usage ? { usage: o.usage } : {},
       ...o.decisions ? { decisions: o.decisions } : {},
       ...o.thought && !t.thought ? { thought: o.thought } : {},
       ...o.attachments && !t.attachments ? { attachments: o.attachments } : {},
-      ...o.tools && t.tools ? { tools: t.tools.map((x) => ({ ...o.tools.find((y) => y.id === x.id), ...x })) } : {}
+      ...o.custom && !t.custom ? { custom: o.custom } : {}
     };
   });
-  return { ...s, turns };
+  return {
+    ...s,
+    turns: [...prefix, ...turns],
+    olderCount: prefix.length,
+    history: keepOlder ? s.history : s.historyNext ?? null,
+    historyNext: void 0
+  };
 }
 function reduceAgUiEvent(prev, e, now = Date.now()) {
   const s = prev.effects.length ? { ...prev, effects: [] } : prev;
   switch (e.type) {
     case "RUN_STARTED":
-      return { ...s, busy: true, error: null, runId: e.runId ?? s.runId };
+      return { ...s, busy: true, error: null, step: null, runId: e.runId ?? s.runId };
     case "TEXT_MESSAGE_START":
       if (e.role && e.role !== "assistant") return s;
       return patchAssistant(s, (t) => ({ ...t, text: t.text && !t.text.endsWith("\n") ? `${t.text}
@@ -169,15 +305,35 @@ function reduceAgUiEvent(prev, e, now = Date.now()) {
       return finish(s, e, now);
     case "RUN_ERROR":
       return finish({ ...s, error: typeof e.message === "string" ? e.message : "El agente fall\xF3." }, e, now, true);
+    case "STEP_STARTED":
+      return typeof e.stepName === "string" ? { ...s, step: e.stepName } : s;
+    case "STEP_FINISHED":
+      return s.step === e.stepName ? { ...s, step: null } : s;
+    case "STATE_SNAPSHOT": {
+      const agentState = e.snapshot && typeof e.snapshot === "object" ? e.snapshot : {};
+      return { ...s, agentState, effects: [{ type: "state", state: agentState }] };
+    }
+    case "STATE_DELTA": {
+      if (!Array.isArray(e.delta)) return s;
+      const { doc, ok } = applyJsonPatch(s.agentState, e.delta);
+      return ok ? { ...s, agentState: doc, effects: [{ type: "state", state: doc }] } : s;
+    }
     case "CUSTOM":
       if (e.name === "ghosty.title") return { ...s, effects: [{ type: "title", title: e.value?.title }] };
-      return s;
+      if (e.name === "ghosty.history") return { ...s, historyNext: toHistory(e.value) };
+      if (typeof e.name !== "string" || PROTOCOL_CUSTOM.has(e.name)) return s;
+      return patchAssistant(s, (t) => ({ ...t, custom: [...t.custom ?? [], { name: e.name, value: e.value, ...typeof e.timestamp === "number" ? { timestamp: e.timestamp } : {} }] }));
     default:
       return s;
   }
 }
+function toHistory(v) {
+  if (!v || typeof v !== "object") return null;
+  const h = v;
+  return { hasMoreBefore: h.hasMoreBefore === true, ...typeof h.before === "string" ? { before: h.before } : {} };
+}
 function finish(s0, e, now, failed = false) {
-  let s = { ...s0, busy: false };
+  let s = { ...s0, busy: false, step: null };
   const outcome = e.outcome;
   const interrupted = outcome?.type === "interrupt" && Array.isArray(outcome.interrupts) && outcome.interrupts.length > 0;
   const clockOffset = typeof e.timestamp === "number" ? now - e.timestamp : 0;
@@ -214,11 +370,19 @@ function beginSend(prev, text, attachments = [], now = Date.now()) {
   const turns = text || attachments.length ? [...prev.turns, { role: "user", text, ...attachments.length ? { attachments } : {} }] : prev.turns;
   return { ...prev, turns, busy: true, error: null, notice: null, turnStartedAt: now, effects: [{ type: "turn-start" }] };
 }
+function beginSteer(prev, text) {
+  return { ...prev, turns: [...prev.turns, { role: "user", text }], notice: null, effects: [] };
+}
+function prependHistory(prev, messages, page) {
+  const have = new Set(prev.turns.map((t) => t.id).filter(Boolean));
+  const older = messagesToTurns(messages).filter((t) => !t.id || !have.has(t.id));
+  return { ...prev, turns: [...older, ...prev.turns], olderCount: prev.olderCount + older.length, history: page, effects: [] };
+}
 function sendFailed(prev, message) {
   return { ...prev, busy: false, turnStartedAt: 0, error: message, effects: [] };
 }
 function stopTurn(prev) {
-  return { ...prev, busy: false, turnStartedAt: 0, turns: closeOpenTools(prev.turns, "cancelled"), effects: [] };
+  return { ...prev, busy: false, step: null, turnStartedAt: 0, turns: closeOpenTools(prev.turns, "cancelled"), effects: [] };
 }
 function dropLastExchange(prev) {
   const turns = [...prev.turns];
@@ -451,12 +615,15 @@ var TOOL_VERBS_EN = {
 };
 
 export {
+  applyJsonPatch,
   createPilotState,
   argsDetail,
   toPermission,
   messagesToTurns,
   reduceAgUiEvent,
   beginSend,
+  beginSteer,
+  prependHistory,
   sendFailed,
   stopTurn,
   dropLastExchange,

package/dist/core/index.d.ts

@@ -1,5 +1,6 @@
 export * from "./types";
-export { argsDetail, beginSend, createPilotState, dropLastExchange, expiryMs, lastUserTurn, messagesToTurns, reduceAgUiEvent, resolvePermission, sendFailed, stopTurn, toPermission, } from "./reducer";
+export { argsDetail, beginSend, beginSteer, createPilotState, dropLastExchange, expiryMs, lastUserTurn, messagesToTurns, prependHistory, reduceAgUiEvent, resolvePermission, sendFailed, stopTurn, toPermission, } from "./reducer";
+export { applyJsonPatch, type PatchOp } from "./jsonPatch";
 export { isNarration, narrationToMarkdown, splitNarration } from "./narration";
 export { cleanReplyOption, extractReplyOptions, type ReplyOptions } from "./options";
 export { TOOL_VERBS_EN, TOOL_VERBS_ES, groupSteps, isRunning, stepLabel, summarizeTools, toolName, toolNames, type ToolVerb, type ToolVerbs, } from "./steps";

package/dist/core/index.js

@@ -1,8 +1,10 @@
 import {
   TOOL_VERBS_EN,
   TOOL_VERBS_ES,
+  applyJsonPatch,
   argsDetail,
   beginSend,
+  beginSteer,
   cleanReplyOption,
   createPilotState,
   dropLastExchange,
@@ -14,6 +16,7 @@ import {
   lastUserTurn,
   messagesToTurns,
   narrationToMarkdown,
+  prependHistory,
   reduceAgUiEvent,
   resolvePermission,
   sendFailed,
@@ -24,7 +27,7 @@ import {
   toPermission,
   toolName,
   toolNames
-} from "../chunks/chunk-JQEB37IY.js";
+} from "../chunks/chunk-VK54J63C.js";
 import {
   applyReferences,
   cleanUserText,
@@ -34,9 +37,11 @@ import {
 export {
   TOOL_VERBS_EN,
   TOOL_VERBS_ES,
+  applyJsonPatch,
   applyReferences,
   argsDetail,
   beginSend,
+  beginSteer,
   cleanReplyOption,
   cleanUserText,
   createPilotState,
@@ -50,6 +55,7 @@ export {
   lastUserTurn,
   messagesToTurns,
   narrationToMarkdown,
+  prependHistory,
   reduceAgUiEvent,
   resolvePermission,
   sendFailed,

package/dist/core/jsonPatch.d.ts

@@ -0,0 +1,11 @@
+export interface PatchOp {
+    op: "add" | "remove" | "replace" | "move" | "copy" | "test";
+    path: string;
+    value?: unknown;
+    from?: string;
+}
+/** Aplica `ops` en orden. Si una falla, regresa el documento original y `ok: false`. */
+export declare function applyJsonPatch<T>(doc: T, ops: PatchOp[]): {
+    doc: T;
+    ok: boolean;
+};

package/dist/core/reducer.d.ts

@@ -1,5 +1,5 @@
 import type { Interrupt, Message } from "@ag-ui/core";
-import type { Attachment, Decision, PermissionRequest, PilotState, Turn } from "./types";
+import type { Attachment, Decision, HistoryPage, PermissionRequest, PilotState, Turn } from "./types";
 export declare function createPilotState(turns?: Turn[]): PilotState;
 type Ev = {
     type: string;
@@ -18,6 +18,16 @@ export declare function messagesToTurns(messages: Message[]): Turn[];
 export declare function reduceAgUiEvent(prev: PilotState, e: Ev, now?: number): PilotState;
 /** El usuario manda un mensaje (o contesta una tarjeta: `text` vacío, sin burbuja). */
 export declare function beginSend(prev: PilotState, text: string, attachments?: Attachment[], now?: number): PilotState;
+/**
+ * Steer: un mensaje del usuario mientras el run sigue. Su burbuja entra en el hilo y lo que el agente
+ * diga después va en una respuesta nueva debajo; el run (y su reloj) siguen siendo los mismos.
+ */
+export declare function beginSteer(prev: PilotState, text: string): PilotState;
+/**
+ * Mensajes más viejos (`loadOlder`) delante del hilo. Las páginas empiezan en un mensaje del usuario;
+ * lo que ya se tenía (mismo id) no se repite.
+ */
+export declare function prependHistory(prev: PilotState, messages: Message[], page: HistoryPage | null): PilotState;
 /** El servidor no aceptó el encargo (HTTP): se DICE, para que no se quede pensando. */
 export declare function sendFailed(prev: PilotState, message: string): PilotState;
 /** Detener: el cliente cortó la conexión (el servidor corta el run). */

package/dist/core/types.d.ts

@@ -38,7 +38,21 @@ export interface Decision {
     status: "approved" | "rejected" | "expired" | "cancelled";
     detail?: string;
 }
+/** Un evento `CUSTOM` del turno (entregas de archivos, avisos propios de la app). */
+export interface CustomEntry {
+    name: string;
+    value: unknown;
+    timestamp?: number;
+}
+/** Hay mensajes más viejos que los del snapshot (`CUSTOM ghosty.history`). */
+export interface HistoryPage {
+    hasMoreBefore: boolean;
+    /** Cursor opaco del servidor: se le regresa a `loadOlder`. */
+    before?: string;
+}
 export interface Turn {
+    /** El id del primer mensaje AG-UI del turno (sólo los que vienen de un snapshot). */
+    id?: string;
     role: "user" | "assistant";
     text: string;
     /** Cuánto tardó, en segundos (sólo los turnos vistos en vivo). */
@@ -51,6 +65,9 @@ export interface Turn {
     usage?: Usage;
     /** Lo que el usuario decidió en las tarjetas de este turno (sólo en vivo). */
     decisions?: Decision[];
+    /** Los `CUSTOM` del turno (p. ej. `ghosty.delivery`), para `renderDeliveries`. Del snapshot salen
+     *  del campo `custom` de cada mensaje del asistente. */
+    custom?: CustomEntry[];
 }
 /** Una opción de la tarjeta de aprobación. */
 export interface PermissionOption {
@@ -90,6 +107,9 @@ export type PilotEffect = {
 } | {
     type: "title";
     title?: string;
+} | {
+    type: "state";
+    state: Record<string, unknown>;
 };
 export interface PilotState {
     turns: Turn[];
@@ -103,6 +123,16 @@ export interface PilotState {
     /** Cuándo empezó el turno que ESTE cliente encargó (0 = ninguno). */
     turnStartedAt: number;
     runId: string | null;
+    /** El estado compartido del agente (`STATE_SNAPSHOT`, con `STATE_DELTA` aplicado encima). */
+    agentState: Record<string, unknown>;
+    /** El paso con nombre en curso (`STEP_STARTED`), p. ej. `waking`. */
+    step: string | null;
+    /** Si hay mensajes más viejos por cargar (`loadOlder`). */
+    history: HistoryPage | null;
+    /** Cuántos de `turns` llegaron con `loadOlder` (van antes del snapshot). */
+    olderCount: number;
+    /** El `ghosty.history` que acompaña al snapshot que viene. */
+    historyNext?: HistoryPage | null;
     /** Efectos de la ÚLTIMA transición. El hook los ejecuta y los descarta. */
     effects: PilotEffect[];
 }

package/dist/react/Piloto.d.ts

@@ -19,6 +19,8 @@ export interface PilotoFeatures {
     replyOptions?: boolean;
     /** «· 12 s» junto a la frase de espera. Default: sí. */
     duration?: boolean;
+    /** Mandar con el run vivo (steer). Default: lo que diga el agente en `state.caps.steer`. */
+    steer?: boolean;
 }
 export interface PilotoSlots {
     /** Lo que la app pinte bajo cada respuesta (archivos, tarjetas propias). */
@@ -31,6 +33,8 @@ export interface PilotoSlots {
     headerActions?: ReactNode;
     /** Pegado arriba del composer (un aviso, un banner). */
     aboveComposer?: ReactNode;
+    /** Un panel junto al chat (subagentes, vista previa), con el estado del agente. */
+    sidePanel?: (agentState: Record<string, unknown>) => ReactNode;
 }
 export interface PilotoProps extends UsePilotOptions {
     transport: PilotTransport | null;

package/dist/react/Status.d.ts

@@ -1,6 +1,8 @@
 /** Los tres puntitos de «escribiendo» (color y animación en CSS: `gc-typing`). */
 export declare function TypingDots(): import("react").JSX.Element;
-export declare function WaitLabel({ since, showDuration, }: {
+export declare function WaitLabel({ since, showDuration, step, }: {
+    /** El paso con nombre en curso (`STEP_STARTED`): si `strings.steps` lo nombra, esa es la frase. */
+    step?: string | null;
     /** Desde que se MANDÓ el mensaje (no desde que se montó la etiqueta). */
     since?: number | null;
     showDuration?: boolean;

package/dist/react/index.js

@@ -1,8 +1,10 @@
 import {
   TOOL_VERBS_EN,
   TOOL_VERBS_ES,
+  applyJsonPatch,
   argsDetail,
   beginSend,
+  beginSteer,
   cleanReplyOption,
   createPilotState,
   dropLastExchange,
@@ -14,6 +16,7 @@ import {
   lastUserTurn,
   messagesToTurns,
   narrationToMarkdown,
+  prependHistory,
   reduceAgUiEvent,
   resolvePermission,
   sendFailed,
@@ -24,7 +27,7 @@ import {
   toPermission,
   toolName,
   toolNames
-} from "../chunks/chunk-JQEB37IY.js";
+} from "../chunks/chunk-VK54J63C.js";
 import {
   PilotHttpError,
   createAgUiTransport,
@@ -884,6 +887,9 @@ var STRINGS_ES = {
   linkOpen: "Abrir",
   close: "Cerrar",
   goToLatest: "Ir al \xFAltimo mensaje",
+  steps: { waking: "Despertando al agente\u2026", session: "Preparando la sesi\xF3n\u2026" },
+  loadOlder: "Cargar mensajes anteriores",
+  loadingOlder: "Cargando\u2026",
   confirmTitle: "Necesito tu permiso para",
   approve: "Aprobar",
   reject: "Rechazar",
@@ -949,6 +955,9 @@ var STRINGS_EN = {
   linkOpen: "Open",
   close: "Close",
   goToLatest: "Go to latest message",
+  steps: { waking: "Waking the agent\u2026", session: "Starting the session\u2026" },
+  loadOlder: "Load earlier messages",
+  loadingOlder: "Loading\u2026",
   confirmTitle: "I need your permission to",
   approve: "Approve",
   reject: "Reject",
@@ -2251,7 +2260,8 @@ function TypingDots() {
 }
 function WaitLabel({
   since,
-  showDuration = true
+  showDuration = true,
+  step
 }) {
   const { strings: t } = usePiloto();
   const [mounted] = useState7(() => Date.now());
@@ -2262,7 +2272,8 @@ function WaitLabel({
   }, []);
   const seconds = Math.max(0, Math.floor((now - (since || mounted)) / 1e3));
   const phrases = t.thinkingPhrases;
-  const what = phrases?.length ? seconds >= STILL_WORKING_S ? t.stillWorking : phrases[Math.floor(seconds / 4) % phrases.length] : t.howItGoes(seconds);
+  const stepText = step ? t.steps?.[step] : void 0;
+  const what = stepText ? stepText : phrases?.length ? seconds >= STILL_WORKING_S ? t.stillWorking : phrases[Math.floor(seconds / 4) % phrases.length] : t.howItGoes(seconds);
   return /* @__PURE__ */ jsx9("div", { className: "flex flex-col gap-0.5 text-sm text-text-secondary", children: /* @__PURE__ */ jsxs7("p", { className: "flex items-center", children: [
     /* @__PURE__ */ jsx9(AnimatePresence2, { mode: "wait", initial: false, children: /* @__PURE__ */ jsx9(
       motion2.span,
@@ -2329,6 +2340,7 @@ function usePilot(transport, opts = {}) {
       if (e.type === "turn-start") o.onTurnStart?.();
       else if (e.type === "turn-done") o.onTurnDone?.({ text: e.text, runId: e.runId, seconds: e.seconds, error: e.error, interrupted: e.interrupted });
       else if (e.type === "title") o.onTitle?.(e.title);
+      else if (e.type === "state") o.onState?.(e.state);
     }
   }, []);
   const runNow = useCallback2(
@@ -2348,7 +2360,8 @@ function usePilot(transport, opts = {}) {
       ctrl.current?.abort();
       const c = new AbortController();
       ctrl.current = c;
-      if (input.messages.length || input.resume?.length) liveRun.current = input.runId;
+      const steering = typeof input.forwardedProps?.steer === "string";
+      if (!steering && (input.messages.length || input.resume?.length)) liveRun.current = input.runId;
       optsRef.current.onSend?.(input);
       let ended = false;
       try {
@@ -2372,6 +2385,10 @@ function usePilot(transport, opts = {}) {
           commit({ ...ref.current, notice: err instanceof Error ? err.message : null, effects: [] });
           return runNow({ messages: [] }, true);
         }
+        if (steering && !reopening) {
+          commit({ ...ref.current, notice: err instanceof Error && err.message ? err.message : null, effects: [] });
+          return runNow({ messages: [] }, true);
+        }
         commit(sendFailed(ref.current, err instanceof Error && err.message ? err.message : "No se pudo hablar con el agente."));
         return;
       }
@@ -2390,9 +2407,17 @@ function usePilot(transport, opts = {}) {
     ...ref.current.permissions.filter((p) => !answers.current.has(p.id)).map((p) => ({ interruptId: p.id, status: "cancelled" })),
     ...[...answers.current.entries()].map(([interruptId, a]) => ({ interruptId, ...a }))
   ];
+  const steerOn = () => optsRef.current.steer ?? ref.current.agentState.caps?.steer === true;
   const send = useCallback2(
     async (text, attachments = [], _extra = {}) => {
-      if (!transportRef.current || ref.current.busy) return;
+      if (!transportRef.current) return;
+      if (ref.current.busy) {
+        const live = liveRun.current ?? ref.current.runId;
+        if (!steerOn() || !live || !text.trim() || attachments.length) return;
+        commit(beginSteer(ref.current, text));
+        await runNow({ messages: [userMessage(text, [])], forwardedProps: { steer: live } });
+        return;
+      }
       const resume = pendingResume();
       answers.current.clear();
       let s = ref.current;
@@ -2454,7 +2479,27 @@ function usePilot(transport, opts = {}) {
     },
     [commit, sendAnswersIfComplete]
   );
-  return { state, threadId, send, stop, retry, respondPermission, recordDecision, expirePermission };
+  const [loadingOlder, setLoadingOlder] = useState8(false);
+  const loadingRef = useRef4(false);
+  const loadOlder = useCallback2(async () => {
+    const fn = optsRef.current.loadOlder;
+    const h = ref.current.history;
+    if (!fn || !h?.hasMoreBefore || loadingRef.current) return;
+    loadingRef.current = true;
+    setLoadingOlder(true);
+    try {
+      const page = await fn(h.before);
+      if (ref.current.history !== h) return;
+      commit(prependHistory(ref.current, page.messages ?? [], { hasMoreBefore: page.hasMoreBefore === true, ...page.before ? { before: page.before } : {} }));
+    } catch (err) {
+      commit({ ...ref.current, notice: err instanceof Error && err.message ? err.message : null, effects: [] });
+    } finally {
+      loadingRef.current = false;
+      setLoadingOlder(false);
+    }
+  }, [commit]);
+  const canSteer = Boolean(transport) && (opts.steer ?? state.agentState.caps?.steer === true);
+  return { state, threadId, send, stop, retry, respondPermission, recordDecision, expirePermission, canSteer, loadOlder, loadingOlder };
 }
 
 // src/react/Piloto.tsx
@@ -2463,10 +2508,10 @@ var useIsoLayoutEffect = typeof window === "undefined" ? useEffect6 : useLayoutE
 var ANCHOR_GAP = 24;
 var Piloto = forwardRef3(function Piloto2(props, handle) {
   const { transport, pilot: external, locale = "es", theme = "light", features = {}, slots = {} } = props;
-  const own = usePilot(external ? null : transport, props);
+  const own = usePilot(external ? null : transport, features.steer === void 0 ? props : { ...props, steer: features.steer });
   const pilot = external ?? own;
   const { state } = pilot;
-  const { turns, busy, error, notice, permissions } = state;
+  const { turns, busy, error, notice, permissions, olderCount } = state;
   const strings = useMemo3(() => ({ ...locale === "en" ? STRINGS_EN : STRINGS_ES, ...props.strings }), [locale, props.strings]);
   const config = useMemo3(
     () => ({
@@ -2550,6 +2595,18 @@ var Piloto = forwardRef3(function Piloto2(props, handle) {
   const touchY = useRef5(null);
   const [atBottom, setAtBottom] = useState9(true);
   const message = (n) => scroller.current?.querySelector(`[data-turn="${n}"]`) ?? null;
+  const olderSeen = useRef5(olderCount);
+  const heightBefore = useRef5(0);
+  useIsoLayoutEffect(() => {
+    const el = scroller.current;
+    if (el && olderCount > olderSeen.current && heightBefore.current) el.scrollTop += el.scrollHeight - heightBefore.current;
+    olderSeen.current = olderCount;
+    heightBefore.current = 0;
+  }, [olderCount]);
+  const loadOlder = () => {
+    heightBefore.current = scroller.current?.scrollHeight ?? 0;
+    void pilot.loadOlder();
+  };
   const placed = useRef5(false);
   useEffect6(() => {
     if (placed.current || turns.length === 0) return;
@@ -2571,10 +2628,10 @@ var Piloto = forwardRef3(function Piloto2(props, handle) {
   useEffect6(() => {
     if (mine === mineSeen.current) return;
     mineSeen.current = mine;
-    if (mine) setAnchor(mineIndex);
+    if (mine) setAnchor(mineIndex - olderCount);
     following.current = true;
   }, [mine, mineIndex]);
-  const gapAbove = (a) => anchor === 0 ? a.offsetTop : ANCHOR_GAP;
+  const gapAbove = (a) => anchor === -olderCount ? a.offsetTop : ANCHOR_GAP;
   const measureSpacer = useCallback3(() => {
     const sc = scroller.current;
     const sp = spacer.current;
@@ -2636,7 +2693,7 @@ var Piloto = forwardRef3(function Piloto2(props, handle) {
         onSubmit: send,
         onStop: pilot.stop,
         busy,
-        canSteer: false,
+        canSteer: pilot.canSteer,
         placeholder,
         attachments: showFiles,
         upload: props.upload,
@@ -2650,8 +2707,12 @@ var Piloto = forwardRef3(function Piloto2(props, handle) {
       draft.n
     )
   ] });
+  const withPanel = (chat) => slots.sidePanel ? /* @__PURE__ */ jsxs8("div", { className: "flex min-h-0 flex-1 flex-row", children: [
+    /* @__PURE__ */ jsx10("div", { className: "relative flex min-h-0 min-w-0 flex-1 flex-col", children: chat }),
+    slots.sidePanel(state.agentState)
+  ] }) : chat;
   const permissionCards = cards.map((p) => /* @__PURE__ */ jsx10(ConfirmCard, { request: p, onRespond: respond, onSettled: settle, onExpire: pilot.expirePermission }, p.id));
-  return /* @__PURE__ */ jsx10(PilotoContext.Provider, { value: config, children: /* @__PURE__ */ jsx10("div", { ...rootProps(theme, props.skin), "data-busy": busy || void 0, className: `piloto ${props.className ?? ""}`, style: props.style, children: empty ? (
+  return /* @__PURE__ */ jsx10(PilotoContext.Provider, { value: config, children: /* @__PURE__ */ jsx10("div", { ...rootProps(theme, props.skin), "data-busy": busy || void 0, className: `piloto ${props.className ?? ""}`, style: props.style, children: withPanel(empty ? (
     // Un hilo vacío enseña lo mismo que la portada: la cara, el saludo, la caja y por dónde
     // empezar. Si no cabe (panel bajo), se desplaza: `safe center` nunca empuja nada fuera.
     /* @__PURE__ */ jsxs8("div", { className: "gs-scroll flex min-h-0 flex-1 flex-col items-center justify-center overflow-y-auto px-4 pb-[10vh] [justify-content:safe_center]", children: [
@@ -2692,10 +2753,20 @@ var Piloto = forwardRef3(function Piloto2(props, handle) {
         className: "gs-scroll relative min-h-0 flex-1 overflow-y-auto overflow-x-hidden",
         children: [
           /* @__PURE__ */ jsxs8("div", { ref: column, className: "mx-auto flex w-full max-w-[784px] flex-col gap-6 px-4 py-8 sm:px-6", children: [
+            state.history?.hasMoreBefore && (external || props.loadOlder) && /* @__PURE__ */ jsx10(
+              "button",
+              {
+                type: "button",
+                onClick: loadOlder,
+                disabled: pilot.loadingOlder,
+                className: "self-center rounded-full border border-border-primary px-3 py-1 text-sm text-text-secondary transition hover:text-text-primary disabled:opacity-60",
+                children: pilot.loadingOlder ? t.loadingOlder : t.loadOlder
+              }
+            ),
             turns.map((turn, i) => {
               const isLast = i === turns.length - 1;
               const live = busy && isLast;
-              return /* @__PURE__ */ jsx10("div", { "data-turn": i, children: turn.role === "user" ? /* @__PURE__ */ jsx10(UserBubble, { turn }) : /* @__PURE__ */ jsx10(
+              return /* @__PURE__ */ jsx10("div", { "data-turn": i - olderCount, children: turn.role === "user" ? /* @__PURE__ */ jsx10(UserBubble, { turn }) : /* @__PURE__ */ jsx10(
                 AgentBubble,
                 {
                   turn,
@@ -2707,12 +2778,12 @@ var Piloto = forwardRef3(function Piloto2(props, handle) {
                   showDuration: features.duration !== false,
                   renderDeliveries: slots.renderDeliveries
                 }
-              ) }, i);
+              ) }, i - olderCount);
             }),
             permissionCards,
             busy && !toolRunning && !cards.length && /* @__PURE__ */ jsxs8("div", { className: "flex flex-col gap-1.5", children: [
               /* @__PURE__ */ jsx10(TypingDots, {}),
-              /* @__PURE__ */ jsx10(WaitLabel, { since: state.turnStartedAt, showDuration: features.duration !== false })
+              /* @__PURE__ */ jsx10(WaitLabel, { since: state.turnStartedAt, step: state.step, showDuration: features.duration !== false })
             ] }),
             notice && /* @__PURE__ */ jsx10("p", { className: "text-sm text-text-tertiary", children: notice }),
             error && /* @__PURE__ */ jsx10("p", { className: "text-sm text-text-danger", children: error })
@@ -2735,7 +2806,7 @@ var Piloto = forwardRef3(function Piloto2(props, handle) {
       slots.aboveComposer,
       composer
     ] })
-  ] }) }) });
+  ] })) }) });
 });
 export {
   AgentBubble,
@@ -2769,9 +2840,11 @@ export {
   UsageStats,
   UserBubble,
   WaitLabel,
+  applyJsonPatch,
   applyReferences,
   argsDetail,
   beginSend,
+  beginSteer,
   cleanReplyOption,
   cleanUserText,
   createAgUiTransport,
@@ -2788,6 +2861,7 @@ export {
   messagesToTurns,
   mimeOf,
   narrationToMarkdown,
+  prependHistory,
   readSse,
   reduceAgUiEvent,
   renderInline,

package/dist/react/strings.d.ts

@@ -54,6 +54,10 @@ export interface PilotStrings {
     linkOpen: string;
     close: string;
     goToLatest: string;
+    /** La frase de espera de cada paso con nombre (`STEP_STARTED.stepName`). Los que no estén aquí no se pintan. */
+    steps: Record<string, string>;
+    loadOlder: string;
+    loadingOlder: string;
     confirmTitle: string;
     approve: string;
     reject: string;

package/dist/react/usePilot.d.ts

@@ -1,5 +1,5 @@
-import type { BaseEvent, RunAgentInput } from "@ag-ui/core";
-import type { Attachment, Decision, PermissionRequest, PilotState, Reference, Turn } from "../core/types";
+import type { BaseEvent, Message, RunAgentInput } from "@ag-ui/core";
+import type { Attachment, Decision, HistoryPage, PermissionRequest, PilotState, Reference, Turn } from "../core/types";
 import { type PilotTransport } from "../transport";
 export interface TurnDoneInfo {
     /** El texto final de la respuesta. */
@@ -31,6 +31,20 @@ export interface UsePilotOptions {
     onEvent?: (event: BaseEvent) => void;
     /** Cada run que sale (analítica). */
     onSend?: (input: RunAgentInput) => void;
+    /** El estado del agente cambió (`STATE_SNAPSHOT` / `STATE_DELTA` ya aplicado). */
+    onState?: (state: Record<string, unknown>) => void;
+    /**
+     * Steer: mandar con el run vivo (docs/protocol.md §6). Default: lo que diga el agente en
+     * `state.caps.steer`. Sin steer, mandar mientras corre no hace nada.
+     */
+    steer?: boolean;
+    /**
+     * Trae los mensajes anteriores a `before` (el cursor de `CUSTOM ghosty.history`), p. ej. del REST de
+     * lectura de la app. Las páginas empiezan en un mensaje del usuario.
+     */
+    loadOlder?: (before: string | undefined) => Promise<{
+        messages: Message[];
+    } & HistoryPage>;
 }
 export interface SendOptions {
     references?: Reference[];
@@ -49,6 +63,11 @@ export interface Pilot {
     recordDecision: (id: string, status: Decision["status"], asked?: PermissionRequest) => void;
     /** Una tarjeta venció sin contestarse: se anota y su interrupt viaja como `cancelled` en el siguiente run. */
     expirePermission: (id: string) => void;
+    /** Se puede mandar con el run vivo (steer). */
+    canSteer: boolean;
+    /** Antepone la página anterior del hilo (si hay `loadOlder` y `state.history.hasMoreBefore`). */
+    loadOlder: () => Promise<void>;
+    loadingOlder: boolean;
 }
 /** El contexto de la app como `context` de AG-UI: `[{description, value}]`, `value` siempre texto. */
 export declare function toAgUiContext(ctx: unknown): RunAgentInput["context"];

package/dist/styles.css

@@ -511,6 +511,9 @@
 .piloto .flex-col {
   flex-direction: column;
 }
+.piloto .flex-row {
+  flex-direction: row;
+}
 .piloto .flex-wrap {
   flex-wrap: wrap;
 }
@@ -588,6 +591,9 @@
 .piloto :where(.divide-border > :not(:last-child)) {
   border-color: var(--color-border);
 }
+.piloto .self-center {
+  align-self: center;
+}
 .piloto .truncate {
   overflow: hidden;
   text-overflow: ellipsis;
@@ -1404,6 +1410,9 @@
 .piloto .disabled\:opacity-50:disabled {
   opacity: 50%;
 }
+.piloto .disabled\:opacity-60:disabled {
+  opacity: 60%;
+}
 @supports (backdrop-filter: var(--tw)) {
   .piloto .supports-\[backdrop-filter\]\:bg-background\/70 {
     background-color: var(--color-background);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ghostykit",
-  "version": "0.4.1",
+  "version": "0.5.0",
   "description": "Ghosty Autopilot \u2014 the autopilot chat for your React app, on AG-UI: works with LangGraph, Mastra, CrewAI or any AG-UI agent. Streaming text, agent steps, human approval cards (interrupt/resume), attachments and voice.",
   "type": "module",
   "main": "./dist/core/index.js",