@harny/sdk 0.1.2 → 0.1.4

package/dist/cjs/agent/util.js

@@ -0,0 +1,188 @@
+"use strict";
+/**
+ * Small helpers the agent modules share. Nothing here reaches the network.
+ *
+ * `pyDumps` writes JSON the way the Python SDK's agent does (", " and ": "
+ * separators), so a tool result or a quoted title reads byte for byte the
+ * same to the business's model whichever SDK runs the agent.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RunAborted = exports.clock = exports.MAX_TIMER_MS = exports.INSPECT = void 0;
+exports.sha256Hex = sha256Hex;
+exports.toHex = toHex;
+exports.randomHex = randomHex;
+exports.newRunId = newRunId;
+exports.asData = asData;
+exports.isPlainObject = isPlainObject;
+exports.truthy = truthy;
+exports.or = or;
+exports.toInt = toInt;
+exports.clipChars = clipChars;
+exports.pyDumps = pyDumps;
+exports.quoted = quoted;
+exports.plainCopy = plainCopy;
+exports.pyIsoformat = pyIsoformat;
+exports.sleep = sleep;
+exports.processEnv = processEnv;
+/** Hex SHA-256 of a UTF-8 string (WebCrypto, built into Node 20+). */
+async function sha256Hex(text) {
+    const digest = await globalThis.crypto.subtle.digest("SHA-256", new TextEncoder().encode(text));
+    return toHex(new Uint8Array(digest));
+}
+function toHex(bytes) {
+    return Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("");
+}
+/** `bytes` random bytes as lowercase hex. */
+function randomHex(bytes) {
+    const buffer = new Uint8Array(bytes);
+    globalThis.crypto.getRandomValues(buffer);
+    return toHex(buffer);
+}
+/** A random 32-hex run id (a v4 UUID without dashes). */
+function newRunId() {
+    if (typeof globalThis.crypto?.randomUUID === "function") {
+        return globalThis.crypto.randomUUID().replace(/-/g, "");
+    }
+    return randomHex(16);
+}
+/** Text placed inside a <context>, <actions> or <email> wrapper cannot close it. */
+function asData(text) {
+    return text.replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/** Truthiness as the Python agent reads it: empty arrays and objects are false. */
+function truthy(value) {
+    if (value === null || value === undefined || value === false || value === 0 || value === "")
+        return false;
+    if (Array.isArray(value))
+        return value.length > 0;
+    if (isPlainObject(value))
+        return Object.keys(value).length > 0;
+    return true;
+}
+/** `value` if truthy, else `fallback`. */
+function or(value, fallback) {
+    return truthy(value) ? value : fallback;
+}
+/** Whole-number conversion that never throws (`0` for anything unreadable). */
+function toInt(value) {
+    const n = typeof value === "number" ? value : Number(value);
+    return Number.isFinite(n) ? Math.trunc(n) : 0;
+}
+/** The first `limit` characters (code points) of `text`. */
+function clipChars(text, limit) {
+    const chars = Array.from(text);
+    return chars.length <= limit ? text : chars.slice(0, limit).join("");
+}
+function jsonString(text, ensureAscii) {
+    const out = JSON.stringify(text);
+    if (!ensureAscii)
+        return out;
+    return out.replace(/[\u007f-￿]/g, (c) => "\\u" + c.charCodeAt(0).toString(16).padStart(4, "0"));
+}
+/**
+ * JSON with the Python SDK's default separators. `undefined` is written as
+ * `null`; a `Date` as its ISO string.
+ */
+function pyDumps(value, ensureAscii = false) {
+    if (value === null || value === undefined)
+        return "null";
+    if (typeof value === "string")
+        return jsonString(value, ensureAscii);
+    if (typeof value === "boolean")
+        return value ? "true" : "false";
+    if (typeof value === "number") {
+        if (Number.isNaN(value))
+            return "NaN";
+        if (!Number.isFinite(value))
+            return value > 0 ? "Infinity" : "-Infinity";
+        return String(value);
+    }
+    if (typeof value === "bigint")
+        return value.toString();
+    if (value instanceof Date)
+        return jsonString(value.toISOString(), ensureAscii);
+    if (Array.isArray(value))
+        return "[" + value.map((v) => pyDumps(v, ensureAscii)).join(", ") + "]";
+    if (typeof value === "object") {
+        const parts = Object.entries(value).map(([k, v]) => `${jsonString(k, ensureAscii)}: ${pyDumps(v, ensureAscii)}`);
+        return "{" + parts.join(", ") + "}";
+    }
+    return jsonString(String(value), ensureAscii);
+}
+/** A string quoted the way the Python agent names it in a message ('x'). */
+function quoted(text) {
+    return `'${text}'`;
+}
+/** A deep copy through JSON (what a tool call's arguments are made of). */
+function plainCopy(value) {
+    return JSON.parse(JSON.stringify(value ?? null));
+}
+/** Node's hook for how `console.log` and `util.inspect` show an object. */
+exports.INSPECT = Symbol.for("nodejs.util.inspect.custom");
+const ISO_DATETIME = /^(\d{4}-\d{2}-\d{2})[T ](\d{2}:\d{2}:\d{2})(?:\.(\d+))?(Z|[+-]\d{2}:?\d{2})?$/;
+/**
+ * A date-time string as the Python SDK writes it after reading it
+ * (`datetime.isoformat()`): `Z` becomes `+00:00`, fractions are six digits or
+ * none. Anything that is not a date-time passes through unchanged.
+ */
+function pyIsoformat(value) {
+    if (typeof value !== "string")
+        return value;
+    const match = ISO_DATETIME.exec(value.trim());
+    if (!match)
+        return value;
+    let fraction = match[3] ? (match[3] + "000000").slice(0, 6) : "";
+    if (/^0*$/.test(fraction))
+        fraction = "";
+    let zone = match[4] ?? "";
+    if (zone === "Z" || zone === "-00:00" || zone === "-0000")
+        zone = "+00:00";
+    else if (zone && !zone.includes(":"))
+        zone = `${zone.slice(0, 3)}:${zone.slice(3)}`;
+    return `${match[1]}T${match[2]}${fraction ? "." + fraction : ""}${zone}`;
+}
+/** The longest delay a timer can hold; a larger one would fire at once. */
+exports.MAX_TIMER_MS = 2147483647;
+/** Resolve after `ms`, or reject at once when `signal` aborts. */
+function sleep(ms, signal) {
+    return new Promise((resolve, reject) => {
+        if (signal?.aborted) {
+            reject(new RunAborted());
+            return;
+        }
+        const timer = setTimeout(() => {
+            signal?.removeEventListener("abort", onAbort);
+            resolve();
+        }, Math.min(ms, exports.MAX_TIMER_MS));
+        const onAbort = () => {
+            clearTimeout(timer);
+            reject(new RunAborted());
+        };
+        signal?.addEventListener("abort", onAbort, { once: true });
+    });
+}
+/**
+ * The loop's clock: milliseconds on a steady clock, and a wait the run's
+ * time can cut short. Tests replace these two; nothing else should.
+ */
+exports.clock = {
+    now: () => (typeof globalThis.performance?.now === "function" ? globalThis.performance.now() : Date.now()),
+    sleep: (ms, signal) => sleep(ms, signal),
+};
+/** Thrown inside a run that already stopped (its time ran out). Never reaches the caller. */
+class RunAborted extends Error {
+    constructor() {
+        super("the run stopped");
+        this.name = "RunAborted";
+    }
+}
+exports.RunAborted = RunAborted;
+/** The process environment when there is one (Node), else an empty map. */
+function processEnv() {
+    const proc = globalThis.process;
+    return proc?.env ?? {};
+}
+//# sourceMappingURL=util.js.map

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

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

package/dist/cjs/conflictQuestion.d.ts

@@ -0,0 +1,137 @@
+/**
+ * What to ask a person whose notes conflict, and the rule for when. Pure: no network, no model call, no clock.
+ *
+ * A person can say two things that cannot both be true ("Maya prefers email", weeks later "Maya prefers phone").
+ * Harny keeps both and picks neither; the context response returns them in
+ * `conflicts`. Harny adds no pause of its own. The question is YOUR confirm step's: call
+ * `decideConflictQuestion` before an action, show `text` if it says `ask`, tell Harny you asked
+ * (`client.markConflictAsked`), and send the person's answer (`client.answerConflict`). The answer is saved as
+ * something the person said, and the conflict stops being returned.
+ *
+ *     const result = await client.assembleContext("send Maya the update", undefined, { user });
+ *     const decision = decideConflictQuestion({
+ *         conflicts: result.conflicts,
+ *         dependsOn: conflictsTheSendDependsOn.map((c) => c.record_id_1), // the ones whose answer changes what is sent
+ *         actionKinds: ["others_affected"],        // the kinds of action this is
+ *         mode: result.conflict_question_mode,     // the app's "When notes conflict" setting
+ *         phrases: new QuestionPhrases({ action: "send", question: "Does Maya prefer email or phone?" }),
+ *     });
+ *     if (decision.ask) {
+ *         const claim = await client.markConflictAsked(decision, { user });   // claim the question FIRST
+ *         if (claim.first_time) show(decision.text);                          // only the first claim shows it
+ *                                                                              // (in your own confirm card or chat)
+ *     }
+ *
+ * Report before you show, and show only when `first_time` is true: the first report wins, so a second action in the same
+ * turn, a retry or a second process cannot put the question twice. (A decision by itself changes nothing: `ledger` and
+ * `record` only help a host that keeps its own memory.)
+ *
+ * THE RULE (all six must hold, checked in this order; the first that fails names itself in `reason`):
+ *
+ * 1. the action is of the "others affected" or "irreversible" kind (`ASKING_KINDS`): an action that only touches
+ *    the person's own things never asks;
+ * 2. a conflict exists for a note the action depends on. `dependsOn` lists the `record_id_1` / `record_id_2` of each
+ *    conflict whose answer changes what the action does; you (or your agent) decide that from the two statements;
+ * 3. the question is on (`mode` is not null or undefined). The response names the app's mode only while Harny has
+ *    the question on, so no mode with a conflict in hand means do not ask;
+ * 4. the person did not say both in one conversation (`same_conversation` is false): they have just said it, so
+ *    they are never asked about it there;
+ * 5. that conflict has not been asked about before: at most once per conflict. It counts as asked when the
+ *    response marked it `asked` or your `ledger` has it;
+ * 6. the wording the question needs was supplied FOR THAT CONFLICT (a lone `QuestionPhrases` is accepted only while
+ *    one conflict can be asked; with several, pass a function of the conflict or a map by `conflictKey`).
+ *
+ * THE WORDS depend on the app's "When notes conflict" setting: `simple` (the default, no dates), `precise` (both
+ * statements with the day each was said) and `handoff` (a short question that offers the detail, which your own
+ * interface shows from the `conflicts` data). The sentences carry natural-language phrases ("Maya prefers email") that the stored statements do not, so YOU supply them in `QuestionPhrases`; this module never writes
+ * wording of its own: a missing phrase is a `missing_phrases` refusal, not a guess.
+ */
+/** The closed set the app's "When notes conflict" setting takes. */
+export declare const CONFLICT_QUESTION_MODES: readonly ["simple", "precise", "handoff"];
+export type ConflictQuestionMode = (typeof CONFLICT_QUESTION_MODES)[number];
+export declare const DEFAULT_CONFLICT_QUESTION_MODE: ConflictQuestionMode;
+/** The action kinds that may ask. `money` and `nobody_else` do not. */
+export declare const ASKING_KINDS: ReadonlySet<string>;
+/** One conflict as the context response carries it (a typed item or a plain object). */
+export type ConflictLike = Record<string, any>;
+export interface QuestionPhrasesInit {
+    action?: string;
+    question?: string;
+    claim_1?: string;
+    claim_2?: string;
+    topic?: string;
+}
+/**
+ * The natural-language pieces YOU write about THIS conflict.
+ *
+ * `action`: the verb of what is about to happen ("send", "reply", "share"); all three modes. `question`: a complete
+ * yes/no question about the fact, for `simple` ("Does Maya prefer email or phone?"). `claim_1` /
+ * `claim_2`: the two statements as they read after "you said" and "that", for `precise` ("Maya prefers email", "she prefers phone"). `topic`: what the notes conflict about, for `handoff` ("Maya's contact preference").
+ */
+export declare class QuestionPhrases {
+    readonly action: string;
+    readonly question: string;
+    readonly claim_1: string;
+    readonly claim_2: string;
+    readonly topic: string;
+    constructor(init?: QuestionPhrasesInit);
+}
+/**
+ * The words for the conflict being asked about: one `QuestionPhrases` (only while a single conflict can be asked),
+ * a function of the conflict item, or a map from `conflictKey` (a `Map` or a plain object).
+ */
+export type PhrasesSource = QuestionPhrases | QuestionPhrasesInit | ((conflict: ConflictLike) => QuestionPhrases | null | undefined) | ReadonlyMap<string, QuestionPhrases> | Readonly<Record<string, QuestionPhrases>>;
+/** Where YOUR app remembers which conflicts it has asked about, besides Harny's own memory. Optional. */
+export interface ConflictAskLedger {
+    has(key: string): boolean;
+    add(key: string): void;
+}
+/** A ledger held in memory: for tests and for a first draft. */
+export declare class InMemoryConflictAskLedger implements ConflictAskLedger {
+    private readonly asked;
+    constructor(asked?: Iterable<string>);
+    has(key: string): boolean;
+    add(key: string): void;
+    get size(): number;
+}
+/**
+ * The decision: `ask` and, when true, the `text` to put to the person. `reason` is `asked` or the first rule that
+ * failed: `kind_not_eligible`, `no_conflict`, `rule_dark`, `same_conversation`, `already_asked`,
+ * `ambiguous_phrases` (one `QuestionPhrases` offered while several conflicts could be asked), `missing_phrases`.
+ * `key` / `conflict` name the conflict asked about (or, for a refusal that found one, the one it stopped on); pass
+ * the decision itself, or `conflict`, to `markConflictAsked`.
+ */
+export interface ConflictQuestion {
+    ask: boolean;
+    reason: string;
+    text: string | null;
+    key: string | null;
+    conflict: ConflictLike | null;
+}
+export interface DecideConflictQuestionOptions {
+    /** `result.conflicts` of the context response. */
+    conflicts: ReadonlyArray<ConflictLike> | null | undefined;
+    /** The record ids of the conflicts the action's result depends on. */
+    dependsOn: Iterable<string> | string;
+    /** The kinds of action this is. */
+    actionKinds: Iterable<string> | string;
+    /** `result.conflict_question_mode`. No mode (null or undefined) means the question is off: do not ask. */
+    mode: string | null | undefined;
+    phrases: PhrasesSource;
+    ledger?: ConflictAskLedger;
+    /** Add the conflict to `ledger` when this returns an ask. */
+    record?: boolean;
+}
+/** One of `CONFLICT_QUESTION_MODES`; anything else is the default (the plain, no-dates question). */
+export declare function normaliseMode(value: unknown): ConflictQuestionMode;
+/** `2024-09-22` -> `Sept 22`. An empty string when the value is not an ISO day. */
+export declare function formatDay(isoDay: unknown): string;
+/** The question for `mode`. Throws on a missing phrase or an unreadable said-day (`precise` only). */
+export declare function questionText(mode: unknown, conflict: ConflictLike, phrases: QuestionPhrases): string;
+/**
+ * The identity of one conflict: the two stored notes behind it, in either order. The same value Harny puts in
+ * `conflicts[].conflict_key`, stable across responses, so "asked once" holds however the list is ordered.
+ */
+export declare function conflictKey(conflict: ConflictLike): string;
+/** Whether to ask now, and what to say. See the module comment for the rule. */
+export declare function decideConflictQuestion(options: DecideConflictQuestionOptions): ConflictQuestion;