openings 0.1.54 → 0.1.56

package/package.json

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

@@ -31,6 +31,14 @@ interface CrawlerOptions {
    * including one whose board states no date at all. The nightly crawl keeps the 30-day default so it spends
    * its small budget on what is new; the catch-up pass lifts it to reach roles still listed but long posted. */
   describeMaxAgeDays?: number;
+  /**
+   * Whether the snapshot written to disk keeps the description text. A local install needs it: the snapshot is
+   * its only copy. A server crawl reports every source to an aggregator that stores them, so keeping a second
+   * copy only costs memory — on one box the file reached 1.3 GB and parsing it needed more RAM than the machine
+   * had, which killed the crawl for seven nights. The experience read out of each description is always kept,
+   * so a role already read is never fetched twice.
+   */
+  retainDescriptions?: boolean;
   pacingNow?: () => number;
   pacingSleep?: (delayMs: number) => Promise<void>;
   now?: () => Date;
@@ -190,7 +198,9 @@ export function createCrawler(options: CrawlerOptions): Crawler {
         cached: considered - eligibleSources.length, deferred: eligibleSources.length - selectedSources.length,
         succeeded, failed: finalFailures, sources: selectedSources.map((source) => metrics.get(source.slug)!),
       };
-      await options.store.write({ version: 1, updatedAt: finishedAt, partitions, lastCrawl: report });
+      // Reporting below still sends the full partitions; only the copy kept on disk is lightened.
+      const stored = options.retainDescriptions === false ? withoutDescriptions(partitions) : partitions;
+      await options.store.write({ version: 1, updatedAt: finishedAt, partitions: stored, lastCrawl: report });
       if (options.onCrawled) {
         const crawled = selectedSources.filter((source) => metrics.get(source.slug)!.status === "succeeded");
         // Four at a time: sending a thousand reports at once made the largest ones time out while the aggregator queued them.
@@ -204,6 +214,18 @@ export function createCrawler(options: CrawlerOptions): Crawler {
 }
 
 // ponytail: per-source caps keep one crawl bounded; a big backlog (first run) drains over a few nights.
+/**
+ * The same partitions with the description text left out. Everything the next crawl needs to avoid re-reading a
+ * description — the experience and its version — is kept, so this costs nothing but the bytes.
+ */
+function withoutDescriptions(partitions: JobSnapshot["partitions"]): JobSnapshot["partitions"] {
+  const out: JobSnapshot["partitions"] = {};
+  for (const [slug, partition] of Object.entries(partitions)) {
+    out[slug] = { ...partition, jobs: partition.jobs.map((job) => (job.description ? { ...job, description: "" } : job)) };
+  }
+  return out;
+}
+
 /** Defaults for the nightly crawl, where the point is to keep every source moving rather than finish any one. */
 const DESCRIBE_LIMIT = 150;
 const DESCRIBE_MAX_AGE_DAYS = 30;

package/src/index.ts

@@ -40,7 +40,7 @@ export { createJobCoverageReader, projectJobCoverage } from "./job-coverage.ts";
 export type { CountryJobCoverage, JobCoverageSummary } from "./job-coverage.ts";
 export { createHostedRuntime } from "./runtime.ts";
 export type { SnapshotStore } from "./crawler.ts";
-export { createToolHandler } from "./tools.ts";
+export { createToolHandler, SCOPES, scopeForTool, type Scope } from "./tools.ts";
 export { createMcpHandler, FLOW_INSTRUCTIONS } from "./mcp.ts";
 export type { UpdateNotice } from "./update-check.ts";
 export { VERSION } from "./version.ts";

package/src/local-jobs.ts

@@ -20,6 +20,7 @@ interface LocalJobsOptions {
   describeLimit?: number;
   describeBudgetMs?: number;
   describeMaxAgeDays?: number;
+  retainDescriptions?: boolean;
   now?: () => Date;
   onCrawled?(source: Company, partition: JobPartition): void | Promise<void>;
 }

package/src/runtime.ts

@@ -41,6 +41,8 @@ export function createRuntime(options: { dataDir?: string; concurrency?: number;
     describeLimit: positiveEnv("OPENINGS_DESCRIBE_LIMIT"),
     describeBudgetMs: positiveEnv("OPENINGS_DESCRIBE_BUDGET_MS"),
     describeMaxAgeDays: wholeEnv("OPENINGS_DESCRIBE_MAX_AGE_DAYS"),
+    // Server crawls set this off: the aggregator they report to is the system of record for descriptions.
+    retainDescriptions: process.env.OPENINGS_RETAIN_DESCRIPTIONS !== "off",
     onCrawled,
   });
   const recommender = createJobRecommender({ sources: companies, store, crawl: local.crawl });

package/src/tools.ts

@@ -33,7 +33,35 @@ interface JobWorkflows {
   optimizeResume(input: unknown): Promise<OptimizeResumeResult>;
 }
 
-export function createToolHandler(catalog: Catalog, workflows: JobWorkflows, options: { onCall?(name: string, input: Record<string, unknown>, result: unknown): void } = {}) {
+/**
+ * What a token is allowed to reach. The split is on what the tool touches, not on what it changes: four tools read
+ * job data and nothing else, three parse a candidate's resume. A client that only wants job search should be able
+ * to say so and be held to it, which is the promise we already make in prose and could not enforce.
+ */
+export const SCOPES = { jobs: "jobs.read", resume: "resume.analyze" } as const;
+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,
+};
+
+/** The scope a tool needs, for a caller that wants to explain the boundary rather than discover it by refusal. */
+export function scopeForTool(name: string): Scope | undefined {
+  return TOOL_SCOPE[name as ToolDefinition["name"]];
+}
+
+export function createToolHandler(catalog: Catalog, workflows: JobWorkflows, options: {
+  onCall?(name: string, input: Record<string, unknown>, result: unknown): void;
+  /**
+   * Scopes this token was granted. Undefined means every tool, which is deliberate: tokens issued before the
+   * split carry no scope claim, and refusing them would break every client that already works. Only a token
+   * that states its scopes is held to them.
+   */
+  scopes?: readonly string[];
+} = {}) {
+  const granted = options.scopes === undefined ? undefined : new Set(options.scopes);
+  const allowed = (name: ToolDefinition["name"]) => granted === undefined || granted.has(TOOL_SCOPE[name]);
   const definitions: Array<Omit<ToolDefinition, "annotations">> = [
     {
       name: "prepare_job_search",
@@ -209,8 +237,14 @@ export function createToolHandler(catalog: Catalog, workflows: JobWorkflows, opt
   ];
 
   return {
-    list: () => definitions.map((definition) => ({ ...definition, annotations: annotationsFor(definition.name) })),
+    // 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))
+      .map((definition) => ({ ...definition, annotations: annotationsFor(definition.name) })),
     async call(name: string, input: Record<string, unknown>) {
+      const needed = TOOL_SCOPE[name as ToolDefinition["name"]];
+      if (needed && !allowed(name as ToolDefinition["name"])) {
+        throw new Error(`${name} needs the ${needed} scope, which this connection was not granted. Reconnect and allow it.`);
+      }
       const result = await dispatch(name, input);
       try { options.onCall?.(name, input, result); } catch { /* usage reporting never affects a tool result */ }
       return result;

package/src/version.ts

@@ -1 +1 @@
-export const VERSION = "0.1.54";
+export const VERSION = "0.1.56";