openings 0.1.34 → 0.1.35

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "openings",
-  "version": "0.1.34",
+  "version": "0.1.35",
   "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.34",
+  "version": "0.1.35",
   "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/candidate-profile.ts

@@ -36,6 +36,14 @@ export class ResumeInputError extends Error {
   ) { super(message); }
 }
 
+/** A PDF or DOCX pasted as text: a file signature, or control characters no resume contains. */
+function looksBinary(content: string): boolean {
+  const head = content.slice(0, 2048);
+  if (/^%PDF-|^PK\u0003\u0004|^\{\\rtf/.test(content.trimStart())) return true;
+  const control = head.match(/[\u0000-\u0008\u000e-\u001f]/g)?.length ?? 0;
+  return control > 0 && control / Math.max(head.length, 1) > 0.01;
+}
+
 export function parseCandidateProfile(input: unknown): CandidateProfile {
   if (!isRecord(input) || typeof input.format !== "string" || typeof input.content !== "string") {
     throw new ResumeInputError("invalid_resume_input", "Resume must contain text or Markdown content");
@@ -43,6 +51,9 @@ export function parseCandidateProfile(input: unknown): CandidateProfile {
   if (input.format === "pdf_base64" || input.format === "docx_base64") {
     throw new ResumeInputError("unsupported_resume_format", `Resume format ${input.format} is not supported yet`, input.format, ["text", "markdown"]);
   }
+  if (looksBinary(input.content)) {
+    throw new ResumeInputError("invalid_resume_input", "That looks like a file's raw bytes, not resume text. Export the resume as text, or paste the text itself.");
+  }
   if (!(["text", "markdown"] as string[]).includes(input.format)) {
     throw new ResumeInputError("invalid_resume_input", "Resume must contain text or Markdown content");
   }

package/src/mcp.ts

@@ -48,11 +48,13 @@ export function createMcpHandler(tools: ToolHandler, options: { update?: () => U
         if (args !== undefined && !isRecord(args)) throw new Error("tools/call arguments must be an object");
         try {
           const result = await tools.call(name, args ?? {});
-          return { ...base, result: { content: [{ type: "text", text: JSON.stringify(withUpdate(result), null, 2) }], isError: false } };
+          const payload = withUpdate(result);
+          // Both shapes: text for models that read it, structuredContent for hosts that render it.
+          return { ...base, result: { content: [{ type: "text", text: JSON.stringify(payload, null, 2) }], structuredContent: payload, isError: false } };
         } catch (error) {
           const details = errorDetails(error);
-          const payload = { error: { message: error instanceof Error ? error.message : String(error), ...(details ?? {}) } };
-          return { ...base, result: { content: [{ type: "text", text: JSON.stringify(withUpdate(payload), null, 2) }], isError: true } };
+          const failure = withUpdate({ error: { message: error instanceof Error ? error.message : String(error), ...(details ?? {}) } });
+          return { ...base, result: { content: [{ type: "text", text: JSON.stringify(failure, null, 2) }], structuredContent: failure, isError: true } };
         }
       }
       if (request.method.startsWith("notifications/")) return null;

package/src/runtime.ts

@@ -1,6 +1,6 @@
 import { join } from "node:path";
 import type { SnapshotStore } from "./crawler.ts";
-import type { Company, SearchQuery } from "./types.ts";
+import type { Company, Job, SearchQuery } from "./types.ts";
 import { fetchJobDescription, fetchSourceJobs } from "./catalog.ts";
 import { createCrawlReporter, fetchSeedSnapshot, resolveAggregatorUrl } from "./crawl-reporting.ts";
 import { createUsageReporter, type UsageReporter } from "./usage.ts";
@@ -74,12 +74,24 @@ export function createHostedRuntime(options: { sources: Company[]; store: Snapsh
   const recommender = createJobRecommender({ sources: options.sources, store: options.store, crawl: noCrawl, now: options.now });
   const coverage = createJobCoverageReader({ sources: options.sources, store: options.store });
   const preparation = createJobSearchPreparer({ sources: options.sources, store: options.store, crawl: noCrawl, now: options.now, freshnessDays: 3650 });
-  const getSelectedJob = createSelectedJobLookup({ getSnapshotJob: async (id) => (await local.get(id, { offline: true, staleDays: 3650 })).job, getDetailedJob: async () => null });
+  // Workday and a few other boards keep descriptions off their listings, so the shared index has none: read one on demand.
+  async function withDescription(job: Job | null): Promise<Job | null> {
+    if (!job || job.description.trim()) return job;
+    const [ats, slug] = job.id.split(":", 3);
+    const company = options.sources.find((source) => source.ats === ats && source.slug === slug);
+    if (!company) return job;
+    try {
+      const description = await fetchJobDescription(company, job, globalThis.fetch);
+      return description.trim() ? { ...job, description } : job;
+    } catch { return job; } // the employer's board is unreachable; the summary is still useful
+  }
+  const snapshotJob = async (id: string) => (await local.get(id, { offline: true, staleDays: 3650 })).job;
+  const getSelectedJob = createSelectedJobLookup({ getSnapshotJob: snapshotJob, getDetailedJob: async (id) => withDescription(await snapshotJob(id)) });
   const analyzer = createJobFitAnalyzer({ getJob: getSelectedJob });
   const optimizer = createResumeOptimizer({ analyzeJobFit: analyzer.analyze });
   return {
     search: (query: SearchQuery) => local.search(query, { offline: true, staleDays: 3650 }),
-    get: (id: string) => local.get(id, { offline: true, staleDays: 3650 }),
+    get: async (id: string) => { const found = await local.get(id, { offline: true, staleDays: 3650 }); return { ...found, job: await withDescription(found.job) }; },
     prepareJobSearch: preparation.prepare, getJobCoverage: coverage.getCoverage, recommend: recommender.recommend, analyzeJobFit: analyzer.analyze, optimizeResume: optimizer.optimize,
   };
 }

package/src/tools.ts

@@ -11,8 +11,14 @@ export interface ToolDefinition {
   name: "prepare_job_search" | "get_job_coverage" | "recommend_jobs" | "analyze_job_fit" | "optimize_resume" | "search_jobs" | "get_job";
   description: string;
   inputSchema: Record<string, unknown>;
+  /** Every tool only reads: nothing here applies, submits, or writes on the candidate's behalf. */
+  annotations: { readOnlyHint: true; destructiveHint: false; idempotentHint: true; openWorldHint: boolean };
 }
 
+/** Tools that reach employer boards over the network are open-world; the rest read the local index. */
+const annotationsFor = (name: ToolDefinition["name"]): ToolDefinition["annotations"] =>
+  ({ readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: name === "prepare_job_search" || name === "recommend_jobs" || name === "get_job" });
+
 interface JobWorkflows {
   prepareJobSearch(input: unknown): Promise<PrepareJobSearchResult>;
   getJobCoverage(input: unknown): Promise<JobCoverageSummary>;
@@ -22,7 +28,7 @@ interface JobWorkflows {
 }
 
 export function createToolHandler(catalog: Catalog, workflows: JobWorkflows, options: { onCall?(name: string, input: Record<string, unknown>, result: unknown): void } = {}) {
-  const definitions: ToolDefinition[] = [
+  const definitions: Array<Omit<ToolDefinition, "annotations">> = [
     {
       name: "prepare_job_search",
       description: "Initialize the local job index: the first call downloads the shared index of every verified source (thousands of employers) and returns ready; only missing or stale sources are crawled, in batches of at most 25. Report coverage from the result rather than calling again once nextAction is ready. This may use the network and write only job data under the local Openings data directory; it never processes a resume.",
@@ -119,7 +125,7 @@ export function createToolHandler(catalog: Catalog, workflows: JobWorkflows, opt
       description: "Get the full description and application URL for a job returned by recommend_jobs or search_jobs.",
       inputSchema: {
         type: "object",
-        properties: { id: { type: "string", description: "Stable job id returned by search_jobs" } },
+        properties: { id: { type: "string", description: "Stable job id returned by search_jobs or recommend_jobs (jobId is accepted too)" } },
         required: ["id"],
         additionalProperties: false,
       },
@@ -127,7 +133,7 @@ export function createToolHandler(catalog: Catalog, workflows: JobWorkflows, opt
   ];
 
   return {
-    list: () => definitions,
+    list: () => definitions.map((definition) => ({ ...definition, annotations: annotationsFor(definition.name) })),
     async call(name: string, input: Record<string, unknown>) {
       const result = await dispatch(name, input);
       try { options.onCall?.(name, input, result); } catch { /* usage reporting never affects a tool result */ }
@@ -163,9 +169,11 @@ export function createToolHandler(catalog: Catalog, workflows: JobWorkflows, opt
         };
       }
       if (name === "get_job") {
-        assertToolKeys(input, ["id"], "get_job");
-        if (typeof input.id !== "string" || !input.id) throw new Error("get_job requires a non-empty id");
-        return { job: await catalog.get(input.id) };
+        // analyze_job_fit and optimize_resume call it jobId, so accept either spelling rather than fail on a near miss.
+        assertToolKeys(input, ["id", "jobId"], "get_job");
+        const id = typeof input.id === "string" && input.id ? input.id : input.jobId;
+        if (typeof id !== "string" || !id) throw new Error("get_job requires a non-empty id");
+        return { job: await catalog.get(id) };
       }
       throw new Error(`Unknown tool: ${name}`);
   }

package/src/version.ts

@@ -1 +1 @@
-export const VERSION = "0.1.34";
+export const VERSION = "0.1.35";