openings 0.1.23 → 0.1.25

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "openings",
-  "version": "0.1.23",
+  "version": "0.1.25",
   "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/package.json

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

@@ -1,4 +1,4 @@
-import type { Company, Job, JobSummary, SearchQuery } from "./types.ts";
+import { CASCADE_MINIMUM, CASCADE_WINDOWS, type Company, type Job, type JobAge, type JobSummary, type SearchQuery, type SearchWindow } from "./types.ts";
 import { providerSpec, type JsonGet } from "./providers.ts";
 import { crawlSite, sitePostingsToJobs } from "./jobposting-site.ts";
 import { classifyJob, isEligibleForCountry, normalizeLocation } from "./locations.ts";
@@ -112,15 +112,37 @@ export function createCatalog(options: CatalogOptions): Catalog {
 }
 
 export const DEFAULT_MAX_AGE_DAYS = 30;
-export function searchJobs(jobs: Job[], query: SearchQuery, now: number = Date.now()): JobSummary[] {
-  const explicit = query.maxAgeDays !== undefined;
-  const days = explicit ? query.maxAgeDays! : DEFAULT_MAX_AGE_DAYS;
-  const since = days > 0 ? now - days * 86_400_000 : undefined;
-  const fresh = (job: Job) => since === undefined || postedTime(job) >= since || (!explicit && postedTime(job) === 0);
-  return jobs
-    .filter((job) => matches(job, query) && fresh(job))
-    .sort((left, right) => postedTime(right) - postedTime(left))
-    .slice(0, query.limit ?? 50).map(toSummary);
+export type SearchResult = JobSummary[] & { window?: SearchWindow };
+
+/** One window: dated jobs inside it; 0 means everything including undated. */
+export function withinWindow(job: Pick<Job, "updatedAt">, days: number, now: number): boolean {
+  if (days <= 0) return true;
+  const time = postedTime(job);
+  return time > 0 && time >= now - days * 86_400_000;
+}
+
+/** 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 steps: SearchWindow["steps"] = [];
+  let found: Job[] = [];
+  for (const days of query.maxAgeDays !== undefined ? [query.maxAgeDays] : CASCADE_WINDOWS) {
+    found = run(days);
+    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;
+  Object.defineProperty(result, "window", { value: { daysUsed: steps[steps.length - 1]!.days, widened: steps.length > 1, steps } satisfies SearchWindow, enumerable: false });
+  return result;
+}
+
+/** Age label from the posting date: new (≤7d), older (≤30d), stale, or undated. */
+export function jobAge(job: Pick<Job, "updatedAt">, now: number = Date.now()): { postedDaysAgo?: number; age: JobAge } {
+  const time = postedTime(job);
+  if (time <= 0) return { age: "undated" };
+  const postedDaysAgo = Math.max(0, Math.floor((now - time) / 86_400_000));
+  return { postedDaysAgo, age: postedDaysAgo <= 7 ? "new" : postedDaysAgo <= 30 ? "older" : "stale" };
 }
 
 /** Posting time in ms for sorting; undated jobs sort last. */
@@ -439,9 +461,9 @@ function matches(job: Job, query: SearchQuery): boolean {
     && (query.remote === undefined || job.remote === query.remote);
 }
 
-function toSummary(job: Job): JobSummary {
+function toSummary(job: Job, now: number = Date.now()): JobSummary {
   const { description: _description, ...summary } = job;
-  return summary;
+  return { ...summary, ...jobAge(job, now) };
 }
 
 function stripHtml(value: string): string {

package/src/job-matching.ts

@@ -1,8 +1,8 @@
 import { validateCandidateProfileEvidence, type CandidateProfile } from "./candidate-profile.ts";
 import { isEligibleForCountry, normalizeLocation } from "./locations.ts";
 import { detectRequirementTerms, findTransferability, matchesExactSkillEvidence, requiresExactSkillEvidence, type TransferabilityKind } from "./requirement-vocabulary.ts";
-import type { Job } from "./types.ts";
-import { DEFAULT_MAX_AGE_DAYS, postedTime } from "./catalog.ts";
+import type { Job, JobAge } from "./types.ts";
+import { DEFAULT_MAX_AGE_DAYS, jobAge, postedTime, withinWindow } from "./catalog.ts";
 import { evaluateScreeningRequirements, type ScreeningRequirement } from "./screening-requirements.ts";
 
 export interface CandidateIntent {
@@ -51,6 +51,8 @@ export interface JobMatch {
   discovery: { category: "direct" | "hidden" | "stretch"; titleExpansions: TitleExpansion[] };
   /** The employer's own posting, repeated at the top level so it is never dropped from a summary. */
   applyUrl: string;
+  postedDaysAgo?: number;
+  age: JobAge;
 }
 
 export interface FilteredJob { jobId: string; reasons: string[] }
@@ -118,6 +120,7 @@ export function matchJobs(profile: CandidateProfile, intent: CandidateIntent, jo
       gaps,
       discovery: { category, titleExpansions },
       applyUrl: job.url,
+      ...jobAge(job),
       score,
       index,
     });
@@ -232,9 +235,10 @@ 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}`);
+  // The recommender walks the windows itself and always passes an explicit value; a bare call keeps the 30-day default with undated roles allowed.
   const explicitAge = intent.maxAgeDays !== undefined;
   const maxAgeDays = explicitAge ? intent.maxAgeDays! : DEFAULT_MAX_AGE_DAYS;
-  if (maxAgeDays > 0 && (postedTime(job) > 0 || explicitAge) && postedTime(job) < Date.now() - maxAgeDays * 86_400_000) reasons.push(`posted_too_old:${maxAgeDays}d`);
+  if (maxAgeDays > 0 && !withinWindow(job, maxAgeDays, Date.now()) && (explicitAge || postedTime(job) > 0)) reasons.push(`posted_too_old:${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}`;

package/src/job-recommendations.ts

@@ -1,6 +1,8 @@
 import { parseCandidateProfile, type CandidateProfile, type ResumeInput } from "./candidate-profile.ts";
 import type { SnapshotStore } from "./crawler.ts";
 import { matchJobs, type CandidateIntent, type FilteredJob, type JobMatch, type MatchingOptions } from "./job-matching.ts";
+import { withinWindow } from "./catalog.ts";
+import { CASCADE_MINIMUM, CASCADE_WINDOWS, type SearchWindow } from "./types.ts";
 import { isEligibleForCountry } from "./locations.ts";
 import type { Company, CrawlReport, JobSnapshot } from "./types.ts";
 import { snapshotStatus, type CrawlScope, type SnapshotStatus } from "./local-jobs.ts";
@@ -22,7 +24,8 @@ export interface RecommendJobsResult {
   profile: CandidateProfile;
   matches: JobMatch[];
   exploration: ReturnType<typeof matchJobs>["exploration"];
-  filteredOut: FilteredJob[];
+  /** Counts by reason plus a small sample: the full list once ran to every job in the index and blew past MCP payload limits. */
+  filteredOut: { total: number; byReason: Record<string, number>; sample: FilteredJob[] };
   assumptions: string[];
   ranking: { mode: "evidence" | "keyword"; minimumPercent: number };
   snapshot: SnapshotStatus;
@@ -30,6 +33,11 @@ export interface RecommendJobsResult {
   refresh: RecommendationRefreshResult;
   shortfall?: { minimumMatches: number; actualMatches: number; message: string };
   nextActions: string[];
+  /** Which age windows were walked and where the results came from. */
+  window: SearchWindow;
+  outcome: "matches" | "widened" | "no_matches";
+  explanation: string;
+  nextMoves: string[];
 }
 
 export interface JobRecommenderOptions {
@@ -98,6 +106,7 @@ export function createJobRecommender(options: JobRecommenderOptions) {
         refresh: { policy, attempted, occurred, reason, failures: report?.failed ?? [], ...(refreshError ? { error: refreshError } : {}) },
         ...(shortfall ? { shortfall } : {}),
         nextActions: limited.matches.length ? [`Analyze fit for job ${limited.matches[0]!.job.id}`] : ["Clarify or broaden explicit job intent"],
+        ...describeOutcome(profile, input.intent, limited.window, limited.matches.length),
       };
     },
   };
@@ -138,20 +147,54 @@ function invalidInput(field: string, message: string): RecommendationError {
   return new RecommendationError("invalid_recommendation_input", message, field);
 }
 
+/** Matches inside the cascade: 7 days, then 14, 30, everything, until CASCADE_MINIMUM matches appear. An explicit maxAgeDays is a single window. */
 function matchSnapshot(profile: CandidateProfile, intent: CandidateIntent, snapshot: JobSnapshot, ranking?: MatchingOptions) {
   const jobs = Object.values(snapshot.partitions).flatMap((partition) => partition.jobs);
-  return matchJobs(profile, intent, jobs, jobs.length, ranking);
-}
-
-function limitMatching<T extends ReturnType<typeof matchSnapshot>>(matching: T, limit = 20): T {
-  const matches = matching.matches.slice(0, Math.max(0, limit));
-  const ids = new Set(matches.map((match) => match.job.id));
-  return { ...matching, matches, exploration: {
-    ...matching.exploration,
-    directMatches: matching.exploration.directMatches.filter((match) => ids.has(match.job.id)),
-    hiddenMatches: matching.exploration.hiddenMatches.filter((match) => ids.has(match.job.id)),
-    stretchMatches: matching.exploration.stretchMatches.filter((match) => ids.has(match.job.id)),
-  } };
+  const now = Date.now();
+  const steps: SearchWindow["steps"] = [];
+  let matching = matchJobs(profile, { ...intent, maxAgeDays: 0 }, [], 0, ranking);
+  for (const days of intent.maxAgeDays !== undefined ? [intent.maxAgeDays] : CASCADE_WINDOWS) {
+    const candidates = days > 0 ? jobs.filter((job) => withinWindow(job, days, now)) : jobs;
+    matching = matchJobs(profile, { ...intent, maxAgeDays: days }, candidates, candidates.length, ranking);
+    steps.push({ days, results: matching.matches.length });
+    if (matching.matches.length >= CASCADE_MINIMUM) break;
+  }
+  return { ...matching, window: { daysUsed: steps[steps.length - 1]!.days, widened: steps.length > 1, steps } satisfies SearchWindow };
+}
+
+/** Says in data terms why the result is what it is, so the agent never presents silence as an answer. */
+function describeOutcome(profile: CandidateProfile, intent: CandidateIntent, window: SearchWindow, matches: number): { outcome: RecommendJobsResult["outcome"]; explanation: string; nextMoves: string[] } {
+  const skills = profile.facts.filter((fact) => fact.kind === "skill").map((fact) => fact.value).slice(0, 8);
+  const roles = profile.facts.filter((fact) => fact.kind === "role").map((fact) => fact.value).slice(0, 4);
+  const windows = window.steps.map((step) => `${step.days === 0 ? "all time" : `${step.days} days`}: ${step.results}`).join(", ");
+  const scope = [intent.roles?.length ? `roles asked: ${intent.roles.join(", ")}` : "", intent.countries?.length ? `countries: ${intent.countries.join(", ")}` : "", skills.length ? `resume skills: ${skills.join(", ")}` : "", roles.length ? `resume roles: ${roles.join(", ")}` : ""].filter(Boolean).join("; ");
+  if (matches === 0) return {
+    outcome: "no_matches",
+    explanation: `No role matched (${windows}). ${scope}.`,
+    nextMoves: ["Broaden or remove the roles in intent, or drop excludedRoles", "Add countries or allow remote roles", "Try search_jobs with a plain keyword to see what the index holds", "Check get_job_coverage for the countries asked"],
+  };
+  if (window.widened) return {
+    outcome: "widened",
+    explanation: `Fewer than ${CASCADE_MINIMUM} matches in the last ${window.steps[0]!.days} days, so the window widened to ${window.daysUsed === 0 ? "all time" : `${window.daysUsed} days`} (${windows}). ${scope}. Present roles labelled older or stale as possibly still open, not as current.`,
+    nextMoves: ["Tell the person which window the results came from", "Offer to broaden roles or countries for fresher matches"],
+  };
+  return { outcome: "matches", explanation: `${matches} matches in the last ${window.daysUsed} days (${windows}). ${scope}.`, nextMoves: [] };
+}
+
+const EXCERPT_CHARS = 280;
+/** Transport shape: descriptions become excerpts (get_job returns the full text), exploration lists carry the same compact matches, filtered jobs are summarised. */
+function limitMatching(matching: ReturnType<typeof matchSnapshot>, limit = 20): Omit<ReturnType<typeof matchSnapshot>, "filteredOut"> & { filteredOut: RecommendJobsResult["filteredOut"] } {
+  const compact = (match: JobMatch): JobMatch => ({ ...match, job: { ...match.job, description: match.job.description.length > EXCERPT_CHARS ? `${match.job.description.slice(0, EXCERPT_CHARS).trimEnd()}…` : match.job.description } });
+  const matches = matching.matches.slice(0, Math.max(0, limit)).map(compact);
+  const byId = new Map(matches.map((match) => [match.job.id, match]));
+  const pick = (list: JobMatch[]) => list.filter((match) => byId.has(match.job.id)).map((match) => byId.get(match.job.id)!);
+  const byReason: Record<string, number> = {};
+  for (const entry of matching.filteredOut) for (const reason of entry.reasons) { const key = reason.split(":")[0]!; byReason[key] = (byReason[key] ?? 0) + 1; }
+  return {
+    ...matching, matches,
+    exploration: { ...matching.exploration, directMatches: pick(matching.exploration.directMatches), hiddenMatches: pick(matching.exploration.hiddenMatches), stretchMatches: pick(matching.exploration.stretchMatches) },
+    filteredOut: { total: matching.filteredOut.length, byReason, sample: matching.filteredOut.slice(0, 20) },
+  };
 }
 
 function preCutoffMatchCount(matching: ReturnType<typeof matchSnapshot>): number {

package/src/mcp.ts

@@ -17,6 +17,13 @@ interface ToolHandler {
   call(name: string, input: Record<string, unknown>): Promise<unknown>;
 }
 
+/** 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.",
+  "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.",
+  "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.",
+].join("\n");
+
 export function createMcpHandler(tools: ToolHandler, options: { update?: () => UpdateNotice | null } = {}) {
   /** A pending update rides on every tool result so the AI app can prompt the person; nothing is changed on their machine. */
   const withUpdate = (payload: unknown) => { const update = options.update?.(); return update && isRecord(payload) ? { ...payload, updateAvailable: update } : payload; };
@@ -28,7 +35,7 @@ export function createMcpHandler(tools: ToolHandler, options: { update?: () => U
     try {
       if (request.method === "initialize") {
         const update = options.update?.();
-        return { ...base, result: { protocolVersion: "2025-06-18", capabilities: { tools: {} }, serverInfo: { name: "openings", version: VERSION }, ...(update ? { instructions: update.message } : {}) } };
+        return { ...base, result: { protocolVersion: "2025-06-18", capabilities: { tools: {} }, serverInfo: { name: "openings", version: VERSION }, instructions: [FLOW_INSTRUCTIONS, update?.message].filter(Boolean).join("\n\n") } };
       }
       if (request.method === "ping") return { ...base, result: {} };
       if (request.method === "tools/list") return { ...base, result: { tools: tools.list() } };

package/src/tools.ts

@@ -3,6 +3,7 @@ import type { RecommendJobsResult } from "./job-recommendations.ts";
 import type { AnalyzeJobFitResult } from "./job-fit-analysis.ts";
 import type { OptimizeResumeResult } from "./resume-optimization.ts";
 import type { SearchQuery } from "./types.ts";
+import type { SearchResult } from "./catalog.ts";
 import type { JobCoverageSummary } from "./job-coverage.ts";
 import type { PrepareJobSearchResult } from "./job-search-preparation.ts";
 
@@ -99,7 +100,7 @@ export function createToolHandler(catalog: Catalog, workflows: JobWorkflows, opt
     },
     {
       name: "search_jobs",
-      description: "Search the local job snapshot by role, location, country eligibility, and work mode.",
+      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.",
       inputSchema: {
         type: "object",
         properties: {
@@ -155,7 +156,11 @@ 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;
-        return { jobs: await catalog.search(query) };
+        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.",
+        };
       }
       if (name === "get_job") {
         assertToolKeys(input, ["id"], "get_job");

package/src/types.ts

@@ -83,8 +83,18 @@ export interface JobSummary {
   url: string;
   /** Posting date when the board exposes one (Workday's relative label is approximate), otherwise the board's last-update time. */
   updatedAt?: string;
+  /** Days since the posting date at the time of the search; absent when the board gave no date. */
+  postedDaysAgo?: number;
+  /** new = 7 days or less, older = 8 to 30, stale = beyond 30, undated = no posting date. Present it as such; a stale listing may still be open. */
+  age?: JobAge;
 }
 
+export type JobAge = "new" | "older" | "stale" | "undated";
+/** The age windows a search or recommendation walked: 7 days, then 14, then 30, then everything, until at least CASCADE_MINIMUM results appeared. */
+export interface SearchWindow { daysUsed: number; widened: boolean; steps: Array<{ days: number; results: number }> }
+export const CASCADE_WINDOWS = [7, 14, 30, 0] as const;
+export const CASCADE_MINIMUM = 5;
+
 export interface Job extends JobSummary {
   description: string;
 }
@@ -99,7 +109,7 @@ export interface SearchQuery {
   location?: string;
   country?: string;
   remote?: boolean;
-  /** Only jobs posted within this many days. Default 30 keeps undated jobs (sorted last); an explicit value also drops undated jobs; 0 includes everything. */
+  /** 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;
 }

package/src/version.ts

@@ -1 +1 @@
-export const VERSION = "0.1.23";
+export const VERSION = "0.1.25";