openings 0.1.35 → 0.1.36

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "openings",
-  "version": "0.1.35",
+  "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.35",
+  "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/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.",

package/src/tools.ts

@@ -106,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: {
@@ -114,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,
       },
@@ -148,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");
@@ -162,10 +168,13 @@ 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") {

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.35";
+export const VERSION = "0.1.36";