openings 0.1.34 → 0.1.36

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "openings",
-  "version": "0.1.34",
+  "version": "0.1.36",
   "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

@@ -61,7 +61,7 @@ The [job-seeker quickstart](docs/job-seeker-quickstart.md) has sample prompts, a
 | `recommend_jobs` | Ranks jobs against a resume and explicit intent. Returns direct, hidden, and stretch results with evidence. Performs at most one scoped refresh; `refresh.policy: "never"` guarantees no crawl. |
 | `analyze_job_fit` | Explains one job against verbatim resume evidence: supported, transferable, unsupported, and screening risks. |
 | `optimize_resume` | Proposes grounded suggestions, an additive diff, or revised Markdown. Never invents experience. |
-| `search_jobs` | Plain keyword, location, country, and remote search over the index, newest first. `country` takes a two-letter code such as `IN`; `maxAgeDays` keeps only roles posted within that window. |
+| `search_jobs` | Resume-free keyword, location, country, remote, and stated-experience search, newest first. `country` takes a two-letter code such as `IN`. Optional `experienceYears` compares stated min/max ranges, excluding unknowns unless `includeUnknownExperience: true`. Results include `pagination.total` and `pagination.nextOffset`; request the next page with that `offset`, unchanged filters, and `maxAgeDays` set to the returned `window.daysUsed`. Restart pagination after index refresh; this is not a frozen snapshot cursor. Without `maxAgeDays`, search widens through 7/14/30/all days until at least five results exist. |
 | `get_job` | Returns one job with its full description. |
 
 There is deliberately no form-fill, apply, or submit tool. The only thing Openings writes is your own job index.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openings",
-  "version": "0.1.34",
+  "version": "0.1.36",
   "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/skills/openings/SKILL.md

@@ -12,8 +12,8 @@ Use `prepare_job_search` to bootstrap the private local index and set honest cou
 ## Search
 
 1. Ask for the target countries and call `prepare_job_search` before requesting a resume. Explain that first-time setup runs in resumable batches and uses the network only to build a private local job index. While `nextAction` is `call_again`, call the tool again with the same countries and the returned opaque `continuation`; do not ask for a resume between batches. On `retry_later`, disclose failures and offer to continue with the indexed coverage or retry later without the old continuation. On `ready`, present its job-level source, job, and employer counts exactly as returned; never substitute discovery-cohort counts or recalculate coverage.
-2. Ask only for missing constraints that materially change the recommendation.
-3. Supply the user's resume content, explicit intent, and their chosen `ranking.mode` (`evidence` by default or `keyword`) to `recommend_jobs`; never pass an arbitrary filesystem path. Use `ranking.minimumPercent` only when the user requests a cutoff.
+2. Ask only for missing constraints that materially change the search. Search immediately with `search_jobs` when role and country are known; do not require or repeatedly request a resume. Use `experienceYears` only when supplied, explain that it compares stated posting ranges, and offer `includeUnknownExperience` when strict results are thin. Unknown experience is not proof of fit or a gap. To show another page, keep the filters, set `maxAgeDays` to the returned `window.daysUsed`, and use `pagination.nextOffset`; restart after an index refresh.
+3. Offer resume matching as optional. When the user chooses it, supply their resume content, explicit intent, and their chosen `ranking.mode` (`evidence` by default or `keyword`) to `recommend_jobs`; never pass an arbitrary filesystem path. Use `ranking.minimumPercent` only when the user requests a cutoff.
 4. Present the returned coverage summary alongside the recommendations without recalculating it.
 5. Present direct, hidden title-family, and stretch results separately. For a hidden result, quote the returned title expansions and whether each came from explicit intent or validated resume fact IDs; never invent or broaden an alias in the skill.
 6. Present both returned percentages, the selected score, assumptions, evidence, gaps, refresh status, and failures without recalculating fit. Never describe keyword overlap as demonstrated competence.

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/catalog.ts

@@ -2,6 +2,7 @@ import { CASCADE_MINIMUM, CASCADE_WINDOWS, type Company, type Job, type JobAge,
 import { decodeEntities, providerSpec, type JsonGet } from "./providers.ts";
 import { crawlSite, sitePostingsToJobs } from "./jobposting-site.ts";
 import { classifyJob, isEligibleForCountry, normalizeLocation } from "./locations.ts";
+import { statedExperience } from "./experience.ts";
 
 type Fetch = (input: string | URL, init?: RequestInit) => Promise<Response>;
 
@@ -107,7 +108,7 @@ export function createCatalog(options: CatalogOptions): Catalog {
 }
 
 export const DEFAULT_MAX_AGE_DAYS = 30;
-export type SearchResult = JobSummary[] & { window?: SearchWindow };
+export type SearchResult = JobSummary[] & { window?: SearchWindow; pagination?: { offset: number; limit: number; total: number; nextOffset: number | null } };
 
 /** One window: dated jobs inside it; 0 means everything including undated. */
 export function withinWindow(job: Pick<Job, "updatedAt">, days: number, now: number): boolean {
@@ -118,8 +119,12 @@ export function withinWindow(job: Pick<Job, "updatedAt">, days: number, now: num
 
 /** Keyword search newest first. Without maxAgeDays it walks 7, 14, 30, then everything until CASCADE_MINIMUM results appear; the window used rides on the result. */
 export function searchJobs(jobs: Job[], query: SearchQuery, now: number = Date.now()): SearchResult {
-  const matched = jobs.filter((job) => matches(job, query));
-  const run = (days: number) => matched.filter((job) => withinWindow(job, days, now)).sort((left, right) => postedTime(right) - postedTime(left));
+  const matched = jobs.filter((job) => matches(job, query)).filter((job) => {
+    if (query.experienceYears === undefined) return true;
+    const experience = job.experience === undefined ? statedExperience(job.description) : job.experience;
+    return experience ? query.experienceYears >= experience.min && (experience.max === undefined || query.experienceYears <= experience.max) : query.includeUnknownExperience === true;
+  });
+  const run = (days: number) => matched.filter((job) => withinWindow(job, days, now)).sort((left, right) => postedTime(right) - postedTime(left) || (left.id < right.id ? -1 : left.id > right.id ? 1 : 0));
   const steps: SearchWindow["steps"] = [];
   let found: Job[] = [];
   for (const days of query.maxAgeDays !== undefined ? [query.maxAgeDays] : CASCADE_WINDOWS) {
@@ -127,7 +132,9 @@ export function searchJobs(jobs: Job[], query: SearchQuery, now: number = Date.n
     steps.push({ days, results: found.length });
     if (found.length >= CASCADE_MINIMUM) break;
   }
-  const result = found.slice(0, query.limit ?? 50).map((job) => toSummary(job, now)) as SearchResult;
+  const offset = query.offset ?? 0, limit = query.limit ?? 50;
+  const result = found.slice(offset, offset + limit).map((job) => toSummary(query.experienceYears !== undefined && job.experience === undefined ? { ...job, experience: statedExperience(job.description) } : job, now)) as SearchResult;
+  Object.defineProperty(result, "pagination", { value: { offset, limit, total: found.length, nextOffset: offset + limit < found.length ? offset + limit : null }, enumerable: false });
   Object.defineProperty(result, "window", { value: { daysUsed: steps[steps.length - 1]!.days, widened: steps.length > 1, steps } satisfies SearchWindow, enumerable: false });
   return result;
 }

package/src/mcp.ts

@@ -19,7 +19,7 @@ interface ToolHandler {
 
 /** Read by the AI app before its first call: the order of operations that keeps results honest. */
 export const FLOW_INSTRUCTIONS = [
-  "Openings flow: 1) call prepare_job_search for the person's countries; it is normally ready in one call. 2) Ask for the resume before exploring roles, because recommend_jobs ranks by evidence from it. 3) If the person declines a resume, use search_jobs with their keywords. 4) If they decline that too, use your judgement.",
+  "Openings flow: ask only for missing search constraints, such as role and country. Call prepare_job_search when setup is needed, then search_jobs immediately; a resume is optional, never a prerequisite to explore jobs. Offer recommend_jobs when the person wants evidence-based matching and chooses to share a resume. Follow preparation.nextAction rather than assuming setup succeeded.",
   "Freshness: results start with roles posted in the last 7 days and widen to 14, 30, then everything only when fewer than 5 appear; each result carries age (new, older, stale, undated) and postedDaysAgo. Say which window results came from and present older or stale roles as possibly still open, never as current.",
   "Experience: a job's experience field is the years its posting states ({ min, max }); null means the posting states none, and absent means it was not read. Quote it as the employer's requirement.",
   "Every match carries applyUrl, the employer's own posting; include it. When recommend_jobs reports no_matches, relay its explanation and nextMoves instead of searching silently.",
@@ -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.",
@@ -100,7 +106,7 @@ export function createToolHandler(catalog: Catalog, workflows: JobWorkflows, opt
     },
     {
       name: "search_jobs",
-      description: "Plain keyword search over the local job index, newest first, walking 7, 14, 30 days then everything until 5 results appear; the window used is returned. Use only when the person declines to share a resume or asks for a plain search; recommend_jobs ranks against a resume.",
+      description: "Search jobs immediately from role, country, location and optional stated experience. No resume required. Newest first; automatically widens 7, 14, 30 days then all dates until 5 matches. For another page reuse the same filters and returned window.daysUsed as maxAgeDays, with pagination.nextOffset. Resume-based ranking is optional via recommend_jobs.",
       inputSchema: {
         type: "object",
         properties: {
@@ -108,8 +114,11 @@ export function createToolHandler(catalog: Catalog, workflows: JobWorkflows, opt
           location: { type: "string", description: "Case-insensitive location substring" },
           country: { type: "string", pattern: "^[A-Za-z]{2}$", description: "Two-letter country code for job eligibility, such as IN or DE" },
           remote: { type: "boolean", description: "True for remote-only; false for non-remote-only" },
-          maxAgeDays: { type: "integer", minimum: 0, maximum: 365, description: "Only roles posted within this many days, newest first. Default 30 (undated roles kept, listed last); an explicit value also drops undated roles; 0 includes older roles" },
+          maxAgeDays: { type: "integer", minimum: 0, maximum: 365, description: "Omit to widen 7/14/30/all until 5 matches. Explicit positive values exclude undated roles; 0 includes all dates." },
           limit: { type: "integer", minimum: 1, maximum: 100, default: 50 },
+          offset: { type: "integer", minimum: 0, maximum: 1000000, default: 0 },
+          experienceYears: { type: "number", minimum: 0, maximum: 60, description: "Years of experience to compare with the posting's stated min/max range; not a qualification or fit verdict." },
+          includeUnknownExperience: { type: "boolean", default: false, description: "With experienceYears, also keep roles without a stated range, clearly unknown rather than matched." },
         },
         additionalProperties: false,
       },
@@ -119,7 +128,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 +136,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 */ }
@@ -142,7 +151,10 @@ export function createToolHandler(catalog: Catalog, workflows: JobWorkflows, opt
       if (name === "analyze_job_fit") return workflows.analyzeJobFit(input);
       if (name === "optimize_resume") return workflows.optimizeResume(input);
       if (name === "search_jobs") {
-        assertToolKeys(input, ["query", "location", "country", "remote", "maxAgeDays", "limit"], "search_jobs");
+        assertToolKeys(input, ["query", "location", "country", "remote", "maxAgeDays", "limit", "offset", "experienceYears", "includeUnknownExperience"], "search_jobs");
+        if (input.offset !== undefined && (!Number.isInteger(input.offset) || (input.offset as number) < 0 || (input.offset as number) > 1000000)) throw new Error("offset must be an integer between 0 and 1000000");
+        if (input.experienceYears !== undefined && (typeof input.experienceYears !== "number" || !Number.isFinite(input.experienceYears) || input.experienceYears < 0 || input.experienceYears > 60)) throw new Error("experienceYears must be a number between 0 and 60");
+        if (input.includeUnknownExperience !== undefined && typeof input.includeUnknownExperience !== "boolean") throw new Error("includeUnknownExperience must be a boolean");
         if (input.query !== undefined && typeof input.query !== "string") throw new Error("query must be a string");
         if (input.location !== undefined && typeof input.location !== "string") throw new Error("location must be a string");
         if (input.remote !== undefined && typeof input.remote !== "boolean") throw new Error("remote must be a boolean");
@@ -156,16 +168,21 @@ export function createToolHandler(catalog: Catalog, workflows: JobWorkflows, opt
         if (typeof input.remote === "boolean") query.remote = input.remote;
         if (typeof input.maxAgeDays === "number") query.maxAgeDays = input.maxAgeDays;
         if (typeof input.limit === "number") query.limit = input.limit;
+        if (typeof input.offset === "number") query.offset = input.offset;
+        if (typeof input.experienceYears === "number") query.experienceYears = input.experienceYears;
+        if (typeof input.includeUnknownExperience === "boolean") query.includeUnknownExperience = input.includeUnknownExperience;
         const jobs = await catalog.search(query) as SearchResult;
         return {
-          jobs, window: jobs.window,
-          guidance: "Unranked keyword matches. Present roles labelled older or stale as possibly still open, not as current. With a resume, recommend_jobs ranks roles by evidence and explains fit.",
+          jobs, window: jobs.window, pagination: jobs.pagination,
+          guidance: "Unranked keyword matches. Experience filters compare stated ranges only; unknown experience is not a match or a gap. Present older/stale roles as possibly still open, not current. Reuse window.daysUsed as maxAgeDays and pagination.nextOffset with unchanged filters for the next page. Pagination is over the current index, not a frozen snapshot; restart if the index refreshes. Resume-based matching is optional.",
         };
       }
       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/types.ts

@@ -116,6 +116,11 @@ export interface SearchQuery {
   /** Only jobs posted within this many days. Unset walks 7, 14, 30, then everything until 5 results appear; an explicit value is a single window that drops undated jobs; 0 includes everything. */
   maxAgeDays?: number;
   limit?: number;
+  /** Zero-based offset within the chosen date window; restart when the index changes. */
+  offset?: number;
+  /** Match stated experience ranges, not inferred seniority or a hiring guarantee. */
+  experienceYears?: number;
+  includeUnknownExperience?: boolean;
 }
 
 export interface CrawlFailure {

package/src/version.ts

@@ -1 +1 @@
-export const VERSION = "0.1.34";
+export const VERSION = "0.1.36";