@niadra/sdk 0.1.0 → 0.7.0

package/dist/google-adk.js

@@ -0,0 +1,701 @@
+import { BaseTool } from '@google/adk';
+
+// src/integrations/google-adk.ts
+
+// src/tools.ts
+var TOOL_DEFINITIONS = [
+  {
+    "type": "function",
+    "function": {
+      "name": "search_customer_history",
+      "description": "Search everything that already happened with this customer: past conversations, promises, agent actions, orders and invoices. Use it when the customer refers to something earlier or asks whether a problem happened before. Do not call it when the answer is already in the context block, including its 'Do hist\xF3rico' line, which already counts recurrences. Returns short items with date, channel and outcome, plus a recurrence count. Open one with open_history_item.",
+      "parameters": {
+        "type": "object",
+        "properties": {
+          "query": {
+            "type": "string",
+            "description": "What to look for, in the customer's words."
+          },
+          "filters": {
+            "type": "object",
+            "properties": {
+              "since": {
+                "type": "string",
+                "format": "date-time"
+              },
+              "until": {
+                "type": "string",
+                "format": "date-time"
+              },
+              "when": {
+                "type": "string",
+                "description": "The period in the customer's own words, as they said it: 'last week', 'semana passada', 'en marzo'."
+              },
+              "channels": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                }
+              },
+              "categories": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                }
+              },
+              "item_kinds": {
+                "type": "array",
+                "items": {
+                  "enum": [
+                    "episode",
+                    "fact",
+                    "open_item",
+                    "action",
+                    "object",
+                    "trait"
+                  ]
+                }
+              },
+              "outcome": {
+                "type": "string"
+              }
+            },
+            "additionalProperties": false
+          },
+          "max_tokens": {
+            "type": "integer",
+            "minimum": 50,
+            "maximum": 4e3
+          }
+        },
+        "required": [
+          "query"
+        ],
+        "additionalProperties": false
+      }
+    }
+  },
+  {
+    "type": "function",
+    "function": {
+      "name": "get_customer_timeline",
+      "description": "List this customer's conversations and agent actions in order, newest first, one line each. Use it to leaf through the history when you do not know what to search for. Pass next_cursor to continue. Prefer search_customer_history for a specific question.",
+      "parameters": {
+        "type": "object",
+        "properties": {
+          "cursor": {
+            "type": "string"
+          },
+          "limit": {
+            "type": "integer",
+            "minimum": 1,
+            "maximum": 100
+          },
+          "filters": {
+            "type": "object",
+            "properties": {
+              "since": {
+                "type": "string",
+                "format": "date-time"
+              },
+              "until": {
+                "type": "string",
+                "format": "date-time"
+              },
+              "when": {
+                "type": "string",
+                "description": "The period in the customer's own words, as they said it: 'last week', 'semana passada', 'en marzo'."
+              },
+              "channels": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                }
+              },
+              "categories": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                }
+              },
+              "item_kinds": {
+                "type": "array",
+                "items": {
+                  "enum": [
+                    "episode",
+                    "fact",
+                    "open_item",
+                    "action",
+                    "object",
+                    "trait"
+                  ]
+                }
+              },
+              "outcome": {
+                "type": "string"
+              }
+            },
+            "additionalProperties": false
+          }
+        },
+        "additionalProperties": false
+      }
+    }
+  },
+  {
+    "type": "function",
+    "function": {
+      "name": "open_history_item",
+      "description": "Open one conversation or business object returned by search_customer_history or get_customer_timeline: what was asked, what was promised and by whom, the outcome and what memory came from it. Use it only after a search or timeline pointed to the item.",
+      "parameters": {
+        "type": "object",
+        "properties": {
+          "id": {
+            "type": "string",
+            "description": "The item id, e.g. `episode:...`."
+          }
+        },
+        "required": [
+          "id"
+        ],
+        "additionalProperties": false
+      }
+    }
+  }
+];
+var AGENT_MEMORY_TOOL_DEFINITIONS = [
+  {
+    "type": "function",
+    "function": {
+      "name": "search_agent_memory",
+      "description": "Search your own working notes: procedures, how the company's tools and processes behave, and known pitfalls. Use it before a task or a tool call you are unsure how to do. It holds nothing about customers; for the customer's history use search_customer_history.",
+      "parameters": {
+        "type": "object",
+        "properties": {
+          "query": {
+            "type": "string",
+            "description": "What you need to know how to do."
+          },
+          "tags": {
+            "type": "array",
+            "maxItems": 8,
+            "items": {
+              "type": "string",
+              "pattern": "^[a-z0-9][a-z0-9_.:-]{0,63}$"
+            },
+            "description": "Object types, operations or systems, e.g. `invoice`, `credit`, `erp`."
+          }
+        },
+        "required": [
+          "query"
+        ],
+        "additionalProperties": false
+      }
+    }
+  },
+  {
+    "type": "function",
+    "function": {
+      "name": "remember",
+      "description": "Save a working note for yourself and future runs: a procedure that worked, how a tool or process behaves, or a pitfall to avoid. Never write anything about a customer here: no names, phones, e-mails, documents, ids or words from the conversation. A note with personal data is refused. Write it so it helps with any customer.",
+      "parameters": {
+        "type": "object",
+        "properties": {
+          "kind": {
+            "enum": [
+              "procedure",
+              "tool_note",
+              "process_note",
+              "pitfall"
+            ]
+          },
+          "title": {
+            "type": "string",
+            "maxLength": 120
+          },
+          "body": {
+            "type": "string",
+            "maxLength": 2e3
+          },
+          "tags": {
+            "type": "array",
+            "maxItems": 8,
+            "items": {
+              "type": "string",
+              "pattern": "^[a-z0-9][a-z0-9_.:-]{0,63}$"
+            },
+            "description": "Object types, operations or systems, e.g. `invoice`, `credit`, `erp`."
+          }
+        },
+        "required": [
+          "kind",
+          "title",
+          "body"
+        ],
+        "additionalProperties": false
+      }
+    }
+  }
+];
+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";
+  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 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 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/google-adk.ts
+var MAX_SESSIONS = 1e4;
+function niadraAdk(options) {
+  const bySession = /* @__PURE__ */ new Map();
+  const hooks = new TurnHooks("google-adk", options.turns ?? false);
+  const runKey = (context) => `${context.invocationId}:${context.agentName}`;
+  const fixed = typeof options.session === "function" ? null : newState(options.session, options);
+  const stateOf = (context) => {
+    if (fixed) return fixed;
+    const resolve = options.session;
+    const key = context.sessionId;
+    if (bySession.has(key)) return bySession.get(key) ?? null;
+    let state;
+    try {
+      const session = resolve(context);
+      state = session ? newState(session, options) : null;
+    } catch {
+      state = null;
+    }
+    bySession.set(key, state);
+    if (bySession.size > MAX_SESSIONS) {
+      const oldest = bySession.keys().next().value;
+      if (oldest !== void 0) bySession.delete(oldest);
+    }
+    return state;
+  };
+  const beforeModelCallback = async ({ context, request }) => {
+    const state = stateOf(context);
+    if (!state) return void 0;
+    state.model = request.model ?? state.model;
+    try {
+      const contents = request.contents;
+      const said = textOfParts(context.userContent?.parts);
+      if ((options.recordCustomer ?? true) && said && !state.seen.has(context.invocationId)) {
+        state.seen.add(context.invocationId);
+        if (state.seen.size > MAX_SESSIONS) state.seen.clear();
+        state.bridge.customer(said);
+      }
+      const read = await state.bridge.read();
+      state.bridge.injected(read.context);
+      if (read.prefix) {
+        const config = request.config ??= {};
+        const system = config.systemInstruction;
+        if (system === void 0 || system === "") config.systemInstruction = read.prefix;
+        else if (typeof system === "string") config.systemInstruction = `${system}
+
+${read.prefix}`;
+        else if (isRecord(system) && Array.isArray(system.parts)) config.systemInstruction = { ...system, parts: [...system.parts, { text: read.prefix }] };
+        else if (Array.isArray(system)) config.systemInstruction = [...system, { text: read.prefix }];
+      }
+      if (read.suffix) {
+        for (let index = contents.length - 1; index >= 0; index--) {
+          const content = contents[index];
+          if (!content || (content.role ?? "user") !== "user" || !textOfParts(content.parts)) continue;
+          contents[index] = { ...content, parts: [...content.parts ?? [], { text: read.suffix }] };
+          break;
+        }
+      }
+    } catch (error) {
+      state.bridge.logger.warn(`could not inject context (${errorName(error)})`);
+    }
+    return void 0;
+  };
+  const afterModelCallback = async ({ context, response }) => {
+    const state = stateOf(context);
+    if (!state || response.partial === true) return void 0;
+    const tokens = response.usageMetadata;
+    hooks.model(state.bridge.session, state.model || null, { in: count(tokens?.promptTokenCount), out: count(tokens?.candidatesTokenCount), cached: count(tokens?.cachedContentTokenCount) ?? 0 }, runKey(context));
+    try {
+      const parts = response.content?.parts ?? [];
+      const transfer = parts.find((part) => part.functionCall?.name === "transfer_to_agent")?.functionCall;
+      if (transfer) {
+        const target = isRecord(transfer.args) && typeof transfer.args.agent_name === "string" ? transfer.args.agent_name : void 0;
+        await state.bridge.handoff("agent", target ? `${context.agentName} to ${target}` : void 0);
+        return void 0;
+      }
+      if (!(options.recordAgent ?? true) || parts.some((part) => part.functionCall)) return void 0;
+      const text = textOfParts(parts, "");
+      if (!text) return void 0;
+      const usage = adkUsage(response, state.model);
+      state.bridge.agent(text, usage ? { usage } : {});
+    } catch (error) {
+      state.bridge.logger.warn(`could not record the agent's answer (${errorName(error)})`);
+    }
+    return void 0;
+  };
+  const memory = options.agentMemory;
+  const definitions = [
+    ...TOOL_DEFINITIONS,
+    ...memory ? AGENT_MEMORY_TOOL_DEFINITIONS.slice(0, memory !== true && memory.write ? 2 : 1) : []
+  ];
+  const tools = definitions.map(({ function: definition }) => new NiadraTool(definition, (context) => stateOf(context)));
+  const beforeAgentCallback = (context) => {
+    const state = stateOf(context);
+    if (state) hooks.open(state.bridge.session, runKey(context), { agent: context.agentName });
+    return void 0;
+  };
+  const afterAgentCallback = (context) => {
+    hooks.close(runKey(context));
+    return void 0;
+  };
+  const beforeToolCallback = ({ tool, args, context }) => {
+    const state = stateOf(context);
+    if (!state) return void 0;
+    const key = context.functionCallId ?? `${tool.name}:${context.invocationId}`;
+    hooks.toolStart(state.bridge.session, key, tool.name, args, { frameKey: runKey(context), callId: context.functionCallId ?? null });
+    const played = hooks.replayed(state.bridge.session, tool.name, args, tool.execute, runKey(context));
+    if (played === null) return void 0;
+    const answer = played.recorded && isRecord(played.value) ? played.value : {};
+    hooks.toolEnd(key, answer);
+    return answer;
+  };
+  const afterToolCallback = ({ tool, context, response }) => {
+    hooks.toolEnd(context.functionCallId ?? `${tool.name}:${context.invocationId}`, response);
+    return void 0;
+  };
+  return { beforeModelCallback, afterModelCallback, beforeAgentCallback, afterAgentCallback, beforeToolCallback, afterToolCallback, tools };
+}
+function adkUsage(response, model) {
+  const usage = response.usageMetadata;
+  const prompt = count(usage?.promptTokenCount);
+  const name = (response.modelVersion ?? model).replace(/^models\//, "");
+  if (prompt === null || !name) return null;
+  const cached = count(usage?.cachedContentTokenCount) ?? 0;
+  return { provider: providerOf(name), model: name, prompt_tokens: Math.max(prompt, cached), cached_tokens: cached, cache_write_tokens: 0 };
+}
+var NiadraTool = class extends BaseTool {
+  constructor(definition, stateOf) {
+    super({ name: definition.name, description: definition.description });
+    this.definition = definition;
+    this.stateOf = stateOf;
+  }
+  definition;
+  stateOf;
+  _getDeclaration() {
+    return { name: this.definition.name, description: this.definition.description, parametersJsonSchema: this.definition.parameters };
+  }
+  async runAsync({ args, toolContext }) {
+    const state = this.stateOf(toolContext);
+    const spec = state?.bridge.tools().find((candidate) => candidate.name === this.name);
+    if (!spec) return { error: "unavailable", detail: "customer history is unavailable right now" };
+    const text = await spec.execute(args);
+    try {
+      return JSON.parse(text);
+    } catch {
+      return { result: text };
+    }
+  }
+};
+function newState(session, options) {
+  return { bridge: new Bridge(session, options.verify, options.agentMemory), seen: /* @__PURE__ */ new Set(), model: "" };
+}
+function textOfParts(parts, separator = "\n") {
+  if (!Array.isArray(parts)) return "";
+  return parts.map((part) => isRecord(part) && typeof part.text === "string" && part.thought !== true ? part.text : "").filter(Boolean).join(separator);
+}
+
+export { adkUsage, attestationProof, niadraAdk };
+//# sourceMappingURL=google-adk.js.map
+//# sourceMappingURL=google-adk.js.map