@letta-ai/letta-agent-sdk 0.3.2 → 0.3.3

package/src/stream-events.ts

@@ -0,0 +1,88 @@
+import type { SDKStreamEventPayload } from "./types.js";
+
+export type StreamTextKind = "assistant" | "reasoning";
+
+export interface StreamTextDelta {
+  kind: StreamTextKind;
+  text: string;
+}
+
+function extractTextFromContent(content: unknown): string | null {
+  if (typeof content === "string") {
+    return content;
+  }
+
+  if (Array.isArray(content)) {
+    const pieces: string[] = [];
+    for (const part of content) {
+      if (typeof part === "string") {
+        pieces.push(part);
+        continue;
+      }
+      if (!part || typeof part !== "object") {
+        continue;
+      }
+      const rec = part as Record<string, unknown>;
+      if (typeof rec.text === "string") {
+        pieces.push(rec.text);
+      }
+    }
+    const joined = pieces.join("");
+    return joined.length > 0 ? joined : null;
+  }
+
+  if (content && typeof content === "object") {
+    const rec = content as Record<string, unknown>;
+    if (typeof rec.text === "string") {
+      return rec.text;
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Extract appendable assistant/reasoning text from a stream_event payload.
+ *
+ * Supports both shapes currently emitted by headless mode:
+ * 1) content_block style: { type, delta: { text|reasoning } }
+ * 2) message chunk style: { message_type: "assistant_message"|"reasoning_message", ... }
+ */
+export function extractStreamTextDelta(event: SDKStreamEventPayload): StreamTextDelta | null {
+  if (!event || typeof event !== "object") {
+    return null;
+  }
+
+  const rec = event as Record<string, unknown>;
+
+  const maybeDelta = rec.delta;
+  if (maybeDelta && typeof maybeDelta === "object") {
+    const delta = maybeDelta as Record<string, unknown>;
+
+    if (typeof delta.reasoning === "string" && delta.reasoning.length > 0) {
+      return { kind: "reasoning", text: delta.reasoning };
+    }
+
+    if (typeof delta.text === "string" && delta.text.length > 0) {
+      return { kind: "assistant", text: delta.text };
+    }
+  }
+
+  const messageType = rec.message_type;
+  if (messageType === "reasoning_message") {
+    const reasoningText =
+      typeof rec.reasoning === "string" ? rec.reasoning : extractTextFromContent(rec.content);
+    if (reasoningText && reasoningText.length > 0) {
+      return { kind: "reasoning", text: reasoningText };
+    }
+  }
+
+  if (messageType === "assistant_message") {
+    const assistantText = extractTextFromContent(rec.content);
+    if (assistantText && assistantText.length > 0) {
+      return { kind: "assistant", text: assistantText };
+    }
+  }
+
+  return null;
+}

package/src/tool-helpers.ts

@@ -0,0 +1,147 @@
+/**
+ * Tool Helpers
+ * 
+ * Helper functions for creating tool results and parsing parameters.
+ * Matches the API from pi-coding-agent.
+ */
+
+import type { AgentToolResult } from "./types.js";
+
+/**
+ * Create a JSON tool result
+ */
+export function jsonResult(payload: unknown): AgentToolResult<unknown> {
+  return {
+    content: [
+      {
+        type: "text",
+        text: JSON.stringify(payload, null, 2),
+      },
+    ],
+    details: payload,
+  };
+}
+
+/**
+ * Options for reading string parameters
+ */
+export interface StringParamOptions {
+  required?: boolean;
+  trim?: boolean;
+  label?: string;
+  allowEmpty?: boolean;
+}
+
+/**
+ * Read a string parameter from tool args
+ */
+export function readStringParam(
+  params: Record<string, unknown>,
+  key: string,
+  options?: StringParamOptions & { required: true },
+): string;
+export function readStringParam(
+  params: Record<string, unknown>,
+  key: string,
+  options?: StringParamOptions,
+): string | undefined;
+export function readStringParam(
+  params: Record<string, unknown>,
+  key: string,
+  options: StringParamOptions = {},
+): string | undefined {
+  const { required = false, trim = true, label = key, allowEmpty = false } = options;
+  const raw = params[key];
+  if (typeof raw !== "string") {
+    if (required) throw new Error(`${label} required`);
+    return undefined;
+  }
+  const value = trim ? raw.trim() : raw;
+  if (!value && !allowEmpty) {
+    if (required) throw new Error(`${label} required`);
+    return undefined;
+  }
+  return value;
+}
+
+/**
+ * Read a number parameter from tool args
+ */
+export function readNumberParam(
+  params: Record<string, unknown>,
+  key: string,
+  options: { required?: boolean; label?: string; integer?: boolean } = {},
+): number | undefined {
+  const { required = false, label = key, integer = false } = options;
+  const raw = params[key];
+  let value: number | undefined;
+  if (typeof raw === "number" && Number.isFinite(raw)) {
+    value = raw;
+  } else if (typeof raw === "string") {
+    const trimmed = raw.trim();
+    if (trimmed) {
+      const parsed = Number.parseFloat(trimmed);
+      if (Number.isFinite(parsed)) value = parsed;
+    }
+  }
+  if (value === undefined) {
+    if (required) throw new Error(`${label} required`);
+    return undefined;
+  }
+  return integer ? Math.trunc(value) : value;
+}
+
+/**
+ * Read a boolean parameter from tool args
+ */
+export function readBooleanParam(
+  params: Record<string, unknown>,
+  key: string,
+  options: { required?: boolean; label?: string } = {},
+): boolean | undefined {
+  const { required = false, label = key } = options;
+  const raw = params[key];
+  if (typeof raw === "boolean") {
+    return raw;
+  }
+  if (typeof raw === "string") {
+    const lower = raw.toLowerCase().trim();
+    if (lower === "true" || lower === "1" || lower === "yes") return true;
+    if (lower === "false" || lower === "0" || lower === "no") return false;
+  }
+  if (required) throw new Error(`${label} required`);
+  return undefined;
+}
+
+/**
+ * Read a string array parameter from tool args
+ */
+export function readStringArrayParam(
+  params: Record<string, unknown>,
+  key: string,
+  options: StringParamOptions = {},
+): string[] | undefined {
+  const { required = false, label = key } = options;
+  const raw = params[key];
+  if (Array.isArray(raw)) {
+    const values = raw
+      .filter((entry): entry is string => typeof entry === "string")
+      .map((entry) => entry.trim())
+      .filter(Boolean);
+    if (values.length === 0) {
+      if (required) throw new Error(`${label} required`);
+      return undefined;
+    }
+    return values;
+  }
+  if (typeof raw === "string") {
+    const value = raw.trim();
+    if (!value) {
+      if (required) throw new Error(`${label} required`);
+      return undefined;
+    }
+    return [value];
+  }
+  if (required) throw new Error(`${label} required`);
+  return undefined;
+}