@okrlinkhub/agent-factory 0.2.12 → 0.2.14

package/src/component/queue.ts

@@ -65,6 +65,23 @@ const bridgeRuntimeConfigValidator = v.object({
   serviceKeySecretRef: v.union(v.null(), v.string()),
 });
 
+const messageRuntimeConfigValidator = v.object({
+  systemPrompt: v.optional(v.string()),
+});
+
+const globalSkillStatusValidator = v.union(v.literal("active"), v.literal("disabled"));
+const globalSkillReleaseChannelValidator = v.union(v.literal("stable"), v.literal("canary"));
+const globalSkillModuleFormatValidator = v.union(v.literal("esm"), v.literal("cjs"));
+
+const globalSkillManifestItemValidator = v.object({
+  slug: v.string(),
+  version: v.string(),
+  moduleFormat: globalSkillModuleFormatValidator,
+  entryPoint: v.string(),
+  sourceJs: v.string(),
+  sha256: v.string(),
+});
+
 const BRIDGE_SECRET_REFS = {
   serviceKey: "agent-bridge.serviceKey",
   baseUrl: "agent-bridge.baseUrl",
@@ -73,6 +90,11 @@ const BRIDGE_SECRET_REFS = {
   appKey: "agent-bridge.appKey",
 } as const;
 
+const RUNTIME_CONFIG_KEYS = {
+  provider: "provider",
+  message: "message",
+} as const;
+
 export const enqueueMessage = mutation({
   args: {
     conversationId: v.string(),
@@ -87,6 +109,10 @@ export const enqueueMessage = mutation({
   returns: v.id("messageQueue"),
   handler: async (ctx, args) => {
     const nowMs = args.nowMs ?? Date.now();
+    const messageRuntimeConfigRow = await ctx.db
+      .query("runtimeConfig")
+      .withIndex("by_key", (q) => q.eq("key", RUNTIME_CONFIG_KEYS.message))
+      .unique();
     const profile = await ctx.db
       .query("agentProfiles")
       .withIndex("by_agentKey", (q) => q.eq("agentKey", args.agentKey))
@@ -113,6 +139,10 @@ export const enqueueMessage = mutation({
 
     const payload = {
       ...args.payload,
+      messageText: appendSystemPromptToMessage(
+        args.payload.messageText,
+        messageRuntimeConfigRow?.messageConfig?.systemPrompt,
+      ),
       providerUserId: providerUserIdStr,
       metadata: {
         ...(args.payload.metadata ?? {}),
@@ -239,9 +269,9 @@ export const upsertAgentProfile = mutation({
     agentKey: v.string(),
     providerUserId: v.optional(v.string()),
     version: v.string(),
-    soulMd: v.string(),
+    soulMd: v.optional(v.string()),
     clientMd: v.optional(v.string()),
-    skills: v.array(v.string()),
+    skills: v.optional(v.array(v.string())),
     secretsRef: v.array(v.string()),
     bridgeConfig: v.optional(bridgeProfileConfigValidator),
     enabled: v.boolean(),
@@ -265,6 +295,85 @@ export const upsertAgentProfile = mutation({
   },
 });
 
+export const clearDeprecatedAgentProfileFields = mutation({
+  args: {
+    dryRun: v.optional(v.boolean()),
+  },
+  returns: v.object({
+    dryRun: v.boolean(),
+    scanned: v.number(),
+    updated: v.number(),
+    unchanged: v.number(),
+    clearedProviderUserId: v.number(),
+    clearedSoulMd: v.number(),
+    clearedClientMd: v.number(),
+    clearedSkills: v.number(),
+    updatedAgentKeys: v.array(v.string()),
+  }),
+  handler: async (ctx, args) => {
+    const profiles = await ctx.db.query("agentProfiles").collect();
+    const dryRun = args.dryRun ?? false;
+
+    let updated = 0;
+    let clearedProviderUserId = 0;
+    let clearedSoulMd = 0;
+    let clearedClientMd = 0;
+    let clearedSkills = 0;
+    const updatedAgentKeys: Array<string> = [];
+
+    for (const profile of profiles) {
+      const patch: {
+        providerUserId?: undefined;
+        soulMd?: undefined;
+        clientMd?: undefined;
+        skills?: undefined;
+      } = {};
+      let shouldPatch = false;
+
+      if (profile.providerUserId !== undefined) {
+        patch.providerUserId = undefined;
+        clearedProviderUserId += 1;
+        shouldPatch = true;
+      }
+      if (profile.soulMd !== undefined) {
+        patch.soulMd = undefined;
+        clearedSoulMd += 1;
+        shouldPatch = true;
+      }
+      if (profile.clientMd !== undefined) {
+        patch.clientMd = undefined;
+        clearedClientMd += 1;
+        shouldPatch = true;
+      }
+      if (profile.skills !== undefined) {
+        patch.skills = undefined;
+        clearedSkills += 1;
+        shouldPatch = true;
+      }
+
+      if (!shouldPatch) continue;
+
+      updated += 1;
+      updatedAgentKeys.push(profile.agentKey);
+      if (!dryRun) {
+        await ctx.db.patch(profile._id, patch);
+      }
+    }
+
+    return {
+      dryRun,
+      scanned: profiles.length,
+      updated,
+      unchanged: profiles.length - updated,
+      clearedProviderUserId,
+      clearedSoulMd,
+      clearedClientMd,
+      clearedSkills,
+      updatedAgentKeys,
+    };
+  },
+});
+
 export const importPlaintextSecret = mutation({
   args: {
     secretRef: v.string(),
@@ -365,9 +474,9 @@ export const getProviderRuntimeConfig = internalQuery({
   handler: async (ctx) => {
     const row = await ctx.db
       .query("runtimeConfig")
-      .withIndex("by_key", (q) => q.eq("key", "provider"))
+      .withIndex("by_key", (q) => q.eq("key", RUNTIME_CONFIG_KEYS.provider))
       .unique();
-    if (!row) {
+    if (!row?.providerConfig) {
       return null;
     }
     return row.providerConfig;
@@ -384,11 +493,11 @@ export const upsertProviderRuntimeConfig = internalMutation({
     const nowMs = args.nowMs ?? Date.now();
     const existing = await ctx.db
       .query("runtimeConfig")
-      .withIndex("by_key", (q) => q.eq("key", "provider"))
+      .withIndex("by_key", (q) => q.eq("key", RUNTIME_CONFIG_KEYS.provider))
       .unique();
     if (!existing) {
       await ctx.db.insert("runtimeConfig", {
-        key: "provider",
+        key: RUNTIME_CONFIG_KEYS.provider,
         providerConfig: args.providerConfig,
         updatedAt: nowMs,
       });
@@ -408,9 +517,9 @@ export const providerRuntimeConfig = query({
   handler: async (ctx) => {
     const row = await ctx.db
       .query("runtimeConfig")
-      .withIndex("by_key", (q) => q.eq("key", "provider"))
+      .withIndex("by_key", (q) => q.eq("key", RUNTIME_CONFIG_KEYS.provider))
       .unique();
-    if (!row) {
+    if (!row?.providerConfig) {
       return null;
     }
     return row.providerConfig;
@@ -427,11 +536,11 @@ export const setProviderRuntimeConfig = mutation({
     const nowMs = args.nowMs ?? Date.now();
     const existing = await ctx.db
       .query("runtimeConfig")
-      .withIndex("by_key", (q) => q.eq("key", "provider"))
+      .withIndex("by_key", (q) => q.eq("key", RUNTIME_CONFIG_KEYS.provider))
       .unique();
     if (!existing) {
       await ctx.db.insert("runtimeConfig", {
-        key: "provider",
+        key: RUNTIME_CONFIG_KEYS.provider,
         providerConfig: args.providerConfig,
         updatedAt: nowMs,
       });
@@ -445,6 +554,511 @@ export const setProviderRuntimeConfig = mutation({
   },
 });
 
+export const getMessageRuntimeConfig = internalQuery({
+  args: {},
+  returns: v.union(v.null(), messageRuntimeConfigValidator),
+  handler: async (ctx) => {
+    const row = await ctx.db
+      .query("runtimeConfig")
+      .withIndex("by_key", (q) => q.eq("key", RUNTIME_CONFIG_KEYS.message))
+      .unique();
+    if (!row?.messageConfig) {
+      return null;
+    }
+    return row.messageConfig;
+  },
+});
+
+export const upsertMessageRuntimeConfig = internalMutation({
+  args: {
+    messageConfig: messageRuntimeConfigValidator,
+    nowMs: v.optional(v.number()),
+  },
+  returns: v.null(),
+  handler: async (ctx, args) => {
+    const nowMs = args.nowMs ?? Date.now();
+    const normalizedMessageConfig = normalizeMessageRuntimeConfig(args.messageConfig);
+    const existing = await ctx.db
+      .query("runtimeConfig")
+      .withIndex("by_key", (q) => q.eq("key", RUNTIME_CONFIG_KEYS.message))
+      .unique();
+    if (normalizedMessageConfig === null) {
+      if (existing) {
+        await ctx.db.delete(existing._id);
+      }
+      return null;
+    }
+    if (!existing) {
+      await ctx.db.insert("runtimeConfig", {
+        key: RUNTIME_CONFIG_KEYS.message,
+        messageConfig: normalizedMessageConfig,
+        updatedAt: nowMs,
+      });
+      return null;
+    }
+    await ctx.db.patch(existing._id, {
+      messageConfig: normalizedMessageConfig,
+      updatedAt: nowMs,
+    });
+    return null;
+  },
+});
+
+export const messageRuntimeConfig = query({
+  args: {},
+  returns: v.union(v.null(), messageRuntimeConfigValidator),
+  handler: async (ctx) => {
+    const row = await ctx.db
+      .query("runtimeConfig")
+      .withIndex("by_key", (q) => q.eq("key", RUNTIME_CONFIG_KEYS.message))
+      .unique();
+    if (!row?.messageConfig) {
+      return null;
+    }
+    return row.messageConfig;
+  },
+});
+
+export const setMessageRuntimeConfig = mutation({
+  args: {
+    messageConfig: messageRuntimeConfigValidator,
+    nowMs: v.optional(v.number()),
+  },
+  returns: v.null(),
+  handler: async (ctx, args) => {
+    const nowMs = args.nowMs ?? Date.now();
+    const normalizedMessageConfig = normalizeMessageRuntimeConfig(args.messageConfig);
+    const existing = await ctx.db
+      .query("runtimeConfig")
+      .withIndex("by_key", (q) => q.eq("key", RUNTIME_CONFIG_KEYS.message))
+      .unique();
+    if (normalizedMessageConfig === null) {
+      if (existing) {
+        await ctx.db.delete(existing._id);
+      }
+      return null;
+    }
+    if (!existing) {
+      await ctx.db.insert("runtimeConfig", {
+        key: RUNTIME_CONFIG_KEYS.message,
+        messageConfig: normalizedMessageConfig,
+        updatedAt: nowMs,
+      });
+      return null;
+    }
+    await ctx.db.patch(existing._id, {
+      messageConfig: normalizedMessageConfig,
+      updatedAt: nowMs,
+    });
+    return null;
+  },
+});
+
+export const deployGlobalSkill = mutation({
+  args: {
+    slug: v.string(),
+    displayName: v.optional(v.string()),
+    description: v.optional(v.string()),
+    version: v.string(),
+    sourceJs: v.string(),
+    entryPoint: v.optional(v.string()),
+    moduleFormat: v.optional(globalSkillModuleFormatValidator),
+    releaseChannel: v.optional(globalSkillReleaseChannelValidator),
+    actor: v.optional(v.string()),
+    nowMs: v.optional(v.number()),
+  },
+  returns: v.object({
+    skillId: v.id("globalSkills"),
+    versionId: v.id("globalSkillVersions"),
+    releaseId: v.id("globalSkillReleases"),
+    slug: v.string(),
+    version: v.string(),
+    sha256: v.string(),
+    releaseChannel: globalSkillReleaseChannelValidator,
+  }),
+  handler: async (ctx, args) => {
+    const nowMs = args.nowMs ?? Date.now();
+    const slug = args.slug.trim().toLowerCase();
+    const version = args.version.trim();
+    const entryPoint = (args.entryPoint ?? "default").trim();
+    const releaseChannel = args.releaseChannel ?? "stable";
+    const moduleFormat = args.moduleFormat ?? "esm";
+    const actor = args.actor?.trim() || "system";
+    const sourceJs = args.sourceJs.trim();
+
+    if (!/^[a-z0-9][a-z0-9-_]{1,127}$/.test(slug)) {
+      throw new Error("Invalid skill slug. Use lowercase letters, numbers, '-' and '_'.");
+    }
+    if (!/^\d+\.\d+\.\d+(?:[-+][A-Za-z0-9.-]+)?$/.test(version)) {
+      throw new Error("Invalid skill version. Use semantic versioning format.");
+    }
+    if (sourceJs.length < 16) {
+      throw new Error("Skill source is too short.");
+    }
+    if (sourceJs.length > 200_000) {
+      throw new Error("Skill source too large (max 200KB).");
+    }
+    if (!entryPoint) {
+      throw new Error("entryPoint is required.");
+    }
+
+    const sha256 = await computeSha256Hex(sourceJs);
+
+    const existingSkill = await ctx.db
+      .query("globalSkills")
+      .withIndex("by_slug", (q) => q.eq("slug", slug))
+      .unique();
+    const skillId =
+      existingSkill?._id ??
+      (await ctx.db.insert("globalSkills", {
+        slug,
+        displayName: args.displayName?.trim() || slug,
+        description: args.description?.trim(),
+        status: "active",
+        createdBy: actor,
+        updatedBy: actor,
+        createdAt: nowMs,
+        updatedAt: nowMs,
+      }));
+
+    if (existingSkill) {
+      await ctx.db.patch(skillId, {
+        displayName: args.displayName?.trim() || existingSkill.displayName,
+        description:
+          args.description !== undefined ? args.description.trim() : existingSkill.description,
+        status: "active",
+        updatedBy: actor,
+        updatedAt: nowMs,
+      });
+    }
+
+    const existingVersion = await ctx.db
+      .query("globalSkillVersions")
+      .withIndex("by_skillId_and_version", (q) => q.eq("skillId", skillId).eq("version", version))
+      .unique();
+
+    let versionId = existingVersion?._id;
+    if (!existingVersion) {
+      versionId = await ctx.db.insert("globalSkillVersions", {
+        skillId,
+        version,
+        moduleFormat,
+        entryPoint,
+        sourceJs,
+        sha256,
+        createdBy: actor,
+        createdAt: nowMs,
+      });
+    } else if (existingVersion.sha256 !== sha256) {
+      throw new Error(`Skill ${slug}@${version} already exists with a different source.`);
+    }
+
+    const activeReleases = await ctx.db
+      .query("globalSkillReleases")
+      .withIndex("by_skillId_and_releaseChannel_and_isActive", (q) =>
+        q.eq("skillId", skillId).eq("releaseChannel", releaseChannel).eq("isActive", true),
+      )
+      .collect();
+    for (const release of activeReleases) {
+      await ctx.db.patch(release._id, { isActive: false });
+    }
+
+    const releaseId = await ctx.db.insert("globalSkillReleases", {
+      skillId,
+      versionId: versionId!,
+      releaseChannel,
+      isActive: true,
+      activatedBy: actor,
+      activatedAt: nowMs,
+    });
+
+    return {
+      skillId,
+      versionId: versionId!,
+      releaseId,
+      slug,
+      version,
+      sha256,
+      releaseChannel,
+    };
+  },
+});
+
+export const listGlobalSkills = query({
+  args: {
+    releaseChannel: v.optional(globalSkillReleaseChannelValidator),
+    status: v.optional(globalSkillStatusValidator),
+    limit: v.optional(v.number()),
+  },
+  returns: v.array(
+    v.object({
+      skillId: v.id("globalSkills"),
+      slug: v.string(),
+      displayName: v.string(),
+      description: v.optional(v.string()),
+      status: globalSkillStatusValidator,
+      updatedAt: v.number(),
+      activeRelease: v.union(
+        v.null(),
+        v.object({
+          releaseId: v.id("globalSkillReleases"),
+          versionId: v.id("globalSkillVersions"),
+          version: v.string(),
+          sha256: v.string(),
+          moduleFormat: globalSkillModuleFormatValidator,
+          entryPoint: v.string(),
+          releaseChannel: globalSkillReleaseChannelValidator,
+          activatedAt: v.number(),
+        }),
+      ),
+    }),
+  ),
+  handler: async (ctx, args) => {
+    const releaseChannel = args.releaseChannel ?? "stable";
+    const limit = Math.max(1, Math.min(args.limit ?? 200, 500));
+    const skills =
+      args.status !== undefined
+        ? await ctx.db
+            .query("globalSkills")
+            .withIndex("by_status", (q) => q.eq("status", args.status!))
+            .take(limit)
+        : await ctx.db.query("globalSkills").take(limit);
+
+    const sortedSkills = [...skills].sort((a, b) => a.slug.localeCompare(b.slug));
+    const out: Array<{
+      skillId: any;
+      slug: string;
+      displayName: string;
+      description?: string;
+      status: "active" | "disabled";
+      updatedAt: number;
+      activeRelease: {
+        releaseId: any;
+        versionId: any;
+        version: string;
+        sha256: string;
+        moduleFormat: "esm" | "cjs";
+        entryPoint: string;
+        releaseChannel: "stable" | "canary";
+        activatedAt: number;
+      } | null;
+    }> = [];
+
+    for (const skill of sortedSkills) {
+      const activeRelease = await ctx.db
+        .query("globalSkillReleases")
+        .withIndex("by_skillId_and_releaseChannel_and_isActive", (q) =>
+          q.eq("skillId", skill._id).eq("releaseChannel", releaseChannel).eq("isActive", true),
+        )
+        .first();
+
+      let activeReleaseRow: (typeof out)[number]["activeRelease"] = null;
+      if (activeRelease) {
+        const version = await ctx.db.get(activeRelease.versionId);
+        if (version) {
+          activeReleaseRow = {
+            releaseId: activeRelease._id,
+            versionId: version._id,
+            version: version.version,
+            sha256: version.sha256,
+            moduleFormat: version.moduleFormat,
+            entryPoint: version.entryPoint,
+            releaseChannel: activeRelease.releaseChannel,
+            activatedAt: activeRelease.activatedAt,
+          };
+        }
+      }
+
+      out.push({
+        skillId: skill._id,
+        slug: skill.slug,
+        displayName: skill.displayName,
+        description: skill.description,
+        status: skill.status,
+        updatedAt: skill.updatedAt,
+        activeRelease: activeReleaseRow,
+      });
+    }
+    return out;
+  },
+});
+
+export const getWorkerGlobalSkillsManifest = query({
+  args: {
+    workspaceId: v.optional(v.string()),
+    workerId: v.optional(v.string()),
+    releaseChannel: v.optional(globalSkillReleaseChannelValidator),
+  },
+  returns: v.object({
+    manifestVersion: v.string(),
+    generatedAt: v.number(),
+    releaseChannel: globalSkillReleaseChannelValidator,
+    workspaceId: v.string(),
+    skills: v.array(globalSkillManifestItemValidator),
+  }),
+  handler: async (ctx, args) => {
+    const nowMs = Date.now();
+    const releaseChannel = args.releaseChannel ?? "stable";
+    const activeSkills = await ctx.db
+      .query("globalSkills")
+      .withIndex("by_status", (q) => q.eq("status", "active"))
+      .collect();
+    const sortedSkills = [...activeSkills].sort((a, b) => a.slug.localeCompare(b.slug));
+
+    const manifestSkills: Array<{
+      slug: string;
+      version: string;
+      moduleFormat: "esm" | "cjs";
+      entryPoint: string;
+      sourceJs: string;
+      sha256: string;
+    }> = [];
+
+    for (const skill of sortedSkills) {
+      const activeRelease = await ctx.db
+        .query("globalSkillReleases")
+        .withIndex("by_skillId_and_releaseChannel_and_isActive", (q) =>
+          q.eq("skillId", skill._id).eq("releaseChannel", releaseChannel).eq("isActive", true),
+        )
+        .first();
+      if (!activeRelease) continue;
+
+      const version = await ctx.db.get(activeRelease.versionId);
+      if (!version) continue;
+      manifestSkills.push({
+        slug: skill.slug,
+        version: version.version,
+        moduleFormat: version.moduleFormat,
+        entryPoint: version.entryPoint,
+        sourceJs: version.sourceJs,
+        sha256: version.sha256,
+      });
+    }
+
+    manifestSkills.sort((a, b) => {
+      if (a.slug !== b.slug) return a.slug.localeCompare(b.slug);
+      return a.version.localeCompare(b.version);
+    });
+
+    const fingerprintSeed = manifestSkills
+      .map((row) => `${row.slug}@${row.version}:${row.sha256}`)
+      .join("|");
+    const manifestVersion = await computeSha256Hex(fingerprintSeed || "empty");
+
+    return {
+      manifestVersion,
+      generatedAt: nowMs,
+      releaseChannel,
+      workspaceId: args.workspaceId ?? "default",
+      skills: manifestSkills,
+    };
+  },
+});
+
+export const setGlobalSkillStatus = mutation({
+  args: {
+    slug: v.string(),
+    status: globalSkillStatusValidator,
+    actor: v.optional(v.string()),
+    nowMs: v.optional(v.number()),
+  },
+  returns: v.object({
+    updated: v.boolean(),
+    slug: v.string(),
+    status: globalSkillStatusValidator,
+  }),
+  handler: async (ctx, args) => {
+    const slug = args.slug.trim().toLowerCase();
+    const nowMs = args.nowMs ?? Date.now();
+    const actor = args.actor?.trim() || "system";
+    const skill = await ctx.db
+      .query("globalSkills")
+      .withIndex("by_slug", (q) => q.eq("slug", slug))
+      .unique();
+    if (!skill) {
+      return { updated: false, slug, status: args.status };
+    }
+    await ctx.db.patch(skill._id, {
+      status: args.status,
+      updatedBy: actor,
+      updatedAt: nowMs,
+    });
+    return { updated: true, slug, status: args.status };
+  },
+});
+
+export const deleteGlobalSkill = mutation({
+  args: {
+    slug: v.string(),
+  },
+  returns: v.object({
+    deleted: v.boolean(),
+    slug: v.string(),
+    deletedVersions: v.number(),
+    deletedReleases: v.number(),
+  }),
+  handler: async (ctx, args) => {
+    const slug = args.slug.trim().toLowerCase();
+    const skill = await ctx.db
+      .query("globalSkills")
+      .withIndex("by_slug", (q) => q.eq("slug", slug))
+      .unique();
+    if (!skill) {
+      return { deleted: false, slug, deletedVersions: 0, deletedReleases: 0 };
+    }
+
+    const stableActiveReleases = await ctx.db
+      .query("globalSkillReleases")
+      .withIndex("by_skillId_and_releaseChannel_and_isActive", (q) =>
+        q.eq("skillId", skill._id).eq("releaseChannel", "stable").eq("isActive", true),
+      )
+      .collect();
+    const stableInactiveReleases = await ctx.db
+      .query("globalSkillReleases")
+      .withIndex("by_skillId_and_releaseChannel_and_isActive", (q) =>
+        q.eq("skillId", skill._id).eq("releaseChannel", "stable").eq("isActive", false),
+      )
+      .collect();
+    const canaryActiveReleases = await ctx.db
+      .query("globalSkillReleases")
+      .withIndex("by_skillId_and_releaseChannel_and_isActive", (q) =>
+        q.eq("skillId", skill._id).eq("releaseChannel", "canary").eq("isActive", true),
+      )
+      .collect();
+    const canaryInactiveReleases = await ctx.db
+      .query("globalSkillReleases")
+      .withIndex("by_skillId_and_releaseChannel_and_isActive", (q) =>
+        q.eq("skillId", skill._id).eq("releaseChannel", "canary").eq("isActive", false),
+      )
+      .collect();
+    const allReleases = [
+      ...stableActiveReleases,
+      ...stableInactiveReleases,
+      ...canaryActiveReleases,
+      ...canaryInactiveReleases,
+    ];
+    const versions = await ctx.db
+      .query("globalSkillVersions")
+      .withIndex("by_skillId_and_createdAt", (q) => q.eq("skillId", skill._id))
+      .collect();
+
+    for (const release of allReleases) {
+      await ctx.db.delete(release._id);
+    }
+    for (const version of versions) {
+      await ctx.db.delete(version._id);
+    }
+    await ctx.db.delete(skill._id);
+
+    return {
+      deleted: true,
+      slug,
+      deletedVersions: versions.length,
+      deletedReleases: allReleases.length,
+    };
+  },
+});
+
 export const generateMediaUploadUrl = mutation({
   args: {},
   returns: v.object({
@@ -1623,6 +2237,36 @@ async function resolveBridgeRuntimeConfig(
   };
 }
 
+function appendSystemPromptToMessage(messageText: string, systemPrompt?: string): string {
+  const normalizedSystemPrompt = normalizeSystemPrompt(systemPrompt);
+  if (normalizedSystemPrompt === null) {
+    return messageText;
+  }
+  const normalizedMessageText = messageText.trimEnd();
+  if (normalizedMessageText.length === 0) {
+    return normalizedSystemPrompt;
+  }
+  return `${normalizedMessageText}\n\n${normalizedSystemPrompt}`;
+}
+
+function normalizeMessageRuntimeConfig(
+  messageConfig: { systemPrompt?: string } | null | undefined,
+): { systemPrompt?: string } | null {
+  const systemPrompt = normalizeSystemPrompt(messageConfig?.systemPrompt);
+  if (systemPrompt === null) {
+    return null;
+  }
+  return { systemPrompt };
+}
+
+function normalizeSystemPrompt(systemPrompt?: string | null): string | null {
+  if (typeof systemPrompt !== "string") {
+    return null;
+  }
+  const normalizedSystemPrompt = systemPrompt.trim();
+  return normalizedSystemPrompt.length > 0 ? normalizedSystemPrompt : null;
+}
+
 function getBridgeSecretRefsForProfile(
   agentKey: string,
   bridgeConfig:
@@ -1688,6 +2332,14 @@ function fingerprintConversationDelta(
   return `f${(hash >>> 0).toString(16)}`;
 }
 
+async function computeSha256Hex(input: string): Promise<string> {
+  const bytes = new TextEncoder().encode(input);
+  const digest = await crypto.subtle.digest("SHA-256", bytes);
+  return Array.from(new Uint8Array(digest))
+    .map((value) => value.toString(16).padStart(2, "0"))
+    .join("");
+}
+
 function encryptSecretValue(plaintext: string): string {
   const units = Array.from(plaintext);
   return units