@harny/sdk 0.0.1-alpha.1 → 0.1.0

package/dist/cjs/index.js

@@ -0,0 +1,1118 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RECALL_LEVELS = exports.questionText = exports.normaliseMode = exports.formatDay = exports.decideConflictQuestion = exports.conflictKey = exports.QuestionPhrases = exports.InMemoryConflictAskLedger = exports.DEFAULT_CONFLICT_QUESTION_MODE = exports.CONFLICT_QUESTION_MODES = exports.ASKING_KINDS = exports.resolvePreset = exports.parseTraceparent = exports.buildAdapter = exports.Usage = exports.Turn = exports.Tracer = exports.SpendMeter = exports.SpendCap = exports.RunResult = exports.ResolvedModel = exports.PresetResolutionError = exports.PRESET_NAMES = exports.ModelTurn = exports.ModelProviderError = exports.MessagesAdapter = exports.Message = exports.MemorySessionStore = exports.MODEL_REACHABLE_CALLS = exports.HookBlocked = exports.HarnyTools = exports.HARNY_CALLS = exports.GenerateContentAdapter = exports.FileSessionStore = exports.ChatCompletionsAdapter = exports.AgentPendingConfirmation = exports.AgentConfig = exports.Agent = exports.ActionTrace = exports.ActionNote = exports.ActDecision = exports.HarnyClient = exports.END_USER_MESSAGE_MAX_CHARS = exports.ACTION_KINDS = exports.HarnyMissingKeyError = exports.HarnyInvalidKeyError = exports.HarnyStateError = exports.HarnyError = void 0;
+exports.computeWebhookSignature = computeWebhookSignature;
+exports.verifyWebhookSignature = verifyWebhookSignature;
+exports.parseSourceArrivalEvent = parseSourceArrivalEvent;
+const util_js_1 = require("./agent/util.js");
+const memoryV1_js_1 = require("./memoryV1.js");
+const SDK_VERSION = "0.1.0";
+class HarnyError extends Error {
+    constructor(statusCode, errorCode, message, recoveryHint, docsUrl, retryAfterS, 
+    /** Field-level reasons when the API rejected the request's fields: where, why, and the kind. */
+    detail) {
+        super(message);
+        this.statusCode = statusCode;
+        this.errorCode = errorCode;
+        this.recoveryHint = recoveryHint;
+        this.docsUrl = docsUrl;
+        this.retryAfterS = retryAfterS;
+        this.detail = detail;
+        this.name = "HarnyError";
+    }
+}
+exports.HarnyError = HarnyError;
+/**
+ * Thrown for local state problems that never reach the network — calling a
+ * user-scoped method before `provisionUser`, or provisioning twice on one
+ * client. Mirrors the Python SDK's `HarnyStateError`.
+ */
+class HarnyStateError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "HarnyStateError";
+    }
+}
+exports.HarnyStateError = HarnyStateError;
+/** A key was given that is not text (a number, an object, ...). */
+class HarnyInvalidKeyError extends HarnyStateError {
+    constructor(message) {
+        super(message);
+        this.name = "HarnyInvalidKeyError";
+    }
+}
+exports.HarnyInvalidKeyError = HarnyInvalidKeyError;
+/** No API key was given and none was found in `HARNY_API_KEY` (or its alias `HARNY_APP_KEY`). */
+class HarnyMissingKeyError extends HarnyStateError {
+    constructor(message) {
+        super(message);
+        this.name = "HarnyMissingKeyError";
+    }
+}
+exports.HarnyMissingKeyError = HarnyMissingKeyError;
+const USER_ROLES = ["staff", "test"];
+const ANSWERED_BY = ["tap", "timeout", "dismissed", "server"];
+const CONFIRM_EDIT_FIELDS = [
+    "title",
+    "start",
+    "end",
+    "duration_minutes",
+    "time_zone",
+    "description",
+    "location",
+    "attendees",
+];
+const TRACEPARENT = /^00-[0-9a-f]{32}-[0-9a-f]{16}-[0-9a-f]{2}$/;
+function conflictRef(conflict, asked = false) {
+    if (asked && conflict?.ask === false) {
+        throw new Error("this decision says not to ask, so there is no question to report");
+    }
+    const inner = conflict?.conflict;
+    const source = (inner && typeof inner === "object" ? inner : conflict);
+    const ids = [];
+    for (const name of ["record_id_1", "record_id_2"]) {
+        const value = source?.[name];
+        if (typeof value !== "string" || !value.trim())
+            throw new Error(`${name} must be a non-blank string`);
+        ids.push(value.trim());
+    }
+    return { record_id_1: ids[0], record_id_2: ids[1] };
+}
+const BRIDGE_FINISHED = ["done", "failed", "expired"];
+const BRIDGE_SOURCES = ["gmail", "calendar", "drive"];
+function bridgeText(name, value) {
+    if (typeof value !== "string")
+        throw new Error(`${name} must be a string`);
+    const trimmed = value.trim();
+    if (!trimmed)
+        throw new Error(`${name} must not be blank`);
+    return trimmed;
+}
+function withTrace(headers, traceparent) {
+    if (traceparent === undefined)
+        return headers;
+    const value = traceparent.trim().toLowerCase();
+    // All-zero trace or span ids are invalid (W3C), and Harny would read the
+    // call as outside any run.
+    if (!TRACEPARENT.test(value) || value.split("-")[1] === "0".repeat(32) || value.split("-")[2] === "0".repeat(16)) {
+        throw new Error("traceparent must be a W3C trace context header: 00-<32 hex>-<16 hex>-<2 hex>");
+    }
+    return { ...(headers ?? {}), traceparent: value };
+}
+/** The four kinds of action, in the order Harny lists them everywhere. */
+exports.ACTION_KINDS = ["nobody_else", "others_affected", "money", "irreversible"];
+function toActionOutcome(payload) {
+    const block = (payload.action ?? {});
+    const confirmation = (block.confirmation ?? {});
+    const view = (block.model_view ?? {});
+    const outcome = {
+        executionId: String(payload.execution_id),
+        action: String(block.name ?? ""),
+        outcome: block.outcome ?? "failed",
+        kinds: Array.isArray(block.kinds) ? block.kinds : [],
+        kindReasons: Array.isArray(block.kind_reasons) ? block.kind_reasons : [],
+        decidedBy: block.decided_by ?? null,
+        recordId: block.record_id ?? null,
+        refusal: block.refusal ?? null,
+        result: block.result ?? null,
+        alreadyDecided: Boolean(block.already_decided),
+        replayed: Boolean(block.replayed),
+        confirmExpiresAt: confirmation.expires_at ?? null,
+        forModel: () => ({
+            status: String(view.status ?? block.outcome ?? "failed"),
+            message: String(view.message ?? block.outcome ?? "failed"),
+        }),
+    };
+    Object.defineProperty(outcome, "forModel", { enumerable: false });
+    if (typeof confirmation.confirm_ref === "string") {
+        Object.defineProperty(outcome, "confirmRef", {
+            value: confirmation.confirm_ref,
+            enumerable: false,
+        });
+    }
+    return outcome;
+}
+/**
+ * The longest end-user message Harny reads for the addresses it names; a
+ * longer one is sent cut to this length (addresses past it are not read).
+ */
+exports.END_USER_MESSAGE_MAX_CHARS = 100000;
+/** The end user's own words as sent, or undefined when there are none. */
+function endUserWords(value) {
+    if (value === undefined || value === null)
+        return undefined;
+    if (typeof value !== "string")
+        throw new Error("endUserMessage must be a string");
+    if (!value.trim())
+        return undefined;
+    return value.slice(0, exports.END_USER_MESSAGE_MAX_CHARS);
+}
+/** The `Idempotency-Key` header next to the acting-user headers; the same value as the body's `idempotencyKey`. */
+function withIdempotencyHeader(headers, key) {
+    if (!key)
+        return headers;
+    return { ...(headers ?? {}), "Idempotency-Key": key };
+}
+function newIdempotencyKey() {
+    const random = typeof globalThis.crypto?.randomUUID === "function"
+        ? globalThis.crypto.randomUUID()
+        : `${Date.now()}-${Math.random().toString(16).slice(2)}`;
+    return `sdk-${random}`;
+}
+const MAX_FALLBACK_MESSAGE_CHARS = 200;
+/**
+ * The error for an answer that is not Harny's JSON envelope: a proxy, load balancer or parked host answered with a page.
+ * A short plain-text body is kept (it is usually the real reason); markup and long bodies give way to the status.
+ * 502, 503 and 504 say that nothing reached the API, and the hint names the address to check.
+ */
+function unreadableErrorBody(status, text) {
+    const body = text.trim();
+    const looksLikeMarkup = body.startsWith("<") || body.slice(0, 512).toLowerCase().includes("<html");
+    const gateway = status === 502 || status === 503 || status === 504;
+    const hint = gateway
+        ? "Check baseUrl (or HARNY_API_URL) and that the host is serving, then try again. Nothing was read or written."
+        : "";
+    if (body && !looksLikeMarkup && body.length <= MAX_FALLBACK_MESSAGE_CHARS) {
+        return new HarnyError(status, "UNKNOWN", body, hint, "", null);
+    }
+    if (gateway) {
+        return new HarnyError(status, "UNKNOWN", `The request did not reach the Harny API (HTTP ${status} from an upstream gateway)`, hint, "", null);
+    }
+    return new HarnyError(status, "UNKNOWN", `Request failed with status ${status}`, hint, "", null);
+}
+/** The API's field-level reasons for a rejected request: where, why and the kind. The submitted values are dropped (they can hold a secret). */
+function fieldDetail(body) {
+    if (!Array.isArray(body.detail))
+        return undefined;
+    const rows = [];
+    for (const entry of body.detail) {
+        if (typeof entry === "object" && entry !== null && typeof entry.msg === "string") {
+            const e = entry;
+            rows.push({
+                loc: Array.isArray(e.loc) ? e.loc.map((part) => String(part)) : [],
+                msg: e.msg,
+                ...(typeof e.type === "string" ? { type: e.type } : {}),
+            });
+        }
+    }
+    return rows.length > 0 ? rows : undefined;
+}
+function describeFields(rows) {
+    return rows.map((row) => (row.loc.length > 0 ? `${row.loc.join(".")}: ${row.msg}` : row.msg)).join("; ");
+}
+function parseError(status, body) {
+    if (typeof body === "object" && body !== null) {
+        const obj = body;
+        const rows = fieldDetail(obj);
+        // The memory routes' error body: { code, status, debugMessage, data }.
+        if (typeof obj.code === "string" && typeof obj.debugMessage === "string" && obj.error_code === undefined) {
+            return new HarnyError(status, obj.code, obj.debugMessage, "", "", obj.retry_after_s ?? null);
+        }
+        if (typeof obj.error_code === "string") {
+            const message = obj.message ?? "Request failed";
+            return new HarnyError(status, obj.error_code, rows ? `${message} (${describeFields(rows)})` : message, obj.recovery_hint ?? "", obj.docs_url ?? "", obj.retry_after_s ?? null, rows);
+        }
+        if (typeof obj.detail === "string") {
+            return new HarnyError(status, "UNKNOWN", obj.detail, "", "", null);
+        }
+        if (Array.isArray(obj.detail)) {
+            return new HarnyError(status, "VALIDATION_ERROR", rows
+                ? describeFields(rows)
+                : obj.detail.map((d) => String(d)).join("; "), "", "", null, rows);
+        }
+    }
+    return new HarnyError(status, "UNKNOWN", "Request failed", "", "", null);
+}
+/**
+ * A person's context reads are limited per minute (and per day by plan): the
+ * API answers `assembly_rate_limited`. What happened and what to do, in plain
+ * words, with the wait filled in. The Python client
+ * writes the same text, so an agent's model reads the same words from either
+ * SDK.
+ */
+const CONTEXT_READ_LIMIT_CODE = "assembly_rate_limited";
+const CONTEXT_READ_LIMIT_HINT = "This person has reached Harny's limit on context reads for now; no new key is needed.";
+/** A response's `Retry-After` header, if the response carries headers at all. */
+function retryAfterHeader(response) {
+    const headers = response.headers;
+    return typeof headers?.get === "function" ? headers.get("retry-after") : null;
+}
+/** Seconds from a `Retry-After` header, read as the Python client reads it (at least 1). */
+function retryAfterFromHeader(value) {
+    const text = value.trim();
+    return /^[+-]?\d+$/.test(text) ? Math.max(1, Number.parseInt(text, 10)) : 1;
+}
+/**
+ * A 429 says what happened and what to do: `retryAfterS` comes from the
+ * `Retry-After` header when the body has none, and a person's context-read
+ * limit says so in plain words, with the wait.
+ */
+function withRateLimitDetail(error, headerValue) {
+    if (error.statusCode !== 429)
+        return error;
+    let retryAfterS = error.retryAfterS;
+    if (retryAfterS === null && headerValue !== null)
+        retryAfterS = retryAfterFromHeader(headerValue);
+    let hint = error.recoveryHint;
+    if (error.errorCode === CONTEXT_READ_LIMIT_CODE) {
+        hint =
+            retryAfterS !== null
+                ? `${CONTEXT_READ_LIMIT_HINT} Wait ${retryAfterS} s, then read again.`
+                : `${CONTEXT_READ_LIMIT_HINT} ${hint.trim()}`.trim();
+    }
+    if (retryAfterS === error.retryAfterS && hint === error.recoveryHint)
+        return error;
+    return new HarnyError(error.statusCode, error.errorCode, error.message, hint, error.docsUrl, retryAfterS, error.detail);
+}
+/** `HARNY_API_KEY`, else its alias `HARNY_APP_KEY`, from the process environment, trimmed; undefined when unset, blank, or there is no process (browser). */
+function environmentApiKey() {
+    const env = (0, util_js_1.processEnv)();
+    return (env.HARNY_API_KEY ?? "").trim() || (env.HARNY_APP_KEY ?? "").trim() || undefined;
+}
+/** `HARNY_API_URL` from the process environment, trimmed; empty when unset, blank, or there is no process (browser). */
+function environmentApiUrl() {
+    return ((0, util_js_1.processEnv)().HARNY_API_URL ?? "").trim();
+}
+class HarnyClient {
+    constructor({ apiKey, userApiKey, baseUrl, timeoutMs } = {}) {
+        for (const [name, given] of [["apiKey", apiKey], ["userApiKey", userApiKey]]) {
+            if (given !== undefined && given !== null && typeof given !== "string") {
+                throw new HarnyInvalidKeyError(`${name} must be a string (the key itself, starting with fsa_ or fsk_), got ${typeof given}. ` +
+                    "Read it from the environment: process.env.HARNY_API_KEY");
+            }
+        }
+        const trimmedUser = userApiKey?.trim();
+        // With no key given, Node reads HARNY_API_KEY (HARNY_APP_KEY is the older name some setup files still write).
+        // Nothing is read in a browser: there is no process, and a key in a browser bundle is public.
+        const trimmedApp = apiKey?.trim() || (trimmedUser ? undefined : environmentApiKey());
+        if (!trimmedApp && !trimmedUser) {
+            throw new HarnyMissingKeyError("Provide apiKey (the app key, starts with fsa_) or userApiKey (one person's key, starts with fsk_), " +
+                "or set the HARNY_API_KEY environment variable.");
+        }
+        if (trimmedApp && trimmedApp.startsWith("fsk_")) {
+            throw new Error("apiKey expects an app key (prefix 'fsa_'). You passed a user key (prefix 'fsk_'). Use userApiKey for user keys.");
+        }
+        if (trimmedUser && trimmedUser.startsWith("fsa_")) {
+            throw new Error("userApiKey expects a user key (prefix 'fsk_'). You passed an app key (prefix 'fsa_'). Use apiKey for app keys.");
+        }
+        this.apiKey = trimmedApp || undefined;
+        this.userApiKeyValue = trimmedUser || undefined;
+        this.userKeyGiven = Boolean(trimmedUser);
+        // An explicit baseUrl wins; without one the client reads HARNY_API_URL (the Python SDK's rule), else the public API.
+        this.baseUrl = this.resolveBaseUrl(baseUrl ?? (environmentApiUrl() || "https://api.harny.ai"));
+        this.timeoutMs = timeoutMs ?? 20000;
+        // The keys are never listed, logged or serialized with the client.
+        for (const field of ["apiKey", "userApiKeyValue"]) {
+            Object.defineProperty(this, field, { enumerable: false, writable: true, configurable: true });
+        }
+    }
+    /** A key-free view: `JSON.stringify(client)` never carries a key. */
+    toJSON() {
+        return { baseUrl: this.baseUrl, appKey: this.apiKey ? "set" : "not set", userKey: this.userApiKeyValue ? "set" : "not set" };
+    }
+    /**
+     * The current user-scoped key, or `undefined` before `provisionUser`.
+     * Persist it to restore this user's session on a later run instead of
+     * provisioning again (provisioning is rate-limited).
+     */
+    get userApiKey() {
+        return this.userApiKeyValue;
+    }
+    resolveBaseUrl(url) {
+        const trimmed = url.trim().replace(/\/+$/, "");
+        let parsed;
+        try {
+            parsed = new URL(trimmed);
+        }
+        catch {
+            throw new Error("baseUrl must be a valid absolute http/https URL");
+        }
+        if (parsed.protocol !== "https:" && parsed.protocol !== "http:") {
+            throw new Error("baseUrl must be a valid absolute http/https URL");
+        }
+        // Every call carries a key: plain http only to this machine.
+        if (parsed.protocol === "http:" && !["localhost", "127.0.0.1", "[::1]"].includes(parsed.hostname.toLowerCase())) {
+            throw new Error("baseUrl must use https unless the host is localhost or a loopback address");
+        }
+        return trimmed.endsWith("/v1") ? trimmed : `${trimmed}/v1`;
+    }
+    bearer(mode, operation) {
+        if (mode === "user") {
+            if (!this.userApiKeyValue) {
+                throw new HarnyStateError(`${operation} is user-scoped. Call provisionUser({ identifier, email }) first, ` +
+                    "or construct the client with userApiKey: 'fsk_...' to restore an existing session. " +
+                    "If that person already existed, Harny does not show their key twice: use the key you saved, " +
+                    "or use the app key and name the person with user.");
+            }
+            return `Bearer ${this.userApiKeyValue}`;
+        }
+        if (mode === "app") {
+            if (!this.apiKey) {
+                throw new HarnyStateError(`${operation} needs an app key. Construct the client with apiKey: 'fsa_...'.`);
+            }
+            return `Bearer ${this.apiKey}`;
+        }
+        const key = this.userApiKeyValue ?? this.apiKey;
+        return `Bearer ${key}`;
+    }
+    async request(method, path, mode, operation, body, extraHeaders) {
+        const url = `${this.baseUrl}${path}`;
+        const headers = {
+            "Authorization": this.bearer(mode, operation),
+            "User-Agent": `harny-ts-sdk/${SDK_VERSION}`,
+            ...(extraHeaders ?? {}),
+        };
+        const init = {
+            method,
+            headers,
+            signal: AbortSignal.timeout(this.timeoutMs),
+        };
+        if (body !== undefined && body instanceof FormData) {
+            init.body = body;
+        }
+        else if (body !== undefined) {
+            headers["Content-Type"] = "application/json";
+            init.body = JSON.stringify(body);
+        }
+        let response;
+        try {
+            response = await fetch(url, init);
+        }
+        catch (err) {
+            if (err instanceof DOMException && err.name === "TimeoutError") {
+                throw new HarnyError(0, "TIMEOUT", `Request timed out after ${this.timeoutMs}ms`, "", "", null);
+            }
+            if (err instanceof DOMException && err.name === "AbortError") {
+                throw new HarnyError(0, "ABORTED", "Request was aborted", "", "", null);
+            }
+            if (err instanceof TypeError) {
+                throw new HarnyError(0, "NETWORK_ERROR", err.message || "Network request failed", "Nothing reached Harny. Check baseUrl (or HARNY_API_URL) and your network connection, then try again.", "", null);
+            }
+            throw err;
+        }
+        if (response.ok) {
+            const text = await response.text();
+            if (!text)
+                return undefined;
+            return JSON.parse(text);
+        }
+        let errorBody;
+        let errorText = "";
+        try {
+            errorText = await response.text();
+            errorBody = JSON.parse(errorText);
+        }
+        catch {
+            throw withRateLimitDetail(unreadableErrorBody(response.status, errorText), retryAfterHeader(response));
+        }
+        throw withRateLimitDetail(parseError(response.status, errorBody), retryAfterHeader(response));
+    }
+    /**
+     * Per-subsystem health snapshot. Needs no user session; with one, the
+     * response also carries per-source freshness.
+     */
+    async diagnose() {
+        return this.request("GET", "/harness/diagnose", "any", "diagnose");
+    }
+    /**
+     * Create or retrieve one app-scoped end user and switch this client to
+     * that user's key. Call it again for the next person: the client then
+     * acts for that person.
+     *
+     * Requires an `fsa_` app key. Provisioning is rate-limited: persist
+     * `client.userApiKey` and reuse it instead of re-provisioning per run.
+     * For a person who already exists, the call returns that user and no new
+     * key: nothing new is cached (name the person with `user`).
+     */
+    async provisionUser(identifier, email, options) {
+        if (this.userKeyGiven) {
+            throw new HarnyStateError("This client was built with one person's key (userApiKey), so it acts only for that person. " +
+                "To add people, construct a HarnyClient with the app key (apiKey).");
+        }
+        const trimmedIdentifier = identifier?.trim();
+        if (!trimmedIdentifier) {
+            throw new Error("identifier must be a non-empty string");
+        }
+        const trimmedEmail = email?.trim();
+        if (!trimmedEmail) {
+            throw new Error("email must be a non-empty string");
+        }
+        const role = options?.role;
+        if (role !== undefined && role !== null && !USER_ROLES.includes(role)) {
+            throw new Error(`role must be one of ${USER_ROLES.join(", ")}, or null to remove the mark`);
+        }
+        const payload = await this.request("POST", "/users", "app", "provisionUser", {
+            identifier: trimmedIdentifier,
+            identifier_type: options?.identifier_type ?? "app_id",
+            email: trimmedEmail,
+            email_trust_level: options?.email_trust_level ?? "app_asserted",
+            ...(role !== undefined ? { role } : {}),
+        });
+        const issued = payload?.api_key;
+        if (typeof issued === "string" && issued.trim()) {
+            this.userApiKeyValue = issued.trim();
+            this.provisionedUserId = payload.user?.id;
+        }
+        else if (this.provisionedUserId !== undefined && this.provisionedUserId !== payload.user?.id) {
+            // No key in the answer means the person already existed: Harny shows a user key once, when the person is
+            // first made. The call still succeeded and the user is returned. The client was acting as an earlier
+            // person, so stop: a later call without `user` must not write into that other person's vault.
+            // Use the app key with `user`, or construct the client with the `userApiKey` you saved.
+            this.userApiKeyValue = undefined;
+            this.provisionedUserId = undefined;
+        }
+        return payload.user;
+    }
+    /**
+     * Persist a plain-text document to the user's vault (the provisioned
+     * user's, or `options.user` with an app key). `options.writtenByPerson`:
+     * set only when the text is the person's own typed words, never pasted,
+     * received or model-written content, and only with `options.user` (your
+     * app key for that person); it is ignored with the person's own key. An
+     * email address in such text then counts as one the person gave: after
+     * your agent read someone else's content, an invitation or message to it
+     * follows your settings instead of waiting for their yes.
+     */
+    async ingestText(content, title, options) {
+        const body = { content };
+        if (title !== undefined)
+            body.title = title;
+        if (options?.writtenByPerson)
+            body.written_by_person = true;
+        // The server accepts a long note, answers `queued` after about 15 seconds and finishes in the background; the key makes a
+        // repeat of THIS call (a timeout, a dropped connection) the same ingest, never a second one or a second charge. One key per
+        // call, kept across the single automatic retry below. Pass `idempotencyKey` to reuse a key across your own retries.
+        const key = options?.idempotencyKey ?? newIdempotencyKey();
+        const send = () => {
+            if (options?.user === undefined) {
+                return this.request("POST", "/vault/ingest/text", "user", "ingestText", body, { "Idempotency-Key": key });
+            }
+            const [mode, headers] = this.actingAuth(options.user, "ingestText");
+            return this.request("POST", "/vault/ingest/text", mode, "ingestText", body, { ...headers, "Idempotency-Key": key });
+        };
+        return this.retryOnceWhenLost(send);
+    }
+    /** Run an idempotent request; if the answer never arrived (timeout or dropped connection), send it once more with the same key. */
+    async retryOnceWhenLost(send) {
+        try {
+            return await send();
+        }
+        catch (err) {
+            if (err instanceof HarnyError && (err.errorCode === "TIMEOUT" || err.errorCode === "NETWORK_ERROR")) {
+                return send();
+            }
+            throw err;
+        }
+    }
+    /** Upload a binary file to the provisioned user's vault. */
+    async ingestFile(file, filename) {
+        const form = new FormData();
+        // A Node Buffer is a Uint8Array; FormData takes bytes only as a Blob, so wrap them. The cast quiets the type
+        // difference between Node and DOM Blob declarations.
+        const part = file instanceof Uint8Array ? new Blob([file]) : file;
+        form.append("file", part, filename ?? "upload");
+        return this.request("POST", "/vault/ingest/file", "user", "ingestFile", form);
+    }
+    /**
+     * Retrieve assembled context for a query.
+     *
+     * Check `result.degraded_sources` before treating an empty `blocks` array
+     * as "this user has no data" — a non-empty array means retrieval FAILED
+     * for those sources.
+     */
+    async assembleContext(query, options, target) {
+        if (options?.token_budget !== undefined) {
+            if (!Number.isInteger(options.token_budget) ||
+                options.token_budget < 256 ||
+                options.token_budget > 128000) {
+                throw new Error("token_budget must be an integer between 256 and 128000");
+            }
+        }
+        if (options?.min_relevance_score !== undefined &&
+            options.min_relevance_score !== null) {
+            const score = options.min_relevance_score;
+            if (typeof score !== "number" || Number.isNaN(score) || score < 0 || score > 1) {
+                throw new Error("min_relevance_score must be a number between 0 and 1");
+            }
+        }
+        if (options?.conversation_context !== undefined &&
+            options.conversation_context !== null &&
+            options.conversation_context.length > 5) {
+            throw new Error("conversation_context accepts at most 5 turns");
+        }
+        // Built field by field: the API's ContextAssembleRequest is
+        // `extra="forbid"`, so an unknown key here is a 422, not an ignored
+        // hint. Never spread caller-supplied options into this body.
+        const body = { query };
+        if (options?.token_budget !== undefined)
+            body.token_budget = options.token_budget;
+        if (options?.assembly_profile !== undefined) {
+            body.assembly_profile = options.assembly_profile;
+        }
+        if (options?.thread_id !== undefined)
+            body.thread_id = options.thread_id;
+        if (options?.include_tools !== undefined)
+            body.include_tools = options.include_tools;
+        if (options?.source_filter !== undefined)
+            body.source_filter = options.source_filter;
+        if (options?.min_relevance_score !== undefined) {
+            body.min_relevance_score = options.min_relevance_score;
+        }
+        if (options?.conversation_context !== undefined) {
+            body.conversation_context = options.conversation_context;
+        }
+        const [mode, headers] = this.actingAuth(target?.user, "assembleContext");
+        return this.request("POST", "/context/assemble", mode, "assembleContext", body, withTrace(headers, target?.traceparent));
+    }
+    /**
+     * Tell Harny you asked the user about a conflict, so the question is not put twice. Call it BEFORE you show the
+     * question `decideConflictQuestion` returned, and show it only when the result's `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. The
+     * next context response marks that conflict `asked`. `conflict` is a `ContextConflict`, an object with its
+     * `record_id_1` and `record_id_2`, or the decision itself (a decision that says not to ask is refused). Safe to repeat. `options.user`: the end user (needs an app key); omit it
+     * on a client that provisioned a user. Never expose this to a model as a tool: asking is your confirm step's.
+     * Throws `HarnyError` (404, `conflict_not_found`) for a conflict that was not in this user's context response.
+     */
+    async markConflictAsked(conflict, options) {
+        const body = conflictRef(conflict, true);
+        const [mode, headers] = this.actingAuth(options?.user, "markConflictAsked");
+        return this.request("POST", "/conflicts/asked", mode, "markConflictAsked", body, withTrace(headers, options?.traceparent));
+    }
+    /**
+     * Send the user's answer to a conflict. It is saved as something the user said, and the conflict is no
+     * longer returned. `answer` is the user's answer as a statement that stands on its own, in their words (for
+     * example "Maya prefers email"); it is saved the way `ingestText` saves text and goes through the
+     * same limits. Throws `HarnyError` as `ingestText` does (for example when the memory service is unavailable;
+     * nothing is marked answered then), and 404 `conflict_not_found` for a conflict that was not in this user's
+     * context response (nothing is saved then). `conflict` and `options` are as for `markConflictAsked`.
+     */
+    async answerConflict(conflict, answer, options) {
+        const text = typeof answer === "string" ? answer.trim() : "";
+        if (!text)
+            throw new Error("answer must not be blank");
+        const body = { ...conflictRef(conflict), answer: text };
+        const [mode, headers] = this.actingAuth(options?.user, "answerConflict");
+        return this.request("POST", "/conflicts/answer", mode, "answerConflict", body, withTrace(headers, options?.traceparent));
+    }
+    /**
+     * Read one arrived email (an arrival's `item_ref`) for its end user. The
+     * text comes back hardened — secrets redacted, instruction-like lines
+     * removed — and is third-party content: pass it to a model as data only.
+     */
+    async getSourceItem(itemRef, options) {
+        const [mode, headers] = this.actingAuth(options?.user, "getSourceItem");
+        return this.request("GET", `/context-sources/items/${encodeURIComponent(itemRef)}`, mode, "getSourceItem", undefined, withTrace(headers, options?.traceparent));
+    }
+    /**
+     * Poll new items that arrived on your end users' email sources (app key),
+     * oldest first — the same arrivals the `source.sync_complete` webhook
+     * delivers. Pass the last `next_cursor` as `after`; process each
+     * `dedupe_key` once. `user` narrows to one end user.
+     */
+    async listArrivals(options) {
+        const after = options?.after ?? 0;
+        const limit = options?.limit ?? 50;
+        if (!Number.isInteger(after) || after < 0) {
+            throw new Error("after must be a non-negative integer cursor");
+        }
+        if (!Number.isInteger(limit) || limit < 1 || limit > 200) {
+            throw new Error("limit must be an integer from 1 to 200");
+        }
+        const headers = options?.user !== undefined ? { "X-Harny-User": options.user } : undefined;
+        return this.request("GET", `/context-sources/arrivals?after=${after}&limit=${limit}`, "app", "listArrivals", undefined, withTrace(headers, options?.traceparent));
+    }
+    /**
+     * Start an OAuth flow for one external source. Send the end user to the
+     * returned `authorization_url`.
+     *
+     * Which providers a deployment can connect varies, and Gmail / Calendar /
+     * Drive sit behind Early Access approval — do not hardcode a provider
+     * name without checking the account's access first.
+     *
+     * `sharedFactsOptIn` passes the person's own answer to Harny's sharing
+     * question, the one Harny's connect widget shows (unticked). Send `true`
+     * only when the person themselves ticked it: Harny keeps the answer with
+     * this connect and saves it, as the person's own choice, when the
+     * connection completes. `false` and leaving it out record nothing and never
+     * withdraw an earlier yes. A person flagged as a child is never opted in.
+     * Anything but `true` or `false` throws.
+     */
+    async connectSource(provider, returnUrl, options) {
+        const body = {};
+        if (returnUrl !== undefined)
+            body.return_url = returnUrl;
+        if (options?.capabilities?.length)
+            body.capabilities = options.capabilities;
+        if (options?.sharedFactsOptIn !== undefined) {
+            if (typeof options.sharedFactsOptIn !== "boolean") {
+                throw new Error("sharedFactsOptIn must be true or false");
+            }
+            body.shared_facts_opt_in = options.sharedFactsOptIn;
+        }
+        const [mode, headers] = this.actingAuth(options?.user, "connectSource");
+        return this.request("POST", `/context-sources/${encodeURIComponent(provider)}/connect`, mode, "connectSource", body, headers);
+    }
+    /** The end user an action is for: app key + named user, or the user's own key. */
+    actingAuth(user, operation) {
+        if (user !== undefined) {
+            if (!this.apiKey) {
+                throw new HarnyStateError(`${operation} with user needs an app key. Construct the client with apiKey: 'fsa_...'.`);
+            }
+            return ["app", { "X-Harny-User": user }];
+        }
+        return ["user", undefined];
+    }
+    /**
+     * Perform one catalog action (for example `calendar.create_event`) for one
+     * end user. Harny works out which kinds of action it is from what it does,
+     * follows the most careful of your business's settings for those kinds,
+     * checks the user's write consent, performs the action and records the
+     * outcome. No model is called. Tell a model only `outcome.forModel()`.
+     * After your agent read someone else's content (an email, a calendar
+     * entry, a shared document), where your setting is act, an invitation or
+     * message to an address the person never gave waits for their yes; with
+     * `initiatedBy: "system_event"` it always does. `endUserMessage`: the
+     * person's own words for this request (their chat message), from your
+     * backend, never a model; an email address in them counts as given. Only
+     * the addresses are kept, never the words; with `initiatedBy:
+     * "system_event"` they are not counted.
+     */
+    async act(action, args, options) {
+        const body = {
+            action,
+            arguments: args,
+            request_hash: options?.idempotencyKey ?? newIdempotencyKey(),
+        };
+        if (options?.initiatedBy)
+            body.initiated_by = options.initiatedBy;
+        if (options?.correlationId)
+            body.correlation_id = options.correlationId;
+        const words = endUserWords(options?.endUserMessage);
+        if (words !== undefined)
+            body.end_user_message = words;
+        const [mode, headers] = this.actingAuth(options?.user, "act");
+        const payload = await this.request("POST", "/tools/execute", mode, "act", body, withTrace(headers, options?.traceparent));
+        return toActionOutcome(payload);
+    }
+    /**
+     * Send the end user's decision on an ask-first action, from your UI
+     * handler. Never expose this to a model as a tool.
+     *
+     * `answeredBy` says how the card was answered, as your app knows it: `tap` (the person pressed the button),
+     * `timeout` (the card ran out of time), `dismissed` (the person closed it without choosing) or `server` (your backend
+     * answered without showing a card). Leave it out when you do not know; an answer marked `timeout`, `dismissed` or
+     * `server` is not counted as a person's choice when Harny reads how your users answer.
+     *
+     * `edit` is what the person corrected on the card before approving it (only with `approve: true`, for a calendar
+     * event): `title`, `start`, `end`, `duration_minutes`, `time_zone`, `description`, `location`, or a shorter guest list in
+     * `attendees` (the same guests or fewer). The corrected action is the one that runs, and the record shows what changed.
+     * An edit never adds a guest: one who was not on the card is refused (`confirm_edit_not_allowed`) and the card stays
+     * open; the agent proposes that as a new request. Any other field throws before a call is made.
+     */
+    async confirm(executionId, confirmRef, approve, options) {
+        const [mode, headers] = this.actingAuth(options?.user, "confirm");
+        const answeredBy = options?.answeredBy;
+        if (answeredBy !== undefined && !ANSWERED_BY.includes(answeredBy)) {
+            throw new Error(`answeredBy must be one of ${ANSWERED_BY.join(", ")}`);
+        }
+        const edit = options?.edit;
+        if (edit !== undefined) {
+            if (!approve) {
+                throw new Error("edit goes with approve: true: a declined card changes nothing");
+            }
+            if (edit === null || typeof edit !== "object" || Array.isArray(edit) || Object.keys(edit).length === 0) {
+                throw new Error("edit must be an object of the fields the person changed");
+            }
+            const unknown = Object.keys(edit).filter((key) => !CONFIRM_EDIT_FIELDS.includes(key));
+            if (unknown.length > 0) {
+                throw new Error(`edit can change only ${CONFIRM_EDIT_FIELDS.join(", ")}; not ${unknown.join(", ")}. ` +
+                    "A guest who was not on the card is a new request, not an edit.");
+            }
+        }
+        const payload = await this.request("POST", `/tools/executions/${encodeURIComponent(executionId)}/confirm`, mode, "confirm", {
+            confirm_ref: confirmRef,
+            approve,
+            ...(answeredBy !== undefined ? { answered_by: answeredBy } : {}),
+            ...(edit !== undefined ? { edit: { ...edit } } : {}),
+        }, withTrace(headers, options?.traceparent));
+        return toActionOutcome(payload);
+    }
+    /**
+     * Mint a short-lived token for ONE end user (app key), for a hosted agent
+     * runtime's MCP connection. The runtime reads that person's context and
+     * performs catalog actions for that person only, through your acting
+     * policy, until the token expires. It also reads that person's action
+     * history by default (`actionHistory: false` leaves it out).
+     */
+    async mintRuntimeToken(user, options) {
+        if (!user || !user.trim()) {
+            throw new Error("user is required: a runtime token acts for exactly one end user");
+        }
+        const body = { read_only: Boolean(options?.readOnly) };
+        if (options?.ttlSeconds !== undefined)
+            body.ttl_seconds = options.ttlSeconds;
+        if (options?.actions !== undefined)
+            body.actions = options.actions;
+        if (options?.initiatedBy !== undefined)
+            body.initiated_by = options.initiatedBy;
+        if (options?.label !== undefined)
+            body.label = options.label;
+        if (options?.connectUrl !== undefined)
+            body.connect_url = options.connectUrl;
+        if (options?.userDrivenOnly)
+            body.user_driven_only = true;
+        if (options?.actionHistory === false)
+            body.action_history = false;
+        const words = endUserWords(options?.endUserMessage);
+        if (words !== undefined)
+            body.end_user_message = words;
+        return this.request("POST", "/runtime-tokens", "app", "mintRuntimeToken", body, {
+            "X-Harny-User": user.trim(),
+        });
+    }
+    /** Revoke one runtime token now (app key). Rotating the app key revokes them all. */
+    async revokeRuntimeToken(tokenId) {
+        return this.request("DELETE", `/runtime-tokens/${encodeURIComponent(tokenId)}`, "app", "revokeRuntimeToken");
+    }
+    /**
+     * The confirm reference of an ask-first action a hosted runtime asked for
+     * over MCP (app key). Call it when the approval-needed webhook names the
+     * execution, show your confirm card, then `confirm(...)`.
+     */
+    async getPendingConfirmation(executionId, options) {
+        if (!options?.user || !options.user.trim()) {
+            throw new Error("user is required: name the end user the action was for");
+        }
+        return this.request("GET", `/tools/executions/${encodeURIComponent(executionId)}/confirmation`, "app", "getPendingConfirmation", undefined, { "X-Harny-User": options.user.trim() });
+    }
+    /**
+     * Set up the person's Google bridge: a small script they copy into their own Google account.
+     *
+     * Call it first without `acceptedTextSha256`: it returns `{ registered: false, consent, next_step }`. Show the
+     * person `consent.text` and ask which of `gmail`, `calendar` and `drive` to include. After their yes, call it
+     * again with `acceptedTextSha256: consent.text_sha256` (and `sources`): it registers and returns the setup
+     * answer once (`setup_code`, `script_properties`, `agent_instructions`). Needs the bridge to be switched on for
+     * your deployment (otherwise a 404 `google_bridge_off`). `user`: as in `act`.
+     */
+    async googleBridgeSetup(sources, options) {
+        const [mode, headers] = this.actingAuth(options?.user, "googleBridgeSetup");
+        if (options?.acceptedTextSha256 === undefined) {
+            const consent = await this.request("GET", "/google-bridge/consent", mode, "googleBridgeSetup", undefined, headers);
+            return {
+                registered: false,
+                consent,
+                next_step: "Show the person consent.text and ask which of gmail, calendar and drive to include. After their yes, call " +
+                    "googleBridgeSetup again with acceptedTextSha256: consent.text_sha256 (and sources: [...]).",
+            };
+        }
+        const body = {
+            accepted_text_sha256: bridgeText("acceptedTextSha256", options.acceptedTextSha256),
+        };
+        if (options.label !== undefined)
+            body.label = options.label;
+        if (sources !== undefined) {
+            const chosen = sources.map((item) => bridgeText("sources", item).toLowerCase());
+            const unknown = chosen.filter((item) => !BRIDGE_SOURCES.includes(item));
+            if (unknown.length) {
+                throw new Error(`sources must be some of ${BRIDGE_SOURCES.join(", ")}; got ${unknown.join(", ")}`);
+            }
+            body.sources = chosen;
+        }
+        const answer = await this.request("POST", "/google-bridge/register", mode, "googleBridgeSetup", body, headers);
+        return { ...answer, registered: true };
+    }
+    /**
+     * Ask the person's Google bridge to do one thing in their own Google account.
+     *
+     * `kind`: `gmail.send`, `gmail.draft`, `gmail.search`, `gmail.read`, `calendar.list`, `calendar.create`,
+     * `calendar.delete`, `drive.search`, `drive.read` or `drive.create`; `params` holds that kind's fields. With
+     * `wait` (the default) it polls until the action is `done`, `failed` or `expired`, or `timeoutMs` pass, and
+     * returns the last view: check `status`. A send, draft or create whose delivery is unconfirmed is not repeated:
+     * read `status` before asking again. `user`: as in `act`.
+     */
+    async googleBridgeAct(kind, params, options) {
+        const [mode, headers] = this.actingAuth(options?.user, "googleBridgeAct");
+        let view = await this.request("POST", "/google-bridge/actions", mode, "googleBridgeAct", { kind: bridgeText("kind", kind), params: { ...(params ?? {}) } }, headers);
+        const wait = options?.wait ?? true;
+        const deadline = Date.now() + Math.max(0, options?.timeoutMs ?? 30000);
+        const pause = Math.max(0, options?.pollIntervalMs ?? 1000);
+        while (wait && !BRIDGE_FINISHED.includes(view.status) && Date.now() < deadline) {
+            await new Promise((resolve) => setTimeout(resolve, pause));
+            view = await this.request("GET", `/google-bridge/actions/${encodeURIComponent(bridgeText("action_id", String(view.action_id)))}`, mode, "googleBridgeAct", undefined, headers);
+        }
+        return view;
+    }
+    /** Undo an action your agent performed, by its action-record id. */
+    async undo(recordId, options) {
+        return this.act("calendar.delete_event", { reverses: recordId }, options);
+    }
+    /**
+     * Read the platform model roster (app key): presets over provider/model
+     * entries with capability flags, region hints and list prices. Your agent
+     * runs on your own model key.
+     */
+    async getModelRoster() {
+        return this.request("GET", "/models/roster", "app", "getModelRoster");
+    }
+    /**
+     * The setup bundle a coding assistant stands your agent up from (app key).
+     * It names key variables and never carries a key.
+     */
+    async getSetupBundle(appId, options) {
+        const body = {
+            shape: options.shape,
+            deploy_target: options.deployTarget ?? "unspecified",
+        };
+        if (options.preset !== undefined)
+            body.preset = options.preset;
+        if (options.surface !== undefined)
+            body.surface = options.surface;
+        if (options.sources?.length)
+            body.sources = options.sources;
+        if (options.actions?.length)
+            body.actions = options.actions;
+        if (options.emailArrivalTrigger !== undefined)
+            body.email_arrival_trigger = options.emailArrivalTrigger;
+        if (options.description !== undefined)
+            body.description = options.description;
+        return this.request("POST", `/apps/${encodeURIComponent(appId)}/setup-bundle`, "app", "getSetupBundle", body);
+    }
+    /** Read your app's acting policy (app key). */
+    async getActingPolicy(appId) {
+        return this.request("GET", `/apps/${encodeURIComponent(appId)}/acting-policy`, "app", "getActingPolicy");
+    }
+    /**
+     * Set what your agent may do for each kind of action: "act", "ask_first",
+     * "off", or null (unset — the agent does not act on that kind). Kinds you
+     * omit are unchanged. The kinds: `nobody_else` (only the customer's own
+     * account), `others_affected` (reaches other people),
+     * `money` (any charge, payment, refund, discount or credit) and
+     * `irreversible` (can't be undone once done). An action can be more than
+     * one kind; your agent follows the most careful of your settings for the
+     * kinds it is. Where that is act and your agent has read someone else's
+     * content, an invitation or message to an address the person never gave
+     * waits for their yes.
+     *
+     * Needs the APP OWNER's user key (`userApiKey: 'fsk_...'`), never the
+     * `fsa_` app key your agent runs with: Harny refuses that key here (403
+     * owner_credential_required) so an agent can never turn acting on for
+     * itself. Keep the owner key out of the agent's deployment, or set the
+     * policy in the console.
+     */
+    async setActingPolicy(appId, policy) {
+        const body = { set_via: policy.setVia ?? "api" };
+        for (const kind of exports.ACTION_KINDS) {
+            if (!(kind in policy))
+                continue;
+            const mode = policy[kind] ?? null;
+            if (mode !== null && mode !== "act" && mode !== "ask_first" && mode !== "off") {
+                throw new Error(`${kind} must be "act", "ask_first", "off" or null (unset)`);
+            }
+            body[kind] = mode;
+        }
+        if (Object.keys(body).length === 1) {
+            throw new Error("name at least one kind of action: nobody_else, others_affected, money or irreversible");
+        }
+        if (policy.confirm === true)
+            body.confirm = true;
+        if (!this.userKeyGiven) {
+            throw new HarnyStateError("setActingPolicy needs the app owner's user key: construct a separate client with " +
+                "userApiKey: 'fsk_...' (the owner's key, kept out of the agent's deployment), or set the " +
+                "policy in the console. The fsa_ app key your agent runs with is refused.");
+        }
+        return this.request("PUT", `/apps/${encodeURIComponent(appId)}/acting-policy`, "user", "setActingPolicy", body);
+    }
+    /** List the provisioned user's connected sources and their freshness. */
+    async listSources() {
+        return this.request("GET", "/context-sources", "user", "listSources");
+    }
+    /** Trigger a sync job for one connected source. */
+    async syncSource(provider, options) {
+        return this.request("POST", `/context-sources/${encodeURIComponent(provider)}/sync`, "user", "syncSource", { full_resync: options?.fullResync ?? false });
+    }
+    // ── Memory API v1: data points, status, delete, recall, usage ───────────
+    /**
+     * Send one data point: text plus the time it happened. Answers 202 with an `ingestionId` to poll with
+     * `getIngestion`. Send the same `id` again with changed content and the new text replaces the old; the same
+     * content again answers `unchanged: true` and costs nothing. `options.user` names the person (needs an app key).
+     */
+    async ingestDataPoint(point, options) {
+        const body = (0, memoryV1_js_1.ingestBody)(point, options?.idempotencyKey);
+        const [mode, headers] = this.actingAuth(options?.user, "ingestDataPoint");
+        const sent = withIdempotencyHeader(headers, options?.idempotencyKey);
+        const send = () => this.request("POST", "/memory/ingest", mode, "ingestDataPoint", body, sent);
+        // Retry a lost answer only when the caller gave a key: without one a repeat could be a second send.
+        return options?.idempotencyKey ? this.retryOnceWhenLost(send) : send();
+    }
+    /** Send 1 to 1,000 data points at once. Send the same `idempotencyKey` and body again after a failure to resume. */
+    async ingestBatch(items, options) {
+        const body = (0, memoryV1_js_1.batchBody)(items, options?.idempotencyKey);
+        const [mode, headers] = this.actingAuth(options?.user, "ingestBatch");
+        const sent = withIdempotencyHeader(headers, options?.idempotencyKey);
+        const send = () => this.request("POST", "/memory/ingest/batch", mode, "ingestBatch", body, sent);
+        return options?.idempotencyKey ? this.retryOnceWhenLost(send) : send();
+    }
+    /** Where one send is: `processing`, `completed` or `failed`. */
+    async getIngestion(ingestionId, options) {
+        const [mode, headers] = this.actingAuth(options?.user, "getIngestion");
+        return this.request("GET", `/memory/ingest/${(0, memoryV1_js_1.pathPart)("ingestionId", ingestionId)}`, mode, "getIngestion", undefined, headers);
+    }
+    /** Poll `getIngestion` until the send is `completed` or `failed`; throws after `timeoutMs` (default 300000). A timeout does not mean the save failed. */
+    async waitForIngestion(ingestionId, options) {
+        const deadline = Date.now() + (options?.timeoutMs ?? 300000);
+        for (;;) {
+            const status = await this.getIngestion(ingestionId, { user: options?.user });
+            if (status.status === "completed" || status.status === "failed")
+                return status;
+            if (Date.now() >= deadline) {
+                const waitedS = (options?.timeoutMs ?? 300000) / 1000;
+                throw new HarnyError(0, "TIMEOUT", `Ingestion ${ingestionId} is still ${status.status} on Harny's side after waiting ${waitedS}s. `
+                    + `This is not a failure: the save is still being processed and will usually complete. `
+                    + `Call getIngestion("${ingestionId}") again later to check it.`, `Call getIngestion("${ingestionId}") again later to check the save.`, "", null);
+            }
+            await new Promise((resolve) => setTimeout(resolve, options?.pollMs ?? 2000));
+        }
+    }
+    /** Forget one send: its data points and every memory that rests only on them. Free; a repeat succeeds. */
+    async deleteIngestion(ingestionId, options) {
+        const [mode, headers] = this.actingAuth(options?.user, "deleteIngestion");
+        await this.request("DELETE", `/memory/ingest/${(0, memoryV1_js_1.pathPart)("ingestionId", ingestionId)}`, mode, "deleteIngestion", undefined, headers);
+    }
+    /** Delete one data point by its `sourceId`, and the memory built on it. */
+    async deleteDataPoint(sourceId, options) {
+        const [mode, headers] = this.actingAuth(options?.user, "deleteDataPoint");
+        return this.request("DELETE", `/memory/data-points/${(0, memoryV1_js_1.pathPart)("sourceId", sourceId)}`, mode, "deleteDataPoint", undefined, headers);
+    }
+    /** Delete 1 to 1,000 data points by `sourceId`. If one id is unknown, none is deleted and the error names it. */
+    async deleteDataPoints(ids, options) {
+        const body = (0, memoryV1_js_1.deleteBody)(ids);
+        const [mode, headers] = this.actingAuth(options?.user, "deleteDataPoints");
+        return this.request("POST", "/memory/data-points/delete", mode, "deleteDataPoints", body, headers);
+    }
+    /** Ranked, dated evidence for a question, as the person asking (`options.identity`, default `options.user`). */
+    async recall(query, options = {}) {
+        const identity = options.identity ?? options.user ?? this.userApiKeyIdentity();
+        const body = (0, memoryV1_js_1.recallBody)(query, identity, options);
+        const [mode, headers] = this.actingAuth(options.user, "recall");
+        return this.request("POST", "/memory/recall", mode, "recall", body, headers);
+    }
+    /** This month's usage for the app. Needs the app key. */
+    async getUsage() {
+        return this.request("GET", "/memory/usage", "app", "getUsage");
+    }
+    /** The recall identity when none is named: only a client that provisioned a user knows it. */
+    userApiKeyIdentity() {
+        return this.provisionedUserId ?? "";
+    }
+}
+exports.HarnyClient = HarnyClient;
+// `console.log(client)` shows the key-free view, never a key.
+Object.defineProperty(HarnyClient.prototype, Symbol.for("nodejs.util.inspect.custom"), {
+    value() {
+        return `HarnyClient ${JSON.stringify(this.toJSON())}`;
+    },
+    enumerable: false,
+});
+// ── Webhook deliveries ──────────────────────────────────────────────────
+function toHex(bytes) {
+    return Array.from(new Uint8Array(bytes), (b) => b.toString(16).padStart(2, "0")).join("");
+}
+function asBytes(body) {
+    return typeof body === "string" ? new TextEncoder().encode(body) : body;
+}
+/** The `X-Harny-Signature` value Harny sends for `body` under `secret`. */
+async function computeWebhookSignature(secret, body) {
+    const key = await globalThis.crypto.subtle.importKey("raw", new TextEncoder().encode(secret), { name: "HMAC", hash: "SHA-256" }, false, ["sign"]);
+    const digest = await globalThis.crypto.subtle.sign("HMAC", key, asBytes(body));
+    return `sha256=${toHex(digest)}`;
+}
+/**
+ * Constant-time check of `X-Harny-Signature` against one or more secrets
+ * (pass the current and the previous one during a rotation). Verify the RAW
+ * body bytes before parsing. Accepts the header with or without `sha256=`.
+ */
+async function verifyWebhookSignature(body, signature, secrets) {
+    if (!signature)
+        return false;
+    let provided = signature.trim().toLowerCase();
+    if (provided.startsWith("sha256="))
+        provided = provided.slice("sha256=".length);
+    if (!provided)
+        return false;
+    for (const secret of Array.isArray(secrets) ? secrets : [secrets]) {
+        if (!secret)
+            continue;
+        const expected = (await computeWebhookSignature(secret, body)).slice("sha256=".length);
+        if (expected.length !== provided.length)
+            continue;
+        let diff = 0;
+        for (let i = 0; i < expected.length; i += 1) {
+            diff |= expected.charCodeAt(i) ^ provided.charCodeAt(i);
+        }
+        if (diff === 0)
+            return true;
+    }
+    return false;
+}
+/**
+ * Verify, then parse a `source.sync_complete` delivery. Throws when the
+ * signature does not verify (answer 401 and do nothing) or the body is not a
+ * `source.sync_complete` event.
+ */
+async function parseSourceArrivalEvent(body, signature, secrets) {
+    if (!(await verifyWebhookSignature(body, signature, secrets))) {
+        throw new Error("X-Harny-Signature does not match");
+    }
+    const text = typeof body === "string" ? body : new TextDecoder().decode(body);
+    const payload = JSON.parse(text);
+    if (payload?.event_type !== "source.sync_complete") {
+        throw new Error("not a source.sync_complete event");
+    }
+    return payload;
+}
+// ── Agent loop: your model, your key, Harny for context and actions ──
+var index_js_1 = require("./agent/index.js");
+Object.defineProperty(exports, "ActDecision", { enumerable: true, get: function () { return index_js_1.ActDecision; } });
+Object.defineProperty(exports, "ActionNote", { enumerable: true, get: function () { return index_js_1.ActionNote; } });
+Object.defineProperty(exports, "ActionTrace", { enumerable: true, get: function () { return index_js_1.ActionTrace; } });
+Object.defineProperty(exports, "Agent", { enumerable: true, get: function () { return index_js_1.Agent; } });
+Object.defineProperty(exports, "AgentConfig", { enumerable: true, get: function () { return index_js_1.AgentConfig; } });
+Object.defineProperty(exports, "AgentPendingConfirmation", { enumerable: true, get: function () { return index_js_1.AgentPendingConfirmation; } });
+Object.defineProperty(exports, "ChatCompletionsAdapter", { enumerable: true, get: function () { return index_js_1.ChatCompletionsAdapter; } });
+Object.defineProperty(exports, "FileSessionStore", { enumerable: true, get: function () { return index_js_1.FileSessionStore; } });
+Object.defineProperty(exports, "GenerateContentAdapter", { enumerable: true, get: function () { return index_js_1.GenerateContentAdapter; } });
+Object.defineProperty(exports, "HARNY_CALLS", { enumerable: true, get: function () { return index_js_1.HARNY_CALLS; } });
+Object.defineProperty(exports, "HarnyTools", { enumerable: true, get: function () { return index_js_1.HarnyTools; } });
+Object.defineProperty(exports, "HookBlocked", { enumerable: true, get: function () { return index_js_1.HookBlocked; } });
+Object.defineProperty(exports, "MODEL_REACHABLE_CALLS", { enumerable: true, get: function () { return index_js_1.MODEL_REACHABLE_CALLS; } });
+Object.defineProperty(exports, "MemorySessionStore", { enumerable: true, get: function () { return index_js_1.MemorySessionStore; } });
+Object.defineProperty(exports, "Message", { enumerable: true, get: function () { return index_js_1.Message; } });
+Object.defineProperty(exports, "MessagesAdapter", { enumerable: true, get: function () { return index_js_1.MessagesAdapter; } });
+Object.defineProperty(exports, "ModelProviderError", { enumerable: true, get: function () { return index_js_1.ModelProviderError; } });
+Object.defineProperty(exports, "ModelTurn", { enumerable: true, get: function () { return index_js_1.ModelTurn; } });
+Object.defineProperty(exports, "PRESET_NAMES", { enumerable: true, get: function () { return index_js_1.PRESET_NAMES; } });
+Object.defineProperty(exports, "PresetResolutionError", { enumerable: true, get: function () { return index_js_1.PresetResolutionError; } });
+Object.defineProperty(exports, "ResolvedModel", { enumerable: true, get: function () { return index_js_1.ResolvedModel; } });
+Object.defineProperty(exports, "RunResult", { enumerable: true, get: function () { return index_js_1.RunResult; } });
+Object.defineProperty(exports, "SpendCap", { enumerable: true, get: function () { return index_js_1.SpendCap; } });
+Object.defineProperty(exports, "SpendMeter", { enumerable: true, get: function () { return index_js_1.SpendMeter; } });
+Object.defineProperty(exports, "Tracer", { enumerable: true, get: function () { return index_js_1.Tracer; } });
+Object.defineProperty(exports, "Turn", { enumerable: true, get: function () { return index_js_1.Turn; } });
+Object.defineProperty(exports, "Usage", { enumerable: true, get: function () { return index_js_1.Usage; } });
+Object.defineProperty(exports, "buildAdapter", { enumerable: true, get: function () { return index_js_1.buildAdapter; } });
+Object.defineProperty(exports, "parseTraceparent", { enumerable: true, get: function () { return index_js_1.parseTraceparent; } });
+Object.defineProperty(exports, "resolvePreset", { enumerable: true, get: function () { return index_js_1.resolvePreset; } });
+var conflictQuestion_js_1 = require("./conflictQuestion.js");
+Object.defineProperty(exports, "ASKING_KINDS", { enumerable: true, get: function () { return conflictQuestion_js_1.ASKING_KINDS; } });
+Object.defineProperty(exports, "CONFLICT_QUESTION_MODES", { enumerable: true, get: function () { return conflictQuestion_js_1.CONFLICT_QUESTION_MODES; } });
+Object.defineProperty(exports, "DEFAULT_CONFLICT_QUESTION_MODE", { enumerable: true, get: function () { return conflictQuestion_js_1.DEFAULT_CONFLICT_QUESTION_MODE; } });
+Object.defineProperty(exports, "InMemoryConflictAskLedger", { enumerable: true, get: function () { return conflictQuestion_js_1.InMemoryConflictAskLedger; } });
+Object.defineProperty(exports, "QuestionPhrases", { enumerable: true, get: function () { return conflictQuestion_js_1.QuestionPhrases; } });
+Object.defineProperty(exports, "conflictKey", { enumerable: true, get: function () { return conflictQuestion_js_1.conflictKey; } });
+Object.defineProperty(exports, "decideConflictQuestion", { enumerable: true, get: function () { return conflictQuestion_js_1.decideConflictQuestion; } });
+Object.defineProperty(exports, "formatDay", { enumerable: true, get: function () { return conflictQuestion_js_1.formatDay; } });
+Object.defineProperty(exports, "normaliseMode", { enumerable: true, get: function () { return conflictQuestion_js_1.normaliseMode; } });
+Object.defineProperty(exports, "questionText", { enumerable: true, get: function () { return conflictQuestion_js_1.questionText; } });
+var memoryV1_js_2 = require("./memoryV1.js");
+Object.defineProperty(exports, "RECALL_LEVELS", { enumerable: true, get: function () { return memoryV1_js_2.RECALL_LEVELS; } });
+//# sourceMappingURL=index.js.map