openings 0.1.13 → 0.1.15

package/.codex-plugin/plugin.json

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

@@ -50,7 +50,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. `country` takes a two-letter code such as `IN`. |
+| `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. |
 | `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.13",
+  "version": "0.1.15",
   "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/catalog.ts

@@ -20,6 +20,7 @@ interface GreenhouseJob {
   title: string;
   location: { name: string };
   absolute_url: string;
+  first_published?: string;
   updated_at?: string;
   content?: string;
 }
@@ -109,8 +110,18 @@ export function createCatalog(options: CatalogOptions): Catalog {
   };
 }
 
-export function searchJobs(jobs: Job[], query: SearchQuery): JobSummary[] {
-  return jobs.filter((job) => matches(job, query)).slice(0, query.limit ?? 50).map(toSummary);
+export function searchJobs(jobs: Job[], query: SearchQuery, now: number = Date.now()): JobSummary[] {
+  const since = query.maxAgeDays ? now - query.maxAgeDays * 86_400_000 : undefined;
+  return jobs
+    .filter((job) => matches(job, query) && (since === undefined || postedTime(job) >= since))
+    .sort((left, right) => postedTime(right) - postedTime(left))
+    .slice(0, query.limit ?? 50).map(toSummary);
+}
+
+/** Posting time in ms for sorting; undated jobs sort last. */
+export function postedTime(job: Pick<Job, "updatedAt">): number {
+  const time = job.updatedAt ? Date.parse(job.updatedAt) : Number.NaN;
+  return Number.isFinite(time) ? time : 0;
 }
 
 export interface FetchJobsObserver {
@@ -293,10 +304,22 @@ function normalizeWorkday(company: Company, source: ReturnType<typeof parseWorkd
     workMode: /remote/i.test(location) ? "remote" : "unknown",
     eligibleCountries: [], excludedCountries: [], eligibleRegions: [], eligibilityConfidence: "unknown",
     url: `https://${source.host}/en-US/${source.site}${job.externalPath}`,
+    ...(workdayPostedAt(job.postedOn) ? { updatedAt: workdayPostedAt(job.postedOn) } : {}),
     description: "",
   });
 }
 
+/** Workday lists only a relative label ("Posted Today", "Posted 3 Days Ago", "Posted 30+ Days Ago"); turn it into an approximate posting date. */
+export function workdayPostedAt(label: string | undefined, now: number = Date.now()): string | undefined {
+  const text = label?.trim().toLowerCase() ?? "";
+  let days: number | undefined;
+  if (/\btoday\b/.test(text)) days = 0;
+  else if (/\byesterday\b/.test(text)) days = 1;
+  else { const match = /(\d+)\+?\s*days?\s*ago/.exec(text); if (match) days = Number(match[1]) + (text.includes("+") ? 1 : 0); }
+  if (days === undefined) return undefined;
+  return new Date(now - days * 86_400_000).toISOString().slice(0, 10);
+}
+
 async function fetchWorkdayDescription(company: Company, jobUrl: string, fetcher: Fetch): Promise<string> {
   const source = parseWorkdayToken(company.token);
   const path = new URL(jobUrl).pathname.replace(new RegExp(`^/en-US/${escapeRegExp(source.site)}`), "");
@@ -367,7 +390,7 @@ function normalizeGreenhouse(company: Company, job: GreenhouseJob): Job {
     eligibleRegions: [],
     eligibilityConfidence: "unknown",
     url: job.absolute_url,
-    updatedAt: job.updated_at,
+    updatedAt: job.first_published ?? job.updated_at,
     description: stripHtml(job.content ?? ""),
   });
 }
@@ -376,7 +399,7 @@ function normalizeRecruitee(company: Company, job: RecruiteeJob): Job {
   const location = [job.city, job.state_name, job.country_code?.toUpperCase()].filter(Boolean).join(", ") || "Unspecified";
   const translation = job.translations?.en ?? Object.values(job.translations ?? {})[0];
   const description = [translation?.description ?? job.description, translation?.requirements ?? job.requirements].filter(Boolean).map((value) => stripHtml(value!)).join("\n\n");
-  const updatedAt = job.updated_at ?? job.published_at;
+  const updatedAt = job.published_at ?? job.updated_at;
   return classifyJob({
     id: `recruitee:${company.slug}:${job.guid}`,
     company: company.name,

package/src/cli.ts

@@ -22,7 +22,7 @@ import { mergeAttemptedRoundLeads, prepareRecruiteeRoundArtifacts } from "./recr
 const HELP = `Openings — search public company job boards
 
 Usage:
-  openings crawl [--workday-countries IN,US] [--country CODE | --companies FILE] [--concurrency N] [--source-cache-hours N] [--source-limit N] [--delay-ms N] [--workday-page-delay-ms N] [--data-dir PATH]
+  openings crawl [--workday-countries IN,US] [--country CODE | --companies FILE] [--concurrency N] [--source-cache-hours N] [--source-limit N] [--delay-ms N] [--workday-page-delay-ms N] [--timeout-ms N] [--data-dir PATH]
   openings snapshot export [--input FILE] [--output-dir PATH]
   openings coverage report --country CODE [--snapshot FILE] [--catalog FILE] [--candidates FILE] [--registry FILE] [--output FILE] [--as-of ISO]
   openings sources discover-subdomains SEEDS.json [--output FILE] [--limit N] [--delay-ms N] [--report FILE]
@@ -69,7 +69,7 @@ export async function run(args: string[]): Promise<number> {
     if (typeof parsed === "string") return fail(parsed);
     const runtime = createRuntime({
       dataDir: parsed.dataDir, concurrency: parsed.concurrency, sourceCacheHours: parsed.sourceCacheHours,
-      sourceLimit: parsed.sourceLimit, crawlDelayMs: parsed.delayMs, workdayPageDelayMs: parsed.workdayPageDelayMs, workdayCountries: parsed.workdayCountries,
+      sourceLimit: parsed.sourceLimit, crawlDelayMs: parsed.delayMs, workdayPageDelayMs: parsed.workdayPageDelayMs, workdayCountries: parsed.workdayCountries, timeoutMs: parsed.timeoutMs,
     });
     const slugs = parsed.companiesFile ? await readCompanyFile(parsed.companiesFile) : undefined;
     console.log(JSON.stringify(await runtime.crawl({ country: parsed.country, slugs }), null, 2));
@@ -514,6 +514,7 @@ function parseCrawl(args: string[]) {
   let concurrency = 10;
   let delayMs = 0;
   let workdayPageDelayMs = 0;
+  let timeoutMs: number | undefined;
   let workdayCountries: string[] | undefined;
   let sourceCacheHours = 24;
   let sourceLimit = 0;
@@ -537,6 +538,9 @@ function parseCrawl(args: string[]) {
     } else if (arg === "--workday-page-delay-ms") {
       workdayPageDelayMs = Number(args[++index]);
       if (!Number.isInteger(workdayPageDelayMs) || workdayPageDelayMs < 0 || workdayPageDelayMs > 60_000) return "--workday-page-delay-ms must be an integer from 0 to 60000";
+    } else if (arg === "--timeout-ms") {
+      timeoutMs = Number(args[++index]);
+      if (!Number.isInteger(timeoutMs) || timeoutMs < 1000 || timeoutMs > 1_800_000) return "--timeout-ms must be an integer from 1000 to 1800000";
     } else if (arg === "--source-cache-hours") {
       sourceCacheHours = Number(args[++index]);
       if (!Number.isFinite(sourceCacheHours) || sourceCacheHours < 0 || sourceCacheHours > 8760) return "--source-cache-hours must be a number from 0 to 8760";
@@ -548,7 +552,7 @@ function parseCrawl(args: string[]) {
   if (country && companiesFile) return "Use either --country or --companies, not both";
   if (args.includes("--companies") && !companiesFile) return "--companies requires a file";
   if (args.includes("--data-dir") && !dataDir) return "--data-dir requires a value";
-  return { country, companiesFile, dataDir, concurrency, delayMs, workdayPageDelayMs, sourceCacheHours, sourceLimit , workdayCountries };
+  return { country, companiesFile, dataDir, concurrency, delayMs, workdayPageDelayMs, sourceCacheHours, sourceLimit, workdayCountries, timeoutMs };
 }
 
 function parseCountry(value: string | undefined): string | undefined {

package/src/intent-validation.ts

@@ -6,7 +6,7 @@ const arrayFields = ["roles", "countries", "locations", "seniority", "requiredSk
 export function validateCandidateIntent(value: unknown, invalid: InvalidInput, options: { optional?: boolean } = {}): CandidateIntent {
   if (value === undefined && options.optional) return {};
   if (!isRecord(value)) throw invalid("intent", "Candidate intent must be an object");
-  assertKnownKeys(value, [...arrayFields, "remote"], "intent", invalid);
+  assertKnownKeys(value, [...arrayFields, "remote", "maxAgeDays"], "intent", invalid);
   for (const field of arrayFields) {
     const candidate = value[field];
     if (candidate !== undefined && (!Array.isArray(candidate) || !candidate.every((item) => typeof item === "string" && item.trim().length > 0))) throw invalid(`intent.${field}`, `${field} must be an array of non-empty strings`);
@@ -17,6 +17,7 @@ export function validateCandidateIntent(value: unknown, invalid: InvalidInput, o
     if (Array.isArray(countries) && !countries.every((country) => typeof country === "string" && /^[A-Za-z]{2}$/.test(country))) throw invalid(`intent.${field}`, `${field} must contain two-letter country codes`);
   }
   if (value.remote !== undefined && typeof value.remote !== "boolean") throw invalid("intent.remote", "remote must be a boolean");
+  if (value.maxAgeDays !== undefined && (!Number.isInteger(value.maxAgeDays) || (value.maxAgeDays as number) < 1 || (value.maxAgeDays as number) > 365)) throw invalid("intent.maxAgeDays", "maxAgeDays must be an integer between 1 and 365");
   return value as unknown as CandidateIntent;
 }
 

package/src/job-matching.ts

@@ -2,6 +2,7 @@ import { validateCandidateProfileEvidence, type CandidateProfile } from "./candi
 import { isEligibleForCountry, normalizeLocation } from "./locations.ts";
 import { detectRequirementTerms, findTransferability, matchesExactSkillEvidence, requiresExactSkillEvidence, type TransferabilityKind } from "./requirement-vocabulary.ts";
 import type { Job } from "./types.ts";
+import { postedTime } from "./catalog.ts";
 import { evaluateScreeningRequirements, type ScreeningRequirement } from "./screening-requirements.ts";
 
 export interface CandidateIntent {
@@ -15,6 +16,8 @@ export interface CandidateIntent {
   excludedCountries?: string[];
   excludedLocations?: string[];
   excludedRoles?: string[];
+  /** Only roles posted within this many days; undated roles are dropped when set. */
+  maxAgeDays?: number;
 }
 
 export interface SupportedRequirement {
@@ -226,6 +229,7 @@ function hardFilterReasons(job: Job, intent: CandidateIntent): string[] {
   if (intent.locations?.length && !intent.locations.some((location) => normalizeLocation(job.location).includes(normalizeLocation(location)))) reasons.push("location_mismatch");
   for (const location of intent.excludedLocations ?? []) if (normalizeLocation(job.location).includes(normalizeLocation(location))) reasons.push(`location_excluded:${location}`);
   for (const role of intent.excludedRoles ?? []) if (includesPhrase(job.title, role) || tokenOverlap(role, job.title) === 1) reasons.push(`role_excluded:${role}`);
+  if (intent.maxAgeDays && postedTime(job) < Date.now() - intent.maxAgeDays * 86_400_000) reasons.push(`posted_too_old:${intent.maxAgeDays}d`);
   if (intent.remote === true && job.workMode !== "remote") reasons.push("remote_required");
   if (intent.remote === false && (job.workMode === "remote" || job.workMode === "unknown")) reasons.push("non_remote_required");
   const searchable = `${job.title}\n${job.company}\n${job.location}\n${job.description}`;
@@ -439,7 +443,4 @@ function tokenOverlap(left: string, right: string): number {
   return [...leftTokens].filter((token) => rightTokens.has(token)).length / leftTokens.size;
 }
 
-function freshness(job: Job): number {
-  const timestamp = job.updatedAt ? Date.parse(job.updatedAt) : Number.NaN;
-  return Number.isFinite(timestamp) ? timestamp : 0;
-}
+const freshness = postedTime;

package/src/runtime.ts

@@ -13,7 +13,7 @@ import { createFileSnapshotStore } from "./snapshot-store.ts";
 import { createJobCoverageReader } from "./job-coverage.ts";
 import { createJobSearchPreparer } from "./job-search-preparation.ts";
 
-export function createRuntime(options: { dataDir?: string; concurrency?: number; crawlDelayMs?: number; workdayPageDelayMs?: number; workdayCountries?: string[]; sourceCacheHours?: number; sourceLimit?: number } = {}) {
+export function createRuntime(options: { dataDir?: string; concurrency?: number; crawlDelayMs?: number; workdayPageDelayMs?: number; workdayCountries?: string[]; sourceCacheHours?: number; sourceLimit?: number; timeoutMs?: number } = {}) {
   const workdayCountries = options.workdayCountries ?? (process.env.OPENINGS_WORKDAY_COUNTRIES ?? "IN,US").split(",").map((code) => code.trim().toUpperCase()).filter((code) => /^[A-Z]{2}$/.test(code));
   const dataDir = options.dataDir ?? process.env.OPENINGS_DATA_DIR ?? join(process.cwd(), ".openings");
   const store = createFileSnapshotStore(join(dataDir, "snapshot.json"));
@@ -25,6 +25,7 @@ export function createRuntime(options: { dataDir?: string; concurrency?: number;
     store,
     fetchJobs: (source, signal, observer) => fetchSourceJobs(source, globalThis.fetch, signal, observer),
     concurrency: options.concurrency,
+    timeoutMs: options.timeoutMs,
     sourceStartDelayMs: options.crawlDelayMs,
     sourceFreshnessMs: (options.sourceCacheHours ?? 0) * 60 * 60 * 1000,
     sourceLimit: options.sourceLimit,

package/src/tools.ts

@@ -107,6 +107,7 @@ 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: 1, maximum: 365, description: "Only roles posted within this many days; results are newest first" },
           limit: { type: "integer", minimum: 1, maximum: 100, default: 50 },
         },
         additionalProperties: false,
@@ -140,10 +141,11 @@ 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", "limit"], "search_jobs");
+        assertToolKeys(input, ["query", "location", "country", "remote", "maxAgeDays", "limit"], "search_jobs");
         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");
+        if (input.maxAgeDays !== undefined && (!Number.isInteger(input.maxAgeDays) || (input.maxAgeDays as number) < 1 || (input.maxAgeDays as number) > 365)) throw new Error("maxAgeDays must be an integer between 1 and 365");
         if (input.limit !== undefined && (!Number.isInteger(input.limit) || (input.limit as number) < 1 || (input.limit as number) > 100)) throw new Error("limit must be an integer between 1 and 100");
         const query: SearchQuery = {};
         if (typeof input.query === "string") query.query = input.query;
@@ -151,6 +153,7 @@ export function createToolHandler(catalog: Catalog, workflows: JobWorkflows, opt
         if (typeof input.country === "string" && /^[a-z]{2}$/i.test(input.country)) query.country = input.country.toUpperCase();
         else if (input.country !== undefined) throw new Error("country must be a two-letter code");
         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;
         return { jobs: await catalog.search(query) };
       }
@@ -181,6 +184,7 @@ function intentSchema(): Record<string, unknown> {
       roles: stringArray(), countries: countryArray(), locations: stringArray(), remote: { type: "boolean" }, seniority: stringArray(),
       requiredSkills: stringArray(), excludedTerms: stringArray(),
       excludedCountries: countryArray(), excludedLocations: stringArray(), excludedRoles: stringArray(),
+      maxAgeDays: { type: "integer", minimum: 1, maximum: 365, description: "Only roles posted within this many days" },
     },
     additionalProperties: false,
   };

package/src/types.ts

@@ -80,6 +80,7 @@ export interface JobSummary {
   eligibleRegions: string[];
   eligibilityConfidence: EligibilityConfidence;
   url: string;
+  /** Posting date when the board exposes one (Workday's relative label is approximate), otherwise the board's last-update time. */
   updatedAt?: string;
 }
 
@@ -92,6 +93,8 @@ export interface SearchQuery {
   location?: string;
   country?: string;
   remote?: boolean;
+  /** Only jobs posted within this many days; undated jobs are excluded when set. */
+  maxAgeDays?: number;
   limit?: number;
 }
 

package/src/version.ts

@@ -1 +1 @@
-export const VERSION = "0.1.13";
+export const VERSION = "0.1.15";