@longshot-harness/longshot 0.0.0-stage → 0.1.0-beta.2

package/sidecars/claude/protocol.mjs

@@ -0,0 +1,222 @@
+/**
+ * The sidecar wire protocol: envelope, NDJSON framing and correlation.
+ *
+ * JavaScript port of protocol.py; the frozen contract lives in
+ * internal/backend/claude/protocol.go and is documented in
+ * docs/claude-sidecar.md. No SDK imports — only Node built-ins.
+ */
+
+// 2 adds one event, message.completed: the doc's bump rule is that adding a
+// message bumps, because an unknown event kind is refused rather than ignored
+// (docs/claude-sidecar.md, "Versioning and the handshake").
+export const PROTOCOL_VERSION = 2;
+export const SIDECAR_VERSION = '0.2.0';
+
+/** Refusal codes, verbatim from protocol.go's Code registry. */
+export const Code = Object.freeze({
+  HELLO_REQUIRED: 'helloRequired',
+  UNSUPPORTED_VERSION: 'unsupportedVersion',
+  MALFORMED_REQUEST: 'malformedRequest',
+  UNKNOWN_OPERATION: 'unknownOperation',
+  UNKNOWN_SESSION: 'unknownSession',
+  NO_ACTIVE_TURN: 'noActiveTurn',
+  UNSUPPORTED_MODE: 'unsupportedMode',
+  FORBIDDEN_VALUE: 'forbiddenValue',
+  INTERNAL: 'internal',
+});
+
+/**
+ * Operations Longshot may send, verbatim from protocol.go's HostOps.
+ *
+ * tool.call and permission.request are the sidecar's own two
+ * sidecar-to-Longshot requests (protocol.go's SidecarOps); they are not
+ * listed here because the dispatcher only classifies frames arriving from
+ * Longshot.
+ */
+export const Op = Object.freeze({
+  HELLO: 'hello',
+  SESSION_START: 'session.start',
+  SESSION_RESUME: 'session.resume',
+  SESSION_READ: 'session.read',
+  SESSION_HISTORY: 'session.history',
+  INPUT_SUBMIT: 'input.submit',
+  TURN_INTERRUPT: 'turn.interrupt',
+  MODEL_SET: 'model.set',
+  PERMISSION_SET: 'permission.set',
+  SESSION_CLOSE: 'session.close',
+});
+
+/** All host operations as a Set, for O(1) membership tests. */
+export const KNOWN_OPS = new Set(Object.values(Op));
+
+/**
+ * Raised by parseFrame for a line that is not a well-formed frame.
+ *
+ * Never raised for EOF — that is parseFrame returning null, the one
+ * unconditional exit signal the loop acts on.
+ */
+export class FrameError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'FrameError';
+  }
+}
+
+/**
+ * Thrown by Session methods to indicate the sidecar refuses a Longshot
+ * request.  The dispatcher catches it and writes a refusal frame.
+ * .code is one of the Code values; .message is a human-readable sentence.
+ */
+export class Refusal extends Error {
+  constructor(code, message) {
+    super(message);
+    this.name = 'Refusal';
+    this.code = code;
+  }
+}
+
+/**
+ * Parse one NDJSON line into an object, or return null on EOF ('').
+ *
+ * A line that is not valid JSON, or that decodes to something other than a
+ * JSON object, throws FrameError rather than being skipped: skipping an
+ * unrecognised line would let the second half of a split frame pass as
+ * valid (docs/claude-sidecar.md, "Framing").
+ *
+ * @param {string} line
+ * @returns {object}
+ */
+export function parseFrame(line) {
+  let frame;
+  try {
+    frame = JSON.parse(line);
+  } catch (err) {
+    throw new FrameError(`the line did not parse as JSON: ${err.message}`);
+  }
+  if (frame === null || typeof frame !== 'object' || Array.isArray(frame)) {
+    throw new FrameError('the line did not decode to a JSON object');
+  }
+  return frame;
+}
+
+/**
+ * Encode one frame as a single compact, newline-terminated JSON line.
+ *
+ * JSON.stringify does not escape non-ASCII by default, matching Python's
+ * ensure_ascii=False and the Go encoder in codec.go: payloads carry
+ * prompts and diffs whose non-ASCII characters must round-trip verbatim,
+ * and every frame is exactly one line.
+ *
+ * @param {object} frame
+ * @returns {string}
+ */
+export function encodeFrame(frame) {
+  return JSON.stringify(frame) + '\n';
+}
+
+/**
+ * Build a success response. result is never omitted: an empty result is {},
+ * matching Go's NewResponse rule.
+ *
+ * @param {number} id
+ * @param {object|null} result
+ * @returns {object}
+ */
+export function response(id, result) {
+  return { kind: 'response', id, result: result ?? {} };
+}
+
+/**
+ * Build a refusal response. message is a whole sentence.
+ *
+ * @param {number} id
+ * @param {string} code
+ * @param {string} message
+ * @returns {object}
+ */
+export function refusal(id, code, message) {
+  return { kind: 'response', id, error: { code, message } };
+}
+
+// ---- Sidecar to Longshot: request/response correlation.
+//
+// Both requests this side initiates — permission.request and tool.call —
+// share one id counter, one pending registry and one resolve(), and that
+// sharing is the whole reason the primitive sits here instead of in either
+// caller: a second correlation mechanism is refused (T20-S02). The dispatcher
+// calls resolve() once for both.
+//
+// The counter is this side's own: each side of the channel numbers its own
+// requests, unique as (initiator, id) (docs/claude-sidecar.md, "Correlation
+// and identifiers"), so nothing here ever reads or reuses a Longshot request id.
+
+/**
+ * Create one correlation registry for the lifetime of the process.
+ *
+ * @param {function(object): void} emit  - called with the outgoing request frame
+ * @returns {{ request(op: string, params: object): Promise<object>,
+ *             resolve(frame: object): boolean,
+ *             failPending(reason: string): void,
+ *             readonly pending: number }}
+ */
+export function createCorrelation(emit) {
+  let nextId = 1;
+  const pending = new Map(); // id → { resolve, reject }
+
+  /**
+   * Send one sidecar-initiated request and await its correlated result.
+   *
+   * There is no deadline: the protocol freezes "there is no protocol-level
+   * timeout on either" of the two sidecar requests
+   * (docs/claude-sidecar.md, "Sidecar to Longshot: requests"); the bound
+   * is channel life via failPending.
+   */
+  function request(op, params) {
+    const id = nextId++;
+    return new Promise((resolve, reject) => {
+      pending.set(id, { resolve, reject });
+      emit({ kind: 'request', id, op, params });
+    }).finally(() => {
+      pending.delete(id);
+    });
+  }
+
+  /**
+   * Route one incoming kind:response frame to the waiting request.
+   *
+   * Returns false when nobody is waiting: the id belongs to something else,
+   * or the waiter already gave up (the pending entry is removed when
+   * request() settles).
+   */
+  function resolve(frame) {
+    const waiter = pending.get(frame.id);
+    if (!waiter) return false;
+    const error = frame.error;
+    if (error != null) {
+      waiter.reject(new Error(error.message ?? ''));
+    } else {
+      waiter.resolve(frame.result ?? {});
+    }
+    return true;
+  }
+
+  /**
+   * Fail every request still outstanding with reason as the message.
+   *
+   * Called when the channel goes away. A waiter that outlived its channel
+   * would wait forever; raising instead reaches the model as a readable
+   * tool result (protocol.py:204-217).
+   */
+  function failPending(reason) {
+    for (const { reject } of pending.values()) {
+      reject(new Error(reason));
+    }
+  }
+
+  return {
+    request,
+    resolve,
+    failPending,
+    get pending() { return pending.size; },
+  };
+}