@myspec/mcp-server 0.5.0-next.113 → 0.5.0-next.115

package/README.md

@@ -303,6 +303,7 @@ Local state is stored under `~/.myspec/` (alongside the on-disk cache root), spl
 | `list_spec_sessions` | `project_id`, optional `archive_filter` (`active`/`archived`/`all`), optional `status`, optional `query`, optional `limit`, optional `offset` | Paginated session metadata plus `session_summary` and `context_size_bytes` — never the context itself or the chat transcript. Default 10 per page, capped at 20 |
 | `get_spec_session` | `session_id`, optional `include_context` | Session metadata (status, counters, timestamps, `archived_at`), `session_summary`, `context_size_bytes` and `context_keys`. `include_context=true` returns the full context under a 1 MiB ceiling (above it the tool errors with the actual size). The chat transcript is never returned |
 | `rename_spec_session` | `session_id`, `session_summary` | Sets `context.sessionSummary` (max 500 chars) via read-merge-write, preserving every other context key; works on archived sessions; refuses when the context is not a JSON object. Returns `renamed`, `session_id`, `session_summary` |
+| `start_spec_session` | `project_id`, `mode` (`generate`/`edit`), `prompt`, optional `workflow_id`, `language`, `model_id`, `attachment_ids[]`, `spec_file_ids[]`, `session_title` | Starts a NEW chat session with an opening prompt you compose, runs its first turn through the webapp, and returns `session_url`, `assistant_text`, `session_id`, `project_id`, `pending_action` and `next_step_instruction` (plus `first_turn_error` / `warnings` when relevant). One call = one real session and real model spend, so call it once per intent and check `list_spec_sessions` before retrying after a timeout. Waits up to 75 s for the first reply — one budget covering both the request and the stream that follows — then returns `pending_action: turn_still_running` while the turn finishes in the background. `attachment_ids` / `spec_file_ids` are capped at 25 each and resolved before the session is created. See [Brownfield sessions](#brownfield-sessions-start-the-bridge-first) |
 | `archive_spec_session` | `session_id` | Archives the session (idempotent — re-archiving keeps the original `archived_at`); the required confirmation step before `delete_spec_session` |
 | `unarchive_spec_session` | `session_id` | Returns an archived session to the active list |
 | `delete_spec_session` | `session_id` | Soft-deletes an ARCHIVED session. Refuses non-archived sessions with an archive-first error and never archives on the caller's behalf |
@@ -313,6 +314,34 @@ Local state is stored under `~/.myspec/` (alongside the on-disk cache root), spl
 | `write_artifact_revision` | `artifact_id`, `files[]`, optional `base_revision` (patch mode), `remove[]`, `expected_version`, `message`, `entry_path` | Appends an immutable revision. Full mode replaces the whole bundle; patch mode (with `base_revision`) sends only changed files plus paths to `remove`. A stale `expected_version` is reported as a conflict naming the new head — re-read with `get_artifact` and retry |
 | `rollback_artifact` | `artifact_id`, `revision_number`, optional `expected_version`, `message` | Restores an earlier revision by APPENDING a revision with its files (`git revert` semantics); history is never rewritten, but only the newest N revisions are retained (50 by default, `ARTIFACT_MAX_REVISIONS` on the platform), so a pruned target answers not found |
 
+### Brownfield sessions: start the bridge first
+
+`start_spec_session` hands MySpec a prompt; it does **not** hand it your files.
+For a **brownfield** generate workflow (`openspec-brownfield-v1`,
+`myspec-brownfield-v1`) the cloud agent reads your codebase over the reverse-MCP
+bridge, so the ordering is a contract:
+
+```bash
+# 1. Start the bridge and LEAVE IT RUNNING
+npx -y @myspec/mcp-server reverse --root <path>
+# 2. Then call start_spec_session
+```
+
+Reverse-MCP presence is keyed by **user**, not by session, so a bridge already
+running under the same account is automatically reachable by the new session's
+first turn — there is nothing to wire up per session. That is also why the
+bridge must **outlive the tool call**: the session keeps exploring the codebase
+while you work in the webapp.
+
+The tool warns (it never refuses) when it can see that no bridge is connected.
+If it cannot tell — no agent URL discovered yet, or the ai-agent is unreachable,
+or the presence check itself takes longer than 3 s — it says nothing and starts
+the session anyway.
+
+The live check runs for a brownfield **generate** workflow only. An edit session
+against an existing codebase (`myspec-edit-brownfield-v1`) wants the bridge just
+as much; it simply starts without asking.
+
 ### Download destinations
 
 `download_spec_file` prefers the **`.specs/` folder in the MCP server's working

package/dist/index.js

@@ -2876,6 +2876,35 @@ var PlatformClient = class {
   async getSpecSession(sessionId) {
     return this.withTokenRetry((jwt, c) => c.session.getSpecSession(sessionId, jwt));
   }
+  /**
+   * Creates a spec session with its context seeded in the SAME request
+   * (CR-003 AC1, AR-005).
+   *
+   * The context must be complete here, not written by a follow-up update: the
+   * follow-up can land AFTER the first chat request, leaving
+   * `context.workflow.workflowId` unset so the ai-agent falls back to its
+   * default edit workflow (issue #1045).
+   */
+  async createSession(projectId, context) {
+    return this.withTokenRetry((jwt, c) => c.session.createSpecSession({ projectId, context }, jwt));
+  }
+  /**
+   * A currently-valid access token, for a tool that must make its own
+   * authenticated request rather than go through the platform clients
+   * (CR-003 AC2) — `start_spec_session` calls the webapp's chat proxy.
+   *
+   * Paired with {@link forceRefreshAccessToken}, mirroring the
+   * `getAccessToken` / `forceRefresh` pair `discoverConfig` already consumes,
+   * so the one-refresh-and-retry idiom is written once and used identically
+   * everywhere (AR-016).
+   */
+  async getAccessToken() {
+    return this.tokenManager.getValidAccessToken();
+  }
+  /** Forces a token refresh and returns the new token. See {@link getAccessToken}. */
+  async forceRefreshAccessToken() {
+    return this.tokenManager.forceRefresh();
+  }
   /**
    * Writes ONLY the session's `context` field (rename's read-merge-write).
    * Deliberately narrow: status, chatHistory and the counters stay
@@ -5540,46 +5569,650 @@ var revokeStreamTokenTool = {
   }
 };
 
+// src/server/tools/start_spec_session.ts
+import { z as z37 } from "zod";
+
+// src/server/tools/start-session-core.ts
+var START_SESSION_WAIT_MS = 75e3;
+var MAX_REFERENCE_IDS = 25;
+var SESSION_TITLE_MAX_LENGTH = 500;
+function httpErrorStatus(err) {
+  if (typeof err !== "object" || err === null) {
+    return void 0;
+  }
+  const candidate = err.status;
+  if (typeof candidate === "number") {
+    return candidate;
+  }
+  const message = err.message;
+  if (typeof message !== "string") {
+    return void 0;
+  }
+  const match = /HTTP (\d{3}):/.exec(message);
+  return match ? Number(match[1]) : void 0;
+}
+var SPEC_SESSION_LANGUAGES = ["en", "zh", "ja", "vi"];
+var GENERATE_WORKFLOW_VARIANT_REFS = [
+  {
+    id: "myspec-greenfield-v1",
+    workflowId: "generate-greenfield-myspec",
+    mode: "generate",
+    scope: "greenfield"
+  },
+  {
+    id: "enterprise-greenfield-v1",
+    workflowId: "generate-greenfield-enterprise",
+    mode: "generate",
+    scope: "greenfield"
+  },
+  {
+    id: "speckit-greenfield-v1",
+    workflowId: "generate-greenfield-speckit",
+    mode: "generate",
+    scope: "greenfield"
+  },
+  {
+    id: "openspec-brownfield-v1",
+    workflowId: "generate-brownfield-openspec",
+    mode: "generate",
+    scope: "brownfield"
+  },
+  {
+    id: "myspec-brownfield-v1",
+    workflowId: "generate-brownfield-myspec",
+    mode: "generate",
+    scope: "brownfield"
+  }
+];
+var EDIT_WORKFLOW_VARIANT_REFS = [
+  {
+    id: "myspec-edit-v1",
+    workflowId: "edit-greenfield-myspec",
+    mode: "edit",
+    scope: "greenfield"
+  },
+  {
+    id: "myspec-edit-brownfield-v1",
+    workflowId: "edit-brownfield-myspec",
+    mode: "edit",
+    scope: "brownfield"
+  }
+];
+var DEFAULT_GENERATE_WORKFLOW_ID = "myspec-greenfield-v1";
+var DEFAULT_EDIT_WORKFLOW_ID = "myspec-edit-v1";
+var ALL_WORKFLOW_VARIANT_REFS = [
+  ...GENERATE_WORKFLOW_VARIANT_REFS,
+  ...EDIT_WORKFLOW_VARIANT_REFS
+];
+function knownIdList() {
+  return ALL_WORKFLOW_VARIANT_REFS.map((v) => v.id).join(", ");
+}
+function defaultVariant(mode) {
+  const id = mode === "generate" ? DEFAULT_GENERATE_WORKFLOW_ID : DEFAULT_EDIT_WORKFLOW_ID;
+  const variant = ALL_WORKFLOW_VARIANT_REFS.find((v) => v.id === id);
+  if (!variant) {
+    throw new Error(`workflow catalog is missing its default variant "${id}"`);
+  }
+  return variant;
+}
+function resolveWorkflow(mode, workflowId) {
+  if (workflowId === void 0 || workflowId === "") {
+    return { ok: true, variant: defaultVariant(mode) };
+  }
+  const variant = ALL_WORKFLOW_VARIANT_REFS.find((v) => v.id === workflowId);
+  if (!variant) {
+    return {
+      ok: false,
+      message: `workflow_id "${workflowId}" is not a known MySpec workflow. Pass one of: ${knownIdList()} \u2014 or omit workflow_id to use the default for mode "${mode}".`
+    };
+  }
+  if (variant.mode !== mode) {
+    return {
+      ok: false,
+      message: `mode "${mode}" contradicts workflow_id "${workflowId}", which is a "${variant.mode}" workflow. Pass mode "${variant.mode}" with this workflow_id, or omit workflow_id to use the default "${mode}" workflow.`
+    };
+  }
+  return { ok: true, variant };
+}
+var OPENSPEC_ROOT = "openspec";
+var OPENSPEC_CHANGES_DIR = "changes";
+var OPENSPEC_ARCHIVE_DIR = "archive";
+function bundleNameFromSpecFilePath(filePath) {
+  const segments = filePath.split("/");
+  if (segments[0] === "specs" && segments.length >= 3) {
+    return segments.slice(1, -1).join("/");
+  }
+  if (segments[0] === OPENSPEC_ROOT && segments[1] === OPENSPEC_CHANGES_DIR && segments.length >= 4) {
+    const changeId = segments[2];
+    return changeId === OPENSPEC_ARCHIVE_DIR ? "" : changeId ?? "";
+  }
+  return "";
+}
+function specFileDisplayName(filePath) {
+  return filePath.split("/").pop() ?? filePath;
+}
+function specFilePartRef(file) {
+  return {
+    specFileId: file.id,
+    name: specFileDisplayName(file.filePath),
+    specType: file.fileType,
+    bundleName: bundleNameFromSpecFilePath(file.filePath),
+    filePath: file.filePath
+  };
+}
+function buildPromptParts(prompt, attachments, specFiles) {
+  const parts = [{ type: "text", text: prompt }];
+  for (const attachment of attachments) {
+    parts.push({
+      type: "data-user-attachment-ref",
+      data: {
+        id: attachment.id,
+        name: attachment.name,
+        mimeType: attachment.mimeType,
+        size: attachment.size
+      }
+    });
+  }
+  for (const specFile of specFiles) {
+    parts.push({
+      type: "data-user-specfile-ref",
+      data: {
+        specFileId: specFile.specFileId,
+        name: specFile.name,
+        specType: specFile.specType,
+        bundleName: specFile.bundleName,
+        filePath: specFile.filePath
+      }
+    });
+  }
+  return parts;
+}
+function buildInitialSessionContext(workflowId, sessionTitle) {
+  return {
+    workflow: { version: 1, workflowId },
+    ...sessionTitle === void 0 || sessionTitle === "" ? {} : { sessionSummary: sessionTitle }
+  };
+}
+function stripTrailingSlash3(value) {
+  return value.endsWith("/") ? value.slice(0, -1) : value;
+}
+function buildFirstTurnRequest(input) {
+  return {
+    url: `${stripTrailingSlash3(input.webappUrl)}/api/v1/chat/${input.sessionId}`,
+    method: "POST",
+    headers: {
+      authorization: `Bearer ${input.accessToken}`,
+      "content-type": "application/json",
+      // The header ai-agent already segments analytics on (#81).
+      "x-client-type": "mcp-server"
+    },
+    body: {
+      parts: input.parts,
+      ...input.modelId === void 0 ? {} : { modelId: input.modelId },
+      ...input.language === void 0 ? {} : { language: input.language },
+      version: 1
+    }
+  };
+}
+var CARD_PENDING_ACTIONS = {
+  "data-mcq-form": "mcq_form_pending",
+  "data-spec-file": "spec_file_pending_decision",
+  "data-review-feedback": "review_feedback_pending",
+  "data-user-choice-prompt": "user_choice_pending"
+};
+function cardPendingAction(frame) {
+  const type = typeof frame.type === "string" ? frame.type : "";
+  const action = CARD_PENDING_ACTIONS[type];
+  if (action === void 0) {
+    return null;
+  }
+  if (type === "data-spec-file" || type === "data-review-feedback") {
+    const data = frame.data;
+    if (typeof data === "object" && data !== null && data.superseded === true) {
+      return null;
+    }
+  }
+  return action;
+}
+function applyFrame(raw, state) {
+  if (raw === "[DONE]") {
+    return;
+  }
+  let frame;
+  try {
+    const parsed = JSON.parse(raw);
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+      return;
+    }
+    frame = parsed;
+  } catch {
+    return;
+  }
+  if (frame.type === "text-delta") {
+    const delta = typeof frame.delta === "string" ? frame.delta : "";
+    state.text += delta;
+    return;
+  }
+  const card = cardPendingAction(frame);
+  if (card !== null) {
+    state.card = card;
+  }
+}
+function readFirstTurnStream(body) {
+  const state = {
+    text: "",
+    card: null,
+    error: null
+  };
+  const drained = (async () => {
+    const reader = body.getReader();
+    const decoder = new TextDecoder();
+    let buffer = "";
+    for (; ; ) {
+      const { done, value } = await reader.read();
+      if (done) {
+        break;
+      }
+      buffer += decoder.decode(value, { stream: true });
+      let boundary = buffer.indexOf("\n\n");
+      while (boundary !== -1) {
+        const frame = buffer.slice(0, boundary);
+        buffer = buffer.slice(boundary + 2);
+        for (const line of frame.split("\n")) {
+          if (line.startsWith("data:")) {
+            applyFrame(line.slice(5).trim(), state);
+          }
+        }
+        boundary = buffer.indexOf("\n\n");
+      }
+    }
+    for (const line of buffer.split("\n")) {
+      if (line.startsWith("data:")) {
+        applyFrame(line.slice(5).trim(), state);
+      }
+    }
+  })().catch((err) => {
+    state.error = err instanceof Error ? err.message : String(err);
+  });
+  return {
+    drained,
+    snapshot: () => ({
+      assistantText: state.text,
+      pendingCard: state.card,
+      streamError: state.error
+    })
+  };
+}
+function awaitWithinBudget(drained, waitMs) {
+  return new Promise((resolve3) => {
+    const timer = setTimeout(() => {
+      resolve3(false);
+    }, waitMs);
+    void drained.then(
+      () => {
+        clearTimeout(timer);
+        resolve3(true);
+      },
+      () => {
+        clearTimeout(timer);
+        resolve3(true);
+      }
+    );
+  });
+}
+function raceWithinBudget(promise, waitMs) {
+  return new Promise((resolve3) => {
+    const timer = setTimeout(() => {
+      resolve3({ status: "expired" });
+    }, waitMs);
+    void promise.then(
+      (value) => {
+        clearTimeout(timer);
+        resolve3({ status: "settled", value });
+      },
+      (error) => {
+        clearTimeout(timer);
+        resolve3({ status: "failed", error });
+      }
+    );
+  });
+}
+async function drainLateFirstTurn(body) {
+  if (body === null || body === void 0) {
+    return;
+  }
+  const reader = body.getReader();
+  try {
+    for (; ; ) {
+      const chunk = await reader.read();
+      if (chunk.done) {
+        return;
+      }
+    }
+  } catch {
+  }
+}
+function startWaitBudget(totalMs = START_SESSION_WAIT_MS) {
+  const deadline = Date.now() + totalMs;
+  return {
+    remaining: () => Math.max(0, deadline - Date.now())
+  };
+}
+var ERROR_DETAIL_MAX_BYTES = 1024;
+var ERROR_DETAIL_MAX_CHARS = 300;
+async function readErrorDetail(body, waitMs = 2e3) {
+  if (body === null || body === void 0 || body.locked) {
+    return "";
+  }
+  const reader = body.getReader();
+  const read = (async () => {
+    const decoder = new TextDecoder();
+    let text2 = "";
+    let bytes = 0;
+    for (; ; ) {
+      const chunk = await reader.read();
+      if (chunk.done) {
+        return text2;
+      }
+      bytes += chunk.value.byteLength;
+      text2 += decoder.decode(chunk.value, { stream: true });
+      if (bytes >= ERROR_DETAIL_MAX_BYTES) {
+        return text2;
+      }
+    }
+  })();
+  const race = await raceWithinBudget(read, waitMs);
+  void reader.cancel().catch(() => void 0);
+  if (race.status !== "settled") {
+    return "";
+  }
+  const text = race.value.replace(/\s+/g, " ").trim();
+  return text.length > ERROR_DETAIL_MAX_CHARS ? `${text.slice(0, ERROR_DETAIL_MAX_CHARS)}\u2026` : text;
+}
+function buildSessionUrl(webappUrl, projectId, sessionId) {
+  return `${stripTrailingSlash3(webappUrl)}/projects/${projectId}/chats/${sessionId}`;
+}
+var HANDOFF_INSTRUCTION = "Give session_url to the user and tell them to open it in MySpec to continue this session. Your part is done: do NOT try to answer MySpec, drive the workflow, or call this tool again for the same intent.";
+function buildStartSessionResult(input) {
+  const instruction = [HANDOFF_INSTRUCTION];
+  if (input.pendingAction === "turn_still_running") {
+    instruction.push(
+      "The first turn is still in progress; it is being finished in the background, and opening the URL will show the completed turn."
+    );
+  }
+  if (input.firstTurnError !== void 0) {
+    instruction.push(
+      "The session was created but its first turn could not be started, so the prompt has not been sent yet; the user can send it from the session page."
+    );
+  }
+  return {
+    // Every result for a session that WAS created carries the identifiers,
+    // including one reporting a failed first turn (AR-011 AC8).
+    session_url: buildSessionUrl(input.webappUrl, input.projectId, input.sessionId),
+    session_id: input.sessionId,
+    project_id: input.projectId,
+    assistant_text: input.assistantText,
+    pending_action: input.pendingAction,
+    ...input.firstTurnError === void 0 ? {} : { first_turn_error: input.firstTurnError },
+    ...input.warnings === void 0 || input.warnings.length === 0 ? {} : { warnings: [...input.warnings] },
+    next_step_instruction: instruction.join(" ")
+  };
+}
+var START_SESSION_DESCRIPTION_BASE = "Start a NEW MySpec chat session on the user's behalf with an opening prompt you compose, run its first turn, and hand back a URL for the user to continue in the MySpec webapp. Compose the prompt yourself from what you know about this repository and the user's intent \u2014 that context is the whole point, and it is lost if the user has to retype it. ONE invocation starts exactly ONE real chat session and consumes model tokens billed to the token owner, so call it ONCE PER INTENT, never in a loop. After a timeout or a transport error, call list_spec_sessions BEFORE invoking again \u2014 the session may already exist, and a retry would create a duplicate. Your responsibility ENDS at relaying the returned session_url to the user: do NOT attempt to drive the MySpec workflow yourself. Arguments: project_id, mode (generate | edit) and prompt are required; workflow_id, language, model_id, attachment_ids, spec_file_ids and session_title are optional. Returns session_url, assistant_text, session_id, project_id, pending_action and next_step_instruction; plus first_turn_error when the session was created but its first turn could not run, and (stdio only) warnings when something about the setup will limit the session \u2014 neither of which means the session is missing, so relay session_url either way.";
+
+// src/server/tools/start_spec_session.ts
+var BRIDGE_COMMAND = "npx -y @myspec/mcp-server reverse --root <path>";
+var inputSchema35 = {
+  project_id: z37.string().min(1).describe("UUID of the project to start the session in."),
+  mode: z37.enum(["generate", "edit"]).describe(
+    "'generate' writes a new spec bundle from scratch; 'edit' changes the spec files of an existing bundle."
+  ),
+  prompt: z37.string().min(1).describe(
+    "The opening message. Write it as the user would: what they want specced, and the repository context you have gathered that they would otherwise have to retype."
+  ),
+  workflow_id: z37.string().optional().describe(
+    "Workflow variant id, e.g. myspec-greenfield-v1, enterprise-greenfield-v1, speckit-greenfield-v1, openspec-brownfield-v1, myspec-brownfield-v1, myspec-edit-v1, myspec-edit-brownfield-v1. Omit to use the default for the chosen mode. Must agree with mode \u2014 a contradiction is rejected, not silently resolved."
+  ),
+  language: z37.enum(SPEC_SESSION_LANGUAGES).optional().describe(
+    "Output language the session locks to on its first turn. Defaults to 'en'. A session's language is immutable once set."
+  ),
+  model_id: z37.string().optional().describe("Model id to run the session with, e.g. openai:gpt-6-astra."),
+  attachment_ids: z37.array(z37.string().min(1)).max(MAX_REFERENCE_IDS).optional().describe(
+    `Project attachment ids to cite in the opening message, as the composer @-mentions do. At most ${String(MAX_REFERENCE_IDS)}.`
+  ),
+  spec_file_ids: z37.array(z37.string().min(1)).max(MAX_REFERENCE_IDS).optional().describe(
+    `Existing spec file ids to cite in the opening message. Required in practice for edit sessions. At most ${String(MAX_REFERENCE_IDS)}.`
+  ),
+  session_title: z37.string().min(1).max(SESSION_TITLE_MAX_LENGTH).optional().describe(
+    `Human-readable session title, stored as context.sessionSummary (max ${String(SESSION_TITLE_MAX_LENGTH)} characters). A workflow that names the session itself during its interview will overwrite it, exactly as in the webapp.`
+  )
+};
+var BRIDGE_ORDERING_NOTE = " BROWNFIELD WORKFLOWS: start the reverse-MCP bridge with `" + BRIDGE_COMMAND + "` BEFORE calling this tool, so the very first turn can already read the local codebase. Keep the bridge RUNNING after this tool returns \u2014 the session keeps reading the local codebase while the user works in the webapp.";
+function httpUrlOrNull(value) {
+  if (value === void 0 || value === "") {
+    return null;
+  }
+  try {
+    const parsed = new URL(value);
+    return parsed.protocol === "http:" || parsed.protocol === "https:" ? value : null;
+  } catch {
+    return null;
+  }
+}
+function notFoundAsNull(err) {
+  if (httpErrorStatus(err) === 404) {
+    return null;
+  }
+  throw err;
+}
+async function resolveAttachments(ctx, projectId, ids) {
+  const found = await Promise.all(
+    ids.map((id) => ctx.client.getAttachmentMetadata(id).catch(notFoundAsNull))
+  );
+  const refs = [];
+  const unresolved = [];
+  ids.forEach((id, index) => {
+    const attachment = found[index];
+    if (attachment?.projectId !== projectId) {
+      unresolved.push(id);
+      return;
+    }
+    refs.push({
+      id: attachment.id,
+      name: attachment.name,
+      mimeType: attachment.mimeType,
+      size: attachment.fileSizeBytes
+    });
+  });
+  return { refs, unresolved };
+}
+async function resolveSpecFiles(ctx, projectId, ids) {
+  const found = await Promise.all(
+    ids.map((id) => ctx.client.getFileMetadata(id).catch(notFoundAsNull))
+  );
+  const refs = [];
+  const unresolved = [];
+  ids.forEach((id, index) => {
+    const file = found[index];
+    if (file?.projectId !== projectId) {
+      unresolved.push(id);
+      return;
+    }
+    refs.push(specFilePartRef({ id: file.id, filePath: file.filePath, fileType: file.fileType }));
+  });
+  return { refs, unresolved };
+}
+var startSpecSessionTool = {
+  name: "start_spec_session",
+  description: START_SESSION_DESCRIPTION_BASE + BRIDGE_ORDERING_NOTE,
+  inputSchema: inputSchema35,
+  handler: async (args, ctx) => {
+    const webappUrl = httpUrlOrNull(ctx.webappUrl);
+    if (webappUrl === null) {
+      return errorResult(
+        "start_spec_session is unavailable: this server has no webapp URL. No session was created. Check --user-auth-url / MYSPEC_USER_AUTH_URL, which the webapp URL is derived from."
+      );
+    }
+    const resolution = resolveWorkflow(args.mode, args.workflow_id);
+    if (!resolution.ok) {
+      return errorResult(`start_spec_session was NOT started: ${resolution.message}`);
+    }
+    const budget = startWaitBudget();
+    const [attachments, specFiles] = await Promise.all([
+      resolveAttachments(ctx, args.project_id, args.attachment_ids ?? []),
+      resolveSpecFiles(ctx, args.project_id, args.spec_file_ids ?? [])
+    ]);
+    const unresolved = [...attachments.unresolved, ...specFiles.unresolved];
+    if (unresolved.length > 0) {
+      return errorResult(
+        `start_spec_session was NOT started: these ids do not resolve within project ${args.project_id}: ${unresolved.join(", ")}. No session was created.`
+      );
+    }
+    const warnings = [];
+    if (resolution.variant.mode === "generate" && resolution.variant.scope === "brownfield") {
+      const connected = await ctx.probeReverseMcpPresence?.().catch(() => null);
+      if (connected === false) {
+        warnings.push(
+          `No reverse-MCP bridge is connected for this account, so this brownfield session cannot read the local codebase yet. Start one with \`${BRIDGE_COMMAND}\` and leave it running.`
+        );
+      }
+    }
+    const session = await ctx.client.createSession(
+      args.project_id,
+      buildInitialSessionContext(resolution.variant.workflowId, args.session_title)
+    );
+    const failedWith = (assistantText, detail) => jsonResult(
+      buildStartSessionResult({
+        webappUrl,
+        projectId: args.project_id,
+        sessionId: session.id,
+        assistantText,
+        pendingAction: "none",
+        firstTurnError: detail,
+        warnings
+      })
+    );
+    const failed = (detail) => failedWith("", detail);
+    const parts = buildPromptParts(args.prompt, attachments.refs, specFiles.refs);
+    const sendFirstTurn = (token) => {
+      const request = buildFirstTurnRequest({
+        webappUrl,
+        sessionId: session.id,
+        accessToken: token,
+        parts,
+        modelId: args.model_id,
+        language: args.language
+      });
+      return fetch(request.url, {
+        method: request.method,
+        headers: request.headers,
+        body: JSON.stringify(request.body)
+      });
+    };
+    const send = async (token) => {
+      const pending = sendFirstTurn(token);
+      const race = await raceWithinBudget(pending, budget.remaining());
+      if (race.status === "failed") {
+        throw race.error;
+      }
+      if (race.status === "expired") {
+        const lateDrain = pending.then((late) => drainLateFirstTurn(late.body)).catch(() => void 0);
+        void lateDrain;
+        return "expired";
+      }
+      return race.value;
+    };
+    let response;
+    let rejectedOnce = false;
+    try {
+      response = await send(ctx.accessToken ?? await ctx.client.getAccessToken());
+      if (response !== "expired" && response.status === 401) {
+        rejectedOnce = true;
+        await readErrorDetail(response.body);
+        response = await send(await ctx.client.forceRefreshAccessToken());
+      }
+    } catch (err) {
+      return failed(
+        `the first-turn request to the webapp failed: ${err instanceof Error ? err.message : String(err)}`
+      );
+    }
+    if (response === "expired") {
+      const seconds = String(START_SESSION_WAIT_MS / 1e3);
+      return failed(
+        rejectedOnce ? `the webapp rejected the access token (HTTP 401) and the retry ran out of the ${seconds}s budget, so the first turn did not run` : `the webapp did not answer the first-turn request within ${seconds}s; the turn may still be running`
+      );
+    }
+    if (!response.ok || response.body === null) {
+      const base = response.status === 401 ? "the webapp rejected the access token twice (HTTP 401), so the first turn did not run" : `the webapp chat endpoint answered HTTP ${String(response.status)}`;
+      const detail = redactSensitive(await readErrorDetail(response.body));
+      return failed(detail === "" ? base : `${base}: ${detail}`);
+    }
+    const stream = readFirstTurnStream(response.body);
+    const completed = await awaitWithinBudget(stream.drained, budget.remaining());
+    const snapshot = stream.snapshot();
+    if (completed && snapshot.streamError !== null) {
+      return failedWith(snapshot.assistantText, `the first-turn stream ended early: ${redactSensitive(snapshot.streamError)}`);
+    }
+    const pendingAction = completed ? snapshot.pendingCard ?? "none" : "turn_still_running";
+    return jsonResult(
+      buildStartSessionResult({
+        webappUrl,
+        projectId: args.project_id,
+        sessionId: session.id,
+        assistantText: snapshot.assistantText,
+        pendingAction,
+        warnings
+      })
+    );
+  }
+};
+
 // src/server/server.ts
 function buildServer(deps) {
   const server = new McpServer({
     name: "myspec-mcp-server",
     version: deps.version ?? "0.1.0"
   });
-  registerTool(server, listProjectsTool, deps.client);
-  registerTool(server, getProjectTool, deps.client);
-  registerTool(server, getSpecFileTool, deps.client);
-  registerTool(server, readSpecFileTool, deps.client);
-  registerTool(server, downloadSpecFileTool, deps.client);
-  registerTool(server, listSpecFileTool, deps.client);
-  registerTool(server, getAttachmentTool, deps.client);
-  registerTool(server, uploadAttachmentTool, deps.client);
-  registerTool(server, createProjectTool, deps.client);
-  registerTool(server, updateProjectTool, deps.client);
-  registerTool(server, archiveProjectTool, deps.client);
-  registerTool(server, unarchiveProjectTool, deps.client);
-  registerTool(server, deleteProjectTool, deps.client);
-  registerTool(server, uploadSpecFileTool, deps.client);
-  registerTool(server, updateSpecFileTool, deps.client);
-  registerTool(server, moveSpecFileToTrashTool, deps.client);
-  registerTool(server, restoreSpecFileFromTrashTool, deps.client);
-  registerTool(server, listAttachmentsTool, deps.client);
-  registerTool(server, readAttachmentTool, deps.client);
-  registerTool(server, listSpecSessionsTool, deps.client);
-  registerTool(server, getSpecSessionTool, deps.client);
-  registerTool(server, renameSpecSessionTool, deps.client);
-  registerTool(server, archiveSpecSessionTool, deps.client);
-  registerTool(server, unarchiveSpecSessionTool, deps.client);
-  registerTool(server, deleteSpecSessionTool, deps.client);
-  registerTool(server, listArtifactsTool, deps.client);
-  registerTool(server, getArtifactTool, deps.client);
-  registerTool(server, readArtifactFileTool, deps.client);
-  registerTool(server, createArtifactTool, deps.client);
-  registerTool(server, writeArtifactRevisionTool, deps.client);
-  registerTool(server, rollbackArtifactTool, deps.client);
-  registerTool(server, createStreamTokenTool, deps.client);
-  registerTool(server, listStreamTokensTool, deps.client);
-  registerTool(server, revokeStreamTokenTool, deps.client);
+  const ctx = {
+    client: deps.client,
+    webappUrl: deps.webappUrl,
+    probeReverseMcpPresence: deps.probeReverseMcpPresence
+  };
+  registerTool(server, listProjectsTool, ctx);
+  registerTool(server, getProjectTool, ctx);
+  registerTool(server, getSpecFileTool, ctx);
+  registerTool(server, readSpecFileTool, ctx);
+  registerTool(server, downloadSpecFileTool, ctx);
+  registerTool(server, listSpecFileTool, ctx);
+  registerTool(server, getAttachmentTool, ctx);
+  registerTool(server, uploadAttachmentTool, ctx);
+  registerTool(server, createProjectTool, ctx);
+  registerTool(server, updateProjectTool, ctx);
+  registerTool(server, archiveProjectTool, ctx);
+  registerTool(server, unarchiveProjectTool, ctx);
+  registerTool(server, deleteProjectTool, ctx);
+  registerTool(server, uploadSpecFileTool, ctx);
+  registerTool(server, updateSpecFileTool, ctx);
+  registerTool(server, moveSpecFileToTrashTool, ctx);
+  registerTool(server, restoreSpecFileFromTrashTool, ctx);
+  registerTool(server, listAttachmentsTool, ctx);
+  registerTool(server, readAttachmentTool, ctx);
+  registerTool(server, listSpecSessionsTool, ctx);
+  registerTool(server, getSpecSessionTool, ctx);
+  registerTool(server, renameSpecSessionTool, ctx);
+  registerTool(server, archiveSpecSessionTool, ctx);
+  registerTool(server, unarchiveSpecSessionTool, ctx);
+  registerTool(server, deleteSpecSessionTool, ctx);
+  registerTool(server, listArtifactsTool, ctx);
+  registerTool(server, getArtifactTool, ctx);
+  registerTool(server, readArtifactFileTool, ctx);
+  registerTool(server, createArtifactTool, ctx);
+  registerTool(server, writeArtifactRevisionTool, ctx);
+  registerTool(server, rollbackArtifactTool, ctx);
+  registerTool(server, createStreamTokenTool, ctx);
+  registerTool(server, listStreamTokensTool, ctx);
+  registerTool(server, revokeStreamTokenTool, ctx);
+  registerTool(server, startSpecSessionTool, ctx);
   return server;
 }
 async function startStdioServer(deps) {
@@ -5587,10 +6220,10 @@ async function startStdioServer(deps) {
   const transport = new StdioServerTransport();
   await server.connect(transport);
 }
-function wrapToolHandler(tool, client) {
+function wrapToolHandler(tool, ctx) {
   return async (args) => {
     try {
-      return await tool.handler(args, { client });
+      return await tool.handler(args, ctx);
     } catch (err) {
       if (err instanceof NeedsLoginError) {
         return errorResult(err.message);
@@ -5600,14 +6233,14 @@ function wrapToolHandler(tool, client) {
     }
   };
 }
-function registerTool(server, tool, client) {
+function registerTool(server, tool, ctx) {
   server.registerTool(
     tool.name,
     {
       description: tool.description,
       inputSchema: tool.inputSchema
     },
-    wrapToolHandler(tool, client)
+    wrapToolHandler(tool, ctx)
   );
 }
 
@@ -5733,7 +6366,7 @@ async function canonicaliseRoot(root) {
 import { promises as fs4 } from "fs";
 import { join as join2, relative } from "path";
 import { spawn } from "child_process";
-import { z as z37 } from "zod";
+import { z as z38 } from "zod";
 import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
 
 // src/reverse/ignore.ts
@@ -6038,37 +6671,37 @@ var READ_FILE_MAX_LINES = 2e3;
 var LIST_DIR_HARD_CAP = 5e3;
 var LIST_DIR_DEFAULT_CAP = 1e3;
 var GREP_MAX_MATCHES_DEFAULT = 200;
-var listDirInput = z37.object({
-  path: z37.string(),
-  recursive: z37.boolean().optional(),
-  maxEntries: z37.number().int().positive().optional(),
-  includeIgnored: z37.boolean().optional()
+var listDirInput = z38.object({
+  path: z38.string(),
+  recursive: z38.boolean().optional(),
+  maxEntries: z38.number().int().positive().optional(),
+  includeIgnored: z38.boolean().optional()
 });
-var readFileInput = z37.object({
-  path: z37.string(),
-  offset: z37.number().int().nonnegative().optional(),
-  limit: z37.number().int().positive().optional(),
-  includeIgnored: z37.boolean().optional()
+var readFileInput = z38.object({
+  path: z38.string(),
+  offset: z38.number().int().nonnegative().optional(),
+  limit: z38.number().int().positive().optional(),
+  includeIgnored: z38.boolean().optional()
 });
-var grepInput = z37.object({
-  pattern: z37.string().describe(
+var grepInput = z38.object({
+  pattern: z38.string().describe(
     "Search pattern. Interpreted as a regular expression by default (ripgrep syntax), e.g. `foo|bar` or `[Rr]ole`. Set `isRegex: false` to match the pattern as an exact literal string instead."
   ),
-  path: z37.string().optional().describe("File or directory under --root to search. Defaults to the whole root."),
-  isRegex: z37.boolean().optional().describe("Treat `pattern` as a regex (default true). Set false for literal-string search."),
-  caseSensitive: z37.boolean().optional(),
-  maxMatches: z37.number().int().positive().optional(),
-  contextLines: z37.number().int().nonnegative().optional(),
-  includeIgnored: z37.boolean().optional()
+  path: z38.string().optional().describe("File or directory under --root to search. Defaults to the whole root."),
+  isRegex: z38.boolean().optional().describe("Treat `pattern` as a regex (default true). Set false for literal-string search."),
+  caseSensitive: z38.boolean().optional(),
+  maxMatches: z38.number().int().positive().optional(),
+  contextLines: z38.number().int().nonnegative().optional(),
+  includeIgnored: z38.boolean().optional()
 });
-var packCodebaseInput = z37.object({
-  subpath: z37.string().optional(),
-  includePatterns: z37.string().optional(),
-  ignorePatterns: z37.string().optional()
+var packCodebaseInput = z38.object({
+  subpath: z38.string().optional(),
+  includePatterns: z38.string().optional(),
+  ignorePatterns: z38.string().optional()
 });
-var packCodebaseReadPageInput = z37.object({
-  outputId: z37.string(),
-  page: z37.number().int().positive()
+var packCodebaseReadPageInput = z38.object({
+  outputId: z38.string(),
+  page: z38.number().int().positive()
 });
 function structuredError(error, message, extra) {
   const payload = { error, message, ...extra ?? {} };
@@ -6596,7 +7229,7 @@ function jsonSchemaFromZod(schema) {
   return zodToJson(schema);
 }
 function zodToJson(schema) {
-  if (schema instanceof z37.ZodObject) {
+  if (schema instanceof z38.ZodObject) {
     const shape = schema.shape;
     const properties = {};
     const required = [];
@@ -6611,19 +7244,19 @@ function zodToJson(schema) {
     if (required.length > 0) out.required = required;
     return out;
   }
-  if (schema instanceof z37.ZodOptional) {
+  if (schema instanceof z38.ZodOptional) {
     return zodToJson(schema.unwrap());
   }
-  if (schema instanceof z37.ZodString) {
+  if (schema instanceof z38.ZodString) {
     return { type: "string" };
   }
-  if (schema instanceof z37.ZodNumber) {
+  if (schema instanceof z38.ZodNumber) {
     return { type: "number" };
   }
-  if (schema instanceof z37.ZodBoolean) {
+  if (schema instanceof z38.ZodBoolean) {
     return { type: "boolean" };
   }
-  if (schema instanceof z37.ZodEnum) {
+  if (schema instanceof z38.ZodEnum) {
     return { type: "string", enum: schema.options };
   }
   return { type: "string" };
@@ -6871,6 +7504,58 @@ function sleep2(ms) {
   return new Promise((resolve3) => setTimeout(resolve3, ms));
 }
 
+// src/reverse/presence-probe.ts
+var REVERSE_MCP_STATUS_PATH = "/api/me/reverse-mcp/status";
+var PRESENCE_PROBE_TIMEOUT_MS = 3e3;
+function reverseMcpStatusUrl(reverseUrl) {
+  let parsed;
+  try {
+    parsed = new URL(reverseUrl);
+  } catch {
+    return void 0;
+  }
+  if (parsed.protocol === "wss:") {
+    parsed.protocol = "https:";
+  } else if (parsed.protocol === "ws:") {
+    parsed.protocol = "http:";
+  } else {
+    return void 0;
+  }
+  return `${parsed.origin}${REVERSE_MCP_STATUS_PATH}`;
+}
+function createReverseMcpPresenceProbe(deps) {
+  const fetchImpl = deps.fetchImpl ?? fetch;
+  return async () => {
+    try {
+      const reverseUrl = await deps.loadReverseUrl();
+      if (reverseUrl === void 0 || reverseUrl === "") {
+        return null;
+      }
+      const endpoint = reverseMcpStatusUrl(reverseUrl);
+      if (endpoint === void 0) {
+        return null;
+      }
+      const token = await deps.getAccessToken();
+      const response = await fetchImpl(endpoint, {
+        method: "GET",
+        headers: { Authorization: `Bearer ${token}` },
+        signal: AbortSignal.timeout(PRESENCE_PROBE_TIMEOUT_MS)
+      });
+      if (!response.ok) {
+        return null;
+      }
+      const body = await response.json();
+      if (typeof body !== "object" || body === null) {
+        return null;
+      }
+      const connected = body.connected;
+      return typeof connected === "boolean" ? connected : null;
+    } catch {
+      return null;
+    }
+  };
+}
+
 // src/index.ts
 function parseArgs(argv) {
   const [first, ...rest] = argv;
@@ -7249,7 +7934,23 @@ async function runServe(flags) {
     }),
     tokenManager
   });
-  await startStdioServer({ client, version: readVersion() });
+  await startStdioServer({
+    client,
+    version: readVersion(),
+    // Already resolved above — `start_spec_session` needs it, and CR-002 AC3
+    // forbids a new CLI option or environment variable for it.
+    webappUrl: config.webappUrl,
+    // Reads the agent URL a previous discovery saved, so a brownfield session
+    // started with no bridge running gets a warning (AR-015). Fails open: no
+    // saved URL, or an unreachable ai-agent, simply means no warning.
+    probeReverseMcpPresence: createReverseMcpPresenceProbe({
+      loadReverseUrl: async () => {
+        const saved = await store.load().catch(() => null);
+        return saved?.aiAgentMcpReverseUrl;
+      },
+      getAccessToken: () => tokenManager.getValidAccessToken()
+    })
+  });
 }
 function isCliEntry() {
   const entry = process.argv[1];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@myspec/mcp-server",
-  "version": "0.5.0-next.113",
+  "version": "0.5.0-next.115",
   "description": "MySpec MCP server — exposes MySpec platform projects, files and attachments to MCP-aware clients via OAuth-authenticated access tokens.",
   "type": "module",
   "repository": {