@aitty/protocol 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,99 @@
+//#region packages/protocol/src/index.d.ts
+declare const AITTY_SESSION_PATH_PREFIX = "/s/";
+type AittyTheme = "dark" | "light" | string;
+type AittyThemeSource = {
+  getTheme?: () => AittyTheme | undefined | Promise<AittyTheme | undefined>;
+  subscribe?: (listener: (theme: AittyTheme | undefined) => void) => AittyThemeSubscription | void;
+};
+type AittyThemeSubscription = (() => void) | {
+  dispose(): void;
+};
+type AittyRuntimeKind = "droid" | "pty";
+type AittySessionInfo = {
+  runtimeKind: AittyRuntimeKind;
+};
+interface AittyPortlessOptions {
+  label?: string;
+  project?: string;
+}
+interface AittyPortlessIdentity {
+  label: string;
+  path: string;
+  project: string;
+  sessionId: string;
+}
+type AittyTerminalConnectionState = "connecting" | "open" | "reconnecting" | "superseded" | "closed" | "error";
+type AittyTerminalOutputState = "pending" | "ready";
+type AittyTerminalSessionPresentationState = "starting" | "live" | "reconnecting" | "superseded" | "shutdown" | "ended" | "error";
+type AittyTerminalLoadingPresentation = {
+  message: string;
+  visible: boolean;
+};
+type AittyTerminalStatusSnapshot = {
+  connection: AittyTerminalConnectionState;
+  loading: AittyTerminalLoadingPresentation;
+  message: string;
+  output: AittyTerminalOutputState;
+  sessionState: AittyTerminalSessionPresentationState;
+};
+type AittyHelloControlFrame = {
+  cols: number;
+  replay: string;
+  rows: number;
+  type: "hello";
+};
+type AittyPingControlFrame = {
+  type: "ping";
+};
+type AittyPongControlFrame = {
+  type: "pong";
+};
+type AittyResizeControlFrame = {
+  cols: number;
+  rows: number;
+  type: "resize";
+};
+type AittyExitControlFrame = {
+  code: number | null;
+  signal: string | null;
+  type: "exit";
+};
+type AittyThemeControlFrame = {
+  theme: AittyTheme | null;
+  type: "theme";
+};
+type AittyControlFrame = AittyExitControlFrame | AittyHelloControlFrame | AittyPingControlFrame | AittyPongControlFrame | AittyResizeControlFrame | AittyThemeControlFrame;
+declare function createAittyPortlessIdentity(options: {
+  label?: string;
+  labelFallback?: string;
+  project?: string;
+  projectFallback?: string;
+  sessionIdLength?: number;
+  token: string;
+}): AittyPortlessIdentity;
+declare function normalizePortlessSegment(value: string | undefined, fallback: string): string;
+declare function normalizeAittyPortlessPathname(pathname: string): string;
+declare function createSessionInfoBody(runtimeKind: AittyRuntimeKind): string;
+declare function createThemeControlFrame(theme: AittyTheme | undefined): string;
+declare function createHelloControlFrame(options: {
+  cols: number;
+  replay?: string;
+  rows: number;
+}): string;
+declare function createPingControlFrame(): string;
+declare function createPongControlFrame(): string;
+declare function createResizeControlFrame(cols: number, rows: number): string;
+declare function createExitControlFrame(options: {
+  code: number | null;
+  signal?: string | null;
+}): string;
+declare function parseAittyControlFrame(data: string): AittyControlFrame | null;
+declare function isAittyResizeControlFrame(frame: AittyControlFrame): frame is AittyResizeControlFrame;
+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>;
+declare function subscribeThemeSource(source: AittyThemeSource | undefined, listener: (theme: AittyTheme | undefined) => void): {
+  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 };

package/dist/index.js

@@ -0,0 +1,94 @@
+//#region packages/protocol/src/index.ts
+const AITTY_SESSION_PATH_PREFIX = "/s/";
+function createAittyPortlessIdentity(options) {
+	const project = normalizePortlessSegment(options.project, options.projectFallback ?? "session");
+	const label = normalizePortlessSegment(options.label, options.labelFallback ?? "agent");
+	const sessionId = options.token.slice(0, Math.max(1, options.sessionIdLength ?? 8));
+	return {
+		label,
+		path: `/s/${project}/${label}-${sessionId}`,
+		project,
+		sessionId
+	};
+}
+function normalizePortlessSegment(value, fallback) {
+	return Array.from((value ?? "").normalize("NFKD")).filter((character) => character.charCodeAt(0) <= 127).join("").toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "") || fallback;
+}
+function normalizeAittyPortlessPathname(pathname) {
+	const candidate = pathname.trim();
+	if (!candidate) throw new Error("Aitty URL pathname must be a portless session path");
+	const normalizedPathname = candidate.startsWith("/") ? candidate : `/${candidate}`;
+	if (!normalizedPathname.startsWith("/s/")) throw new Error(`Aitty URL pathname must start with /s/`);
+	return normalizedPathname;
+}
+function createSessionInfoBody(runtimeKind) {
+	return JSON.stringify({ runtimeKind });
+}
+function createThemeControlFrame(theme) {
+	return JSON.stringify({
+		theme: normalizeTheme(theme) ?? null,
+		type: "theme"
+	});
+}
+function createHelloControlFrame(options) {
+	return JSON.stringify({
+		cols: options.cols,
+		replay: options.replay ?? "",
+		rows: options.rows,
+		type: "hello"
+	});
+}
+function createPingControlFrame() {
+	return JSON.stringify({ type: "ping" });
+}
+function createPongControlFrame() {
+	return JSON.stringify({ type: "pong" });
+}
+function createResizeControlFrame(cols, rows) {
+	return JSON.stringify({
+		cols,
+		rows,
+		type: "resize"
+	});
+}
+function createExitControlFrame(options) {
+	return JSON.stringify({
+		code: options.code,
+		signal: options.signal ?? null,
+		type: "exit"
+	});
+}
+function parseAittyControlFrame(data) {
+	try {
+		const parsed = JSON.parse(data);
+		if (!parsed || typeof parsed !== "object" || !("type" in parsed)) return null;
+		if (typeof parsed.type !== "string") return null;
+		return parsed;
+	} catch {
+		return null;
+	}
+}
+function isAittyResizeControlFrame(frame) {
+	return frame.type === "resize" && isValidAittyResizeDimension(frame.cols) && isValidAittyResizeDimension(frame.rows);
+}
+function isValidAittyResizeDimension(value) {
+	return typeof value === "number" && Number.isInteger(value) && value > 0;
+}
+function normalizeTheme(theme) {
+	if (typeof theme !== "string") return;
+	const normalized = theme.trim();
+	return normalized.length > 0 ? normalized : void 0;
+}
+async function readThemeSource(source) {
+	return normalizeTheme(await source?.getTheme?.());
+}
+function subscribeThemeSource(source, listener) {
+	const subscription = source?.subscribe?.((theme) => {
+		listener(normalizeTheme(theme));
+	});
+	if (typeof subscription === "function") return { dispose: subscription };
+	if (subscription && typeof subscription.dispose === "function") return subscription;
+	return { dispose() {} };
+}
+//#endregion
+export { AITTY_SESSION_PATH_PREFIX, createAittyPortlessIdentity, createExitControlFrame, createHelloControlFrame, createPingControlFrame, createPongControlFrame, createResizeControlFrame, createSessionInfoBody, createThemeControlFrame, isAittyResizeControlFrame, isValidAittyResizeDimension, normalizeAittyPortlessPathname, normalizePortlessSegment, normalizeTheme, parseAittyControlFrame, readThemeSource, subscribeThemeSource };

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@aitty/protocol",
+  "version": "0.1.0",
+  "description": "Shared protocol types and helpers for aitty.",
+  "keywords": [
+    "agent",
+    "ai",
+    "browser",
+    "protocol",
+    "terminal"
+  ],
+  "homepage": "https://github.com/kingsword09/aitty#readme",
+  "bugs": {
+    "url": "https://github.com/kingsword09/aitty/issues"
+  },
+  "license": "Apache-2.0",
+  "author": "Kingsword kingsword09 <kingsword09@gmail.com>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kingsword09/aitty.git",
+    "directory": "packages/protocol"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}