@harny/sdk 0.0.1-alpha.1 → 0.1.1

package/dist/cjs/index.d.ts

@@ -0,0 +1,950 @@
+import type { ConflictLike, ConflictQuestion } from "./conflictQuestion.js";
+import type { DataPoint, IngestDataPointOptions, MemoryDeletion, MemoryIngestionStatus, MemoryIngestReceipt, MemoryRecall, MemoryUsage, RecallOptions, WaitOptions } from "./memoryV1.js";
+export declare class HarnyError extends Error {
+    readonly statusCode: number;
+    readonly errorCode: string;
+    readonly recoveryHint: string;
+    readonly docsUrl: string;
+    readonly retryAfterS: number | null;
+    /** Field-level reasons when the API rejected the request's fields: where, why, and the kind. */
+    readonly detail?: ReadonlyArray<{
+        loc: string[];
+        msg: string;
+        type?: string;
+    }> | undefined;
+    constructor(statusCode: number, errorCode: string, message: string, recoveryHint: string, docsUrl: string, retryAfterS: number | null, 
+    /** Field-level reasons when the API rejected the request's fields: where, why, and the kind. */
+    detail?: ReadonlyArray<{
+        loc: string[];
+        msg: string;
+        type?: string;
+    }> | undefined);
+}
+/**
+ * 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`.
+ */
+export declare class HarnyStateError extends Error {
+    constructor(message: string);
+}
+/** A key was given that is not text (a number, an object, ...). */
+export declare class HarnyInvalidKeyError extends HarnyStateError {
+    constructor(message: string);
+}
+/** No API key was given and none was found in `HARNY_API_KEY` (or its alias `HARNY_APP_KEY`). */
+export declare class HarnyMissingKeyError extends HarnyStateError {
+    constructor(message: string);
+}
+/** Providers the platform can connect. Mirrors the API's ContextSourceProvider. */
+export type ContextSourceProvider = "gmail" | "calendar" | "drive" | "notion" | "slack" | "email_bridge";
+export type SubsystemStatus = "ready" | "degraded" | "failing";
+export interface ContextSourceFreshness {
+    provider: string;
+    last_refreshed_at?: string | null;
+    auth_state: "ok" | "expired" | "error" | "disconnected";
+    last_sync_status?: string | null;
+    last_error?: string | null;
+}
+export interface DiagnoseResponse {
+    oauth_status: SubsystemStatus;
+    vault_status: SubsystemStatus;
+    assembly_status: SubsystemStatus;
+    overall: SubsystemStatus;
+    /** Empty when the request carried no user context. */
+    context_sources: ContextSourceFreshness[];
+}
+export type IdentifierType = "email" | "app_id" | "device_id";
+/**
+ * Trust levels the API accepts when CREATING a user. Narrower than the trust
+ * levels it returns: `platform_verified` is server-assigned only and is
+ * rejected on the request.
+ */
+export type IngressEmailTrustLevel = "unverified" | "app_asserted";
+/** Trust levels the API may report back on a user record. */
+export type EmailTrustLevel = IngressEmailTrustLevel | "platform_verified";
+export interface User {
+    id: string;
+    app_id: string;
+    identifier: string;
+    identifier_type: IdentifierType;
+    email: string | null;
+    email_trust_level: EmailTrustLevel;
+    identity_provider: string | null;
+    created_at: string;
+    vault_initialized: boolean;
+}
+/** The mark a host may put on a person at registration. */
+export type UserRole = "staff" | "test";
+/** How a host says a card was answered when it confirms. */
+export type ConfirmAnsweredBy = "tap" | "timeout" | "dismissed" | "server";
+/**
+ * What a person may correct on the card before approving: the content of the action. `attendees` is the guest list of the same guests or fewer; the API refuses a guest who
+ * was not on the card.
+ */
+export interface ConfirmEdit {
+    title?: string;
+    start?: string;
+    end?: string;
+    duration_minutes?: number;
+    time_zone?: string;
+    description?: string;
+    location?: string;
+    attendees?: string[];
+}
+export interface ProvisionUserOptions {
+    identifier_type?: IdentifierType;
+    email_trust_level?: IngressEmailTrustLevel;
+    /**
+     * Mark the person: `staff` (works for the business) or `test` (an account made to try the app). Leave it out for an
+     * ordinary customer. A `test` account is not counted as a customer when Harny reads how your users answer. Sent again
+     * for a person who already exists it updates the mark; leaving it out never removes one; `null` removes it.
+     */
+    role?: UserRole | null;
+}
+export interface ProvisionUserResponse {
+    user: User;
+    /**
+     * Always present on the wire, but `null` for a returning user the API
+     * did not mint a fresh key for. Reuse the key you stored the first time.
+     */
+    api_key_id: string | null;
+    api_key: string | null;
+    api_key_display: string | null;
+    trust_upgraded: boolean;
+    message: string;
+    delivery_ack_token?: string | null;
+    delivery_reread_expires_at?: string | null;
+}
+export type IngestStatus = "ingested" | "deduped" | "queued";
+export type IngestQueuedReason = "extraction_unavailable" | "memory_service_degraded" | "circuit_open" | "empty_extraction_suspected";
+export interface IngestResponse {
+    status: IngestStatus;
+    message: string;
+    resource_uri: string;
+    /** Present only when `status` is `queued`: why the content was accepted for retry. */
+    queued_reason?: IngestQueuedReason | null;
+    /** Present only when `status` is `deduped`. */
+    existing_memory_ids?: string[] | null;
+}
+export interface ContextBlockPolicy {
+    cross_app: boolean;
+    sharing_tier: "open" | "sensitive" | "restricted";
+    consent_basis: "self_app_scope" | "vault_link_category_policy";
+    origin_app_id?: string | null;
+}
+export interface TemporalAnchor {
+    event_time?: string | null;
+    /** Tolerant string: the server may add categories without an SDK bump. */
+    recency?: string | null;
+    temporal_relevance?: string | null;
+}
+export type ContextBlockSourceType = "vault" | "context_source" | "linked" | "tool" | "memory";
+export interface ContextBlock {
+    source_type: ContextBlockSourceType;
+    score: number;
+    content: string;
+    token_count: number;
+    policy: ContextBlockPolicy;
+    metadata: Record<string, unknown>;
+    last_refreshed_at?: string | null;
+    temporal?: TemporalAnchor | null;
+    /** Tolerant strings — the API's registries may gain values mid-deploy. */
+    basis?: string | null;
+    freshness?: string | null;
+    provenance_type?: string | null;
+    occurred_at?: string | null;
+    last_retrieved_at?: string | null;
+    /** Present only on deployments with graduated confidence enabled. */
+    confidence_tier?: string | null;
+    uncertainty_note?: string | null;
+}
+export interface TemporalScope {
+    start?: string | null;
+    end?: string | null;
+    label: string;
+}
+export interface QueryInterpretation {
+    intent: string;
+    temporal_scope?: TemporalScope | null;
+    entities: Array<Record<string, string>>;
+    source_hints: string[];
+    reformulated_query?: string | null;
+}
+/**
+ * The one mechanically-earned issue attached to a thin or empty result.
+ * `null` on a healthy response.
+ */
+export interface Issue {
+    reason: string;
+    scope?: string | null;
+    plain: string;
+    next: string;
+    fix_url: string;
+}
+export interface EmailCaptureHealth {
+    state: string;
+    status_message: string;
+    last_updated_at?: string | null;
+    action?: string | null;
+}
+export type ContextAssemblySource = "vault" | "context_source" | "memory" | "linked" | "tool";
+/**
+ * Two things one user said that cannot both be true. Neither statement replaces
+ * the other: nothing here says which one is right.
+ */
+export interface ContextConflict {
+    statement_1: string;
+    said_1: string;
+    event_date_1?: string | null;
+    statement_2: string;
+    said_2: string;
+    record_id_1: string;
+    record_id_2: string;
+    /** True when the user said both in one conversation: do not ask about it there. */
+    same_conversation: boolean;
+    speaker: string;
+    /** Names this conflict: the same in every response, whichever statement is listed first. Absent from older servers. */
+    conflict_key?: string | null;
+    /** True when your app has already reported asking the user about this conflict (`markConflictAsked`). */
+    asked?: boolean;
+}
+/** Harny's answer to `markConflictAsked`. */
+export interface ConflictAsked {
+    conflict_key: string;
+    /** True the first time you report this conflict as asked, false on every repeat. */
+    first_time: boolean;
+}
+/** Harny's answer to `answerConflict`. */
+export interface ConflictAnswered {
+    conflict_key: string;
+    /** True once the answer is saved; the conflict is no longer returned. */
+    answered: boolean;
+    /** How the saving went: `ingested`, `deduped` or `queued`. */
+    status: string;
+    message: string;
+    /** Identifies the saved answer. */
+    resource_uri: string;
+}
+export interface ContextResult {
+    blocks: ContextBlock[];
+    total_tokens: number;
+    budget_used: number;
+    budget_remaining: number;
+    query: string;
+    assembly_profile: string;
+    sources_queried: ContextAssemblySource[];
+    /** A source here FAILED. Never read an empty result as "the user has no data". */
+    degraded_sources: ContextAssemblySource[];
+    source_failures?: Record<string, string> | null;
+    thread_id?: string | null;
+    query_interpretation?: QueryInterpretation | null;
+    /** Matches the `X-Request-Id` response header. Quote it in support requests. */
+    request_id: string;
+    issue?: Issue | null;
+    capture_health?: EmailCaptureHealth | null;
+    /**
+     * Two things the user said that cannot both be true, for your own interface
+     * to show. Absent unless there is at least one.
+     */
+    conflicts?: ContextConflict[] | null;
+    /**
+     * How to word the question when you ask about a conflict: your app's "When notes conflict" setting (simple,
+     * precise or handoff). Absent with no conflict, and absent while Harny has the question switched off, so no
+     * mode with a conflict in hand means do not ask. Pass it to `decideConflictQuestion({ mode })`.
+     */
+    conflict_question_mode?: string | null;
+}
+export type AssemblySourceFilter = "vault" | "context_source" | "memory" | "linked" | "tool" | "permission";
+export interface AssembleOptions {
+    token_budget?: number;
+    assembly_profile?: string;
+    thread_id?: string | null;
+    include_tools?: boolean;
+    source_filter?: AssemblySourceFilter[] | null;
+    min_relevance_score?: number | null;
+    /** Last N conversation turns (max 5) for context-adaptive retrieval. */
+    conversation_context?: string[] | null;
+}
+/**
+ * Who the assembly is for, sent as a header (never in the request body):
+ * `user` assembles for that end user with the app key (Harny id or your
+ * identifier) — for a backend agent woken by a webhook. Omit it on a client
+ * that provisioned a user.
+ */
+export interface AssembleTarget {
+    user?: string;
+    /** W3C trace context header, so Harny's work joins your trace. */
+    traceparent?: string;
+}
+/** List price per million tokens, from a versioned rate table. */
+export interface RosterPrice {
+    priced: boolean;
+    input_per_mtok?: number | null;
+    output_per_mtok?: number | null;
+    cached_input_per_mtok?: number | null;
+    has_peak_window?: boolean;
+    rate_version: string;
+}
+export interface RosterApi {
+    style: "chat_completions" | "messages" | "generate_content";
+    base_url: string;
+    auth: "bearer" | "x-api-key" | "x-goog-api-key";
+    headers?: Record<string, string>;
+    max_tokens_param: string;
+    /** Added to every request body (for example a pin to one host); never replaces a field the agent sets. */
+    extra_body?: Record<string, unknown>;
+}
+/** The one host that serves an entry on a provider that routes to many hosts. */
+export interface RosterHost {
+    id: string;
+    label: string;
+    headquarters?: string | null;
+}
+export interface RosterCapabilities {
+    tool_calls?: boolean;
+    mcp_supported?: boolean;
+    /** The model thinks before it answers (never switched off); the thinking counts against the answer limit. */
+    thinking_always_on?: boolean;
+    /** Set with `thinking_always_on`: the answer limit (max output tokens) to give the model at least. */
+    answer_room_tokens?: number | null;
+}
+export interface RosterEntry {
+    id: string;
+    provider: string;
+    provider_label: string;
+    model: string;
+    api: RosterApi;
+    capabilities: RosterCapabilities;
+    key_env: string[];
+    region: string;
+    price: RosterPrice;
+    notes?: string | null;
+    host?: RosterHost | null;
+    /** Informational only: never used to pick or refuse an entry. */
+    data_terms?: string | null;
+}
+export interface RosterPreset {
+    name: "cost_first" | "quality_first" | "regulated";
+    description: string;
+    entries: RosterEntry[];
+}
+/**
+ * The platform model roster: for each preset, provider/model entries an agent
+ * resolves with the business's own key (first entry whose provider it holds a
+ * key for). Reading it runs no model.
+ */
+export interface ModelRoster {
+    roster_version: string;
+    updated_at: string;
+    rate_version: string;
+    presets: Record<string, RosterPreset>;
+}
+export interface SetupBundleOptions {
+    /** `common:<path id>` or `developer`. */
+    shape: string;
+    preset?: "cost_first" | "quality_first" | "regulated";
+    deployTarget?: "cloud_run" | "render" | "docker" | "unspecified";
+    surface?: "chat_page" | "email" | "webhook_only";
+    sources?: string[];
+    actions?: string[];
+    emailArrivalTrigger?: boolean;
+    description?: string;
+}
+/** What names a conflict: a `ContextConflict`, an object with both note ids, or the decision `decideConflictQuestion` returned. */
+export type ConflictRefInput = ConflictLike | ConflictQuestion;
+export interface ConnectResponse {
+    provider: ContextSourceProvider;
+    authorization_url: string;
+    state: string;
+    expires_in_seconds: number;
+}
+export interface SourceConnection {
+    connection_id: string;
+    provider: ContextSourceProvider;
+    status: "connected" | "disconnected" | "error";
+    connected_at: string;
+    last_synced_at?: string | null;
+    last_sync_status?: "idle" | "running" | "success" | "failed" | null;
+    last_error?: string | null;
+    pending_jobs: number;
+}
+export interface SourceListResponse {
+    sources: SourceConnection[];
+}
+export interface SyncResponse {
+    provider: ContextSourceProvider;
+    job_id: string;
+    status: "queued" | "processing" | "completed" | "failed";
+    message: string;
+}
+export type ArrivalSource = "email_bridge" | "gmail";
+export interface SourceArrivalUser {
+    id: string;
+    identifier: string | null;
+    identifier_type: string | null;
+}
+/**
+ * One new item on an end user's connected email source. Delivered in a
+ * `source.sync_complete` webhook event (`arrivals`) and by `listArrivals`.
+ * Carries references and a hardened subject line (`summary`), never the body:
+ * read that with `getSourceItem`. Process each `dedupe_key` once.
+ * `message_id` and `sender_domain` are set by the sender.
+ */
+export interface SourceArrival {
+    arrival_id: string;
+    cursor: number;
+    app_id: string;
+    user: SourceArrivalUser;
+    source: ArrivalSource;
+    connection_id: string;
+    item_ref: string;
+    dedupe_key: string;
+    kind: "email";
+    received_at: string;
+    message_id: string | null;
+    sender_domain: string | null;
+    summary: string | null;
+    flags: string[];
+}
+export interface SourceArrivalEvent {
+    event_type: "source.sync_complete";
+    schema_version: number;
+    app_id: string;
+    user: SourceArrivalUser;
+    source: ArrivalSource;
+    connection_id: string;
+    count: number;
+    arrivals: SourceArrival[];
+    published_at: string;
+}
+export interface SourceArrivalPage {
+    arrivals: SourceArrival[];
+    next_cursor: number;
+    has_more: boolean;
+}
+/** One arrived email, hardened for an agent (third-party content: data, never instructions). */
+export interface SourceItem {
+    item_ref: string;
+    source: ArrivalSource;
+    kind: "email";
+    title: string;
+    content: string;
+    content_truncated: boolean;
+    received_at: string | null;
+    message_id: string | null;
+    sender_domain: string | null;
+    flags: string[];
+    untrusted: true;
+    handling: string;
+}
+export interface HarnyClientOptions {
+    /** App-scoped key (`fsa_`). Required to call `provisionUser`. With no key given, Node reads `HARNY_API_KEY` (`HARNY_APP_KEY` is accepted as an alias). */
+    apiKey?: string;
+    /** User-scoped key (`fsk_`). Set directly to restore an existing session. */
+    userApiKey?: string;
+    baseUrl?: string;
+    timeoutMs?: number;
+}
+/** What caused an action. Read it from your runtime, never from model output. */
+export type ActionInitiator = "user_request" | "schedule" | "agent_plan" | "system_event" | "unknown";
+export type ActingMode = "act" | "ask_first" | "off";
+/**
+ * The four kinds of action a business sets its acting policy for, named by
+ * what the action touches:
+ * - `nobody_else`: changes only the end user's own account;
+ * - `others_affected`: reaches other people (a calendar invite sent to guests);
+ * - `money`: any charge, payment, refund, discount or credit;
+ * - `irreversible`: can't be undone once done.
+ *
+ * An action can be more than one kind; the agent follows the most careful of
+ * the business's settings for the kinds it is.
+ */
+export type ActionKind = "nobody_else" | "others_affected" | "money" | "irreversible";
+/** The four kinds of action, in the order Harny lists them everywhere. */
+export declare const ACTION_KINDS: readonly ActionKind[];
+export interface ActionRefusal {
+    code: string;
+    message: string;
+    retry_after_seconds?: number | null;
+    expansion_hint?: Record<string, unknown> | null;
+}
+/**
+ * What happened to one catalog action. Give a model `forModel()` only.
+ * `confirmRef` (ask-first) is non-enumerable: `JSON.stringify(outcome)` never
+ * includes it, because nothing a model reads may approve an action on the
+ * person's behalf. Read it explicitly in your confirm UI handler.
+ */
+export interface ActionOutcome {
+    executionId: string;
+    action: string;
+    outcome: "completed" | "awaiting_end_user" | "refused" | "declined" | "expired" | "failed" | "processing";
+    /** The kinds of action this is, in Harny's order (e.g. `["others_affected"]`). */
+    kinds: ActionKind[];
+    /** Why the action is those kinds (e.g. `guests_receive_invitations`). */
+    kindReasons: string[];
+    /** The kind whose setting decided the outcome: the most careful of the business's settings for the kinds read. */
+    decidedBy: ActionKind | null;
+    recordId: string | null;
+    refusal: ActionRefusal | null;
+    result: Record<string, unknown> | null;
+    alreadyDecided: boolean;
+    replayed: boolean;
+    confirmExpiresAt: string | null;
+    readonly confirmRef?: string;
+    forModel(): {
+        status: string;
+        message: string;
+    };
+}
+/** The business's setting for one kind of action, and who set it when. */
+export interface ActingKindSetting {
+    mode: ActingMode | null;
+    version: number | null;
+    set_by: string | null;
+    set_via: string | null;
+    set_at: string | null;
+}
+export interface ActingPolicyResponse {
+    app_id: string;
+    version: number;
+    nobody_else: ActingKindSetting;
+    others_affected: ActingKindSetting;
+    money: ActingKindSetting;
+    irreversible: ActingKindSetting;
+    unset_means: string;
+    /**
+     * True while a proposal stored before the owner decided is in force: while
+     * the app is in test, Harny applies every proposed kind as proposed. Absent
+     * from older servers.
+     */
+    proposal_in_effect?: boolean;
+    /**
+     * The app's stage: "test" (the default) or "production". The owner moves the
+     * app to production by confirming the four settings. Absent from older servers.
+     */
+    stage?: "test" | "production";
+}
+/**
+ * A short-lived token for ONE end user, for a hosted agent runtime's MCP
+ * connection. Give `access_token` only to that connection
+ * (`Authorization: Bearer`) at `mcp_url`; never the app key. Rotating the
+ * app key ends every token it minted.
+ */
+export interface RuntimeToken {
+    access_token: string;
+    token_type?: "Bearer";
+    expires_in: number;
+    expires_at: string;
+    scope: string;
+    token_id: string;
+    user_id: string;
+    mcp_url: string;
+    message: string;
+    user_driven_only?: boolean;
+}
+export interface RuntimeTokenRevoked {
+    token_id: string;
+    revoked_at: string;
+    already_revoked?: boolean;
+}
+export interface MintRuntimeTokenOptions {
+    /** Seconds the token works; the deployment's default (15 minutes) when omitted. */
+    ttlSeconds?: number;
+    /** Read the end user's context only; perform no action. */
+    readOnly?: boolean;
+    /** Catalog actions it may perform, e.g. ["calendar.create_event"]; all when omitted. Undo needs "calendar.delete_event". */
+    actions?: string[];
+    /** What started the runtime session, from your backend (never a model). */
+    initiatedBy?: ActionInitiator;
+    /** Your note for the audit trail, e.g. the runtime session id. */
+    label?: string;
+    /** Your own https page where the end user grants write access. Required unless readOnly. */
+    connectUrl?: string;
+    /**
+     * A hosted runtime can read content Harny never sees, so by default, where
+     * a setting is act, an invitation or message from the session to an
+     * address the person never gave waits for their yes. True (only when every
+     * action in the session is the end user's own request) removes that
+     * assumption and nothing else: the same wait still applies when
+     * initiatedBy is "system_event" or when something read for this person
+     * through Harny recently (15 minutes by default) included someone else's
+     * content, such as an email. Actions on the person's own account never
+     * wait for this.
+     */
+    userDrivenOnly?: boolean;
+    /**
+     * The end user's own words that start this session (their chat message),
+     * from your backend, never a model. An email address in them counts as one
+     * the person gave for the session's actions, so an invitation or message
+     * to it follows your settings instead of waiting for their yes. Only the
+     * addresses are kept, never the words.
+     */
+    endUserMessage?: string;
+    /**
+     * The token reads this person's action history (read-only) by default;
+     * false leaves it out.
+     */
+    actionHistory?: boolean;
+}
+/**
+ * An ask-first action a hosted runtime asked for over MCP. The runtime never
+ * receives `confirm_ref`; your backend reads it here and shows your confirm
+ * card. Never pass `confirm_ref` to a model.
+ */
+export interface PendingConfirmation {
+    execution_id: string;
+    confirm_ref: string;
+    expires_at: string;
+    action: string;
+    arguments: Record<string, unknown>;
+    summary?: Record<string, unknown>;
+    kinds?: ActionKind[];
+    kind_reasons?: string[];
+    decided_by?: ActionKind | null;
+    /**
+     * The addresses the person never gave, when that is why it waits although
+     * your setting said act: show them on your confirm card.
+     */
+    held_for_recipients?: string[];
+    /**
+     * True when Harny could not finish checking those addresses (a look-up
+     * failed), so it asked instead; they may well be ones the person gave.
+     */
+    recipient_lookup_failed?: boolean;
+}
+/**
+ * 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).
+ */
+export declare const END_USER_MESSAGE_MAX_CHARS = 100000;
+export declare class HarnyClient {
+    private readonly apiKey;
+    private userApiKeyValue;
+    /** A user key given to the constructor (possibly the app owner's), not one cached by provisionUser. */
+    private readonly userKeyGiven;
+    private readonly baseUrl;
+    private readonly timeoutMs;
+    /** The id of the user provisionUser made: the recall identity of a client that acts as that user. */
+    private provisionedUserId;
+    constructor({ apiKey, userApiKey, baseUrl, timeoutMs }?: HarnyClientOptions);
+    /** A key-free view: `JSON.stringify(client)` never carries a key. */
+    toJSON(): Record<string, unknown>;
+    /**
+     * 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(): string | undefined;
+    private resolveBaseUrl;
+    private bearer;
+    private request;
+    /**
+     * Per-subsystem health snapshot. Needs no user session; with one, the
+     * response also carries per-source freshness.
+     */
+    diagnose(): Promise<DiagnoseResponse>;
+    /**
+     * 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`).
+     */
+    provisionUser(identifier: string, email: string, options?: ProvisionUserOptions): Promise<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.
+     */
+    ingestText(content: string, title?: string, options?: {
+        user?: string;
+        writtenByPerson?: boolean;
+        idempotencyKey?: string;
+    }): Promise<IngestResponse>;
+    /** Run an idempotent request; if the answer never arrived (timeout or dropped connection), send it once more with the same key. */
+    private retryOnceWhenLost;
+    /** Upload a binary file to the provisioned user's vault. */
+    ingestFile(file: File | Blob | Uint8Array, filename?: string): Promise<IngestResponse>;
+    /**
+     * 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.
+     */
+    assembleContext(query: string, options?: AssembleOptions, target?: AssembleTarget): Promise<ContextResult>;
+    /**
+     * 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.
+     */
+    markConflictAsked(conflict: ConflictRefInput, options?: {
+        user?: string;
+        traceparent?: string;
+    }): Promise<ConflictAsked>;
+    /**
+     * 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`.
+     */
+    answerConflict(conflict: ConflictRefInput, answer: string, options?: {
+        user?: string;
+        traceparent?: string;
+    }): Promise<ConflictAnswered>;
+    /**
+     * 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.
+     */
+    getSourceItem(itemRef: string, options?: {
+        user?: string;
+        traceparent?: string;
+    }): Promise<SourceItem>;
+    /**
+     * 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.
+     */
+    listArrivals(options?: {
+        after?: number;
+        limit?: number;
+        user?: string;
+        traceparent?: string;
+    }): Promise<SourceArrivalPage>;
+    /**
+     * 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.
+     */
+    connectSource(provider: ContextSourceProvider | string, returnUrl?: string, options?: {
+        capabilities?: string[];
+        user?: string;
+        sharedFactsOptIn?: boolean;
+    }): Promise<ConnectResponse>;
+    /** The end user an action is for: app key + named user, or the user's own key. */
+    private actingAuth;
+    /**
+     * 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.
+     */
+    act(action: string, args: Record<string, unknown>, options?: {
+        user?: string;
+        initiatedBy?: ActionInitiator;
+        idempotencyKey?: string;
+        correlationId?: string;
+        traceparent?: string;
+        endUserMessage?: string;
+    }): Promise<ActionOutcome>;
+    /**
+     * 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.
+     */
+    confirm(executionId: string, confirmRef: string, approve: boolean, options?: {
+        user?: string;
+        traceparent?: string;
+        answeredBy?: ConfirmAnsweredBy;
+        edit?: ConfirmEdit;
+    }): Promise<ActionOutcome>;
+    /**
+     * 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).
+     */
+    mintRuntimeToken(user: string, options?: MintRuntimeTokenOptions): Promise<RuntimeToken>;
+    /** Revoke one runtime token now (app key). Rotating the app key revokes them all. */
+    revokeRuntimeToken(tokenId: string): Promise<RuntimeTokenRevoked>;
+    /**
+     * 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(...)`.
+     */
+    getPendingConfirmation(executionId: string, options: {
+        user: string;
+    }): Promise<PendingConfirmation>;
+    /**
+     * 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`.
+     */
+    googleBridgeSetup(sources?: string[], options?: {
+        acceptedTextSha256?: string;
+        label?: string;
+        user?: string;
+    }): Promise<Record<string, any>>;
+    /**
+     * 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`.
+     */
+    googleBridgeAct(kind: string, params?: Record<string, unknown>, options?: {
+        wait?: boolean;
+        timeoutMs?: number;
+        pollIntervalMs?: number;
+        user?: string;
+    }): Promise<Record<string, any>>;
+    /** Undo an action your agent performed, by its action-record id. */
+    undo(recordId: string, options?: {
+        user?: string;
+        initiatedBy?: ActionInitiator;
+        idempotencyKey?: string;
+        traceparent?: string;
+    }): Promise<ActionOutcome>;
+    /**
+     * 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.
+     */
+    getModelRoster(): Promise<ModelRoster>;
+    /**
+     * The setup bundle a coding assistant stands your agent up from (app key).
+     * It names key variables and never carries a key.
+     */
+    getSetupBundle(appId: string, options: SetupBundleOptions): Promise<Record<string, unknown>>;
+    /** Read your app's acting policy (app key). */
+    getActingPolicy(appId: string): Promise<ActingPolicyResponse>;
+    /**
+     * 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.
+     */
+    setActingPolicy(appId: string, policy: {
+        nobody_else?: ActingMode | null;
+        others_affected?: ActingMode | null;
+        money?: ActingMode | null;
+        irreversible?: ActingMode | null;
+        setVia?: "console" | "api" | "bundle" | "assistant";
+        /** Needed only while the app is live (in production): `true` confirms the change and it applies at once. */
+        confirm?: boolean;
+    }): Promise<ActingPolicyResponse>;
+    /** List the provisioned user's connected sources and their freshness. */
+    listSources(): Promise<SourceListResponse>;
+    /** Trigger a sync job for one connected source. */
+    syncSource(provider: ContextSourceProvider | string, options?: {
+        fullResync?: boolean;
+    }): Promise<SyncResponse>;
+    /**
+     * 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).
+     */
+    ingestDataPoint(point: DataPoint, options?: IngestDataPointOptions): Promise<MemoryIngestReceipt>;
+    /** Send 1 to 1,000 data points at once. Send the same `idempotencyKey` and body again after a failure to resume. */
+    ingestBatch(items: DataPoint[], options?: IngestDataPointOptions): Promise<MemoryIngestReceipt>;
+    /** Where one send is: `processing`, `completed` or `failed`. */
+    getIngestion(ingestionId: string, options?: {
+        user?: string;
+    }): Promise<MemoryIngestionStatus>;
+    /** Poll `getIngestion` until the send is `completed` or `failed`; throws after `timeoutMs` (default 300000). A timeout does not mean the save failed. */
+    waitForIngestion(ingestionId: string, options?: WaitOptions): Promise<MemoryIngestionStatus>;
+    /** Forget one send: its data points and every memory that rests only on them. Free; a repeat succeeds. */
+    deleteIngestion(ingestionId: string, options?: {
+        user?: string;
+    }): Promise<void>;
+    /** Delete one data point by its `sourceId`, and the memory built on it. */
+    deleteDataPoint(sourceId: string, options?: {
+        user?: string;
+    }): Promise<MemoryDeletion>;
+    /** Delete 1 to 1,000 data points by `sourceId`. If one id is unknown, none is deleted and the error names it. */
+    deleteDataPoints(ids: string[], options?: {
+        user?: string;
+    }): Promise<MemoryDeletion>;
+    /** Ranked, dated evidence for a question, as the person asking (`options.identity`, default `options.user`). */
+    recall(query: string, options?: RecallOptions): Promise<MemoryRecall>;
+    /** This month's usage for the app. Needs the app key. */
+    getUsage(): Promise<MemoryUsage>;
+    /** The recall identity when none is named: only a client that provisioned a user knows it. */
+    private userApiKeyIdentity;
+}
+/** The `X-Harny-Signature` value Harny sends for `body` under `secret`. */
+export declare function computeWebhookSignature(secret: string, body: string | Uint8Array): Promise<string>;
+/**
+ * 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=`.
+ */
+export declare function verifyWebhookSignature(body: string | Uint8Array, signature: string | null | undefined, secrets: string | string[]): Promise<boolean>;
+/**
+ * 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.
+ */
+export declare function parseSourceArrivalEvent(body: string | Uint8Array, signature: string | null | undefined, secrets: string | string[]): Promise<SourceArrivalEvent>;
+export { ActDecision, ActionNote, ActionTrace, Agent, AgentConfig, AgentPendingConfirmation, ChatCompletionsAdapter, FileSessionStore, GenerateContentAdapter, HARNY_CALLS, HarnyTools, HookBlocked, MODEL_REACHABLE_CALLS, MemorySessionStore, Message, MessagesAdapter, ModelProviderError, ModelTurn, PRESET_NAMES, PresetResolutionError, ResolvedModel, RunResult, SpendCap, SpendMeter, Tracer, Turn, Usage, buildAdapter, parseTraceparent, resolvePreset, } from "./agent/index.js";
+export type { AdapterOptions, AgentConfigOptions, AgentHooks, AgentOptions, CompleteRequest, ContextStatus, CreateAgentOptions, HarnyClientLike, HookContext, MessageRole, ModelAdapter, OtelApiLike, OtelSpanContextLike, OtelSpanLike, OtelTracerLike, PresetName, ResolvePresetOptions, RunOptions, SessionStore, SpanAttributeValue, StopReason, ToolCall, ToolResult, ToolSpec, ToolTransport, TurnRole, } from "./agent/index.js";
+export { ASKING_KINDS, CONFLICT_QUESTION_MODES, DEFAULT_CONFLICT_QUESTION_MODE, InMemoryConflictAskLedger, QuestionPhrases, conflictKey, decideConflictQuestion, formatDay, normaliseMode, questionText, } from "./conflictQuestion.js";
+export type { ConflictAskLedger, ConflictLike, ConflictQuestion, ConflictQuestionMode, DecideConflictQuestionOptions, PhrasesSource, QuestionPhrasesInit, } from "./conflictQuestion.js";
+export { RECALL_LEVELS } from "./memoryV1.js";
+export type { DataPoint, IngestDataPointOptions, MemoryDeletion, MemoryIngestionStatus, MemoryIngestReceipt, MemoryItemReceipt, MemoryReadiness, MemoryRecall, MemoryResult, MemorySource, MemoryUsage, RecallLevel, RecallOptions, RecallSort, WaitOptions, } from "./memoryV1.js";