@agentproto/apps 0.8.0 → 0.9.0

package/dist/live-session/index.d.ts

@@ -0,0 +1,46 @@
+/**
+ * McpApp definition for the live-session widget — a two-pane panel (left:
+ * live session tree, right: streaming timeline) that lets a host attach to
+ * any running agent session and watch it work in real time.
+ *
+ * The HTML bundle itself (`LIVE_SESSION_HTML`, its wire protocol, the
+ * inlined timeline-reducer copy, compact-mode rendering, …) lives in
+ * ./panel.ts, which imports nothing beyond plain TS — see that file for the
+ * full protocol/rendering doc. Kept separate so a consumer that only needs
+ * the HTML can import `@agentproto/apps/live-session/panel` without pulling
+ * in `@agentproto/app-kit` (and therefore `@mastra/core`) the way importing
+ * from this file would.
+ *
+ * This module also exports `liveSessionApp`, a real `defineApp()`
+ * `AppHandle` (`agents: []`, UI-only) — the catalog/emit/`app_install` path.
+ * Its `ui.html` is a static snapshot (`LIVE_SESSION_HTML` called with the
+ * default `httpBaseUrl`) since `AppUiDefinition.ui.html` must be a plain
+ * string; it's separate from `makeLiveSessionApp` above, which the daemon
+ * mounts directly at boot with the real daemon origin baked in per-call.
+ */
+import { z } from "zod";
+import { type AppHandle } from "@agentproto/app-kit";
+import type { AgnoMcpApp } from "../mcp-app-types.js";
+import { LIVE_SESSION_HTML, type LiveSessionOutput } from "./panel.js";
+export { LIVE_SESSION_HTML };
+export type { LiveSessionOutput };
+export declare const liveSessionInputSchema: z.ZodObject<{
+    sessionId: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type LiveSessionInput = z.infer<typeof liveSessionInputSchema>;
+export interface LiveSessionOps {
+    /** The daemon's own HTTP origin, e.g. "http://127.0.0.1:18790". Defaults
+     *  to the daemon's documented default port (`index.ts:776`) so the app
+     *  works out of the box in the common single-daemon case. */
+    httpBaseUrl?: string;
+}
+/**
+ * Factory: close over the daemon's own HTTP origin so execute() needs
+ * nothing beyond the tool input (no registry access — mirrors
+ * sessions-panel/index.ts and runtime's terminal-panel-app.ts; the app_*
+ * tools this widget calls over the bridge are what actually touch the
+ * registry).
+ */
+export declare function makeLiveSessionApp(ops?: LiveSessionOps): AgnoMcpApp<LiveSessionInput, LiveSessionOutput>;
+export declare const liveSessionApp: AppHandle;
+//# sourceMappingURL=index.d.ts.map

package/dist/live-session/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/live-session/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AACvB,OAAO,EAAa,KAAK,SAAS,EAAE,MAAM,qBAAqB,CAAA;AAC/D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAA;AACrD,OAAO,EAAE,iBAAiB,EAAE,KAAK,iBAAiB,EAAE,MAAM,YAAY,CAAA;AAEtE,OAAO,EAAE,iBAAiB,EAAE,CAAA;AAC5B,YAAY,EAAE,iBAAiB,EAAE,CAAA;AAEjC,eAAO,MAAM,sBAAsB;;iBAQjC,CAAA;AAEF,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAA;AAErE,MAAM,WAAW,cAAc;IAC7B;;iEAE6D;IAC7D,WAAW,CAAC,EAAE,MAAM,CAAA;CACrB;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAChC,GAAG,CAAC,EAAE,cAAc,GACnB,UAAU,CAAC,gBAAgB,EAAE,iBAAiB,CAAC,CAuBjD;AAID,eAAO,MAAM,cAAc,EAAE,SAY3B,CAAA"}

package/dist/live-session/logic.d.ts

@@ -0,0 +1,125 @@
+/**
+ * Pure, dependency-free reducer for the live-session widget's timeline.
+ *
+ * This module is imported by BOTH the test suite AND (as a hand-kept
+ * inlined copy, since the widget HTML is a self-contained script with no
+ * bundler) `live-session/index.ts`'s browser bundle — see the "INLINED
+ * REDUCER COPY" section there. Keep this file plain TS (no zod, no node
+ * imports, no external deps) so it stays trivially portable to that copy.
+ *
+ * Consumes the `events.jsonl` vocabulary (`{seq,ts,kind,...}`, one record
+ * per line) documented in `.plans/CONTRACT.md`. Unknown `kind`s are ignored
+ * (state passes through unchanged) rather than throwing, since new kinds can
+ * appear in the transcript before the widget knows how to render them.
+ */
+export interface TimelineEventRecord {
+    seq?: number;
+    ts?: string | number;
+    kind: string;
+    sessionId?: string;
+    text?: string;
+    partial?: boolean;
+    toolCallId?: string;
+    toolName?: string;
+    arguments?: unknown;
+    result?: unknown;
+    isError?: boolean;
+    reason?: string;
+    size?: number;
+    used?: number;
+    cost?: number;
+    tokensIn?: number;
+    tokensOut?: number;
+    [key: string]: unknown;
+}
+interface RowBase {
+    /** Stable, deterministic key derived from the record's `seq` (falls back
+     *  to the row's index when `seq` is absent) — never `Date.now()`/random,
+     *  so the same event sequence always reduces to identical row ids. */
+    id: string;
+    seq?: number;
+    ts?: string | number;
+    sessionId?: string;
+}
+export interface TextRow extends RowBase {
+    kind: "text";
+    text: string;
+    /** Reducer-internal continuation hint: true when the LATEST record folded
+     *  into this row was flagged `partial` (an explicitly unterminated debounce
+     *  flush, see transcript-writer.ts). This flag is the ONLY glue signal
+     *  across an interleave — a non-partial record with no trailing "\n" is the
+     *  writer's normal end-of-text-block shape, not a mid-line tear. */
+    partial?: boolean;
+}
+export interface ToolCallRow extends RowBase {
+    kind: "tool-call";
+    toolCallId: string;
+    toolName: string;
+    arguments?: unknown;
+    status: "pending" | "ok" | "error";
+    result?: unknown;
+}
+export interface TurnEndRow extends RowBase {
+    kind: "turn-end";
+    reason?: string;
+}
+export interface UsageInfo {
+    size?: number;
+    used?: number;
+    cost?: number;
+    tokensIn?: number;
+    tokensOut?: number;
+    /** seq/ts of the record that produced this snapshot — last-write-wins. */
+    seq?: number;
+    ts?: string | number;
+}
+export type TimelineRow = TextRow | ToolCallRow | TurnEndRow;
+export interface TimelineState {
+    rows: TimelineRow[];
+    /** Latest known usage snapshot, or null before the first usage_update
+     *  record. Not a row — state, updated in place. */
+    usage: UsageInfo | null;
+}
+export declare function initialTimelineState(): TimelineState;
+/**
+ * Reduce one `events.jsonl` record into the next timeline state. Pure: never
+ * mutates `state` or the record, always returns a fresh state object (or the
+ * same `state` reference for an ignored/unknown kind, so callers can cheaply
+ * check `next === prev` to skip a re-render).
+ */
+export declare function reduceEvent(state: TimelineState, record: TimelineEventRecord): TimelineState;
+export declare const SCROLL_STICK_THRESHOLD_PX = 24;
+/** True when the viewport is close enough to the bottom that new content
+ *  should auto-follow. Pure arithmetic — no DOM access — so it's testable
+ *  outside a browser and the DOM layer can call it with live element
+ *  metrics (`el.scrollHeight`, `el.scrollTop`, `el.clientHeight`). */
+export declare function isNearBottom(scrollHeight: number, scrollTop: number, clientHeight: number, threshold?: number): boolean;
+export declare const TOOL_CALL_GROUP_THRESHOLD = 2;
+export type RowGroupEntry = {
+    kind: "row";
+    row: TimelineRow;
+} | {
+    kind: "tool-group";
+    rows: ToolCallRow[];
+};
+/** Walk `rows` once (order preserved) and collapse runs of `threshold`+
+ *  adjacent tool-call rows into a single `tool-group` entry. A run breaks
+ *  on any non-tool-call row in between (text, turn-end). Non-tool-call rows,
+ *  and tool-call runs shorter than `threshold`, pass through as individual
+ *  `{kind:"row"}` entries — same order as `rows`. */
+export declare function groupAdjacentToolCalls(rows: readonly TimelineRow[], threshold?: number): RowGroupEntry[];
+/**
+ * Pull a session id out of an ext-apps `ui/notifications/tool-result`
+ * payload — the host's push of the tool call that mounted the widget.
+ * Handles both wrapping shapes seen in hosts (`params` IS the
+ * CallToolResult, or nests it under `params.result`) and both body shapes
+ * this widget can be mounted from: an `agent_start` result (a session
+ * descriptor whose id lives in `id`) and a `live_session` result
+ * (`{sessionId, httpBaseUrl}`). `sessionId` wins over `id` when both are
+ * present. Returns `null` for error results, non-JSON text, or any shape
+ * mismatch — never throws. A hand-kept inlined copy lives in
+ * `live-session/index.ts`'s browser bundle (same convention as the reducer).
+ */
+export declare function extractToolResultSessionId(params: unknown): string | null;
+export {};
+//# sourceMappingURL=logic.d.ts.map

package/dist/live-session/logic.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logic.d.ts","sourceRoot":"","sources":["../../src/live-session/logic.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,MAAM,WAAW,mBAAmB;IAClC,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAAA;IACpB,IAAI,EAAE,MAAM,CAAA;IACZ,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,SAAS,CAAC,EAAE,OAAO,CAAA;IACnB,MAAM,CAAC,EAAE,OAAO,CAAA;IAChB,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;CACvB;AAED,UAAU,OAAO;IACf;;0EAEsE;IACtE,EAAE,EAAE,MAAM,CAAA;IACV,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAAA;IACpB,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAED,MAAM,WAAW,OAAQ,SAAQ,OAAO;IACtC,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,EAAE,MAAM,CAAA;IACZ;;;;wEAIoE;IACpE,OAAO,CAAC,EAAE,OAAO,CAAA;CAClB;AAED,MAAM,WAAW,WAAY,SAAQ,OAAO;IAC1C,IAAI,EAAE,WAAW,CAAA;IACjB,UAAU,EAAE,MAAM,CAAA;IAClB,QAAQ,EAAE,MAAM,CAAA;IAChB,SAAS,CAAC,EAAE,OAAO,CAAA;IACnB,MAAM,EAAE,SAAS,GAAG,IAAI,GAAG,OAAO,CAAA;IAClC,MAAM,CAAC,EAAE,OAAO,CAAA;CACjB;AAED,MAAM,WAAW,UAAW,SAAQ,OAAO;IACzC,IAAI,EAAE,UAAU,CAAA;IAChB,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB;AAED,MAAM,WAAW,SAAS;IACxB,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,0EAA0E;IAC1E,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAAA;CACrB;AAED,MAAM,MAAM,WAAW,GAAG,OAAO,GAAG,WAAW,GAAG,UAAU,CAAA;AAE5D,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,WAAW,EAAE,CAAA;IACnB;uDACmD;IACnD,KAAK,EAAE,SAAS,GAAG,IAAI,CAAA;CACxB;AAED,wBAAgB,oBAAoB,IAAI,aAAa,CAEpD;AAeD;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,aAAa,EAAE,MAAM,EAAE,mBAAmB,GAAG,aAAa,CAsH5F;AAID,eAAO,MAAM,yBAAyB,KAAK,CAAA;AAE3C;;;sEAGsE;AACtE,wBAAgB,YAAY,CAC1B,YAAY,EAAE,MAAM,EACpB,SAAS,EAAE,MAAM,EACjB,YAAY,EAAE,MAAM,EACpB,SAAS,GAAE,MAAkC,GAC5C,OAAO,CAET;AAID,eAAO,MAAM,yBAAyB,IAAI,CAAA;AAE1C,MAAM,MAAM,aAAa,GACrB;IAAE,IAAI,EAAE,KAAK,CAAC;IAAC,GAAG,EAAE,WAAW,CAAA;CAAE,GACjC;IAAE,IAAI,EAAE,YAAY,CAAC;IAAC,IAAI,EAAE,WAAW,EAAE,CAAA;CAAE,CAAA;AAE/C;;;;qDAIqD;AACrD,wBAAgB,sBAAsB,CACpC,IAAI,EAAE,SAAS,WAAW,EAAE,EAC5B,SAAS,GAAE,MAAkC,GAC5C,aAAa,EAAE,CA0BjB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,0BAA0B,CAAC,MAAM,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAkBzE"}

package/dist/live-session/panel.d.ts

@@ -0,0 +1,61 @@
+/**
+ * HTML bundle for the agentproto live-session widget — `LIVE_SESSION_HTML`,
+ * a two-pane panel (left: live session tree, right: streaming timeline)
+ * that lets a host attach to any running agent session and watch it work in
+ * real time. Mounted via the `live_session` tool defined in ./index.ts.
+ *
+ * Kept in its own module, importing nothing beyond plain TS, so a consumer
+ * that only needs the HTML (e.g. packages/vscode's story-panel-style
+ * webviews, or a future live-session webview) can import it via the
+ * `@agentproto/apps/live-session/panel` subpath without pulling in
+ * `@agentproto/app-kit` (and therefore `@mastra/core`) the way importing
+ * from `./index.js` would.
+ *
+ * Forked structurally from terminal-panel-app.ts: same "static ui://
+ * resource renders with empty initData, widget self-bootstraps via
+ * tools/call" pattern. Unlike the terminal (one WebSocket, one PTY), this
+ * widget has two independent data needs — a polled tree snapshot and a
+ * per-session event timeline — so it layers on top of the bridge rather
+ * than replacing it with a single socket.
+ *
+ * Data paths (see `.plans/CONTRACT.md` §WP-B):
+ *   LEFT  (tree):     poll `app_session_tree` via `callTool` every ~2s.
+ *   RIGHT (timeline):  PRIMARY = `EventSource` on `/sessions/:id/events/stream`
+ *                      (opportunistic — falls back if it doesn't open/emit
+ *                      within ~2.5s); FALLBACK = poll `app_session_events`
+ *                      via `callTool` every ~1.5s, advancing `since`.
+ *   Both app_* tools are registered by WP-A (`app-pull-tools.ts`) and are
+ *   `visibility: ["app"]`-only, i.e. reachable solely over this bridge.
+ *
+ * The timeline reducer lives in `live-session/logic.ts` as a pure,
+ * dependency-free module so it's unit-testable outside the browser. This
+ * file inlines a hand-kept COPY of that same logic into the HTML bundle
+ * (see "INLINED REDUCER COPY" below) since the widget ships as one
+ * self-contained script with no bundler step. Keep the two in sync. Its MCP
+ * Apps handshake comes from the shared spec-correct panel bridge.
+ *
+ * Rendering (WP1): the timeline body is patched INCREMENTALLY — a
+ * text-delta that merges into the last row patches only that row's text
+ * node (found via `data-row-id`); every other new row is appended with one
+ * `insertAdjacentHTML`. A full `innerHTML` reset happens only on session
+ * start/`setFocus()` and on display-mode switches. Auto-scroll decision is
+ * `isNearBottom` (inlined copy, SPEC §2) captured BEFORE any DOM mutation:
+ * stick to bottom when the user was at the bottom, otherwise preserve the
+ * read position exactly and surface a "new messages" pill.
+ *
+ * Compact mode (WP3/WP4): when `hostContext.displayMode === 'inline'` (or
+ * the viewport is under ~640px) the tree pane collapses into a header
+ * `<select>` (WP4) and the timeline renders through `groupAdjacentToolCalls`
+ * (inlined copy, SPEC §3) with a colour rail and collapsible tool-call
+ * groups. `setFocus()` remains the only session-switch entry point.
+ */
+export type LiveSessionOutput = {
+    /** Echoes the input id, or undefined to let the widget self-discover a
+     *  focus session client-side from `app_session_tree`. */
+    sessionId?: string;
+    /** The daemon's own HTTP origin — connection recipe for both the SSE
+     *  stream and the bridge's `tools/call` fallback. */
+    httpBaseUrl: string;
+};
+export declare function LIVE_SESSION_HTML(initData: LiveSessionOutput): string;
+//# sourceMappingURL=panel.d.ts.map

package/dist/live-session/panel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"panel.d.ts","sourceRoot":"","sources":["../../src/live-session/panel.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkDG;AAIH,MAAM,MAAM,iBAAiB,GAAG;IAC9B;6DACyD;IACzD,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB;yDACqD;IACrD,WAAW,EAAE,MAAM,CAAA;CACpB,CAAA;AAID,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,iBAAiB,GAAG,MAAM,CAs0BrE"}