incremnt 0.7.2 → 0.8.0

package/src/remote.js

@@ -1,6 +1,10 @@
 import fs from 'node:fs/promises';
+import { randomUUID } from 'node:crypto';
+import { askMissingObservationFollowUpContext, askObservationFollowUpContext, askRoutedContext } from './ask-coach.js';
+import { contractVersion, writeCommandSchema } from './contract.js';
 import { readSnapshot } from './local.js';
-import { executeCoachReadTool as executeLocalCoachReadTool, executeReadCommand } from './queries.js';
+import { sanitizeHistory } from './prompt-security.js';
+import { executeCoachReadTool as executeLocalCoachReadTool, executeReadCommand, shouldKeepCurrentCoachObservation } from './queries.js';
 import { resolveServiceUrl } from './service-url.js';
 
 function notImplementedError() {
@@ -21,6 +25,111 @@ function authenticationFailedError() {
   return error;
 }
 
+function insufficientScopeError(message = 'This agent token is read-only. Create or use a write-capable agent token for this command.') {
+  const error = new Error(message);
+  error.code = 'INSUFFICIENT_SCOPE';
+  // Structured remedy so an agent can act instead of retry-looping. Minting a
+  // write token requires a human login, so this is an escalation, not something
+  // the agent can self-correct.
+  error.requiredAccess = 'write';
+  error.requiresHuman = true;
+  error.remedy = 'A write-capable agent token is required. Minting one needs a human login: run `incremnt login`, then `incremnt agents create --access write`.';
+  return error;
+}
+
+function remoteContractMismatchError(remoteVersion) {
+  const parsedRemoteVersion = Number(remoteVersion);
+  const remoteLabel = remoteVersion == null ? 'missing' : `v${remoteVersion}`;
+  const action = Number.isFinite(parsedRemoteVersion) && parsedRemoteVersion > contractVersion
+    ? 'Update the incremnt CLI, then run incremnt login again.'
+    : 'Run incremnt login again after the service updates.';
+  const error = new Error(`Remote incremnt sync service is incompatible with this CLI. Expected contract v${contractVersion}, got ${remoteLabel}. ${action}`);
+  error.code = 'REMOTE_CONTRACT_MISMATCH';
+  return error;
+}
+
+function remoteTimeoutError(timeoutMs = REMOTE_ASK_PLAN_TIMEOUT_MS) {
+  const error = new Error(`Remote Ask planning timed out after ${Math.round(timeoutMs / 1000)} seconds.`);
+  error.code = 'REMOTE_TIMEOUT';
+  return error;
+}
+
+function assertValidAskPlanQuestion(question) {
+  if (!question || typeof question !== 'string' || question.trim().length === 0) {
+    const error = new Error('question is required');
+    error.code = 'VALIDATION_ERROR';
+    throw error;
+  }
+  if (question.length > 500) {
+    const error = new Error('question must be 500 characters or fewer');
+    error.code = 'VALIDATION_ERROR';
+    throw error;
+  }
+}
+
+const requiredAccessByWriteCommandId = new Map(
+  writeCommandSchema.map((command) => [command.id, command.requiredAccess ?? 'write'])
+);
+
+function requiredAccessForCommand(commandId) {
+  return requiredAccessByWriteCommandId.get(commandId) ?? 'read';
+}
+
+// Fail-closed gate for the write dispatch path: anything routed as a write
+// command must be write-scoped UNLESS the contract explicitly marks it
+// 'read'-access. An unknown id (e.g. a future write handler missing its schema
+// entry) defaults to requiring write, so a read-only token can never slip
+// through the client gate.
+function writeCommandRequiresWriteScope(commandId) {
+  return (requiredAccessByWriteCommandId.get(commandId) ?? 'write') === 'write';
+}
+
+async function ensureCompatibleRemoteContract(sessionState, transportOptions = {}) {
+  const baseUrl = sessionState.session?.transport?.baseUrl;
+  let remoteVersion = sessionState.session?.transport?.contractVersion;
+  if (sessionState.session?.transport?.uncheckedContract && transportOptions.resolveContract) {
+    const remoteContract = await transportOptions.resolveContract();
+    sessionState.session.transport = {
+      ...(sessionState.session.transport ?? {}),
+      contractVersion: remoteContract.contractVersion,
+      capabilities: remoteContract.capabilities ?? null,
+      uncheckedContract: false
+    };
+    remoteVersion = remoteContract.contractVersion;
+  }
+  if (!baseUrl) return;
+  if (remoteVersion == null) {
+    throw remoteContractMismatchError(remoteVersion);
+  }
+  if (Number(remoteVersion) !== contractVersion) {
+    throw remoteContractMismatchError(remoteVersion);
+  }
+}
+
+async function throwForbiddenResponse(response, sessionState, commandId) {
+  const payload = await response.json().catch(() => null);
+  const requiredAccess = requiredAccessForCommand(commandId);
+  const auth = sessionState.session?.auth;
+  const isAgentToken = auth?.type === 'agent-token';
+  // A token we know to be write-capable hit a genuine authorization failure, not
+  // a scope problem — never mask it as INSUFFICIENT_SCOPE.
+  const knownWriteCapable = isAgentToken && auth?.access === 'write';
+  // Trust the server's explicit code. Only synthesise a scope error when the
+  // server returned no code at all (older/edge paths) for an agent token of
+  // unknown-or-read scope hitting a write command — there a 403 can only be a
+  // scope problem (the service runs its scope check before any ownership check).
+  if (
+    payload?.code === 'INSUFFICIENT_SCOPE'
+    || (!payload?.code && isAgentToken && !knownWriteCapable && requiredAccess === 'write')
+  ) {
+    throw insufficientScopeError(payload?.error);
+  }
+
+  const error = new Error(payload?.error ?? `Remote request forbidden (HTTP ${response.status}).`);
+  error.code = payload?.code ?? 'REMOTE_FORBIDDEN';
+  throw error;
+}
+
 const remoteCommandHandlers = {
   'session-insights': executeRemoteRead,
   'session-show': executeRemoteRead,
@@ -29,8 +138,11 @@ const remoteCommandHandlers = {
   'program-list': executeRemoteRead,
   'program-summary': executeRemoteRead,
   'program-detail': executeRemoteRead,
+  'program-progress': executeRemoteRead,
+  'exercise-progress-summary': executeRemoteRead,
   'cycle-summary-list': executeRemoteRead,
   'cycle-summary-show': executeRemoteRead,
+  'cycle-progression-summary': executeRemoteRead,
   'planned-vs-actual': executeRemoteRead,
   'why-did-this-change': executeRemoteRead,
   'goals-list': executeRemoteRead,
@@ -38,6 +150,7 @@ const remoteCommandHandlers = {
   'health-summary': executeRemoteRead,
   'health-ai': executeRemoteRead,
   'training-load': executeRemoteRead,
+  'training-profile': executeRemoteRead,
   'ask-history': executeRemoteRead,
   'ask-show': executeRemoteRead,
   'program-share-fetch': executeRemoteRead,
@@ -46,6 +159,21 @@ const remoteCommandHandlers = {
   'coach-observations-current': executeRemoteRead
 };
 
+const REMOTE_ASK_PLAN_TIMEOUT_MS = 30_000;
+
+async function fetchWithTimeout(url, init = {}, timeoutMs = REMOTE_ASK_PLAN_TIMEOUT_MS) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    return await fetch(url, {
+      ...init,
+      signal: controller.signal
+    });
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
 async function executeRemoteRead(options, sessionState, normalizedCommand) {
   const baseUrl = sessionState.session?.transport?.baseUrl;
   if (baseUrl) {
@@ -81,7 +209,7 @@ async function executeRemoteHttpRead(baseUrl, sessionState, normalizedCommand, o
   }
 
   if (response.status === 403) {
-    throw authenticationFailedError();
+    await throwForbiddenResponse(response, sessionState, normalizedCommand);
   }
 
   if (response.status === 404) {
@@ -122,6 +250,13 @@ function endpointForCommand(baseUrl, normalizedCommand, options) {
       return resolveServiceUrl(baseUrl, '/cli/programs/current');
     case 'program-detail':
       return resolveServiceUrl(baseUrl, options.id ? `/cli/programs/${encodeURIComponent(options.id)}` : '/cli/programs/active');
+    case 'program-progress': {
+      const url = resolveServiceUrl(baseUrl, '/cli/programs/progress');
+      if (options['program-id']) url.searchParams.set('program-id', options['program-id']);
+      if (options.since) url.searchParams.set('since', options.since);
+      if (options.limitExercises) url.searchParams.set('limitExercises', options.limitExercises);
+      return url;
+    }
     case 'cycle-summary-list': {
       const cyclesUrl = resolveServiceUrl(baseUrl, '/cli/cycles');
       if (options['program-id']) {
@@ -131,11 +266,25 @@ function endpointForCommand(baseUrl, normalizedCommand, options) {
     }
     case 'cycle-summary-show':
       return resolveServiceUrl(baseUrl, `/cli/cycles/${encodeURIComponent(options.id)}`);
+    case 'cycle-progression-summary': {
+      const url = resolveServiceUrl(baseUrl, '/cli/cycles/progress');
+      if (options['program-id']) url.searchParams.set('program-id', options['program-id']);
+      if (options.limit) url.searchParams.set('limit', options.limit);
+      return url;
+    }
     case 'exercise-history': {
       const historyUrl = resolveServiceUrl(baseUrl, '/cli/exercises/history');
       historyUrl.searchParams.set('name', options.name ?? options.exercise);
       return historyUrl;
     }
+    case 'exercise-progress-summary': {
+      const url = resolveServiceUrl(baseUrl, '/cli/exercises/progress');
+      if (options.name ?? options.exercise) url.searchParams.set('name', options.name ?? options.exercise);
+      if (options.since) url.searchParams.set('since', options.since);
+      if (options['program-id']) url.searchParams.set('program-id', options['program-id']);
+      if (options.limit) url.searchParams.set('limit', options.limit);
+      return url;
+    }
     case 'records':
       return resolveServiceUrl(baseUrl, '/cli/records');
     case 'goals-list':
@@ -153,6 +302,11 @@ function endpointForCommand(baseUrl, normalizedCommand, options) {
       return resolveServiceUrl(baseUrl, '/cli/health/ai');
     case 'training-load':
       return resolveServiceUrl(baseUrl, '/cli/training-load');
+    case 'training-profile': {
+      const url = resolveServiceUrl(baseUrl, '/cli/training-profile');
+      if (options.since) url.searchParams.set('since', options.since);
+      return url;
+    }
     case 'ask-history': {
       const askUrl = resolveServiceUrl(baseUrl, '/cli/ask/history');
       if (options.limit) {
@@ -223,7 +377,8 @@ async function executeRemoteCoachReadTool(toolName, input, sessionState) {
       body: JSON.stringify(input ?? {})
     });
 
-    if (response.status === 401 || response.status === 403) throw authenticationFailedError();
+    if (response.status === 401) throw authenticationFailedError();
+    if (response.status === 403) await throwForbiddenResponse(response, sessionState, 'coach-read-tool');
     if (response.status === 404) {
       const error = new Error(`Unknown coach read tool: ${toolName}`);
       error.code = 'REMOTE_NOT_FOUND';
@@ -244,6 +399,72 @@ async function executeRemoteCoachReadTool(toolName, input, sessionState) {
   return executeLocalCoachReadTool(snapshot, toolName, input);
 }
 
+async function executeRemoteAskPlan(input, sessionState) {
+  const baseUrl = sessionState.session?.transport?.baseUrl;
+  if (baseUrl) {
+    const endpoint = resolveServiceUrl(baseUrl, '/cli/ask/plan');
+    let response;
+    try {
+      response = await fetchWithTimeout(endpoint, {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          Authorization: `Bearer ${sessionState.session?.auth?.accessToken ?? ''}`
+        },
+        body: JSON.stringify(input ?? {})
+      });
+    } catch (error) {
+      if (error?.name === 'AbortError') throw remoteTimeoutError();
+      throw error;
+    }
+
+    if (response.status === 401) throw authenticationFailedError();
+    if (response.status === 403) await throwForbiddenResponse(response, sessionState, 'plan-ask-interaction');
+    if (!response.ok) {
+      const payload = await response.json().catch(() => null);
+      const error = new Error(payload?.error ?? `Unexpected error from incremnt sync service (HTTP ${response.status}).`);
+      error.code = 'REMOTE_HTTP_ERROR';
+      throw error;
+    }
+    return response.json();
+  }
+
+  const fixturePath = sessionState.session?.transport?.fixturePath;
+  if (!fixturePath) throw notImplementedError();
+  assertValidAskPlanQuestion(input?.question);
+  const snapshot = await readSnapshot(fixturePath);
+  const exclude = new Set(String(input?.exclude ?? '').split(',').map((item) => item.trim()).filter(Boolean));
+  if (input?.coachObservation) {
+    const observationId = String(input.coachObservation.id ?? '').trim();
+    const snapshotObservation = (snapshot.coachObservations ?? [])
+      .find((observation) => (
+        String(observation?.id ?? '') === observationId &&
+        shouldKeepCurrentCoachObservation(observation, { includeOutcomeHistory: true })
+      ));
+    const routedContext = snapshotObservation
+      ? askObservationFollowUpContext(snapshot, input?.question, snapshotObservation, {
+          exclude,
+          intent: input.coachObservation.intent
+        })
+      : askMissingObservationFollowUpContext(snapshot, input?.question, input.coachObservation, {
+          exclude,
+          intent: input.coachObservation.intent
+        });
+    return {
+      contextBundle: routedContext.contextBundle,
+      metadata: routedContext.metadata
+    };
+  }
+  const routedContext = askRoutedContext(snapshot, input?.question, {
+    exclude,
+    history: sanitizeHistory(input?.history)
+  });
+  return {
+    contextBundle: routedContext.contextBundle,
+    metadata: routedContext.metadata
+  };
+}
+
 // Build the shape of a write request without executing it.
 // Returns { method, url, body }. body is a parsed JS object or null.
 // Used by the --dry-run path. Keep endpoint and body changes in sync with the
@@ -353,6 +574,48 @@ export async function buildWriteRequest(commandId, options, sessionState) {
         body: {}
       };
     }
+    case 'coach-observations-outcome': {
+      if (!options.id) {
+        const error = new Error('--id is required for coach observations outcome.');
+        error.code = 'MISSING_OPTION';
+        throw error;
+      }
+      if (!options.status) {
+        const error = new Error('--status is required for coach observations outcome.');
+        error.code = 'MISSING_OPTION';
+        throw error;
+      }
+      const body = { outcomeStatus: options.status };
+      if (options.observedAt) body.outcomeObservedAt = options.observedAt;
+      if (options.notes) body.outcomeNotes = options.notes;
+      if (options.linkedFollowupObservationId) {
+        body.linkedFollowupObservationId = options.linkedFollowupObservationId;
+      }
+      return {
+        method: 'POST',
+        url: resolveServiceUrl(baseUrl, `/cli/coach-observations/${encodeURIComponent(options.id)}/outcome`).toString(),
+        body
+      };
+    }
+    case 'coach-observations-feedback': {
+      if (!options.id) {
+        const error = new Error('--id is required for coach observations feedback.');
+        error.code = 'MISSING_OPTION';
+        throw error;
+      }
+      if (!options.status) {
+        const error = new Error('--status is required for coach observations feedback.');
+        error.code = 'MISSING_OPTION';
+        throw error;
+      }
+      const body = { feedbackStatus: options.status };
+      if (options.feedbackAt) body.feedbackAt = options.feedbackAt;
+      return {
+        method: 'POST',
+        url: resolveServiceUrl(baseUrl, `/cli/coach-observations/${encodeURIComponent(options.id)}/feedback`).toString(),
+        body
+      };
+    }
     default: {
       const error = new Error(`Command ${commandId} does not support --dry-run.`);
       error.code = 'UNSUPPORTED_DRY_RUN';
@@ -386,7 +649,8 @@ const remoteWriteCommandHandlers = {
       body: JSON.stringify(proposal)
     });
 
-    if (response.status === 401 || response.status === 403) throw authenticationFailedError();
+    if (response.status === 401) throw authenticationFailedError();
+    if (response.status === 403) await throwForbiddenResponse(response, sessionState, 'programs-propose');
     if (!response.ok) {
       const payload = await response.json().catch(() => null);
       const error = new Error(payload?.error ?? `Unexpected error (HTTP ${response.status}).`);
@@ -412,7 +676,8 @@ const remoteWriteCommandHandlers = {
       }
     });
 
-    if (response.status === 401 || response.status === 403) throw authenticationFailedError();
+    if (response.status === 401) throw authenticationFailedError();
+    if (response.status === 403) await throwForbiddenResponse(response, sessionState, 'programs-proposals');
     if (!response.ok) {
       const payload = await response.json().catch(() => null);
       const error = new Error(payload?.error ?? `Unexpected error (HTTP ${response.status}).`);
@@ -443,7 +708,8 @@ const remoteWriteCommandHandlers = {
       body: JSON.stringify({ status: 'dismissed' })
     });
 
-    if (response.status === 401 || response.status === 403) throw authenticationFailedError();
+    if (response.status === 401) throw authenticationFailedError();
+    if (response.status === 403) await throwForbiddenResponse(response, sessionState, 'proposal-dismiss');
     if (response.status === 404) {
       const error = new Error(`Proposal not found: ${options.id}`);
       error.code = 'REMOTE_NOT_FOUND';
@@ -476,7 +742,8 @@ const remoteWriteCommandHandlers = {
       }
     });
 
-    if (response.status === 401 || response.status === 403) throw authenticationFailedError();
+    if (response.status === 401) throw authenticationFailedError();
+    if (response.status === 403) await throwForbiddenResponse(response, sessionState, 'program-share-create');
     if (response.status === 404) {
       const error = new Error(`Program not found: ${options['program-id']}`);
       error.code = 'REMOTE_NOT_FOUND';
@@ -507,7 +774,8 @@ const remoteWriteCommandHandlers = {
       }
     });
 
-    if (response.status === 401 || response.status === 403) throw authenticationFailedError();
+    if (response.status === 401) throw authenticationFailedError();
+    if (response.status === 403) await throwForbiddenResponse(response, sessionState, 'program-share-list');
     if (!response.ok) {
       const payload = await response.json().catch(() => null);
       const error = new Error(payload?.error ?? `Unexpected error (HTTP ${response.status}).`);
@@ -544,7 +812,8 @@ const remoteWriteCommandHandlers = {
       body: JSON.stringify(body)
     });
 
-    if (response.status === 401 || response.status === 403) throw authenticationFailedError();
+    if (response.status === 401) throw authenticationFailedError();
+    if (response.status === 403) await throwForbiddenResponse(response, sessionState, 'increment-score-upload');
     if (!response.ok) {
       const payload = await response.json().catch(() => null);
       const error = new Error(payload?.error ?? `Unexpected error (HTTP ${response.status}).`);
@@ -572,7 +841,8 @@ const remoteWriteCommandHandlers = {
       }
     });
 
-    if (response.status === 401 || response.status === 403) throw authenticationFailedError();
+    if (response.status === 401) throw authenticationFailedError();
+    if (response.status === 403) await throwForbiddenResponse(response, sessionState, 'program-share-revoke');
     if (response.status === 404) {
       const error = new Error(`Program share not found: ${options['share-id']}`);
       error.code = 'REMOTE_NOT_FOUND';
@@ -608,7 +878,8 @@ const remoteWriteCommandHandlers = {
       body: JSON.stringify(body)
     });
 
-    if (response.status === 401 || response.status === 403) throw authenticationFailedError();
+    if (response.status === 401) throw authenticationFailedError();
+    if (response.status === 403) await throwForbiddenResponse(response, sessionState, 'coach-observations-seen');
     if (response.status === 404) {
       const error = new Error(`Coach observation not found: ${options.id}`);
       error.code = 'REMOTE_NOT_FOUND';
@@ -642,7 +913,54 @@ const remoteWriteCommandHandlers = {
       body: JSON.stringify({})
     });
 
-    if (response.status === 401 || response.status === 403) throw authenticationFailedError();
+    if (response.status === 401) throw authenticationFailedError();
+    if (response.status === 403) await throwForbiddenResponse(response, sessionState, 'coach-observations-dismiss');
+    if (response.status === 404) {
+      const error = new Error(`Coach observation not found: ${options.id}`);
+      error.code = 'REMOTE_NOT_FOUND';
+      throw error;
+    }
+    if (!response.ok) {
+      const payload = await response.json().catch(() => null);
+      const error = new Error(payload?.error ?? `Unexpected error (HTTP ${response.status}).`);
+      error.code = 'REMOTE_HTTP_ERROR';
+      throw error;
+    }
+    return response.json();
+  },
+
+  'coach-observations-outcome': async (options, sessionState) => {
+    const baseUrl = sessionState.session?.transport?.baseUrl;
+    if (!baseUrl) throw notImplementedError();
+    if (!options.id) {
+      const error = new Error('--id is required for coach observations outcome.');
+      error.code = 'MISSING_OPTION';
+      throw error;
+    }
+    if (!options.status) {
+      const error = new Error('--status is required for coach observations outcome.');
+      error.code = 'MISSING_OPTION';
+      throw error;
+    }
+
+    const body = { outcomeStatus: options.status };
+    if (options.observedAt) body.outcomeObservedAt = options.observedAt;
+    if (options.notes) body.outcomeNotes = options.notes;
+    if (options.linkedFollowupObservationId) {
+      body.linkedFollowupObservationId = options.linkedFollowupObservationId;
+    }
+    const endpoint = resolveServiceUrl(baseUrl, `/cli/coach-observations/${encodeURIComponent(options.id)}/outcome`);
+    const response = await fetch(endpoint, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        Authorization: `Bearer ${sessionState.session?.auth?.accessToken ?? ''}`
+      },
+      body: JSON.stringify(body)
+    });
+
+    if (response.status === 401) throw authenticationFailedError();
+    if (response.status === 403) await throwForbiddenResponse(response, sessionState, 'coach-observations-outcome');
     if (response.status === 404) {
       const error = new Error(`Coach observation not found: ${options.id}`);
       error.code = 'REMOTE_NOT_FOUND';
@@ -655,13 +973,133 @@ const remoteWriteCommandHandlers = {
       throw error;
     }
     return response.json();
+  },
+
+  'coach-observations-feedback': async (options, sessionState) => {
+    const baseUrl = sessionState.session?.transport?.baseUrl;
+    if (!baseUrl) throw notImplementedError();
+    if (!options.id) {
+      const error = new Error('--id is required for coach observations feedback.');
+      error.code = 'MISSING_OPTION';
+      throw error;
+    }
+    if (!options.status) {
+      const error = new Error('--status is required for coach observations feedback.');
+      error.code = 'MISSING_OPTION';
+      throw error;
+    }
+
+    const body = { feedbackStatus: options.status };
+    if (options.feedbackAt) body.feedbackAt = options.feedbackAt;
+    const endpoint = resolveServiceUrl(baseUrl, `/cli/coach-observations/${encodeURIComponent(options.id)}/feedback`);
+    const response = await fetch(endpoint, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        Authorization: `Bearer ${sessionState.session?.auth?.accessToken ?? ''}`
+      },
+      body: JSON.stringify(body)
+    });
+
+    if (response.status === 401) throw authenticationFailedError();
+    if (response.status === 403) await throwForbiddenResponse(response, sessionState, 'coach-observations-feedback');
+    if (response.status === 404) {
+      const error = new Error(`Coach observation not found: ${options.id}`);
+      error.code = 'REMOTE_NOT_FOUND';
+      throw error;
+    }
+    if (!response.ok) {
+      const payload = await response.json().catch(() => null);
+      const error = new Error(payload?.error ?? `Unexpected error (HTTP ${response.status}).`);
+      error.code = 'REMOTE_HTTP_ERROR';
+      throw error;
+    }
+    return response.json();
+  },
+
+  'ask': async (options, sessionState) => {
+    const baseUrl = sessionState.session?.transport?.baseUrl;
+    if (!baseUrl) throw notImplementedError();
+    const question = String(options.question ?? '').trim();
+    if (!question) {
+      const error = new Error('--question is required for ask.');
+      error.code = 'MISSING_OPTION';
+      throw error;
+    }
+    if (question.length > 500) {
+      const error = new Error('--question must be 500 characters or fewer.');
+      error.code = 'INVALID_OPTION';
+      throw error;
+    }
+
+    let history;
+    if (options.history) {
+      try {
+        history = JSON.parse(options.history);
+      } catch {
+        const error = new Error('--history must be valid JSON (array of {role, content}).');
+        error.code = 'INVALID_OPTION';
+        throw error;
+      }
+      if (!Array.isArray(history)) {
+        const error = new Error('--history must be a JSON array.');
+        error.code = 'INVALID_OPTION';
+        throw error;
+      }
+    }
+
+    const providedConversationId = String(
+      options['conversation-id'] ?? options.conversationId ?? ''
+    ).trim();
+    const conversationId = providedConversationId || randomUUID();
+
+    const body = { question, conversationId };
+    if (history) body.history = history;
+    if (options.exclude) body.exclude = options.exclude;
+    if (options.tone) body.tone = options.tone;
+
+    const endpoint = resolveServiceUrl(baseUrl, '/cli/ask');
+    const response = await fetch(endpoint, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        Authorization: `Bearer ${sessionState.session?.auth?.accessToken ?? ''}`
+      },
+      body: JSON.stringify(body)
+    });
+
+    if (response.status === 401) throw authenticationFailedError();
+    if (response.status === 403) await throwForbiddenResponse(response, sessionState, 'ask');
+    if (!response.ok) {
+      const payload = await response.json().catch(() => null);
+      const error = new Error(payload?.error ?? `Unexpected error (HTTP ${response.status}).`);
+      error.code = 'REMOTE_HTTP_ERROR';
+      throw error;
+    }
+    const payload = await response.json();
+    const responseConversationId = typeof payload?.conversationId === 'string'
+      ? payload.conversationId.trim()
+      : '';
+    return {
+      ...payload,
+      conversationId: responseConversationId || conversationId
+    };
   }
 };
 
 export function createRemoteTransport(sessionState, transportOptions = {}) {
+  const auth = sessionState.session?.auth ?? {};
+  const credential = {
+    source: transportOptions.credentialSource ?? auth.source ?? 'session',
+    type: auth.type ?? (auth.accessToken ? 'session' : null),
+    access: auth.access ?? null,
+    expiresAt: auth.expiresAt ?? null,
+    canRefresh: Boolean(auth.accessToken && auth.type !== 'agent-token' && sessionState.session?.transport?.baseUrl)
+  };
   return {
     kind: 'remote',
     account: sessionState.session?.account ?? null,
+    credential,
     bootstrap: Boolean(sessionState.session?.transport?.fixturePath || sessionState.session?.transport?.baseUrl),
     source: sessionState.session?.transport?.baseUrl
       ? 'http'
@@ -672,10 +1110,12 @@ export function createRemoteTransport(sessionState, transportOptions = {}) {
     contractVersion: sessionState.session?.transport?.contractVersion ?? null,
     capabilities: sessionState.session?.transport?.capabilities ?? null,
     fixturePath: sessionState.session?.transport?.fixturePath ?? null,
+    contractUnchecked: Boolean(sessionState.session?.transport?.uncheckedContract),
     async executeReadCommand(normalizedCommand, options = {}) {
       if (transportOptions.expired) {
         throw expiredSessionError();
       }
+      await ensureCompatibleRemoteContract(sessionState, transportOptions);
 
       const handler = remoteCommandHandlers[normalizedCommand];
       if (!handler) {
@@ -690,13 +1130,26 @@ export function createRemoteTransport(sessionState, transportOptions = {}) {
       if (transportOptions.expired) {
         throw expiredSessionError();
       }
+      await ensureCompatibleRemoteContract(sessionState, transportOptions);
 
       return executeRemoteCoachReadTool(toolName, input, sessionState);
     },
+    async planAskInteraction(input = {}) {
+      if (transportOptions.expired) {
+        throw expiredSessionError();
+      }
+      await ensureCompatibleRemoteContract(sessionState, transportOptions);
+
+      return executeRemoteAskPlan(input, sessionState);
+    },
     async executeWriteCommand(normalizedCommand, options = {}) {
       if (transportOptions.expired) {
         throw expiredSessionError();
       }
+      if (credential.type === 'agent-token' && credential.access === 'read' && writeCommandRequiresWriteScope(normalizedCommand)) {
+        throw insufficientScopeError();
+      }
+      await ensureCompatibleRemoteContract(sessionState, transportOptions);
 
       const handler = remoteWriteCommandHandlers[normalizedCommand];
       if (!handler) {