@harny/sdk 0.1.2 → 0.1.4

package/dist/cjs/agent/session.js

@@ -0,0 +1,261 @@
+"use strict";
+/**
+ * Short-term conversation memory for the agent, kept in the business's own deploy.
+ *
+ * The agent remembers the last turns of a conversation so a follow-up ("move
+ * it to 4") makes sense. Those turns live HERE, in a store the business runs;
+ * they are never sent to Harny. Swap the store by implementing `SessionStore`
+ * (three methods) over the business's own database.
+ *
+ * The agent's default is `MemorySessionStore`, which keeps conversations
+ * until the process stops. `FileSessionStore` (Node only) writes one JSON
+ * file per session, readable only by its owner, with an atomic replace, so a
+ * crash never leaves half a file. Session ids are hashed into file names, so
+ * an id can never escape the directory. The file format is the one the Python
+ * SDK writes, so either SDK can read the other's files.
+ *
+ * Each assistant turn also carries a short note of the actions the agent
+ * performed in it (`ActionNote`: action, record id, time, and for an event its
+ * title and start). The next run puts those notes in front of the model, so
+ * "undo that" in a later message finds the record id. The notes stay in this
+ * store with the conversation; they are never sent to Harny. A store that
+ * keeps only `role` and `content` still works: it just loses the notes.
+ */
+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.FileSessionStore = exports.MemorySessionStore = exports.Turn = exports.ActionNote = void 0;
+const util_js_1 = require("./util.js");
+function toDate(value) {
+    if (value instanceof Date)
+        return value;
+    if (typeof value === "string" || typeof value === "number") {
+        const parsed = new Date(value);
+        if (!Number.isNaN(parsed.getTime()))
+            return parsed;
+    }
+    return new Date();
+}
+function optionalText(value) {
+    return value === null || value === undefined ? null : String(value);
+}
+/** One action the agent performed, as the conversation remembers it. */
+class ActionNote {
+    constructor(init) {
+        this.action = init.action;
+        this.recordId = init.recordId;
+        this.at = init.at === undefined ? new Date() : toDate(init.at);
+        this.outcome = init.outcome ?? "completed";
+        this.reverses = init.reverses ?? null;
+        this.title = init.title ?? null;
+        this.start = init.start ?? null;
+        this.confirmedInApp = init.confirmedInApp ?? false;
+    }
+    /** The stored form (the Python SDK's field names). */
+    toJSON() {
+        return {
+            action: this.action,
+            record_id: this.recordId,
+            at: this.at.toISOString(),
+            outcome: this.outcome,
+            reverses: this.reverses,
+            title: this.title,
+            start: this.start,
+            confirmed_in_app: this.confirmedInApp,
+        };
+    }
+    static fromJSON(raw) {
+        if (!(0, util_js_1.isPlainObject)(raw) || typeof raw.action !== "string" || raw.record_id === undefined || raw.record_id === null) {
+            throw new Error("a stored action note needs action and record_id");
+        }
+        return new ActionNote({
+            action: raw.action,
+            recordId: String(raw.record_id),
+            at: raw.at === undefined || raw.at === null ? undefined : toDate(raw.at),
+            outcome: raw.outcome === undefined || raw.outcome === null ? undefined : String(raw.outcome),
+            reverses: optionalText(raw.reverses),
+            title: optionalText(raw.title),
+            start: optionalText(raw.start),
+            confirmedInApp: Boolean(raw.confirmed_in_app),
+        });
+    }
+}
+exports.ActionNote = ActionNote;
+class Turn {
+    constructor(init) {
+        if (init.role !== "user" && init.role !== "assistant")
+            throw new Error("a turn's role is user or assistant");
+        if (typeof init.content !== "string")
+            throw new Error("a turn's content is text");
+        this.role = init.role;
+        this.content = init.content;
+        this.at = init.at === undefined ? new Date() : toDate(init.at);
+        this.actions = [...(init.actions ?? [])];
+    }
+    toJSON() {
+        return {
+            role: this.role,
+            content: this.content,
+            at: this.at.toISOString(),
+            actions: this.actions.map((note) => note.toJSON()),
+        };
+    }
+    static fromJSON(raw) {
+        if (!(0, util_js_1.isPlainObject)(raw))
+            throw new Error("a stored turn is an object");
+        const actions = Array.isArray(raw.actions) ? raw.actions.map((a) => ActionNote.fromJSON(a)) : [];
+        return new Turn({
+            role: raw.role,
+            content: raw.content,
+            at: raw.at === undefined || raw.at === null ? undefined : toDate(raw.at),
+            actions,
+        });
+    }
+}
+exports.Turn = Turn;
+function lastTurns(turns, limit) {
+    return limit ? turns.slice(-limit) : turns;
+}
+/** In-process store: the agent's default. Kept until the process stops. */
+class MemorySessionStore {
+    constructor(options = {}) {
+        this.data = new Map();
+        this.maxTurns = options.maxTurns ?? 200;
+    }
+    async load(sessionId, options = {}) {
+        return lastTurns([...(this.data.get(sessionId) ?? [])], options.limit);
+    }
+    async append(sessionId, turns) {
+        const kept = [...(this.data.get(sessionId) ?? []), ...turns].slice(-this.maxTurns);
+        this.data.set(sessionId, kept);
+    }
+    async clear(sessionId) {
+        this.data.delete(sessionId);
+    }
+    sessionIds() {
+        return [...this.data.keys()];
+    }
+}
+exports.MemorySessionStore = MemorySessionStore;
+/** One JSON file per session under `directory`, readable only by its owner (Node only). */
+class FileSessionStore {
+    constructor(directory, options = {}) {
+        this.queue = Promise.resolve();
+        this.modules = null;
+        if (!directory)
+            throw new Error("directory is required");
+        this.directory = directory;
+        this.maxTurns = options.maxTurns ?? 200;
+    }
+    node() {
+        this.modules ?? (this.modules = Promise.all([Promise.resolve().then(() => __importStar(require("node:fs/promises"))), Promise.resolve().then(() => __importStar(require("node:path")))]));
+        return this.modules;
+    }
+    /** One operation at a time, so two appends never interleave a read and a write. */
+    locked(operation) {
+        const next = this.queue.then(operation, operation);
+        this.queue = next.catch(() => undefined);
+        return next;
+    }
+    async file(sessionId) {
+        const [, path] = await this.node();
+        return path.join(this.directory, `${await (0, util_js_1.sha256Hex)(sessionId)}.json`);
+    }
+    async read(sessionId) {
+        const [fs] = await this.node();
+        let raw;
+        try {
+            raw = JSON.parse(await fs.readFile(await this.file(sessionId), "utf8"));
+        }
+        catch {
+            return [];
+        }
+        const turns = (0, util_js_1.isPlainObject)(raw) && Array.isArray(raw.turns) ? raw.turns : [];
+        return turns.map((item) => Turn.fromJSON(item));
+    }
+    async write(sessionId, turns) {
+        const [fs, path] = await this.node();
+        await fs.mkdir(this.directory, { recursive: true });
+        const tmp = path.join(this.directory, `.tmp-${(0, util_js_1.randomHex)(8)}.json`);
+        const payload = { session_id: sessionId, turns: turns.map((t) => t.toJSON()) };
+        try {
+            await fs.writeFile(tmp, JSON.stringify(payload), { encoding: "utf8", flag: "wx", mode: 0o600 });
+            await fs.rename(tmp, await this.file(sessionId));
+        }
+        finally {
+            await fs.rm(tmp, { force: true });
+        }
+    }
+    load(sessionId, options = {}) {
+        return this.locked(async () => lastTurns(await this.read(sessionId), options.limit));
+    }
+    append(sessionId, turns) {
+        return this.locked(async () => {
+            const kept = [...(await this.read(sessionId)), ...turns].slice(-this.maxTurns);
+            await this.write(sessionId, kept);
+        });
+    }
+    clear(sessionId) {
+        return this.locked(async () => {
+            const [fs] = await this.node();
+            await fs.rm(await this.file(sessionId), { force: true });
+        });
+    }
+    sessionIds() {
+        return this.locked(async () => {
+            const [fs, path] = await this.node();
+            let names;
+            try {
+                names = (await fs.readdir(this.directory)).filter((n) => n.endsWith(".json")).sort();
+            }
+            catch {
+                return [];
+            }
+            const ids = [];
+            for (const name of names) {
+                try {
+                    const raw = JSON.parse(await fs.readFile(path.join(this.directory, name), "utf8"));
+                    if ((0, util_js_1.isPlainObject)(raw) && raw.session_id !== undefined)
+                        ids.push(String(raw.session_id));
+                }
+                catch {
+                    continue;
+                }
+            }
+            return ids;
+        });
+    }
+}
+exports.FileSessionStore = FileSessionStore;
+//# sourceMappingURL=session.js.map

package/dist/cjs/agent/session.js.map

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

package/dist/cjs/agent/spend.d.ts

@@ -0,0 +1,39 @@
+/**
+ * A spend cap per run, so one chatty conversation cannot run up the model bill.
+ *
+ * The cap is checked before every model call and after it. When the cap is
+ * reached the run stops; nothing already done is undone, and the run result
+ * says `stoppedReason === "spend_cap"`.
+ *
+ * Dollars need a price. The roster carries list prices for most entries; for
+ * an entry without one, state the price in the agent's options, or rely on
+ * the token cap. A run always has a cap: when no token cap is set and no
+ * dollar cap can apply (no cap at all, or a dollar cap on a model without a
+ * price), the run stops at `FALLBACK_MAX_TOKENS` tokens, and the agent's model
+ * notes say so.
+ */
+import { Usage } from "./adapters.js";
+/** The token cap a run falls back to when no other cap can apply. */
+export declare const FALLBACK_MAX_TOKENS = 100000;
+export declare class SpendCap {
+    readonly maxUsd: number | null;
+    readonly maxTokens: number | null;
+    constructor(init?: {
+        maxUsd?: number | null;
+        maxTokens?: number | null;
+    });
+}
+export declare class SpendMeter {
+    readonly cap: SpendCap;
+    readonly inputPerMtok: number | null;
+    readonly outputPerMtok: number | null;
+    readonly usage: Usage;
+    constructor(cap: SpendCap, inputPerMtok?: number | null, outputPerMtok?: number | null);
+    get priced(): boolean;
+    get costUsd(): number | null;
+    get usdCapEnforced(): boolean;
+    /** The token cap in force: the cap's own, else the fallback when no dollar cap can apply. */
+    get maxTokens(): number | null;
+    record(usage: Usage): void;
+    exhausted(): boolean;
+}

package/dist/cjs/agent/spend.js

@@ -0,0 +1,70 @@
+"use strict";
+/**
+ * A spend cap per run, so one chatty conversation cannot run up the model bill.
+ *
+ * The cap is checked before every model call and after it. When the cap is
+ * reached the run stops; nothing already done is undone, and the run result
+ * says `stoppedReason === "spend_cap"`.
+ *
+ * Dollars need a price. The roster carries list prices for most entries; for
+ * an entry without one, state the price in the agent's options, or rely on
+ * the token cap. A run always has a cap: when no token cap is set and no
+ * dollar cap can apply (no cap at all, or a dollar cap on a model without a
+ * price), the run stops at `FALLBACK_MAX_TOKENS` tokens, and the agent's model
+ * notes say so.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SpendMeter = exports.SpendCap = exports.FALLBACK_MAX_TOKENS = void 0;
+const adapters_js_1 = require("./adapters.js");
+/** The token cap a run falls back to when no other cap can apply. */
+exports.FALLBACK_MAX_TOKENS = 100000;
+class SpendCap {
+    constructor(init = {}) {
+        this.maxUsd = init.maxUsd ?? null;
+        this.maxTokens = init.maxTokens ?? null;
+        if (this.maxUsd !== null && !(this.maxUsd > 0))
+            throw new Error("maxUsd must be positive");
+        if (this.maxTokens !== null && !(this.maxTokens > 0))
+            throw new Error("maxTokens must be positive");
+        Object.freeze(this);
+    }
+}
+exports.SpendCap = SpendCap;
+class SpendMeter {
+    constructor(cap, inputPerMtok = null, outputPerMtok = null) {
+        this.cap = cap;
+        this.inputPerMtok = inputPerMtok;
+        this.outputPerMtok = outputPerMtok;
+        this.usage = new adapters_js_1.Usage();
+    }
+    get priced() {
+        return this.inputPerMtok !== null && this.outputPerMtok !== null;
+    }
+    get costUsd() {
+        if (!this.priced)
+            return null;
+        return ((this.usage.inputTokens * Number(this.inputPerMtok)) / 1000000 +
+            (this.usage.outputTokens * Number(this.outputPerMtok)) / 1000000);
+    }
+    get usdCapEnforced() {
+        return this.cap.maxUsd !== null && this.priced;
+    }
+    /** The token cap in force: the cap's own, else the fallback when no dollar cap can apply. */
+    get maxTokens() {
+        if (this.cap.maxTokens !== null)
+            return this.cap.maxTokens;
+        return this.usdCapEnforced ? null : exports.FALLBACK_MAX_TOKENS;
+    }
+    record(usage) {
+        this.usage.add(usage);
+    }
+    exhausted() {
+        const limit = this.maxTokens;
+        if (limit !== null && this.usage.totalTokens >= limit)
+            return true;
+        const cost = this.costUsd;
+        return this.cap.maxUsd !== null && cost !== null && cost >= this.cap.maxUsd;
+    }
+}
+exports.SpendMeter = SpendMeter;
+//# sourceMappingURL=spend.js.map

package/dist/cjs/agent/spend.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"spend.js","sourceRoot":"","sources":["../../../src/agent/spend.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;GAaG;;;AAEH,+CAAsC;AAEtC,qEAAqE;AACxD,QAAA,mBAAmB,GAAG,MAAO,CAAC;AAE3C,MAAa,QAAQ;IAIjB,YAAY,OAA8D,EAAE;QACxE,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,IAAI,IAAI,CAAC;QAClC,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC,SAAS,IAAI,IAAI,CAAC;QACxC,IAAI,IAAI,CAAC,MAAM,KAAK,IAAI,IAAI,CAAC,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC;YAAE,MAAM,IAAI,KAAK,CAAC,yBAAyB,CAAC,CAAC;QAC3F,IAAI,IAAI,CAAC,SAAS,KAAK,IAAI,IAAI,CAAC,CAAC,IAAI,CAAC,SAAS,GAAG,CAAC,CAAC;YAAE,MAAM,IAAI,KAAK,CAAC,4BAA4B,CAAC,CAAC;QACpG,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IACxB,CAAC;CACJ;AAXD,4BAWC;AAED,MAAa,UAAU;IAGnB,YACa,GAAa,EACb,eAA8B,IAAI,EAClC,gBAA+B,IAAI;QAFnC,QAAG,GAAH,GAAG,CAAU;QACb,iBAAY,GAAZ,YAAY,CAAsB;QAClC,kBAAa,GAAb,aAAa,CAAsB;QALvC,UAAK,GAAG,IAAI,mBAAK,EAAE,CAAC;IAM1B,CAAC;IAEJ,IAAI,MAAM;QACN,OAAO,IAAI,CAAC,YAAY,KAAK,IAAI,IAAI,IAAI,CAAC,aAAa,KAAK,IAAI,CAAC;IACrE,CAAC;IAED,IAAI,OAAO;QACP,IAAI,CAAC,IAAI,CAAC,MAAM;YAAE,OAAO,IAAI,CAAC;QAC9B,OAAO,CACH,CAAC,IAAI,CAAC,KAAK,CAAC,WAAW,GAAG,MAAM,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC,GAAG,OAAS;YAChE,CAAC,IAAI,CAAC,KAAK,CAAC,YAAY,GAAG,MAAM,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC,GAAG,OAAS,CACrE,CAAC;IACN,CAAC;IAED,IAAI,cAAc;QACd,OAAO,IAAI,CAAC,GAAG,CAAC,MAAM,KAAK,IAAI,IAAI,IAAI,CAAC,MAAM,CAAC;IACnD,CAAC;IAED,6FAA6F;IAC7F,IAAI,SAAS;QACT,IAAI,IAAI,CAAC,GAAG,CAAC,SAAS,KAAK,IAAI;YAAE,OAAO,IAAI,CAAC,GAAG,CAAC,SAAS,CAAC;QAC3D,OAAO,IAAI,CAAC,cAAc,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,2BAAmB,CAAC;IAC5D,CAAC;IAED,MAAM,CAAC,KAAY;QACf,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;IAC1B,CAAC;IAED,SAAS;QACL,MAAM,KAAK,GAAG,IAAI,CAAC,SAAS,CAAC;QAC7B,IAAI,KAAK,KAAK,IAAI,IAAI,IAAI,CAAC,KAAK,CAAC,WAAW,IAAI,KAAK;YAAE,OAAO,IAAI,CAAC;QACnE,MAAM,IAAI,GAAG,IAAI,CAAC,OAAO,CAAC;QAC1B,OAAO,IAAI,CAAC,GAAG,CAAC,MAAM,KAAK,IAAI,IAAI,IAAI,KAAK,IAAI,IAAI,IAAI,IAAI,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC;IAChF,CAAC;CACJ;AAzCD,gCAyCC"}

package/dist/cjs/agent/tools.d.ts

@@ -0,0 +1,83 @@
+/**
+ * The agent's one door to Harny, and the tools it offers the model.
+ *
+ * `HarnyTools` wraps a Harny client and exposes exactly six named calls:
+ * `assembleContext`, `act`, `undo`, `getSourceItem`, `listArrivals` and
+ * `confirm`. The agent loop holds this facade, never the client, so it cannot
+ * reach any other Harny call. In particular it has no way to write the
+ * conversation into Harny's memory: a chat turn, and above all an AI turn, is
+ * never ingested. The conversation stays in the business's own session store.
+ *
+ * `confirm` is on the facade for the HOST (the business's confirm button) and
+ * is never offered to the model: an instruction planted in an email must not
+ * be able to approve an action on the person's behalf.
+ */
+import type { ActionInitiator, ActionOutcome, ContextResult, HarnyClient, SourceArrivalPage, SourceItem } from "../index.js";
+import type { ToolSpec } from "./adapters.js";
+export declare const HARNY_CALLS: readonly ["assembleContext", "act", "undo", "getSourceItem", "listArrivals", "confirm"];
+/** Calls the model can trigger through a tool. `confirm` is deliberately absent. */
+export declare const MODEL_REACHABLE_CALLS: readonly string[];
+/** The client methods the facade needs: a `HarnyClient` built with an app key. */
+export type HarnyClientLike = Pick<HarnyClient, (typeof HARNY_CALLS)[number]>;
+/**
+ * Exactly the Harny calls an agent needs, by name, and nothing else. The client
+ * (and its key) is held out of sight: logging or serializing the facade shows
+ * neither.
+ */
+export declare class HarnyTools {
+    constructor(client: HarnyClientLike);
+    private get client();
+    toJSON(): Record<string, unknown>;
+    assembleContext(query: string, options: {
+        user: string;
+        tokenBudget: number;
+        traceparent?: string;
+    }): Promise<ContextResult>;
+    act(action: string, args: Record<string, unknown>, options: {
+        user: string;
+        initiatedBy: ActionInitiator;
+        idempotencyKey: string;
+        correlationId?: string | null;
+        traceparent?: string;
+        /** The person's own words for this run. */
+        endUserMessage?: string | null;
+    }): Promise<ActionOutcome>;
+    undo(recordId: string, options: {
+        user: string;
+        initiatedBy: ActionInitiator;
+        idempotencyKey: string;
+        traceparent?: string;
+    }): Promise<ActionOutcome>;
+    getSourceItem(itemRef: string, options: {
+        user: string;
+        traceparent?: string;
+    }): Promise<SourceItem>;
+    listArrivals(options: {
+        user: string;
+        after?: number;
+        limit?: number;
+        traceparent?: string;
+    }): Promise<SourceArrivalPage>;
+    /** Host-only: the end user's decision from the business's confirm UI. */
+    confirm(executionId: string, confirmRef: string, options: {
+        approve: boolean;
+        user: string;
+        traceparent?: string;
+    }): Promise<ActionOutcome>;
+}
+export declare const CONTEXT_TOOL = "assemble_context";
+export declare const UNDO_TOOL = "undo_action";
+export declare const GET_ITEM_TOOL = "get_source_item";
+export declare const LIST_ARRIVALS_TOOL = "list_arrivals";
+/**
+ * Catalog actions with a precise argument schema. An action missing here still
+ * works: it is offered with a free-form arguments object and Harny validates it.
+ */
+export declare const ACTION_TOOL_SPECS: Readonly<Record<string, readonly [string, Record<string, unknown>]>>;
+export declare function actionToolName(action: string): string;
+export declare function buildToolSpecs(actions: readonly string[], options: {
+    allowUndo: boolean;
+    offerSourceTools: boolean;
+}): ToolSpec[];
+/** A tool result as the model reads it (the same bytes the Python SDK writes). */
+export declare function toolResultJson(payload: Record<string, unknown>): string;