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

package/sidecars/claude/session.mjs

@@ -0,0 +1,561 @@
+/**
+ * The one live Claude session this sidecar serves (D07).
+ *
+ * JavaScript port of session.py + permissions.py over an injected SDK
+ * ({query, getSessionMessages}): one streaming query() per session, fed by an
+ * input queue and read by one open-ended loop that maps every SDK message to
+ * wire events (events.mjs). Nothing here writes a response frame: refusals are
+ * thrown as Refusal and the dispatcher (T04) answers them. Event frames go out
+ * through the injected emit; sidecar-to-Longshot requests through the
+ * injected correlation registry (protocol.mjs).
+ *
+ * Everything a Session holds arrived from Longshot and arrives again on
+ * session.resume (I12).
+ */
+
+import { randomUUID } from 'node:crypto';
+
+import { Code, Refusal } from './protocol.mjs';
+import { StreamState, beginTurn, event, mapMessage, sessionReady } from './events.mjs';
+import { serializeMessage } from './history.mjs';
+import { buildLongshotServer } from './mcpserver.mjs';
+
+// The one permission_mode both sides of the channel refuse: the mode of an
+// unattended worker run, never the coordinator's own session (I08).
+export const FORBIDDEN_PERMISSION_MODE = 'bypassPermissions';
+
+// Verbatim from internal/backend/claude/testdata/error_forbiddenValue.json.
+const FORBIDDEN_PERMISSION_MODE_MESSAGE = (mode) =>
+  `permission_mode "${mode}" is forbidden on the coordinator session: it is ` +
+  'the mode of a worker in an isolated working directory and is not ' +
+  'carried over to the coordinator';
+
+// The permission_mode vocabulary of the vendor CLI, and the one place it is
+// written down (session.py:47-71). The wire carries Claude's own spelling;
+// anything else reaches the CLI verbatim and kills it, so it is refused here.
+// `manual` is not in the TS PermissionMode type, but the SDK passes the value
+// through unchecked and Longshot sends it for read-only (D07).
+export const ALLOWED_PERMISSION_MODES = Object.freeze([
+  'acceptEdits',
+  'auto',
+  'bypassPermissions',
+  'manual',
+  'dontAsk',
+  'plan',
+  'default',
+]);
+
+// The two input.submit modes served; both make the same call (session.py:73-80).
+export const SERVED_SUBMIT_MODES = Object.freeze(['turn', 'steer']);
+
+// The two wire modes refused by design, each with its reason (session.py:82-97).
+const UNSERVED_SUBMIT_MODES = {
+  'next-turn':
+    "next-turn is served by Longshot's own mailbox, not by this sidecar; accepting it " +
+    'here would mean holding a queue of pending input, which is state this side must ' +
+    'not hold (I12)',
+  'external-wake':
+    'external-wake needs a channel notification, which this vendor accepts but never ' +
+    'delivers into the session (F01, measured-constraints.md section 4), so there is ' +
+    'nothing this side could serve honestly',
+};
+
+const OPEN_FAILED = 'the Claude session could not be opened in this environment: ';
+const EARLY_END = 'the Claude CLI exited before the session opened';
+
+const quote = (v) => JSON.stringify(v ?? '');
+const why = (err) => `${err?.name ?? 'Error'}: ${err?.message ?? String(err)}`;
+
+/**
+ * Enforces I08 for every frame that carries permission_mode: session.start,
+ * session.resume and permission.set. Three facts, three codes
+ * (docs/claude-sidecar.md, "Empty versus forbidden value"): empty is
+ * malformedRequest, bypassPermissions is forbiddenValue, a mode outside the
+ * CLI's vocabulary is unsupportedMode.
+ */
+export function checkPermissionMode(mode) {
+  if (!mode) {
+    throw new Refusal(
+      Code.MALFORMED_REQUEST,
+      'a non-empty permission_mode is required; the frame carried none',
+    );
+  }
+  if (mode === FORBIDDEN_PERMISSION_MODE) {
+    throw new Refusal(Code.FORBIDDEN_VALUE, FORBIDDEN_PERMISSION_MODE_MESSAGE(mode));
+  }
+  if (!ALLOWED_PERMISSION_MODES.includes(mode)) {
+    throw new Refusal(
+      Code.UNSUPPORTED_MODE,
+      `permission_mode ${quote(mode)} is not a mode the Claude CLI accepts; it accepts ` +
+        `one of ${ALLOWED_PERMISSION_MODES.join(', ')}`,
+    );
+  }
+}
+
+/**
+ * Options for query() from session.start/session.resume params (D07).
+ * Empty cwd/model/effort/system_prompt leave the option unset. extra carries
+ * what is per session: sessionId (start) or resume (resume), canUseTool,
+ * mcpServers. settingSources [] cuts off the operator's own settings, hooks
+ * and MCP servers.
+ *
+ * @param {object} params
+ * @param {object} extra
+ * @returns {object}
+ */
+export function buildOptions(params, extra) {
+  const permissionMode = params.permission_mode || '';
+  checkPermissionMode(permissionMode);
+  const options = {};
+  if (params.cwd) options.cwd = params.cwd;
+  if (params.model) options.model = params.model;
+  if (params.effort) options.effort = params.effort;
+  if (params.system_prompt) options.systemPrompt = params.system_prompt;
+  return {
+    ...options,
+    permissionMode,
+    includePartialMessages: true,
+    settingSources: [],
+    disallowedTools: [...(params.withheld_tools ?? [])],
+    ...extra,
+  };
+}
+
+/**
+ * The prompt of the one streaming query(): an async iterable that yields what
+ * push() queued and finishes after end(). Never throws.
+ */
+class InputQueue {
+  #items = [];
+  #waiter = null;
+  #ended = false;
+
+  push(message) {
+    if (this.#ended) return;
+    if (this.#waiter) {
+      const w = this.#waiter;
+      this.#waiter = null;
+      w({ value: message, done: false });
+    } else {
+      this.#items.push(message);
+    }
+  }
+
+  end() {
+    this.#ended = true;
+    if (this.#waiter) {
+      const w = this.#waiter;
+      this.#waiter = null;
+      w({ value: undefined, done: true });
+    }
+  }
+
+  next() {
+    if (this.#items.length) return Promise.resolve({ value: this.#items.shift(), done: false });
+    if (this.#ended) return Promise.resolve({ value: undefined, done: true });
+    return new Promise((resolve) => { this.#waiter = resolve; });
+  }
+
+  return() {
+    this.end();
+    return Promise.resolve({ value: undefined, done: true });
+  }
+
+  [Symbol.asyncIterator]() {
+    return this;
+  }
+}
+
+export class Session {
+  // Connection under construction during #open: set before the first await,
+  // cleared when #open succeeds or fails. #requireUnopened refuses while this
+  // is set; disconnect() closes it so a concurrent close never orphans the query.
+  #pending = null;
+
+  /**
+   * @param {{ sdk: {query: Function, getSessionMessages: Function},
+   *           emit: (frame: object) => void,
+   *           correlation: {request: Function, failPending: Function},
+   *           logUnknown: (what: string, name: string) => void,
+   *           logProblem?: (line: string) => void }} deps
+   */
+  constructor({ sdk, emit, correlation, logUnknown, logProblem }) {
+    this.sdk = sdk;
+    this.emit = emit;
+    this.correlation = correlation;
+    this.logUnknown = logUnknown;
+    this.logProblem = logProblem ?? ((s) => process.stderr.write(s));
+    this.sessionId = null;
+    this.nativeId = '';
+    this.cwd = '';
+    this.model = '';
+    this.effort = '';
+    this.permissionMode = '';
+    // The live connection: {q, input, state, loop}, or null when no CLI is
+    // behind this session (never opened, closed, or the stream ended).
+    this.conn = null;
+  }
+
+  async start(params) {
+    checkPermissionMode(params.permission_mode);
+    this.#requireUnopened();
+    if (params.mcp_endpoint) {
+      // Accepting and ignoring it would silently drop the session's tool set.
+      throw new Refusal(Code.INTERNAL, 'mcp_endpoint is served by T20, not by this build');
+    }
+    const sessionId = randomUUID();
+    const nativeId = randomUUID();
+    await this.#open(params, sessionId, nativeId, { sessionId: nativeId });
+    return this.#startResult();
+  }
+
+  async resume(params) {
+    checkPermissionMode(params.permission_mode);
+    this.#requireUnopened();
+    const nativeId = params.native_id || '';
+    if (!nativeId) {
+      throw new Refusal(
+        Code.MALFORMED_REQUEST,
+        'session.resume requires a non-empty native_id; the frame carried none',
+      );
+    }
+    const sessionId = params.session_id || '';
+    if (!sessionId) {
+      throw new Refusal(
+        Code.MALFORMED_REQUEST,
+        'session.resume requires a non-empty session_id; the frame carried none',
+      );
+    }
+    await this.#open(params, sessionId, nativeId, { resume: nativeId });
+    return this.#startResult();
+  }
+
+  read(sessionId) {
+    this.#requireServing(sessionId);
+    return {
+      session_id: this.sessionId,
+      native_id: this.nativeId,
+      cwd: this.cwd,
+      model: this.model,
+    };
+  }
+
+  async history(params) {
+    this.#requireServing(params.session_id || '');
+    const cursor = params.cursor || '';
+    const limit = params.limit || 0;
+    if (cursor && !/^\d+$/.test(String(cursor))) {
+      throw new Refusal(
+        Code.MALFORMED_REQUEST,
+        `session.history cursor ${quote(cursor)} is not a position this sidecar issued`,
+      );
+    }
+    const start = cursor ? Number(cursor) : 0;
+    let messages;
+    try {
+      messages = await this.sdk.getSessionMessages(this.nativeId, { dir: this.cwd });
+    } catch (err) {
+      throw new Refusal(Code.INTERNAL, `session.history could not be read: ${why(err)}`);
+    }
+    const items = messages.map(serializeMessage);
+    const end = limit <= 0 ? items.length : Math.min(start + limit, items.length);
+    const hasMore = end < items.length;
+    return {
+      items: items.slice(start, end),
+      next_cursor: hasMore ? String(end) : '',
+      has_more: hasMore,
+    };
+  }
+
+  async submit(params) {
+    const sessionId = params.session_id || '';
+    const conn = this.#requireLive(sessionId);
+
+    const mode = params.mode || '';
+    if (!SERVED_SUBMIT_MODES.includes(mode)) {
+      const reason =
+        UNSERVED_SUBMIT_MODES[mode] ??
+        `this sidecar serves mode ${SERVED_SUBMIT_MODES.join(' and ')}, and knows no mode ${quote(mode)}`;
+      throw new Refusal(Code.UNSUPPORTED_MODE, `input.submit mode ${quote(mode)} is not served: ${reason}`);
+    }
+    const text = params.text || '';
+    if (!text) {
+      throw new Refusal(
+        Code.MALFORMED_REQUEST,
+        'input.submit requires a non-empty text; the frame carried none',
+      );
+    }
+
+    // uuid is the one field measured to round-trip as the carrier; no
+    // carrier means no uuid key at all (measured-constraints.md section 2).
+    const carrier = params.carrier || '';
+    const message = { type: 'user', message: { role: 'user', content: text }, parent_tool_use_id: null };
+    if (carrier) message.uuid = carrier;
+    conn.input.push(message);
+
+    // After the message is queued, never before; a steer folded into a
+    // running turn gets no frame and no turn_id (I11: beginTurn mints).
+    const frames = beginTurn(conn.state, carrier);
+    for (const f of frames) this.emit(f);
+
+    const result = { accepted: true };
+    if (carrier) result.carrier = carrier;
+    if (frames.length) result.turn_id = conn.state.currentTurnId;
+    return result;
+  }
+
+  async interrupt(sessionId) {
+    const conn = this.#requireLive(sessionId);
+    if (!conn.state.currentTurnId) {
+      throw new Refusal(Code.NO_ACTIVE_TURN, `session ${quote(sessionId)} has no turn in flight to interrupt`);
+    }
+    // The still_queued receipt is ignored; the turn's end is turn.completed.
+    await this.#control('turn.interrupt', () => conn.q.interrupt());
+    return { interrupted: true };
+  }
+
+  async setModel(params) {
+    const conn = this.#requireLive(params.session_id || '');
+    const model = params.model || '';
+    if (!model) {
+      throw new Refusal(
+        Code.MALFORMED_REQUEST,
+        'model.set requires a non-empty model; the frame carried none',
+      );
+    }
+    const effort = params.effort || '';
+    if (effort) {
+      throw new Refusal(
+        Code.UNSUPPORTED_MODE,
+        `effort ${quote(effort)} cannot be applied: this vendor exposes no reasoning-effort ` +
+          'control on a live session, and applying the model alone would report a change ' +
+          'to effort that never happened. Send model.set with an empty effort to change ' +
+          'the model only',
+      );
+    }
+    await this.#control('model.set', () => conn.q.setModel(model));
+    this.model = model; // after the SDK call: a failed change never reads back as applied
+    return { model, effort: '' };
+  }
+
+  async setPermissionMode(sessionId, mode) {
+    checkPermissionMode(mode);
+    this.#requireServing(sessionId);
+    const conn = this.conn;
+    if (!conn) {
+      throw new Refusal(
+        Code.UNKNOWN_SESSION,
+        `session ${quote(sessionId)} is not connected; there is no live client to change the mode of`,
+      );
+    }
+    await this.#control('permission.set', () => conn.q.setPermissionMode(mode));
+    this.permissionMode = mode;
+    return { permission_mode: mode };
+  }
+
+  async close(sessionId) {
+    this.#requireServing(sessionId);
+    await this.disconnect();
+    return {};
+  }
+
+  /**
+   * Fails every outstanding request, ends the input queue, closes the query
+   * and waits for the read loop (D07). Safe with no session, when repeated,
+   * and when called concurrently with an in-flight #open.
+   */
+  async disconnect() {
+    this.correlation.failPending(
+      'the session was closed while the tool call was still outstanding; ' +
+        `session ${quote(this.sessionId)} is gone and its calls cannot be answered`,
+    );
+    const conn = this.conn ?? this.#pending;
+    if (!conn) return;
+    this.conn = null;
+    this.#pending = null;
+    conn.input.end();
+    conn.q?.close();
+    if (conn.loop) await conn.loop;
+  }
+
+  /** The session.ready frame; T04 writes it after the start/resume response. */
+  readyEvent() {
+    return sessionReady(this.sessionId || '', this.nativeId, this.model);
+  }
+
+  // ---- internals
+
+  async #open(params, sessionId, nativeId, which) {
+    const state = new StreamState(sessionId);
+    const input = new InputQueue();
+    const turnId = () => state.currentTurnId ?? '';
+
+    // Every tool use is asked of Longshot; updatedInput is the input
+    // unchanged, since nobody rewrites a tool call's arguments.
+    const canUseTool = async (toolName, toolInput) => {
+      const r = await this.correlation.request('permission.request', {
+        session_id: sessionId,
+        turn_id: turnId(),
+        tool_name: toolName,
+        input: toolInput,
+      });
+      return r.behavior === 'allow'
+        ? { behavior: 'allow', updatedInput: toolInput }
+        : { behavior: 'deny', message: r.message || `${toolName} was refused` };
+    };
+
+    // tool_id must correlate with the tool.started already emitted, and the
+    // MCP handler is never told that id: first match by name, else a minted
+    // id (session.py:376-396). Two calls of one tool outstanding at once may
+    // get each other's id; exact correlation is F06.
+    const toolIdFor = (fullName) => {
+      for (const [id, name] of state.toolNames) if (name === fullName) return id;
+      return randomUUID();
+    };
+    const callTool = (fullName, args) =>
+      this.correlation.request('tool.call', {
+        session_id: sessionId,
+        turn_id: turnId(),
+        tool_id: toolIdFor(fullName),
+        tool_name: fullName,
+        arguments: args,
+      });
+
+    const options = buildOptions(params, {
+      ...which,
+      canUseTool,
+      mcpServers: { longshot: buildLongshotServer(params.tools ?? [], callTool) },
+    });
+
+    const conn = { q: null, input, state, loop: null };
+    // Record before the first await so that #requireUnopened and disconnect()
+    // see this connection even while initializationResult() is pending.
+    this.#pending = conn;
+    let ended = false;
+    let loopError;
+    try {
+      conn.q = this.sdk.query({ prompt: input, options });
+      // The loop starts before initialization is awaited (D07).
+      conn.loop = (async () => {
+        try {
+          for await (const m of conn.q) {
+            for (const f of mapMessage(m, state, this.logUnknown)) this.emit(f);
+          }
+        } catch (err) {
+          loopError = err;
+        }
+        ended = true;
+        if (this.conn === conn) this.#streamEnded(conn, loopError);
+      })();
+      const earlyEnd = () => loopError ?? new Error(EARLY_END);
+      await Promise.race([
+        conn.q.initializationResult(),
+        conn.loop.then(() => { throw earlyEnd(); }),
+      ]);
+      if (ended) throw earlyEnd();
+    } catch (err) {
+      if (this.#pending === conn) {
+        // disconnect() hasn't cleaned up yet; we own the cleanup.
+        this.#pending = null;
+        input.end();
+        conn.q?.close();
+        if (conn.loop) await conn.loop;
+      } else {
+        // disconnect() already cleared #pending and closed the query/loop.
+        if (conn.loop) await conn.loop;
+      }
+      throw new Refusal(Code.INTERNAL, OPEN_FAILED + why(err));
+    }
+
+    if (this.#pending !== conn) {
+      // disconnect() was called while initializationResult() was pending and
+      // already cleaned up; don't install a dead connection.
+      if (conn.loop) await conn.loop;
+      throw new Refusal(Code.INTERNAL, OPEN_FAILED + 'the session was disconnected while opening');
+    }
+
+    this.#pending = null;
+    this.conn = conn;
+    this.sessionId = sessionId;
+    this.nativeId = nativeId;
+    this.cwd = params.cwd || '';
+    this.model = params.model || '';
+    this.effort = params.effort || '';
+    this.permissionMode = params.permission_mode;
+  }
+
+  /**
+   * The read loop finished with nobody closing the session: the CLI died.
+   * A turn in flight is ended on the wire, then the session is disconnected.
+   */
+  #streamEnded(conn, error) {
+    const reason = error ? why(error) : 'the CLI closed its output';
+    this.logProblem(`claude sidecar: the Claude CLI stream ended: ${reason}\n`);
+    const turnId = conn.state.currentTurnId;
+    if (turnId !== null) {
+      const at = new Date().toISOString();
+      this.emit(event('error', {
+        session_id: conn.state.sessionId,
+        turn_id: turnId,
+        message: `the Claude CLI stopped before the turn ended: ${reason}`,
+        will_retry: false,
+        at,
+      }));
+      this.emit(event('turn.completed', { session_id: conn.state.sessionId, turn_id: turnId, at }));
+      conn.state.currentTurnId = null;
+    }
+    this.conn = null;
+    conn.input.end();
+    conn.q.close();
+  }
+
+  async #control(op, call) {
+    try {
+      await call();
+    } catch (err) {
+      throw new Refusal(Code.INTERNAL, `the Claude CLI refused ${op}: ${why(err)}`);
+    }
+  }
+
+  #startResult() {
+    return {
+      session_id: this.sessionId,
+      native_id: this.nativeId,
+      model: this.model,
+      effort: this.effort,
+      permission_mode: this.permissionMode,
+    };
+  }
+
+  // One sidecar serves one session (I03): a second open would orphan the
+  // first session's CLI. Also refuse while #pending is set: a concurrent
+  // start during an in-flight #open would race for conn.
+  #requireUnopened() {
+    if (this.conn !== null || this.#pending !== null) {
+      throw new Refusal(
+        Code.INTERNAL,
+        `this sidecar already serves session ${quote(this.sessionId)}; ` +
+          'a second session needs a sidecar of its own',
+      );
+    }
+  }
+
+  // A session never opened serves no id at all, not even an empty one.
+  #requireServing(sessionId) {
+    const served = this.sessionId || '';
+    if (this.sessionId === null || sessionId !== served) {
+      throw new Refusal(Code.UNKNOWN_SESSION, `this sidecar is serving ${quote(served)}, not ${quote(sessionId)}`);
+    }
+  }
+
+  #requireLive(sessionId) {
+    this.#requireServing(sessionId);
+    if (!this.conn) {
+      throw new Refusal(
+        Code.UNKNOWN_SESSION,
+        `session ${quote(sessionId)} is not connected; there is no live client to serve this request`,
+      );
+    }
+    return this.conn;
+  }
+}