salt-agent-sdk 0.1.0 → 0.19.0

package/dist/recovery.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"recovery.js","sourceRoot":"","sources":["../src/recovery.ts"],"names":[],"mappings":";;AA4EA,sDAEC;AAQD,0CAWC;AAjGD,4EAA4E;AAC5E,4EAA4E;AAC5E,2DAA2D;AAC3D,EAAE;AACF,yEAAyE;AACzE,6DAA6D;AAC7D,iEAAiE;AACjE,4EAA4E;AAC5E,uEAAuE;AACvE,qDAAqD;AACrD,2EAA2E;AAC3E,6CAA6C;AAC7C,uEAAuE;AACvE,EAAE;AACF,mDAAmD;AACnD,6EAA6E;AAC7E,6CAA6C;AAC7C,EAAE;AACF,2EAA2E;AAC3E,+EAA+E;AAC/E,yEAAyE;AACzE,EAAE;AACF,sEAAsE;AACtE,2EAA2E;AAC3E,2EAA2E;AAC3E,6EAA6E;AAC7E,0EAA0E;AAC1E,gFAAgF;AAChF,EAAE;AACF,6EAA6E;AAC7E,8EAA8E;AAC9E,0EAA0E;AAC1E,6EAA6E;AAC7E,iDAAiD;AACjD,2CAAkD;AAyClD,2GAA2G;AACpG,KAAK,UAAU,qBAAqB,CAAC,aAAqB,EAAE,kBAA0B;IAC3F,OAAO,IAAA,sBAAU,EAAC,aAAa,EAAE,CAAC,kBAAkB,CAAC,CAAC,CAAC;AACzD,CAAC;AAED;;;;;GAKG;AACI,KAAK,UAAU,eAAe,CAAC,MAKrC;IACC,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC,QAAQ,CAAC,KAAK,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,YAAY,CAAC,CAAC,CAAC;IACjG,IAAI,CAAC,IAAI;QAAE,MAAM,IAAI,KAAK,CAAC,kCAAkC,CAAC,CAAC;IAC/D,MAAM,KAAK,GAAG,MAAM,IAAA,mBAAO,EAAC,IAAI,CAAC,eAAe,EAAE,MAAM,CAAC,UAAU,EAAE,MAAM,CAAC,UAAU,CAAC,CAAC;IACxF,IAAI,CAAC,KAAK;QAAE,MAAM,IAAI,KAAK,CAAC,6CAA6C,CAAC,CAAC;IAC3E,OAAO,qBAAqB,CAAC,KAAK,EAAE,MAAM,CAAC,OAAO,CAAC,oBAAoB,CAAC,CAAC;AAC3E,CAAC"}

package/dist/register.d.ts

@@ -0,0 +1,32 @@
+import { type SaltUser } from "./client.js";
+import type { AgentIdentity, IdentityStore } from "./identities.js";
+export interface RegisterAgentOptions {
+    /** Defaults to https://saltapp.ai. */
+    baseUrl?: string;
+    username: string;
+    /** Must not start with "salt". */
+    displayName: string;
+    /** List the agent in Salt's directory. Defaults to unlisted. */
+    listed?: boolean;
+    /** Omit for socket mode (no public URL needed). */
+    webhook?: string;
+    /** Protects the private key at rest. Defaults to a fresh random one, returned as `passphrase`. */
+    passphrase?: string;
+    /** When given, the new identity is registered (and persisted) there. */
+    identities?: IdentityStore;
+    /** Override fetch (tests). */
+    fetchImpl?: typeof fetch;
+}
+export interface RegisteredAgent {
+    agent: SaltUser;
+    /** Shown by Salt exactly once. */
+    apiKey: string;
+    privateKey: string;
+    publicKey: string;
+    /** The passphrase protecting `privateKey`. */
+    passphrase: string;
+    /** Ready for `identities.register` (already done when `identities` was passed). */
+    identity: AgentIdentity;
+}
+export declare function registerAgent(options: RegisterAgentOptions): Promise<RegisteredAgent>;
+//# sourceMappingURL=register.d.ts.map

package/dist/register.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"register.d.ts","sourceRoot":"","sources":["../src/register.ts"],"names":[],"mappings":"AAQA,OAAO,EAAgB,KAAK,QAAQ,EAAE,MAAM,aAAa,CAAC;AAC1D,OAAO,KAAK,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAEpE,MAAM,WAAW,oBAAoB;IACnC,sCAAsC;IACtC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,kCAAkC;IAClC,WAAW,EAAE,MAAM,CAAC;IACpB,gEAAgE;IAChE,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,mDAAmD;IACnD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,kGAAkG;IAClG,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,wEAAwE;IACxE,UAAU,CAAC,EAAE,aAAa,CAAC;IAC3B,8BAA8B;IAC9B,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;CAC1B;AAED,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,QAAQ,CAAC;IAChB,kCAAkC;IAClC,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,8CAA8C;IAC9C,UAAU,EAAE,MAAM,CAAC;IACnB,mFAAmF;IACnF,QAAQ,EAAE,aAAa,CAAC;CACzB;AAUD,wBAAsB,aAAa,CAAC,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAAC,eAAe,CAAC,CA4C3F"}

package/dist/register.js

@@ -0,0 +1,65 @@
+"use strict";
+// registerAgent: a root agent with no human account (POST /auth,
+// account_type "Agent"). Generates the OpenPGP pair locally, reads the
+// current terms/privacy versions from GET /api/v1/config, registers, and
+// hands back everything once. The private key is generated here and never
+// sent anywhere; Salt receives only the public key.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerAgent = registerAgent;
+const node_crypto_1 = require("node:crypto");
+const crypto_js_1 = require("./crypto.js");
+const client_js_1 = require("./client.js");
+async function readJson(res) {
+    try {
+        return await res.json();
+    }
+    catch {
+        return await res.text().catch(() => undefined);
+    }
+}
+async function registerAgent(options) {
+    const baseUrl = (options.baseUrl ?? "https://saltapp.ai").replace(/\/$/, "");
+    const doFetch = options.fetchImpl ?? fetch;
+    const configUrl = `${baseUrl}/api/v1/config`;
+    const configRes = await doFetch(configUrl, { method: "GET" });
+    if (!configRes.ok)
+        throw new client_js_1.SaltApiError("GET", configUrl, configRes.status, await readJson(configRes));
+    const config = (await configRes.json());
+    if (!config.terms_version || !config.privacy_version) {
+        throw new Error("Salt's config did not name the current terms and privacy versions.");
+    }
+    const passphrase = options.passphrase ?? (0, node_crypto_1.randomBytes)(24).toString("hex");
+    const keys = await (0, crypto_js_1.generateKeypair)(passphrase);
+    const body = {
+        account_type: "Agent",
+        username: options.username,
+        display_name: options.displayName,
+        public_key: keys.publicKey,
+        accepted_terms_version: config.terms_version,
+        accepted_privacy_version: config.privacy_version,
+    };
+    if (options.listed !== undefined)
+        body.listed = options.listed;
+    if (options.webhook)
+        body.webhook = options.webhook;
+    // The trailing slash matters on saltfor.com (a bare POST /auth is a CloudFront 403).
+    const url = `${baseUrl}/auth/`;
+    const res = await doFetch(url, { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify(body) });
+    if (!res.ok)
+        throw new client_js_1.SaltApiError("POST", url, res.status, await readJson(res));
+    const agent = (await res.json());
+    if (!agent.api_key)
+        throw new Error("Salt registered the agent but returned no api_key.");
+    const { api_key: apiKey, ...rest } = agent;
+    const identity = {
+        saltAppId: agent.id,
+        username: agent.username,
+        displayName: agent.display_name,
+        apiKey,
+        publicKey: keys.publicKey,
+        privateKey: keys.privateKey,
+    };
+    options.identities?.register(identity);
+    return { agent: rest, apiKey, privateKey: keys.privateKey, publicKey: keys.publicKey, passphrase, identity };
+}
+//# sourceMappingURL=register.js.map

package/dist/register.js.map

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

package/dist/scriptJob.d.ts

@@ -0,0 +1,92 @@
+export interface SeenMarkOptions {
+    /** How long these keys stay "seen", in ms. Overrides the store's default; `Infinity` never expires. */
+    ttlMs?: number;
+}
+/**
+ * What a script job has already sent. Keys are opaque strings (a URL, a post
+ * id); each is remembered until its own expiry, so a feed that republishes an
+ * old story a month later can be told again on purpose.
+ */
+export interface SeenStore {
+    /** True when `key` was marked and has not expired. */
+    has(key: string): Promise<boolean>;
+    /** Marks every key in `keys` seen, each expiring `ttlMs` from now (the store's default when omitted). */
+    mark(keys: string[], opts?: SeenMarkOptions): Promise<void>;
+    /** Forgets `key`, so the next run treats it as new. A no-op when it was never marked. */
+    forget(key: string): Promise<void>;
+}
+export interface SeenStoreOptions {
+    /** Default lifetime of a mark. Defaults to DEFAULT_SEEN_TTL_MS. */
+    ttlMs?: number;
+    /** Clock, for tests. Defaults to Date.now. */
+    now?: () => number;
+}
+/** A mark lasts 30 days unless the store or the call says otherwise. */
+export declare const DEFAULT_SEEN_TTL_MS: number;
+/** In-memory SeenStore. Marks are lost on process restart, and it dedupes only while the SAME instance outlives the runs -- construct it once, not inside the job. */
+export declare function MemorySeenStore(options?: SeenStoreOptions): SeenStore;
+/**
+ * One plain JSON file, `{ "<key>": <expires-at epoch ms, or null for never> }`,
+ * written atomically (temp file + rename, the same convention as
+ * FileSessionStore) so a crash mid-write never leaves half a file. Expired
+ * keys are dropped whenever the file is rewritten. A missing file is an empty
+ * store; an unreadable one throws rather than silently re-sending everything.
+ *
+ * The keys are whatever you pass to `key(item)` -- usually URLs -- stored in
+ * PLAINTEXT (the file is created 0600, its new directories 0700). Run ONE job
+ * per file at a time: writes are queued per instance, in this process only,
+ * so two processes (or two instances) on one file can lose each other's keys.
+ */
+export declare function FileSeenStore(file: string, options?: SeenStoreOptions): SeenStore;
+/** Handed to every source: abort the fetch when it fires (the job's timeout). Sources that ignore it still get raced against the timeout. */
+export interface ScriptSourceContext {
+    signal: AbortSignal;
+}
+/** A source is a plain async function: fetch something, normalise it into items, return them. No model. */
+export type ScriptSource<T> = (ctx: ScriptSourceContext) => Promise<T[]> | T[];
+/** What an item looks like when you don't write `compose`: `title` and `url` make the default list. */
+export interface ScriptJobItem {
+    title?: string;
+    url?: string;
+    [key: string]: unknown;
+}
+export interface ScriptJobLogger {
+    error(msg: string): void;
+}
+export interface ScriptJobOptions<T> {
+    /** Named sources (`{ hackerNews, rss }`) or a plain array. The name is what `failedSources` reports; an array entry is named by its function name, else `source-<index>`. */
+    sources: Record<string, ScriptSource<T>> | Array<ScriptSource<T>>;
+    /** A stable id for an item -- its URL, a post id. Two items with the same key are the same story. */
+    key: (item: T) => string;
+    /** What was already sent. */
+    seen: SeenStore;
+    /** OPTIONAL, and the only place a model may be called. Gets only the NEW items, and only when there are some. Return the text to post; an empty string or null posts nothing and marks nothing. Omit it for a plain list. */
+    compose?: (fresh: T[]) => Promise<string | null | undefined> | string | null | undefined;
+    /** Sends the text to the chat. Throwing leaves every item unseen. */
+    post: (text: string, fresh: T[]) => Promise<unknown> | unknown;
+    /** Per-source timeout in ms. Default DEFAULT_SOURCE_TIMEOUT_MS. */
+    sourceTimeoutMs?: number;
+    /** How long posted items stay seen, in ms. Default: the store's own. */
+    seenTtlMs?: number;
+    logger?: ScriptJobLogger;
+}
+export interface ScriptJobResult {
+    /** Items the sources returned, before dropping any (items from a failed source are not counted). */
+    fetched: number;
+    /** Items not seen before and not duplicated within this run: what compose got. */
+    fresh: number;
+    /** True when `post` ran and succeeded. */
+    posted: boolean;
+    /** Names of the sources that threw or timed out. */
+    failedSources: string[];
+}
+export declare const DEFAULT_SOURCE_TIMEOUT_MS = 20000;
+/** The deterministic text posted when there is no `compose`: one line per item, "- title" and its url beneath. */
+export declare function defaultCompose<T>(fresh: T[], key: (item: T) => string): string;
+/**
+ * Runs one pass of a script job and says what happened. See the header
+ * comment for the contract; the short version: fetch in code, drop what was
+ * sent, compose only if something is new, post, and only then mark seen.
+ */
+export declare function runScriptJob<T>(options: ScriptJobOptions<T>): Promise<ScriptJobResult>;
+//# sourceMappingURL=scriptJob.d.ts.map

package/dist/scriptJob.d.ts.map

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

package/dist/scriptJob.js

@@ -0,0 +1,270 @@
+"use strict";
+// Deterministic-first scheduled work ("script jobs").
+//
+// A recurring job -- a news digest, a price watch, a "tell me when the build
+// is green" -- is mostly plumbing: fetch some pages, drop what was already
+// sent, write it up, post it. Only the "write it up" step ever needs a model,
+// and often not even that. The owner's rule (2026-10-13): "use the right
+// tools for the right jobs; don't use AI as the hammer for everything when
+// deterministic scripts and tools can accommodate just as well."
+//
+// runScriptJob is that rule as a function. The host's scheduler (cron, a
+// Grains wake_me, setInterval) calls it; this file never schedules anything.
+//
+//   sources   plain async functions that fetch and normalise items in code
+//             (no model). Each runs ONCE per call, with a timeout; one that
+//             throws or times out is listed in `failedSources` and the rest
+//             carry on.
+//   key       a stable id for an item (its URL, a post id) -- what `seen`
+//             remembers.
+//   seen      a SeenStore (required): drops items already sent. MemorySeenStore() lives
+//             until the process restarts; FileSeenStore(file) survives it.
+//   compose   OPTIONAL, and the ONLY place a model may be called. It runs
+//             only when there is something new, so a quiet day costs no
+//             tokens. Use the cheapest model that can write the text.
+//             Leave it out and a plain list is posted (see defaultCompose).
+//             Return empty only for a transient failure: empty posts nothing
+//             and marks nothing, so the same items reach the model next run.
+//   post      sends the text to the chat.
+//
+// Nothing new means no compose and no post. Items are marked seen only AFTER
+// post succeeds: a failed post leaves them unseen so the next run retries,
+// and a compose or post error is thrown to the scheduler (re-arm the schedule
+// in a `finally` so a failed run never silently ends it).
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_SOURCE_TIMEOUT_MS = exports.DEFAULT_SEEN_TTL_MS = void 0;
+exports.MemorySeenStore = MemorySeenStore;
+exports.FileSeenStore = FileSeenStore;
+exports.defaultCompose = defaultCompose;
+exports.runScriptJob = runScriptJob;
+const node_crypto_1 = require("node:crypto");
+const fs = __importStar(require("node:fs/promises"));
+const path = __importStar(require("node:path"));
+// Owner-only, like socket.ts's cursor files: the keys are usually URLs.
+const DIR_MODE = 0o700;
+const FILE_MODE = 0o600;
+/** A mark lasts 30 days unless the store or the call says otherwise. */
+exports.DEFAULT_SEEN_TTL_MS = 30 * 24 * 60 * 60 * 1000;
+function expiryFor(now, ttlMs, fallback) {
+    const ttl = ttlMs ?? fallback;
+    return Number.isFinite(ttl) ? now + ttl : null;
+}
+/** In-memory SeenStore. Marks are lost on process restart, and it dedupes only while the SAME instance outlives the runs -- construct it once, not inside the job. */
+function MemorySeenStore(options = {}) {
+    const now = options.now ?? Date.now;
+    const defaultTtl = options.ttlMs ?? exports.DEFAULT_SEEN_TTL_MS;
+    const store = new Map();
+    return {
+        async has(key) {
+            if (!store.has(key))
+                return false;
+            const expiresAt = store.get(key);
+            if (expiresAt != null && expiresAt <= now()) {
+                store.delete(key);
+                return false;
+            }
+            return true;
+        },
+        async mark(keys, opts) {
+            const at = now();
+            for (const key of keys)
+                store.set(key, expiryFor(at, opts?.ttlMs, defaultTtl));
+        },
+        async forget(key) {
+            store.delete(key);
+        },
+    };
+}
+/**
+ * One plain JSON file, `{ "<key>": <expires-at epoch ms, or null for never> }`,
+ * written atomically (temp file + rename, the same convention as
+ * FileSessionStore) so a crash mid-write never leaves half a file. Expired
+ * keys are dropped whenever the file is rewritten. A missing file is an empty
+ * store; an unreadable one throws rather than silently re-sending everything.
+ *
+ * The keys are whatever you pass to `key(item)` -- usually URLs -- stored in
+ * PLAINTEXT (the file is created 0600, its new directories 0700). Run ONE job
+ * per file at a time: writes are queued per instance, in this process only,
+ * so two processes (or two instances) on one file can lose each other's keys.
+ */
+function FileSeenStore(file, options = {}) {
+    const now = options.now ?? Date.now;
+    const defaultTtl = options.ttlMs ?? exports.DEFAULT_SEEN_TTL_MS;
+    async function load() {
+        try {
+            const parsed = JSON.parse(await fs.readFile(file, "utf8"));
+            return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : {};
+        }
+        catch (err) {
+            if (err.code === "ENOENT")
+                return {};
+            throw err;
+        }
+    }
+    async function save(entries) {
+        await fs.mkdir(path.dirname(file), { recursive: true, mode: DIR_MODE });
+        const tmp = `${file}.${process.pid}.${(0, node_crypto_1.randomBytes)(4).toString("hex")}.tmp`;
+        await fs.writeFile(tmp, JSON.stringify(entries, null, 2), { mode: FILE_MODE });
+        await fs.rename(tmp, file);
+    }
+    // Writes are read-modify-write; run them one at a time so two overlapping
+    // marks in this process never lose each other's keys.
+    let chain = Promise.resolve();
+    function serial(fn) {
+        const run = chain.then(fn, fn);
+        chain = run.catch(() => undefined);
+        return run;
+    }
+    return {
+        async has(key) {
+            const entries = await load();
+            if (!Object.prototype.hasOwnProperty.call(entries, key))
+                return false;
+            const expiresAt = entries[key];
+            return expiresAt == null || expiresAt > now();
+        },
+        mark(keys, opts) {
+            return serial(async () => {
+                const at = now();
+                const entries = await load();
+                for (const [k, expiresAt] of Object.entries(entries)) {
+                    if (expiresAt != null && expiresAt <= at)
+                        delete entries[k];
+                }
+                for (const key of keys)
+                    entries[key] = expiryFor(at, opts?.ttlMs, defaultTtl);
+                await save(entries);
+            });
+        },
+        forget(key) {
+            return serial(async () => {
+                const entries = await load();
+                if (!Object.prototype.hasOwnProperty.call(entries, key))
+                    return;
+                delete entries[key];
+                await save(entries);
+            });
+        },
+    };
+}
+exports.DEFAULT_SOURCE_TIMEOUT_MS = 20_000;
+/** The deterministic text posted when there is no `compose`: one line per item, "- title" and its url beneath. */
+function defaultCompose(fresh, key) {
+    return fresh
+        .map((item) => {
+        const it = item;
+        const k = key(item);
+        const title = typeof it?.title === "string" && it.title ? it.title : k;
+        const url = typeof it?.url === "string" && it.url && it.url !== title ? it.url : null;
+        return url ? `- ${title}\n  ${url}` : `- ${title}`;
+    })
+        .join("\n");
+}
+function withTimeout(run, ms, name) {
+    const controller = new AbortController();
+    let timer;
+    const timeout = new Promise((_, reject) => {
+        timer = setTimeout(() => {
+            controller.abort();
+            reject(new Error(`${name} timed out after ${ms}ms`));
+        }, ms);
+    });
+    return Promise.race([Promise.resolve().then(() => run(controller.signal)), timeout]).finally(() => clearTimeout(timer));
+}
+/**
+ * Runs one pass of a script job and says what happened. See the header
+ * comment for the contract; the short version: fetch in code, drop what was
+ * sent, compose only if something is new, post, and only then mark seen.
+ */
+async function runScriptJob(options) {
+    const { key, seen, compose, post } = options;
+    const logger = options.logger ?? { error: (msg) => console.error(msg) };
+    const timeoutMs = options.sourceTimeoutMs ?? exports.DEFAULT_SOURCE_TIMEOUT_MS;
+    const named = Array.isArray(options.sources)
+        ? options.sources.map((fn, i) => [fn.name || `source-${i}`, fn])
+        : Object.entries(options.sources);
+    const settled = await Promise.all(named.map(async ([name, fn]) => {
+        try {
+            const items = await withTimeout((signal) => fn({ signal }), timeoutMs, name);
+            return { name, items: Array.isArray(items) ? items : [], ok: true };
+        }
+        catch (err) {
+            logger.error(`[script job] source ${name} failed: ${err.message}`);
+            return { name, items: [], ok: false };
+        }
+    }));
+    const failedSources = settled.filter((s) => !s.ok).map((s) => s.name);
+    const all = settled.flatMap((s) => s.items);
+    // Source order decides which copy of a duplicate wins.
+    const fresh = [];
+    const freshKeys = [];
+    const inRun = new Set();
+    for (const item of all) {
+        let k;
+        try {
+            k = String(key(item));
+        }
+        catch (err) {
+            logger.error(`[script job] key() threw, item skipped: ${err.message}`);
+            continue;
+        }
+        if (inRun.has(k))
+            continue;
+        inRun.add(k);
+        if (await seen.has(k))
+            continue;
+        fresh.push(item);
+        freshKeys.push(k);
+    }
+    const result = { fetched: all.length, fresh: fresh.length, posted: false, failedSources };
+    if (fresh.length === 0)
+        return result;
+    const text = compose ? await compose(fresh) : defaultCompose(fresh, key);
+    if (typeof text !== "string" || text.trim() === "")
+        return result;
+    await post(text, fresh);
+    result.posted = true;
+    try {
+        await seen.mark(freshKeys, options.seenTtlMs === undefined ? undefined : { ttlMs: options.seenTtlMs });
+    }
+    catch (err) {
+        // The post already went out; throwing now would tell the scheduler it
+        // did not. The cost is a possible repeat next run, so say so loudly.
+        logger.error(`[script job] posted, but marking ${freshKeys.length} item(s) seen failed (they may repeat): ${err.message}`);
+    }
+    return result;
+}
+//# sourceMappingURL=scriptJob.js.map

package/dist/scriptJob.js.map

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

package/dist/sessions.d.ts

@@ -0,0 +1,131 @@
+import type { SaltId } from "./ids.js";
+import type { CardSection } from "./identity.js";
+export interface SessionTurn {
+    role: "user" | "assistant";
+    content: string;
+    /** epoch ms */
+    at: number;
+    /** Who said it, for a "user" turn -- a username when known, else an id. Omitted for "assistant" (that's always this identity). */
+    from?: string;
+    /** Why this delivery reached the identity, on an open room only -- mirrors
+     *  webhook.ts's MessageContext.deliveredBecause for a "user" turn rebuilt
+     *  from the chat's own history (see rebuildTranscriptTail). Never set on
+     *  an "assistant" turn (this identity's own message); omitted for an
+     *  ordinary encrypted chat, where the question doesn't apply. */
+    deliveredBecause?: "mention" | "reply" | "keyword" | "all" | "team_lead";
+}
+export interface SessionNote {
+    /** What this session is trying to accomplish, in the agent's own words. */
+    goal?: string;
+    /** Set while blocked on something from the person/other party; cleared once they answer. */
+    waitingOn?: string;
+    /** Every delegate_to_agent / consult_agent call made in service of this session -- oldest first. */
+    consulted: Array<{
+        handle: string;
+        laneId: string;
+    }>;
+    /** The most recent work.ts report id this session posted, if any -- lets a resumed session keep updating the same report instead of starting a new one. */
+    lastReportId?: string;
+}
+/**
+ * One SALT-IDENTITY-SLICE this session received from a chat member (see
+ * identityShare.ts) -- kept so a later turn can use what someone shared
+ * without re-asking. `verified` mirrors identityShare's own signature
+ * check (never re-verified here). Nothing removes an entry except a
+ * matching SALT-IDENTITY-REVOKE naming the same `id` (see
+ * forgetReceivedIdentitySlice) or MAX_IDENTITY_SLICES_PER_SENDER eviction.
+ */
+export interface ReceivedIdentitySlice {
+    id: string;
+    sections: CardSection[];
+    verified: boolean;
+    /** epoch ms this slice was received. */
+    receivedAt: number;
+}
+export interface Session {
+    /** The room this session ultimately serves -- itself for an ordinary chat, or the shared chat a lane (sidechain/coaching/consult) was opened from. */
+    roomId: SaltId;
+    /** The actual chat this session's messages arrive/post in -- may be a lane. */
+    chatId: SaltId;
+    /** This identity's relationship to `chatId`: the active participant ("active"), a lane off some room ("lane" -- Mediator coaching, a translator, a work.ts report lane), a consult lane specifically ("consult"), or present without being the one who speaks ("observer"). Descriptive only -- nothing in this SDK gates behavior on it. */
+    role: "active" | "observer" | "consult" | "lane";
+    /** Recent turns, oldest first, capped at MAX_TRANSCRIPT_TURNS. */
+    transcriptTail: SessionTurn[];
+    note: SessionNote;
+    /** Verified (and unverified) SALT-IDENTITY-SLICEs received in this chat, keyed by the lowercased sender id -- oldest first, capped at MAX_IDENTITY_SLICES_PER_SENDER per sender. Empty object when nothing has been shared here yet. */
+    identity: Record<string, ReceivedIdentitySlice[]>;
+    /** epoch ms of the last write. */
+    updatedAt: number;
+}
+export interface SessionStore {
+    get(identityId: SaltId, chatId: SaltId): Promise<Session | null>;
+    put(identityId: SaltId, chatId: SaltId, session: Session): Promise<void>;
+    forget(identityId: SaltId, chatId: SaltId): Promise<void>;
+}
+/** Turns kept per session -- old ones drop off the front, oldest first. */
+export declare const MAX_TRANSCRIPT_TURNS = 40;
+/** A note's serialized size budget, in characters. */
+export declare const MAX_NOTE_CHARS = 1200;
+/** Received identity slices kept per sender -- old ones drop off the front, oldest first, same convention as MAX_TRANSCRIPT_TURNS. */
+export declare const MAX_IDENTITY_SLICES_PER_SENDER = 20;
+/** A fresh, empty session for `chatId` (in room `roomId`). */
+export declare function emptySession(chatId: SaltId, roomId: SaltId, role?: Session["role"]): Session;
+/**
+ * Records a SALT-IDENTITY-SLICE this session just received from
+ * `fromId`, in place. Called by webhook.ts right after
+ * identityShare.parseIdentityMarker/crypto.verifyDetached resolve one.
+ */
+export declare function recordReceivedIdentitySlice(session: Session, fromId: SaltId, slice: ReceivedIdentitySlice): void;
+/**
+ * Drops every slice from `fromId` whose `id` matches `sliceId`, in place --
+ * called on an incoming SALT-IDENTITY-REVOKE naming that id. A no-op when
+ * nothing recorded under that (sender, id) pair exists (the revoke arrived
+ * before this process ever saw the slice, or from a different process
+ * hosting the same identity).
+ */
+export declare function forgetReceivedIdentitySlice(session: Session, fromId: SaltId, sliceId: string): void;
+/** Appends one turn in place, dropping the oldest turns past MAX_TRANSCRIPT_TURNS. */
+export declare function appendTurn(session: Session, turn: SessionTurn): void;
+/**
+ * Returns a copy of `note` whose serialized JSON fits MAX_NOTE_CHARS,
+ * dropping the OLDEST `consulted` entries first -- `goal`/`waitingOn`/
+ * `lastReportId` are the actual point of the note and are never what gets
+ * cut to make room. If it's still over budget with nothing left to drop,
+ * returns it as-is: that's a caller writing an oversized goal/waitingOn
+ * string, which no amount of trimming `consulted` will fix.
+ */
+export declare function boundNote(note: SessionNote): SessionNote;
+/**
+ * In-memory session store -- the default. Sessions are lost on process
+ * restart (a cold-start rebuild from chat history fills the gap -- see
+ * webhook.ts's loadOrRebuildSession).
+ */
+export declare function MemorySessionStore(): SessionStore;
+/**
+ * One plain JSON file per (identity, chat) under `dir`, written atomically
+ * (temp file + rename, so a crash mid-write never leaves a half-written
+ * session on disk -- the same convention identities.ts uses for its own
+ * store).
+ *
+ * TRUST BOUNDARY, stated plainly: sessions are stored in PLAINTEXT on this
+ * filesystem, right beside the identities.json this same process already
+ * keeps there (which holds every hosted identity's PRIVATE PGP KEY). This
+ * store adds no encryption of its own -- it is exactly as trusted as the
+ * disk it's on, which is the same trust level the rest of this process
+ * already assumes. Fine for a single-tenant agent host's own local/attached
+ * disk; do not point `dir` at shared or otherwise untrusted storage, and
+ * do not treat a session file as safe to hand to anyone Salt itself
+ * couldn't already show the conversation to.
+ */
+export declare function FileSessionStore(dir: string): SessionStore;
+export declare const SESSION_NOTE_MARKER = "[[SALT-SESSION-NOTE]]";
+/**
+ * A session note's wire line, or undefined when there's nothing worth
+ * carrying forward (an empty note would just be noise on every hand-off).
+ */
+export declare function formatSessionNoteLine(note: SessionNote | undefined | null): string | undefined;
+/** The LAST [[SALT-SESSION-NOTE]] line's parsed payload in `text`, or undefined if there isn't one or it doesn't parse. */
+export declare function extractSessionNote(text: string): SessionNote | undefined;
+/** Removes every [[SALT-SESSION-NOTE]] line from `text` -- wire protocol, not conversational content. */
+export declare function stripSessionNoteLines(text: string): string;
+//# sourceMappingURL=sessions.d.ts.map

package/dist/sessions.d.ts.map

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