salt-agent-sdk 0.1.0 → 0.19.0

package/dist/sessions.js

@@ -0,0 +1,240 @@
+"use strict";
+// A hosted identity's memory of ONE chat: enough of the recent back-and-forth
+// and a short structured note to pick a conversation back up -- across a
+// process restart (FileSessionStore), and across a hand-off (the note rides
+// the outgoing agent's briefing message as a final wire-protocol line and is
+// parsed back into the new session on the other end -- see webhook.ts).
+//
+// This is bookkeeping, not intelligence: nothing here decides what an agent
+// says. webhook.ts loads/rebuilds a session before onMessage runs, hands it
+// to the consumer as ctx.session (a plain mutable object -- write to
+// ctx.session.note directly, e.g. to record who you consulted), and persists
+// it after the handler returns. A consumer that ignores ctx.session entirely
+// sees no behavior change.
+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.SESSION_NOTE_MARKER = exports.MAX_IDENTITY_SLICES_PER_SENDER = exports.MAX_NOTE_CHARS = exports.MAX_TRANSCRIPT_TURNS = void 0;
+exports.emptySession = emptySession;
+exports.recordReceivedIdentitySlice = recordReceivedIdentitySlice;
+exports.forgetReceivedIdentitySlice = forgetReceivedIdentitySlice;
+exports.appendTurn = appendTurn;
+exports.boundNote = boundNote;
+exports.MemorySessionStore = MemorySessionStore;
+exports.FileSessionStore = FileSessionStore;
+exports.formatSessionNoteLine = formatSessionNoteLine;
+exports.extractSessionNote = extractSessionNote;
+exports.stripSessionNoteLines = stripSessionNoteLines;
+const node_crypto_1 = require("node:crypto");
+const fs = __importStar(require("node:fs/promises"));
+const path = __importStar(require("node:path"));
+/** Turns kept per session -- old ones drop off the front, oldest first. */
+exports.MAX_TRANSCRIPT_TURNS = 40;
+/** A note's serialized size budget, in characters. */
+exports.MAX_NOTE_CHARS = 1200;
+/** Received identity slices kept per sender -- old ones drop off the front, oldest first, same convention as MAX_TRANSCRIPT_TURNS. */
+exports.MAX_IDENTITY_SLICES_PER_SENDER = 20;
+const mapKey = (id) => String(id).toLowerCase();
+/** A fresh, empty session for `chatId` (in room `roomId`). */
+function emptySession(chatId, roomId, role = "active") {
+    return { roomId, chatId, role, transcriptTail: [], note: { consulted: [] }, identity: {}, updatedAt: Date.now() };
+}
+/**
+ * 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.
+ */
+function recordReceivedIdentitySlice(session, fromId, slice) {
+    if (!session.identity)
+        session.identity = {};
+    const key = mapKey(fromId);
+    const list = session.identity[key] || (session.identity[key] = []);
+    list.push(slice);
+    if (list.length > exports.MAX_IDENTITY_SLICES_PER_SENDER)
+        list.splice(0, list.length - exports.MAX_IDENTITY_SLICES_PER_SENDER);
+}
+/**
+ * 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).
+ */
+function forgetReceivedIdentitySlice(session, fromId, sliceId) {
+    if (!session.identity)
+        return;
+    const key = mapKey(fromId);
+    const list = session.identity[key];
+    if (!list)
+        return;
+    session.identity[key] = list.filter((s) => s.id !== sliceId);
+}
+/** Appends one turn in place, dropping the oldest turns past MAX_TRANSCRIPT_TURNS. */
+function appendTurn(session, turn) {
+    session.transcriptTail.push(turn);
+    if (session.transcriptTail.length > exports.MAX_TRANSCRIPT_TURNS) {
+        session.transcriptTail.splice(0, session.transcriptTail.length - exports.MAX_TRANSCRIPT_TURNS);
+    }
+}
+/**
+ * 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.
+ */
+function boundNote(note) {
+    const bounded = { ...note, consulted: [...(note.consulted || [])] };
+    while (JSON.stringify(bounded).length > exports.MAX_NOTE_CHARS && bounded.consulted.length > 0) {
+        bounded.consulted.shift();
+    }
+    return bounded;
+}
+/**
+ * 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).
+ */
+function MemorySessionStore() {
+    const store = new Map();
+    const key = (identityId, chatId) => `${mapKey(identityId)}:${mapKey(chatId)}`;
+    return {
+        async get(identityId, chatId) {
+            return store.get(key(identityId, chatId)) ?? null;
+        },
+        async put(identityId, chatId, session) {
+            store.set(key(identityId, chatId), session);
+        },
+        async forget(identityId, chatId) {
+            store.delete(key(identityId, chatId));
+        },
+    };
+}
+// --- FileSessionStore ----------------------------------------------------
+function fileFor(dir, identityId, chatId) {
+    const safe = (id) => mapKey(id).replace(/[^a-z0-9_-]/g, "_");
+    return path.join(dir, `${safe(identityId)}__${safe(chatId)}.json`);
+}
+/**
+ * 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.
+ */
+function FileSessionStore(dir) {
+    return {
+        async get(identityId, chatId) {
+            try {
+                const raw = await fs.readFile(fileFor(dir, identityId, chatId), "utf8");
+                return JSON.parse(raw);
+            }
+            catch (err) {
+                if (err.code === "ENOENT")
+                    return null;
+                throw err;
+            }
+        },
+        async put(identityId, chatId, session) {
+            await fs.mkdir(dir, { recursive: true });
+            const target = fileFor(dir, identityId, chatId);
+            const tmp = `${target}.${process.pid}.${(0, node_crypto_1.randomBytes)(4).toString("hex")}.tmp`;
+            await fs.writeFile(tmp, JSON.stringify(session, null, 2));
+            await fs.rename(tmp, target);
+        },
+        async forget(identityId, chatId) {
+            try {
+                await fs.unlink(fileFor(dir, identityId, chatId));
+            }
+            catch (err) {
+                if (err.code !== "ENOENT")
+                    throw err;
+            }
+        },
+    };
+}
+// --- Hand-off session note wire format -------------------------------------
+//
+// A hand-off briefing's FINAL line, appended by webhook.ts's
+// handleHandoffConfirmed to whatever text the consumer's onHandoffConfirmed
+// sent -- transparent to that consumer. The incoming agent's
+// handleHandoffReceived parses it back out of the polled transcript (see
+// HANDOFF_BRIEFING_MARKER in webhook.ts) into the new session's note, then
+// strips the line before handing the transcript to onHandoffReceived: it's
+// wire protocol, never conversational content. salt-fe strips the same line
+// from what a human reads.
+exports.SESSION_NOTE_MARKER = "[[SALT-SESSION-NOTE]]";
+const SESSION_NOTE_LINE_RE = /^\[\[SALT-SESSION-NOTE\]\] (.+)$/gm;
+/**
+ * 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).
+ */
+function formatSessionNoteLine(note) {
+    if (!note)
+        return undefined;
+    const hasContent = !!(note.goal || note.waitingOn || note.lastReportId || (note.consulted && note.consulted.length > 0));
+    if (!hasContent)
+        return undefined;
+    return `${exports.SESSION_NOTE_MARKER} ${JSON.stringify(boundNote(note))}`;
+}
+/** The LAST [[SALT-SESSION-NOTE]] line's parsed payload in `text`, or undefined if there isn't one or it doesn't parse. */
+function extractSessionNote(text) {
+    const matches = [...text.matchAll(SESSION_NOTE_LINE_RE)];
+    if (matches.length === 0)
+        return undefined;
+    try {
+        return JSON.parse(matches[matches.length - 1][1]);
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Removes every [[SALT-SESSION-NOTE]] line from `text` -- wire protocol, not conversational content. */
+function stripSessionNoteLines(text) {
+    return text
+        .replace(/^\[\[SALT-SESSION-NOTE\]\].*$/gm, "")
+        .replace(/\n{3,}/g, "\n\n")
+        .trim();
+}
+//# sourceMappingURL=sessions.js.map

package/dist/sessions.js.map

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

package/dist/socket.d.ts

@@ -0,0 +1,115 @@
+import WebSocket from "ws";
+import { type WebhookServerOptions } from "./webhook.js";
+import type { SaltId } from "./ids.js";
+export interface CursorStore {
+    /** The last-acked update id for this identity, or 0 for "never polled". */
+    get(agentId: SaltId): Promise<number>;
+    put(agentId: SaltId, cursor: number): Promise<void>;
+}
+/** In-memory cursor store. Lost on restart (a fresh process re-subscribes
+ *  from cursor 0, which resumes from salt-api's own server-side ack --
+ *  see this file's header comment). Opt in explicitly; the default is
+ *  FileCursorStore -- see createSocketClient. */
+export declare function MemoryCursorStore(): CursorStore;
+/**
+ * `<agentId>.cursor.json` inside `dir` -- written atomically (temp file +
+ * rename), the same convention sessions.ts's FileSessionStore uses. `dir`
+ * defaults to one identity's own directory (see defaultStateDir), but N9
+ * (second security review, 2026-09-18) keys the FILENAME by agent id too:
+ * a caller pointing several identities at one SHARED directory (rather
+ * than createSocketClient's per-identity default) used to collide on the
+ * same fixed `cursor.json` -- one agent's cursor silently clobbering
+ * another's. Keying by id makes a shared directory safe the same way
+ * sessions.ts's one-file-per-key convention already is.
+ */
+export declare function FileCursorStore(dir: string): CursorStore;
+export interface DedupeStore {
+    has(agentId: SaltId, deliveryId: string): Promise<boolean>;
+    add(agentId: SaltId, deliveryId: string): Promise<void>;
+}
+export declare const DEFAULT_DEDUPE_MAX = 5000;
+/** In-memory dedupe set, bounded to the last `max` delivery ids (oldest
+ *  dropped first). Opt in explicitly; the default is FileDedupeStore. */
+export declare function MemoryDedupeStore(max?: number): DedupeStore;
+/**
+ * `<agentId>.seen.json` inside `dir` (an ordered array of the last `max`
+ * delivery ids, oldest first) -- same atomic-write convention as
+ * FileCursorStore. N9 (second security review, 2026-09-18): the filename
+ * is keyed by agent id, same reasoning as FileCursorStore above -- a
+ * shared `dir` across identities must not let one identity's dedupe set
+ * clobber another's (or worse, let identity B's real deliveries appear
+ * "already seen" because they share a delivery_id namespace collision
+ * with identity A's file).
+ */
+export declare function FileDedupeStore(dir: string, max?: number): DedupeStore;
+/** Exponential reconnect backoff bounds (jittered). Not a poll interval --
+ *  these only govern the wait between one dropped/closed connection and
+ *  the next connection attempt. */
+export declare const RECONNECT_MIN_DELAY_MS = 1000;
+export declare const RECONNECT_MAX_DELAY_MS = 60000;
+/** No Action Cable ping for this long means the connection is presumed
+ *  dead (a half-open TCP socket may never emit its own 'close'/'error'). */
+export declare const PING_TIMEOUT_MS = 30000;
+export interface SocketClientOptions extends WebhookServerOptions {
+    /** The salt-api deployment's origin, e.g. "https://saltapp.ai" (or
+     *  "http://localhost:3000" in dev) -- rewritten to a ws(s):// `/cable`
+     *  URL for the websocket, and used as-is for the backfill/ack HTTP
+     *  calls. No trailing slash required either way. */
+    host: string;
+    /** This identity's OWN api-key, sent as the `api-key` header on the
+     *  websocket handshake and on every backfill/ack HTTP call. Not the same
+     *  thing as `identities`, which can hold several hosted identities for
+     *  DECRYPT/ROUTE purposes -- a process draining more than one identity's
+     *  outbox runs one createSocketClient per identity. */
+    apiKey: string;
+    /** That identity's Salt id -- the cursor/dedupe stores' default directory
+     *  key, and used in log lines. */
+    agentId: SaltId;
+    /** Where the resume cursor is persisted across restarts/reconnects.
+     *  Defaults to `FileCursorStore(~/.salt/agents/<agentId>)` -- pass
+     *  `MemoryCursorStore()` explicitly to opt OUT of persistence instead. */
+    cursorStore?: CursorStore;
+    /** Persistent per-agent delivery_id dedupe (M5/F3) -- replay protection
+     *  that doesn't rely on the envelope's own timestamp. Defaults to
+     *  `FileDedupeStore(~/.salt/agents/<agentId>)`; pass `MemoryDedupeStore()`
+     *  explicitly to opt out of persistence. */
+    dedupeStore?: DedupeStore;
+    /** Max rows per backfill page (only fetched when replay_done.more is
+     *  true -- see this file's header comment). Defaults to 100. */
+    limit?: number;
+    /** Reconnect backoff bounds (ms), exponential + jittered. Also used for
+     *  a failed backfill/ack HTTP call's own retry wait. Defaults to
+     *  RECONNECT_MIN_DELAY_MS..RECONNECT_MAX_DELAY_MS (1s..60s). */
+    minBackoffMs?: number;
+    maxBackoffMs?: number;
+    /** Override fetch (backfill/ack HTTP calls; tests). Defaults to global fetch. */
+    fetchImpl?: typeof fetch;
+    /** Override the WebSocket implementation (tests). Defaults to `ws`'s WebSocket. */
+    webSocketImpl?: typeof WebSocket;
+    /** How long without an Action Cable ping before this connection is
+     *  presumed dead and torn down for a reconnect. Defaults to
+     *  PING_TIMEOUT_MS (30s) -- exposed mainly so tests don't have to wait
+     *  out the real default. */
+    pingTimeoutMs?: number;
+}
+export interface SocketClient {
+    /** Starts the connection loop in the background. A no-op if already running. */
+    start(): void;
+    /** Stops the loop: terminates any open/connecting websocket and aborts
+     *  any in-flight backfill/ack request immediately, and resolves once
+     *  everything has actually settled (never mid-reconnect, never with a
+     *  background ack still in flight). */
+    stop(): Promise<void>;
+}
+/**
+ * Drains one identity's K2 socket-mode outbox by staying connected to
+ * salt-api's `AgentUpdatesChannel` over Action Cable, verifying each
+ * envelope with the exact same check createWebhookServer applies to a
+ * webhook POST (createDispatcher's verifyEnvelope), and dispatching it to
+ * the SAME onMessage/onCardInteraction/etc. handlers. See this file's
+ * header comment for the full wire protocol, the one-line switch from
+ * createWebhookServer, and the reasoning behind cursor persistence, the
+ * ack call, backfill, and reconnect.
+ */
+export declare function createSocketClient(options: SocketClientOptions): SocketClient;
+//# sourceMappingURL=socket.d.ts.map

package/dist/socket.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"socket.d.ts","sourceRoot":"","sources":["../src/socket.ts"],"names":[],"mappings":"AAiJA,OAAO,SAAS,MAAM,IAAI,CAAC;AAC3B,OAAO,EAAiC,KAAK,oBAAoB,EAAE,MAAM,cAAc,CAAC;AAExF,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAkGvC,MAAM,WAAW,WAAW;IAC1B,2EAA2E;IAC3E,GAAG,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IACtC,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACrD;AAED;;;iDAGiD;AACjD,wBAAgB,iBAAiB,IAAI,WAAW,CAW/C;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,WAAW,CAiBxD;AAKD,MAAM,WAAW,WAAW;IAC1B,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAC3D,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACzD;AAED,eAAO,MAAM,kBAAkB,OAAO,CAAC;AAEvC;yEACyE;AACzE,wBAAgB,iBAAiB,CAAC,GAAG,GAAE,MAA2B,GAAG,WAAW,CAwB/E;AAED;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,GAAE,MAA2B,GAAG,WAAW,CAmC1F;AA2BD;;mCAEmC;AACnC,eAAO,MAAM,sBAAsB,OAAO,CAAC;AAC3C,eAAO,MAAM,sBAAsB,QAAS,CAAC;AAE7C;4EAC4E;AAC5E,eAAO,MAAM,eAAe,QAAS,CAAC;AAEtC,MAAM,WAAW,mBAAoB,SAAQ,oBAAoB;IAC/D;;;wDAGoD;IACpD,IAAI,EAAE,MAAM,CAAC;IACb;;;;2DAIuD;IACvD,MAAM,EAAE,MAAM,CAAC;IACf;sCACkC;IAClC,OAAO,EAAE,MAAM,CAAC;IAChB;;8EAE0E;IAC1E,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B;;;gDAG4C;IAC5C,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B;oEACgE;IAChE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;oEAEgE;IAChE,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,iFAAiF;IACjF,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;IACzB,mFAAmF;IACnF,aAAa,CAAC,EAAE,OAAO,SAAS,CAAC;IACjC;;;gCAG4B;IAC5B,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,YAAY;IAC3B,gFAAgF;IAChF,KAAK,IAAI,IAAI,CAAC;IACd;;;2CAGuC;IACvC,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACvB;AAiDD;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,mBAAmB,GAAG,YAAY,CAyiB7E"}