@buckeyestudio/pi-wire 18.4.13

package/CHANGELOG.md

@@ -0,0 +1,82 @@
+# Changelog
+
+## [Unreleased]
+
+## [18.4.11] - 2026-10-02
+
+### Added
+
+- Added support for agent completion estimates in the wire protocol.
+
+## [18.4.9] - 2026-10-01
+
+### Added
+
+- Added terminal scrolling support through the TSP scroll operation, allowing keyboard scrolling of the terminal scroller when supported.
+- Added a terminal focus event for requesting keyboard focus on editors and inputs, or returning focus to the preferences sheet.
+
+## [18.4.6] - 2026-10-01
+
+### Added
+
+- Added the `TspMeterMark` component for marking a position on a meter track with a custom icon and a total value that defines the full span of the track.
+
+## [18.4.4] - 2026-09-29
+
+### Added
+
+- Added the Tern Surface Protocol wire contract (`@oh-my-pi/pi-wire`): message framing constants, the component vocabulary, document ops, frames, the handshake and terminal events that let omp render natively in terminals that speak it
+
+## [18.2.11] - 2026-09-23
+
+### Added
+
+- Added public API contract and authentication schemas for the Skillshare registry.
+
+## [18.2.5] - 2026-09-17
+
+### Added
+
+- Added the `omp stream` wire contract (`@oh-my-pi/pi-wire/stream`) for pane screen updates, viewer snapshots and chat, channel metadata, and `live.omp.sh` stream routes.
+- Added authentication support for stencil.so streams, including user identity in welcome messages, channel ownership metadata, and explicit unauthorized and forbidden close codes.
+
+### Changed
+
+- Restricted channel names to the Stencil-compatible alphanumeric-and-underscore format and derived host channels from authentication tokens rather than URL path segments.
+
+## [16.3.0] - 2026-07-02
+
+### Breaking Changes
+
+- Upgraded the collaboration protocol to version 3. Guests using version 2 will now be rejected during the handshake with a protocol-mismatch error.
+
+### Added
+
+- Added support for interactive UI request and response frames, enabling browser guests to respond to prompts initiated by the host.
+
+## [16.1.8] - 2026-06-20
+
+### Breaking Changes
+
+- Bumped `COLLAB_PROTO` to `2`. The `welcome` host frame now carries metadata only (`header`, `state`, `agents`, `entryCount`, optional `readOnly`) — the transcript moves to a new `snapshot-chunk` host frame (`{ entries: SessionEntry[]; final: boolean }`) sent immediately after the welcome. Hosts split large snapshots into multiple chunks; the last chunk carries `final: true`. Old guests speaking proto v1 are rejected with the existing protocol-mismatch error. ([#3144](https://github.com/can1357/oh-my-pi/issues/3144))
+
+## [15.12.4] - 2026-06-13
+
+### Changed
+
+- Changed `WireModel.contextWindow` and `ContextUsage.contextWindow` to `number | null` to allow representing unavailable context-window values
+
+## [15.12.0] - 2026-06-12
+
+### Added
+
+- Added `readOnly` flags to participant and session payload types to indicate when a guest is connected via a read-only (view) link
+- Added `writeToken` to `GuestFrame` hello payloads and parsed collaboration links so full-access links can carry and expose a write-capability token
+- Added `ROOM_KEY_BYTES` and `WRITE_TOKEN_BYTES` constants for room key and write-token sizing in the wire protocol
+- Added `DEFAULT_SHARE_URL` (`https://my.omp.sh/s`), the default share viewer/upload base for `/share` links
+
+## [15.11.8] - 2026-06-12
+
+### Added
+
+- Added shared collab live-session wire contracts for the host CLI and browser guest client.

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2025-2026 Can Bölük
+Copyright (c) 2026 Stencil Labs, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,31 @@
+# @buckeyestudio/pi-wire
+
+Shared TypeScript wire contracts for omp collab live sessions.
+
+The package contains only JSON-safe protocol shapes and constants. It has no runtime dependencies and is consumed by both the host CLI (`@buckeyestudio/pi-coding-agent`) and browser guest (`@buckeyestudio/collab-web`).
+
+## Exports
+
+```ts
+import type { GuestFrame, HostFrame, SessionEntry } from "@buckeyestudio/pi-wire";
+import { COLLAB_PROTO, DEFAULT_RELAY_URL, ENVELOPE_HEADER_LENGTH } from "@buckeyestudio/pi-wire";
+```
+
+Key groups:
+
+- message and transcript entry shapes rendered by collab guests,
+- live agent event and task-subagent bus payload shapes,
+- `GuestFrame`, `HostFrame`, and `WireFrame` unions for AES-GCM sealed payloads,
+- relay control TEXT messages,
+- link/envelope constants shared by host, guest, and local relay code.
+
+## Protocol boundary
+
+`pi-wire` does not encode, decode, validate, encrypt, or route frames. It defines the shared contract used at those boundaries:
+
+1. callers build a `GuestFrame` or `HostFrame`,
+2. transport code serializes it as JSON inside an encrypted payload,
+3. relay code routes opaque envelopes using the plaintext peer-id prefix,
+4. receivers switch on `frame.t` and tolerate unknown future fields.
+
+Keep protocol changes backward-aware: bump `COLLAB_PROTO` only when old hosts and guests must reject each other.

package/package.json

@@ -0,0 +1,54 @@
+{
+  "type": "module",
+  "name": "@buckeyestudio/pi-wire",
+  "version": "18.4.13",
+  "description": "Shared wire protocol types for omp packages",
+  "homepage": "https://omp.sh",
+  "author": { "name": "Stencil Labs, Inc.", "url": "https://stencil.so" },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/can1357/oh-my-pi.git",
+    "directory": "packages/wire"
+  },
+  "bugs": {
+    "url": "https://github.com/can1357/oh-my-pi/issues"
+  },
+  "keywords": [
+    "wire",
+    "protocol",
+    "types",
+    "collab"
+  ],
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "scripts": {
+    "check": "oxlint . && oxfmt --check --no-error-on-unmatched-pattern 'src/**/*.{ts,tsx}' '{test,bench,examples,scripts}/**/*.ts' '*.ts' && bun run check:types",
+    "check:types": "tsgo -p tsconfig.json --noEmit",
+    "lint": "oxlint .",
+    "fix": "oxlint --fix --fix-suggestions . && bun run fmt",
+    "fmt": "oxfmt --no-error-on-unmatched-pattern 'src/**/*.{ts,tsx}' '{test,bench,examples,scripts}/**/*.ts' '*.ts'"
+  },
+  "devDependencies": {
+    "@types/bun": "catalog:"
+  },
+  "engines": {
+    "bun": ">=1.3.14"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "import": "./src/index.ts"
+    },
+    "./*": {
+      "types": "./src/*.ts",
+      "import": "./src/*.ts"
+    },
+    "./*.js": "./src/*.ts"
+  }
+}

package/src/index.ts

@@ -0,0 +1,451 @@
+/**
+ * Shared wire types for the omp collab live-session protocol.
+ *
+ * Dependency-free JSON shapes produced by `@buckeyestudio/pi-coding-agent`
+ * (`src/collab/protocol.ts` and friends). Browser and test clients import this
+ * package instead of depending on the coding-agent runtime; conformance is
+ * asserted type-only in `packages/coding-agent/test/collab/web-wire.types.ts`.
+ *
+ * Unknown entry/event variants arrive over the wire as plain JSON. The unions
+ * below cover only the variants this client renders; consumers cast at the
+ * JSON boundary and every `switch` keeps a tolerant `default:` branch.
+ */
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Content blocks
+// ═══════════════════════════════════════════════════════════════════════════
+
+export interface TextContent {
+	type: "text";
+	text: string;
+}
+
+export interface ImageContent {
+	type: "image";
+	/** Base64-encoded image data. */
+	data: string;
+	/** e.g. "image/png". */
+	mimeType: string;
+}
+
+export interface ThinkingContent {
+	type: "thinking";
+	thinking: string;
+}
+
+export interface RedactedThinkingContent {
+	type: "redactedThinking";
+	data: string;
+}
+
+export interface ToolCallContent {
+	type: "toolCall";
+	id: string;
+	name: string;
+	arguments: Record<string, unknown>;
+	intent?: string;
+}
+
+export type AssistantContent = TextContent | ThinkingContent | RedactedThinkingContent | ToolCallContent;
+
+export type StopReason = "stop" | "length" | "toolUse" | "error" | "aborted";
+
+export interface WireUsage {
+	input: number;
+	output: number;
+	cacheRead: number;
+	cacheWrite: number;
+	totalTokens: number;
+	cost: { total: number };
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Messages
+// ═══════════════════════════════════════════════════════════════════════════
+
+export interface UserMessage {
+	role: "user";
+	content: string | (TextContent | ImageContent)[];
+	/** True if the message was injected by the system (e.g. auto-continue). */
+	synthetic?: boolean;
+	/** Unix timestamp in milliseconds. */
+	timestamp: number;
+}
+
+export interface DeveloperMessage {
+	role: "developer";
+	content: string | (TextContent | ImageContent)[];
+	timestamp: number;
+}
+
+export interface AssistantMessage {
+	role: "assistant";
+	content: AssistantContent[];
+	model: string;
+	usage: WireUsage;
+	stopReason: StopReason;
+	errorMessage?: string;
+	timestamp: number;
+}
+
+export interface ToolResultMessage {
+	role: "toolResult";
+	toolCallId: string;
+	toolName: string;
+	content: (TextContent | ImageContent)[];
+	details?: unknown;
+	isError: boolean;
+	timestamp: number;
+}
+
+export type WireMessage = UserMessage | DeveloperMessage | AssistantMessage | ToolResultMessage;
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Session entries (rendered subset; cast `as SessionEntry` at the JSON
+// boundary and skip unknown `type`s in a tolerant `default:`)
+// ═══════════════════════════════════════════════════════════════════════════
+
+export interface SessionHeader {
+	type: "session";
+	id: string;
+	title?: string;
+	timestamp: string;
+	cwd: string;
+}
+
+export interface EntryBase {
+	id: string;
+	parentId: string | null;
+	timestamp: string;
+}
+
+export interface MessageEntry extends EntryBase {
+	type: "message";
+	message: WireMessage;
+}
+
+export interface CustomMessageEntry extends EntryBase {
+	type: "custom_message";
+	customType: string;
+	content: string | (TextContent | ImageContent)[];
+	details?: unknown;
+	display: boolean;
+}
+
+export interface CompactionEntry extends EntryBase {
+	type: "compaction";
+	summary: string;
+	shortSummary?: string;
+	firstKeptEntryId: string;
+	tokensBefore: number;
+}
+
+export interface BranchSummaryEntry extends EntryBase {
+	type: "branch_summary";
+	fromId: string;
+	summary: string;
+}
+
+export interface ModelChangeEntry extends EntryBase {
+	type: "model_change";
+	/** Model in "provider/modelId" format. */
+	model: string;
+	role?: string;
+}
+
+export interface ThinkingLevelChangeEntry extends EntryBase {
+	type: "thinking_level_change";
+	thinkingLevel?: string | null;
+}
+
+export type SessionEntry =
+	| MessageEntry
+	| CustomMessageEntry
+	| CompactionEntry
+	| BranchSummaryEntry
+	| ModelChangeEntry
+	| ThinkingLevelChangeEntry;
+
+/** customType of collab guest prompts injected on the host. */
+export const COLLAB_PROMPT_MESSAGE_TYPE = "collab-prompt";
+
+/** `details` shape of `custom_message` entries with `customType === "collab-prompt"`. */
+export interface CollabPromptDetails {
+	from?: string;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Events (handled subset)
+// ═══════════════════════════════════════════════════════════════════════════
+
+export type AgentEvent =
+	| { type: "agent_start" }
+	| { type: "agent_end" }
+	| { type: "turn_start" }
+	| { type: "turn_end" }
+	| { type: "message_start"; message: WireMessage }
+	/** Carries the FULL accumulating partial message — no delta tracking needed. */
+	| { type: "message_update"; message: WireMessage }
+	| { type: "message_end"; message: WireMessage }
+	| { type: "tool_execution_start"; toolCallId: string; toolName: string; args: unknown; intent?: string }
+	| { type: "tool_execution_update"; toolCallId: string; toolName: string; args: unknown; partialResult: unknown }
+	| { type: "tool_execution_end"; toolCallId: string; toolName: string; result: unknown; isError?: boolean }
+	| { type: "notice"; level: "info" | "warning" | "error"; message: string; source?: string }
+	| { type: "auto_compaction_start"; reason: string; action: string }
+	| { type: "auto_compaction_end"; aborted: boolean; willRetry: boolean; errorMessage?: string; skipped?: boolean }
+	| { type: "auto_retry_start"; attempt: number; maxAttempts: number; delayMs: number; errorMessage: string }
+	| { type: "auto_retry_end"; success: boolean; attempt: number; finalError?: string }
+	| { type: "thinking_level_changed"; thinkingLevel?: string };
+
+// ═══════════════════════════════════════════════════════════════════════════
+// State & agents
+// ═══════════════════════════════════════════════════════════════════════════
+
+export interface WireModel {
+	id: string;
+	name: string;
+	provider: string;
+	contextWindow: number | null;
+}
+
+export interface ContextUsage {
+	tokens: number | null;
+	contextWindow: number | null;
+	percent: number | null;
+}
+
+export interface Participant {
+	name: string;
+	role: "host" | "guest";
+	/** True when the guest joined through a read-only (view) link. */
+	readOnly?: boolean;
+}
+
+/** Debounced footer snapshot broadcast by the host. */
+export interface SessionState {
+	isStreaming: boolean;
+	queuedMessageCount: number;
+	sessionName?: string;
+	/** Host cwd — display only; the guest never chdirs. */
+	cwd: string;
+	model?: WireModel;
+	thinkingLevel?: string;
+	contextUsage?: ContextUsage;
+	participants: Participant[];
+	isAborting?: boolean;
+}
+
+export interface AgentSnapshot {
+	id: string;
+	displayName: string;
+	kind: "main" | "sub";
+	parentId?: string;
+	status: "running" | "idle" | "parked" | "aborted";
+	/** Whether the host has a transcript file for this agent (gates remote transcript fetch). */
+	hasSessionFile: boolean;
+	createdAt: number;
+	lastActivity: number;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Bus payloads (task subagent lifecycle/progress channels)
+// ═══════════════════════════════════════════════════════════════════════════
+
+export interface AgentProgress {
+	index: number;
+	id: string;
+	agent: string;
+	status: "pending" | "running" | "completed" | "failed" | "aborted";
+	task: string;
+	description?: string;
+	lastIntent?: string;
+	currentTool?: string;
+	currentToolArgs?: string;
+	/** Argument key selected for the display preview, when known. */
+	currentToolArgsKey?: string;
+	/** Intent the model attached to the current call; undefined when that call carried none. */
+	currentToolIntent?: string;
+	currentToolStartMs?: number;
+	recentTools: { tool: string; args: string; argsKey?: string; intent?: string; isError?: boolean; endMs: number }[];
+	recentOutput: string[];
+	toolCount: number;
+	requests: number;
+	tokens: number;
+	contextTokens?: number;
+	contextWindow?: number;
+	cost: number;
+	durationMs: number;
+	resolvedModel?: string;
+}
+
+export interface SubagentProgressPayload {
+	index: number;
+	agent: string;
+	task: string;
+	parentToolCallId?: string;
+	assignment?: string;
+	progress: AgentProgress;
+	sessionFile?: string;
+}
+
+export interface SubagentLifecyclePayload {
+	id: string;
+	agent: string;
+	description?: string;
+	status: "started" | "completed" | "failed" | "aborted";
+	sessionFile?: string;
+	parentToolCallId?: string;
+	index: number;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Frames (JSON inside the AES-GCM seal)
+// ═══════════════════════════════════════════════════════════════════════════
+
+export type CollabUiSelectItem = string | { label: string; description?: string };
+
+export type CollabUiResponseValue = string | undefined;
+
+export type CollabUiRequestDraft =
+	| {
+			kind: "select";
+			title: string;
+			options: CollabUiSelectItem[];
+			initialIndex?: number;
+			selectionMarker?: "radio" | "checkbox";
+			checkedIndices?: number[];
+			markableCount?: number;
+			helpText?: string;
+	  }
+	| {
+			kind: "editor";
+			title: string;
+			prefill?: string;
+	  };
+
+export type CollabUiRequest = CollabUiRequestDraft & { reqId: number };
+
+export type GuestFrame =
+	| {
+			t: "hello";
+			proto: number;
+			name: string;
+			/**
+			 * base64url write token proving full-link possession; absent for
+			 * read-only (view) links. The host marks peers without a valid token
+			 * read-only and rejects their mutating frames.
+			 */
+			writeToken?: string;
+	  }
+	| { t: "prompt"; text: string; images?: ImageContent[] }
+	| { t: "ui-response"; reqId: number; value?: CollabUiResponseValue }
+	| { t: "abort" }
+	| { t: "agent-cmd"; cmd: "chat" | "kill" | "revive"; agentId: string; text?: string }
+	| { t: "fetch-transcript"; reqId: number; agentId: string; fromByte: number };
+
+/** EventBus channels mirrored to guests (task subagent traffic only). */
+export type BusChannel = "task:subagent:progress" | "task:subagent:lifecycle";
+
+export type HostFrame =
+	| {
+			t: "welcome";
+			proto: number;
+			header: SessionHeader;
+			state: SessionState;
+			agents: AgentSnapshot[];
+			/**
+			 * Total number of `SessionEntry` items the host will deliver in the
+			 * `snapshot-chunk` frames that follow. Guests stay in the loading
+			 * phase until they have accumulated all of them (or a chunk arrives
+			 * with `final: true`).
+			 */
+			entryCount: number;
+			/** True when this peer joined through a read-only (view) link. */
+			readOnly?: boolean;
+	  }
+	/**
+	 * Targeted snapshot fragment delivered after `welcome`. Hosts split the
+	 * transcript into chunks bounded by byte size so a multi-MB session is not
+	 * forced through one giant frame the relay may stall on. The last chunk
+	 * carries `final: true`; guests finalize the replica on that frame.
+	 */
+	| { t: "snapshot-chunk"; entries: SessionEntry[]; final: boolean }
+	| { t: "entry"; entry: SessionEntry }
+	| { t: "event"; event: AgentEvent }
+	| { t: "state"; state: SessionState }
+	/** Mirrored EventBus traffic (task subagent lifecycle/progress channels only). */
+	| { t: "bus"; channel: BusChannel; data: unknown }
+	| { t: "agents"; agents: AgentSnapshot[] }
+	| { t: "ui-request"; request: CollabUiRequest }
+	| { t: "ui-request-end"; reqId: number }
+	/** Targeted reply to fetch-transcript; `text` is decoded JSONL from `fromByte`, `newSize` the next offset base. */
+	| { t: "transcript"; reqId: number; text: string; newSize: number; error?: string }
+	| { t: "bye"; reason: string }
+	| { t: "error"; message: string };
+
+export type WireFrame = GuestFrame | HostFrame;
+
+/**
+ * Wire protocol version carried in `hello`; the host rejects mismatches.
+ *
+ * - `1` (legacy): `welcome` carried the full `entries` array inline.
+ * - `2`: `welcome` carries only metadata (header/state/agents/entryCount);
+ *   transcript entries follow in `snapshot-chunk` frames, so multi-MB
+ *   sessions are not gated on a single welcome frame fitting under the
+ *   guest's first-welcome timeout.
+ * - `3`: host asks guests through `ui-request`/`ui-request-end` host frames
+ *   answered by the `ui-response` guest frame. Guests that predate the
+ *   grammar would silently drop `ui-request` (asks hang forever on the
+ *   host), so they must be rejected at hello.
+ */
+export const COLLAB_PROTO = 3;
+
+/** Parameter key used for intent tracing (e.g. prompt explanation/reasoning) */
+export const INTENT_FIELD = "i";
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Envelope & link constants
+// ═══════════════════════════════════════════════════════════════════════════
+
+/** Plaintext envelope prefix: `[4B uint32 BE peerId][sealed payload]`. */
+export const ENVELOPE_HEADER_LENGTH = 4;
+
+export const ROOM_ID_BYTES = 16;
+
+/** AES-256-GCM room key; the seal key for every collab frame. */
+export const ROOM_KEY_BYTES = 32;
+
+/**
+ * Random write token appended to the room key in full links
+ * (`base64url(key ∥ token)`); view links carry the bare key. Possession
+ * proves prompt/abort/agent-cmd capability to the host.
+ */
+export const WRITE_TOKEN_BYTES = 16;
+
+/** Default public relay; bare `<roomId>.<key>` links resolve against it. */
+export const DEFAULT_RELAY_URL = "wss://my.omp.sh";
+
+/** Default share viewer/upload base; `/share` links resolve against `<base>/<id>#<key>`. */
+export const DEFAULT_SHARE_URL = "https://my.omp.sh/s";
+
+export interface ParsedCollabLink {
+	/** wss://host[:port]/r/<roomId> — no query, no fragment. */
+	wsUrl: string;
+	roomId: string;
+	key: Uint8Array;
+	/** Write token from a full link; absent for read-only (view) links. */
+	writeToken?: Uint8Array;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Relay control messages (TEXT JSON, unencrypted, no session data)
+// ═══════════════════════════════════════════════════════════════════════════
+
+/** Relay → host control message. */
+export type RelayControlToHost = { t: "peer-joined" | "peer-left"; peer: number };
+/** Relay → guest control message. */
+export type RelayControlToGuest = { t: "room-closed" };
+export type RelayControlMessage = RelayControlToHost | RelayControlToGuest;
+
+export * from "./stream";
+export * from "./tsp";