pi-open-deskos 0.2.1 → 0.4.0

package/src/transport.ts

@@ -1,12 +1,14 @@
 import { connect, type Socket } from "node:net";
-import { DESK_LINK_PROTOCOL, type DeskLinkConfig, type DeskLinkRecord } from "./types.ts";
+import { ODK_LINK_PROTOCOL, type OdkLinkConfig, type OdkLinkRecord } from "./types.ts";
+
+const MAX_INBOUND_FRAME_BYTES = 1024 * 1024;
 
 /**
- * A Desk Link transport. The reporter never touches a socket directly, so the
+ * A Open DeskOS Link transport. The reporter never touches a socket directly, so the
  * wire contract is testable without a network.
  */
 export interface DeskTransport {
-  send(record: DeskLinkRecord): void;
+  send(record: OdkLinkRecord): void;
   close(): void;
   onOpen(handler: () => void): void;
   onClose(handler: (reason: string) => void): void;
@@ -31,8 +33,8 @@ export function parseRecords(chunk: string, remainder: string): { records: unkno
   return { records, pending };
 }
 
-/** The real Desk Link: one outbound TCP connection with newline-delimited JSON. */
-export function createTcpTransport(config: DeskLinkConfig): DeskTransport {
+/** The real Open DeskOS Link: one outbound TCP connection with newline-delimited JSON. */
+export function createTcpTransport(config: OdkLinkConfig, options: { connectTimeoutMs?: number } = {}): DeskTransport {
   const openHandlers: Array<() => void> = [];
   const closeHandlers: Array<(reason: string) => void> = [];
   const recordHandlers: Array<(record: unknown) => void> = [];
@@ -42,6 +44,9 @@ export function createTcpTransport(config: DeskLinkConfig): DeskTransport {
   const socket: Socket = connect({ host: config.host, port: config.port });
   socket.setKeepAlive(true, 15000);
   socket.setNoDelay(true);
+  // Node's stream decoder retains incomplete UTF-8 code points across packets.
+  socket.setEncoding("utf8");
+  socket.setTimeout(options.connectTimeoutMs ?? 10000);
 
   const announceClose = (reason: string): void => {
     if (closed) return;
@@ -50,18 +55,36 @@ export function createTcpTransport(config: DeskLinkConfig): DeskTransport {
   };
 
   socket.on("connect", () => {
+    if (closed) return;
+    socket.setTimeout(0);
     for (const handler of openHandlers) handler();
   });
-  socket.on("data", (chunk: Buffer) => {
-    const parsed = parseRecords(chunk.toString("utf8"), remainder);
-    remainder = parsed.pending.length > 4096 ? "" : parsed.pending;
+  socket.on("timeout", () => {
+    announceClose("connection timeout");
+    socket.destroy();
+  });
+  socket.on("data", (chunk: string) => {
+    if (closed) return;
+    const text = remainder + chunk;
+    const lines = text.split("\n");
+    // Never discard a prefix and parse the suffix as an independent record.
+    if (lines.some((line) => Buffer.byteLength(line) + 1 > MAX_INBOUND_FRAME_BYTES)) {
+      announceClose("inbound record exceeds 1 MiB frame limit");
+      socket.destroy();
+      return;
+    }
+    const parsed = parseRecords(chunk, remainder);
+    remainder = parsed.pending;
     for (const record of parsed.records) for (const handler of recordHandlers) handler(record);
   });
-  socket.on("error", (error: Error) => announceClose(error.message));
+  socket.on("error", (error: Error) => {
+    announceClose(error.message);
+    socket.destroy();
+  });
   socket.on("close", () => announceClose("link closed"));
 
   return {
-    send(record: DeskLinkRecord) {
+    send(record: OdkLinkRecord) {
       if (closed || socket.destroyed) return;
       socket.write(`${JSON.stringify(record)}\n`);
     },
@@ -83,4 +106,4 @@ export function createTcpTransport(config: DeskLinkConfig): DeskTransport {
   };
 }
 
-export const DESK_LINK_PROTOCOL_DECLARATION = DESK_LINK_PROTOCOL;
+export const ODK_LINK_PROTOCOL_DECLARATION = ODK_LINK_PROTOCOL;

package/src/types.ts

@@ -1,12 +1,12 @@
 /**
- * The Desk Link wire contract, version 1.
+ * The Open DeskOS Link wire contract, version 1.
  *
- * A Desk Link carries one Reporting Machine's Reported Sessions to one
+ * A Open DeskOS Link carries one Reporting Machine's Reported Sessions to one
  * Open DeskOS runtime. Records are newline-delimited JSON over one connection
  * the package opens; Open DeskOS never reaches back to this machine.
  */
 
-export const DESK_LINK_PROTOCOL = 1;
+export const ODK_LINK_PROTOCOL = 1;
 
 /** Event bounds, identical to the runtime's local session collector. */
 export const MAX_EVENTS_PER_SESSION = 300;
@@ -27,8 +27,15 @@ export type SessionEventKind = "user" | "thinking" | "tool" | "result" | "assist
 export interface SessionEvent {
   kind: SessionEventKind;
   text: string;
+  /** The actual persisted assistant SessionMessageEntry ID. */
+  eventId?: string;
+  stopReason?: "stop" | "toolUse" | "length" | "error" | "aborted";
   /** Result-only label, kept outside the Markdown body. */
   toolName?: string;
+  /** Tool and result only: the call identity Pi wrote, which pairs the two. */
+  toolCallId?: string;
+  /** Result only, and only when Pi recorded that result as an error. */
+  isError?: true;
   /** Present only when a result or assistant body was shortened. */
   /** Present only when the event body was shortened by its kind's limit. */
   truncated?: true;
@@ -49,7 +56,7 @@ export interface ReportedSession {
   activity?: string;
 }
 
-export interface DeskLinkConfig {
+export interface OdkLinkConfig {
   /** Reporting machine identity, as shown on the desk. */
   machine: string;
   host: string;
@@ -94,14 +101,14 @@ export interface HistoryPage {
 }
 
 export interface HelloRecord {
-  v: typeof DESK_LINK_PROTOCOL;
+  v: typeof ODK_LINK_PROTOCOL;
   type: "hello";
   machine: string;
   token: string;
 }
 
 export interface SessionsRecord {
-  v: typeof DESK_LINK_PROTOCOL;
+  v: typeof ODK_LINK_PROTOCOL;
   type: "sessions";
   machine: string;
   sessions: ReportedSession[];
@@ -109,7 +116,7 @@ export interface SessionsRecord {
 
 /** Append-only events; a new connection replays the bounded retained tail. */
 export interface EventsRecord {
-  v: typeof DESK_LINK_PROTOCOL;
+  v: typeof ODK_LINK_PROTOCOL;
   type: "events";
   machine: string;
   sessionId: string;
@@ -117,12 +124,12 @@ export interface EventsRecord {
 }
 
 export interface ByeRecord {
-  v: typeof DESK_LINK_PROTOCOL;
+  v: typeof ODK_LINK_PROTOCOL;
   type: "bye";
   machine: string;
 }
 
-export type DeskLinkRecord = HelloRecord | SessionsRecord | EventsRecord | ByeRecord;
+export type OdkLinkRecord = HelloRecord | SessionsRecord | EventsRecord | ByeRecord;
 
 /**
  * The message parts this package reads. Pi streams these shapes for user,
@@ -141,6 +148,8 @@ export interface ThinkingPart {
 
 export interface ToolCallPart {
   type: "toolCall";
+  /** Pi's identity for this call; its result echoes the same value. */
+  id?: string;
   name: string;
   arguments: unknown;
 }