trackly-cli 0.7.2 → 0.8.1

package/mcp/server.js

@@ -4,17 +4,17 @@ const { McpServer } = require('@modelcontextprotocol/sdk/server/mcp.js');
 const { StdioServerTransport } = require('@modelcontextprotocol/sdk/server/stdio.js');
 const { McpError } = require('@modelcontextprotocol/sdk/types.js');
 const { z } = require('zod');
-const { apiRequest, hasAuth, maintenanceOutput } = require('../lib/client');
-const { prepareResume, verifyPreparedResume } = require('../lib/agent');
+const { apiRequest, createTracklyAccessError, hasAuth, maintenanceOutput } = require('../lib/client');
 const { version: PACKAGE_VERSION } = require('../package.json');
-const APPLY_CONTRACT = require('../contracts/trackly-apply-tools.json');
+const { registerApplyTools } = require('./apply-tools');
 
 const MCP_USER_AGENT = `trackly-mcp/${PACKAGE_VERSION}`;
 const MCP_MAINTENANCE_ERROR_CODE = -32002;
-const AUTH_HINT = 'Run `trackly login` or set TRACKLY_API_KEY. Get a key at https://usetrackly.app (sign in → Settings → API Keys).';
-const APPLY_BROWSER_SURFACES = APPLY_CONTRACT.constants.applyBrowserSurfaces;
-const APPLY_SCENARIO_CODES = APPLY_CONTRACT.constants.applyScenarioCodes;
-const SAFE_OBSERVATION_CODE = /^[a-z0-9][a-z0-9_:-]{0,99}$/;
+const MCP_ACCESS_ERROR_CODE = -32003;
+const MCP_AUTH_ERROR_CODE = -32004;
+const AUTH_HINT =
+  'Existing members: run `trackly login` or set TRACKLY_API_KEY. ' +
+  'New members need a private invite during the limited rollout; request access at https://usetrackly.app/early-access.';
 
 // Mirrors `granola-followup-app/src/services/region-classifier.ts:8` REGION_TAGS.
 // Keep in sync when the backend enum changes.
@@ -60,21 +60,44 @@ const ACTION_TO_STAGE = { applied: 'applied', saved: 'backlog', dismissed: 'disc
 
 function createErrorResult(error, fallbackMessage, extra = {}) {
   const normalizedMaintenance = maintenanceOutput(error);
+  const normalizedAccess = createTracklyAccessError(error, error?.status);
   const payload = normalizedMaintenance
     ? {
         ...normalizedMaintenance,
         error: error?.error || error?.message || fallbackMessage,
         ...extra,
       }
-    : {
-        error: error?.error || error?.message || fallbackMessage,
-        ...extra,
-      };
+    : normalizedAccess
+      ? {
+          error: normalizedAccess.error,
+          message: normalizedAccess.message,
+          status: normalizedAccess.status,
+          code: normalizedAccess.code,
+          retryable: normalizedAccess.retryable,
+          ...extra,
+        }
+      : {
+          error: error?.error || error?.message || fallbackMessage,
+          ...extra,
+        };
 
   if (error?.status) {
     payload.status = error.status;
   }
 
+  if (
+    error?.code === 'experience_filter_v2_unavailable'
+    || error?.code === 'invalid_preference_revision'
+  ) {
+    payload.code = error.code;
+  }
+
+  if (error?.status === 409 && error?.error === 'preference_revision_conflict') {
+    payload.preferences = error.preferences;
+    payload.discoveryPreferenceRevision = error.discoveryPreferenceRevision;
+    payload.hint = 'Preferences changed elsewhere. Refetch with trackly_get_preferences, reconcile with the user, and never retry blindly with the newer revision.';
+  }
+
   if (error?.status === 429 && !payload.hint) {
     payload.hint = 'Daily limit reached (20 natural language queries per day).';
   }
@@ -102,6 +125,25 @@ function throwMcpResourceError(error) {
       normalizedMaintenance,
     );
   }
+  const normalizedAccess = createTracklyAccessError(error, error?.status);
+  if (normalizedAccess) {
+    throw new McpError(
+      MCP_ACCESS_ERROR_CODE,
+      normalizedAccess.message,
+      {
+        status: normalizedAccess.status,
+        code: normalizedAccess.code,
+        retryable: normalizedAccess.retryable,
+      },
+    );
+  }
+  if (error?.status === 401) {
+    throw new McpError(
+      MCP_AUTH_ERROR_CODE,
+      error?.message || 'Not authenticated',
+      { status: 401, hint: AUTH_HINT },
+    );
+  }
   throw error;
 }
 
@@ -126,6 +168,17 @@ function wrapTool(handler, fallbackMessage) {
   };
 }
 
+function projectPreferenceResponse(result, experienceFilterV2Available = null) {
+  const user = result?.user || {};
+  return {
+    success: result?.success === true,
+    experienceFilterV2Available: experienceFilterV2Available === null
+      ? user.experienceFilterV2Available === true
+      : experienceFilterV2Available === true,
+    preferences: user.preferences || result?.preferences || {},
+  };
+}
+
 function createServer() {
   const server = new McpServer({
     name: 'trackly',
@@ -239,6 +292,62 @@ function createServer() {
     }, 'Failed to fetch stats')
   );
 
+  server.tool(
+    'trackly_get_preferences',
+    'Read the authenticated user\'s discovery preferences, including selected and effective job functions, role-specific experience limits and active state, and the discoveryPreferenceRevision required for a safe update.',
+    {},
+    wrapTool(async () => {
+      const result = await apiRequest('GET', '/api/jobscout/me', null, false, false, MCP_USER_AGENT);
+      return projectPreferenceResponse(result);
+    }, 'Failed to fetch preferences')
+  );
+
+  server.tool(
+    'trackly_update_experience_limits',
+    'Atomically replace the complete role-specific experience-limit map. Each value is the highest stated minimum years requirement the user wants for that job function. When Trackly enforcement is active, a job is included when its stated minimum is less than or equal to the limit. Jobs with no stated minimum remain visible. An empty object clears the saved limits. experienceFilterV2Available reports edit capability, not enforcement state. Read discoveryPreferenceRevision with trackly_get_preferences first. If the backend returns a revision conflict, refetch and reconcile with the user; never retry blindly with the newer revision.',
+    {
+      experienceLimitsByJobFunction: z.record(z.enum(JOB_FUNCTIONS), z.number().int().min(0).max(60)).describe(
+        'Complete replacement map from canonical job-function slug to maximum acceptable stated minimum years. Use {} to turn role-specific experience filtering off.'
+      ),
+      expectedPreferenceRevision: z.number().int().min(0).max(Number.MAX_SAFE_INTEGER).describe(
+        'The non-negative safe-integer discoveryPreferenceRevision returned by the latest trackly_get_preferences call. A stale revision is rejected instead of overwriting newer choices.'
+      ),
+    },
+    wrapTool(async ({ experienceLimitsByJobFunction, expectedPreferenceRevision }) => {
+      const current = await apiRequest('GET', '/api/jobscout/me', null, false, false, MCP_USER_AGENT);
+      if (current?.user?.experienceFilterV2Available !== true) {
+        throw {
+          status: 403,
+          code: 'experience_filter_v2_unavailable',
+          error: 'Role-specific experience preferences are not available for this account yet. No changes were saved.',
+        };
+      }
+      const currentPreferences = current?.user?.preferences || {};
+      const currentRevision = currentPreferences.discoveryPreferenceRevision;
+      if (!Number.isSafeInteger(currentRevision) || currentRevision < 0) {
+        throw {
+          status: 502,
+          code: 'invalid_preference_revision',
+          error: 'Trackly did not return a valid preference revision. No changes were saved.',
+        };
+      }
+      if (currentRevision !== expectedPreferenceRevision) {
+        throw {
+          status: 409,
+          error: 'preference_revision_conflict',
+          preferences: currentPreferences,
+          discoveryPreferenceRevision: currentRevision,
+        };
+      }
+      const result = await apiRequest('PUT', '/api/jobscout/preferences', {
+        experienceLimitsByJobFunction,
+        experienceFilterVersion: 2,
+        expectedPreferenceRevision,
+      }, false, false, MCP_USER_AGENT);
+      return projectPreferenceResponse(result, true);
+    }, 'Failed to update experience limits')
+  );
+
   server.tool(
     'trackly_update_status',
     'Update a job application status (apply, save, or dismiss).',
@@ -350,206 +459,11 @@ function createServer() {
     }, 'Failed to request company')
   );
 
-  // Trackly Apply tools. Keep schemas aligned with the hosted MCP server.
-  server.tool(
-    'trackly_get_apply_queue',
-    'Get the deterministic queue of jobs the user already approved by saving as check later. Do not rescore or veto these jobs.',
-    { limit: z.number().int().min(1).max(100).optional() },
-    wrapTool(async ({ limit }) => {
-      const qs = limit ? `?limit=${limit}` : '';
-      return apiRequest('GET', `/api/jobscout/apply/queue${qs}`, null, false, false, MCP_USER_AGENT);
-    }, 'Failed to fetch apply queue')
-  );
-
-  server.tool(
-    'trackly_get_application_profile',
-    'Get the versioned application profile. Sensitive values are returned only after the user opted into encrypted storage.',
-    {
-      includeSensitive: z.boolean().optional(),
-      provider: z.string().max(100).optional(),
-      companyId: z.string().max(100).optional(),
-    },
-    wrapTool(async ({ includeSensitive, provider, companyId }) => {
-      const qs = new URLSearchParams();
-      if (includeSensitive) qs.set('includeSensitive', 'true');
-      if (provider) qs.set('provider', provider);
-      if (companyId) qs.set('companyId', companyId);
-      return apiRequest('GET', `/api/jobscout/application-profile?${qs.toString()}`, null, false, false, MCP_USER_AGENT);
-    }, 'Failed to fetch application profile')
-  );
-
-  server.tool(
-    'trackly_get_profile_onboarding',
-    'Get the backend-owned profile schema and onboarding questions. Ask only fields whose state is unknown or needs confirmation.',
-    {},
-    wrapTool(async () => {
-      const [schema, profile] = await Promise.all([
-        apiRequest('GET', '/api/jobscout/application-profile/schema', null, false, false, MCP_USER_AGENT),
-        apiRequest('GET', '/api/jobscout/application-profile', null, false, false, MCP_USER_AGENT),
-      ]);
-      return { schema, profile };
-    }, 'Failed to fetch profile onboarding')
-  );
-
-  server.tool(
-    'trackly_update_application_profile',
-    'Update confirmed profile answers with optimistic concurrency. Use global scope only for an explicit always-answer preference.',
-    {
-      expectedRevision: z.number().int().min(1),
-      source: z.enum(['web', 'ios', 'macos', 'codex', 'claude', 'mcp']).optional(),
-      changes: z.array(z.discriminatedUnion('scope', [
-        z.object({
-          key: z.string().min(1).max(200), state: z.enum(['unknown', 'answered', 'intentionally_blank', 'declined']),
-          value: z.any().optional(), scope: z.literal('global'), questionLabel: z.string().max(1000).optional(),
-        }),
-        z.object({
-          key: z.string().min(1).max(200), state: z.enum(['unknown', 'answered', 'intentionally_blank', 'declined']),
-          value: z.any().optional(), scope: z.literal('provider'), scopeValue: z.string().min(1).max(200),
-          questionLabel: z.string().max(1000).optional(),
-        }),
-        z.object({
-          key: z.string().min(1).max(200), state: z.enum(['unknown', 'answered', 'intentionally_blank', 'declined']),
-          value: z.any().optional(), scope: z.literal('company'), scopeValue: z.string().min(1).max(200),
-          questionLabel: z.string().max(1000).optional(),
-        }),
-      ])).max(100).optional(),
-      education: z.array(z.object({
-        school: z.string().min(1).max(500),
-        degree: z.string().max(500).nullable().optional(),
-        fieldOfStudy: z.string().max(500).nullable().optional(),
-        gpa: z.string().max(50).nullable().optional(),
-        startDate: z.string().max(50).nullable().optional(),
-        endDate: z.string().max(50).nullable().optional(),
-      })).max(20).optional(),
-      confirmProfile: z.boolean().optional(),
-      sensitiveStorageConsent: z.boolean().optional(),
-    },
-    wrapTool(async (params) => apiRequest('PATCH', '/api/jobscout/application-profile', params, false, false, MCP_USER_AGENT), 'Failed to update application profile')
-  );
-
-  server.tool(
-    'trackly_start_apply_run',
-    'Start a manual-submit browser run for a job already in the approved queue. If maintenance interrupts an existing run, do not call this tool again: wait, refetch protocol/profile state, and resume that same run.',
-    { jobId: z.number().int().min(1), clientName: z.string().max(100).optional() },
-    wrapTool(async (params) => apiRequest('POST', '/api/jobscout/apply/runs', params, false, false, MCP_USER_AGENT), 'Failed to start apply run')
-  );
-
-  server.tool(
-    'trackly_get_apply_evidence',
-    'Get the authenticated user\'s aggregate, value-free Apply beta evidence and release gate. The report never returns answers, contact values, addresses, or page text.',
-    {
-      windowDays: z.number().int().min(1).max(365).optional(),
-      targetReviewedRuns: z.number().int().min(1).max(1000).optional(),
-    },
-    wrapTool(async ({ windowDays, targetReviewedRuns }) => {
-      const qs = new URLSearchParams();
-      if (windowDays !== undefined) qs.set('windowDays', String(windowDays));
-      if (targetReviewedRuns !== undefined) qs.set('targetReviewedRuns', String(targetReviewedRuns));
-      const query = qs.toString();
-      const suffix = query ? `?${query}` : '';
-      return apiRequest('GET', `/api/jobscout/apply/evidence${suffix}`, null, false, false, MCP_USER_AGENT);
-    }, 'Failed to fetch apply evidence')
-  );
-
-  server.tool(
-    'trackly_get_apply_protocol',
-    'Get the current browser workflow, ATS support matrix, integrity rules, and compatible public-skill major version. Fetch at the start of every run and again after maintenance before resuming the existing run.',
-    {},
-    wrapTool(async () => apiRequest('GET', '/api/jobscout/apply/protocol', null, false, false, MCP_USER_AGENT), 'Failed to fetch apply protocol')
-  );
-
-  server.tool(
-    'trackly_report_apply_observation',
-    'Report a redacted ATS mechanics or scenario-coverage observation. Never include answer values, addresses, contact data, OTPs, or free-form page content.',
-    {
-      runId: z.number().int().min(1),
-      provider: z.string().regex(SAFE_OBSERVATION_CODE),
-      fieldLabel: z.string().min(1).max(1000),
-      observationType: z.string().regex(SAFE_OBSERVATION_CODE),
-      resolutionCode: z.string().regex(SAFE_OBSERVATION_CODE).optional(),
-      metadata: z.object({
-        controlType: z.string().regex(SAFE_OBSERVATION_CODE).optional(),
-        required: z.boolean().optional(),
-        errorCode: z.string().regex(SAFE_OBSERVATION_CODE).optional(),
-        committed: z.boolean(),
-        scenarioCode: z.enum(APPLY_SCENARIO_CODES),
-        browserSurface: z.enum(APPLY_BROWSER_SURFACES),
-        browserBindingHash: z.string().regex(/^[a-f0-9]{64}$/).optional(),
-        resumedAfterHandoff: z.boolean().optional(),
-      }),
-    },
-    wrapTool(async (params) => apiRequest('POST', '/api/jobscout/apply/observations', params, false, false, MCP_USER_AGENT), 'Failed to report apply observation')
-  );
-
-  server.tool(
-    'trackly_record_application_outcome',
-    'Record review readiness or a user-confirmed outcome. Mark submitted only after a success page or explicit user confirmation.',
-    {
-      runId: z.number().int().min(1),
-      outcome: z.enum(['review_ready', 'submitted', 'failed', 'blocked']),
-      confirmation: z.string().max(500).optional(),
-    },
-    wrapTool(async ({ runId, ...body }) => apiRequest('POST', `/api/jobscout/apply/runs/${runId}/outcome`, body, false, false, MCP_USER_AGENT), 'Failed to record application outcome')
-  );
-
-  server.tool(
-    'trackly_prepare_resume',
-    'Download the authenticated default resume into a mode-0600 temporary Trackly cache and return exact-file proof for user confirmation before browser upload.',
-    {
-      runId: z.number().int().min(1),
-      browserSurface: z.enum(APPLY_BROWSER_SURFACES),
-      browserBindingHash: z.string().regex(/^[a-f0-9]{64}$/),
-    },
-    wrapTool(async ({ runId, browserSurface, browserBindingHash }) =>
-      prepareResume(runId, browserSurface, browserBindingHash), 'Failed to prepare default resume')
-  );
-
-  server.tool(
-    'trackly_verify_prepared_resume',
-    'Immediately before attachment, recompute the prepared resume fingerprint, validate its run and expiration, and lock the confirmed file read-only.',
-    {
-      runId: z.number().int().min(1),
-      confirmationId: z.string().min(1).max(200),
-      exactLocalPath: z.string().min(1).max(4096),
-      sha256: z.string().regex(/^[a-f0-9]{64}$/i),
-      sizeBytes: z.number().int().min(1),
-      expiresAt: z.string().datetime(),
-    },
-    wrapTool(async (proof) => verifyPreparedResume(proof), 'Prepared resume integrity verification failed')
-  );
-
-  server.registerPrompt('trackly-apply', {
-    title: 'Apply to the next Trackly job',
-    description: 'Run the manual-submit Trackly Apply workflow for the next user-approved job.',
-  }, async () => ({
-    messages: [{
-      role: 'user',
-      content: {
-        type: 'text',
-        text: 'Compatibility gate: before starting a new run, require the fetched Trackly Apply protocol to be version 3.1.0 or newer. After trackly_start_apply_run returns, or before resuming an existing run, require the returned or stored run.protocolVersion to be version 3.1.0 or newer. Never continue or replace a pre-evidence 3.0.x run; preserve it, record it blocked when possible, and stop for supported lifecycle cleanup.',
-      },
-    }, {
-      role: 'user',
-      content: {
-        type: 'text',
-        text: 'Fetch the Trackly Apply protocol, profile onboarding, profile, and approved queue. Resolve missing answers with me. Treat required completeness separately from optional reusable coverage and employer-specific contextual questions. Before starting anything, stop on every non-null executionBlocker and every manual_only item. Start only the selected approved queue item, require major(run.protocolVersion) === major(protocol.version), require protocol.compatibleSkillMajor === 4, preserve the stored version for a resumed run, and require its provider, atsCapability, required scenarios, and originPolicy to match the queue preflight. Reclaim semantic browser control, verify the exact job/run/tab binding, hash that value-free binding, and report the same-run browser_ready attestation with committed=true. Before entering private data, require the visible company and role to match the run binding and, when available, the requisition identifier to match the stored job URL. When job_identity_match is required, report a value-free committed scenario_coverage attestation only after that visible identity check passes; never include the company, role, URL, requisition identifier, page text, or any profile value in that observation. On exact-origin fallback, revalidate the frozen company, role, and available requisition identity after every navigation or redirect and before entering any additional private data. Normalize every page, redirect, and data-receiving iframe URL; accept an exact authorized origin or hostname only when host === allowedDomain or host.endsWith("." + allowedDomain), never by substring or page text. When originPolicy.verification is trackly_employer_source_exact_origin, authorize only the exact origin in authorizedOrigins: never promote it to a host suffix and never carry it across a redirect or iframe origin change. For every other vendor-hosted ATS policy, require both originPolicy.tenantRule and originPolicy.verifiedAtsTenant to be non-null or stop before private data entry. Execute the backend-owned originPolicy.tenantRule exactly after every redirect or data-receiving iframe change, including its extraction, exact-host-depth, locale, percent-decoding, normalization, and fail-closed semantics, then require the normalized result to equal originPolicy.verifiedAtsTenant; never invent or reinterpret a strategy token. Obey every capability stop condition. Determine whether the form has a semantically identified Resume or CV attachment control. Only when that specific control exists, prepare the run-bound resume locally with that browser surface and binding hash, show me its exact path, filename, size, SHA-256, run, and expiration, and obtain my explicit confirmation. Treat cover-letter, portfolio, transcript, and other supporting-document controls separately according to the profile and protocol; never upload a resume to them. Immediately before attaching the resume, use the local verifier to validate the signed proof, recompute hash and size, check expiration, and lock the file read-only. Fill the form through semantic controls, verify committed values and every required error, and report a same-run passed or corrected scenario_coverage observation with committed=true for every backend-required scenario except browser_reclaim, which is satisfied only by browser_ready with the binding hash. Before every review_ready outcome, also report value-free committed critical_contact_integrity and manual_submit_boundary evidence; never include contact values, answers, page text, or local paths. If a required or universal review scenario cannot pass, record blocked rather than review_ready. Stop before Submit. If maintenance interrupts the run, retain the run and browser context, wait for the advertised window, refetch protocol, queue, and profile state, and resume the existing agent_browser run. Never start a duplicate run, blindly retry a mutation, enter credentials or verification codes, evade human verification, or click Submit.',
-      },
-    }],
-  }));
-
-  server.registerResource('trackly-apply-protocol', 'trackly://apply/protocol', {
-    title: 'Current Trackly Apply protocol',
-    description: 'Versioned browser mechanics and compatibility contract.',
-    mimeType: 'application/json',
-  }, async (uri) => {
-    try {
-      const result = await apiRequest('GET', '/api/jobscout/apply/protocol', null, false, false, MCP_USER_AGENT);
-      return { contents: [{ uri: uri.href, mimeType: 'application/json', text: JSON.stringify(result) }] };
-    } catch (error) {
-      return throwMcpResourceError(error);
-    }
+  registerApplyTools(server, {
+    wrapTool,
+    mcpUserAgent: MCP_USER_AGENT,
+    throwMcpResourceError,
   });
-
   return server;
 }