@harny/sdk 0.1.2 → 0.1.4

package/dist/esm/agent/hooks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hooks.js","sourceRoot":"","sources":["../../../src/agent/hooks.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAKH,sFAAsF;AACtF,MAAM,OAAO,WAAY,SAAQ,KAAK;IAClC,YAAY,OAAe;QACvB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,aAAa,CAAC;IAC9B,CAAC;CACJ;AAUD,MAAM,OAAO,WAAW;IACpB,YACa,KAAc,EACd,SAAiB,EAAE;QADnB,UAAK,GAAL,KAAK,CAAS;QACd,WAAM,GAAN,MAAM,CAAa;QAE5B,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IACxB,CAAC;IAED,MAAM,CAAC,OAAO;QACV,OAAO,IAAI,WAAW,CAAC,IAAI,CAAC,CAAC;IACjC,CAAC;IAED,MAAM,CAAC,IAAI,CAAC,MAAc;QACtB,OAAO,IAAI,WAAW,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;IAC1C,CAAC;CACJ"}

package/dist/esm/agent/index.d.ts

@@ -0,0 +1,34 @@
+/**
+ * An agent loop on the business's own model key, with Harny for context and actions.
+ *
+ *     import { Agent, FileSessionStore, HarnyClient } from "@harny/sdk";
+ *
+ *     const harny = new HarnyClient({ apiKey: process.env.HARNY_APP_KEY });
+ *     const agent = await Agent.create({
+ *         harny,
+ *         // The preset you chose: cost_first, quality_first or regulated.
+ *         preset: process.env.HARNY_MODEL_PRESET ?? "",
+ *         config: { instructions: "You help one person with their calendar." },
+ *         store: new FileSessionStore("./data/sessions"),
+ *     });
+ *     const result = await agent.run({ user: "user-123", message: "Put the call with Sam on Thursday at 3pm" });
+ *     console.log(result.answer, result.pendingConfirmations.map((p) => p.public()));
+ *
+ * Put the model key in the provider's usual environment variable, or pass
+ * `apiKey` together with `provider`. Harny never sees it.
+ */
+export { ChatCompletionsAdapter, GenerateContentAdapter, Message, MessagesAdapter, ModelProviderError, ModelTurn, Usage, buildAdapter, } from "./adapters.js";
+export type { AdapterOptions, CompleteRequest, MessageRole, ModelAdapter, ToolCall, ToolResult, ToolSpec, } from "./adapters.js";
+export { ActDecision, HookBlocked } from "./hooks.js";
+export type { AgentHooks, HookContext } from "./hooks.js";
+export { ActionTrace, Agent, AgentConfig, AgentPendingConfirmation, RunResult } from "./loop.js";
+export type { AgentConfigOptions, AgentOptions, ContextStatus, CreateAgentOptions, RunOptions, StopReason } from "./loop.js";
+export { PRESET_NAMES, PresetResolutionError, ResolvedModel, resolvePreset } from "./roster.js";
+export type { PresetName, ResolvePresetOptions, ToolTransport } from "./roster.js";
+export { ActionNote, FileSessionStore, MemorySessionStore, Turn } from "./session.js";
+export type { SessionStore, TurnRole } from "./session.js";
+export { FALLBACK_MAX_TOKENS, SpendCap, SpendMeter } from "./spend.js";
+export { HARNY_CALLS, HarnyTools, MODEL_REACHABLE_CALLS } from "./tools.js";
+export type { HarnyClientLike } from "./tools.js";
+export { Tracer, parseTraceparent } from "./tracing.js";
+export type { OtelApiLike, OtelSpanContextLike, OtelSpanLike, OtelTracerLike, SpanAttributeValue, } from "./tracing.js";

package/dist/esm/agent/index.js

@@ -0,0 +1,28 @@
+/**
+ * An agent loop on the business's own model key, with Harny for context and actions.
+ *
+ *     import { Agent, FileSessionStore, HarnyClient } from "@harny/sdk";
+ *
+ *     const harny = new HarnyClient({ apiKey: process.env.HARNY_APP_KEY });
+ *     const agent = await Agent.create({
+ *         harny,
+ *         // The preset you chose: cost_first, quality_first or regulated.
+ *         preset: process.env.HARNY_MODEL_PRESET ?? "",
+ *         config: { instructions: "You help one person with their calendar." },
+ *         store: new FileSessionStore("./data/sessions"),
+ *     });
+ *     const result = await agent.run({ user: "user-123", message: "Put the call with Sam on Thursday at 3pm" });
+ *     console.log(result.answer, result.pendingConfirmations.map((p) => p.public()));
+ *
+ * Put the model key in the provider's usual environment variable, or pass
+ * `apiKey` together with `provider`. Harny never sees it.
+ */
+export { ChatCompletionsAdapter, GenerateContentAdapter, Message, MessagesAdapter, ModelProviderError, ModelTurn, Usage, buildAdapter, } from "./adapters.js";
+export { ActDecision, HookBlocked } from "./hooks.js";
+export { ActionTrace, Agent, AgentConfig, AgentPendingConfirmation, RunResult } from "./loop.js";
+export { PRESET_NAMES, PresetResolutionError, ResolvedModel, resolvePreset } from "./roster.js";
+export { ActionNote, FileSessionStore, MemorySessionStore, Turn } from "./session.js";
+export { FALLBACK_MAX_TOKENS, SpendCap, SpendMeter } from "./spend.js";
+export { HARNY_CALLS, HarnyTools, MODEL_REACHABLE_CALLS } from "./tools.js";
+export { Tracer, parseTraceparent } from "./tracing.js";
+//# sourceMappingURL=index.js.map

package/dist/esm/agent/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/agent/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EACH,sBAAsB,EACtB,sBAAsB,EACtB,OAAO,EACP,eAAe,EACf,kBAAkB,EAClB,SAAS,EACT,KAAK,EACL,YAAY,GACf,MAAM,eAAe,CAAC;AAUvB,OAAO,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAEtD,OAAO,EAAE,WAAW,EAAE,KAAK,EAAE,WAAW,EAAE,wBAAwB,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAEjG,OAAO,EAAE,YAAY,EAAE,qBAAqB,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAEhG,OAAO,EAAE,UAAU,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,IAAI,EAAE,MAAM,cAAc,CAAC;AAEtF,OAAO,EAAE,mBAAmB,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AACvE,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAE5E,OAAO,EAAE,MAAM,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC"}

package/dist/esm/agent/loop.d.ts

@@ -0,0 +1,401 @@
+/**
+ * The agent loop: context from Harny, the business's own model, actions through Harny.
+ *
+ * One run answers one input: a user's chat message, an arrived email, or a
+ * scheduled instruction.
+ *
+ * 1. Ask Harny for context about the user (`assembleContext`).
+ * 2. Call the business's model, on the business's key, with the tools below.
+ * 3. Perform each tool call through Harny by name (`act`, `undo`, reads).
+ * 4. Repeat until the model answers, the step limit, the timeout or the spend cap.
+ *
+ * What the loop guarantees:
+ *
+ * - Harny is reached only through `HarnyTools`. The conversation (the user's
+ *   turns and the model's) is kept in the business's session store and is
+ *   never written into Harny's memory.
+ * - `initiatedBy` comes from the runtime (a chat message, an email, a
+ *   schedule), never from the model.
+ * - A chat run (`initiatedBy: "user_request"`) sends the person's WHOLE
+ *   message with each action as their own words: an email address in it
+ *   counts as one the person gave. After the agent read someone else's
+ *   content, an invitation or message to an address the person gave follows
+ *   the business's settings, and one to an address they never gave waits for
+ *   their yes. When the message carries anything but what the person typed (a
+ *   pasted email, a quoted document), pass their own words as
+ *   `endUserMessage`. Any other run sends no words unless given them: an
+ *   email run's message is the email, not the person.
+ * - The loop adds no pause of its own. It asks the person only when Harny,
+ *   running the business's acting policy, says an action waits for them; it
+ *   then returns a confirmation for the business's page. The model is told
+ *   only that it is waiting; it has no tool that can approve it.
+ * - Each action gets an idempotency key derived from the run id, the action and
+ *   how many times Harny already answered that action with an outcome in this
+ *   run, so retrying a run with the same run id never performs an action
+ *   twice, even when the retry takes a different path to it. A request Harny
+ *   refused before binding the key (bad arguments), a server or network fault,
+ *   a timeout and a "key already used" answer all leave the count where it
+ *   was, so the next request for that action carries the same key. When Harny
+ *   answers that the key was already used, the model is told the action was
+ *   already requested in an earlier attempt.
+ * - No action starts after the run's time is up. An action already on its way
+ *   is waited for (as long as the client's request timeout) and recorded.
+ * - A spend cap per run stops the loop before the next model call once reached.
+ * - Harny's limit on a person's context reads never fails a run. When the
+ *   first read is refused for now (HTTP 429), the loop waits the time Harny
+ *   names plus one second, once, if that is at most half of the run's
+ *   remaining time and at most 60 seconds, and reads again. Otherwise, or if
+ *   the second read is refused too, the model gets the context this person's
+ *   previous message read (kept up to two minutes, labelled as such), or
+ *   none, and `RunResult.contextStatus` says which. A limit met by the model's
+ *   own context read reaches it as data ("carry on with what you have"). The
+ *   loop adds no question to the person of its own.
+ * - At the step limit the model gets one closing turn, its tools still listed
+ *   but none run, to answer from what the run found (within the spend cap and
+ *   the run's time). The run stops `max_steps` with that answer, or, when
+ *   there is none, with `error` saying why and no answer written for it.
+ * - A model turn the provider stopped before it finished (at the answer limit,
+ *   or for another documented reason such as a content filter or a lack of
+ *   resources) ends the run as `cut_off`: its text is never returned as the
+ *   answer and its tool calls are never run, so a half-written reply or action
+ *   records nothing new.
+ * - The business's `afterAct` hook runs after the outcome is recorded; a hook
+ *   that fails is logged and never turns a completed action into an error.
+ * - Each completed action leaves a short note (action, record id, time) on the
+ *   conversation in the business's session store, so a later message ("undo
+ *   that") can name the record. The note goes to the business's model with
+ *   the next run, never to Harny.
+ */
+import type { ActionInitiator, ActionOutcome, ModelRoster, SourceArrival } from "../index.js";
+import { Usage, type ModelAdapter, type ToolSpec } from "./adapters.js";
+import { type AgentHooks } from "./hooks.js";
+import { type ResolvedModel } from "./roster.js";
+import { ActionNote, type SessionStore } from "./session.js";
+import { SpendCap } from "./spend.js";
+import { type HarnyClientLike, HarnyTools } from "./tools.js";
+import { type OtelApiLike } from "./tracing.js";
+/**
+ * Whether the model got what Harny knows about the person for this message:
+ * read, read after waiting out Harny's read limit, the person's previous
+ * message's context reused, or not read.
+ */
+export type ContextStatus = "read" | "read_after_wait" | "reused_previous" | "not_read";
+/** Why a run stopped. */
+export type StopReason = "completed" | "cut_off" | "max_steps" | "spend_cap" | "timeout" | "model_error" | "blocked";
+/** The actions this agent performed earlier in the conversation, for the model only. */
+export declare function actionsBlock(notes: ActionNote[], options: {
+    allowUndo: boolean;
+}): string;
+export interface AgentConfigOptions {
+    /** What the agent is for, in your words. Required. */
+    instructions: string;
+    /** Catalog actions the model may ask for. Default: `["calendar.create_event"]`. */
+    actions?: readonly string[];
+    allowUndo?: boolean;
+    offerSourceTools?: boolean;
+    prefetchContext?: boolean;
+    /** Tokens of context Harny assembles per question. Default 4096. */
+    contextTokenBudget?: number;
+    historyTurns?: number;
+    maxSteps?: number;
+    /** Time a run may take. Default 90 seconds. */
+    runTimeoutMs?: number;
+    maxOutputTokens?: number;
+    spendCap?: SpendCap;
+    defaultTimeZone?: string | null;
+    name?: string;
+}
+export declare class AgentConfig {
+    readonly instructions: string;
+    readonly actions: readonly string[];
+    readonly allowUndo: boolean;
+    readonly offerSourceTools: boolean;
+    readonly prefetchContext: boolean;
+    /** 4,096: room for the memory records a default question reads, with headroom. */
+    readonly contextTokenBudget: number;
+    readonly historyTurns: number;
+    readonly maxSteps: number;
+    readonly runTimeoutMs: number;
+    readonly maxOutputTokens: number;
+    readonly spendCap: SpendCap;
+    readonly defaultTimeZone: string | null;
+    readonly name: string;
+    constructor(options: AgentConfigOptions);
+}
+/**
+ * An action waiting for the end user, for the business's confirm UI.
+ *
+ * `confirmRef` never reaches a model: it is readable, but never enumerated or
+ * serialized, and `public()` leaves it out. Store it yourself (read it
+ * explicitly) when a confirmation must survive a restart, and rebuild the
+ * object with the constructor. `arguments` are the arguments Harny holds for
+ * the action (what an approval performs). For an undo, `removes` holds the
+ * arguments of the event it deletes when this agent created it. `sessionId`
+ * is the conversation the action came from (empty for an email or scheduled
+ * run); an approval leaves its action note there.
+ */
+export declare class AgentPendingConfirmation {
+    readonly id: string;
+    readonly user: string;
+    readonly action: string;
+    readonly summary: string;
+    readonly expiresAt: string | null;
+    readonly runId: string;
+    readonly arguments: Record<string, unknown>;
+    readonly removes: Record<string, unknown> | null;
+    readonly sessionId: string;
+    constructor(init: {
+        id: string;
+        user: string;
+        action: string;
+        summary: string;
+        confirmRef: string;
+        expiresAt?: string | null;
+        runId?: string;
+        arguments?: Record<string, unknown>;
+        removes?: Record<string, unknown> | null;
+        sessionId?: string;
+    });
+    get confirmRef(): string;
+    /**
+     * What the business's page may show: no confirm reference. `event` is the
+     * event an approval creates and `removes` the event an approved undo
+     * deletes, field by field, so the person sees the guests, the description
+     * and the repeats, not only a model-written title.
+     */
+    public(): Record<string, unknown>;
+}
+export declare class ActionTrace {
+    readonly tool: string;
+    readonly action: string | null;
+    readonly outcome: string;
+    readonly recordId: string | null;
+    readonly refusalCode: string | null;
+    readonly detail: string;
+    constructor(init: {
+        tool: string;
+        action: string | null;
+        outcome: string;
+        recordId?: string | null;
+        refusalCode?: string | null;
+        detail?: string;
+    });
+    public(): Record<string, unknown>;
+}
+export declare class RunResult {
+    readonly runId: string;
+    /**
+     * The model's answer: from a `completed` run, or the closing answer of a
+     * run that reached its step limit (`max_steps`). `null` otherwise. Never a
+     * cut-off answer.
+     */
+    readonly answer: string | null;
+    readonly stoppedReason: StopReason;
+    /** Steps that could use tools; the closing turn at the step limit is not one. */
+    readonly steps: number;
+    readonly actions: ActionTrace[];
+    readonly pendingConfirmations: AgentPendingConfirmation[];
+    readonly usage: Usage;
+    readonly costUsd: number | null;
+    readonly model: Record<string, unknown>;
+    readonly traceId: string;
+    readonly error: string | null;
+    /**
+     * Whether the model got what Harny knows about the person for this message.
+     * For your logs; the person sees only the answer.
+     */
+    readonly contextStatus: ContextStatus;
+    /** Why, when `contextStatus` is not a plain `read` (empty otherwise). */
+    readonly contextStatusReason: string;
+    constructor(init: {
+        runId: string;
+        answer: string | null;
+        stoppedReason: StopReason;
+        steps: number;
+        actions: ActionTrace[];
+        pendingConfirmations: AgentPendingConfirmation[];
+        usage: Usage;
+        costUsd: number | null;
+        model: Record<string, unknown>;
+        traceId: string;
+        error?: string | null;
+        contextStatus?: ContextStatus;
+        contextStatusReason?: string;
+    });
+    /** What the business's page may show (the same fields the Python SDK's result has). */
+    public(): Record<string, unknown>;
+}
+export interface AgentOptions {
+    /** A `HarnyClient` built with your app key, or a `HarnyTools` around one. */
+    harny: HarnyClientLike | HarnyTools;
+    model: ModelAdapter;
+    config: AgentConfig | AgentConfigOptions;
+    store?: SessionStore;
+    hooks?: AgentHooks;
+    /** `[input, output]` dollars per million tokens, for the dollar spend cap. */
+    prices?: readonly [number, number] | null;
+    modelInfo?: Record<string, unknown>;
+    /** Your OpenTelemetry API, to emit spans. */
+    otel?: OtelApiLike | null;
+}
+export interface CreateAgentOptions {
+    /** A `HarnyClient` built with your app key. */
+    harny: HarnyClientLike & {
+        getModelRoster(): Promise<ModelRoster>;
+    };
+    /** `cost_first`, `quality_first` or `regulated`. */
+    preset: string;
+    config: AgentConfig | AgentConfigOptions;
+    /** Pin one provider of the preset. */
+    provider?: string | null;
+    /** An explicit model key; needs `provider`. */
+    apiKey?: string | null;
+    /** Where the conventional key variables are read. Defaults to the process environment. */
+    env?: Record<string, string | undefined>;
+    prices?: readonly [number, number] | null;
+    store?: SessionStore;
+    hooks?: AgentHooks;
+    /** A `fetch` for the model calls (tests, proxies). */
+    fetch?: typeof fetch;
+    otel?: OtelApiLike | null;
+}
+export interface RunOptions {
+    /** The end user, by Harny id or your own identifier. */
+    user: string;
+    message: string;
+    /** The conversation. Default `user:<user>`. */
+    sessionId?: string | null;
+    /** What caused the run, from your runtime (never from a model). Default `user_request`. */
+    initiatedBy?: ActionInitiator;
+    sourceRef?: string | null;
+    contextQuery?: string | null;
+    traceparent?: string | null;
+    /** Retry a run with the same id and no action is performed twice. */
+    runId?: string | null;
+    /** Keep the exchange in the session store. Default true. */
+    persist?: boolean;
+    now?: Date;
+    /**
+     * The person's own words for this run. For a chat run (`user_request`)
+     * the WHOLE `message` is sent with each action as their words when this
+     * is not given: an email address in it counts as one the person gave, so
+     * after the agent read someone else's content an invitation or message to
+     * it follows your settings instead of waiting for their yes. Pass only
+     * what the person typed when `message` carries anything else (a pasted
+     * email, a quoted document, text your app added). Any other run sends
+     * these only when given; Harny never counts them for `system_event`.
+     */
+    endUserMessage?: string | null;
+}
+/** One configured agent. Reuse it across runs and users. */
+export declare class Agent {
+    readonly config: AgentConfig;
+    readonly modelInfo: Record<string, unknown>;
+    private readonly harny;
+    private readonly model;
+    private readonly store;
+    private readonly hooks;
+    private readonly prices;
+    private readonly otel;
+    private readonly tools;
+    private readonly actionByTool;
+    /** (user, record id) → arguments of an event this agent created (bounded). */
+    private readonly created;
+    /** user → when (loop clock, ms) and text of their last context read for a message (bounded, in memory only). */
+    private readonly previousContext;
+    constructor(options: AgentOptions);
+    /** Read the roster, resolve the preset with your own key, build the agent. */
+    static create(options: CreateAgentOptions): Promise<Agent>;
+    static fromResolved(options: {
+        harny: HarnyClientLike | HarnyTools;
+        resolved: ResolvedModel;
+        config: AgentConfig | AgentConfigOptions;
+        prices?: readonly [number, number] | null;
+        store?: SessionStore;
+        hooks?: AgentHooks;
+        fetch?: typeof fetch;
+        otel?: OtelApiLike | null;
+    }): Agent;
+    /** A key-free view for logs: never a key, never the client. */
+    toJSON(): Record<string, unknown>;
+    /** The tool names the model is offered (for audits and tests). */
+    get toolNames(): string[];
+    get toolSpecs(): ToolSpec[];
+    run(options: RunOptions): Promise<RunResult>;
+    /**
+     * Handle one arrived email (a `SourceArrival`) as third-party content.
+     *
+     * The email is read INSIDE the run's trace. The run sends no words of the
+     * person's with its actions (the message is the email): an invitation or
+     * message to an address the person never gave waits for their yes.
+     */
+    runArrival(arrival: SourceArrival, options: {
+        instruction: string;
+        traceparent?: string | null;
+        runId?: string | null;
+        now?: Date;
+    }): Promise<RunResult>;
+    /** One tool-free call to the model, to prove the key and the endpoint work. */
+    pingModel(): Promise<string>;
+    /**
+     * Host-only: send the end user's decision. Never wire this to a model.
+     *
+     * An approved action that completes leaves its note on the conversation
+     * (`sessionId`, else the one the action came from), so the person can say
+     * "undo that" in their next message.
+     */
+    confirm(pending: AgentPendingConfirmation, options: {
+        approve: boolean;
+        traceparent?: string | null;
+        sessionId?: string | null;
+    }): Promise<ActionOutcome>;
+    private createdKey;
+    private rememberCreated;
+    /** After a restart, the conversation's notes still let an undo card name its event. */
+    private recallCreated;
+    private trimCreated;
+    private system;
+    private loop;
+    /**
+     * At the step limit: one more model turn, to answer from what the run found.
+     *
+     * The tools stay listed (a provider refuses a request whose history holds
+     * tool calls but lists none) and nothing the turn asks for is run. The
+     * instruction rides in the same turn as the last tool results, so every
+     * wire style keeps its user and model turns alternating. The run stays
+     * `max_steps`: with the model's answer, or with `error` saying why there is
+     * none. No answer is ever written for the model.
+     */
+    private closingAnswer;
+    private contextText;
+    /**
+     * What the model's <context> shows for this message (escaped), from the
+     * run's first read.
+     *
+     * Context can carry stored third-party text (an email): it never closes its
+     * wrapper. A read limit (HTTP 429) never fails the run: the loop waits the
+     * time Harny names plus one second, once, if that is at most half of the
+     * run's remaining time and at most a minute, and reads again. Otherwise, or
+     * if the second read is refused too, the model gets the context this
+     * person's previous message read (up to two minutes old, labelled), or
+     * none. Any other error is thrown as before.
+     */
+    private firstContext;
+    /** A read that got through: kept for this person's next message, shown to the model. */
+    private contextRead;
+    /** The read limit kept this message's context out: the previous message's, or none. */
+    private contextKeptOut;
+    private dispatch;
+    private runTool;
+    /**
+     * Send one action to Harny and record its outcome. The key is computed and
+     * the run's time checked first, then the call starts with no wait in
+     * between, so no action starts after the run has stopped. The recording is
+     * part of the tracked promise, so a run whose time runs out while the
+     * action is on its way waits for it and shows it.
+     */
+    private perform;
+    /** A retry of the run reached an action an earlier attempt already requested. */
+    private alreadyRequested;
+    private outcomePayload;
+}