@xenosystem/blocks 0.6.0 → 0.8.0

package/dist/types-C5T3uVwd.d.ts

@@ -0,0 +1,425 @@
+/**
+ * The `xeno.core.agent` contract — **the session-event shape this panel consumes.**
+ *
+ * ## 🔴 Read this before comparing it to `xeno-agent-interface`
+ *
+ * This file is NOT a copy of that repo's types, and deliberately so. `AgentHostEvent.payload` is
+ * declared `unknown` there and session events ride `event: Record<string, unknown>`, so there is
+ * nothing to import and nothing a compatibility claim could be checked against — the governing
+ * spec says exactly that (`XENO AGENT PANEL - SPEC.md` §D3: *"none of it is typecheckable today"*).
+ *
+ * So this is **the panel declaring its own input port contract**, which is how every other panel in
+ * this catalog works: `xeno.core.runs` did not import a workflow's execution model, it declared
+ * `XenoRunDelta` and hosts adapt. The obligation this creates is the host's and it is stated
+ * plainly in `INTEGRATION.md`: *the host adapts its stream to this shape.* When the host's payloads
+ * are eventually typed, the adapter that already has to exist becomes a typed function instead of
+ * an untyped one — nothing here has to change, and nothing here was ever a guess about a shape
+ * somebody else owns.
+ *
+ * ## What is deliberately NOT modelled here
+ *
+ * A permission, a diff and a terminal write already have canonical shapes, in
+ * `@xenosystem/panel-consent`, `@xenosystem/panel-diff` and `@xenosystem/panel-terminal`. Restating
+ * them would create a second copy of somebody else's contract — the exact failure
+ * `WELL_KNOWN_PORT_SCHEMAS.QUERY_REQUEST` records — so those payloads are **forwarded verbatim**
+ * and typed here only by the fields this package itself reads. Where a shape is described as
+ * "forwarded verbatim", the owning panel's contract is the authority and this one is a courier.
+ *
+ * @module
+ */
+/**
+ * Which execution lane runs a turn.
+ *
+ * Three peers behind one seam, matching the three `AgentTurnExecutionAdapter` implementations that
+ * ship today (`XENO AGENT PANEL - SPEC.md` §D2). ⚠️ They are NOT layered over one another: `cloud`
+ * and `local` never touch ACP, and a panel that presented them as a hierarchy would misdescribe
+ * the only architectural fact a user needs from this control — where their code and their credits
+ * go.
+ */
+type XenoAgentLane = 'cloud' | 'local' | 'acp';
+/** One model a provider offers. */
+interface XenoAgentModel {
+    id: string;
+    label: string;
+    /** Free-form host copy ("128k context", "reasoning"). Rendered verbatim, never parsed. */
+    note?: string;
+}
+/**
+ * One selectable agent.
+ *
+ * 🔴 **`unavailable` is a sentence, not a boolean.** The provider registry ships runnable providers
+ * beside placeholders the capability gate refuses, and "why can I not pick this one?" is the whole
+ * question a user has when they see one greyed out. A boolean answers it with silence.
+ */
+interface XenoAgentProvider {
+    id: string;
+    label: string;
+    lane: XenoAgentLane;
+    models?: XenoAgentModel[];
+    /** Host-authored reason the provider cannot be selected. Absent ⇒ runnable. */
+    unavailable?: string;
+}
+/** The providers the host will accept, and what is currently selected. */
+interface XenoAgentCatalog {
+    providers: XenoAgentProvider[];
+    /** Selected provider id. The HOST is authoritative — the panel never selects on its own. */
+    activeProviderId?: string;
+    activeModelId?: string;
+}
+/**
+ * Where a turn is.
+ *
+ * ⚠️ Chosen so the mapping onto `XenoRunStatus` is total and mechanical (`turnStatusToRunStatus` in
+ * `./projections`). The three that used to have no run-panel equivalent — a turn that has been
+ * asked for but not started, one stopped on a person, one stopped on a grant — are exactly the
+ * three the governing spec asked `xeno.core.runs` to gain, and it has them (`queued`,
+ * `awaiting-decision`, `awaiting-permission`).
+ */
+type XenoAgentTurnState = 'idle' | 'queued' | 'running' | 'waiting-for-user' | 'waiting-for-permission' | 'succeeded' | 'failed' | 'cancelled';
+/** One conversation with one agent. */
+interface XenoAgentSession {
+    id: string;
+    /** Tab/row label. Absent ⇒ the panel shows the id, never a fabricated title. */
+    title?: string;
+    providerId?: string;
+    modelId?: string;
+    lane?: XenoAgentLane;
+    /** Working directory, when the lane has one. Rendered verbatim. */
+    cwd?: string;
+    /** Epoch ms the session was created. Sessions are ordered by this, newest first. */
+    createdAt?: number;
+    /** Current turn state. Absent ⇒ `idle`. */
+    turn?: XenoAgentTurnState;
+    /** Host-authored sentence for `failed`, rendered verbatim. */
+    message?: string;
+}
+/** A message's author. `system` covers host notices; the panel never invents one. */
+type XenoAgentRole = 'user' | 'assistant' | 'system' | 'error';
+/** A typed failure. Never a bare string — a consumer must be able to branch and to group. */
+interface XenoAgentError {
+    code: string;
+    message: string;
+    detail?: string;
+    retryable?: boolean;
+}
+/**
+ * A message opened, extended or closed.
+ *
+ * 🔴 **`text` and `append` are different channels and the difference IS the streaming case.**
+ * `text` sets the body outright; `append` concatenates. A token-streamed reply is one `message`
+ * event carrying `text` (usually `''`, which opens the record) followed by many carrying `append`
+ * — which is exactly the `xeno.core.console` `patch` / `appendMessage` path, and the reason that
+ * path had to exist at all. A producer that sent one event per token with `text` instead would
+ * defeat the console's adjacent-duplicate collapsing and render one row per token.
+ */
+interface XenoAgentMessageEvent {
+    type: 'message';
+    sessionId: string;
+    /** The turn this belongs to, when it belongs to one. */
+    turnId?: string;
+    /** Stable id. The console row key, and the address of every later `append`. */
+    messageId: string;
+    role: XenoAgentRole;
+    /** Epoch ms. Absent ⇒ the projection stamps arrival time. */
+    ts?: number;
+    /** Replace the message body. */
+    text?: string;
+    /** Concatenate onto it — the streaming channel. Applied after `text` within one event. */
+    append?: string;
+    /** No more text is coming. Presentation only; never treated as a turn ending. */
+    done?: boolean;
+}
+/**
+ * A tool call's lifecycle.
+ *
+ * `parentCallId` is what makes this a TREE. A subagent's own tool calls sit at depth 3 under a
+ * turn, which is the case `xeno.core.runs` gained a recursive step model for; flattening it here
+ * would throw the nesting away one layer above the panel that can finally render it.
+ */
+interface XenoAgentToolEvent {
+    type: 'tool';
+    sessionId: string;
+    /** The run this step belongs to. A tool call outside a turn has nowhere to be drawn. */
+    turnId: string;
+    /** Stable id, unique within the turn. */
+    callId: string;
+    /** The enclosing call, when this one was made by a subagent or a nested tool. */
+    parentCallId?: string;
+    /** Display label. Required on the event that OPENS a call; optional on later updates. */
+    label?: string;
+    state: XenoAgentTurnState;
+    /** `0`–`1`. Absent means indeterminate, which is not the same as `0`. */
+    progress?: number;
+    /** Pre-formatted detail lines. The host formats; the panel places. */
+    detail?: Record<string, string>;
+    /** Set when `state === 'failed'`. */
+    error?: XenoAgentError;
+    startedAt?: number;
+    endedAt?: number;
+}
+/** A turn opened, changed state, or ended. */
+interface XenoAgentTurnEvent {
+    type: 'turn';
+    sessionId: string;
+    /** Stable id. Becomes the RUN id in `xeno.core.runs`. */
+    turnId: string;
+    state: XenoAgentTurnState;
+    /** Display label — usually the prompt's first line. */
+    label?: string;
+    startedAt?: number;
+    endedAt?: number;
+    error?: XenoAgentError;
+}
+/** A session appeared or changed. Upsert semantics; the host is authoritative. */
+interface XenoAgentSessionEvent {
+    type: 'session';
+    session: XenoAgentSession;
+}
+/** A session went away. */
+interface XenoAgentSessionClosedEvent {
+    type: 'session-closed';
+    sessionId: string;
+}
+/**
+ * Something the agent needs a human to answer.
+ *
+ * 🔴 **The payload is `@xenosystem/panel-consent`'s `XenoElicitation`, forwarded verbatim**, and
+ * only the two fields this package itself reads are typed. Restating that union here would put a
+ * second copy of a security contract in a package that does not own it — and the copy would be the
+ * one that drifts, because nothing here could notice.
+ *
+ * ⚠️ So the honest statement is: **whether an ask renders at all is `panel-consent`'s decision, not
+ * this panel's.** It refuses a shape it cannot render, visibly, and this panel does not
+ * second-guess that.
+ */
+interface XenoAgentAskEvent {
+    type: 'ask';
+    sessionId: string;
+    turnId?: string;
+    /** The elicitation, in the consent panel's shape. `id` and `title` are all this package reads. */
+    ask: {
+        id: string;
+        title: string;
+        [key: string]: unknown;
+    };
+}
+/** An ask the agent no longer needs answered. */
+interface XenoAgentAskWithdrawEvent {
+    type: 'ask-withdraw';
+    sessionId: string;
+    askId: string;
+}
+/** One file the agent proposes to change. */
+interface XenoAgentPatchFile {
+    path: string;
+    /** Previous path, when renamed. */
+    oldPath?: string;
+    status: 'added' | 'removed' | 'modified' | 'renamed';
+    /**
+     * A unified diff for THIS file — `@@` headers and `+`/`-`/` ` lines.
+     *
+     * 🔴 The reason this package ships a parser. The spec's §D3 measured the mismatch: the host emits
+     * raw unified-diff strings while `xeno.core.diff` requires `XenoDiffLine[]` and *"ships no engine
+     * by charter"*. Its verdict was that the parser is **adapter-side**, and this panel is the
+     * adapter.
+     */
+    diff?: string;
+    /** Language hint, forwarded to the diff panel. Never used to load anything. */
+    language?: string;
+    /**
+     * Why there are no hunks, when the reason is not equality.
+     *
+     * 🔴 Forwarded because the diff panel's whole `omitted` field exists to stop an unread file
+     * reading as an unchanged one. An agent's patch set is precisely where that matters: a binary
+     * blob shown as "no changes" is content nobody looked at, approved.
+     */
+    omitted?: 'binary' | 'tooLarge' | 'unreadable' | 'identical';
+}
+/** A proposed change set, awaiting review. */
+interface XenoAgentPatchEvent {
+    type: 'patch';
+    sessionId: string;
+    turnId?: string;
+    /** Stable id for the change set — the correlation key a decision comes back on. */
+    patchId: string;
+    files: XenoAgentPatchFile[];
+    /** Labels for the two sides ("HEAD" / "Agent proposal"). */
+    oldLabel?: string;
+    newLabel?: string;
+}
+/**
+ * Raw terminal output, or a terminal's lifecycle.
+ *
+ * Both halves are forwarded verbatim to `xeno.core.terminal`: `data` is raw bytes as a string with
+ * escape sequences intact (**never pre-parsed — the emulator is the parser**) and `session` is that
+ * panel's `XenoTerminalSession`.
+ */
+interface XenoAgentTerminalEvent {
+    type: 'terminal';
+    sessionId: string;
+    /** The terminal instance id, as `xeno.core.terminal` addresses it. */
+    terminalId: string;
+    /** Raw bytes as a string. */
+    data?: string;
+    /** Lifecycle, in the terminal panel's shape. Forwarded verbatim. */
+    session?: {
+        id: string;
+        status: string;
+        [key: string]: unknown;
+    };
+}
+/** Everything a host can deliver on the `session` port. */
+type XenoAgentEvent = XenoAgentSessionEvent | XenoAgentSessionClosedEvent | XenoAgentTurnEvent | XenoAgentMessageEvent | XenoAgentToolEvent | XenoAgentAskEvent | XenoAgentAskWithdrawEvent | XenoAgentPatchEvent | XenoAgentTerminalEvent;
+/**
+ * A batch of events.
+ *
+ * ⚠️ A LIST, not one event per envelope, for the same reason every other panel in this catalog
+ * takes a delta: a streaming turn produces events far faster than a wire should carry envelopes,
+ * and one envelope per token is the thousand-array-copies non-starter in a second costume.
+ */
+interface XenoAgentSessionDelta {
+    /** Monotonic revision. A delta whose rev has not advanced is dropped. */
+    rev?: number;
+    events?: XenoAgentEvent[];
+    /** Replace the session index outright (the host reconnected). */
+    replace?: XenoAgentSession[];
+    /** Drop everything. Wins over `events` in the same delta. */
+    clear?: boolean;
+}
+/** Whether the panel is connected to an agent host at all. */
+type XenoAgentConnection = 'idle' | 'connecting' | 'ready' | 'failed';
+/** Connection state, out of band. */
+interface XenoAgentStatus {
+    status: XenoAgentConnection;
+    /** Host-authored sentence, rendered verbatim. */
+    message?: string;
+}
+/**
+ * The single thing the host acts on.
+ *
+ * 🔴 **One output port, not eight.** The answers this panel forwards — a consent decision, a hunk
+ * decision, a run action, a terminal keystroke — arrive from the canonical panels carrying no
+ * session id, because none of those panels knows sessions exist. Something has to correlate them,
+ * and the only place that already holds the map is the translator that minted the ask. Handing the
+ * host eight raw streams instead would move that bookkeeping into every host — which is how the
+ * four bespoke agent UIs the spec measured came to exist.
+ */
+type XenoAgentIntent = 
+/** Run a prompt. ⚠️ The panel clears its composer only once the host confirms a turn. */
+{
+    type: 'prompt';
+    sessionId: string;
+    text: string;
+    providerId?: string;
+    modelId?: string;
+}
+/** Stop the running turn. */
+ | {
+    type: 'cancel';
+    sessionId: string;
+    turnId?: string;
+}
+/**
+ * Steer a running turn.
+ *
+ * ⚠️ **Lands at the agent's NEXT decision point, not instantly** — proven against real Claude
+ * Code, and recorded as a caveat in the ADE spec. A view must not imply otherwise.
+ */
+ | {
+    type: 'steer';
+    sessionId: string;
+    text: string;
+} | {
+    type: 'select-session';
+    sessionId: string;
+} | {
+    type: 'new-session';
+    providerId?: string;
+    modelId?: string;
+} | {
+    type: 'select-provider';
+    sessionId: string;
+    providerId: string;
+    modelId?: string;
+}
+/** A consent decision or elicitation result, correlated back to its session. Payload verbatim. */
+ | {
+    type: 'answer';
+    sessionId: string;
+    askId: string;
+    answer: Record<string, unknown>;
+}
+/** A hunk decision, correlated back to its session and change set. Payload verbatim. */
+ | {
+    type: 'patch-decision';
+    sessionId: string;
+    patchId: string;
+    decision: Record<string, unknown>;
+}
+/** Cancel or retry a turn, or one of its tool calls. */
+ | {
+    type: 'run-action';
+    sessionId: string;
+    turnId: string;
+    action: 'cancel' | 'retry';
+    /** The tool call, when a step was targeted rather than the whole turn. */
+    callId?: string;
+}
+/** A terminal intent, correlated back to its session. Payload verbatim. */
+ | {
+    type: 'terminal';
+    sessionId: string;
+    terminal: Record<string, unknown>;
+};
+/** Persisted panel state. **Preferences plus the unsent draft** — never a session, never a transcript. */
+interface AgentPanelState {
+    activeSessionId?: string | null;
+    /**
+     * The unsent composer text.
+     *
+     * ⚠️ Persisted deliberately, and it is the ONE piece of content here. A half-typed prompt lost to
+     * a layout change is the single most annoying thing a chat surface can do, and it is the user's
+     * own text rather than host state. Nothing else is kept — a transcript belongs to the host, and
+     * `.xapp` is a plain JSON file that may contain nothing sensitive.
+     */
+    draft?: string;
+}
+/** What the view renders. */
+interface AgentViewState {
+    sessions: XenoAgentSession[];
+    /** The session being shown, or `null` when there is none. */
+    active: XenoAgentSession | null;
+    /** Its turn state, resolved. `idle` when there is no session. */
+    turn: XenoAgentTurnState;
+    connection: XenoAgentConnection;
+    /** Host-authored sentence for a failed connection or a failed turn. */
+    message: string | null;
+    providers: XenoAgentProvider[];
+    activeProvider: XenoAgentProvider | null;
+    activeModelId: string | null;
+    draft: string;
+    /**
+     * Would `submit()` do anything right now?
+     *
+     * Computed from the SAME predicate `submit()` enforces, so an enabled button cannot be a button
+     * that refuses — the affordance and the guard can never disagree. (The rule `xeno.core.consent`
+     * arrived at, applied here for the same reason.)
+     */
+    canSubmit: boolean;
+    /** Is a turn in flight, so the composer offers Stop rather than Send? */
+    busy: boolean;
+    /** How many asks are outstanding across every session. */
+    pendingAsks: number;
+}
+/** Is the agent doing something a Stop would interrupt? */
+declare function isBusy(turn: XenoAgentTurnState): boolean;
+/**
+ * Is the turn stopped on a human?
+ *
+ * Separate from {@link isBusy} because folding the two together is how a surface reports a working
+ * agent while it sits on a permission prompt nobody has seen — the same distinction
+ * `xeno.core.runs` draws between `active` and `waiting`, and for the same reason.
+ */
+declare function isWaitingOnUser(turn: XenoAgentTurnState): boolean;
+
+export { type AgentViewState as A, type XenoAgentSessionDelta as X, type XenoAgentEvent as a, type XenoAgentTurnState as b, type XenoAgentCatalog as c, type XenoAgentConnection as d, type AgentPanelState as e, type XenoAgentAskEvent as f, type XenoAgentAskWithdrawEvent as g, type XenoAgentError as h, type XenoAgentIntent as i, type XenoAgentLane as j, type XenoAgentMessageEvent as k, type XenoAgentModel as l, type XenoAgentPatchEvent as m, type XenoAgentPatchFile as n, type XenoAgentProvider as o, type XenoAgentRole as p, type XenoAgentSession as q, type XenoAgentSessionClosedEvent as r, type XenoAgentSessionEvent as s, type XenoAgentStatus as t, type XenoAgentTerminalEvent as u, type XenoAgentToolEvent as v, type XenoAgentTurnEvent as w, isBusy as x, isWaitingOnUser as y };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xenosystem/blocks",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "description": "XENO Blocks \u2014 rung 3 of the front ladder: components composed into a contract-bearing unit (manifest: ports, intents, commands, agent surface), rendered by @xenosystem/workbench. ONE package, one subpath per family (/auth, /edit, /data, /time, /ops, /trust, /agent), one named export per block \u2014 XENO PACKAGE NAMING - STANDARD.md.",
   "license": "UNLICENSED",
   "type": "module",
@@ -37,6 +37,14 @@
     "./edit": {
       "types": "./dist/edit/index.d.ts",
       "import": "./dist/edit/index.js"
+    },
+    "./agent": {
+      "types": "./dist/agent/index.d.ts",
+      "import": "./dist/agent/index.js"
+    },
+    "./agent/host-source": {
+      "types": "./dist/agent/host-source.d.ts",
+      "import": "./dist/agent/host-source.js"
     }
   },
   "files": [
@@ -52,12 +60,10 @@
   "peerDependencies": {
     "@xenosystem/components": "^0.6.0",
     "@xenosystem/elements-react": ">=0.0.1",
-    "@xenosystem/panel-account": "^0.1.0",
-    "@xenosystem/panel-sdk": "^1.1.0",
     "@xenosystem/workbench": "^1.0.0",
     "react": ">=18.0.0",
     "react-dom": ">=18.0.0",
-    "@xenosystem/block-sdk": "^0.1.1",
+    "@xenosystem/block-sdk": "^0.2.0",
     "@xenosystem/tree-core": "^0.1.0",
     "@xterm/xterm": ">=5.5.0",
     "@xterm/addon-fit": ">=0.10.0",
@@ -71,8 +77,6 @@
     "@types/react-dom": "^19.0.0",
     "@xenosystem/components": "^0.6.0",
     "@xenosystem/elements-react": "0.0.1",
-    "@xenosystem/panel-account": "^0.1.0",
-    "@xenosystem/panel-sdk": "^1.1.0",
     "@xenosystem/workbench": "^1.0.0",
     "jsdom": "^26.0.0",
     "react": "^19.0.0",
@@ -80,7 +84,7 @@
     "tsup": "^8.0.0",
     "typescript": "^5.4.0",
     "vitest": "^4.1.0",
-    "@xenosystem/block-sdk": "^0.1.1",
+    "@xenosystem/block-sdk": "^0.2.0",
     "@xenosystem/tree-core": "^0.1.0",
     "@xterm/xterm": "^6.0.0",
     "@xterm/addon-fit": "^0.11.0",