openings 0.1.33 → 0.1.35

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "openings",
-  "version": "0.1.33",
+  "version": "0.1.35",
   "description": "Find evidence-grounded jobs, including relevant roles you may not have searched for, without accounts or API keys.",
   "author": { "name": "Openings contributors" },
   "license": "MIT",

package/README.md

@@ -2,7 +2,18 @@
 
 A free, candidate-safe job search for AI agents.
 
-Openings indexes public company job boards into a private index on your machine and exposes it to any MCP client. Your agent can find roles that fit a resume, explain the fit with evidence, and propose truthful resume improvements. There are no accounts, no API keys, no model calls, and no way to submit an application.
+Openings indexes public company job boards into a private index on your machine and exposes it to any MCP client. Your agent can find roles that fit a resume, explain the fit with evidence, and propose truthful resume improvements. Installed this way there are no accounts and no API keys; there are never model calls and never a way to submit an application.
+
+Two ways to run it, with different data rules:
+
+| | On your machine (this package) | Hosted connector at `openings.avagama.co/mcp` |
+|---|---|---|
+| Sign-in | None | Email code, so an account exists |
+| Job index | Built and stored on your machine | Ours, shared |
+| Resume | Parsed in memory for one request, never written to disk | Sent to our server, processed in memory for that request, then discarded |
+| What we receive | Crawl reports, plus anonymous usage events unless you turn them off | The same usage record, keyed to your account |
+
+Both are covered in [Sharing crawls and usage](#sharing-crawls-and-usage) and on the [privacy page](https://avagama.co/privacy/).
 
 - **Eleven providers plus company sites.** Greenhouse, Lever, Ashby, Workday, Recruitee, SmartRecruiters, Workable, Breezy, Freshteam, Keka, and Zoho Recruit, crawled from their public structured endpoints, plus employer career sites read only through the schema.org JobPosting markup they publish for search engines. No free-form HTML scraping.
 - **Verified sources only.** Every company in the catalog passed an identity check against its own board.
@@ -99,7 +110,11 @@ On startup the server makes one request to the npm registry to learn the latest
 
 ## Privacy
 
-Job data comes straight from public ATS endpoints and is stored only on your machine. Your MCP client reads the resume file and passes its content to a tool; Openings never sees the path and never persists the content or anything derived from it. Every proposed change stays subject to your review.
+Job data comes straight from public ATS endpoints and is stored only on your machine. Your MCP client reads the resume file and passes its content to a tool; Openings never sees the path, and it never writes the resume to disk, logs it, or sends it anywhere.
+
+One thing derived from a resume does leave your machine while usage reporting is on, which is the default: the skill and title words the parser extracted, in the anonymous event described in [Sharing crawls and usage](#sharing-crawls-and-usage). Never the resume text, the quoted evidence, your name, or your contact details. `OPENINGS_USAGE=off` stops it, and an empty `OPENINGS_AGGREGATOR_URL` keeps everything local.
+
+Every proposed change stays subject to your review.
 
 ## Develop
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openings",
-  "version": "0.1.33",
+  "version": "0.1.35",
   "description": "A free, candidate-safe job-search substrate for AI agents",
   "license": "MIT",
   "repository": { "type": "git", "url": "git+https://github.com/abhay-avagama/hiring-agent.git" },

package/src/candidate-profile.ts

@@ -36,6 +36,14 @@ export class ResumeInputError extends Error {
   ) { super(message); }
 }
 
+/** A PDF or DOCX pasted as text: a file signature, or control characters no resume contains. */
+function looksBinary(content: string): boolean {
+  const head = content.slice(0, 2048);
+  if (/^%PDF-|^PK\u0003\u0004|^\{\\rtf/.test(content.trimStart())) return true;
+  const control = head.match(/[\u0000-\u0008\u000e-\u001f]/g)?.length ?? 0;
+  return control > 0 && control / Math.max(head.length, 1) > 0.01;
+}
+
 export function parseCandidateProfile(input: unknown): CandidateProfile {
   if (!isRecord(input) || typeof input.format !== "string" || typeof input.content !== "string") {
     throw new ResumeInputError("invalid_resume_input", "Resume must contain text or Markdown content");
@@ -43,6 +51,9 @@ export function parseCandidateProfile(input: unknown): CandidateProfile {
   if (input.format === "pdf_base64" || input.format === "docx_base64") {
     throw new ResumeInputError("unsupported_resume_format", `Resume format ${input.format} is not supported yet`, input.format, ["text", "markdown"]);
   }
+  if (looksBinary(input.content)) {
+    throw new ResumeInputError("invalid_resume_input", "That looks like a file's raw bytes, not resume text. Export the resume as text, or paste the text itself.");
+  }
   if (!(["text", "markdown"] as string[]).includes(input.format)) {
     throw new ResumeInputError("invalid_resume_input", "Resume must contain text or Markdown content");
   }

package/src/crawler.ts

@@ -30,7 +30,7 @@ interface CrawlerOptions {
 }
 
 export interface Crawler {
-  crawl(sources: Company[], settings?: { prune?: boolean }): Promise<CrawlReport>;
+  crawl(sources: Company[], settings?: { prune?: boolean; workdayCountries?: string[] }): Promise<CrawlReport>;
 }
 
 export function createCrawler(options: CrawlerOptions): Crawler {
@@ -124,7 +124,8 @@ export function createCrawler(options: CrawlerOptions): Crawler {
               const listed = await options.fetchJobs(source, controller.signal, {
                 onBackoff: ({ status, delayMs }) => { metric.backoffMs += delayMs; if (status === 429) metric.throttles += 1; },
                 workdayPageDelayMs: options.workdayPageDelayMs,
-                workdayCountries: options.workdayCountries,
+                // The countries this crawl asked for drive Workday's supplementary passes, not just the configured default.
+                workdayCountries: settings?.workdayCountries ?? options.workdayCountries,
               });
               const jobs = await withExperience(source, listed, partitionFor(partitions, source.slug)?.jobs);
               partitions[source.slug] = { fetchedAt: now().toISOString(), jobs };

package/src/job-recommendations.ts

@@ -211,7 +211,7 @@ function refreshReason(policy: RefreshPolicy, snapshot: JobSnapshot | null, matc
 }
 
 function refreshScope(intent: CandidateIntent, snapshot: JobSnapshot | null, sources: Company[]): CrawlScope {
-  return intent.countries?.length ? { slugs: relevantSourceSlugs(snapshot, intent, sources) } : {};
+  return intent.countries?.length ? { slugs: relevantSourceSlugs(snapshot, intent, sources), countries: intent.countries } : {};
 }
 
 function relevantSnapshot(snapshot: JobSnapshot, intent: CandidateIntent, sources: Company[]): JobSnapshot {

package/src/job-search-preparation.ts

@@ -38,7 +38,7 @@ export function createJobSearchPreparer(options: {
       }
       const pendingBefore = pendingSources(options.sources, snapshot, now(), freshnessMs);
       const selected = pendingBefore.filter((source) => !input.attempted.has(source.slug)).slice(0, batchSize).map((source) => source.slug);
-      const crawl = selected.length ? await options.crawl({ slugs: selected }) : undefined;
+      const crawl = selected.length ? await options.crawl({ slugs: selected, countries }) : undefined;
       if (crawl) snapshot = await options.store.read();
       if (!snapshot) throw new Error("Job search preparation did not produce a local snapshot");
 

package/src/local-jobs.ts

@@ -44,7 +44,10 @@ export function createLocalJobs(options: LocalJobsOptions) {
 
   async function crawl(scope: CrawlScope = {}): Promise<CrawlReport> {
     const selected = selectSources(options.sources, scope);
-    return crawler.crawl(selected, { prune: !scope.country && !scope.countries && !scope.slugs });
+    // Workday's country passes cover the countries this crawl is for, on top of the configured ones.
+    const asked = [...(scope.countries ?? []), ...(scope.country ? [scope.country] : [])].map((code) => code.toUpperCase());
+    const workdayCountries = asked.length ? [...new Set([...(options.workdayCountries ?? []), ...asked])] : undefined;
+    return crawler.crawl(selected, { prune: !scope.country && !scope.countries && !scope.slugs, ...(workdayCountries ? { workdayCountries } : {}) });
   }
 
   async function ensureFresh(offline: boolean, staleDays: number): Promise<{ snapshot: JobSnapshot; refreshed: boolean }> {

package/src/mcp.ts

@@ -48,11 +48,13 @@ export function createMcpHandler(tools: ToolHandler, options: { update?: () => U
         if (args !== undefined && !isRecord(args)) throw new Error("tools/call arguments must be an object");
         try {
           const result = await tools.call(name, args ?? {});
-          return { ...base, result: { content: [{ type: "text", text: JSON.stringify(withUpdate(result), null, 2) }], isError: false } };
+          const payload = withUpdate(result);
+          // Both shapes: text for models that read it, structuredContent for hosts that render it.
+          return { ...base, result: { content: [{ type: "text", text: JSON.stringify(payload, null, 2) }], structuredContent: payload, isError: false } };
         } catch (error) {
           const details = errorDetails(error);
-          const payload = { error: { message: error instanceof Error ? error.message : String(error), ...(details ?? {}) } };
-          return { ...base, result: { content: [{ type: "text", text: JSON.stringify(withUpdate(payload), null, 2) }], isError: true } };
+          const failure = withUpdate({ error: { message: error instanceof Error ? error.message : String(error), ...(details ?? {}) } });
+          return { ...base, result: { content: [{ type: "text", text: JSON.stringify(failure, null, 2) }], structuredContent: failure, isError: true } };
         }
       }
       if (request.method.startsWith("notifications/")) return null;

package/src/runtime.ts

@@ -1,6 +1,6 @@
 import { join } from "node:path";
 import type { SnapshotStore } from "./crawler.ts";
-import type { Company, SearchQuery } from "./types.ts";
+import type { Company, Job, SearchQuery } from "./types.ts";
 import { fetchJobDescription, fetchSourceJobs } from "./catalog.ts";
 import { createCrawlReporter, fetchSeedSnapshot, resolveAggregatorUrl } from "./crawl-reporting.ts";
 import { createUsageReporter, type UsageReporter } from "./usage.ts";
@@ -74,12 +74,24 @@ export function createHostedRuntime(options: { sources: Company[]; store: Snapsh
   const recommender = createJobRecommender({ sources: options.sources, store: options.store, crawl: noCrawl, now: options.now });
   const coverage = createJobCoverageReader({ sources: options.sources, store: options.store });
   const preparation = createJobSearchPreparer({ sources: options.sources, store: options.store, crawl: noCrawl, now: options.now, freshnessDays: 3650 });
-  const getSelectedJob = createSelectedJobLookup({ getSnapshotJob: async (id) => (await local.get(id, { offline: true, staleDays: 3650 })).job, getDetailedJob: async () => null });
+  // Workday and a few other boards keep descriptions off their listings, so the shared index has none: read one on demand.
+  async function withDescription(job: Job | null): Promise<Job | null> {
+    if (!job || job.description.trim()) return job;
+    const [ats, slug] = job.id.split(":", 3);
+    const company = options.sources.find((source) => source.ats === ats && source.slug === slug);
+    if (!company) return job;
+    try {
+      const description = await fetchJobDescription(company, job, globalThis.fetch);
+      return description.trim() ? { ...job, description } : job;
+    } catch { return job; } // the employer's board is unreachable; the summary is still useful
+  }
+  const snapshotJob = async (id: string) => (await local.get(id, { offline: true, staleDays: 3650 })).job;
+  const getSelectedJob = createSelectedJobLookup({ getSnapshotJob: snapshotJob, getDetailedJob: async (id) => withDescription(await snapshotJob(id)) });
   const analyzer = createJobFitAnalyzer({ getJob: getSelectedJob });
   const optimizer = createResumeOptimizer({ analyzeJobFit: analyzer.analyze });
   return {
     search: (query: SearchQuery) => local.search(query, { offline: true, staleDays: 3650 }),
-    get: (id: string) => local.get(id, { offline: true, staleDays: 3650 }),
+    get: async (id: string) => { const found = await local.get(id, { offline: true, staleDays: 3650 }); return { ...found, job: await withDescription(found.job) }; },
     prepareJobSearch: preparation.prepare, getJobCoverage: coverage.getCoverage, recommend: recommender.recommend, analyzeJobFit: analyzer.analyze, optimizeResume: optimizer.optimize,
   };
 }

package/src/tools.ts

@@ -11,8 +11,14 @@ export interface ToolDefinition {
   name: "prepare_job_search" | "get_job_coverage" | "recommend_jobs" | "analyze_job_fit" | "optimize_resume" | "search_jobs" | "get_job";
   description: string;
   inputSchema: Record<string, unknown>;
+  /** Every tool only reads: nothing here applies, submits, or writes on the candidate's behalf. */
+  annotations: { readOnlyHint: true; destructiveHint: false; idempotentHint: true; openWorldHint: boolean };
 }
 
+/** Tools that reach employer boards over the network are open-world; the rest read the local index. */
+const annotationsFor = (name: ToolDefinition["name"]): ToolDefinition["annotations"] =>
+  ({ readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: name === "prepare_job_search" || name === "recommend_jobs" || name === "get_job" });
+
 interface JobWorkflows {
   prepareJobSearch(input: unknown): Promise<PrepareJobSearchResult>;
   getJobCoverage(input: unknown): Promise<JobCoverageSummary>;
@@ -22,7 +28,7 @@ interface JobWorkflows {
 }
 
 export function createToolHandler(catalog: Catalog, workflows: JobWorkflows, options: { onCall?(name: string, input: Record<string, unknown>, result: unknown): void } = {}) {
-  const definitions: ToolDefinition[] = [
+  const definitions: Array<Omit<ToolDefinition, "annotations">> = [
     {
       name: "prepare_job_search",
       description: "Initialize the local job index: the first call downloads the shared index of every verified source (thousands of employers) and returns ready; only missing or stale sources are crawled, in batches of at most 25. Report coverage from the result rather than calling again once nextAction is ready. This may use the network and write only job data under the local Openings data directory; it never processes a resume.",
@@ -119,7 +125,7 @@ export function createToolHandler(catalog: Catalog, workflows: JobWorkflows, opt
       description: "Get the full description and application URL for a job returned by recommend_jobs or search_jobs.",
       inputSchema: {
         type: "object",
-        properties: { id: { type: "string", description: "Stable job id returned by search_jobs" } },
+        properties: { id: { type: "string", description: "Stable job id returned by search_jobs or recommend_jobs (jobId is accepted too)" } },
         required: ["id"],
         additionalProperties: false,
       },
@@ -127,7 +133,7 @@ export function createToolHandler(catalog: Catalog, workflows: JobWorkflows, opt
   ];
 
   return {
-    list: () => definitions,
+    list: () => definitions.map((definition) => ({ ...definition, annotations: annotationsFor(definition.name) })),
     async call(name: string, input: Record<string, unknown>) {
       const result = await dispatch(name, input);
       try { options.onCall?.(name, input, result); } catch { /* usage reporting never affects a tool result */ }
@@ -163,9 +169,11 @@ export function createToolHandler(catalog: Catalog, workflows: JobWorkflows, opt
         };
       }
       if (name === "get_job") {
-        assertToolKeys(input, ["id"], "get_job");
-        if (typeof input.id !== "string" || !input.id) throw new Error("get_job requires a non-empty id");
-        return { job: await catalog.get(input.id) };
+        // analyze_job_fit and optimize_resume call it jobId, so accept either spelling rather than fail on a near miss.
+        assertToolKeys(input, ["id", "jobId"], "get_job");
+        const id = typeof input.id === "string" && input.id ? input.id : input.jobId;
+        if (typeof id !== "string" || !id) throw new Error("get_job requires a non-empty id");
+        return { job: await catalog.get(id) };
       }
       throw new Error(`Unknown tool: ${name}`);
   }

package/src/version.ts

@@ -1 +1 @@
-export const VERSION = "0.1.33";
+export const VERSION = "0.1.35";