@elizaos/app-core 2.0.0-alpha.10

package/src/actions/character.test.ts

@@ -0,0 +1,139 @@
+import { describe, expect, it } from "vitest";
+
+import type { CharacterData } from "../api/client";
+import { prepareDraftForSave } from "./character";
+
+describe("prepareDraftForSave", () => {
+  it("builds a strict payload and preserves message actions", () => {
+    const draft = {
+      name: "Sakuya",
+      username: "sakuya-clockwork",
+      system: "Act composed.",
+      bio: " first line \n\n second line ",
+      adjectives: ["precise", "", "calm"],
+      topics: ["time", "", "duty"],
+      postExamples: ["Mission report", ""],
+      style: {
+        all: ["Be exact"],
+        chat: [],
+        post: ["Stay brief"],
+      },
+      messageExamples: [
+        {
+          examples: [
+            {
+              name: "{{user1}}",
+              content: {
+                text: "status?",
+                legacy: "remove",
+              },
+            },
+            {
+              name: "Sakuya",
+              content: {
+                text: "On track.",
+                actions: ["REPORT_STATUS"],
+                debug: true,
+              },
+            },
+            {
+              name: "",
+              content: { text: "skip me" },
+            },
+            {
+              name: "Sakuya",
+              content: { text: "   " },
+            },
+          ],
+        },
+        { examples: [] },
+      ],
+      extraField: "drop me",
+    } as unknown as CharacterData;
+
+    expect(prepareDraftForSave(draft)).toEqual({
+      name: "Sakuya",
+      username: "sakuya-clockwork",
+      system: "Act composed.",
+      bio: ["first line", "second line"],
+      adjectives: ["precise", "calm"],
+      topics: ["time", "duty"],
+      postExamples: ["Mission report"],
+      style: {
+        all: ["Be exact"],
+        post: ["Stay brief"],
+      },
+      messageExamples: [
+        {
+          examples: [
+            {
+              name: "{{user1}}",
+              content: { text: "status?" },
+            },
+            {
+              name: "Sakuya",
+              content: {
+                text: "On track.",
+                actions: ["REPORT_STATUS"],
+              },
+            },
+          ],
+        },
+      ],
+    });
+  });
+
+  it("omits empty collections and invalid message examples", () => {
+    const draft = {
+      bio: " \n ",
+      adjectives: ["", " "],
+      postExamples: [" "],
+      style: {
+        all: [],
+        chat: [],
+        post: [],
+      },
+      messageExamples: [
+        {
+          examples: [
+            { name: "", content: { text: "missing speaker" } },
+            { name: "User", content: { text: "   " } },
+          ],
+        },
+      ],
+    } as CharacterData;
+
+    expect(prepareDraftForSave(draft)).toEqual({});
+  });
+
+  it("preserves array bios and populated style groups", () => {
+    const draft: CharacterData = {
+      name: "Reimu",
+      bio: ["Line one", "Line two"],
+      style: {
+        chat: ["Stay direct"],
+      },
+    };
+
+    expect(prepareDraftForSave(draft)).toEqual({
+      name: "Reimu",
+      username: "Reimu",
+      bio: ["Line one", "Line two"],
+      style: {
+        chat: ["Stay direct"],
+      },
+    });
+  });
+
+  it("falls back username to name when no username is provided", () => {
+    const draft: CharacterData = {
+      name: "Marisa",
+      username: "   ",
+    };
+
+    expect(prepareDraftForSave(draft)).toEqual({
+      name: "Marisa",
+      username: "Marisa",
+    });
+  });
+});

package/src/actions/character.ts

@@ -0,0 +1,152 @@
+/**
+ * Character action helpers — extracted from AppContext.
+ *
+ * Pure functions for character CRUD and draft management.
+ */
+
+import type { CharacterData, MiladyClient } from "../api/client";
+
+export interface CharacterActionContext {
+  client: MiladyClient;
+  setCharacterData: (data: CharacterData | null) => void;
+  setCharacterDraft: (
+    fn: CharacterData | ((prev: CharacterData) => CharacterData),
+  ) => void;
+  setCharacterLoading: (loading: boolean) => void;
+  setCharacterSaving: (saving: boolean) => void;
+  setCharacterSaveError: (error: string | null) => void;
+  setCharacterSaveSuccess: (message: string | null) => void;
+}
+
+export async function loadCharacter(
+  ctx: CharacterActionContext,
+): Promise<void> {
+  ctx.setCharacterLoading(true);
+  ctx.setCharacterSaveError(null);
+  ctx.setCharacterSaveSuccess(null);
+  try {
+    const { character } = await ctx.client.getCharacter();
+    ctx.setCharacterData(character);
+    ctx.setCharacterDraft({
+      name: character.name ?? "",
+      username: character.username ?? "",
+      bio: Array.isArray(character.bio)
+        ? character.bio.join("\n")
+        : (character.bio ?? ""),
+      system: character.system ?? "",
+      adjectives: character.adjectives ?? [],
+      topics: character.topics ?? [],
+      style: {
+        all: character.style?.all ?? [],
+        chat: character.style?.chat ?? [],
+        post: character.style?.post ?? [],
+      },
+      messageExamples: character.messageExamples ?? [],
+      postExamples: character.postExamples ?? [],
+    });
+  } catch {
+    ctx.setCharacterData(null);
+    ctx.setCharacterDraft({});
+  }
+  ctx.setCharacterLoading(false);
+}
+
+export function prepareDraftForSave(
+  draft: CharacterData,
+): Record<string, unknown> {
+  // Only pick fields the API schema accepts (.strict() rejects unknown keys)
+  const result: Record<string, unknown> = {};
+
+  if (draft.name?.trim()) {
+    result.name = draft.name.trim();
+  }
+
+  if (draft.username?.trim()) {
+    result.username = draft.username.trim();
+  } else if (typeof result.name === "string") {
+    result.username = result.name;
+  }
+  if (draft.system) result.system = draft.system;
+
+  if (typeof draft.bio === "string") {
+    const lines = draft.bio
+      .split("\n")
+      .map((l: string) => l.trim())
+      .filter((l: string) => l.length > 0);
+    if (lines.length > 0) result.bio = lines;
+  } else if (Array.isArray(draft.bio) && draft.bio.length > 0) {
+    result.bio = draft.bio;
+  }
+
+  const adjectives = (draft.adjectives ?? []).filter(
+    (s) => s.trim().length > 0,
+  );
+  if (adjectives.length > 0) result.adjectives = adjectives;
+
+  const topics = (draft.topics ?? []).filter((s) => s.trim().length > 0);
+  if (topics.length > 0) result.topics = topics;
+
+  const postExamples = (draft.postExamples ?? []).filter(
+    (s) => s.trim().length > 0,
+  );
+  if (postExamples.length > 0) result.postExamples = postExamples;
+
+  if (
+    Array.isArray(draft.messageExamples) &&
+    draft.messageExamples.length > 0
+  ) {
+    // Strip extra fields from content (schema is .strict() — only text + actions allowed)
+    const cleaned = draft.messageExamples
+      .map((group) => ({
+        examples: (group.examples ?? [])
+          .filter((msg) => msg.name?.trim() && msg.content?.text?.trim())
+          .map((msg) => ({
+            name: msg.name,
+            content: {
+              text: msg.content.text,
+              ...(msg.content.actions ? { actions: msg.content.actions } : {}),
+            },
+          })),
+      }))
+      .filter((group) => group.examples.length > 0);
+    if (cleaned.length > 0) result.messageExamples = cleaned;
+  }
+
+  if (draft.style) {
+    const style: Record<string, string[]> = {};
+    if (draft.style.all?.length) style.all = draft.style.all;
+    if (draft.style.chat?.length) style.chat = draft.style.chat;
+    if (draft.style.post?.length) style.post = draft.style.post;
+    if (Object.keys(style).length > 0) result.style = style;
+  }
+
+  return result;
+}
+
+export function parseMessageExamplesInput(value: string): Array<{
+  examples: Array<{ name: string; content: { text: string } }>;
+}> {
+  if (!value.trim()) return [];
+  const blocks = value.split(/\n\s*\n/).filter((b) => b.trim().length > 0);
+  return blocks.map((block) => {
+    const lines = block.split("\n").filter((l) => l.trim().length > 0);
+    const examples = lines.map((line) => {
+      const colonIdx = line.indexOf(":");
+      if (colonIdx > 0) {
+        return {
+          name: line.slice(0, colonIdx).trim(),
+          content: { text: line.slice(colonIdx + 1).trim() },
+        };
+      }
+      return { name: "User", content: { text: line.trim() } };
+    });
+    return { examples };
+  });
+}
+
+export function parseArrayInput(value: string): string[] {
+  return value
+    .split("\n")
+    .map((s) => s.trim())
+    .filter((s) => s.length > 0);
+}

package/src/actions/chat-helpers.ts

@@ -0,0 +1,100 @@
+/**
+ * Chat helpers — streaming delta computation, formatting, and common patterns.
+ *
+ * Extracted from AppContext to be reusable across providers.
+ */
+
+import {
+  computeStreamingDelta as computeStreamingDeltaInternal,
+  mergeStreamingText,
+} from "../utils/streaming-text";
+
+export { mergeStreamingText };
+
+/**
+ * Compute the streaming delta between the accumulated text and the new token.
+ * The SSE endpoint may emit the full text so far or just the delta — this
+ * function handles both by returning only the new characters.
+ */
+export function computeStreamingDelta(
+  accumulated: string,
+  token: string,
+): string {
+  return computeStreamingDeltaInternal(accumulated, token);
+}
+
+/**
+ * Determine whether the final stream response text should replace the
+ * accumulated text in the UI. This handles cases where the final text
+ * differs from what was streamed (e.g., post-processing on the server).
+ */
+export function shouldApplyFinalStreamText(
+  streamed: string,
+  final: string,
+): boolean {
+  if (!final) return false;
+  return final !== streamed;
+}
+
+/**
+ * Format a search result section with a label and bullet items.
+ */
+export function formatSearchBullet(label: string, items: string[]): string {
+  if (items.length === 0) return `**${label}**: (none)`;
+  return `**${label}**:\n${items.map((item) => `• ${item}`).join("\n")}`;
+}
+
+/**
+ * Parse slash command input into a command name and raw arguments.
+ */
+export function parseSlashCommandInput(
+  rawText: string,
+): { name: string; argsRaw: string } | null {
+  if (!rawText.startsWith("/")) return null;
+  const rest = rawText.slice(1);
+  const spaceIdx = rest.indexOf(" ");
+  if (spaceIdx < 0) {
+    return { name: rest.toLowerCase(), argsRaw: "" };
+  }
+  return {
+    name: rest.slice(0, spaceIdx).toLowerCase(),
+    argsRaw: rest.slice(spaceIdx + 1),
+  };
+}
+
+/**
+ * Normalize a custom action name for slash command matching.
+ */
+export function normalizeCustomActionName(name: string): string {
+  return name.trim().toLowerCase().replace(/\s+/g, "-");
+}
+
+/**
+ * Parse custom action params from a slash command args string.
+ */
+export function parseCustomActionParams(
+  action: { params?: Array<{ name: string; required?: boolean }> },
+  argsRaw: string,
+): { params: Record<string, string>; missingRequired: string[] } {
+  const params: Record<string, string> = {};
+  const missingRequired: string[] = [];
+
+  if (!action.params || action.params.length === 0) {
+    if (argsRaw.trim()) {
+      params.input = argsRaw.trim();
+    }
+    return { params, missingRequired };
+  }
+
+  const tokens = argsRaw.trim().split(/\s+/);
+  for (let i = 0; i < action.params.length; i++) {
+    const param = action.params[i];
+    if (i < tokens.length && tokens[i]) {
+      params[param.name] = tokens[i];
+    } else if (param.required) {
+      missingRequired.push(param.name);
+    }
+  }
+
+  return { params, missingRequired };
+}

package/src/actions/cloud.ts

@@ -0,0 +1,59 @@
+/**
+ * Cloud action helpers — extracted from AppContext.
+ *
+ * Pure functions for Eliza Cloud status polling and credit management.
+ */
+
+import type { MiladyClient } from "../api/client";
+
+export interface CloudStatusResult {
+  enabled: boolean;
+  connected: boolean;
+  userId: string | null;
+  topUpUrl: string | null;
+  credits: number | null;
+  creditsLow: boolean;
+  creditsCritical: boolean;
+}
+
+export async function pollCloudStatus(
+  client: MiladyClient,
+): Promise<CloudStatusResult> {
+  const cloudStatus = await client.getCloudStatus().catch(() => null);
+  if (!cloudStatus) {
+    return {
+      enabled: false,
+      connected: false,
+      userId: null,
+      topUpUrl: null,
+      credits: null,
+      creditsLow: false,
+      creditsCritical: false,
+    };
+  }
+
+  const isConnected = Boolean(cloudStatus.connected || cloudStatus.hasApiKey);
+  const result: CloudStatusResult = {
+    enabled: Boolean(cloudStatus.enabled ?? false),
+    connected: isConnected,
+    userId: cloudStatus.userId ?? null,
+    topUpUrl: cloudStatus.topUpUrl ?? null,
+    credits: null,
+    creditsLow: false,
+    creditsCritical: false,
+  };
+
+  if (isConnected) {
+    const credits = await client.getCloudCredits().catch(() => null);
+    if (credits && typeof credits.balance === "number") {
+      result.credits = credits.balance;
+      result.creditsLow = credits.low ?? false;
+      result.creditsCritical = credits.critical ?? false;
+      if (credits.topUpUrl) result.topUpUrl = credits.topUpUrl;
+    } else if (credits?.topUpUrl) {
+      result.topUpUrl = credits.topUpUrl;
+    }
+  }
+
+  return result;
+}

package/src/actions/index.ts

@@ -0,0 +1,12 @@
+/**
+ * Domain action modules — barrel export.
+ *
+ * Re-exports all action helpers for use by providers and components.
+ */
+
+export * from "./character";
+export * from "./chat-helpers";
+export * from "./cloud";
+export * from "./lifecycle";
+export * from "./onboarding";
+export * from "./triggers";

package/src/actions/lifecycle.ts

@@ -0,0 +1,175 @@
+/**
+ * Lifecycle action helpers — extracted from AppContext.
+ *
+ * Provides pure-logic functions for agent lifecycle operations
+ * (start, stop, restart, reset) that can be
+ * called from any provider implementation.
+ */
+
+import type { MiladyClient } from "../api/client";
+
+export type LifecycleAction = "start" | "stop" | "restart" | "reset";
+
+export interface LifecycleMessages {
+  progress: string;
+  success: string;
+  verb: string;
+  inProgress: string;
+}
+
+export const LIFECYCLE_MESSAGES: Record<LifecycleAction, LifecycleMessages> = {
+  start: {
+    progress: "Starting agent...",
+    success: "Agent started.",
+    verb: "start",
+    inProgress: "starting",
+  },
+  stop: {
+    progress: "Stopping agent...",
+    success: "Agent stopped.",
+    verb: "stop",
+    inProgress: "stopping",
+  },
+
+  restart: {
+    progress: "Restarting agent...",
+    success: "Agent restarted.",
+    verb: "restart",
+    inProgress: "restarting",
+  },
+  reset: {
+    progress: "Resetting agent...",
+    success: "Agent reset successfully.",
+    verb: "reset",
+    inProgress: "resetting",
+  },
+};
+
+export interface LifecycleActionContext {
+  client: MiladyClient;
+  isBusy: () => boolean;
+  setBusy: (busy: boolean) => void;
+  setNotice: (message: string, type: string, duration?: number) => void;
+}
+
+export async function executeLifecycleAction(
+  action: LifecycleAction,
+  ctx: LifecycleActionContext,
+): Promise<ReturnType<MiladyClient["getStatus"]> | null> {
+  if (ctx.isBusy()) {
+    ctx.setNotice(
+      `Agent action already in progress. Please wait.`,
+      "info",
+      2800,
+    );
+    return null;
+  }
+  ctx.setBusy(true);
+  ctx.setNotice(LIFECYCLE_MESSAGES[action].progress, "info", 3000);
+
+  try {
+    let result: Awaited<ReturnType<MiladyClient["getStatus"]>>;
+    switch (action) {
+      case "start":
+        result = await ctx.client.startAgent();
+        break;
+      case "stop":
+        result = await ctx.client.stopAgent();
+        break;
+
+      case "restart":
+        result = await ctx.client.restartAgent();
+        break;
+      default:
+        throw new Error(`Unknown lifecycle action: ${action}`);
+    }
+    ctx.setNotice(LIFECYCLE_MESSAGES[action].success, "success", 2400);
+    return result;
+  } catch (err) {
+    ctx.setNotice(
+      `Failed to ${LIFECYCLE_MESSAGES[action].verb} agent: ${
+        err instanceof Error ? err.message : "unknown error"
+      }`,
+      "error",
+      4200,
+    );
+    return null;
+  } finally {
+    ctx.setBusy(false);
+  }
+}
+
+// ── Startup helpers ─────────────────────────────────────────────────
+
+export const AGENT_READY_TIMEOUT_MS = 120_000;
+const DEFAULT_BACKEND_STARTUP_TIMEOUT_MS = 60_000;
+
+export function getBackendStartupTimeoutMs(): number {
+  try {
+    const envVal = (globalThis as Record<string, unknown>)
+      .MILADY_STARTUP_TIMEOUT;
+    if (typeof envVal === "number" && envVal > 0) return envVal;
+  } catch {
+    /* ignore */
+  }
+  return DEFAULT_BACKEND_STARTUP_TIMEOUT_MS;
+}
+
+export interface StartupErrorState {
+  reason:
+    | "backend-unreachable"
+    | "backend-timeout"
+    | "agent-timeout"
+    | "agent-error";
+  phase: "starting-backend" | "initializing-agent";
+  message: string;
+  detail?: string;
+  status?: number;
+  path?: string;
+}
+
+export function formatStartupErrorDetail(err: unknown): string {
+  if (!err) return "";
+  if (err instanceof Error) return err.message;
+  if (typeof err === "string") return err;
+  try {
+    return JSON.stringify(err);
+  } catch {
+    return String(err);
+  }
+}
+
+export interface ApiLikeError {
+  kind: "http" | "timeout" | "network";
+  status?: number;
+  path?: string;
+  message?: string;
+}
+
+export function asApiLikeError(err: unknown): ApiLikeError | null {
+  if (!err || typeof err !== "object") return null;
+  const candidate = err as Record<string, unknown>;
+  if (typeof candidate.status === "number") {
+    return {
+      kind: "http",
+      status: candidate.status,
+      path: typeof candidate.path === "string" ? candidate.path : undefined,
+      message:
+        typeof candidate.message === "string" ? candidate.message : undefined,
+    };
+  }
+  if (
+    candidate.name === "AbortError" ||
+    (typeof candidate.message === "string" &&
+      candidate.message.includes("timeout"))
+  ) {
+    return {
+      kind: "timeout",
+      message:
+        typeof candidate.message === "string" ? candidate.message : undefined,
+    };
+  }
+  return null;
+}
+
+export const AGENT_TRANSFER_MIN_PASSWORD_LENGTH = 8;

package/src/actions/onboarding.ts

@@ -0,0 +1,46 @@
+/**
+ * Onboarding step constants and helpers — extracted from AppContext.
+ */
+
+export type OnboardingStep =
+  | "wakeUp"
+  | "language"
+  | "identity"
+  | "connection"
+  | "senses"
+  | "activate";
+
+export const ONBOARDING_STEP_ORDER: OnboardingStep[] = [
+  "wakeUp",
+  "language",
+  "identity",
+  "connection",
+  "senses",
+  "activate",
+];
+
+export interface OnboardingNextOptions {
+  allowPermissionBypass?: boolean;
+}
+
+export const ONBOARDING_PERMISSION_LABELS: Record<string, string> = {
+  accessibility: "Accessibility",
+  "screen-recording": "Screen Recording",
+  microphone: "Microphone",
+};
+
+export function getNextOnboardingStep(
+  current: OnboardingStep,
+): OnboardingStep | null {
+  const idx = ONBOARDING_STEP_ORDER.indexOf(current);
+  if (idx < 0 || idx >= ONBOARDING_STEP_ORDER.length - 1) return null;
+  return ONBOARDING_STEP_ORDER[idx + 1];
+}
+
+export function getPreviousOnboardingStep(
+  current: OnboardingStep,
+): OnboardingStep | null {
+  const idx = ONBOARDING_STEP_ORDER.indexOf(current);
+  if (idx <= 0) return null;
+  return ONBOARDING_STEP_ORDER[idx - 1];
+}