@anyslate/cli 0.1.0 → 0.2.0

package/src/mcp-client.mjs

@@ -1,7 +1,7 @@
 // Minimal JSON-RPC client for the AnySlate MCP service.
 //
 // The MCP service speaks the standard MCP JSON-RPC protocol. We only need
-// `tools/call` from the CLI — that one method covers `activity_submit`,
+// `tools/call` from the CLI - that one method covers `activity_submit`,
 // `checkpoint_session`, and `upload_artifact`.
 //
 // The server replies with `{ jsonrpc: '2.0', id, result | error }`. When the
@@ -9,12 +9,34 @@
 // JSON-parse it (the AnySlate dispatcher always returns JSON-encoded text).
 //
 // Streamable HTTP transport requires every non-initialize request to carry
-// an `Mcp-Session-Id` header (mcp-protocol.ts:2566). The CLI is one-shot per
+// an `Mcp-Session-Id` header (mcp-protocol.ts:5825). The CLI is one-shot per
 // invocation, so we run `initialize` first, capture the server-issued
 // session id from the response header, and reuse it for the `tools/call`.
+//
+// IMPORTANT (W2): the MCP wire protocol returns **HTTP 200 with
+// `result.isError === true`** for tool-level rejections — 403 handle denial,
+// 400 unsupported kind, 500 insert failure, tool-level 429. Trusting
+// `res.ok` alone reports every one of those as success. `callTool` therefore
+// inspects `result.isError` and maps it to `ok: false` with the embedded
+// status, which is what makes `--strict` and the checkpoint/upload-artifact
+// fail-closed contract actually mean anything.
+
+import { USER_AGENT } from './version.mjs';
 
 let nextRequestId = 1;
 
+const MCP_HEADERS = (token, sessionId) => {
+  const h = {
+    'content-type': 'application/json',
+    authorization: `Bearer ${token}`,
+    accept: 'application/json, text/event-stream',
+    'mcp-protocol-version': '2025-06-18',
+    'user-agent': USER_AGENT,
+  };
+  if (sessionId) h['mcp-session-id'] = sessionId;
+  return h;
+};
+
 async function readBody(res) {
   const ctype = res.headers.get('content-type') || '';
   // The MCP service may stream JSON-RPC results as text/event-stream
@@ -42,16 +64,153 @@ async function readBody(res) {
   }
 }
 
+/**
+ * Render a server error body as a human string, preserving `error_description`.
+ *
+ * Dropping `error_description` makes *revoked* and *mistyped* indistinguishable
+ * (defect #15) — the single most common real-world 401.
+ *
+ * @param {unknown} raw
+ * @returns {string|object|null}
+ */
+export function formatErrorPayload(raw) {
+  if (raw == null) return null;
+  if (typeof raw === 'string') return raw;
+  if (typeof raw !== 'object') return String(raw);
+
+  const desc =
+    typeof raw.error_description === 'string'
+      ? raw.error_description
+      : typeof raw.errorDescription === 'string'
+        ? raw.errorDescription
+        : null;
+  const err = raw.error;
+
+  if (typeof err === 'string' && err) {
+    return desc ? `${err}: ${desc}` : err;
+  }
+  if (err && typeof err === 'object') {
+    // JSON-RPC error object — keep the object so callers can read `.message`.
+    return err;
+  }
+  if (desc) return desc;
+  if (typeof raw.message === 'string') return raw.message;
+  return null;
+}
+
+/**
+ * Extract 429 metadata. `Retry-After` was never read and
+ * `retry_after_seconds`/`reset_at`/`reason` survived only in `raw`
+ * (defect #31). Surfacing only — no retry/backoff logic.
+ *
+ * @param {Response} res
+ * @param {unknown} raw
+ */
+export function extractRateLimit(res, raw) {
+  const header = res?.headers?.get ? res.headers.get('retry-after') : null;
+  const body = raw && typeof raw === 'object' ? raw : {};
+  const fromBody = body.retry_after_seconds ?? body.retryAfterSeconds;
+  const parsedHeader = header != null && header !== '' ? Number(header) : NaN;
+  const retryAfterSeconds = Number.isFinite(fromBody)
+    ? Number(fromBody)
+    : Number.isFinite(parsedHeader)
+      ? parsedHeader
+      : null;
+  return {
+    retry_after_seconds: retryAfterSeconds,
+    retry_after_header: header ?? null,
+    reset_at: body.reset_at ?? body.resetAt ?? null,
+    reason: body.reason ?? null,
+  };
+}
+
+/**
+ * Turn a thrown fetch error into something that names the host and the cause.
+ * Previously DNS failure, connection refused and timeout were all
+ * `request failed (fetch failed)` (defect #30).
+ *
+ * @param {unknown} err
+ * @param {string} host
+ * @param {number} timeoutMs
+ * @returns {string}
+ */
+/**
+ * Undici wraps the real cause: `fetch failed` carries `cause`, which for a
+ * refused/multi-address connect is an AggregateError whose `.errors[]` hold
+ * the codes. Walk the whole chain, or every connection error looks identical.
+ *
+ * @param {unknown} err
+ * @param {number} [depth]
+ * @returns {string|null}
+ */
+export function findErrorCode(err, depth = 0) {
+  if (!err || depth > 5) return null;
+  if (typeof err.code === 'string' && err.code) return err.code;
+  if (Array.isArray(err.errors)) {
+    for (const inner of err.errors) {
+      const code = findErrorCode(inner, depth + 1);
+      if (code) return code;
+    }
+  }
+  return findErrorCode(err.cause, depth + 1);
+}
+
+export function classifyNetworkError(err, host, timeoutMs) {
+  const message = String(err?.message ?? err ?? '');
+  const code = findErrorCode(err);
+  const seconds = Math.round((timeoutMs ?? 0) / 1000);
+
+  if (err?.name === 'AbortError' || /aborted/i.test(message)) {
+    return `timed out after ${seconds}s contacting ${host}`;
+  }
+  switch (code) {
+    case 'ENOTFOUND':
+      return `ENOTFOUND ${host} (DNS)`;
+    case 'EAI_AGAIN':
+      return `EAI_AGAIN ${host} (DNS)`;
+    case 'ECONNREFUSED':
+      return `ECONNREFUSED ${host}`;
+    case 'ECONNRESET':
+      return `ECONNRESET ${host}`;
+    case 'ETIMEDOUT':
+    case 'UND_ERR_CONNECT_TIMEOUT':
+    case 'UND_ERR_HEADERS_TIMEOUT':
+      return `timed out contacting ${host} (${code})`;
+    default:
+      break;
+  }
+  if (code && /CERT|SSL|TLS/i.test(code)) return `TLS error contacting ${host} (${code})`;
+  if (/certificate|self[- ]signed|SSL/i.test(message)) return `TLS error contacting ${host}`;
+  if (code) return `${code} ${host}`;
+  return `${message || 'request failed'} (${host})`;
+}
+
+/**
+ * Uniform failure line for every command. Network failures are not "server
+ * <status>" failures — printing `server 0` would be a lie.
+ *
+ * @param {string} prefix  e.g. `anyslate hook stop`
+ * @param {{status: number, data: unknown, networkError?: boolean}} res
+ * @returns {string}
+ */
+export function formatCallFailure(prefix, res) {
+  const msg = typeof res.data === 'string' ? res.data : JSON.stringify(res.data);
+  if (res.networkError) return `${prefix}: request failed: ${msg}\n`;
+  return `${prefix}: server ${res.status} — ${msg}\n`;
+}
+
+function hostOf(url) {
+  try {
+    return new URL(url).host;
+  } catch {
+    return url;
+  }
+}
+
 async function initializeSession({ url, token, fetchImpl, ac }) {
   const res = await fetchImpl(url, {
     method: 'POST',
-    headers: {
-      'content-type': 'application/json',
-      authorization: `Bearer ${token}`,
-      accept: 'application/json, text/event-stream',
-      'mcp-protocol-version': '2025-06-18',
-      'user-agent': 'anyslate-cli/0.1.0',
-    },
+    headers: MCP_HEADERS(token),
     body: JSON.stringify({
       jsonrpc: '2.0',
       id: nextRequestId++,
@@ -59,7 +218,7 @@ async function initializeSession({ url, token, fetchImpl, ac }) {
       params: {
         protocolVersion: '2025-06-18',
         capabilities: {},
-        clientInfo: { name: 'anyslate-cli', version: '0.1.0' },
+        clientInfo: { name: 'anyslate-cli', version: USER_AGENT.split('/')[1] },
       },
     }),
     signal: ac.signal,
@@ -67,45 +226,61 @@ async function initializeSession({ url, token, fetchImpl, ac }) {
   const sid = res.headers.get('mcp-session-id');
   if (!res.ok) {
     const raw = await readBody(res);
-    return { ok: false, status: res.status, sessionId: null, raw };
+    return { ok: false, status: res.status, sessionId: null, raw, res };
   }
   if (!sid) {
-    return { ok: false, status: res.status, sessionId: null, raw: { error: 'server omitted Mcp-Session-Id header on initialize' } };
+    return {
+      ok: false,
+      status: res.status,
+      sessionId: null,
+      raw: { error: 'server omitted Mcp-Session-Id header on initialize' },
+      res,
+    };
   }
-  // Best-effort `notifications/initialized` — server returns 202 and we
+  // Best-effort `notifications/initialized` - server returns 202 and we
   // proceed regardless. Required by spec; harmless if dropped on the floor.
   try {
     await fetchImpl(url, {
       method: 'POST',
-      headers: {
-        'content-type': 'application/json',
-        authorization: `Bearer ${token}`,
-        accept: 'application/json, text/event-stream',
-        'mcp-protocol-version': '2025-06-18',
-        'mcp-session-id': sid,
-        'user-agent': 'anyslate-cli/0.1.0',
-      },
+      headers: MCP_HEADERS(token, sid),
       body: JSON.stringify({ jsonrpc: '2.0', method: 'notifications/initialized', params: {} }),
       signal: ac.signal,
     });
   } catch {
-    // Swallow — we have the session id; the notification is advisory.
+    // Swallow - we have the session id; the notification is advisory.
   }
   return { ok: true, status: res.status, sessionId: sid, raw: null };
 }
 
 /**
  * @param {object} opts
- * @param {string} opts.apiUrl
+ * @param {string} opts.apiUrl  service ROOT (the client appends `/mcp`)
  * @param {string} opts.token  Bearer token (MCP token).
  * @param {string} opts.toolName
  * @param {Record<string, unknown>} opts.args
  * @param {typeof fetch} [opts.fetchImpl]  override for tests
  * @param {number} [opts.timeoutMs]
- * @returns {Promise<{ ok: boolean, status: number, data: unknown, raw: unknown }>}
+ * @returns {Promise<{ ok: boolean, status: number, data: unknown, raw: unknown,
+ *   isError?: boolean, networkError?: boolean, retryAfterSeconds?: number|null,
+ *   rateLimit?: object }>}
  */
-export async function callTool({ apiUrl, token, toolName, args, fetchImpl = fetch, timeoutMs = 15000, sessionId: presetSessionId }) {
-  const url = `${apiUrl.replace(/\/+$/, '')}/mcp`;
+export async function callTool({
+  apiUrl,
+  token,
+  toolName,
+  args,
+  fetchImpl = fetch,
+  timeoutMs = 15000,
+  sessionId: presetSessionId,
+}) {
+  // `apiUrl` is already normalized by loadConfig; strip again defensively so a
+  // direct caller cannot reintroduce `/mcp/mcp`.
+  const root = String(apiUrl ?? '')
+    .trim()
+    .replace(/\/+$/, '')
+    .replace(/(\/mcp)+$/i, '');
+  const url = `${root}/mcp`;
+  const host = hostOf(url);
   const ac = new AbortController();
   const timer = setTimeout(() => ac.abort(), timeoutMs);
 
@@ -116,12 +291,16 @@ export async function callTool({ apiUrl, token, toolName, args, fetchImpl = fetc
       if (!init.ok) {
         // Surface the auth/init failure exactly as if the tool call itself failed,
         // so the CLI's existing error handling (server 401 etc.) keeps working.
-        const errLike = init.raw && typeof init.raw === 'object' && 'error' in init.raw
-          ? init.raw.error
-          : init.raw && typeof init.raw === 'object' && 'message' in init.raw
-            ? init.raw
-            : { message: `initialize failed (HTTP ${init.status})` };
-        return { ok: false, status: init.status, data: errLike, raw: init.raw };
+        const formatted = formatErrorPayload(init.raw);
+        const errLike = formatted ?? { message: `initialize failed (HTTP ${init.status})` };
+        const out = { ok: false, status: init.status, data: errLike, raw: init.raw };
+        if (init.status === 429) {
+          const rl = extractRateLimit(init.res, init.raw);
+          out.rateLimit = rl;
+          out.retryAfterSeconds = rl.retry_after_seconds;
+          out.data = withRetryHint(errLike, rl);
+        }
+        return out;
       }
       sessionId = init.sessionId;
     }
@@ -136,39 +315,106 @@ export async function callTool({ apiUrl, token, toolName, args, fetchImpl = fetc
 
     const res = await fetchImpl(url, {
       method: 'POST',
-      headers: {
-        'content-type': 'application/json',
-        authorization: `Bearer ${token}`,
-        accept: 'application/json, text/event-stream',
-        'mcp-protocol-version': '2025-06-18',
-        'mcp-session-id': sessionId,
-        'user-agent': 'anyslate-cli/0.1.0',
-      },
+      headers: MCP_HEADERS(token, sessionId),
       body: JSON.stringify(body),
       signal: ac.signal,
     });
 
     const status = res.status;
     const raw = await readBody(res);
+    const rateLimit = status === 429 ? extractRateLimit(res, raw) : null;
 
+    const finish = (out) => {
+      if (rateLimit) {
+        out.rateLimit = rateLimit;
+        out.retryAfterSeconds = rateLimit.retry_after_seconds;
+        out.data = withRetryHint(out.data, rateLimit);
+      }
+      return out;
+    };
+
+    // JSON-RPC transport-level error.
     if (raw && typeof raw === 'object' && 'error' in raw && raw.error) {
-      return { ok: false, status, data: raw.error, raw };
+      return finish({ ok: false, status, data: formatErrorPayload(raw) ?? raw.error, raw });
     }
 
-    // `result.content[0].text` is the AnySlate dispatcher's JSON envelope.
     const result = raw && typeof raw === 'object' ? raw.result : null;
+
+    // ---- Tool-level error: HTTP 200 + result.isError === true (W2). ----
+    if (result && typeof result === 'object' && result.isError === true) {
+      const content = Array.isArray(result.content) ? result.content[0] : null;
+      const text = content && typeof content.text === 'string' ? content.text : null;
+      let parsed = null;
+      if (text) {
+        try {
+          parsed = JSON.parse(text);
+        } catch {
+          parsed = null;
+        }
+      }
+      if (parsed && typeof parsed === 'object') {
+        const embeddedStatus = Number.isFinite(parsed.status) ? Number(parsed.status) : status;
+        const data = formatErrorPayload(parsed) ?? parsed.error ?? text ?? 'tool returned isError';
+        const out = { ok: false, status: embeddedStatus, data, raw, isError: true };
+        if (embeddedStatus === 429) {
+          const rl = extractRateLimit(res, parsed);
+          out.rateLimit = rl;
+          out.retryAfterSeconds = rl.retry_after_seconds;
+          out.data = withRetryHint(data, rl);
+        }
+        return out;
+      }
+      return finish({
+        ok: false,
+        status,
+        data: text ?? 'tool returned isError with no content',
+        raw,
+        isError: true,
+      });
+    }
+
+    // `result.content[0].text` is the AnySlate dispatcher's JSON envelope.
     const content = result && Array.isArray(result.content) ? result.content[0] : null;
     if (content && content.type === 'text' && typeof content.text === 'string') {
       try {
         const parsed = JSON.parse(content.text);
-        return { ok: res.ok, status, data: parsed, raw };
+        return finish({ ok: res.ok, status, data: parsed, raw });
       } catch {
-        return { ok: res.ok, status, data: content.text, raw };
+        return finish({ ok: res.ok, status, data: content.text, raw });
       }
     }
 
-    return { ok: res.ok, status, data: result, raw };
+    // Non-2xx with no parseable JSON-RPC body: never print the literal `null`.
+    if (!res.ok) {
+      return finish({
+        ok: false,
+        status,
+        data: formatErrorPayload(raw) ?? `server returned HTTP ${status} with no JSON-RPC body`,
+        raw,
+      });
+    }
+
+    return finish({ ok: res.ok, status, data: result, raw });
+  } catch (e) {
+    return {
+      ok: false,
+      status: 0,
+      data: classifyNetworkError(e, host, timeoutMs),
+      raw: null,
+      networkError: true,
+    };
   } finally {
     clearTimeout(timer);
   }
 }
+
+function withRetryHint(data, rl) {
+  if (!rl) return data;
+  const bits = [];
+  if (rl.retry_after_seconds != null) bits.push(`retry after ${rl.retry_after_seconds}s`);
+  if (rl.reset_at) bits.push(`resets at ${rl.reset_at}`);
+  if (rl.reason) bits.push(String(rl.reason));
+  if (!bits.length) return data;
+  const base = typeof data === 'string' ? data : data == null ? 'rate limited' : JSON.stringify(data);
+  return `${base} — ${bits.join(', ')}`;
+}

package/src/runlog.mjs

@@ -0,0 +1,196 @@
+// W7 — persisted observability for a fail-open CLI.
+//
+// Exit 0 is correct policy: a network blip must never break a Claude Code
+// session. But the error strategy was "write to stderr", and Claude Code files
+// `exit 0 + stderr` as `hook_success` — 0 of 4,896 production hook_success
+// records carry stderr. The entire error channel had no receiver.
+//
+// So: persist every run. `~/.anyslate/cli-last-run.json` (mode 0600) plus a
+// capped NDJSON ring log. `anyslate doctor` reads them. Nothing here changes an
+// exit code.
+//
+// REDACTION: the record must never contain token material. Every value is run
+// through `redact()` before it is written, and there is a test asserting the
+// file never contains `as_mcp_` / `as_oauth_`.
+
+import { mkdirSync, readFileSync, writeFileSync, appendFileSync, statSync, renameSync } from 'node:fs';
+import { join } from 'node:path';
+import { anyslateDir } from './config.mjs';
+
+export const LAST_RUN_FILE = 'cli-last-run.json';
+export const RING_LOG_FILE = 'cli-runs.ndjson';
+
+/** Escalate only on persistence, not incidence. One failure is a blip. */
+export const ESCALATE_AFTER_CONSECUTIVE_FAILURES = 3;
+
+const RING_MAX_ENTRIES = 200;
+const RING_MAX_BYTES = 256 * 1024;
+
+const TOKEN_RE = /\b(as_mcp_|as_oauth_)[A-Za-z0-9_-]*/g;
+const BEARER_RE = /\bBearer\s+\S+/gi;
+
+/**
+ * Strip anything that looks like credential material from arbitrary data.
+ * @param {unknown} value
+ * @returns {unknown}
+ */
+export function redact(value) {
+  if (value == null) return value;
+  if (typeof value === 'string') {
+    return value.replace(TOKEN_RE, '[redacted-token]').replace(BEARER_RE, 'Bearer [redacted]');
+  }
+  if (Array.isArray(value)) return value.map(redact);
+  if (typeof value === 'object') {
+    const out = {};
+    for (const [k, v] of Object.entries(value)) {
+      if (/token|secret|authorization|password|bearer/i.test(k)) {
+        out[k] = v == null ? v : '[redacted]';
+        continue;
+      }
+      out[k] = redact(v);
+    }
+    return out;
+  }
+  return value;
+}
+
+export function lastRunPath(env = process.env) {
+  return join(anyslateDir(env), LAST_RUN_FILE);
+}
+export function ringLogPath(env = process.env) {
+  return join(anyslateDir(env), RING_LOG_FILE);
+}
+
+/**
+ * @param {NodeJS.ProcessEnv} [env]
+ * @returns {object|null}
+ */
+export function readLastRun(env = process.env) {
+  try {
+    const parsed = JSON.parse(readFileSync(lastRunPath(env), 'utf8'));
+    return parsed && typeof parsed === 'object' ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Persist the outcome of one CLI invocation.
+ *
+ * Never throws — an unwritable home directory must not turn a successful
+ * capture into a failure.
+ *
+ * @param {object} entry
+ * @param {string} entry.command
+ * @param {boolean} entry.ok
+ * @param {string} [entry.apiUrl]
+ * @param {number} [entry.status]
+ * @param {boolean} [entry.isError]
+ * @param {boolean} [entry.networkError]
+ * @param {unknown} [entry.error]
+ * @param {number} [entry.exitCode]
+ * @param {NodeJS.ProcessEnv} [env]
+ * @returns {{consecutiveFailures: number, lastSuccessAt: string|null, failingSince: string|null}}
+ */
+export function recordRun(entry, env = process.env) {
+  const previous = readLastRun(env) || {};
+  const ts = new Date().toISOString();
+
+  const consecutiveFailures = entry.ok
+    ? 0
+    : Number.isFinite(previous.consecutive_failures)
+      ? Number(previous.consecutive_failures) + 1
+      : 1;
+  const lastSuccessAt = entry.ok ? ts : (previous.last_success_at ?? null);
+  const failingSince = entry.ok ? null : (previous.failing_since ?? ts);
+
+  const record = redact({
+    ts,
+    command: entry.command,
+    ok: !!entry.ok,
+    exit_code: entry.exitCode ?? (entry.ok ? 0 : 1),
+    api_url: entry.apiUrl ?? null,
+    endpoint: entry.apiUrl ? `${String(entry.apiUrl).replace(/\/+$/, '')}/mcp` : null,
+    http_status: entry.status ?? null,
+    is_error: entry.isError ?? false,
+    network_error: entry.networkError ?? false,
+    error: entry.error == null ? null : typeof entry.error === 'string' ? entry.error : JSON.stringify(entry.error),
+    consecutive_failures: consecutiveFailures,
+    last_success_at: lastSuccessAt,
+    failing_since: failingSince,
+    cli_version: entry.version ?? null,
+  });
+
+  try {
+    const dir = anyslateDir(env);
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+    writeFileSync(join(dir, LAST_RUN_FILE), `${JSON.stringify(record, null, 2)}\n`, { mode: 0o600 });
+    appendRing(dir, record);
+  } catch {
+    // Observability must never be load-bearing.
+  }
+
+  return { consecutiveFailures, lastSuccessAt, failingSince };
+}
+
+function appendRing(dir, record) {
+  const path = join(dir, RING_LOG_FILE);
+  try {
+    let size = 0;
+    try {
+      size = statSync(path).size;
+    } catch {
+      size = 0;
+    }
+    if (size > RING_MAX_BYTES) {
+      // Cheap rotation: keep the newest half.
+      try {
+        const lines = readFileSync(path, 'utf8').split('\n').filter(Boolean);
+        const keep = lines.slice(-Math.floor(RING_MAX_ENTRIES / 2));
+        writeFileSync(`${path}.tmp`, `${keep.join('\n')}\n`, { mode: 0o600 });
+        renameSync(`${path}.tmp`, path);
+      } catch {
+        writeFileSync(path, '', { mode: 0o600 });
+      }
+    }
+    appendFileSync(path, `${JSON.stringify(record)}\n`, { mode: 0o600 });
+  } catch {
+    // ignore
+  }
+}
+
+/**
+ * Should a SessionStart hook escalate to the model/user?
+ *
+ * @param {{consecutiveFailures: number, failingSince: string|null}} state
+ * @returns {boolean}
+ */
+export function shouldEscalate(state) {
+  if (!state) return false;
+  if (state.consecutiveFailures >= ESCALATE_AFTER_CONSECUTIVE_FAILURES) return true;
+  if (state.failingSince) {
+    const since = Date.parse(state.failingSince);
+    if (Number.isFinite(since) && Date.now() - since > 24 * 60 * 60 * 1000) return true;
+  }
+  return false;
+}
+
+/**
+ * The structured stdout block Claude Code actually renders.
+ * `hook_system_message` and `hook_additional_context` are both verified working
+ * channels; plain stderr is not.
+ *
+ * @param {{consecutiveFailures: number, failingSince: string|null, error?: string|null}} state
+ * @returns {string}
+ */
+export function escalationPayload(state) {
+  const since = state.failingSince ? ` since ${String(state.failingSince).slice(0, 10)}` : '';
+  const because = state.error ? ` (${state.error})` : '';
+  return `${JSON.stringify({
+    hookSpecificOutput: {
+      hookEventName: 'SessionStart',
+      additionalContext: `AnySlate capture has been failing${since}${because}. Run \`anyslate doctor\`.`,
+    },
+    systemMessage: 'AnySlate capture is failing — run `anyslate doctor`.',
+  })}\n`;
+}