openings 0.1.58 → 0.1.59

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openings",
-  "version": "0.1.58",
+  "version": "0.1.59",
   "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/index.ts

@@ -41,6 +41,7 @@ export type { CountryJobCoverage, JobCoverageSummary } from "./job-coverage.ts";
 export { createHostedRuntime } from "./runtime.ts";
 export type { SnapshotStore } from "./crawler.ts";
 export { createToolHandler, SCOPES, scopeForTool, type Scope } from "./tools.ts";
+export { describeWatchProfile, matchWatch, toWatchProfile, type WatchableJob, type WatchMatch, type WatchProfile } from "./watch-profile.ts";
 export { createMcpHandler, FLOW_INSTRUCTIONS } from "./mcp.ts";
 export type { UpdateNotice } from "./update-check.ts";
 export { VERSION } from "./version.ts";

package/src/tools.ts

@@ -8,7 +8,8 @@ import type { JobCoverageSummary } from "./job-coverage.ts";
 import type { PrepareJobSearchResult } from "./job-search-preparation.ts";
 
 export interface ToolDefinition {
-  name: "prepare_job_search" | "get_job_coverage" | "recommend_jobs" | "analyze_job_fit" | "optimize_resume" | "search_jobs" | "get_job";
+  name: "prepare_job_search" | "get_job_coverage" | "recommend_jobs" | "analyze_job_fit" | "optimize_resume" | "search_jobs" | "get_job"
+    | "watch_jobs" | "list_watches" | "check_watch" | "stop_watch";
   /** Human-readable name for a consent screen or tool picker, where a snake_case identifier reads poorly. */
   title: string;
   description: string;
@@ -18,12 +19,16 @@ export interface ToolDefinition {
   outputSchema: Record<string, unknown>;
   /** Nothing here applies, submits, or writes on the candidate's behalf. Preparation is the one tool that writes
    * at all: it caches the job index on disk, so claiming readOnlyHint for it would be untrue. */
-  annotations: { readOnlyHint: boolean; destructiveHint: false; idempotentHint: true; openWorldHint: boolean };
+  annotations: { readOnlyHint: boolean; destructiveHint: boolean; idempotentHint: true; openWorldHint: boolean };
 }
 
 /** Tools that reach employer boards over the network are open-world; the rest read the local index. */
+const WRITES = new Set<ToolDefinition["name"]>(["prepare_job_search", "watch_jobs", "stop_watch"]);
+/** Monitors need somewhere to persist, which a local install does not have. The host says whether it offers them. */
+const WATCH_TOOLS = new Set<ToolDefinition["name"]>(["watch_jobs", "list_watches", "check_watch", "stop_watch"]);
 const annotationsFor = (name: ToolDefinition["name"]): ToolDefinition["annotations"] =>
-  ({ readOnlyHint: name !== "prepare_job_search", destructiveHint: false, idempotentHint: true, openWorldHint: name === "prepare_job_search" || name === "recommend_jobs" || name === "get_job" });
+  ({ readOnlyHint: !WRITES.has(name), destructiveHint: name === "stop_watch", idempotentHint: true,
+     openWorldHint: name === "prepare_job_search" || name === "recommend_jobs" || name === "get_job" });
 
 interface JobWorkflows {
   prepareJobSearch(input: unknown): Promise<PrepareJobSearchResult>;
@@ -31,6 +36,13 @@ interface JobWorkflows {
   recommend(input: unknown): Promise<RecommendJobsResult>;
   analyzeJobFit(input: unknown): Promise<AnalyzeJobFitResult>;
   optimizeResume(input: unknown): Promise<OptimizeResumeResult>;
+  /** Monitors. Absent where the host does not offer them, in which case the four tools are not listed at all. */
+  watches?: {
+    create(input: unknown): Promise<unknown>;
+    list(): Promise<unknown>;
+    check(input: unknown): Promise<unknown>;
+    stop(input: unknown): Promise<unknown>;
+  };
 }
 
 /**
@@ -44,6 +56,10 @@ export type Scope = (typeof SCOPES)[keyof typeof SCOPES];
 const TOOL_SCOPE: Record<ToolDefinition["name"], Scope> = {
   prepare_job_search: SCOPES.jobs, get_job_coverage: SCOPES.jobs, search_jobs: SCOPES.jobs, get_job: SCOPES.jobs,
   recommend_jobs: SCOPES.resume, analyze_job_fit: SCOPES.resume, optimize_resume: SCOPES.resume,
+  // Creating or changing a monitor reads a resume. Reading one back does not, so an agent can poll a monitor
+  // with a job-search token and never hold resume access at all.
+  watch_jobs: SCOPES.resume, stop_watch: SCOPES.resume,
+  list_watches: SCOPES.jobs, check_watch: SCOPES.jobs,
 };
 
 /** The scope a tool needs, for a caller that wants to explain the boundary rather than discover it by refusal. */
@@ -222,6 +238,65 @@ export function createToolHandler(catalog: Catalog, workflows: JobWorkflows, opt
         guidance: { type: "string", description: "How to present these results honestly; meant for the assistant, not the candidate" },
       }, ["jobs", "window", "pagination"]),
     },
+    {
+      name: "watch_jobs",
+      title: "Watch for roles that fit",
+      description: "Create a standing monitor from a resume, so new roles that fit are found without asking again. What is kept is the search the resume produced, never the resume: the skills, titles, seniority and years that matching uses, which the result shows back in plain words so the candidate can read, change or stop it. Use it when someone wants to be told about new roles over time; use recommend_jobs for a one-off ranking right now.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          resume: resumeSchema(),
+          intent: intentSchema(),
+          email: { type: "string", description: "Where to send new matches. Omit to create a monitor the assistant checks with check_watch instead of one that emails" },
+          label: { type: "string", description: "A short name for this monitor, so a person with several can tell them apart" },
+        },
+        required: ["resume"], additionalProperties: false,
+      },
+      outputSchema: output({
+        id: { type: "string", description: "Pass this to check_watch or stop_watch" },
+        holding: { type: "string", description: "What is stored, in plain words. Read it back to the candidate: it is the whole privacy claim" },
+        profile: { type: "object", additionalProperties: true, description: "The stored search itself, which contains no resume text" },
+        matchesNow: { type: "array", items: { type: "object", additionalProperties: true }, description: "Roles matching today, so the monitor is useful immediately" },
+        emailing: { type: "boolean", description: "Whether new matches will be emailed; false means the assistant must call check_watch" },
+      }, ["id", "holding"]),
+    },
+    {
+      name: "list_watches",
+      title: "List monitors",
+      description: "Every monitor on this account, with what each one holds and when it last found something. Reads no resume.",
+      inputSchema: { type: "object", properties: {}, additionalProperties: false },
+      outputSchema: output({ watches: { type: "array", items: { type: "object", additionalProperties: true } } }, ["watches"]),
+    },
+    {
+      name: "check_watch",
+      title: "What is new for a monitor",
+      description: "Roles matching a monitor that it has not reported before, newest first, each with the reason it matched. Reads no resume, so an assistant can poll a monitor without ever holding resume access. Calling it marks those roles as seen, so the next call returns only what is new after that.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          id: { type: "string", minLength: 1, description: "The monitor id from watch_jobs or list_watches" },
+          limit: { type: "integer", minimum: 1, maximum: 50, default: 20, description: "How many new roles to return" },
+          peek: { type: "boolean", default: false, description: "True to look without marking anything as seen" },
+        },
+        required: ["id"], additionalProperties: false,
+      },
+      outputSchema: output({
+        matches: { type: "array", items: { type: "object", additionalProperties: true }, description: "Each carries the job, why it matched, and the employer's own posting URL" },
+        checkedAt: { type: "string" },
+        newSince: { type: "string", description: "Roles are new relative to this moment, not to when they were posted" },
+      }, ["matches"]),
+    },
+    {
+      name: "stop_watch",
+      title: "Stop a monitor",
+      description: "Delete a monitor and everything stored with it, including the record of what it has already reported. Nothing is kept.",
+      inputSchema: {
+        type: "object",
+        properties: { id: { type: "string", minLength: 1, description: "The monitor id" } },
+        required: ["id"], additionalProperties: false,
+      },
+      outputSchema: output({ stopped: { type: "boolean" }, deleted: { type: "string", description: "What was removed" } }, ["stopped"]),
+    },
     {
       name: "get_job",
       title: "Get job details",
@@ -238,7 +313,7 @@ export function createToolHandler(catalog: Catalog, workflows: JobWorkflows, opt
 
   return {
     // A client sees only what it may call. Listing a tool it would be refused teaches it to try and fail.
-    list: () => definitions.filter((definition) => allowed(definition.name))
+    list: () => definitions.filter((definition) => allowed(definition.name) && (workflows.watches !== undefined || !WATCH_TOOLS.has(definition.name)))
       .map((definition) => ({ ...definition, annotations: annotationsFor(definition.name) })),
     async call(name: string, input: Record<string, unknown>) {
       const needed = TOOL_SCOPE[name as ToolDefinition["name"]];
@@ -251,9 +326,18 @@ export function createToolHandler(catalog: Catalog, workflows: JobWorkflows, opt
     },
   };
 
+  const requireWatches = () => {
+    if (!workflows.watches) throw new Error("Monitors are only available on the hosted server, where there is an account to attach one to.");
+    return workflows.watches;
+  };
+
   async function dispatch(name: string, input: Record<string, unknown>): Promise<unknown> {
       if (name === "prepare_job_search") return workflows.prepareJobSearch(input);
       if (name === "get_job_coverage") return workflows.getJobCoverage(input);
+      if (name === "watch_jobs") return requireWatches().create(input);
+      if (name === "list_watches") return requireWatches().list();
+      if (name === "check_watch") return requireWatches().check(input);
+      if (name === "stop_watch") return requireWatches().stop(input);
       if (name === "recommend_jobs") return workflows.recommend(input);
       if (name === "analyze_job_fit") return workflows.analyzeJobFit(input);
       if (name === "optimize_resume") return workflows.optimizeResume(input);

package/src/version.ts

@@ -1 +1 @@
-export const VERSION = "0.1.58";
+export const VERSION = "0.1.59";

package/src/watch-profile.ts

@@ -0,0 +1,121 @@
+/**
+ * The part of a candidate we are willing to remember.
+ *
+ * A monitor has to persist something or it cannot tell you what is new. Resumes are not that something: the
+ * privacy page says a resume is read for one request and never stored, and that promise is the product rather
+ * than a detail of it. What survives here is the search the resume produced — the skills, titles, seniority and
+ * years that matching actually uses — and never a word of the document itself.
+ *
+ * Evidence spans are dropped deliberately. They are verbatim quotes from the resume, and keeping them would put
+ * the document back in the database through a side door.
+ */
+import type { CandidateProfile } from "./candidate-profile.ts";
+
+export interface WatchProfile {
+  /** Skills named in the resume, lower-cased, with no surrounding text. */
+  skills: string[];
+  /** Role titles the candidate has held, as written, with no employer or dates attached. */
+  roles: string[];
+  seniority?: "intern" | "junior" | "mid" | "senior" | "lead" | "staff" | "principal" | "manager";
+  roleFamilies: string[];
+  /** Years as derived from dated work, not as claimed anywhere in prose. */
+  approximateYears?: number;
+  /** What the candidate asked for, which is theirs to state rather than ours to infer. */
+  countries: string[];
+  locations: string[];
+  remoteOnly?: boolean;
+  excludedTerms: string[];
+}
+
+const CAP = 40;
+const clean = (values: Iterable<string>, cap = CAP): string[] => {
+  const out: string[] = [];
+  const seen = new Set<string>();
+  for (const raw of values) {
+    const value = raw.trim().toLowerCase().slice(0, 64);
+    // A fact long enough to be a sentence is a sentence, and a sentence from a resume is resume text.
+    if (!value || value.length > 64 || value.split(/\s+/).length > 5 || seen.has(value)) continue;
+    seen.add(value); out.push(value);
+    if (out.length >= cap) break;
+  }
+  return out;
+};
+
+/** Reduce a parsed resume to the little we keep. Everything not named here is discarded. */
+export function toWatchProfile(profile: CandidateProfile, intent: {
+  countries?: string[]; locations?: string[]; remote?: boolean; excludedTerms?: string[];
+} = {}): WatchProfile {
+  const facts = profile.facts ?? [];
+  const seniority = profile.inferences?.find((i) => i.kind === "seniority");
+  const years = profile.inferences?.find((i) => i.kind === "approximate_experience_years");
+  return {
+    skills: clean(facts.filter((f) => f.kind === "skill").map((f) => f.value)),
+    roles: clean(facts.filter((f) => f.kind === "role").map((f) => f.value), 12),
+    ...(seniority ? { seniority: seniority.value as WatchProfile["seniority"] } : {}),
+    roleFamilies: clean(profile.inferences?.filter((i) => i.kind === "role_family").map((i) => String(i.value)) ?? [], 6),
+    ...(years && typeof years.value === "number" ? { approximateYears: years.value } : {}),
+    countries: clean(intent.countries ?? [], 8).map((c) => c.toUpperCase()),
+    locations: clean(intent.locations ?? [], 12),
+    ...(intent.remote === true ? { remoteOnly: true } : {}),
+    excludedTerms: clean(intent.excludedTerms ?? [], 16),
+  };
+}
+
+/** What the candidate is told we hold, in their words rather than ours. A monitor they cannot read is a monitor
+ * they cannot trust, so this is shown whenever one is created, listed or edited. */
+export function describeWatchProfile(profile: WatchProfile): string {
+  const parts: string[] = [];
+  if (profile.roles.length) parts.push(`roles like ${profile.roles.slice(0, 3).join(", ")}`);
+  if (profile.seniority) parts.push(`at ${profile.seniority} level`);
+  if (profile.approximateYears !== undefined) parts.push(`around ${profile.approximateYears} years of experience`);
+  if (profile.skills.length) parts.push(`skills including ${profile.skills.slice(0, 6).join(", ")}`);
+  if (profile.countries.length) parts.push(`open to ${profile.countries.join(", ")}`);
+  if (profile.locations.length) parts.push(`in ${profile.locations.slice(0, 4).join(", ")}`);
+  if (profile.remoteOnly) parts.push("remote only");
+  if (profile.excludedTerms.length) parts.push(`not ${profile.excludedTerms.slice(0, 4).join(", ")}`);
+  return parts.join("; ") || "no details were derived from the resume";
+}
+
+/** The job fields a monitor needs. Deliberately the same shape the search already produces. */
+export interface WatchableJob {
+  id: string; title: string; company: string; location: string; remote: boolean;
+  countries: string[]; skills?: string; experience?: { min: number; max?: number } | null;
+}
+
+/** Why a role matched, so a candidate is told rather than asked to trust a score. */
+export interface WatchMatch { job: WatchableJob; score: number; reasons: string[] }
+
+/**
+ * Roles worth telling this candidate about. The rule is deliberately plain: a role has to look like work they
+ * have done, in a place they said they would work, and not be something they asked to avoid. A clever ranking
+ * that cannot be explained in one line is worse here than a simple one that can, because the candidate is reading
+ * an email rather than watching a demo.
+ */
+export function matchWatch(profile: WatchProfile, jobs: readonly WatchableJob[], limit = 20): WatchMatch[] {
+  const skills = new Set(profile.skills);
+  const roleWords = new Set(profile.roles.flatMap((role) => role.split(/\s+/)).filter((w) => w.length > 3));
+  const excluded = profile.excludedTerms;
+  const matches: WatchMatch[] = [];
+  for (const job of jobs) {
+    const title = (job.title || "").toLowerCase();
+    const haystack = `${title} ${(job.skills || "").toLowerCase()}`;
+    if (excluded.some((term) => title.includes(term))) continue;
+    if (profile.remoteOnly && !job.remote) continue;
+    if (profile.countries.length && !job.countries.some((code) => profile.countries.includes(code))) continue;
+    if (profile.locations.length && !job.remote) {
+      const where = (job.location || "").toLowerCase();
+      if (!profile.locations.some((place) => where.includes(place))) continue;
+    }
+    const titleHits = [...roleWords].filter((word) => title.includes(word));
+    const skillHits = [...skills].filter((skill) => haystack.includes(skill));
+    if (!titleHits.length && !skillHits.length) continue;
+    // Stated years are the employer's requirement, so a role far above the candidate is noise rather than a stretch.
+    if (profile.approximateYears !== undefined && job.experience && job.experience.min > profile.approximateYears + 3) continue;
+    const reasons: string[] = [];
+    if (titleHits.length) reasons.push(`the title matches your work: ${titleHits.slice(0, 3).join(", ")}`);
+    if (skillHits.length) reasons.push(`asks for ${skillHits.slice(0, 4).join(", ")}`);
+    if (job.experience) reasons.push(`wants ${job.experience.min}${job.experience.max ? `-${job.experience.max}` : "+"} years`);
+    matches.push({ job, score: titleHits.length * 2 + skillHits.length, reasons });
+  }
+  return matches.sort((left, right) => right.score - left.score).slice(0, limit);
+}