@niadra/sdk 0.1.1 → 0.9.0

package/dist/cloudflare-agents.cjs

@@ -0,0 +1,626 @@
+'use strict';
+
+var ai = require('ai');
+
+// src/integrations/ai-sdk.ts
+
+// 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", ageMs: null, 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/prompt.ts
+function injectPrompt(prompt, read) {
+  const injected = [...prompt];
+  if (read.suffix) {
+    const last = lastUserIndex(injected);
+    const message = injected[last];
+    if (isRecord(message) && Array.isArray(message.content)) {
+      injected[last] = { ...message, content: [...message.content, { type: "text", text: read.suffix }] };
+    }
+  }
+  if (read.prefix) {
+    let position = 0;
+    while (position < injected.length && roleOf(injected[position]) === "system") position++;
+    injected.splice(position, 0, { role: "system", content: read.prefix });
+  }
+  return injected;
+}
+function recordNewest(bridge, seen, prompt) {
+  const index = lastUserIndex(prompt);
+  if (index < 0) return;
+  const message = prompt[index];
+  const text = isRecord(message) ? textParts(message.content) : "";
+  const key = `${String(index)}:${text}`;
+  if (!text || seen.has(key)) return;
+  seen.add(key);
+  bridge.customer(text);
+}
+function textParts(content) {
+  if (typeof content === "string") return content;
+  if (!Array.isArray(content)) return "";
+  return content.map((part) => isRecord(part) && part.type === "text" && typeof part.text === "string" ? part.text : "").filter(Boolean).join("\n");
+}
+function lastUserIndex(prompt) {
+  for (let index = prompt.length - 1; index >= 0; index--) if (roleOf(prompt[index]) === "user") return index;
+  return -1;
+}
+function roleOf(message) {
+  return isRecord(message) && typeof message.role === "string" ? message.role : "";
+}
+
+// src/integrations/ai-sdk.ts
+function niadraMiddleware(session, options = {}) {
+  const states = /* @__PURE__ */ new WeakMap();
+  const hooks = new TurnHooks("ai-sdk", true);
+  const modelCall = (usage, model, modelId) => {
+    const current = resolveSession(session);
+    if (!current) return;
+    const name = typeof modelId === "string" && modelId ? modelId : model.modelId;
+    const reported = aiSdkUsage(usage, model, modelId);
+    const out = isRecord(usage) ? count(usage.outputTokens) ?? (isRecord(usage.outputTokens) ? count(usage.outputTokens.total) : null) : null;
+    hooks.model(current, name, reported ? { in: reported.prompt_tokens, out, cached: reported.cached_tokens ?? 0 } : {});
+  };
+  const stateOf = () => {
+    const current = resolveSession(session);
+    if (!current) return null;
+    let state = states.get(current);
+    if (!state) {
+      state = { bridge: new Bridge(current, options.verify, options.agentMemory), seen: /* @__PURE__ */ new Set() };
+      states.set(current, state);
+    }
+    return state;
+  };
+  return {
+    specificationVersion: "v3",
+    async transformParams({ params }) {
+      const state = stateOf();
+      if (!state || !Array.isArray(params.prompt)) return params;
+      try {
+        const prompt = params.prompt;
+        if (options.recordCustomer ?? true) recordNewest(state.bridge, state.seen, prompt);
+        const read = await state.bridge.read();
+        state.bridge.injected(read.context);
+        return { ...params, prompt: injectPrompt(prompt, read) };
+      } catch (error) {
+        state.bridge.logger.warn(`could not inject context (${errorName(error)})`);
+        return params;
+      }
+    },
+    async wrapGenerate({ doGenerate, model }) {
+      const result = await doGenerate();
+      if (isRecord(result)) modelCall(result.usage, model, isRecord(result.response) ? result.response.modelId : void 0);
+      if (options.recordAgent ?? true) {
+        const state = stateOf();
+        if (state) {
+          try {
+            const content = isRecord(result) && Array.isArray(result.content) ? result.content : [];
+            const text = content.map((part) => isRecord(part) && part.type === "text" && typeof part.text === "string" ? part.text : "").join("");
+            const response = isRecord(result) && isRecord(result.response) ? result.response : {};
+            record(state, text, isRecord(result) ? result.usage : void 0, model, response.modelId);
+          } catch (error) {
+            state.bridge.logger.warn(`could not capture the model's answer (${errorName(error)})`);
+          }
+        }
+      }
+      return result;
+    },
+    async wrapStream({ doStream, model }) {
+      const result = await doStream();
+      const state = options.recordAgent ?? true ? stateOf() : null;
+      if (!state || !isRecord(result) || !(result.stream instanceof ReadableStream)) return result;
+      const parts = [];
+      let usage;
+      let modelId;
+      const capture = new TransformStream({
+        transform(chunk, controller) {
+          if (isRecord(chunk)) {
+            if (chunk.type === "text-delta") parts.push(typeof chunk.delta === "string" ? chunk.delta : typeof chunk.textDelta === "string" ? chunk.textDelta : "");
+            else if (chunk.type === "finish") usage = chunk.usage;
+            else if (chunk.type === "response-metadata") modelId = chunk.modelId;
+          }
+          controller.enqueue(chunk);
+        },
+        flush() {
+          try {
+            modelCall(usage, model, modelId);
+            record(state, parts.join(""), usage, model, modelId);
+          } catch (error) {
+            state.bridge.logger.warn(`could not capture the model's answer (${errorName(error)})`);
+          }
+        }
+      });
+      return { ...result, stream: result.stream.pipeThrough(capture) };
+    }
+  };
+}
+function niadraTools(session, options = {}) {
+  const tools = {};
+  for (const spec of new Bridge(session, void 0, options.agentMemory).tools()) {
+    tools[spec.name] = ai.tool({
+      description: spec.description,
+      inputSchema: ai.jsonSchema(spec.parameters),
+      execute: async (input) => parsed(await spec.execute(input))
+    });
+  }
+  return tools;
+}
+function aiSdkUsage(usage, model, modelId) {
+  if (!isRecord(usage)) return null;
+  const name = typeof modelId === "string" && modelId ? modelId : model.modelId;
+  const provider = model.provider?.split(".")[0]?.toLowerCase();
+  if (!name || !provider) return null;
+  let prompt;
+  let cached;
+  let written;
+  if (isRecord(usage.inputTokens)) {
+    const input = usage.inputTokens;
+    cached = count(input.cacheRead) ?? 0;
+    written = count(input.cacheWrite) ?? 0;
+    prompt = count(input.total) ?? (count(input.noCache) === null ? null : (count(input.noCache) ?? 0) + cached + written);
+  } else {
+    prompt = count(usage.inputTokens);
+    cached = count(usage.cachedInputTokens) ?? 0;
+    written = 0;
+  }
+  if (prompt === null) return null;
+  return { provider, model: name, prompt_tokens: Math.max(prompt, cached + written), cached_tokens: cached, cache_write_tokens: written };
+}
+function record(state, text, usage, model, modelId) {
+  const reported = aiSdkUsage(usage, model, modelId);
+  state.bridge.agent(text, reported ? { usage: reported } : {});
+}
+function parsed(text) {
+  try {
+    return JSON.parse(text);
+  } catch {
+    return text;
+  }
+}
+
+// src/integrations/cloudflare-agents.ts
+var helpers = /* @__PURE__ */ new WeakMap();
+function niadraAgent(agent, options) {
+  const existing = helpers.get(agent);
+  if (existing) return existing;
+  const helper = build(agent, options);
+  helpers.set(agent, helper);
+  return helper;
+}
+function build(agent, options) {
+  const logger = options.niadra.logger;
+  const session = options.session ?? open(agent, options);
+  const waitUntil = options.waitUntil ?? waitUntilOf(agent);
+  const flush = () => {
+    try {
+      const sending = options.niadra.flush().catch((error) => {
+        logger.warn(`could not send to Niadra (${errorName(error)})`);
+      });
+      waitUntil?.(sending);
+    } catch (error) {
+      logger.warn(`could not schedule the flush (${errorName(error)})`);
+    }
+  };
+  const base = niadraMiddleware(session ?? (() => null), {
+    ...options.verify === void 0 ? {} : { verify: options.verify },
+    ...options.recordCustomer === void 0 ? {} : { recordCustomer: options.recordCustomer },
+    ...options.recordAgent === void 0 ? {} : { recordAgent: options.recordAgent },
+    ...options.agentMemory === void 0 ? {} : { agentMemory: options.agentMemory }
+  });
+  const middleware = {
+    specificationVersion: base.specificationVersion,
+    transformParams: (call) => base.transformParams(call),
+    async wrapGenerate(call) {
+      const result = await base.wrapGenerate(call);
+      flush();
+      return result;
+    },
+    async wrapStream(call) {
+      const result = await base.wrapStream(call);
+      if (!isRecord(result) || !(result.stream instanceof ReadableStream)) return result;
+      const after = new TransformStream({ flush });
+      return { ...result, stream: result.stream.pipeThrough(after) };
+    }
+  };
+  const bridge = session ? new Bridge(session, options.verify, options.agentMemory) : null;
+  const seen = /* @__PURE__ */ new Set();
+  return {
+    session,
+    middleware,
+    tools: () => session ? niadraTools(session, options.agentMemory === void 0 ? {} : { agentMemory: options.agentMemory }) : {},
+    async prepare(messages) {
+      if (!bridge) return [...messages];
+      try {
+        if (options.recordCustomer ?? true) {
+          const index = lastUser(messages);
+          const text = index >= 0 ? textOf(messages[index]?.content) : "";
+          const key = `${String(index)}:${text}`;
+          if (text && !seen.has(key)) {
+            seen.add(key);
+            bridge.customer(text);
+          }
+        }
+        const read = await bridge.read();
+        bridge.injected(read.context);
+        return inject(messages, read.prefix, read.suffix);
+      } catch (error) {
+        logger.warn(`could not inject context (${errorName(error)})`);
+        return [...messages];
+      }
+    },
+    record(text, turn = {}) {
+      if (!bridge || !(options.recordAgent ?? true)) return;
+      bridge.agent(text, turn);
+      flush();
+    },
+    flush,
+    async end() {
+      if (bridge) await bridge.end();
+      flush();
+    }
+  };
+}
+function open(agent, options) {
+  let subject;
+  try {
+    subject = typeof options.subject === "function" ? options.subject(agent) : options.subject;
+  } catch (error) {
+    options.niadra.logger.warn(`could not find the customer (${errorName(error)})`);
+    return null;
+  }
+  if (!subject) return null;
+  return options.niadra.conversation({ subject, channel: options.channel ?? "web_chat", conversation_id: options.conversationId ?? agent.name });
+}
+function workersAiUsage(answer, model) {
+  const usage = isRecord(answer) && isRecord(answer.usage) ? answer.usage : null;
+  const prompt = usage ? count(usage.prompt_tokens) : null;
+  const name = model.replace(/^@/, "");
+  if (prompt === null || !name) return null;
+  const details = usage && isRecord(usage.prompt_tokens_details) ? usage.prompt_tokens_details : {};
+  const cached = Math.min(count(details.cached_tokens) ?? 0, prompt);
+  return { provider: "workers-ai", model: name, prompt_tokens: prompt, cached_tokens: cached, cache_write_tokens: 0 };
+}
+function waitUntilOf(agent) {
+  const ctx = agent.ctx;
+  if (!isRecord(ctx) || typeof ctx.waitUntil !== "function") return void 0;
+  const waitUntil = ctx.waitUntil;
+  return (promise) => {
+    waitUntil.call(ctx, promise);
+  };
+}
+function lastUser(messages) {
+  for (let index = messages.length - 1; index >= 0; index--) if (messages[index]?.role === "user") return index;
+  return -1;
+}
+function inject(messages, prefix, suffix) {
+  const result = [...messages];
+  const index = lastUser(result);
+  const last = result[index];
+  if (suffix && last) {
+    const content = last.content;
+    const next = typeof content === "string" ? `${content}
+
+${suffix}` : Array.isArray(content) ? [...content, { type: "text", text: suffix }] : content;
+    result[index] = { ...last, content: next };
+  }
+  if (prefix) {
+    let position = 0;
+    while (position < result.length && result[position]?.role === "system") position++;
+    result.splice(position, 0, { role: "system", content: prefix });
+  }
+  return result;
+}
+
+exports.attestationProof = attestationProof;
+exports.niadraAgent = niadraAgent;
+exports.workersAiUsage = workersAiUsage;
+//# sourceMappingURL=cloudflare-agents.cjs.map
+//# sourceMappingURL=cloudflare-agents.cjs.map