codekanban 0.26.0 → 0.28.0

package/packages/node-sdk/src/web-session-command-channel.js

@@ -0,0 +1,378 @@
+import { CodeKanbanConfigError, CodeKanbanError, CodeKanbanValidationError } from './errors.js';
+import {
+  WEB_SESSION_PROTOCOL_VERSION,
+  buildWebSessionCommandFrame,
+  buildWebSessionHeartbeatFrame,
+  decodeWebSessionSocketMessage,
+  isWebSessionHeartbeatFrame,
+  normalizeWebSessionFrame,
+} from './web-session-shared.js';
+import { ensureArrayOfStrings, ensureOptionalString, ensureString } from './utils.js';
+
+const SOCKET_OPEN = 1;
+const DEFAULT_OPEN_TIMEOUT_MS = 8000;
+const ACK_SETTLE_DELAY_MS = 10;
+
+function createRequestId() {
+  return `web_ws_${Date.now()}_${Math.random().toString(36).slice(2, 10)}`;
+}
+
+function normalizeHistoryLimit(value) {
+  const parsed = Number(value);
+  if (!Number.isFinite(parsed) || parsed <= 0) {
+    return 80;
+  }
+  return Math.max(1, Math.trunc(parsed));
+}
+
+export class WebSessionCommandChannel {
+  constructor({ url, WebSocketImpl } = {}) {
+    const resolvedUrl = ensureString(url, 'url');
+    const Socket = WebSocketImpl || globalThis.WebSocket;
+    if (!Socket) {
+      throw new CodeKanbanConfigError('WebSocket implementation is unavailable');
+    }
+
+    this.url = resolvedUrl;
+    this.socket = new Socket(resolvedUrl);
+    this.protocolVersion = WEB_SESSION_PROTOCOL_VERSION;
+    this._pendingRequests = new Map();
+    this._pendingFollowUp = null;
+    this._commandQueue = Promise.resolve();
+    this._openPromise = new Promise((resolve, reject) => {
+      this._resolveOpen = resolve;
+      this._rejectOpen = reject;
+    });
+    this._closed = false;
+
+    this.socket.addEventListener('open', () => {
+      this._resolveOpen?.();
+    });
+
+    this.socket.addEventListener('message', event => {
+      this._handleMessage(event.data);
+    });
+
+    this.socket.addEventListener('error', event => {
+      const error = new CodeKanbanError('web session command websocket error', { event });
+      this._rejectOpen?.(error);
+      this._rejectAll(error);
+    });
+
+    this.socket.addEventListener('close', event => {
+      this._closed = true;
+      const error = new CodeKanbanError('web session command websocket closed', { event });
+      this._rejectOpen?.(error);
+      this._rejectAll(error);
+    });
+  }
+
+  async waitForOpen(timeoutMs = DEFAULT_OPEN_TIMEOUT_MS) {
+    if (this.socket.readyState === SOCKET_OPEN) {
+      return;
+    }
+    await Promise.race([
+      this._openPromise,
+      new Promise((_, reject) => {
+        setTimeout(
+          () => reject(new CodeKanbanValidationError(`web session command channel did not open within ${timeoutMs}ms`)),
+          timeoutMs,
+        );
+      }),
+    ]);
+  }
+
+  async list(projectId) {
+    const ack = await this._executeCommand({
+      operation: 'list',
+      payload: {
+        pid: ensureString(projectId, 'projectId'),
+      },
+    });
+    return Array.isArray(ack.payload?.items) ? ack.payload.items : [];
+  }
+
+  async create(input = {}) {
+    const { frame } = await this._executeCommand({
+      operation: 'create',
+      payload: {
+        pid: ensureString(input.projectId, 'projectId'),
+        wid: ensureOptionalString(input.worktreeId),
+        ag: ensureString(input.agent, 'agent'),
+        md: ensureOptionalString(input.model),
+        re: ensureOptionalString(input.reasoningEffort),
+        wm: ensureOptionalString(input.workflowMode),
+        pl: ensureOptionalString(input.permissionLevel),
+        pm: ensureOptionalString(input.permissionMode),
+        ttl: ensureOptionalString(input.title),
+      },
+      expectType: 'snapshot',
+    });
+    return frame.snapshot;
+  }
+
+  async connect(sessionId) {
+    const { frame } = await this._executeCommand({
+      operation: 'connect',
+      sessionId,
+      expectType: 'snapshot',
+    });
+    return frame.snapshot;
+  }
+
+  async history(sessionId, options = {}) {
+    const { frame } = await this._executeCommand({
+      operation: 'hist',
+      sessionId,
+      payload: {
+        lim: normalizeHistoryLimit(options.limit),
+        bc: ensureOptionalString(options.beforeCursor),
+      },
+      expectType: 'historyPage',
+    });
+    return frame.history;
+  }
+
+  async sendMessage(sessionId, input = {}) {
+    const text = ensureOptionalString(input.text);
+    const attachmentIds = ensureArrayOfStrings(input.attachmentIds, 'attachmentIds');
+    if (!text && attachmentIds.length === 0) {
+      throw new CodeKanbanValidationError('text or attachmentIds is required');
+    }
+    return await this._executeCommand({
+      operation: 'send',
+      sessionId,
+      payload: {
+        txt: text,
+        atts: attachmentIds,
+      },
+    });
+  }
+
+  async abort(sessionId) {
+    return await this._executeCommand({ operation: 'abort', sessionId });
+  }
+
+  async approve(sessionId) {
+    return await this._executeCommand({ operation: 'approve', sessionId });
+  }
+
+  async reject(sessionId) {
+    return await this._executeCommand({ operation: 'reject', sessionId });
+  }
+
+  async answerUserInput(sessionId, input = {}) {
+    return await this._executeCommand({
+      operation: 'user_input',
+      sessionId,
+      payload: {
+        iid: ensureString(input.itemId, 'itemId'),
+        ans: input.answers && typeof input.answers === 'object' ? input.answers : {},
+      },
+    });
+  }
+
+  async rename(sessionId, input = {}) {
+    return await this._executeCommand({
+      operation: 'rename',
+      sessionId,
+      payload: {
+        ttl: ensureString(input.title, 'title'),
+      },
+    });
+  }
+
+  async updateModel(sessionId, input = {}) {
+    return await this._executeCommand({
+      operation: 'set_md',
+      sessionId,
+      payload: {
+        md: ensureString(input.model, 'model'),
+      },
+    });
+  }
+
+  async updateReasoningEffort(sessionId, input = {}) {
+    return await this._executeCommand({
+      operation: 'set_re',
+      sessionId,
+      payload: {
+        re: ensureString(input.reasoningEffort, 'reasoningEffort'),
+      },
+    });
+  }
+
+  async updateWorkflowMode(sessionId, input = {}) {
+    return await this._executeCommand({
+      operation: 'set_wm',
+      sessionId,
+      payload: {
+        wm: ensureString(input.workflowMode, 'workflowMode'),
+      },
+    });
+  }
+
+  async updatePermissionLevel(sessionId, input = {}) {
+    return await this._executeCommand({
+      operation: 'set_pl',
+      sessionId,
+      payload: {
+        pl: ensureString(input.permissionLevel, 'permissionLevel'),
+      },
+    });
+  }
+
+  async updateAgent(sessionId, input = {}) {
+    return await this._executeCommand({
+      operation: 'set_ag',
+      sessionId,
+      payload: {
+        ag: ensureString(input.agent, 'agent'),
+      },
+    });
+  }
+
+  async move(sessionId, input = {}) {
+    return await this._executeCommand({
+      operation: 'move',
+      sessionId,
+      payload: {
+        prv: ensureOptionalString(input.prevSessionId),
+        nxt: ensureOptionalString(input.nextSessionId),
+      },
+    });
+  }
+
+  async delete(sessionId) {
+    return await this._executeCommand({ operation: 'del', sessionId });
+  }
+
+  close() {
+    this._closed = true;
+    this.socket.close();
+  }
+
+  _enqueue(task) {
+    const next = this._commandQueue.then(task, task);
+    this._commandQueue = next.catch(() => {});
+    return next;
+  }
+
+  async _executeCommand({ operation, sessionId, payload = {}, expectType = null }) {
+    return await this._enqueue(async () => {
+      await this.waitForOpen();
+      if (this._closed || this.socket.readyState !== SOCKET_OPEN) {
+        throw new CodeKanbanError('web session command channel is not open');
+      }
+
+      const requestId = createRequestId();
+      const ackPromise = new Promise((resolve, reject) => {
+        this._pendingRequests.set(requestId, {
+          resolve,
+          reject,
+          ack: null,
+          ackTimer: null,
+        });
+      });
+
+      const followUpPromise =
+        expectType == null
+          ? null
+          : new Promise((resolve, reject) => {
+              this._pendingFollowUp = {
+                expectedType: expectType,
+                sessionId: ensureOptionalString(sessionId) || null,
+                resolve,
+                reject,
+              };
+            });
+
+      this.socket.send(
+        JSON.stringify(
+          buildWebSessionCommandFrame({
+            requestId,
+            sessionId,
+            operation,
+            payload,
+          }),
+        ),
+      );
+
+      const ack = await ackPromise;
+      if (!followUpPromise) {
+        return ack;
+      }
+      const frame = await followUpPromise;
+      return { ack, frame };
+    });
+  }
+
+  _handleMessage(data) {
+    const rawFrame = decodeWebSessionSocketMessage(data);
+    if (isWebSessionHeartbeatFrame(rawFrame)) {
+      if (rawFrame?.op === 'ping' && this.socket.readyState === SOCKET_OPEN) {
+        this.socket.send(JSON.stringify(buildWebSessionHeartbeatFrame('pong')));
+      }
+      return;
+    }
+    const frame = normalizeWebSessionFrame(rawFrame);
+
+    if (frame.type === 'error' && frame.requestId && this._pendingRequests.has(frame.requestId)) {
+      const pending = this._pendingRequests.get(frame.requestId);
+      this._clearAckTimer(pending);
+      this._pendingRequests.delete(frame.requestId);
+      pending?.reject(
+        new CodeKanbanError(frame.message, {
+          name: 'CodeKanbanWebSessionCommandError',
+          code: frame.code,
+          retry: frame.retry,
+          frame,
+        }),
+      );
+      return;
+    }
+
+    if (frame.type === 'ack' && frame.requestId && this._pendingRequests.has(frame.requestId)) {
+      const pending = this._pendingRequests.get(frame.requestId);
+      if (!pending) {
+        return;
+      }
+      pending.ack = frame;
+      pending.ackTimer = setTimeout(() => {
+        this._pendingRequests.delete(frame.requestId);
+        pending.resolve(frame);
+      }, ACK_SETTLE_DELAY_MS);
+      return;
+    }
+
+    if (
+      this._pendingFollowUp &&
+      frame.type === this._pendingFollowUp.expectedType &&
+      (!this._pendingFollowUp.sessionId || frame.sessionId === this._pendingFollowUp.sessionId)
+    ) {
+      const pendingFollowUp = this._pendingFollowUp;
+      this._pendingFollowUp = null;
+      pendingFollowUp.resolve(frame);
+    }
+  }
+
+  _clearAckTimer(pending) {
+    if (pending?.ackTimer) {
+      clearTimeout(pending.ackTimer);
+      pending.ackTimer = null;
+    }
+  }
+
+  _rejectAll(error) {
+    this._pendingRequests.forEach(pending => {
+      this._clearAckTimer(pending);
+      pending.reject(error);
+    });
+    this._pendingRequests.clear();
+
+    if (this._pendingFollowUp) {
+      this._pendingFollowUp.reject(error);
+      this._pendingFollowUp = null;
+    }
+  }
+}

package/packages/node-sdk/src/web-session-event-stream.js

@@ -0,0 +1,216 @@
+import { EventEmitter } from 'node:events';
+
+import { CodeKanbanConfigError, CodeKanbanError, CodeKanbanValidationError } from './errors.js';
+import {
+  buildWebSessionHeartbeatFrame,
+  decodeWebSessionSocketMessage,
+  isWebSessionHeartbeatFrame,
+  normalizeWebSessionFrame,
+  shouldEmitWebSessionFrame,
+} from './web-session-shared.js';
+import { ensureOptionalString, ensureString } from './utils.js';
+
+const SOCKET_OPEN = 1;
+const DEFAULT_OPEN_TIMEOUT_MS = 8000;
+
+function nowEventBase() {
+  const timestampMs = Date.now();
+  return {
+    timestampMs,
+    timestamp: new Date(timestampMs).toISOString(),
+  };
+}
+
+export class WebSessionEventStream {
+  constructor({ url, sessionId, WebSocketImpl } = {}) {
+    const resolvedUrl = ensureString(url, 'url');
+    const Socket = WebSocketImpl || globalThis.WebSocket;
+    if (!Socket) {
+      throw new CodeKanbanConfigError('WebSocket implementation is unavailable');
+    }
+
+    this.url = resolvedUrl;
+    this.sessionId = ensureOptionalString(sessionId) || null;
+    this.socket = new Socket(resolvedUrl);
+    this._emitter = new EventEmitter();
+    this._queue = [];
+    this._nextResolvers = [];
+    this._closed = false;
+    this._openPromise = new Promise((resolve, reject) => {
+      this._resolveOpen = resolve;
+      this._rejectOpen = reject;
+    });
+
+    this.socket.addEventListener('open', () => {
+      const payload = {
+        type: 'open',
+        url: this.url,
+        sessionId: this.sessionId,
+        ...nowEventBase(),
+      };
+      this._resolveOpen?.();
+      this._publish(payload);
+    });
+
+    this.socket.addEventListener('message', event => {
+      this._handleMessage(event.data);
+    });
+
+    this.socket.addEventListener('error', event => {
+      const error = new CodeKanbanError('web session event websocket error', { event });
+      const payload = {
+        type: 'error',
+        errorType: 'socket',
+        message: error.message,
+        error,
+        raw: event,
+        sessionId: this.sessionId,
+        ...nowEventBase(),
+      };
+      this._rejectOpen?.(error);
+      this._publish(payload);
+    });
+
+    this.socket.addEventListener('close', event => {
+      this._closed = true;
+      const payload = {
+        type: 'close',
+        url: this.url,
+        sessionId: this.sessionId,
+        code: typeof event?.code === 'number' ? event.code : null,
+        reason: typeof event?.reason === 'string' ? event.reason : '',
+        wasClean: event?.wasClean === true,
+        ...nowEventBase(),
+      };
+      this._rejectOpen?.(new CodeKanbanError('web session event websocket closed', { event }));
+      this._publish(payload);
+      this._flushIteratorDone();
+    });
+  }
+
+  on(type, handler) {
+    this._emitter.on(type, handler);
+    return () => this.off(type, handler);
+  }
+
+  off(type, handler) {
+    this._emitter.off(type, handler);
+  }
+
+  async waitForOpen(timeoutMs = DEFAULT_OPEN_TIMEOUT_MS) {
+    if (this.socket.readyState === SOCKET_OPEN) {
+      return;
+    }
+    await Promise.race([
+      this._openPromise,
+      new Promise((_, reject) => {
+        setTimeout(
+          () => reject(new CodeKanbanValidationError(`web session event stream did not open within ${timeoutMs}ms`)),
+          timeoutMs,
+        );
+      }),
+    ]);
+  }
+
+  async waitFor(predicate, options = {}) {
+    const timeoutMs = Number.isFinite(options.timeoutMs) ? Math.max(1, Math.trunc(options.timeoutMs)) : 15000;
+
+    return await new Promise((resolve, reject) => {
+      const cleanup = this.on('__event__', payload => {
+        try {
+          if (!predicate(payload)) {
+            return;
+          }
+          cleanup();
+          clearTimeout(timer);
+          resolve(payload);
+        } catch (error) {
+          cleanup();
+          clearTimeout(timer);
+          reject(error);
+        }
+      });
+
+      const timer = setTimeout(() => {
+        cleanup();
+        reject(new CodeKanbanValidationError(`web session event stream waitFor timed out after ${timeoutMs}ms`));
+      }, timeoutMs);
+    });
+  }
+
+  close() {
+    this._closed = true;
+    this.socket.close();
+  }
+
+  [Symbol.asyncIterator]() {
+    return {
+      next: () => {
+        if (this._queue.length > 0) {
+          return Promise.resolve({ value: this._queue.shift(), done: false });
+        }
+        if (this._closed) {
+          return Promise.resolve({ value: undefined, done: true });
+        }
+        return new Promise(resolve => {
+          this._nextResolvers.push(resolve);
+        });
+      },
+    };
+  }
+
+  _handleMessage(data) {
+    let rawFrame;
+    let frame;
+    try {
+      rawFrame = decodeWebSessionSocketMessage(data);
+      if (isWebSessionHeartbeatFrame(rawFrame)) {
+        if (rawFrame?.op === 'ping' && this.socket.readyState === SOCKET_OPEN) {
+          this.socket.send(JSON.stringify(buildWebSessionHeartbeatFrame('pong')));
+        }
+        return;
+      }
+      frame = normalizeWebSessionFrame(rawFrame);
+    } catch (error) {
+      const payload = {
+        type: 'error',
+        errorType: 'decode',
+        message: error instanceof Error ? error.message : String(error),
+        error,
+        raw: data,
+        sessionId: this.sessionId,
+        ...nowEventBase(),
+      };
+      this._publish(payload);
+      return;
+    }
+
+    if (!shouldEmitWebSessionFrame(frame, this.sessionId)) {
+      return;
+    }
+
+    this._publish(frame.type === 'error' ? { ...frame, errorType: 'frame' } : frame, true);
+  }
+
+  _publish(payload, emitFrame = false) {
+    if (emitFrame) {
+      this._emitter.emit('frame', payload);
+    }
+    this._emitter.emit(payload.type, payload);
+    this._emitter.emit('__event__', payload);
+
+    if (this._nextResolvers.length > 0) {
+      const resolve = this._nextResolvers.shift();
+      resolve?.({ value: payload, done: false });
+      return;
+    }
+    this._queue.push(payload);
+  }
+
+  _flushIteratorDone() {
+    while (this._nextResolvers.length > 0) {
+      const resolve = this._nextResolvers.shift();
+      resolve?.({ value: undefined, done: true });
+    }
+  }
+}