@longshot-harness/longshot 0.1.0-beta.1 → 0.1.0-beta.2

package/sidecars/claude/sidecar.mjs

@@ -0,0 +1,207 @@
+/**
+ * The sidecar dispatch loop: hello gate, op dispatcher, EOF shutdown.
+ *
+ * JavaScript port of sidecars/claude/main.py:197-363. The injected sdk,
+ * input and output seams (D08) let tests run the whole loop without a real
+ * SDK or a real CLI. Requests from Longshot are serialised through a promise
+ * chain (one at a time, in arrival order); kind:"response" frames bypass the
+ * chain immediately so that sidecar-initiated requests can be resolved while a
+ * Longshot request is in flight (D07).
+ */
+
+import { createInterface } from 'node:readline';
+
+import {
+  PROTOCOL_VERSION,
+  SIDECAR_VERSION,
+  Code,
+  Op,
+  KNOWN_OPS,
+  parseFrame,
+  encodeFrame,
+  response,
+  refusal,
+  createCorrelation,
+  Refusal,
+} from './protocol.mjs';
+import { createUnknownLog } from './events.mjs';
+import { Session } from './session.mjs';
+
+// The two ops that emit session.ready immediately after their own response
+// frame (main.py:108-113). The event is written here, after the result frame,
+// never from inside Session: the caller reads the session id from that result,
+// so an event naming a session Longshot has not been told about yet would be
+// a frame out of order.
+const READY_AFTER = new Set([Op.SESSION_START, Op.SESSION_RESUME]);
+
+/**
+ * Route one host request to the appropriate Session method.
+ *
+ * @param {Session} session
+ * @param {string} op
+ * @param {object} params
+ * @returns {Promise<object>}
+ */
+async function dispatch(session, op, params) {
+  switch (op) {
+    case Op.SESSION_START:   return session.start(params);
+    case Op.SESSION_RESUME:  return session.resume(params);
+    case Op.SESSION_READ:    return session.read(params.session_id || '');
+    case Op.SESSION_HISTORY: return session.history(params);
+    case Op.INPUT_SUBMIT:    return session.submit(params);
+    case Op.TURN_INTERRUPT:  return session.interrupt(params.session_id || '');
+    case Op.MODEL_SET:       return session.setModel(params);
+    case Op.PERMISSION_SET:  return session.setPermissionMode(
+                               params.session_id || '', params.permission_mode || '');
+    case Op.SESSION_CLOSE:   return session.close(params.session_id || '');
+    default:
+      // Unreachable: KNOWN_OPS is checked before dispatch.
+      throw new Error(`unrouted op: ${op}`);
+  }
+}
+
+/**
+ * Run the sidecar protocol loop over the given I/O streams.
+ *
+ * Returns 0 on EOF, 2 on a protocol error that ends the channel, 1 on an
+ * unhandled internal error; always calls session.disconnect() before returning
+ * (main.py:362-363).
+ *
+ * @param {{ sdk: { query: Function, getSessionMessages: Function,
+ *                  version?: string, claudeCodeVersion?: string },
+ *            input: import('node:stream').Readable,
+ *            output: { write(s: string): void },
+ *            errput: { write(s: string): void } }} opts
+ * @returns {Promise<0|1|2>}
+ */
+export async function run({ sdk, input, output, errput }) {
+  let chainError = null;
+
+  function writeFrame(frame) {
+    output.write(encodeFrame(frame));
+  }
+
+  function diag(line) {
+    errput.write(line + '\n');
+  }
+
+  const correlation = createCorrelation(writeFrame);
+  const session = new Session({
+    sdk,
+    emit: writeFrame,
+    correlation,
+    logUnknown: createUnknownLog((s) => errput.write(s)),
+    logProblem: (s) => errput.write(s),
+  });
+
+  // One promise chain: each Longshot request starts after the previous one
+  // has written its response frame. kind:"response" frames bypass the chain
+  // (handled synchronously in the readline loop below).
+  let chain = Promise.resolve();
+
+  function enqueue(op, id, params) {
+    chain = chain.then(async () => {
+      if (chainError) return; // stop processing after an internal error
+      try {
+        const result = await dispatch(session, op, params);
+        writeFrame(response(id, result));
+        if (READY_AFTER.has(op)) writeFrame(session.readyEvent());
+      } catch (err) {
+        if (err instanceof Refusal) {
+          writeFrame(refusal(id, err.code, err.message));
+        } else {
+          errput.write(`claude sidecar: internal error: ${err?.stack ?? String(err)}\n`);
+          chainError = err;
+        }
+      }
+    });
+  }
+
+  let greeted = false;
+  let exitCode = 0;
+  const rl = createInterface({ input, crlfDelay: Infinity });
+
+  try {
+    for await (const line of rl) {
+      let frame;
+      try {
+        frame = parseFrame(line);
+      } catch (err) {
+        diag(`malformed frame: ${err.message}`);
+        exitCode = 2;
+        break;
+      }
+
+      const kind = frame.kind;
+      const op = frame.op;
+      const id = typeof frame.id === 'number' ? frame.id : 0;
+      const params = frame.params || {};
+
+      if (!greeted) {
+        if (kind !== 'request' || op !== Op.HELLO) {
+          writeFrame(refusal(id, Code.HELLO_REQUIRED,
+            `the sidecar channel received ${JSON.stringify(op || '')} before completing the ` +
+            'hello handshake; a sidecar channel must complete hello first'));
+          exitCode = 2;
+          break;
+        }
+        if (params.protocol !== PROTOCOL_VERSION) {
+          writeFrame(refusal(id, Code.UNSUPPORTED_VERSION,
+            `sidecar protocol mismatch: this sidecar speaks protocol ${PROTOCOL_VERSION}, ` +
+            `longshot speaks protocol ${JSON.stringify(params.protocol)}. Reinstall the sidecar ` +
+            'that ships with this longshot build, or run the longshot build that matches it.'));
+          exitCode = 2;
+          break;
+        }
+        writeFrame(response(id, {
+          protocol: PROTOCOL_VERSION,
+          sidecar: { name: 'claude-sidecar', version: SIDECAR_VERSION, pid: process.pid },
+          cli_version: sdk.claudeCodeVersion || 'unknown',
+          sdk_version: sdk.version || 'unknown',
+        }));
+        greeted = true;
+        continue;
+      }
+
+      // A second hello is refused but does not end the channel (main.py:264-276).
+      if (kind === 'request' && op === Op.HELLO) {
+        writeFrame(refusal(id, Code.MALFORMED_REQUEST,
+          'the sidecar received hello twice; hello is the first frame of a channel and is sent once'));
+        continue;
+      }
+
+      // Longshot responses to sidecar-initiated requests bypass the chain so
+      // that a sidecar request (permission.request, tool.call) can be resolved
+      // while a Longshot request is in flight (D07, main.py:278-294).
+      if (kind === 'response') {
+        if (!correlation.resolve(frame)) {
+          diag(`claude sidecar: response id=${frame.id} matched no pending sidecar-initiated request`);
+        }
+        continue;
+      }
+
+      // Non-request, non-response kind (e.g. "event").
+      if (kind !== 'request') {
+        writeFrame(refusal(id, Code.MALFORMED_REQUEST,
+          `the sidecar channel received a frame of kind ${JSON.stringify(kind)}, which Longshot may not send`));
+        continue;
+      }
+
+      // Unknown op.
+      if (!KNOWN_OPS.has(op)) {
+        writeFrame(refusal(id, Code.UNKNOWN_OPERATION,
+          `${JSON.stringify(op)} is not an operation either side of the sidecar channel knows`));
+        continue;
+      }
+
+      enqueue(op, id, params);
+    }
+  } finally {
+    rl.close();
+  }
+
+  // Drain any queued requests before disconnecting, on every exit path.
+  await chain;
+  await session.disconnect();
+  return chainError ? 1 : exitCode;
+}