trackly-cli 0.7.2 → 0.8.1

package/lib/agent.js

@@ -7,15 +7,17 @@ const path = require('node:path');
 const { spawnSync } = require('node:child_process');
 const { apiRequest, downloadFile, getConfigPaths, hasAuth, maintenanceOutput } = require('./client');
 const { version: PACKAGE_VERSION } = require('../package.json');
-const SKILL_VERSION = '4.1.1';
+const { contractVersion: MCP_CONTRACT_VERSION } = require('../contracts/trackly-apply-tools.json');
+const SKILL_VERSION = '4.2.1';
 const CLI_USER_AGENT = `trackly-cli/${PACKAGE_VERSION}`;
 const MCP_USER_AGENT = `trackly-mcp/${PACKAGE_VERSION}`;
 
 const SKILL_NAME = 'trackly-apply';
 const SKILL_MAJOR = Number(SKILL_VERSION.split('.')[0]);
-const MIN_APPLY_PROTOCOL_VERSION = '3.1.0';
+const MIN_APPLY_PROTOCOL_VERSION = '3.3.1';
 const CACHE_TTL_MS = 2 * 60 * 60 * 1000;
 const MANAGED_FILE = '.trackly-managed.json';
+const SKILL_MANIFEST_VERSION = 1;
 const RESUME_PROOF_FILE = '.trackly-resume-proof.json';
 const RESUME_PROOF_KEY_BYTES = 32;
 
@@ -52,6 +54,43 @@ function copyDirectory(source, destination) {
   }
 }
 
+function skillContentManifest(root) {
+  const files = [];
+
+  function collect(directory, relativeDirectory = '') {
+    const names = fs.readdirSync(directory).sort();
+    for (const name of names) {
+      if (!relativeDirectory && name === MANAGED_FILE) continue;
+      const absolutePath = path.join(directory, name);
+      const relativePath = relativeDirectory ? `${relativeDirectory}/${name}` : name;
+      const stat = fs.lstatSync(absolutePath);
+      if (stat.isDirectory()) {
+        collect(absolutePath, relativePath);
+        continue;
+      }
+      if (!stat.isFile()) {
+        throw new Error(`Trackly Apply skill contains an unsupported filesystem entry: ${relativePath}`);
+      }
+      const content = fs.readFileSync(absolutePath);
+      files.push({
+        path: relativePath,
+        sizeBytes: content.length,
+        sha256: crypto.createHash('sha256').update(content).digest('hex'),
+      });
+    }
+  }
+
+  collect(root);
+  const digest = crypto.createHash('sha256')
+    .update(JSON.stringify({ version: SKILL_MANIFEST_VERSION, files }))
+    .digest('hex');
+  return {
+    version: SKILL_MANIFEST_VERSION,
+    digest,
+    fileCount: files.length,
+  };
+}
+
 function managedMetadata(extra = {}) {
   return JSON.stringify({ managedBy: 'trackly-cli', skill: SKILL_NAME, skillVersion: SKILL_VERSION, ...extra }, null, 2);
 }
@@ -80,7 +119,12 @@ function installCanonicalSkill() {
   const staging = `${destination}.staging.${process.pid}.${crypto.randomBytes(4).toString('hex')}`;
   try {
     copyDirectory(source, staging);
-    fs.writeFileSync(path.join(staging, MANAGED_FILE), managedMetadata(), { mode: 0o600 });
+    const manifest = skillContentManifest(staging);
+    fs.writeFileSync(path.join(staging, MANAGED_FILE), managedMetadata({
+      skillManifestVersion: manifest.version,
+      skillContentDigest: manifest.digest,
+      skillFileCount: manifest.fileCount,
+    }), { mode: 0o600 });
   } catch (error) {
     if (fs.existsSync(staging)) fs.rmSync(staging, { recursive: true, force: true });
     throw error;
@@ -157,7 +201,13 @@ function linkClientSkill(client, canonical) {
     const staging = `${target}.staging.${process.pid}.${crypto.randomBytes(4).toString('hex')}`;
     try {
       copyDirectory(canonical, staging);
-      fs.writeFileSync(path.join(staging, MANAGED_FILE), managedMetadata({ copiedFrom: canonical }), { mode: 0o600 });
+      const manifest = skillContentManifest(staging);
+      fs.writeFileSync(path.join(staging, MANAGED_FILE), managedMetadata({
+        copiedFrom: canonical,
+        skillManifestVersion: manifest.version,
+        skillContentDigest: manifest.digest,
+        skillFileCount: manifest.fileCount,
+      }), { mode: 0o600 });
       fs.renameSync(staging, target);
       if (backup) fs.rmSync(backup, { recursive: true, force: true });
       return { client, target, method: 'copy', status: 'installed' };
@@ -281,10 +331,47 @@ function inspectClient(client) {
   const target = clientSkillDir(client);
   const executable = commandExists(client === 'codex' ? 'codex' : 'claude');
   const metadata = managedSkillMetadata(target);
-  const installed = fs.existsSync(path.join(target, 'SKILL.md')) && metadata?.skillVersion === SKILL_VERSION;
+  let expectedManifest = null;
+  let installedManifest = null;
+  try {
+    expectedManifest = skillContentManifest(bundledSkillDir());
+    installedManifest = skillContentManifest(target);
+  } catch (_) {}
+  const hasRecordedManifest = metadata?.skillManifestVersion === SKILL_MANIFEST_VERSION
+    && typeof metadata?.skillContentDigest === 'string'
+    && Number.isInteger(metadata?.skillFileCount);
+  const contentMatches = hasRecordedManifest
+    && expectedManifest !== null
+    && installedManifest !== null
+    && metadata.skillContentDigest === expectedManifest.digest
+    && metadata.skillContentDigest === installedManifest.digest
+    && metadata.skillFileCount === expectedManifest.fileCount
+    && metadata.skillFileCount === installedManifest.fileCount;
+  const skillIntegrity = contentMatches
+    ? 'verified'
+    : metadata && !hasRecordedManifest
+      ? 'manifest_missing'
+      : metadata
+        ? 'content_mismatch'
+        : 'not_managed';
+  const installed = fs.existsSync(path.join(target, 'SKILL.md'))
+    && metadata?.skillVersion === SKILL_VERSION
+    && skillIntegrity === 'verified';
   const mcpRegistration = mcpRegistrationState(client);
   const mcpRegistered = mcpRegistration === 'current';
-  return { client, executable, installed, installedSkillVersion: metadata?.skillVersion || null, mcpRegistered, mcpRegistration, target };
+  return {
+    client,
+    executable,
+    installed,
+    installedSkillVersion: metadata?.skillVersion || null,
+    skillIntegrity,
+    expectedSkillContentDigest: expectedManifest?.digest || null,
+    installedSkillContentDigest: installedManifest?.digest || null,
+    recordedSkillContentDigest: metadata?.skillContentDigest || null,
+    mcpRegistered,
+    mcpRegistration,
+    target,
+  };
 }
 
 function cacheDir() {
@@ -368,11 +455,21 @@ function resumeCacheName(fileName, contentType, now = Date.now(), nonce = crypto
   return path.join(`${now}-${nonce}`, safeResumeName(fileName, contentType));
 }
 
-function resumeConfirmation(fileName, sha256, sizeBytes, exactLocalPath, runId, expiresAt, confirmationId) {
+function resumeConfirmation(
+  fileName,
+  sha256,
+  sizeBytes,
+  exactLocalPath,
+  runId,
+  expiresAt,
+  confirmationId,
+  resumeId = null,
+) {
   return {
     required: true,
     source: 'trackly_default_resume',
     runId,
+    ...(resumeId == null ? {} : { resumeId }),
     confirmationId,
     fileName,
     sha256,
@@ -450,6 +547,10 @@ function verifyResumeProofSignature(manifest) {
 function materializeResume(download, options = {}) {
   const runId = Number(options.runId);
   if (!Number.isInteger(runId) || runId < 1) throw new Error('A valid Trackly Apply run ID is required before preparing a resume.');
+  const resumeId = download.resumeId == null ? null : Number(download.resumeId);
+  if (resumeId !== null && (!Number.isInteger(resumeId) || resumeId < 1)) {
+    throw new Error('Trackly returned an invalid default resume identity.');
+  }
   const now = options.now ?? Date.now();
   const nonce = options.nonce ?? crypto.randomBytes(4).toString('hex');
   const confirmationId = options.confirmationId ?? crypto.randomUUID();
@@ -471,11 +572,13 @@ function materializeResume(download, options = {}) {
     runId,
     expiresAt,
     confirmationId,
+    resumeId,
   );
   const manifestPath = path.join(path.dirname(destination), RESUME_PROOF_FILE);
   try {
     const manifest = signedResumeProof({
       runId,
+      resumeId,
       confirmationId,
       exactLocalPath: destination,
       fileName,
@@ -494,6 +597,7 @@ function materializeResume(download, options = {}) {
   }
   return {
     path: destination,
+    resumeId,
     fileName,
     contentType: validated.contentType,
     sha256: validated.digest,
@@ -542,6 +646,11 @@ function verifyPreparedResume(proof, now = Date.now()) {
   }
 
   const bindingMatches = manifest.runId === runId
+    && (
+      proof.resumeId == null
+        ? manifest.resumeId == null
+        : manifest.resumeId === Number(proof.resumeId)
+    )
     && manifest.confirmationId === proof.confirmationId
     && manifest.exactLocalPath === expectedPath
     && manifest.fileName === path.basename(expectedPath)
@@ -570,6 +679,7 @@ function verifyPreparedResume(proof, now = Date.now()) {
   return {
     verified: true,
     runId,
+    resumeId: manifest.resumeId ?? null,
     confirmationId: proof.confirmationId,
     exactLocalPath: expectedPath,
     sha256,
@@ -621,6 +731,9 @@ async function prepareResume(runId, browserSurface, browserBindingHash, userAgen
     if (Number(download.applyRunId) !== normalizedRunId) {
       throw new Error('Trackly did not confirm that the resume belongs to the active Apply run.');
     }
+    if (!Number.isInteger(Number(download.resumeId)) || Number(download.resumeId) < 1) {
+      throw new Error('Trackly did not confirm the default resume identity.');
+    }
     return materializeResume(download, { runId: normalizedRunId });
   } finally {
     download.buffer.fill(0);
@@ -631,7 +744,12 @@ function protocolAtLeast(version, minimum = MIN_APPLY_PROTOCOL_VERSION) {
   const parse = (value) => String(value || '').split('.').map((part) => Number(part));
   const actual = parse(version);
   const required = parse(minimum);
-  if (actual.length < 2 || actual.some((part) => !Number.isInteger(part) || part < 0)) return false;
+  if (
+    actual.length < 2
+    || required.length < 2
+    || actual.some((part) => !Number.isInteger(part) || part < 0)
+    || required.some((part) => !Number.isInteger(part) || part < 0)
+  ) return false;
   for (let index = 0; index < Math.max(actual.length, required.length); index++) {
     const left = actual[index] || 0;
     const right = required[index] || 0;
@@ -640,6 +758,47 @@ function protocolAtLeast(version, minimum = MIN_APPLY_PROTOCOL_VERSION) {
   return true;
 }
 
+function evaluateApplyCompatibility(protocol, clients) {
+  const compatibleSkillMajor = Number(protocol?.compatibleSkillMajor);
+  const minimumSkillVersion = typeof protocol?.compatibleSkillMinimumVersion === 'string'
+    ? protocol.compatibleSkillMinimumVersion
+    : null;
+  const minimumCliVersion = typeof protocol?.compatibleCliMinimumVersion === 'string'
+    ? protocol.compatibleCliMinimumVersion
+    : null;
+  const mcpContractCompatible = protocol?.mcpContractVersion === MCP_CONTRACT_VERSION;
+  const cliMinimumSatisfied = minimumCliVersion
+    ? protocolAtLeast(PACKAGE_VERSION, minimumCliVersion)
+    : false;
+  const protocolCompatible = compatibleSkillMajor === SKILL_MAJOR
+    && protocolAtLeast(protocol?.version, MIN_APPLY_PROTOCOL_VERSION);
+  const compatibleClientSkills = minimumSkillVersion
+    ? clients
+      .filter((client) => {
+        const installedMajor = Number(String(client.installedSkillVersion || '').split('.')[0]);
+        return client.installed === true
+          && installedMajor === compatibleSkillMajor
+          && protocolAtLeast(client.installedSkillVersion, minimumSkillVersion);
+      })
+      .map((client) => client.client)
+    : [];
+  const skillMinimumSatisfied = compatibleClientSkills.length > 0;
+  return {
+    protocolCompatible,
+    mcpContractVersion: MCP_CONTRACT_VERSION,
+    mcpContractCompatible,
+    minimumCliVersion,
+    cliMinimumSatisfied,
+    minimumSkillVersion,
+    compatibleClientSkills,
+    skillMinimumSatisfied,
+    compatible: protocolCompatible
+      && mcpContractCompatible
+      && cliMinimumSatisfied
+      && skillMinimumSatisfied,
+  };
+}
+
 function liveBrowserReady(browserControl) {
   return (browserControl?.codex === true && browserControl?.codexComputerUse === true)
     || browserControl?.claude === true;
@@ -654,13 +813,38 @@ async function doctorAgent() {
     codexComputerUse,
     claude: null,
   };
+  const tabInventory = {
+    controllerOwnedTabs: 'runtime_verification_required',
+    userOwnedTabs: 'runtime_verification_required',
+    unionReconciliation: 'runtime_verification_required',
+    detectedSurfaces: [],
+    unionInventoryDetected: false,
+    requiredForClosedClaim: true,
+    note: 'Installed plugins do not prove controller-owned and user-owned tab union inventory. The active browser client must verify both inventories before claiming a tab is closed.',
+  };
+  const clients = ['codex', 'claude'].map(inspectClient);
+  const skillIntegrityFailures = clients
+    .filter((client) => (
+      client.installedSkillVersion === SKILL_VERSION
+      && client.skillIntegrity !== 'verified'
+    ))
+    .map((client) => ({ client: client.client, integrity: client.skillIntegrity }));
   const report = {
+    cliVersion: PACKAGE_VERSION,
+    mcpContractVersion: MCP_CONTRACT_VERSION,
     skillVersion: SKILL_VERSION,
     authenticated: hasAuth(),
-    clients: ['codex', 'claude'].map(inspectClient),
+    clients,
+    skillPackIntegrity: {
+      ok: skillIntegrityFailures.length === 0,
+      expectedDigest: clients.find((client) => client.expectedSkillContentDigest)
+        ?.expectedSkillContentDigest || null,
+      failures: skillIntegrityFailures,
+    },
     browserControl: {
       ...browserControl,
       semanticReady: liveBrowserReady(browserControl),
+      tabInventory,
       note: 'A live run requires both semantic browser control and computer use. Claude capability must be verified by the active client before the run starts.',
     },
     cache,
@@ -682,8 +866,8 @@ async function doctorAgent() {
       completeness: profile.profile?.completeness,
       hasDefaultResume: Boolean(profile.profile?.defaultResume),
     };
-    report.compatible = Number(report.protocol.compatibleSkillMajor) === SKILL_MAJOR
-      && protocolAtLeast(report.protocol.version, MIN_APPLY_PROTOCOL_VERSION);
+    report.compatibility = evaluateApplyCompatibility(report.protocol, report.clients);
+    report.compatible = report.compatibility.compatible;
     if (report.profile.hasDefaultResume) {
       report.resume = {
         available: true,
@@ -697,6 +881,7 @@ async function doctorAgent() {
   report.ok = report.authenticated
     && report.compatible
     && report.browserControl.semanticReady
+    && report.skillPackIntegrity.ok
     && report.clients.some((client) => client.executable && client.installed && client.mcpRegistered)
     && Boolean(report.profile?.hasDefaultResume)
     && report.resume.available
@@ -724,6 +909,7 @@ module.exports = {
   cleanResumeCache,
   clientSkillDir,
   doctorAgent,
+  evaluateApplyCompatibility,
   inspectClient,
   liveBrowserReady,
   materializeResume,

package/lib/client.js

@@ -18,6 +18,22 @@ const MAINTENANCE_APPLY_GUIDANCE =
   'Do not blindly retry an Apply mutation. Wait for the advertised maintenance window, ' +
   'refetch the Apply protocol and application profile, then resume the existing agent_browser run. ' +
   'Never create a duplicate run or click Submit.';
+const TRACKLY_ACCESS_GUIDANCE =
+  'Trackly is in a limited rollout. Existing members can sign in; new members need a private invite. ' +
+  'Request access at https://usetrackly.app/early-access.';
+const TRACKLY_ACCESS_PENDING_GUIDANCE =
+  'Your Trackly access request is already pending. No new request is needed.';
+const TRACKLY_ACCESS_UNAVAILABLE_GUIDANCE =
+  'Trackly access could not be verified right now. Please try again.';
+const TRACKLY_ACCESS_CODES = new Set([
+  'INVITATION_REQUIRED',
+  'INVITATION_INVALID',
+  'INVITATION_REDEEMED',
+  'SIGNUP_INTENT_EXPIRED',
+  'ACCESS_BATCH_FULL',
+  'ACCESS_CHECK_UNAVAILABLE',
+  'ALREADY_REQUESTED',
+]);
 
 class TracklyConfigError extends Error {
   constructor(message) {
@@ -243,6 +259,27 @@ function nestedRecord(value) {
   return value && typeof value === 'object' && !Array.isArray(value) ? value : {};
 }
 
+function createTracklyAccessError(json, status) {
+  const record = nestedRecord(json);
+  const code = cleanText(record.code);
+  if (!code || !TRACKLY_ACCESS_CODES.has(code.toUpperCase())) return null;
+  const normalizedCode = code.toUpperCase();
+  const retryable = normalizedCode === 'ACCESS_CHECK_UNAVAILABLE';
+  const message = retryable
+    ? TRACKLY_ACCESS_UNAVAILABLE_GUIDANCE
+    : normalizedCode === 'ALREADY_REQUESTED'
+      ? TRACKLY_ACCESS_PENDING_GUIDANCE
+      : TRACKLY_ACCESS_GUIDANCE;
+  return {
+    ...record,
+    status: status ?? (retryable ? 503 : 403),
+    code: normalizedCode,
+    error: message,
+    message,
+    retryable,
+  };
+}
+
 // REST maintenance responses and hosted MCP JSON-RPC errors intentionally use
 // different envelopes. Collapse both into the same source view so every CLI
 // surface preserves equivalent code/retry/ETA/request context.
@@ -472,7 +509,15 @@ async function _doRefresh() {
   return null;
 }
 
-function apiRequest(method, endpoint, data = null, skipAuth = false, _isRetry = false, userAgent = null) {
+function apiRequest(
+  method,
+  endpoint,
+  data = null,
+  skipAuth = false,
+  _isRetry = false,
+  userAgent = null,
+  additionalHeaders = null
+) {
   return new Promise((resolve, reject) => {
     let url;
     try {
@@ -485,6 +530,27 @@ function apiRequest(method, endpoint, data = null, skipAuth = false, _isRetry =
     const isHttps = url.protocol === 'https:';
     const lib = isHttps ? https : http;
     const headers = getRequestHeaders(skipAuth, userAgent);
+    if (additionalHeaders !== null) {
+      const entries = (
+        typeof additionalHeaders === 'object'
+        && additionalHeaders !== null
+        && !Array.isArray(additionalHeaders)
+        && Object.getPrototypeOf(additionalHeaders) === Object.prototype
+      )
+        ? Object.entries(additionalHeaders)
+        : [];
+      const idempotencyEntry = entries.find(([name]) => name.toLowerCase() === 'idempotency-key');
+      if (
+        entries.length !== 1
+        || !idempotencyEntry
+        || typeof idempotencyEntry[1] !== 'string'
+        || !/^[\x20-\x7e]{16,200}$/.test(idempotencyEntry[1])
+      ) {
+        reject(new Error('Only a valid Idempotency-Key additional header is permitted.'));
+        return;
+      }
+      headers['Idempotency-Key'] = idempotencyEntry[1];
+    }
     const authMethod = getAuthMethod();
     const timeoutMs = getRequestTimeoutMs();
     const hasSensitivePayload = Boolean(data && typeof data === 'object' && 'refreshToken' in data);
@@ -567,7 +633,15 @@ function apiRequest(method, endpoint, data = null, skipAuth = false, _isRetry =
           }
           if (newToken) {
             try {
-              const retried = await apiRequest(method, endpoint, data, false, true, userAgent);
+              const retried = await apiRequest(
+                method,
+                endpoint,
+                data,
+                false,
+                true,
+                userAgent,
+                additionalHeaders
+              );
               return resolve(retried);
             } catch (e) { return reject(e); }
           }
@@ -579,6 +653,8 @@ function apiRequest(method, endpoint, data = null, skipAuth = false, _isRetry =
             headers: res.headers,
           });
           if (maintenanceError) return reject(maintenanceError);
+          const accessError = createTracklyAccessError(json, res.statusCode);
+          if (accessError) return reject(accessError);
           // Spread `json` FIRST so the HTTP statusCode always wins. A backend that returns
           // `{"status": "error"}` in the body would otherwise clobber the numeric status with
           // a string, breaking downstream branches like `typeof e.status === 'number'` in
@@ -676,6 +752,11 @@ function downloadFile(endpoint, userAgent = null, _isRetry = false) {
             reject(maintenanceError);
             return;
           }
+          const accessError = createTracklyAccessError(body, res.statusCode);
+          if (accessError) {
+            reject(accessError);
+            return;
+          }
           reject({ ...body, status: res.statusCode, message: body.error || `HTTP ${res.statusCode}` });
           return;
         }
@@ -686,6 +767,7 @@ function downloadFile(endpoint, userAgent = null, _isRetry = false) {
           fileName: contentDispositionFileName(disposition),
           sha256: res.headers['x-trackly-file-sha256'] || null,
           applyRunId: res.headers['x-trackly-apply-run-id'] || null,
+          resumeId: res.headers['x-trackly-resume-id'] || null,
         });
       });
     });
@@ -720,6 +802,7 @@ module.exports = {
   TracklyConfigError,
   MAINTENANCE_APPLY_GUIDANCE,
   MAINTENANCE_CODE,
+  TRACKLY_ACCESS_GUIDANCE,
   apiRequest,
   downloadFile,
   clearConfig,
@@ -738,6 +821,7 @@ module.exports = {
   hasAuth,
   loadConfig,
   createMaintenanceError,
+  createTracklyAccessError,
   isMaintenanceError,
   maintenanceOutput,
   normalizeMaintenance,