@softactivate/adk 1.1.0

package/dist/esm/sessions/in_memory_session_service.js

@@ -0,0 +1,184 @@
+import {createRequire as topLevelCreateRequire} from 'module';
+const require = topLevelCreateRequire(import.meta.url);
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { cloneDeep } from "lodash-es";
+import { randomUUID } from "../utils/env_aware_utils.js";
+import { logger } from "../utils/logger.js";
+import {
+  BaseSessionService,
+  mergeStates
+} from "./base_session_service.js";
+import { createSession } from "./session.js";
+import { State } from "./state.js";
+function isInMemoryConnectionString(uri) {
+  return uri === "memory://";
+}
+class InMemorySessionService extends BaseSessionService {
+  constructor() {
+    super(...arguments);
+    /**
+     * A map from app name to a map from user ID to a map from session ID to
+     * session.
+     */
+    this.sessions = {};
+    /**
+     * A map from app name to a map from user ID to a map from key to the value.
+     */
+    this.userState = {};
+    /**
+     * A map from app name to a map from key to the value.
+     */
+    this.appState = {};
+  }
+  async createSession({
+    appName,
+    userId,
+    state,
+    sessionId
+  }) {
+    var _a;
+    const session = createSession({
+      id: sessionId || randomUUID(),
+      appName,
+      userId,
+      state,
+      events: [],
+      lastUpdateTime: Date.now()
+    });
+    if (!this.sessions[appName]) {
+      this.sessions[appName] = {};
+    }
+    if (!this.sessions[appName][userId]) {
+      this.sessions[appName][userId] = {};
+    }
+    this.sessions[appName][userId][session.id] = session;
+    const copiedSession = cloneDeep(session);
+    copiedSession.state = mergeStates(
+      this.appState[appName],
+      (_a = this.userState[appName]) == null ? void 0 : _a[userId],
+      copiedSession.state
+    );
+    return copiedSession;
+  }
+  async getSession({
+    appName,
+    userId,
+    sessionId,
+    config
+  }) {
+    var _a;
+    if (!this.sessions[appName] || !this.sessions[appName][userId] || !this.sessions[appName][userId][sessionId]) {
+      return Promise.resolve(void 0);
+    }
+    const session = this.sessions[appName][userId][sessionId];
+    const copiedSession = cloneDeep(session);
+    if (config) {
+      if (config.numRecentEvents) {
+        copiedSession.events = copiedSession.events.slice(
+          -config.numRecentEvents
+        );
+      }
+      if (config.afterTimestamp) {
+        let i = copiedSession.events.length - 1;
+        while (i >= 0) {
+          if (copiedSession.events[i].timestamp < config.afterTimestamp) {
+            break;
+          }
+          i--;
+        }
+        if (i >= 0) {
+          copiedSession.events = copiedSession.events.slice(i + 1);
+        }
+      }
+    }
+    copiedSession.state = mergeStates(
+      this.appState[appName],
+      (_a = this.userState[appName]) == null ? void 0 : _a[userId],
+      copiedSession.state
+    );
+    return copiedSession;
+  }
+  listSessions({
+    appName,
+    userId
+  }) {
+    if (!this.sessions[appName] || !this.sessions[appName][userId]) {
+      return Promise.resolve({ sessions: [] });
+    }
+    const sessionsWithoutEvents = [];
+    for (const session of Object.values(this.sessions[appName][userId])) {
+      sessionsWithoutEvents.push(
+        createSession({
+          id: session.id,
+          appName: session.appName,
+          userId: session.userId,
+          state: {},
+          events: [],
+          lastUpdateTime: session.lastUpdateTime
+        })
+      );
+    }
+    return Promise.resolve({ sessions: sessionsWithoutEvents });
+  }
+  async deleteSession({
+    appName,
+    userId,
+    sessionId
+  }) {
+    const session = await this.getSession({ appName, userId, sessionId });
+    if (!session) {
+      return;
+    }
+    delete this.sessions[appName][userId][sessionId];
+  }
+  async appendEvent({
+    session,
+    event
+  }) {
+    await super.appendEvent({ session, event });
+    session.lastUpdateTime = event.timestamp;
+    const appName = session.appName;
+    const userId = session.userId;
+    const sessionId = session.id;
+    const warning = (message) => {
+      logger.warn(`Failed to append event to session ${sessionId}: ${message}`);
+    };
+    if (!this.sessions[appName]) {
+      warning(`appName ${appName} not in sessions`);
+      return event;
+    }
+    if (!this.sessions[appName][userId]) {
+      warning(`userId ${userId} not in sessions[appName]`);
+      return event;
+    }
+    if (!this.sessions[appName][userId][sessionId]) {
+      warning(`sessionId ${sessionId} not in sessions[appName][userId]`);
+      return event;
+    }
+    if (event.actions && event.actions.stateDelta) {
+      for (const key of Object.keys(event.actions.stateDelta)) {
+        if (key.startsWith(State.APP_PREFIX)) {
+          this.appState[appName] = this.appState[appName] || {};
+          this.appState[appName][key.replace(State.APP_PREFIX, "")] = event.actions.stateDelta[key];
+        }
+        if (key.startsWith(State.USER_PREFIX)) {
+          this.userState[appName] = this.userState[appName] || {};
+          this.userState[appName][userId] = this.userState[appName][userId] || {};
+          this.userState[appName][userId][key.replace(State.USER_PREFIX, "")] = event.actions.stateDelta[key];
+        }
+      }
+    }
+    const storageSession = this.sessions[appName][userId][sessionId];
+    await super.appendEvent({ session: storageSession, event });
+    storageSession.lastUpdateTime = event.timestamp;
+    return event;
+  }
+}
+export {
+  InMemorySessionService,
+  isInMemoryConnectionString
+};

package/dist/esm/sessions/registry.js

@@ -0,0 +1,27 @@
+import {createRequire as topLevelCreateRequire} from 'module';
+const require = topLevelCreateRequire(import.meta.url);
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import {
+  DatabaseSessionService,
+  isDatabaseConnectionString
+} from "./database_session_service.js";
+import {
+  InMemorySessionService,
+  isInMemoryConnectionString
+} from "./in_memory_session_service.js";
+function getSessionServiceFromUri(uri) {
+  if (isInMemoryConnectionString(uri)) {
+    return new InMemorySessionService();
+  }
+  if (isDatabaseConnectionString(uri)) {
+    return new DatabaseSessionService(uri);
+  }
+  throw new Error(`Unsupported session service URI: ${uri}`);
+}
+export {
+  getSessionServiceFromUri
+};

package/dist/esm/sessions/session.js

@@ -0,0 +1,20 @@
+import {createRequire as topLevelCreateRequire} from 'module';
+const require = topLevelCreateRequire(import.meta.url);
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+function createSession(params) {
+  return {
+    id: params.id,
+    appName: params.appName,
+    userId: params.userId || "",
+    state: params.state || {},
+    events: params.events || [],
+    lastUpdateTime: params.lastUpdateTime || 0
+  };
+}
+export {
+  createSession
+};

package/dist/esm/sessions/state.js

@@ -0,0 +1,73 @@
+import {createRequire as topLevelCreateRequire} from 'module';
+const require = topLevelCreateRequire(import.meta.url);
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+class State {
+  constructor(value = {}, delta = {}) {
+    this.value = value;
+    this.delta = delta;
+  }
+  /**
+   * Returns the value of the state dict for the given key.
+   *
+   * @param key The key to get the value for.
+   * @param defaultValue The default value to return if the key is not found.
+   * @return The value of the state for the given key, or the default value if
+   *     not found.
+   */
+  get(key, defaultValue) {
+    if (key in this.delta) {
+      return this.delta[key];
+    }
+    if (key in this.value) {
+      return this.value[key];
+    }
+    return defaultValue;
+  }
+  /**
+   * Sets the value of the state dict for the given key.
+   *
+   * @param key The key to set the value for.
+   * @param value The value to set.
+   */
+  set(key, value) {
+    this.value[key] = value;
+    this.delta[key] = value;
+  }
+  /**
+   * Whether the state has pending delta.
+   */
+  has(key) {
+    return key in this.value || key in this.delta;
+  }
+  /**
+   * Whether the state has pending delta.
+   */
+  hasDelta() {
+    return Object.keys(this.delta).length > 0;
+  }
+  /**
+   * Updates the state dict with the given delta.
+   *
+   * @param delta The delta to update the state with.
+   */
+  update(delta) {
+    Object.assign(this.delta, delta);
+    Object.assign(this.value, delta);
+  }
+  /**
+   * Returns the state as a plain JSON object.
+   */
+  toRecord() {
+    return { ...this.value, ...this.delta };
+  }
+}
+State.APP_PREFIX = "app:";
+State.USER_PREFIX = "user:";
+State.TEMP_PREFIX = "temp:";
+export {
+  State
+};

package/dist/esm/skills/loader.js

@@ -0,0 +1,244 @@
+import {createRequire as topLevelCreateRequire} from 'module';
+const require = topLevelCreateRequire(import.meta.url);
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import yaml from "js-yaml";
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import { logger } from "../utils/logger.js";
+import {
+  FrontmatterSchema
+} from "./skill.js";
+const ALLOWED_FRONTMATTER_KEYS = /* @__PURE__ */ new Set([
+  "name",
+  "description",
+  "license",
+  "allowed-tools",
+  "metadata",
+  "compatibility"
+]);
+const IGNORED_DIRECTORIES = /* @__PURE__ */ new Set([
+  "__pycache__",
+  ".pytest_cache",
+  ".mypy_cache",
+  ".ruff_cache",
+  "node_modules",
+  "coverage",
+  "venv",
+  ".venv",
+  "env",
+  ".env",
+  ".git",
+  ".vscode",
+  ".idea"
+]);
+const IGNORED_EXTENSIONS = /* @__PURE__ */ new Set([
+  ".pyc",
+  ".pyo",
+  ".pyd",
+  ".tsbuildinfo",
+  ".DS_Store"
+]);
+async function loadDir(directoryPath) {
+  const files = {};
+  async function walk(dir) {
+    const entries = await fs.readdir(dir, { withFileTypes: true });
+    for (const entry of entries) {
+      const fullPath = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        if (IGNORED_DIRECTORIES.has(entry.name)) {
+          continue;
+        }
+        await walk(fullPath);
+      } else if (entry.isFile()) {
+        const relativePath = path.relative(directoryPath, fullPath);
+        if (IGNORED_EXTENSIONS.has(path.extname(entry.name))) {
+          continue;
+        }
+        const fileData = await fs.readFile(fullPath);
+        try {
+          files[relativePath] = fileData.toString("utf-8");
+        } catch (_e) {
+          files[relativePath] = fileData;
+        }
+      }
+    }
+  }
+  try {
+    const stats = await fs.stat(directoryPath);
+    if (stats.isDirectory()) {
+      await walk(directoryPath);
+    }
+  } catch (e) {
+    logger.warn(
+      `Failed to load directory '${directoryPath}': ${e.message}`
+    );
+  }
+  return files;
+}
+function parseSkillMdContent(content) {
+  if (!content.startsWith("---")) {
+    throw new Error("SKILL.md must start with YAML frontmatter (---)");
+  }
+  const parts = content.split("---", 3);
+  if (parts.length < 3) {
+    throw new Error("SKILL.md frontmatter not properly closed with ---");
+  }
+  const frontmatterStr = parts[1];
+  const body = parts[2].trim();
+  try {
+    const parsed = yaml.load(frontmatterStr);
+    if (typeof parsed !== "object" || parsed === null) {
+      throw new Error("SKILL.md frontmatter must be a YAML mapping");
+    }
+    const frontmatter = FrontmatterSchema.parse(parsed);
+    return { frontmatter, body };
+  } catch (e) {
+    throw new Error(`Invalid YAML in frontmatter: ${e.message}`);
+  }
+}
+async function loadSkillFromDir(skillDir) {
+  const resolvedDir = path.resolve(skillDir);
+  const skill = await loadSkillFile(skillDir);
+  const referencesDir = path.join(resolvedDir, "references");
+  const assetsDir = path.join(resolvedDir, "assets");
+  const scriptsDir = path.join(resolvedDir, "scripts");
+  const [references, assets, rawScripts] = await Promise.all([
+    loadDir(referencesDir),
+    loadDir(assetsDir),
+    loadDir(scriptsDir)
+  ]);
+  const scripts = {};
+  for (const [name, src] of Object.entries(rawScripts)) {
+    if (typeof src === "string") {
+      scripts[name] = { src };
+    }
+  }
+  const resources = { references, assets, scripts };
+  return {
+    ...skill,
+    resources
+  };
+}
+async function validateSkillDir(skillDir) {
+  const problems = [];
+  const resolvedDir = path.resolve(skillDir);
+  let skill;
+  try {
+    skill = await loadSkillFile(resolvedDir);
+  } catch (e) {
+    return [e.message];
+  }
+  try {
+    const keys = Object.keys(skill.frontmatter);
+    const unknown = keys.filter((k) => !ALLOWED_FRONTMATTER_KEYS.has(k));
+    if (unknown.length > 0) {
+      problems.push(
+        `Unknown frontmatter fields: [${unknown.sort().join(", ")}]`
+      );
+    }
+    const dirName = path.basename(resolvedDir);
+    if (dirName !== skill.frontmatter.name) {
+      problems.push(
+        `Skill name '${skill.frontmatter.name}' does not match directory name '${dirName}'.`
+      );
+    }
+  } catch (e) {
+    problems.push(e.message);
+  }
+  return problems;
+}
+async function loadSkillFile(skillDir) {
+  const resolvedDir = path.resolve(skillDir);
+  let skillMdPath = "";
+  let content = "";
+  try {
+    const entries = await fs.readdir(resolvedDir, { withFileTypes: true });
+    for (const entry of entries) {
+      if (entry.isFile() && entry.name.toLowerCase() === "skill.md") {
+        const p = path.join(resolvedDir, entry.name);
+        try {
+          content = await fs.readFile(p, "utf-8");
+          skillMdPath = p;
+          break;
+        } catch (_e) {
+        }
+      }
+    }
+  } catch (e) {
+    logger.warn(
+      `Failed to load directory '${skillDir}': ${e.message}`
+    );
+  }
+  if (!skillMdPath) {
+    throw new Error(
+      `SKILL.md (or any case variation like skill.md) not found in '${skillDir}'.`
+    );
+  }
+  const { frontmatter: parsed, body } = parseSkillMdContent(content);
+  const frontmatter = FrontmatterSchema.parse(parsed);
+  const dirName = path.basename(resolvedDir);
+  if (dirName !== frontmatter.name) {
+    throw new Error(
+      `Skill name '${frontmatter.name}' does not match directory name '${dirName}'.`
+    );
+  }
+  return {
+    frontmatter,
+    instructions: body
+  };
+}
+async function loadAllSkillsInDir(skillsBasePath) {
+  const resolvedPath = path.resolve(skillsBasePath);
+  const skills = {};
+  async function scanDir(currentDir) {
+    let entries;
+    try {
+      entries = await fs.readdir(currentDir, { withFileTypes: true });
+    } catch (_e) {
+      return;
+    }
+    let isSkillDir = false;
+    if (currentDir !== resolvedPath) {
+      for (const entry of entries) {
+        if (entry.isFile() && entry.name.toLowerCase() === "skill.md") {
+          isSkillDir = true;
+          break;
+        }
+      }
+    }
+    if (isSkillDir) {
+      try {
+        const skill = await loadSkillFromDir(currentDir);
+        skills[skill.frontmatter.name] = skill;
+      } catch (e) {
+        logger.warn(`Skipping invalid skill in '${currentDir}':`, e);
+      }
+    } else {
+      for (const entry of entries) {
+        if (entry.isDirectory()) {
+          if (IGNORED_DIRECTORIES.has(entry.name)) {
+            continue;
+          }
+          await scanDir(path.join(currentDir, entry.name));
+        }
+      }
+    }
+  }
+  try {
+    await fs.readdir(resolvedPath);
+    await scanDir(resolvedPath);
+  } catch (e) {
+    logger.warn(`Skills base path '${skillsBasePath}' is not a directory.`, e);
+  }
+  return skills;
+}
+export {
+  loadAllSkillsInDir,
+  loadSkillFromDir,
+  parseSkillMdContent,
+  validateSkillDir
+};

package/dist/esm/skills/prompt.js

@@ -0,0 +1,30 @@
+import {createRequire as topLevelCreateRequire} from 'module';
+const require = topLevelCreateRequire(import.meta.url);
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+function escapeHtml(unsafe) {
+  return unsafe.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&#039;");
+}
+function formatSkillsAsXml(skills) {
+  if (!skills || skills.length === 0) {
+    return "<available_skills>\n</available_skills>";
+  }
+  const lines = ["<available_skills>"];
+  for (const item of skills) {
+    const frontmatter = "frontmatter" in item ? item.frontmatter : item;
+    lines.push("  <skill>");
+    lines.push(`    <name>${escapeHtml(frontmatter.name)}</name>`);
+    lines.push(
+      `    <description>${escapeHtml(frontmatter.description)}</description>`
+    );
+    lines.push("  </skill>");
+  }
+  lines.push("</available_skills>");
+  return lines.join("\n");
+}
+export {
+  formatSkillsAsXml
+};

package/dist/esm/skills/skill.js

@@ -0,0 +1,49 @@
+import {createRequire as topLevelCreateRequire} from 'module';
+const require = topLevelCreateRequire(import.meta.url);
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { z } from "zod";
+const SNAKE_OR_KEBAB_NAME_PATTERN = /^([a-z0-9]+(-[a-z0-9]+)*|[a-z0-9]+(_[a-z0-9]+)*)$/;
+const FrontmatterSchema = z.preprocess(
+  (data) => {
+    if (typeof data === "object" && data !== null) {
+      const obj = data;
+      if ("allowed-tools" in obj && !("allowedTools" in obj)) {
+        return {
+          ...obj,
+          allowedTools: obj["allowed-tools"]
+        };
+      }
+    }
+    return data;
+  },
+  z.object({
+    name: z.string().regex(SNAKE_OR_KEBAB_NAME_PATTERN, {
+      message: "name must be lowercase kebab-case (a-z, 0-9, hyphens) or snake_case (a-z, 0-9, underscores), with no leading, trailing, or consecutive delimiters. Mixing hyphens and underscores is not allowed."
+    }).max(64),
+    description: z.string().min(1).max(1024),
+    license: z.string().optional(),
+    compatibility: z.string().max(500).optional(),
+    "allowed-tools": z.string().optional(),
+    metadata: z.record(z.string(), z.any()).default({}).refine(
+      (data) => {
+        if ("adk_additional_tools" in data) {
+          return Array.isArray(data.adk_additional_tools) && data.adk_additional_tools.every(
+            (item) => typeof item === "string"
+          );
+        }
+        return true;
+      },
+      {
+        message: "adk_additional_tools must be a list of strings"
+      }
+    )
+  }).loose()
+);
+export {
+  FrontmatterSchema,
+  SNAKE_OR_KEBAB_NAME_PATTERN
+};

package/dist/esm/telemetry/google_cloud.js

@@ -0,0 +1,54 @@
+import {createRequire as topLevelCreateRequire} from 'module';
+const require = topLevelCreateRequire(import.meta.url);
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { MetricExporter } from "@google-cloud/opentelemetry-cloud-monitoring-exporter";
+import { TraceExporter } from "@google-cloud/opentelemetry-cloud-trace-exporter";
+import { gcpDetector } from "@opentelemetry/resource-detector-gcp";
+import { detectResources } from "@opentelemetry/resources";
+import { PeriodicExportingMetricReader } from "@opentelemetry/sdk-metrics";
+import { BatchSpanProcessor } from "@opentelemetry/sdk-trace-base";
+import { GoogleAuth } from "google-auth-library";
+import { logger } from "../utils/logger.js";
+const GCP_PROJECT_ERROR_MESSAGE = "Cannot determine GCP Project. OTel GCP Exporters cannot be set up. Please make sure to log into correct GCP Project.";
+async function getGcpProjectId() {
+  try {
+    const auth = new GoogleAuth();
+    const projectId = await auth.getProjectId();
+    return projectId || void 0;
+  } catch (_e) {
+    return void 0;
+  }
+}
+async function getGcpExporters(config = {}) {
+  const {
+    enableTracing = false,
+    enableMetrics = false
+    // enableCloudLogging = false,
+  } = config;
+  const projectId = await getGcpProjectId();
+  if (!projectId) {
+    logger.warn(GCP_PROJECT_ERROR_MESSAGE);
+    return {};
+  }
+  return {
+    spanProcessors: enableTracing ? [new BatchSpanProcessor(new TraceExporter({ projectId }))] : [],
+    metricReaders: enableMetrics ? [
+      new PeriodicExportingMetricReader({
+        exporter: new MetricExporter({ projectId }),
+        exportIntervalMillis: 5e3
+      })
+    ] : [],
+    logRecordProcessors: []
+  };
+}
+function getGcpResource() {
+  return detectResources({ detectors: [gcpDetector] });
+}
+export {
+  getGcpExporters,
+  getGcpResource
+};