@xenosystem/blocks 0.6.0 → 0.8.0

package/dist/agent/host-source.d.ts

@@ -0,0 +1,118 @@
+import { X as XenoAgentSessionDelta, a as XenoAgentEvent } from '../types-C5T3uVwd.js';
+
+/**
+ * The reference adapter: XENO Agent host runtime events → this panel's `session` input.
+ *
+ * ## Why this lives in the PANEL package
+ *
+ * A panel owns its input contract and a host adapts to it — that is how all 24 canonical panels
+ * work. But "the host adapts" left every host to rediscover the same three traps, and this package
+ * had already paid for all three while writing its own harness. So the reference adapter ships
+ * here, beside the contract it targets, as a separate subpath (`@xenosystem/blocks/agent/host-source`)
+ * that a renderer never imports.
+ *
+ * 🔴 **It is written STRUCTURALLY and imports no host type.** `@xeno-corporation/xeno-agent-interface-contract`
+ * is not a dependency and must not become one: this package has zero runtime dependencies by a
+ * publish gate, and a panel that compiled against a host's types would invert the direction the
+ * whole catalogue depends on. The shapes below are what the host emits, restated as the minimum
+ * this adapter reads — and `translate` refuses anything it does not recognise rather than guessing.
+ *
+ * ## The three traps, all measured rather than anticipated
+ *
+ * 1. 🔴 **`rev` must ADVANCE per delta.** The controller drops `rev <= this.rev` **silently**, and
+ *    `Date.now()` is not monotonic enough — three synchronous sends land in one millisecond, so two
+ *    of every three deltas vanish and the failure surfaces somewhere unrelated. `createHostSource`
+ *    owns a counter for exactly this reason; a caller never supplies `rev`.
+ * 2. 🔴 **`session` NESTS its payload under `session`; `turn`, `message` and `tool` are flat.**
+ *    `INTEGRATION.md` documents the payload without showing the nesting, and the author of that
+ *    document got it wrong reading it back.
+ * 3. 🔴 **A streamed reply is ONE record grown by `append`, never one per chunk.** One event per
+ *    token defeats the console's adjacent-duplicate collapsing and is the reason the console gained
+ *    an update-by-id channel at all. `assistantDelta` opens with `text` once and `append`s after.
+ *
+ * ⚠️ **Unrecognised events are COUNTED, not dropped silently.** A host whose vocabulary drifts must
+ * be able to see that it drifted — a source that quietly ignores half its input looks identical to
+ * a quiet agent.
+ */
+
+/** The host envelope, restated as the fields this adapter reads. Structural on purpose. */
+interface HostRuntimeEvent {
+    readonly conversationId: string;
+    readonly requestId?: string;
+    readonly type: string;
+    readonly providerId?: string;
+    readonly parentRunId?: string;
+    readonly subagentRunId?: string;
+    readonly timestamp?: string;
+    readonly event?: Record<string, unknown>;
+}
+/**
+ * A conversation as the host DESCRIBES it, not as it streams.
+ *
+ * 🔴 **The runtime event stream carries no title.** Measured against
+ * `@xeno-corporation/xeno-agent-interface-contract`: a conversation's `title` lives on the
+ * conversation RECORD returned by `conversation.open` / `conversation.list`, and appears on no
+ * runtime envelope. A host that forwards only the event stream therefore shows every conversation
+ * unnamed — which is what happened the first time this chain ran end to end, and which the first
+ * fix made worse by promoting a tool's `label` into the title (see `translate`).
+ *
+ * So the record is its own entry point. Fields the host does not know are simply absent.
+ */
+interface HostConversationRecord {
+    readonly id: string;
+    readonly title?: string;
+    readonly providerId?: string;
+    /** `cloud` | `sdk-native` | `acp` — the panel renders it, it does not interpret it. */
+    readonly lane?: string;
+}
+interface HostSourceOptions {
+    /** Called with each delta, in order. Wire this to `deliverInput('session', delta)`. */
+    readonly emit: (delta: XenoAgentSessionDelta) => void;
+    /** Injectable for tests. Never used for `rev` — see trap 1. */
+    readonly now?: () => number;
+}
+interface HostSourceStats {
+    /** Events this adapter understood and translated. */
+    readonly translated: number;
+    /** Events it did not recognise, by `type`. Reported, never silently dropped. */
+    readonly unrecognised: Readonly<Record<string, number>>;
+}
+/**
+ * The host frame, before any of this can read it.
+ *
+ * 🔴 **A host event is THREE layers deep, and the first version of this adapter read the top one.**
+ * Measured against a running host on 2026-09-06 — real `AgentHostCoordinator`, real ACP turn
+ * adapter, real socket — a turn produced 13 events and this producer translated **zero**:
+ *
+ * ```
+ * outer    { type: "runtime.event.appended", source: "host", payload: { requestId, event: … } }
+ *                                                                                    ↓
+ * runtime    { conversationId, requestId, providerId, providerKind, type: "acp.…", event: … }
+ *                                                                                    ↓
+ * payload      { messageId, text, … }        ← the fields this adapter actually reads
+ * ```
+ *
+ * The MIDDLE layer is `HostRuntimeEvent`, so the structural assumption was right and the entry
+ * point was wrong. Unwrapping is done here rather than by every consumer, because a consumer that
+ * forgets it sees a silent agent — not an error.
+ *
+ * ⚠️ Not every outer event wraps a runtime event: `turn.execution.completed` carries its
+ * conversation and request ids directly on `payload` and has no inner event at all. That one is
+ * the turn's terminal signal, so dropping it would leave a finished turn spinning forever.
+ */
+declare function unwrapHostFrame(frame: Record<string, unknown>): HostRuntimeEvent | null;
+/**
+ * Translate ONE host event into zero or more panel events.
+ *
+ * Pure and exported so a host can test its own vocabulary against this without a panel, a socket,
+ * or a running agent.
+ */
+declare function translate(envelope: HostRuntimeEvent): XenoAgentEvent[];
+declare function createHostSource(options: HostSourceOptions): {
+    push: (frame: HostRuntimeEvent | Record<string, unknown>) => void;
+    session: (record: HostConversationRecord) => void;
+    stats: () => HostSourceStats;
+    reset: () => void;
+};
+
+export { type HostConversationRecord, type HostRuntimeEvent, type HostSourceOptions, type HostSourceStats, createHostSource, translate, unwrapHostFrame };

package/dist/agent/host-source.js

@@ -0,0 +1,228 @@
+import "../chunk-2KG3PWR4.js";
+
+// src/agent/agent/hostSource.ts
+var str = (v) => typeof v === "string" && v.length > 0 ? v : void 0;
+function turnStateOf(type, event) {
+  if (type === "running" || type === "turn.started") return "running";
+  if (type === "turn.completed" || type === "completed") return "succeeded";
+  if (type === "turn.failed" || type === "failed") return "failed";
+  if (type === "turn.cancelled" || type === "cancelled") return "cancelled";
+  if (type === "turn.execution.completed") return "succeeded";
+  if (type === "turn.execution.failed") return "failed";
+  const state = str(event.state);
+  if (type === "turn" && state) return state;
+  return void 0;
+}
+function elicitationOf(type, event) {
+  if (!type.startsWith("elicitation.")) return null;
+  if (type.endsWith(".requested")) {
+    const ask = event.elicitation ?? event.request ?? event;
+    return { ask };
+  }
+  if (type.endsWith(".answer")) {
+    const id = str(event.permissionId) ?? str(event.askUserId) ?? str(event.chooseDirectoryId) ?? str(event.workspacePlacementId) ?? str(event.id);
+    return id ? { withdrawId: id } : null;
+  }
+  return null;
+}
+function unwrapHostFrame(frame) {
+  const type = str(frame.type);
+  if (!type) return null;
+  const payload = frame.payload ?? {};
+  if (type === "runtime.event.appended") {
+    const inner = payload.event;
+    return inner && typeof inner === "object" ? inner : null;
+  }
+  if (str(frame.conversationId)) return frame;
+  const conversationId = str(payload.conversationId) ?? str(frame.conversationId);
+  if (!conversationId) return null;
+  return {
+    conversationId,
+    ...str(payload.requestId) ?? str(frame.requestId) ? { requestId: str(payload.requestId) ?? str(frame.requestId) } : {},
+    type,
+    event: payload
+  };
+}
+function fromAcp(type, event) {
+  if (type === "acp.session.message.delta" || type === "acp.session.message") {
+    const messageId = str(event.messageId);
+    if (!messageId) return null;
+    const text = str(event.text) ?? "";
+    return { message: { messageId, append: text, role: "assistant" } };
+  }
+  if (type === "acp.session.plan") {
+    const content = str(event.content);
+    if (!content) return { ignored: true };
+    return { message: { messageId: `plan-${str(event.id) ?? "current"}`, text: content, role: "system" } };
+  }
+  if (type.startsWith("acp.tool.")) {
+    const callId = str(event.toolCallId);
+    if (!callId) return null;
+    const status = str(event.status) ?? "";
+    const state = type === "acp.tool.completed" || status === "completed" ? status === "failed" ? "failed" : "succeeded" : status === "failed" ? "failed" : "running";
+    return {
+      tool: {
+        callId,
+        // `title` is what a person reads; `toolName` is the tool's id. Later updates carry only the
+        // latter, and the panel keeps the label it was opened with, so passing both is correct.
+        ...str(event.title) ?? str(event.toolName) ? { label: str(event.title) ?? str(event.toolName) } : {},
+        state,
+        ...str(event.kind) ? { detail: { kind: str(event.kind) } } : {}
+      }
+    };
+  }
+  if (type === "acp.session.completed") {
+    return { turn: str(event.status) === "failed" ? "failed" : "succeeded" };
+  }
+  if (type === "acp.session.failed" || type === "acp.agent.failed") return { turn: "failed" };
+  if (type === "acp.agent.started" || type === "acp.session.started") return { turn: "running" };
+  if (type === "acp.session.usage" || type === "acp.session.thought") return { ignored: true };
+  return null;
+}
+function translate(envelope) {
+  const sessionId = envelope.conversationId;
+  if (!sessionId) return [];
+  const event = envelope.event ?? {};
+  const type = envelope.type;
+  const out = [];
+  out.push({
+    type: "session",
+    session: {
+      id: sessionId,
+      title: str(event.title),
+      providerId: envelope.providerId
+    }
+  });
+  const turnId = envelope.requestId;
+  const state = turnStateOf(type, event);
+  if (turnId && state) {
+    out.push({ type: "turn", sessionId, turnId, state, label: str(event.label) });
+  }
+  const elicitation = elicitationOf(type, event);
+  if (elicitation) {
+    if ("ask" in elicitation) out.push({ type: "ask", sessionId, ask: elicitation.ask });
+    else out.push({ type: "ask-withdraw", sessionId, askId: elicitation.withdrawId });
+    return out;
+  }
+  const acp = type.startsWith("acp.") ? fromAcp(type, event) : null;
+  if (acp) {
+    if (acp.turn && turnId) {
+      out.push({ type: "turn", sessionId, turnId, state: acp.turn, label: str(event.title) });
+    }
+    if (acp.message) {
+      out.push({
+        type: "message",
+        sessionId,
+        turnId,
+        messageId: acp.message.messageId,
+        role: acp.message.role,
+        ...acp.message.append !== void 0 ? { append: acp.message.append } : { text: acp.message.text ?? "" }
+      });
+    }
+    if (acp.tool && turnId) {
+      out.push({
+        type: "tool",
+        sessionId,
+        turnId,
+        callId: acp.tool.callId,
+        parentCallId: envelope.parentRunId,
+        ...acp.tool.label ? { label: acp.tool.label } : {},
+        state: acp.tool.state,
+        ...acp.tool.detail ? { detail: acp.tool.detail } : {}
+      });
+    }
+    return out;
+  }
+  if (type === "assistant" || type === "message") {
+    const messageId = str(event.messageId) ?? str(event.id) ?? turnId;
+    if (messageId) {
+      const append = str(event.delta) ?? str(event.append);
+      out.push({
+        type: "message",
+        sessionId,
+        turnId,
+        messageId,
+        role: str(event.role) ?? "assistant",
+        // Trap 3: `append` is the streaming channel; `text` opens or replaces.
+        ...append !== void 0 ? { append } : { text: str(event.text) ?? "" }
+      });
+    }
+    return out;
+  }
+  if (type === "tool" || type.startsWith("tools.")) {
+    const callId = str(event.callId) ?? str(event.toolCallId) ?? str(event.id);
+    if (callId && turnId) {
+      out.push({
+        type: "tool",
+        sessionId,
+        turnId,
+        callId,
+        // A subagent's call nests under the call that spawned it — the recursion `runs` gained.
+        parentCallId: envelope.parentRunId,
+        label: str(event.label) ?? str(event.name) ?? type.replace(/^tools\./, ""),
+        state: str(event.state) ?? "running",
+        detail: str(event.detail),
+        error: str(event.error)
+      });
+    }
+    return out;
+  }
+  return out;
+}
+var IGNORED_TYPES = /* @__PURE__ */ new Set(["acp.session.usage", "acp.session.thought"]);
+function createHostSource(options) {
+  let rev = 0;
+  let translated = 0;
+  const unrecognised = {};
+  return {
+    push(frame) {
+      const envelope = unwrapHostFrame(frame) ?? frame;
+      const events = translate(envelope);
+      const type = envelope.type ?? frame.type;
+      if (events.length <= 1 && type && !IGNORED_TYPES.has(type)) {
+        unrecognised[type] = (unrecognised[type] ?? 0) + 1;
+      } else {
+        translated += 1;
+      }
+      if (events.length === 0) return;
+      rev += 1;
+      options.emit({ rev, events });
+    },
+    /*
+     * Upsert a conversation from the host's own DESCRIPTION of it.
+     *
+     * ⚠️ Deliberately NOT counted as `translated` — that statistic answers "did this adapter
+     * understand the host's event VOCABULARY", and a record the host handed over directly proves
+     * nothing about the stream. Conflating them would let a source that understood no events at
+     * all report a healthy translation count.
+     */
+    session(record) {
+      if (!record.id) return;
+      rev += 1;
+      options.emit({
+        rev,
+        events: [
+          {
+            type: "session",
+            session: {
+              id: record.id,
+              title: record.title,
+              providerId: record.providerId,
+              lane: record.lane
+            }
+          }
+        ]
+      });
+    },
+    stats: () => ({ translated, unrecognised: { ...unrecognised } }),
+    reset() {
+      translated = 0;
+      for (const key of Object.keys(unrecognised)) delete unrecognised[key];
+    }
+  };
+}
+export {
+  createHostSource,
+  translate,
+  unwrapHostFrame
+};