job-application-agent 2.0.0

package/job-application-agent/scripts/telemetry-client.mjs

@@ -0,0 +1,176 @@
+import { chmod, mkdir, readFile, readdir, rename, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+
+import { createTelemetryEnvelope, jobIdentity, validateEvent } from './telemetry-schema.mjs';
+
+export const SKILL_VERSION = '1.2.1';
+export const DEFAULT_TELEMETRY_ENDPOINT = process.env.JOB_APPLICATION_AGENT_TELEMETRY_URL ?? 'https://job-application-agent-telemetry.varora1406.workers.dev';
+export const TELEMETRY_NOTICE = 'Anonymous usage analytics are enabled by default. They include structured job and workflow metrics, but never your identity, resume, prompts, form answers, browser data, or candidate profile. Run `telemetry disable` to opt out or `telemetry preview` to inspect an event.\n';
+
+const CONFIG_VERSION = 1;
+const CONFIG_FILE = 'telemetry.json';
+const EVENTS_WITH_DOMAIN = new Set(['job_discovered', 'job_assessed', 'application_submitted', 'outcome_recorded']);
+
+export async function prepareTelemetryInput(input) {
+  if (!input || Array.isArray(input) || typeof input !== 'object') return validateEvent(input);
+  for (const key of Object.keys(input)) if (!['event', 'properties'].includes(key)) throw new Error(`Unknown telemetry input property: ${key}.`);
+  const properties = { ...(input.properties ?? {}) };
+  if ('jobUrl' in properties) {
+    const identity = await jobIdentity(properties.jobUrl);
+    delete properties.jobUrl;
+    properties.jobHash = identity.jobHash;
+    if (EVENTS_WITH_DOMAIN.has(input.event)) properties.domain = identity.domain;
+  }
+  return validateEvent({ event: input.event, properties });
+}
+
+async function exists(file) {
+  try { await readFile(file); return true; } catch (error) { if (error.code === 'ENOENT') return false; throw error; }
+}
+
+async function writePrivate(file, value) {
+  const temporary = `${file}.${process.pid}.tmp`;
+  await writeFile(temporary, `${JSON.stringify(value, null, 2)}\n`, { mode: 0o600 });
+  await rename(temporary, file);
+  await chmod(file, 0o600);
+}
+
+export class TelemetryClient {
+  constructor({ stateDir, endpoint = DEFAULT_TELEMETRY_ENDPOINT, fetch: fetchFn = globalThis.fetch, stderr = (value) => process.stderr.write(value), now = () => new Date(), timeoutMs = Number(process.env.JOB_APPLICATION_AGENT_TELEMETRY_TIMEOUT_MS ?? 750) }) {
+    this.stateDir = stateDir;
+    this.endpoint = endpoint.replace(/\/$/, '');
+    this.fetch = fetchFn;
+    this.stderr = stderr;
+    this.now = now;
+    this.timeoutMs = timeoutMs;
+  }
+
+  get configPath() { return join(this.stateDir, CONFIG_FILE); }
+
+  async ensureDirectory() {
+    await mkdir(this.stateDir, { recursive: true, mode: 0o700 });
+    await chmod(this.stateDir, 0o700);
+  }
+
+  async readConfig() {
+    try {
+      const value = JSON.parse(await readFile(this.configPath, 'utf8'));
+      return { version: CONFIG_VERSION, enabled: value.enabled !== false, disclosed: value.disclosed === true, graceConsumed: value.graceConsumed === true, installationEventPending: value.installationEventPending === true, installationId: value.installationId ?? null, token: value.token ?? null, tokenExpiresAt: value.tokenExpiresAt ?? null };
+    } catch (error) {
+      if (error.code === 'ENOENT') return null;
+      return { version: CONFIG_VERSION, enabled: false, disclosed: true, graceConsumed: true, installationEventPending: false, installationId: null, token: null, tokenExpiresAt: null };
+    }
+  }
+
+  async saveConfig(config) {
+    await this.ensureDirectory();
+    await writePrivate(this.configPath, config);
+  }
+
+  async hasExistingPrivateState() {
+    await this.ensureDirectory();
+    const names = await readdir(this.stateDir);
+    return names.some((name) => name !== CONFIG_FILE && !name.endsWith('.tmp'));
+  }
+
+  async beginCommand(command) {
+    let config = await this.readConfig();
+    let allowSend = true;
+    if (!config) {
+      const existing = await this.hasExistingPrivateState();
+      config = { version: CONFIG_VERSION, enabled: true, disclosed: true, graceConsumed: !existing, installationEventPending: !existing, installationId: null, token: null, tokenExpiresAt: null };
+      this.stderr(TELEMETRY_NOTICE);
+      await this.saveConfig(config);
+      if (existing) {
+        allowSend = false;
+        config.graceConsumed = true;
+        await this.saveConfig(config);
+      }
+    } else if (!config.disclosed) {
+      this.stderr(TELEMETRY_NOTICE);
+      config.disclosed = true;
+      if (!config.graceConsumed) {
+        allowSend = false;
+        config.graceConsumed = true;
+      }
+      await this.saveConfig(config);
+    } else if (!config.graceConsumed) {
+      allowSend = false;
+      config.graceConsumed = true;
+      await this.saveConfig(config);
+    }
+    return { command, enabled: config.enabled, allowSend: config.enabled && allowSend, installationEventPending: config.installationEventPending === true };
+  }
+
+  async credentials(config) {
+    if (config.installationId && config.token && config.tokenExpiresAt && Date.parse(config.tokenExpiresAt) > this.now().getTime() + 60_000) return config;
+    const body = config.installationId && config.token ? { installationId: config.installationId, token: config.token } : {};
+    const response = await this.fetch(`${this.endpoint}/v1/install`, { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify(body), signal: AbortSignal.timeout(this.timeoutMs) });
+    if (!response.ok) throw new Error('relay unavailable');
+    const identity = await response.json();
+    const next = { ...config, installationId: identity.installationId, token: identity.token, tokenExpiresAt: identity.expiresAt };
+    await this.saveConfig(next);
+    return next;
+  }
+
+  async record(input, session = { enabled: true, allowSend: true }, { strict = false } = {}) {
+    let event;
+    try {
+      event = await prepareTelemetryInput(input);
+    } catch (error) {
+      if (strict) throw error;
+      return { sent: false, reason: 'invalid' };
+    }
+    try {
+      if (!session.enabled || !session.allowSend) return { sent: false, reason: session.enabled ? 'grace' : 'disabled' };
+      if (session.unavailable) return { sent: false, reason: 'unavailable' };
+      let config = await this.readConfig();
+      if (!config?.enabled) return { sent: false, reason: 'disabled' };
+      config = await this.credentials(config);
+      const payload = createTelemetryEnvelope({ installationId: config.installationId, token: config.token, event, skillVersion: SKILL_VERSION });
+      let response = await this.fetch(`${this.endpoint}/v1/events`, { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify(payload), signal: AbortSignal.timeout(this.timeoutMs) });
+      if (response.status === 401) {
+        config.tokenExpiresAt = null;
+        config = await this.credentials(config);
+        response = await this.fetch(`${this.endpoint}/v1/events`, { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify(createTelemetryEnvelope({ installationId: config.installationId, token: config.token, event, skillVersion: SKILL_VERSION })), signal: AbortSignal.timeout(this.timeoutMs) });
+      }
+      if (!response.ok) {
+        session.unavailable = true;
+        return { sent: false, reason: 'unavailable' };
+      }
+      if (event.event === 'installation_started' && config.installationEventPending) {
+        config.installationEventPending = false;
+        await this.saveConfig(config);
+        session.installationEventPending = false;
+      }
+      return { sent: true };
+    } catch {
+      session.unavailable = true;
+      return { sent: false, reason: 'unavailable' };
+    }
+  }
+
+  async status() {
+    const config = await this.readConfig();
+    return { enabled: config?.enabled ?? true, disclosed: config?.disclosed ?? false, hasInstallationId: Boolean(config?.installationId), endpoint: this.endpoint, schemaVersion: 1 };
+  }
+
+  async configure(action) {
+    const current = await this.readConfig() ?? { version: CONFIG_VERSION, enabled: true, disclosed: false, graceConsumed: true, installationEventPending: true, installationId: null, token: null, tokenExpiresAt: null };
+    if (action === 'status') return this.status();
+    if (action === 'enable') {
+      current.enabled = true;
+      if (!current.installationId) current.installationEventPending = true;
+    }
+    else if (action === 'disable') current.enabled = false;
+    else if (action === 'reset') Object.assign(current, { enabled: false, disclosed: true, graceConsumed: true, installationEventPending: false, installationId: null, token: null, tokenExpiresAt: null });
+    else throw new Error('Telemetry action must be status, enable, disable, or reset.');
+    current.disclosed = true;
+    await this.saveConfig(current);
+    return this.status();
+  }
+
+  async preview(input) {
+    return prepareTelemetryInput(input);
+  }
+}

package/job-application-agent/scripts/telemetry-schema.mjs

@@ -0,0 +1,161 @@
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+const SHA256 = /^[0-9a-f]{64}$/;
+const DOMAIN = /^(?=.{1,253}$)(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z]{2,63}$/;
+const CURRENCY = /^[A-Z]{3}$/;
+const VERSION = /^\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?$/;
+
+export const TELEMETRY_SCHEMA_VERSION = 1;
+export const TELEMETRY_MAX_BYTES = 4096;
+
+const values = (...items) => new Set(items);
+const ATS = values('linkedin', 'greenhouse', 'lever', 'ashby', 'workable', 'comeet', 'workday', 'rippling', 'smartrecruiters', 'google-form', 'company', 'email', 'other');
+const SOURCES = values('linkedin', 'x', 'hacker-news', 'yc', 'aggregator', 'company', 'email', 'referral', 'other');
+const DURATIONS = values('under-1s', '1-5s', '5-30s', '30-60s', '1-2m', '2-5m', '5-15m', '15m-plus');
+const COMMANDS = values('onboard', 'search', 'assess', 'apply', 'batch', 'round', 'outcome', 'review', 'resume', 'profile', 'telemetry', 'other');
+const RESULTS = values('success', 'paused', 'skipped', 'abandoned', 'error');
+const ELIGIBILITY = values('eligible', 'unclear', 'ineligible');
+const DECISIONS = values('review', 'ask', 'skip', 'exclude');
+const WORK_MODES = values('remote', 'hybrid', 'onsite', 'unspecified');
+const SENIORITIES = values('junior', 'mid', 'senior', 'staff', 'principal', 'lead', 'manager', 'director', 'founding', 'unspecified');
+const EMPLOYMENT = values('full-time', 'part-time', 'contract', 'temporary', 'internship', 'unspecified');
+const ROLE_FAMILIES = values('frontend', 'backend', 'full-stack', 'product-engineering', 'ai-ml', 'platform', 'infrastructure', 'mobile', 'engineering-management', 'architecture', 'security', 'data', 'other');
+const APPROVAL_MODES = values('review-each', 'routine-auto');
+const SUBMISSION_MODES = values('review-each', 'routine-auto', 'unconfigured');
+const STAGES = values('discovery', 'assessment', 'application', 'contact', 'resume', 'questions', 'legal', 'demographic', 'review', 'submission', 'confirmation', 'outcome');
+const FIELD_CATEGORIES = values('contact', 'links', 'location', 'authorization', 'compensation', 'experience', 'resume', 'cover-letter', 'referral', 'short-answer', 'legal', 'demographic', 'other');
+const PAUSE_REASONS = values('login', 'sso', 'mfa', 'captcha', 'legal', 'demographic', 'eligibility', 'compensation', 'sensitive-id', 'unverifiable', 'attachment', 'candidate-judgment', 'site-error', 'other');
+const SKIP_REASONS = values('closed', 'duplicate', 'ineligible', 'low-fit', 'location', 'salary', 'seniority', 'candidate-choice', 'no-direct-link', 'other');
+const OUTCOMES = values('interview', 'rejected', 'offer', 'withdrawn');
+const INTERVIEW_QUALITIES = values('promising', 'viable', 'weak', 'dead');
+const FAILURE_POINTS = values('role-scope', 'company-problem', 'constraints', 'interviewer', 'process', 'unknown');
+const ERROR_CODES = values('invalid_input', 'network_failure', 'relay_unavailable', 'authentication_required', 'site_changed', 'upload_failed', 'submission_unconfirmed', 'rate_limited', 'internal_error');
+const MATCH_TAGS = values('role_family', 'seniority', 'skills', 'industry', 'location', 'remote', 'salary', 'ai', 'product', 'leadership', 'authorization');
+const GAP_TAGS = values('role_family', 'seniority', 'skills', 'industry', 'location', 'salary_unknown', 'salary_below', 'authorization_unclear', 'sponsorship', 'experience', 'domain', 'other');
+
+const text = (max, identitySafe = false) => ({ kind: 'text', max, identitySafe });
+const integer = (min, max) => ({ kind: 'integer', min, max });
+const boolean = { kind: 'boolean' };
+const enumValue = (set) => ({ kind: 'enum', set });
+const enumArray = (set, max = 12) => ({ kind: 'enum-array', set, max });
+
+const JOB = {
+  company: text(160, true), title: text(200, true), jobHash: { kind: 'hash' }, domain: { kind: 'domain' }, ats: enumValue(ATS),
+};
+
+export const EVENT_SCHEMAS = {
+  installation_started: { required: { osFamily: enumValue(values('macos', 'linux', 'windows', 'other')), nodeMajor: integer(20, 99), submissionMode: enumValue(SUBMISSION_MODES) } },
+  command_completed: { required: { command: enumValue(COMMANDS), result: enumValue(RESULTS), durationBucket: enumValue(DURATIONS) } },
+  job_discovered: { required: { ...JOB, source: enumValue(SOURCES), jobCountry: text(80, true), workMode: enumValue(WORK_MODES), seniority: enumValue(SENIORITIES), employmentType: enumValue(EMPLOYMENT), roleFamily: enumValue(ROLE_FAMILIES) }, optional: { salaryCurrency: { kind: 'currency' }, salaryMin: integer(0, 10000000), salaryMax: integer(0, 10000000) } },
+  job_assessed: { required: { ...JOB, fitScore: integer(0, 100), eligibility: enumValue(ELIGIBILITY), decision: enumValue(DECISIONS), matchTags: enumArray(MATCH_TAGS), gapTags: enumArray(GAP_TAGS) } },
+  application_started: { required: { jobHash: { kind: 'hash' }, ats: enumValue(ATS), approvalMode: enumValue(APPROVAL_MODES), requiredFieldCount: integer(0, 500), resumeRequired: boolean, coverLetterRequired: boolean, referralPresent: boolean } },
+  application_step: { required: { jobHash: { kind: 'hash' }, ats: enumValue(ATS), stage: enumValue(STAGES), fieldCategory: enumValue(FIELD_CATEGORIES), retryCount: integer(0, 20), durationBucket: enumValue(DURATIONS) } },
+  application_paused: { required: { jobHash: { kind: 'hash' }, ats: enumValue(ATS), stage: enumValue(STAGES), reason: enumValue(PAUSE_REASONS) } },
+  application_skipped: { required: { jobHash: { kind: 'hash' }, reason: enumValue(SKIP_REASONS), fitScore: integer(0, 100), eligibility: enumValue(ELIGIBILITY) } },
+  application_submitted: { required: { ...JOB, durationBucket: enumValue(DURATIONS), fieldsFilled: integer(0, 500), shortAnswerCount: integer(0, 100), resumeUploaded: boolean, approvalMode: enumValue(APPROVAL_MODES) } },
+  round_completed: { required: { requestedCount: integer(1, 1000), submittedCount: integer(0, 1000), assessedCount: integer(0, 10000), skippedCount: integer(0, 10000), pausedCount: integer(0, 10000), errorCount: integer(0, 10000), durationBucket: enumValue(DURATIONS) } },
+  outcome_recorded: {
+    required: { ...JOB, outcome: enumValue(OUTCOMES), daysSinceSubmission: integer(0, 3650) },
+    optional: { interviewQuality: enumValue(INTERVIEW_QUALITIES), failurePoint: enumValue(FAILURE_POINTS) },
+  },
+  review_generated: { required: { submissionCount: integer(0, 100000), interviewCount: integer(0, 100000), rejectionCount: integer(0, 100000), offerCount: integer(0, 100000), withdrawalCount: integer(0, 100000), reviewDue: boolean } },
+  skill_error: { required: { errorCode: enumValue(ERROR_CODES), stage: enumValue(STAGES), recoverable: boolean }, optional: { ats: enumValue(ATS), jobHash: { kind: 'hash' } } },
+};
+
+export function containsDirectIdentity(value) {
+  if (typeof value !== 'string') return false;
+  return /(?:[^\s@]+@[^\s@]+\.[^\s@]+)|(?:https?:\/\/|www\.)|(?:linkedin\.com|github\.com)|(?:\+?\d[\d\s().-]{6,}\d)/i.test(value);
+}
+
+function validateProperty(name, value, rule) {
+  if (rule.kind === 'text') {
+    if (typeof value !== 'string' || !value.trim() || value.length > rule.max) throw new Error(`${name} must be a non-empty string no longer than ${rule.max} characters.`);
+    if (rule.identitySafe && containsDirectIdentity(value)) throw new Error(`${name} contains direct identity data.`);
+    if (/[\x00-\x1f\x7f]/.test(value)) throw new Error(`${name} contains control characters.`);
+    return value.trim();
+  }
+  if (rule.kind === 'integer') {
+    if (!Number.isInteger(value) || value < rule.min || value > rule.max) throw new Error(`${name} must be an integer from ${rule.min} to ${rule.max}.`);
+    return value;
+  }
+  if (rule.kind === 'boolean') {
+    if (typeof value !== 'boolean') throw new Error(`${name} must be a Boolean.`);
+    return value;
+  }
+  if (rule.kind === 'enum') {
+    if (typeof value !== 'string' || !rule.set.has(value)) throw new Error(`${name} is invalid.`);
+    return value;
+  }
+  if (rule.kind === 'enum-array') {
+    if (!Array.isArray(value) || value.length > rule.max || value.some((item) => typeof item !== 'string' || !rule.set.has(item))) throw new Error(`${name} must contain only documented tags.`);
+    return [...new Set(value)];
+  }
+  if (rule.kind === 'hash') {
+    if (typeof value !== 'string' || !SHA256.test(value)) throw new Error(`${name} must be a SHA-256 job hash.`);
+    return value;
+  }
+  if (rule.kind === 'domain') {
+    if (typeof value !== 'string' || !DOMAIN.test(value)) throw new Error(`${name} must be a canonical domain.`);
+    return value;
+  }
+  if (rule.kind === 'currency') {
+    if (typeof value !== 'string' || !CURRENCY.test(value)) throw new Error(`${name} must be an ISO-style currency code.`);
+    return value;
+  }
+  throw new Error(`Unsupported telemetry property ${name}.`);
+}
+
+export function validateEvent(input) {
+  if (!input || Array.isArray(input) || typeof input !== 'object') throw new Error('Telemetry event must be an object.');
+  const schema = EVENT_SCHEMAS[input.event];
+  if (!schema) throw new Error('Unknown telemetry event.');
+  if (!input.properties || Array.isArray(input.properties) || typeof input.properties !== 'object') throw new Error('Telemetry properties must be an object.');
+  const rules = { ...schema.required, ...(schema.optional ?? {}) };
+  for (const name of Object.keys(input.properties)) if (!rules[name]) throw new Error(`Unknown telemetry property: ${name}.`);
+  const properties = {};
+  for (const [name, rule] of Object.entries(schema.required)) {
+    if (!(name in input.properties)) throw new Error(`Missing telemetry property: ${name}.`);
+    properties[name] = validateProperty(name, input.properties[name], rule);
+  }
+  for (const [name, rule] of Object.entries(schema.optional ?? {})) if (name in input.properties) properties[name] = validateProperty(name, input.properties[name], rule);
+  if (input.event === 'outcome_recorded' && properties.failurePoint && !properties.interviewQuality) throw new Error('failurePoint requires interviewQuality.');
+  const result = { event: input.event, properties };
+  if (new TextEncoder().encode(JSON.stringify(result)).length > TELEMETRY_MAX_BYTES) throw new Error('Telemetry event exceeds 4 KB.');
+  return result;
+}
+
+export function canonicalizeJobUrl(value) {
+  const url = new URL(value);
+  if (!['https:', 'http:'].includes(url.protocol)) throw new Error('Job URL must use HTTP or HTTPS.');
+  url.protocol = 'https:';
+  url.username = '';
+  url.password = '';
+  url.search = '';
+  url.hash = '';
+  url.hostname = url.hostname.toLowerCase();
+  url.pathname = url.pathname.replace(/\/+$/, '') || '/';
+  return url.toString().replace(/\/$/, '');
+}
+
+export async function jobIdentity(value) {
+  const canonical = canonicalizeJobUrl(value);
+  const digest = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(canonical));
+  return { jobHash: [...new Uint8Array(digest)].map((byte) => byte.toString(16).padStart(2, '0')).join(''), domain: new URL(canonical).hostname };
+}
+
+export function createTelemetryEnvelope({ installationId, token, event, properties, skillVersion }) {
+  if (!UUID.test(installationId)) throw new Error('installationId must be an anonymous UUID.');
+  if (typeof token !== 'string' || token.length < 8 || token.length > 2048) throw new Error('token is invalid.');
+  if (typeof skillVersion !== 'string' || !VERSION.test(skillVersion)) throw new Error('skillVersion is invalid.');
+  const safe = validateEvent(typeof event === 'string' ? { event, properties } : event);
+  const envelope = { schemaVersion: TELEMETRY_SCHEMA_VERSION, skillVersion, installationId, token, ...safe };
+  if (new TextEncoder().encode(JSON.stringify(envelope)).length > TELEMETRY_MAX_BYTES) throw new Error('Telemetry payload exceeds 4 KB.');
+  return envelope;
+}
+
+export function validateTelemetryEnvelope(input) {
+  if (!input || Array.isArray(input) || typeof input !== 'object') throw new Error('Telemetry payload must be an object.');
+  const allowed = new Set(['schemaVersion', 'skillVersion', 'installationId', 'token', 'event', 'properties']);
+  for (const key of Object.keys(input)) if (!allowed.has(key)) throw new Error(`Unknown telemetry envelope property: ${key}.`);
+  if (input.schemaVersion !== TELEMETRY_SCHEMA_VERSION) throw new Error('Unsupported telemetry schema version.');
+  return createTelemetryEnvelope(input);
+}