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

package/sidecars/claude/events.mjs

@@ -0,0 +1,331 @@
+/**
+ * Claude Agent SDK message stream → sidecar wire events.
+ *
+ * TS equivalent of events.py: one frozen table, transcribed here, plus the
+ * policy for a message or content-block type the table does not name.
+ * Dispatch is by msg.type / block.type, not class name (sdk-mapping.md §6).
+ * Only built-in Node.js modules are imported.
+ */
+
+import { randomUUID } from 'node:crypto';
+
+// ---------------------------------------------------------------------------
+// Public building block
+// ---------------------------------------------------------------------------
+
+/** {kind:'event', event:name, data: data ?? {}} */
+export function event(name, data) {
+  return { kind: 'event', event: name, data: data ?? {} };
+}
+
+// ---------------------------------------------------------------------------
+// IGNORED: SDK message types deliberately not mapped, each with a reason.
+// Keys are msg.type values. The same completeness-by-inspection purpose as
+// events.py: every intentional drop is named here, not buried in a comment.
+// ---------------------------------------------------------------------------
+export const IGNORED = {
+  rate_limit_event:
+    'rate-limit status transitions are deliberately dropped, not uninteresting: ' +
+    'the frozen wire catalog has no event kind meaning "rate limit", which makes this a named ' +
+    'candidate for the next protocol version',
+  conversation_reset:
+    "a mid-session transcript discard zeroes the SDK's running " +
+    'total_cost_usd, but nothing in this sidecar or the adapter accumulates cost, and ' +
+    'session.history is served per request from getSessionMessages() rather than a cache, so ' +
+    'there is no total to snapshot and no cache to invalidate',
+};
+
+// Content block types that never produce a frame on their own (D14).
+export const IGNORED_CONTENT_BLOCKS = {
+  thinking:
+    'thinking is already emitted via stream_event thinking_delta; re-emitting ' +
+    'it here would duplicate it (I11), and unlike an assistant text block there is ' +
+    'no boundary to draw: nothing downstream renders a thinking block as its own message',
+  redacted_thinking:
+    'redacted_thinking blocks carry no displayable text; logging them as ' +
+    'unknown on every extended-thinking response would be noise in the 4 KB stderr Go keeps',
+};
+
+// Structural stream event envelope types: framing only, never content.
+const _IGNORED_STREAM_EVENT_TYPES = new Set([
+  'message_start',
+  'content_block_start',
+  'content_block_stop',
+  'message_delta',
+  'message_stop',
+  'ping',
+]);
+
+// ---------------------------------------------------------------------------
+// StreamState
+// ---------------------------------------------------------------------------
+
+/** The turn-tracking state one session's persistent read loop owns. */
+export class StreamState {
+  /** @param {string} sessionId */
+  constructor(sessionId) {
+    this.sessionId = sessionId;
+    /** @type {string|null} */
+    this.currentTurnId = null;
+    /** @type {Map<string,string>} tool_use_id → tool_name */
+    this.toolNames = new Map();
+  }
+}
+
+// ---------------------------------------------------------------------------
+// session.ready
+// ---------------------------------------------------------------------------
+
+/**
+ * The session.ready frame, built once the session is open and ready.
+ * @param {string} sessionId
+ * @param {string} nativeId
+ * @param {string} model  empty string when operator pinned none
+ * @returns {object}
+ */
+export function sessionReady(sessionId, nativeId, model) {
+  return event('session.ready', {
+    session_id: sessionId,
+    native_id: nativeId,
+    model,
+    at: new Date().toISOString(),
+  });
+}
+
+// ---------------------------------------------------------------------------
+// beginTurn
+// ---------------------------------------------------------------------------
+
+/**
+ * Mint a turn id and return [turn.started], or [] when a turn is already
+ * active.  The only place a turn_id is minted (I11).
+ * @param {StreamState} state
+ * @param {string} [carrier]
+ * @returns {object[]}
+ */
+export function beginTurn(state, carrier = '') {
+  if (state.currentTurnId !== null) return [];
+  state.currentTurnId = randomUUID();
+  const data = { session_id: state.sessionId, turn_id: state.currentTurnId };
+  if (carrier) data.carrier = carrier;
+  data.at = new Date().toISOString();
+  return [event('turn.started', data)];
+}
+
+// ---------------------------------------------------------------------------
+// createUnknownLog
+// ---------------------------------------------------------------------------
+
+/**
+ * Returns a (what, name) → void logger that writes exactly one line per
+ * (what, name) pair per instance (D14: one line per name per process).
+ * @param {(line: string) => void} write
+ * @returns {(what: string, name: string) => void}
+ */
+export function createUnknownLog(write) {
+  const seen = new Set();
+  return function logUnknown(what, name) {
+    const key = `${what}\0${name}`;
+    if (seen.has(key)) return;
+    seen.add(key);
+    write(
+      `claude sidecar: unknown SDK ${what} type ${JSON.stringify(name)}; no event emitted\n`
+    );
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+
+function _now() {
+  return new Date().toISOString();
+}
+
+function _mapSystem(_msg, _state, _log) {
+  // No SystemMessage subtype emits a frame (events.py:163-174).
+  return [];
+}
+
+function _stringifyToolResult(content) {
+  if (content == null) return '';
+  if (typeof content === 'string') return content;
+  if (Array.isArray(content)) {
+    return content
+      .map((part) => {
+        if (part && typeof part === 'object' && 'text' in part) return String(part.text);
+        return String(part);
+      })
+      .join('');
+  }
+  return String(content);
+}
+
+function _mapToolResultBlock(block, state) {
+  const toolUseId = block.tool_use_id ?? '';
+  const toolName = state.toolNames.get(toolUseId) ?? '';
+  state.toolNames.delete(toolUseId);
+  return [
+    event('tool.completed', {
+      session_id: state.sessionId,
+      turn_id: state.currentTurnId ?? '',
+      tool_id: toolUseId,
+      tool_name: toolName,
+      text: _stringifyToolResult(block.content),
+      at: _now(),
+    }),
+  ];
+}
+
+function _mapUser(msg, state, logUnknown) {
+  const content = msg.message?.content;
+  if (typeof content === 'string') {
+    return beginTurn(state);
+  }
+  const blocks = Array.isArray(content) ? content : [];
+  const frames = [];
+  let sawText = false;
+  for (const block of blocks) {
+    const bt = block.type;
+    if (bt === 'tool_result') {
+      frames.push(..._mapToolResultBlock(block, state));
+    } else if (bt === 'text') {
+      sawText = true;
+    } else {
+      logUnknown('content block', String(bt));
+    }
+  }
+  if (sawText) {
+    return [...beginTurn(state), ...frames];
+  }
+  return frames;
+}
+
+function _mapAssistant(msg, state, logUnknown) {
+  const blocks = Array.isArray(msg.message?.content) ? msg.message.content : [];
+  const frames = [];
+  for (const block of blocks) {
+    const bt = block.type;
+    if (bt === 'text') {
+      frames.push(
+        event('message.completed', {
+          session_id: state.sessionId,
+          turn_id: state.currentTurnId ?? '',
+          text: block.text ?? '',
+          at: _now(),
+        })
+      );
+    } else if (bt === 'tool_use') {
+      const toolId = block.id ?? '';
+      const toolName = block.name ?? '';
+      state.toolNames.set(toolId, toolName);
+      frames.push(
+        event('tool.started', {
+          session_id: state.sessionId,
+          turn_id: state.currentTurnId ?? '',
+          tool_id: toolId,
+          tool_name: toolName,
+          at: _now(),
+        })
+      );
+    } else if (bt in IGNORED_CONTENT_BLOCKS) {
+      // deliberate no-op (thinking, redacted_thinking)
+    } else {
+      logUnknown('content block', String(bt));
+    }
+  }
+  return frames;
+}
+
+function _mapStreamEvent(msg, state, logUnknown) {
+  const ev = msg.event ?? {};
+  const eventType = ev.type;
+  if (eventType !== 'content_block_delta') {
+    if (!_IGNORED_STREAM_EVENT_TYPES.has(eventType)) {
+      logUnknown('StreamEvent', String(eventType));
+    }
+    return [];
+  }
+  const delta = ev.delta ?? {};
+  const deltaType = delta.type;
+  if (deltaType === 'text_delta') {
+    return [
+      event('message.delta', {
+        session_id: state.sessionId,
+        turn_id: state.currentTurnId ?? '',
+        delta: delta.text ?? '',
+        at: _now(),
+      }),
+    ];
+  }
+  if (deltaType === 'thinking_delta') {
+    return [
+      event('thinking.delta', {
+        session_id: state.sessionId,
+        turn_id: state.currentTurnId ?? '',
+        delta: delta.thinking ?? '',
+        at: _now(),
+      }),
+    ];
+  }
+  // Other delta types (input_json_delta, etc.) carry no text: drop silently.
+  return [];
+}
+
+function _mapResult(msg, state) {
+  const turnId = state.currentTurnId ?? '';
+  const frames = [];
+  if (msg.is_error) {
+    const text =
+      msg.result || msg.subtype || 'the turn ended with an error';
+    frames.push(
+      event('error', {
+        session_id: state.sessionId,
+        turn_id: turnId,
+        message: text,
+        will_retry: false,
+        at: _now(),
+      })
+    );
+  }
+  frames.push(
+    event('turn.completed', {
+      session_id: state.sessionId,
+      turn_id: turnId,
+      at: _now(),
+    })
+  );
+  // ResultMessage is the one and only turn boundary.
+  state.currentTurnId = null;
+  return frames;
+}
+
+// ---------------------------------------------------------------------------
+// Dispatch table and mapMessage
+// ---------------------------------------------------------------------------
+
+const _DISPATCH = {
+  system: _mapSystem,
+  user: _mapUser,
+  assistant: _mapAssistant,
+  stream_event: _mapStreamEvent,
+  result: _mapResult,
+};
+
+/**
+ * Maps one SDK message to zero, one, or more wire event frames.
+ * Never throws on an unknown type.
+ * @param {object} message
+ * @param {StreamState} state
+ * @param {(what: string, name: string) => void} logUnknown
+ * @returns {object[]}
+ */
+export function mapMessage(message, state, logUnknown) {
+  const type = message.type;
+  const handler = _DISPATCH[type];
+  if (!handler) {
+    if (!(type in IGNORED)) logUnknown('message', String(type));
+    return [];
+  }
+  return handler(message, state, logUnknown);
+}

package/sidecars/claude/history.mjs

@@ -0,0 +1,70 @@
+/**
+ * Claude Agent SDK persisted SessionMessage → session.history wire items.
+ *
+ * TS equivalent of history.py, built against the documented SessionMessage
+ * form (sdk.d.ts:6664: type, uuid, message — raw Messages API object) rather
+ * than repeating the Python deffect of dispatching on class names (D15).
+ * Only built-in Node.js modules are imported (none needed here).
+ */
+
+function _serializeBlock(block) {
+  const bt = block.type;
+  if (bt === 'text') {
+    return { type: 'text', text: block.text ?? '' };
+  }
+  if (bt === 'tool_use') {
+    return {
+      type: 'tool_use',
+      id: block.id ?? '',
+      name: block.name ?? '',
+      input: block.input ?? {},
+    };
+  }
+  if (bt === 'tool_result') {
+    return {
+      type: 'tool_result',
+      tool_use_id: block.tool_use_id ?? '',
+      content: block.content,
+      is_error: Boolean(block.is_error),
+    };
+  }
+  if (bt === 'thinking') {
+    return { type: 'thinking', text: block.thinking ?? '' };
+  }
+  // Unknown block: carry through by its type field (history.go treats
+  // unrecognised blocks as no-item rather than a silent loss).
+  return { type: bt };
+}
+
+function _serializeContent(content) {
+  if (typeof content === 'string') return content;
+  if (Array.isArray(content)) return content.map(_serializeBlock);
+  return content;
+}
+
+/**
+ * Serializes one SessionMessage into the raw item dict session.history
+ * carries on the wire (docs/claude-sidecar.md, "session.history").
+ * Never throws on an unknown type.
+ * @param {{ type: string, uuid?: string, message?: { content?: unknown } }} m
+ * @returns {object}
+ */
+export function serializeMessage(m) {
+  const uuid = m.uuid ?? '';
+  switch (m.type) {
+    case 'user':
+    case 'assistant':
+      return {
+        type: m.type,
+        uuid,
+        message: {
+          role: m.type,
+          content: _serializeContent(m.message?.content),
+        },
+      };
+    case 'system':
+      return { type: 'system', uuid };
+    default:
+      return { type: m.type };
+  }
+}

package/sidecars/claude/main.mjs

@@ -0,0 +1,84 @@
+// Entry point for the Claude sidecar process (D12).
+//
+// Static imports are only node:* built-ins; the SDK and sidecar.mjs are loaded
+// dynamically so their imports cannot reach process.stdout before step 1 runs.
+//
+// 1. Capture real stdout for frames; redirect process.stdout.write to stderr so
+//    that an accidental console.log anywhere in the process goes to diagnostics
+//    instead of the frame stream (main.py:21-23).
+// 2. Reject Node < 18 with a readable message and exit code 3.
+// 3. Resolve the SDK; read its package.json for the two version strings (D05).
+//    ERR_MODULE_NOT_FOUND / MODULE_NOT_FOUND → exit code 3; any other load
+//    error is a sidecar defect → re-throw (exit code 1 via uncaught rejection).
+// 4. Run the sidecar loop.
+// 5. Flush the real stdout before exiting so no frame is truncated.
+
+import { createRequire } from 'node:module';
+import { readFileSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+
+// ---- Step 1 ----------------------------------------------------------------
+
+const frames = process.stdout.write.bind(process.stdout);
+process.stdout.write = process.stderr.write.bind(process.stderr);
+
+// ---- Step 2 ----------------------------------------------------------------
+
+const [nodeMajor] = process.versions.node.split('.').map(Number);
+if (nodeMajor < 18) {
+  process.stderr.write(
+    `claude sidecar: Node.js ${process.versions.node} is too old; ` +
+    'the sidecar needs Node.js 18 or newer\n'
+  );
+  process.exit(3);
+}
+
+// ---- Step 3 ----------------------------------------------------------------
+
+let sdkMod, run, meta;
+try {
+  const require = createRequire(import.meta.url);
+  const entry = require.resolve('@anthropic-ai/claude-agent-sdk');
+  try {
+    meta = JSON.parse(readFileSync(join(dirname(entry), 'package.json'), 'utf8'));
+  } catch {
+    meta = {};
+  }
+  sdkMod = await import('@anthropic-ai/claude-agent-sdk');
+  ({ run } = await import('./sidecar.mjs'));
+} catch (err) {
+  const code = err?.code;
+  if (code === 'MODULE_NOT_FOUND' || code === 'ERR_MODULE_NOT_FOUND') {
+    process.stderr.write(
+      'claude sidecar: @anthropic-ai/claude-agent-sdk cannot be loaded; ' +
+      'run npm ci in sidecars/claude (source checkout) or reinstall ' +
+      '@longshot-harness/longshot; ' +
+      `import failed with: ${err.name}: ${err.message}\n`
+    );
+    process.exit(3);
+  }
+  throw err; // sidecar syntax error or other defect → code 1
+}
+
+// ---- Step 4 ----------------------------------------------------------------
+
+const sdk = {
+  query: sdkMod.query,
+  getSessionMessages: sdkMod.getSessionMessages,
+  version: meta.version || 'unknown',
+  claudeCodeVersion: meta.claudeCodeVersion || 'unknown',
+};
+
+const code = await run({
+  sdk,
+  input: process.stdin,
+  output: { write: frames },
+  errput: process.stderr,
+});
+
+// ---- Step 5 ----------------------------------------------------------------
+
+// Flush the real stdout before exit: write() is async on some platforms and
+// the frame stream must be drained before the process terminates.
+await new Promise((r) => frames('', r));
+process.exit(code);

package/sidecars/claude/mcpserver.mjs

@@ -0,0 +1,88 @@
+/**
+ * Builds the in-process "longshot" MCP server from the tool definitions
+ * session.start carries, using raw JSON Schema handlers (D06).
+ *
+ * McpServer.server.setRequestHandler bypasses the zod-only McpServer.tool()
+ * path, letting Go's raw JSON Schema pass through unmodified. The SDK only
+ * calls instance.connect(transport) on the returned McpServer (D06, context.md
+ * §9.4), so passing the McpServer as-is satisfies McpSdkServerConfigWithInstance.
+ */
+
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { ListToolsRequestSchema, CallToolRequestSchema } from '@modelcontextprotocol/sdk/types.js';
+
+import { SIDECAR_VERSION } from './protocol.mjs';
+
+/**
+ * Prefix Claude adds to every tool name when the MCP server is named "longshot".
+ * A definition arrives as "mcp__longshot__<tool>" and registers on the server
+ * under "<tool>" alone; the prefix is re-attached for the forwarding call.
+ */
+export const MCP_PREFIX = 'mcp__longshot__';
+
+/** Strip the prefix to get the name the MCP server registers the tool under. */
+function bareName(fullName) {
+  return fullName.startsWith(MCP_PREFIX) ? fullName.slice(MCP_PREFIX.length) : fullName;
+}
+
+/**
+ * Build the in-process "longshot" MCP server.
+ *
+ * @param {Array<{name: string, description: string, input_schema: object}>} definitions
+ *   Tool definitions from Go (session.start params).
+ * @param {function(fullName: string, args: object): Promise<{content, is_error}>} callTool
+ *   Forwards to Go via tool.call; rejection is mapped to isError: true per
+ *   protocol.py:204-217 so the SDK delivers a readable error to the model.
+ *
+ * @returns {{ type: 'sdk', name: 'longshot', instance: McpServer }}
+ *   Ready for use as Options.mcpServers.longshot.
+ */
+export function buildLongshotServer(definitions, callTool) {
+  const mcp = new McpServer(
+    { name: 'longshot', version: SIDECAR_VERSION },
+    { capabilities: { tools: {} } },
+  );
+
+  // Build a map from bare name → full name for the call handler.
+  // If a definition's name does not carry the prefix, fall back to
+  // MCP_PREFIX + bareName (unknown name still goes to Go's Dispatcher).
+  const fullNameOf = new Map(
+    definitions.map(d => [bareName(d.name), d.name]),
+  );
+
+  // tools/list: pass raw input_schema as inputSchema without copy or validation.
+  // The low-level Server.setRequestHandler does not call zodToJsonSchema, so
+  // plain JSON Schema objects are accepted here (D06).
+  mcp.server.setRequestHandler(ListToolsRequestSchema, async () => ({
+    tools: definitions.map(d => ({
+      name: bareName(d.name),
+      description: d.description,
+      inputSchema: d.input_schema,
+    })),
+  }));
+
+  // tools/call: forward to callTool exactly once; map the result to MCP shape.
+  mcp.server.setRequestHandler(CallToolRequestSchema, async (req) => {
+    const bare = req.params.name;
+    const full = fullNameOf.get(bare) ?? (MCP_PREFIX + bare);
+    const args = req.params.arguments ?? {};
+
+    let content, isError;
+    try {
+      const result = await callTool(full, args);
+      const raw = result.content;
+      const text = typeof raw === 'string' ? raw : JSON.stringify(raw ?? '');
+      content = [{ type: 'text', text }];
+      isError = Boolean(result.is_error);
+    } catch (err) {
+      // Rejected callTool (e.g. failPending) → readable error result,
+      // no MCP protocol error (protocol.py:204-217).
+      content = [{ type: 'text', text: err.message }];
+      isError = true;
+    }
+
+    return { content, isError };
+  });
+
+  return { type: 'sdk', name: 'longshot', instance: mcp };
+}