@niadra/sdk 0.1.1 → 0.7.0

package/dist/voltagent.js

@@ -0,0 +1,503 @@
+import { createTool } from '@voltagent/core';
+import { jsonSchema } from 'ai';
+
+// src/integrations/voltagent.ts
+
+// src/usage.ts
+function get(value, name) {
+  return (typeof value === "object" || typeof value === "function") && value !== null ? value[name] : void 0;
+}
+function providerOf(model, usage) {
+  const slash = model.indexOf("/");
+  if (slash > 0) return model.slice(0, slash).trim().toLowerCase();
+  const name = model.trim().toLowerCase();
+  if (name.startsWith("claude") || `.${name}`.includes(".anthropic.")) return "anthropic";
+  if (name.startsWith("gemini")) return "google";
+  if (get(usage, "prompt_tokens") === void 0 && get(usage, "cache_read_input_tokens") !== void 0) {
+    return "anthropic";
+  }
+  return "openai";
+}
+
+// src/capture/tool.ts
+var RECORDED = /* @__PURE__ */ Symbol.for("niadra.tool");
+function recordedTool(fn) {
+  return typeof fn === "function" ? fn[RECORDED] ?? null : null;
+}
+
+// src/context.ts
+function emptyResult(error) {
+  return { text: "", suffix: "", variables: {}, pack: null, source: "none", response: null, error, constraints: null, state: null, coordination: null };
+}
+
+// src/integrations/shared.ts
+var ATTESTED = { A: "V2", B: "V1", C: "V1" };
+function attestationProof(attestation) {
+  if (!attestation) return null;
+  const value = attestation.trim().toUpperCase();
+  if (value.includes("FAILED") || value.startsWith("NO-")) return null;
+  const letter = value.length === 1 ? value : /PASSED-([ABC])$/.exec(value)?.[1];
+  const level = letter ? ATTESTED[letter] : void 0;
+  return level ? { method: "network_attestation", level } : null;
+}
+function resolveSession(source) {
+  if (typeof source !== "function") return source;
+  try {
+    return source() ?? null;
+  } catch {
+    return null;
+  }
+}
+function isConversation(session) {
+  return "customer" in session && typeof session.customer === "function";
+}
+function errorName(error) {
+  return error instanceof Error ? error.name : typeof error;
+}
+var Bridge = class {
+  constructor(session, proof, memory = false) {
+    this.session = session;
+    this.proof = proof;
+    this.memory = memory;
+  }
+  session;
+  proof;
+  memory;
+  proving = null;
+  /** `begin()` started the first read of a call: the first `context()` waits for it with `ready()`. */
+  begun = false;
+  opened = false;
+  /**
+   * The context and, when enabled, the agent's notes, read side by side within the same budget.
+   * Never rejects.
+   */
+  async read(options = {}) {
+    const memoryParams = this.memory === false ? null : this.memory === true ? {} : withoutWrite(this.memory);
+    const [context, memory] = await Promise.all([
+      this.context(options),
+      memoryParams ? this.agentMemory(memoryParams, options) : Promise.resolve("")
+    ]);
+    return { context, memory, prefix: [memory, context.text].filter(Boolean).join("\n\n"), suffix: context.suffix };
+  }
+  get logger() {
+    return this.session.logger;
+  }
+  /**
+   * Starts the first read of a call now, in the background, after the proof when one was given (the
+   * pack depends on the level it proves): at call start, so the read runs while the call is set up.
+   * The first `context()` then waits for it within `timeouts.contextVoiceStart`. Never throws.
+   */
+  begin() {
+    const session = this.session;
+    if (!isConversation(session)) return;
+    const start = () => {
+      this.safe("start the first read", () => {
+        this.begun = session.begin();
+      });
+    };
+    if (this.proof === void 0 || this.proof === null) start();
+    else void this.verifyOnce().then(start);
+  }
+  /** Verifies once (when a proof was given), then reads the context. Never rejects. */
+  async context(options = {}) {
+    await this.verifyOnce();
+    try {
+      const session = this.session;
+      if (this.begun && !this.opened && isConversation(session)) {
+        this.opened = true;
+        await session.ready(options.timeout === void 0 ? {} : { timeout: options.timeout });
+      }
+      return await this.session.context(options);
+    } catch (error) {
+      this.logger.warn(`could not read context (${errorName(error)})`);
+      return emptyResult(null);
+    }
+  }
+  /** Records that `context` went into the prompt, unless it was empty for a reason other than the holdout. */
+  injected(context) {
+    if (!context.text && !context.suffix && context.response?.path !== "holdout") return;
+    this.safe("mark the injection", () => {
+      this.session.markInjected(context);
+    });
+  }
+  customer(text, options = {}) {
+    const session = this.session;
+    if (!text.trim() || !isConversation(session)) return;
+    this.safe("record the customer's turn", () => session.customer(text, options));
+  }
+  /** Sends the customer's turn so far, while they speak. In the background; never throws. */
+  prefetch(text) {
+    const session = this.session;
+    if (!text.trim() || !isConversation(session)) return;
+    this.safe("prefetch the turn", () => session.prefetch(text));
+  }
+  agent(text, options = {}) {
+    if (!text.trim()) return;
+    this.safe("record the agent's turn", () => this.session.agent(text, options));
+  }
+  /** Records a transfer. Tasks have no transfer; the call is ignored for them. */
+  async handoff(target, reason) {
+    const session = this.session;
+    if (!isConversation(session)) return;
+    try {
+      await session.handoff(reason ? { target, reason } : { target });
+    } catch (error) {
+      this.logger.warn(`could not record the handoff (${errorName(error)})`);
+    }
+  }
+  async end() {
+    try {
+      await this.session.end();
+    } catch (error) {
+      this.logger.warn(`could not end the session (${errorName(error)})`);
+    }
+  }
+  /** The navigation kit as plain specs (with the agent's memory tools when enabled), or none for a task about an object only. */
+  tools() {
+    let bound;
+    try {
+      const memory = this.memory;
+      bound = this.session.tools(memory === false ? {} : { agentMemory: true, writeAgentMemory: memory !== true && memory.write === true });
+    } catch (error) {
+      this.logger.warn(`could not build the tools (${errorName(error)})`);
+      return [];
+    }
+    return bound ? toolSpecs(bound) : [];
+  }
+  async agentMemory(params, options) {
+    try {
+      const result = await this.session.agentMemory(params, options.timeout === void 0 ? {} : { timeout: options.timeout });
+      return result.text;
+    } catch (error) {
+      this.logger.warn(`could not read the agent's memory (${errorName(error)})`);
+      return "";
+    }
+  }
+  async verifyOnce() {
+    if (this.proof === void 0 || this.proof === null) return;
+    this.proving ??= this.runVerify();
+    await this.proving;
+  }
+  async runVerify() {
+    try {
+      const source = this.proof;
+      const proof = typeof source === "function" ? await source() : source;
+      if (!proof) return;
+      await this.session.verify(proof);
+    } catch (error) {
+      this.logger.warn(`could not record the verification (${errorName(error)})`);
+    }
+  }
+  safe(what, run) {
+    try {
+      run();
+    } catch (error) {
+      this.logger.warn(`could not ${what} (${errorName(error)})`);
+    }
+  }
+};
+function withoutWrite(option) {
+  const { write: _, ...params } = option;
+  return params;
+}
+function toolSpecs(bound) {
+  return bound.definitions.map(({ function: definition }) => ({
+    name: definition.name,
+    description: definition.description,
+    parameters: definition.parameters,
+    execute: (args) => bound.call(definition.name, args)
+  }));
+}
+function textOf(content) {
+  if (typeof content === "string") return content;
+  if (!Array.isArray(content)) return "";
+  const parts = [];
+  for (const part of content) {
+    if (typeof part === "string") parts.push(part);
+    else if (isRecord(part) && typeof part.text === "string" && (part.type === void 0 || part.type === "text")) {
+      parts.push(part.text);
+    }
+  }
+  return parts.join("");
+}
+function isRecord(value) {
+  return typeof value === "object" && value !== null;
+}
+function count(value) {
+  return typeof value === "number" && Number.isInteger(value) && value >= 0 ? value : null;
+}
+var TurnHooks = class _TurnHooks {
+  constructor(adapter, enabled) {
+    this.adapter = adapter;
+    this.enabled = enabled;
+  }
+  adapter;
+  enabled;
+  /** Runs held open at most; past it the oldest run's turn closes, incomplete (a run whose end never came). */
+  static MAX_OPEN = 100;
+  frames = /* @__PURE__ */ new Map();
+  calls = /* @__PURE__ */ new Map();
+  /** The turn of the run `key`: the session's turn in progress, or a new one of its own. */
+  open(session, key, params = {}) {
+    if (!this.enabled) return void 0;
+    const held = this.frames.get(key);
+    if (held !== void 0) return held.frame;
+    try {
+      const active = session.activeTurn();
+      if (active !== void 0 && !this.owns(active)) {
+        this.frames.set(key, { frame: active, own: false });
+        return active;
+      }
+      const frame = session.openTurn({ ...params, adapter: this.adapter });
+      this.frames.set(key, { frame, own: true });
+      if (this.frames.size > _TurnHooks.MAX_OPEN) {
+        const [oldest] = this.frames.keys();
+        if (oldest !== void 0) {
+          this.frames.get(oldest)?.frame.incomplete();
+          this.close(oldest);
+        }
+      }
+      return frame;
+    } catch (error) {
+      session.logger.warn(`could not open the turn (${errorName(error)})`);
+      return void 0;
+    }
+  }
+  /** The turn of `key`, else the session's turn in progress. */
+  frame(session, key) {
+    if (!this.enabled) return void 0;
+    const held = key === void 0 ? void 0 : this.frames.get(key);
+    const frame = held?.frame ?? session.activeTurn();
+    return frame === void 0 || frame.closed ? void 0 : frame;
+  }
+  has(key) {
+    return this.frames.has(key);
+  }
+  owns(frame) {
+    for (const held of this.frames.values()) if (held.own && held.frame === frame) return true;
+    return false;
+  }
+  /** Ends the run `key`: a turn the adapter opened closes; the calls it left open failed. */
+  close(key, error) {
+    const held = this.frames.get(key);
+    if (held === void 0) return;
+    this.frames.delete(key);
+    for (const [callKey, call] of this.calls) {
+      if (call.frame !== held.frame) continue;
+      this.calls.delete(callKey);
+      if (held.own) call.failed(error ?? "error");
+    }
+    if (held.own) held.frame.close(error);
+  }
+  /** A tool call starting, keyed by `callKey`; `callId` is the provider's id of the call, when there is one. */
+  toolStart(session, callKey, name, args, options = {}) {
+    const frame = this.frame(session, options.frameKey);
+    if (frame === void 0) return;
+    try {
+      this.calls.set(callKey, frame.toolCall(name, args, { callId: options.callId ?? null, adoptable: true }));
+    } catch {
+      frame.incomplete();
+    }
+  }
+  /**
+   * In a replay, how a framework tool the adapter stands in for answers: the recorded result of a call with the
+   * same arguments, or empty (a divergence), never the live tool. `null` outside a replay, and for a function
+   * wrapped with `tool()`, which answers itself.
+   */
+  replayed(session, name, args, fn, frameKey) {
+    const frame = this.enabled ? this.frame(session, frameKey) : session.activeTurn();
+    if (frame?.playback == null || fn !== void 0 && recordedTool(fn) !== null) return null;
+    return frame.playback.answer(name, args, false);
+  }
+  toolEnd(callKey, result, error) {
+    const call = this.calls.get(callKey);
+    if (call === void 0) return;
+    this.calls.delete(callKey);
+    try {
+      if (error !== void 0) call.failed(error);
+      else call.result(result);
+    } catch {
+      call.frame.incomplete();
+    }
+  }
+  /** A model call that ended, with its tokens when the framework reported them. */
+  model(session, model, tokens = {}, frameKey) {
+    const frame = this.frame(session, frameKey);
+    if (frame === void 0) return;
+    try {
+      frame.modelCall(model, { tokensIn: tokens.in ?? null, tokensOut: tokens.out ?? null, tokensCached: tokens.cached ?? 0 });
+    } catch {
+      frame.incomplete();
+    }
+  }
+};
+
+// src/integrations/voltagent.ts
+var NIADRA_CONTEXT_KEY = "niadra";
+function niadraHooks(options = {}) {
+  const states = /* @__PURE__ */ new WeakMap();
+  const hooks = new TurnHooks("voltagent", options.turns ?? false);
+  const stateOf = (context) => {
+    const choice = options.session;
+    const session = typeof choice === "function" ? context ? resolveSession(() => choice(context)) : null : choice ?? asSession(context?.context.get(NIADRA_CONTEXT_KEY));
+    if (!session) return null;
+    let state = states.get(session);
+    if (!state) {
+      state = { bridge: new Bridge(session, options.verify, options.agentMemory), seen: /* @__PURE__ */ new Set() };
+      states.set(session, state);
+    }
+    return state;
+  };
+  const callId = (call) => call?.toolContext?.callId ?? null;
+  const callKey = (context, tool, call) => callId(call) ?? `${context.operationId}:${tool}`;
+  const recordAnswer = ({ output, agent, context }) => {
+    if (!(options.recordAgent ?? true) || !output || !("text" in output)) return;
+    const state = stateOf(context);
+    if (!state) return;
+    try {
+      const steps = Array.isArray(output.steps) ? output.steps : [];
+      const last = steps.at(-1);
+      const response = isRecord(last) && isRecord(last.response) ? last.response : {};
+      const model = typeof response.modelId === "string" ? response.modelId : modelName(agent);
+      const usage = model ? voltAgentUsage(output.totalUsage ?? output.usage, model, options.provider) : null;
+      state.bridge.agent(output.text, usage ? { usage } : {});
+    } catch (error) {
+      state.bridge.logger.warn(`could not record the agent's answer (${errorName(error)})`);
+    }
+  };
+  return {
+    async onPrepareModelMessages({ modelMessages, context }) {
+      const state = stateOf(context);
+      if (!state) return {};
+      try {
+        if (options.recordCustomer ?? true) recordNewest(state, modelMessages);
+        const read = await state.bridge.read();
+        state.bridge.injected(read.context);
+        return { modelMessages: inject(modelMessages, read.prefix, read.suffix) };
+      } catch (error) {
+        state.bridge.logger.warn(`could not inject context (${errorName(error)})`);
+        return {};
+      }
+    },
+    onStart({ agent, context }) {
+      const state = hooks.enabled ? stateOf(context) : null;
+      if (state) hooks.open(state.bridge.session, context.operationId, { agent: agent.name });
+    },
+    onToolStart({ tool, args, context, options: call }) {
+      const state = hooks.enabled ? stateOf(context) : null;
+      if (!state) return;
+      hooks.toolStart(state.bridge.session, callKey(context, tool.name, call), tool.name, args, { frameKey: context.operationId, callId: callId(call) });
+    },
+    onToolEnd({ tool, output, error, context, options: call }) {
+      hooks.toolEnd(callKey(context, tool.name, call), output, error);
+      return void 0;
+    },
+    onStepFinish({ agent, step, context }) {
+      const state = hooks.enabled ? stateOf(context) : null;
+      if (!state || !isRecord(step)) return;
+      const response = isRecord(step.response) ? step.response : {};
+      const usage = isRecord(step.usage) ? step.usage : {};
+      const input = isRecord(usage.inputTokens) ? usage.inputTokens : null;
+      hooks.model(
+        state.bridge.session,
+        typeof response.modelId === "string" ? response.modelId : modelName(agent),
+        {
+          in: input ? count(input.total) : count(usage.inputTokens),
+          out: isRecord(usage.outputTokens) ? count(usage.outputTokens.total) : count(usage.outputTokens),
+          cached: (input ? count(input.cacheRead) : count(usage.cachedInputTokens)) ?? 0
+        },
+        context.operationId
+      );
+    },
+    onEnd(args) {
+      try {
+        recordAnswer(args);
+      } finally {
+        hooks.close(args.context.operationId);
+      }
+    },
+    async onHandoff({ agent, sourceAgent }) {
+      const state = typeof options.session === "object" ? stateOf(void 0) : null;
+      if (state) await state.bridge.handoff("agent", `${sourceAgent.name} to ${agent.name}`);
+    }
+  };
+}
+function niadraTools(session, options = {}) {
+  return new Bridge(session, void 0, options.agentMemory).tools().map(
+    (spec) => createTool({
+      name: spec.name,
+      description: spec.description,
+      // VoltAgent hands the schema to the AI SDK, which takes a JSON Schema as it takes Zod.
+      parameters: jsonSchema(spec.parameters),
+      execute: async (input) => parsed(await spec.execute(isRecord(input) ? input : {}))
+    })
+  );
+}
+function voltAgentUsage(usage, model, provider) {
+  if (!isRecord(usage)) return null;
+  const prompt = count(usage.inputTokens);
+  if (prompt === null) return null;
+  const details = isRecord(usage.inputTokenDetails) ? usage.inputTokenDetails : {};
+  const cached = count(details.cacheReadTokens) ?? count(usage.cachedInputTokens) ?? 0;
+  const written = count(details.cacheWriteTokens) ?? 0;
+  return {
+    provider: (provider ?? providerOf(model, usage)).toLowerCase(),
+    model,
+    prompt_tokens: Math.max(prompt, cached + written),
+    cached_tokens: cached,
+    cache_write_tokens: written
+  };
+}
+function recordNewest(state, messages) {
+  const index = lastUser(messages);
+  if (index < 0) return;
+  const text = textOf(messages[index]?.content);
+  const key = `${String(index)}:${text}`;
+  if (!text || state.seen.has(key)) return;
+  state.seen.add(key);
+  state.bridge.customer(text);
+}
+function inject(messages, prefix, suffix) {
+  const result = [...messages];
+  const index = lastUser(result);
+  const last = result[index];
+  if (suffix && last?.role === "user") {
+    const content = typeof last.content === "string" ? `${last.content}
+
+${suffix}` : [...last.content, { type: "text", text: suffix }];
+    result[index] = { ...last, content };
+  }
+  if (prefix) {
+    let position = 0;
+    while (position < result.length && result[position]?.role === "system") position++;
+    result.splice(position, 0, { role: "system", content: prefix });
+  }
+  return result;
+}
+function lastUser(messages) {
+  for (let index = messages.length - 1; index >= 0; index--) if (messages[index]?.role === "user") return index;
+  return -1;
+}
+function modelName(agent) {
+  if (!isRecord(agent) || typeof agent.getModelName !== "function") return void 0;
+  try {
+    const name = agent.getModelName.call(agent);
+    return typeof name === "string" && name ? name : void 0;
+  } catch {
+    return void 0;
+  }
+}
+function asSession(value) {
+  return isRecord(value) && typeof value.context === "function" && typeof value.agent === "function" ? value : null;
+}
+function parsed(text) {
+  try {
+    return JSON.parse(text);
+  } catch {
+    return text;
+  }
+}
+
+export { NIADRA_CONTEXT_KEY, attestationProof, niadraHooks, niadraTools, voltAgentUsage };
+//# sourceMappingURL=voltagent.js.map
+//# sourceMappingURL=voltagent.js.map