@profullstack/agenticjobs 0.1.0

package/dist/directory/announce.d.ts

@@ -0,0 +1,32 @@
+/**
+ * The heartbeat, from the instance's side.
+ *
+ * An instance sends one field — its own URL — and the directory goes and reads
+ * the rest for itself. That asymmetry is the whole design: there is nothing in
+ * an announcement worth forging, so there is nothing to authenticate.
+ *
+ * Announcing is opt-in. An instance with ANNOUNCE unset never contacts
+ * anything, which is the correct default for a company running this for its
+ * own openings.
+ */
+export interface Announcer {
+    stop: () => void;
+    /** Exposed so the CLI can announce once and exit. */
+    beat: () => Promise<boolean>;
+}
+export interface AnnounceOptions {
+    directoryUrl: string;
+    publicUrl: string;
+    intervalMs?: number;
+    log?: (message: string) => void;
+}
+export declare function announceOnce(directoryUrl: string, publicUrl: string): Promise<void>;
+/**
+ * Announce now, then keep announcing.
+ *
+ * Failures are logged once and retried on the next beat rather than escalated:
+ * a directory being down is not a reason for a job board to stop serving jobs,
+ * and the only consequence is that the instance drops off a list until it
+ * comes back.
+ */
+export declare function startAnnouncing(options: AnnounceOptions): Announcer;

package/dist/directory/announce.js

@@ -0,0 +1,59 @@
+/**
+ * The heartbeat, from the instance's side.
+ *
+ * An instance sends one field — its own URL — and the directory goes and reads
+ * the rest for itself. That asymmetry is the whole design: there is nothing in
+ * an announcement worth forging, so there is nothing to authenticate.
+ *
+ * Announcing is opt-in. An instance with ANNOUNCE unset never contacts
+ * anything, which is the correct default for a company running this for its
+ * own openings.
+ */
+import { HEARTBEAT_MS } from "../schema/instance.js";
+import { fetchJson, FetchProblem } from "./fetch.js";
+export async function announceOnce(directoryUrl, publicUrl) {
+    await fetchJson(`${directoryUrl.replace(/\/+$/, '')}/api/v1/directory/announce`, {
+        method: 'POST',
+        body: { url: publicUrl },
+        maxBytes: 64 * 1024,
+    });
+}
+/**
+ * Announce now, then keep announcing.
+ *
+ * Failures are logged once and retried on the next beat rather than escalated:
+ * a directory being down is not a reason for a job board to stop serving jobs,
+ * and the only consequence is that the instance drops off a list until it
+ * comes back.
+ */
+export function startAnnouncing(options) {
+    const interval = options.intervalMs ?? HEARTBEAT_MS;
+    const log = options.log ?? ((message) => console.log(message));
+    let lastError = null;
+    const beat = async () => {
+        try {
+            await announceOnce(options.directoryUrl, options.publicUrl);
+            if (lastError !== null) {
+                log(`directory: ${options.directoryUrl} is answering again`);
+                lastError = null;
+            }
+            return true;
+        }
+        catch (error) {
+            const message = error instanceof FetchProblem ? error.message : String(error);
+            // Only the first occurrence of a given failure is logged. A directory
+            // that is down for a day would otherwise write 144 identical lines.
+            if (message !== lastError) {
+                log(`directory: could not announce to ${options.directoryUrl}: ${message}`);
+                lastError = message;
+            }
+            return false;
+        }
+    };
+    void beat();
+    const timer = setInterval(() => void beat(), interval);
+    // Announcing must never be the reason a process stays alive.
+    timer.unref?.();
+    return { stop: () => clearInterval(timer), beat };
+}
+//# sourceMappingURL=announce.js.map

package/dist/directory/announce.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"announce.js","sourceRoot":"","sources":["../../src/directory/announce.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AACrD,OAAO,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAerD,MAAM,CAAC,KAAK,UAAU,YAAY,CAAC,YAAoB,EAAE,SAAiB;IACxE,MAAM,SAAS,CAAC,GAAG,YAAY,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,4BAA4B,EAAE;QAC/E,MAAM,EAAE,MAAM;QACd,IAAI,EAAE,EAAE,GAAG,EAAE,SAAS,EAAE;QACxB,QAAQ,EAAE,EAAE,GAAG,IAAI;KACpB,CAAC,CAAC;AACL,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,eAAe,CAAC,OAAwB;IACtD,MAAM,QAAQ,GAAG,OAAO,CAAC,UAAU,IAAI,YAAY,CAAC;IACpD,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,IAAI,CAAC,CAAC,OAAe,EAAE,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC;IACvE,IAAI,SAAS,GAAkB,IAAI,CAAC;IAEpC,MAAM,IAAI,GAAG,KAAK,IAAsB,EAAE;QACxC,IAAI,CAAC;YACH,MAAM,YAAY,CAAC,OAAO,CAAC,YAAY,EAAE,OAAO,CAAC,SAAS,CAAC,CAAC;YAC5D,IAAI,SAAS,KAAK,IAAI,EAAE,CAAC;gBACvB,GAAG,CAAC,cAAc,OAAO,CAAC,YAAY,qBAAqB,CAAC,CAAC;gBAC7D,SAAS,GAAG,IAAI,CAAC;YACnB,CAAC;YACD,OAAO,IAAI,CAAC;QACd,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,OAAO,GAAG,KAAK,YAAY,YAAY,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;YAC9E,sEAAsE;YACtE,oEAAoE;YACpE,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;gBAC1B,GAAG,CAAC,oCAAoC,OAAO,CAAC,YAAY,KAAK,OAAO,EAAE,CAAC,CAAC;gBAC5E,SAAS,GAAG,OAAO,CAAC;YACtB,CAAC;YACD,OAAO,KAAK,CAAC;QACf,CAAC;IACH,CAAC,CAAC;IAEF,KAAK,IAAI,EAAE,CAAC;IACZ,MAAM,KAAK,GAAG,WAAW,CAAC,GAAG,EAAE,CAAC,KAAK,IAAI,EAAE,EAAE,QAAQ,CAAC,CAAC;IACvD,6DAA6D;IAC7D,KAAK,CAAC,KAAK,EAAE,EAAE,CAAC;IAEhB,OAAO,EAAE,IAAI,EAAE,GAAG,EAAE,CAAC,aAAa,CAAC,KAAK,CAAC,EAAE,IAAI,EAAE,CAAC;AACpD,CAAC"}

package/dist/directory/federate.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Searching more than one instance at once.
+ *
+ * This is what the directory is for. A candidate should be able to ask one
+ * question and have it answered by every board that opted in, without any of
+ * those boards having to share a database, and without a slow or hostile one
+ * being able to hold up the answer.
+ *
+ * The rules that make that true:
+ *
+ *  - every instance is queried in parallel, with its own timeout;
+ *  - one instance failing removes that instance from the results and nothing
+ *    else, and the failure is reported rather than swallowed, so a client can
+ *    say "11 of 12 boards answered" instead of quietly showing less;
+ *  - results carry the instance they came from, because a job on someone
+ *    else's board is applied for on someone else's board.
+ */
+import type { Job, JobQuery } from '../schema/index.ts';
+import type { InstanceDescriptor } from '../schema/instance.ts';
+export interface FederatedJob {
+    job: Job;
+    /** Origin of the instance that served it. */
+    instance: string;
+    instanceName: string;
+    /** Where a human or an agent goes to apply. Always on the origin board. */
+    url: string;
+}
+export interface FederatedSearch {
+    jobs: FederatedJob[];
+    /** One entry per instance queried, in the order they were asked. */
+    sources: SourceResult[];
+    /** Sum of `total` across the instances that answered. */
+    total: number;
+}
+export interface SourceResult {
+    instance: string;
+    name: string;
+    ok: boolean;
+    count: number;
+    total: number;
+    ms: number;
+    error: string | null;
+}
+export interface FederateOptions {
+    timeoutMs?: number;
+    concurrency?: number;
+    /** Cap per instance, so one busy board cannot crowd out eleven others. */
+    perInstance?: number;
+    signal?: AbortSignal;
+}
+interface Target {
+    url: string;
+    name: string;
+    search: string;
+}
+export declare function targetsFromDescriptors(descriptors: InstanceDescriptor[]): Target[];
+export declare function targetsFromUrls(urls: string[]): Target[];
+export declare function federatedSearch(targets: Target[], query: JobQuery, options?: FederateOptions): Promise<FederatedSearch>;
+export {};

package/dist/directory/federate.js

@@ -0,0 +1,126 @@
+/**
+ * Searching more than one instance at once.
+ *
+ * This is what the directory is for. A candidate should be able to ask one
+ * question and have it answered by every board that opted in, without any of
+ * those boards having to share a database, and without a slow or hostile one
+ * being able to hold up the answer.
+ *
+ * The rules that make that true:
+ *
+ *  - every instance is queried in parallel, with its own timeout;
+ *  - one instance failing removes that instance from the results and nothing
+ *    else, and the failure is reported rather than swallowed, so a client can
+ *    say "11 of 12 boards answered" instead of quietly showing less;
+ *  - results carry the instance they came from, because a job on someone
+ *    else's board is applied for on someone else's board.
+ */
+import { queryToParams } from "../schema/query.js";
+import { fetchJson, FetchProblem } from "./fetch.js";
+export function targetsFromDescriptors(descriptors) {
+    return descriptors.map((descriptor) => ({
+        url: descriptor.url,
+        name: descriptor.name,
+        search: descriptor.endpoints.search,
+    }));
+}
+export function targetsFromUrls(urls) {
+    return urls.map((url) => {
+        const origin = url.replace(/\/+$/, '');
+        return { url: origin, name: hostOf(origin), search: `${origin}/api/v1/jobs` };
+    });
+}
+function hostOf(url) {
+    try {
+        return new URL(url).hostname;
+    }
+    catch {
+        return url;
+    }
+}
+export async function federatedSearch(targets, query, options = {}) {
+    const perInstance = Math.min(100, Math.max(1, options.perInstance ?? query.limit));
+    const concurrency = Math.min(24, Math.max(1, options.concurrency ?? 8));
+    const params = queryToParams({ ...query, limit: perInstance, offset: 0 });
+    const sources = targets.map((target) => ({
+        instance: target.url,
+        name: target.name,
+        ok: false,
+        count: 0,
+        total: 0,
+        ms: 0,
+        error: null,
+    }));
+    const collected = [];
+    let cursor = 0;
+    const workers = Array.from({ length: Math.min(concurrency, targets.length) }, async () => {
+        for (;;) {
+            const index = cursor;
+            cursor += 1;
+            const target = targets[index];
+            const source = sources[index];
+            if (target === undefined || source === undefined)
+                return;
+            const started = Date.now();
+            try {
+                const payload = await fetchJson(`${target.search}?${params.toString()}`, {
+                    ...(options.timeoutMs === undefined ? {} : { timeoutMs: options.timeoutMs }),
+                    ...(options.signal === undefined ? {} : { signal: options.signal }),
+                });
+                const page = payload;
+                const items = Array.isArray(page.items) ? page.items : [];
+                for (const item of items.slice(0, perInstance)) {
+                    const job = item;
+                    // A malformed row from one instance drops that row, not the answer.
+                    if (typeof job?.slug !== 'string' || typeof job?.title !== 'string')
+                        continue;
+                    collected.push({
+                        job,
+                        instance: target.url,
+                        instanceName: target.name,
+                        url: `${target.url}/jobs/${job.slug}`,
+                    });
+                    source.count += 1;
+                }
+                source.total = Number(page.total) || source.count;
+                source.ok = true;
+            }
+            catch (error) {
+                source.error = error instanceof FetchProblem ? error.message : String(error);
+            }
+            finally {
+                source.ms = Date.now() - started;
+            }
+        }
+    });
+    await Promise.all(workers);
+    sortMerged(collected, query);
+    return {
+        jobs: collected.slice(query.offset, query.offset + query.limit),
+        sources,
+        total: sources.reduce((sum, source) => sum + (source.ok ? source.total : 0), 0),
+    };
+}
+/**
+ * Merge-sort the combined set.
+ *
+ * Each instance already sorted its own page, but "recent" across twelve boards
+ * is not any one board's order, so it has to be redone here. Relevance cannot
+ * be: the rank came from each instance's own corpus statistics and the numbers
+ * are not comparable between them, so a relevance search falls back to recency
+ * once merged rather than pretending otherwise.
+ */
+function sortMerged(jobs, query) {
+    if (query.sort === 'salary') {
+        jobs.sort((a, b) => topSalary(b.job) - topSalary(a.job));
+        return;
+    }
+    jobs.sort((a, b) => published(b.job) - published(a.job));
+}
+function published(job) {
+    return Date.parse(job.publishedAt ?? job.createdAt) || 0;
+}
+function topSalary(job) {
+    return job.salary.max ?? job.salary.min ?? 0;
+}
+//# sourceMappingURL=federate.js.map

package/dist/directory/federate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"federate.js","sourceRoot":"","sources":["../../src/directory/federate.ts"],"names":[],"mappings":"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"}

package/dist/directory/fetch.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Fetching from another instance.
+ *
+ * Everything here talks to a URL a stranger supplied, so the rules are the
+ * same in all three directions (a directory reading an instance, an instance
+ * announcing to a directory, a client fanning a search out): a short timeout,
+ * a size cap, no redirect to a different origin, and no trust in anything the
+ * response says about where it came from.
+ */
+import { type InstanceDescriptor } from '../schema/instance.ts';
+export declare const USER_AGENT = "agenticjobs/0.1.0 (+https://agenticjobs.work)";
+export declare class FetchProblem extends Error {
+}
+export interface FetchOptions {
+    timeoutMs?: number;
+    maxBytes?: number;
+    signal?: AbortSignal;
+    method?: 'GET' | 'POST';
+    body?: unknown;
+}
+/**
+ * A JSON GET with the safety rails on.
+ *
+ * Redirects are followed manually so that a redirect off the origin can be
+ * refused: allowing one would let any listed instance point the directory's
+ * HTTP client at an address the origin check already rejected.
+ */
+export declare function fetchJson(url: string, options?: FetchOptions): Promise<unknown>;
+/**
+ * Read an instance's descriptor from the instance itself.
+ *
+ * The URL it is parsed against is where we fetched it, never what the document
+ * claims, so an instance cannot announce itself as somebody else.
+ */
+export declare function fetchDescriptor(origin: string, options?: FetchOptions): Promise<InstanceDescriptor>;

package/dist/directory/fetch.js

@@ -0,0 +1,138 @@
+/**
+ * Fetching from another instance.
+ *
+ * Everything here talks to a URL a stranger supplied, so the rules are the
+ * same in all three directions (a directory reading an instance, an instance
+ * announcing to a directory, a client fanning a search out): a short timeout,
+ * a size cap, no redirect to a different origin, and no trust in anything the
+ * response says about where it came from.
+ */
+import { publishable, WELL_KNOWN_PATH } from "../schema/instance.js";
+import { parseDescriptor } from "../schema/instance.js";
+import { SOFTWARE_NAME, VERSION } from "../config.js";
+export const USER_AGENT = `${SOFTWARE_NAME}/${VERSION} (+https://agenticjobs.work)`;
+/** Big enough for a page of jobs, small enough that nobody can wedge a peer. */
+const MAX_BYTES = 2 * 1024 * 1024;
+const TIMEOUT_MS = 8000;
+export class FetchProblem extends Error {
+}
+/**
+ * A JSON GET with the safety rails on.
+ *
+ * Redirects are followed manually so that a redirect off the origin can be
+ * refused: allowing one would let any listed instance point the directory's
+ * HTTP client at an address the origin check already rejected.
+ */
+export async function fetchJson(url, options = {}) {
+    const origin = publishable(url);
+    if (origin === null)
+        throw new FetchProblem(`${url} is not an address we will fetch`);
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), options.timeoutMs ?? TIMEOUT_MS);
+    const abort = () => controller.abort();
+    options.signal?.addEventListener('abort', abort, { once: true });
+    try {
+        let target = url;
+        for (let hop = 0; hop < 3; hop += 1) {
+            const response = await fetch(target, {
+                method: options.method ?? 'GET',
+                redirect: 'manual',
+                signal: controller.signal,
+                headers: {
+                    accept: 'application/json',
+                    'user-agent': USER_AGENT,
+                    ...(options.body === undefined ? {} : { 'content-type': 'application/json' }),
+                },
+                ...(options.body === undefined ? {} : { body: JSON.stringify(options.body) }),
+            });
+            if (response.status >= 300 && response.status < 400) {
+                const location = response.headers.get('location');
+                if (location === null)
+                    throw new FetchProblem(`${target} redirected with no location`);
+                const next = new URL(location, target);
+                if (next.origin !== origin.origin) {
+                    throw new FetchProblem(`${target} redirected off its own origin, to ${next.origin}`);
+                }
+                target = next.toString();
+                continue;
+            }
+            if (!response.ok)
+                throw new FetchProblem(`${target} answered ${response.status}`);
+            // Content-Length is a hint from the other end, so the body is measured
+            // as it arrives rather than trusted up front.
+            const declared = Number(response.headers.get('content-length') ?? '0');
+            const cap = options.maxBytes ?? MAX_BYTES;
+            if (Number.isFinite(declared) && declared > cap) {
+                throw new FetchProblem(`${target} declared ${declared} bytes`);
+            }
+            const text = await readCapped(response, cap);
+            try {
+                return JSON.parse(text);
+            }
+            catch {
+                throw new FetchProblem(`${target} did not answer with JSON`);
+            }
+        }
+        throw new FetchProblem(`${url} redirected too many times`);
+    }
+    catch (error) {
+        if (error instanceof FetchProblem)
+            throw error;
+        if (error instanceof Error && error.name === 'AbortError') {
+            throw new FetchProblem(`${url} timed out`);
+        }
+        throw new FetchProblem(`${url}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    finally {
+        clearTimeout(timer);
+        options.signal?.removeEventListener('abort', abort);
+    }
+}
+async function readCapped(response, cap) {
+    const body = response.body;
+    if (body === null)
+        return '';
+    const reader = body.getReader();
+    const chunks = [];
+    let total = 0;
+    for (;;) {
+        const { done, value } = await reader.read();
+        if (done)
+            break;
+        if (value === undefined)
+            continue;
+        total += value.byteLength;
+        if (total > cap) {
+            await reader.cancel();
+            throw new FetchProblem(`response exceeded ${cap} bytes`);
+        }
+        chunks.push(value);
+    }
+    const joined = new Uint8Array(total);
+    let offset = 0;
+    for (const chunk of chunks) {
+        joined.set(chunk, offset);
+        offset += chunk.byteLength;
+    }
+    return new TextDecoder().decode(joined);
+}
+/**
+ * Read an instance's descriptor from the instance itself.
+ *
+ * The URL it is parsed against is where we fetched it, never what the document
+ * claims, so an instance cannot announce itself as somebody else.
+ */
+export async function fetchDescriptor(origin, options = {}) {
+    const base = publishable(origin);
+    if (base === null)
+        throw new FetchProblem(`${origin} is not an address we will list`);
+    const payload = await fetchJson(`${base.origin}${WELL_KNOWN_PATH}`, {
+        ...options,
+        maxBytes: 64 * 1024,
+    });
+    const descriptor = parseDescriptor(payload, base.origin);
+    if (descriptor === null)
+        throw new FetchProblem(`${base.origin} did not serve a usable descriptor`);
+    return descriptor;
+}
+//# sourceMappingURL=fetch.js.map

package/dist/directory/fetch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fetch.js","sourceRoot":"","sources":["../../src/directory/fetch.ts"],"names":[],"mappings":"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"}

package/dist/directory/index.d.ts

@@ -0,0 +1,4 @@
+export * from './fetch.ts';
+export * from './registry.ts';
+export * from './announce.ts';
+export * from './federate.ts';

package/dist/directory/index.js

@@ -0,0 +1,5 @@
+export * from "./fetch.js";
+export * from "./registry.js";
+export * from "./announce.js";
+export * from "./federate.js";
+//# sourceMappingURL=index.js.map

package/dist/directory/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/directory/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,eAAe,CAAC;AAC9B,cAAc,eAAe,CAAC;AAC9B,cAAc,eAAe,CAAC"}

package/dist/directory/registry.d.ts

@@ -0,0 +1,55 @@
+/**
+ * The directory: which instances exist.
+ *
+ * An instance announces itself by sending nothing but its own URL. The
+ * directory then fetches that URL's descriptor itself and records what it
+ * actually read. nixamp's stream directory trusts the announcement body, which
+ * is right for a stream whose only claim is "I am playing something"; here an
+ * announcement carries a name, a topic list and a job count, and a board that
+ * could announce someone else's name with its own URL underneath would be a
+ * phishing primitive on day one.
+ */
+import type pg from 'pg';
+import { type InstanceListing } from '../schema/instance.ts';
+export declare class Blocked extends Error {
+}
+/**
+ * Record an announcement.
+ *
+ * Idempotent per origin: an instance that heartbeats every ten minutes updates
+ * one row forever rather than accumulating a history of itself.
+ */
+export declare function announce(pool: pg.Pool, rawUrl: string): Promise<InstanceListing>;
+export interface ListOptions {
+    topic?: string | null;
+    q?: string | null;
+    onlineOnly?: boolean;
+    limit?: number;
+    offset?: number;
+}
+export declare function listInstances(pool: pg.Pool, options?: ListOptions): Promise<InstanceListing[]>;
+export declare function getInstance(pool: pg.Pool, url: string): Promise<InstanceListing | null>;
+/** Every topic the directory knows about, most-used first. */
+export declare function listTopics(pool: pg.Pool): Promise<{
+    topic: string;
+    instances: number;
+}[]>;
+export interface SweepResult {
+    checked: number;
+    ok: number;
+    failed: number;
+    dropped: number;
+}
+/**
+ * Re-read every instance the directory knows about.
+ *
+ * A failure raises a counter rather than deleting the row: an instance is
+ * allowed to be down for a redeploy without losing its place, and the URL only
+ * goes away after MAX_FAILURES consecutive misses, which at the sweep interval
+ * is the better part of a day.
+ */
+export declare function sweep(pool: pg.Pool, options?: {
+    limit?: number;
+    concurrency?: number;
+}): Promise<SweepResult>;
+export declare function blockInstance(pool: pg.Pool, url: string, reason: string): Promise<boolean>;