openings 0.1.14 → 0.1.16

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "openings",
-  "version": "0.1.14",
+  "version": "0.1.16",
   "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.14",
+  "version": "0.1.16",
   "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/crawler.ts

@@ -1,5 +1,5 @@
 import type { FetchJobsObserver } from "./catalog.ts";
-import type { Company, CrawlFailure, CrawlReport, CrawlSourceResult, Job, JobPartition, JobSnapshot } from "./types.ts";
+import { partitionFor, type Company, type CrawlFailure, type CrawlReport, type CrawlSourceResult, type Job, type JobPartition, type JobSnapshot } from "./types.ts";
 
 export interface SnapshotStore {
   read(): Promise<JobSnapshot | null>;
@@ -66,9 +66,9 @@ export function createCrawler(options: CrawlerOptions): Crawler {
       const considered = sources.length;
       const cutoff = Date.parse(startedAt) - sourceFreshnessMs;
       const eligibleSources = (sourceFreshnessMs === 0 ? sources : sources.filter((source) => {
-        const fetchedAt = Date.parse(partitions[source.slug]?.fetchedAt ?? "");
+        const fetchedAt = Date.parse(partitionFor(partitions, source.slug)?.fetchedAt ?? "");
         return !Number.isFinite(fetchedAt) || fetchedAt <= cutoff;
-      })).sort((left, right) => partitionTime(partitions[left.slug]?.fetchedAt) - partitionTime(partitions[right.slug]?.fetchedAt));
+      })).sort((left, right) => partitionTime(partitionFor(partitions, left.slug)?.fetchedAt) - partitionTime(partitionFor(partitions, right.slug)?.fetchedAt));
       const selectedSources = sourceLimit > 0 ? eligibleSources.slice(0, sourceLimit) : eligibleSources;
       let pending = selectedSources;
       let finalFailures: CrawlFailure[] = [];

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-coverage.ts

@@ -1,6 +1,6 @@
 import { isEligibleForCountry } from "./locations.ts";
 import type { SnapshotStore } from "./crawler.ts";
-import type { Company, JobSnapshot } from "./types.ts";
+import { partitionFor, type Company, type JobSnapshot } from "./types.ts";
 
 export interface CountryJobCoverage {
   country: string;
@@ -28,7 +28,7 @@ export function createJobCoverageReader(options: { sources: Company[]; store: Sn
 export function projectJobCoverage(sources: Company[], snapshot: JobSnapshot, countries: string[]): JobCoverageSummary {
   const normalizedCountries = [...new Set(countries.map(normalizeCountry))];
   const indexedSources = sources.flatMap((source) => {
-    const partition = snapshot.partitions[source.slug];
+    const partition = partitionFor(snapshot.partitions, source.slug);
     return partition ? [{ source, jobs: partition.jobs }] : [];
   });
 

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/job-search-preparation.ts

@@ -1,7 +1,7 @@
 import type { SnapshotStore } from "./crawler.ts";
 import { projectJobCoverage, type JobCoverageSummary } from "./job-coverage.ts";
 import type { CrawlScope } from "./local-jobs.ts";
-import type { Company, CrawlReport, JobSnapshot } from "./types.ts";
+import { partitionFor, type Company, type CrawlReport, type JobSnapshot } from "./types.ts";
 
 export interface PrepareJobSearchResult {
   status: "ready" | "partial";
@@ -61,7 +61,7 @@ export function createJobSearchPreparer(options: {
 function pendingSources(sources: Company[], snapshot: Awaited<ReturnType<SnapshotStore["read"]>>, now: Date, freshnessMs: number): Company[] {
   const cutoff = now.getTime() - freshnessMs;
   return sources.filter((source) => {
-    const fetchedAt = Date.parse(snapshot?.partitions[source.slug]?.fetchedAt ?? "");
+    const fetchedAt = Date.parse((snapshot && partitionFor(snapshot.partitions, source.slug))?.fetchedAt ?? "");
     return !Number.isFinite(fetchedAt) || fetchedAt < cutoff;
   });
 }
@@ -71,7 +71,7 @@ function sourceState(sources: Company[], snapshot: NonNullable<Awaited<ReturnTyp
   let missing = 0;
   let stale = 0;
   for (const source of sources) {
-    const partition = snapshot.partitions[source.slug];
+    const partition = partitionFor(snapshot.partitions, source.slug);
     if (!partition) missing += 1;
     else {
       const fetchedAt = Date.parse(partition.fetchedAt);

package/src/runtime.ts

@@ -47,7 +47,7 @@ export function createRuntime(options: { dataDir?: string; concurrency?: number;
     workdayCountries,
     onCrawled,
   });
-  const preparation = createJobSearchPreparer({ sources: companies, store, crawl: preparationLocal.crawl, seed: aggregatorUrl ? (countries) => fetchSeedSnapshot(aggregatorUrl, globalThis.fetch, 20_000, countries) : undefined });
+  const preparation = createJobSearchPreparer({ sources: companies, store, crawl: preparationLocal.crawl, seed: aggregatorUrl ? (countries) => fetchSeedSnapshot(aggregatorUrl, globalThis.fetch, 60_000, countries) : undefined });
   const getSelectedJob = createSelectedJobLookup({
     getSnapshotJob: async (id) => (await local.get(id, { offline: true, staleDays: 14 })).job,
     getDetailedJob: (id) => liveCatalog.get(id),

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;
 }
 
@@ -87,11 +88,18 @@ export interface Job extends JobSummary {
   description: string;
 }
 
+/** Partition lookup that ignores inherited properties, so a slug such as "constructor" never resolves to Object.prototype. */
+export function partitionFor<T>(partitions: Record<string, T>, slug: string): T | undefined {
+  return Object.hasOwn(partitions, slug) ? partitions[slug] : undefined;
+}
+
 export interface SearchQuery {
   query?: string;
   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.14";
+export const VERSION = "0.1.16";