@aitty/protocol 0.1.1 → 0.2.0

package/README.md

@@ -0,0 +1,49 @@
+# @aitty/protocol
+
+Shared protocol types and helpers for aitty browser-terminal sessions.
+
+This package has no Node runtime dependency. Use it when a host, browser
+adapter, or integration needs to share status, control-frame, theme, or portless
+session-path semantics without depending on the full server or browser runtime.
+
+## Install
+
+```bash
+npm i @aitty/protocol
+```
+
+## Usage
+
+```ts
+import {
+  createAittyPortlessIdentity,
+  createHelloControlFrame,
+  parseAittyControlFrame
+} from "@aitty/protocol";
+
+const identity = createAittyPortlessIdentity({
+  project: "my-app",
+  label: "codex",
+  token: "local-session-token"
+});
+
+console.log(identity.path);
+
+const frame = parseAittyControlFrame(createHelloControlFrame({
+  cols: 120,
+  rows: 32,
+  replay: ""
+}));
+```
+
+## Main Exports
+
+- Portless helpers: `createAittyPortlessIdentity()`, `normalizePortlessSegment()`, `normalizeAittyPortlessPathname()`.
+- Control frames: `createHelloControlFrame()`, `createResizeControlFrame()`, `createExitControlFrame()`, `createThemeControlFrame()`, `parseAittyControlFrame()`.
+- Status types: `AittyTerminalStatusSnapshot`, connection states, output states, and session presentation states.
+- Theme helpers: `normalizeTheme()`, `readThemeSource()`, `subscribeThemeSource()`.
+- Session metadata helpers: `createSessionInfoBody()` and `AittySessionInfo`.
+
+## License
+
+Apache-2.0

package/dist/index.d.ts

@@ -36,6 +36,7 @@ type AittyTerminalStatusSnapshot = {
   output: AittyTerminalOutputState;
   sessionState: AittyTerminalSessionPresentationState;
 };
+type AittyClientRole = "controller" | "viewer";
 type AittyHelloControlFrame = {
   cols: number;
   replay: string;
@@ -62,7 +63,44 @@ type AittyThemeControlFrame = {
   theme: AittyTheme | null;
   type: "theme";
 };
-type AittyControlFrame = AittyExitControlFrame | AittyHelloControlFrame | AittyPingControlFrame | AittyPongControlFrame | AittyResizeControlFrame | AittyThemeControlFrame;
+type AittyRoleControlFrame = {
+  clientId: string;
+  role: AittyClientRole;
+  type: "role";
+};
+type AittyTakeoverRequestControlFrame = {
+  requestId?: string;
+  requesterId?: string;
+  type: "takeover-request";
+};
+type AittyTakeoverResponseControlFrame = {
+  approved: boolean;
+  requestId: string;
+  type: "takeover-response";
+};
+type AittyTakeoverResultControlFrame = {
+  approved: boolean;
+  reason?: string;
+  type: "takeover-result";
+};
+type AittyPushSubscriptionPayload = {
+  endpoint: string;
+  expirationTime?: null | number;
+  keys: {
+    auth: string;
+    p256dh: string;
+  };
+};
+type AittyPushSubscribeControlFrame = {
+  subscription: AittyPushSubscriptionPayload;
+  type: "push-subscribe";
+  url?: string;
+};
+type AittyPushUnsubscribeControlFrame = {
+  endpoint?: string;
+  type: "push-unsubscribe";
+};
+type AittyControlFrame = AittyExitControlFrame | AittyHelloControlFrame | AittyPingControlFrame | AittyPongControlFrame | AittyPushSubscribeControlFrame | AittyPushUnsubscribeControlFrame | AittyRoleControlFrame | AittyResizeControlFrame | AittyTakeoverRequestControlFrame | AittyTakeoverResponseControlFrame | AittyTakeoverResultControlFrame | AittyThemeControlFrame;
 declare function createAittyPortlessIdentity(options: {
   label?: string;
   labelFallback?: string;
@@ -87,8 +125,37 @@ declare function createExitControlFrame(options: {
   code: number | null;
   signal?: string | null;
 }): string;
+declare function createRoleControlFrame(options: {
+  clientId: string;
+  role: AittyClientRole;
+}): string;
+declare function createTakeoverRequestControlFrame(options?: {
+  requestId?: string;
+  requesterId?: string;
+}): string;
+declare function createTakeoverResponseControlFrame(options: {
+  approved: boolean;
+  requestId: string;
+}): string;
+declare function createTakeoverResultControlFrame(options: {
+  approved: boolean;
+  reason?: string;
+}): string;
+declare function createPushSubscribeControlFrame(options: {
+  subscription: AittyPushSubscriptionPayload;
+  url?: string;
+}): string;
+declare function createPushUnsubscribeControlFrame(options?: {
+  endpoint?: string;
+}): string;
 declare function parseAittyControlFrame(data: string): AittyControlFrame | null;
+declare function isAittyRoleControlFrame(frame: AittyControlFrame): frame is AittyRoleControlFrame;
 declare function isAittyResizeControlFrame(frame: AittyControlFrame): frame is AittyResizeControlFrame;
+declare function isAittyTakeoverRequestControlFrame(frame: AittyControlFrame): frame is AittyTakeoverRequestControlFrame;
+declare function isAittyTakeoverResponseControlFrame(frame: AittyControlFrame): frame is AittyTakeoverResponseControlFrame;
+declare function isAittyTakeoverResultControlFrame(frame: AittyControlFrame): frame is AittyTakeoverResultControlFrame;
+declare function isAittyPushSubscribeControlFrame(frame: AittyControlFrame): frame is AittyPushSubscribeControlFrame;
+declare function isAittyPushUnsubscribeControlFrame(frame: AittyControlFrame): frame is AittyPushUnsubscribeControlFrame;
 declare function isValidAittyResizeDimension(value: unknown): value is number;
 declare function normalizeTheme(theme: AittyTheme | undefined): AittyTheme | undefined;
 declare function readThemeSource(source: AittyThemeSource | undefined): Promise<AittyTheme | undefined>;
@@ -96,4 +163,4 @@ declare function subscribeThemeSource(source: AittyThemeSource | undefined, list
   dispose(): void;
 };
 //#endregion
-export { AITTY_SESSION_PATH_PREFIX, AittyControlFrame, AittyExitControlFrame, AittyHelloControlFrame, AittyPingControlFrame, AittyPongControlFrame, AittyPortlessIdentity, AittyPortlessOptions, AittyResizeControlFrame, AittyRuntimeKind, AittySessionInfo, AittyTerminalConnectionState, AittyTerminalLoadingPresentation, AittyTerminalOutputState, AittyTerminalSessionPresentationState, AittyTerminalStatusSnapshot, AittyTheme, AittyThemeControlFrame, AittyThemeSource, AittyThemeSubscription, createAittyPortlessIdentity, createExitControlFrame, createHelloControlFrame, createPingControlFrame, createPongControlFrame, createResizeControlFrame, createSessionInfoBody, createThemeControlFrame, isAittyResizeControlFrame, isValidAittyResizeDimension, normalizeAittyPortlessPathname, normalizePortlessSegment, normalizeTheme, parseAittyControlFrame, readThemeSource, subscribeThemeSource };
+export { AITTY_SESSION_PATH_PREFIX, AittyClientRole, AittyControlFrame, AittyExitControlFrame, AittyHelloControlFrame, AittyPingControlFrame, AittyPongControlFrame, AittyPortlessIdentity, AittyPortlessOptions, AittyPushSubscribeControlFrame, AittyPushSubscriptionPayload, AittyPushUnsubscribeControlFrame, AittyResizeControlFrame, AittyRoleControlFrame, AittyRuntimeKind, AittySessionInfo, AittyTakeoverRequestControlFrame, AittyTakeoverResponseControlFrame, AittyTakeoverResultControlFrame, AittyTerminalConnectionState, AittyTerminalLoadingPresentation, AittyTerminalOutputState, AittyTerminalSessionPresentationState, AittyTerminalStatusSnapshot, AittyTheme, AittyThemeControlFrame, AittyThemeSource, AittyThemeSubscription, createAittyPortlessIdentity, createExitControlFrame, createHelloControlFrame, createPingControlFrame, createPongControlFrame, createPushSubscribeControlFrame, createPushUnsubscribeControlFrame, createResizeControlFrame, createRoleControlFrame, createSessionInfoBody, createTakeoverRequestControlFrame, createTakeoverResponseControlFrame, createTakeoverResultControlFrame, createThemeControlFrame, isAittyPushSubscribeControlFrame, isAittyPushUnsubscribeControlFrame, isAittyResizeControlFrame, isAittyRoleControlFrame, isAittyTakeoverRequestControlFrame, isAittyTakeoverResponseControlFrame, isAittyTakeoverResultControlFrame, isValidAittyResizeDimension, normalizeAittyPortlessPathname, normalizePortlessSegment, normalizeTheme, parseAittyControlFrame, readThemeSource, subscribeThemeSource };

package/dist/index.js

@@ -58,6 +58,47 @@ function createExitControlFrame(options) {
 		type: "exit"
 	});
 }
+function createRoleControlFrame(options) {
+	return JSON.stringify({
+		clientId: options.clientId,
+		role: options.role,
+		type: "role"
+	});
+}
+function createTakeoverRequestControlFrame(options = {}) {
+	return JSON.stringify({
+		...options.requestId ? { requestId: options.requestId } : {},
+		...options.requesterId ? { requesterId: options.requesterId } : {},
+		type: "takeover-request"
+	});
+}
+function createTakeoverResponseControlFrame(options) {
+	return JSON.stringify({
+		approved: options.approved,
+		requestId: options.requestId,
+		type: "takeover-response"
+	});
+}
+function createTakeoverResultControlFrame(options) {
+	return JSON.stringify({
+		approved: options.approved,
+		...options.reason ? { reason: options.reason } : {},
+		type: "takeover-result"
+	});
+}
+function createPushSubscribeControlFrame(options) {
+	return JSON.stringify({
+		subscription: options.subscription,
+		...options.url ? { url: options.url } : {},
+		type: "push-subscribe"
+	});
+}
+function createPushUnsubscribeControlFrame(options = {}) {
+	return JSON.stringify({
+		...options.endpoint ? { endpoint: options.endpoint } : {},
+		type: "push-unsubscribe"
+	});
+}
 function parseAittyControlFrame(data) {
 	try {
 		const parsed = JSON.parse(data);
@@ -68,12 +109,36 @@ function parseAittyControlFrame(data) {
 		return null;
 	}
 }
+function isAittyRoleControlFrame(frame) {
+	return frame.type === "role" && (frame.role === "controller" || frame.role === "viewer") && typeof frame.clientId === "string" && frame.clientId.length > 0;
+}
 function isAittyResizeControlFrame(frame) {
 	return frame.type === "resize" && isValidAittyResizeDimension(frame.cols) && isValidAittyResizeDimension(frame.rows);
 }
+function isAittyTakeoverRequestControlFrame(frame) {
+	return frame.type === "takeover-request";
+}
+function isAittyTakeoverResponseControlFrame(frame) {
+	return frame.type === "takeover-response" && typeof frame.requestId === "string" && frame.requestId.length > 0 && typeof frame.approved === "boolean";
+}
+function isAittyTakeoverResultControlFrame(frame) {
+	return frame.type === "takeover-result" && typeof frame.approved === "boolean";
+}
+function isAittyPushSubscribeControlFrame(frame) {
+	return frame.type === "push-subscribe" && isAittyPushSubscriptionPayload(frame.subscription) && (frame.url === void 0 || typeof frame.url === "string");
+}
+function isAittyPushUnsubscribeControlFrame(frame) {
+	return frame.type === "push-unsubscribe" && (frame.endpoint === void 0 || typeof frame.endpoint === "string");
+}
 function isValidAittyResizeDimension(value) {
 	return typeof value === "number" && Number.isInteger(value) && value > 0;
 }
+function isAittyPushSubscriptionPayload(value) {
+	if (!value || typeof value !== "object") return false;
+	const subscription = value;
+	const keys = subscription.keys;
+	return typeof subscription.endpoint === "string" && subscription.endpoint.length > 0 && (subscription.expirationTime === void 0 || subscription.expirationTime === null || typeof subscription.expirationTime === "number") && Boolean(keys) && typeof keys?.auth === "string" && keys.auth.length > 0 && typeof keys.p256dh === "string" && keys.p256dh.length > 0;
+}
 function normalizeTheme(theme) {
 	if (typeof theme !== "string") return;
 	const normalized = theme.trim();
@@ -91,4 +156,4 @@ function subscribeThemeSource(source, listener) {
 	return { dispose() {} };
 }
 //#endregion
-export { AITTY_SESSION_PATH_PREFIX, createAittyPortlessIdentity, createExitControlFrame, createHelloControlFrame, createPingControlFrame, createPongControlFrame, createResizeControlFrame, createSessionInfoBody, createThemeControlFrame, isAittyResizeControlFrame, isValidAittyResizeDimension, normalizeAittyPortlessPathname, normalizePortlessSegment, normalizeTheme, parseAittyControlFrame, readThemeSource, subscribeThemeSource };
+export { AITTY_SESSION_PATH_PREFIX, createAittyPortlessIdentity, createExitControlFrame, createHelloControlFrame, createPingControlFrame, createPongControlFrame, createPushSubscribeControlFrame, createPushUnsubscribeControlFrame, createResizeControlFrame, createRoleControlFrame, createSessionInfoBody, createTakeoverRequestControlFrame, createTakeoverResponseControlFrame, createTakeoverResultControlFrame, createThemeControlFrame, isAittyPushSubscribeControlFrame, isAittyPushUnsubscribeControlFrame, isAittyResizeControlFrame, isAittyRoleControlFrame, isAittyTakeoverRequestControlFrame, isAittyTakeoverResponseControlFrame, isAittyTakeoverResultControlFrame, isValidAittyResizeDimension, normalizeAittyPortlessPathname, normalizePortlessSegment, normalizeTheme, parseAittyControlFrame, readThemeSource, subscribeThemeSource };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aitty/protocol",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "Shared protocol types and helpers for aitty.",
   "keywords": [
     "agent",