@xfxstudio/claworld 0.1.0

package/src/openclaw/runtime/tool-contracts.js

@@ -0,0 +1,714 @@
+function normalizeText(value, fallback = null) {
+  if (value == null) return fallback;
+  const normalized = String(value).trim();
+  return normalized || fallback;
+}
+
+function normalizeInteger(value, fallback = 0) {
+  const parsed = Number(value);
+  if (!Number.isFinite(parsed)) return fallback;
+  return Math.max(0, Math.trunc(parsed));
+}
+
+function normalizePositiveInteger(value, fallback = null) {
+  const parsed = Number(value);
+  if (!Number.isFinite(parsed) || parsed <= 0) return fallback;
+  return Math.max(1, Math.trunc(parsed));
+}
+
+function normalizeOptionalBoolean(value, fallback = null) {
+  if (typeof value === 'boolean') return value;
+  return fallback;
+}
+
+function normalizeOptionalInteger(value, fallback = null) {
+  const parsed = Number(value);
+  if (!Number.isFinite(parsed)) return fallback;
+  return Math.trunc(parsed);
+}
+
+function normalizeStringList(values = []) {
+  if (!Array.isArray(values)) return [];
+  return values
+    .map((value) => normalizeText(value, null))
+    .filter(Boolean);
+}
+
+function summarizeProfileSnippet(profileSummary = {}) {
+  const headline = normalizeText(profileSummary.headline, null);
+  if (headline) return headline;
+
+  const required = Array.isArray(profileSummary.requiredFields) ? profileSummary.requiredFields : [];
+  const optional = Array.isArray(profileSummary.optionalFields) ? profileSummary.optionalFields : [];
+  const allFields = [...required, ...optional]
+    .map((field) => {
+      const label = normalizeText(field.label, field.fieldId || 'Field');
+      const value = Array.isArray(field.value) ? field.value.join(', ') : normalizeText(field.value, null);
+      if (!value) return null;
+      return `${label}: ${value}`;
+    })
+    .filter(Boolean);
+
+  return allFields[0] || null;
+}
+
+function projectEntryProfileFields(worldDetail = {}) {
+  const requiredFields = Array.isArray(worldDetail.requiredFields) ? worldDetail.requiredFields : [];
+  const optionalFields = Array.isArray(worldDetail.optionalFields) ? worldDetail.optionalFields : [];
+  const searchableFieldIds = new Set(
+    Array.isArray(worldDetail.searchSchema?.inputFieldIds) ? worldDetail.searchSchema.inputFieldIds : [],
+  );
+
+  return [...requiredFields, ...optionalFields].map((field) => ({
+    fieldId: field.fieldId,
+    label: field.label,
+    required: field.required === true,
+    searchable: searchableFieldIds.has(field.fieldId),
+    description: field.description || null,
+    examples: normalizeStringList(field.examples),
+  }));
+}
+
+function projectProfileField(field = {}) {
+  return {
+    fieldId: normalizeText(field.fieldId, null),
+    label: normalizeText(field.label, normalizeText(field.fieldId, 'Field')),
+    required: field.required === true,
+    description: normalizeText(field.description, null),
+    examples: normalizeStringList(field.examples),
+    constraints: field.constraints && typeof field.constraints === 'object' ? field.constraints : null,
+  };
+}
+
+function projectSearchMatchReasons(item = {}) {
+  if (Array.isArray(item.matchedFields) && item.matchedFields.length > 0) {
+    return item.matchedFields.map((field) => {
+      if (field.matchType === 'overlap' && Array.isArray(field.sharedValues) && field.sharedValues.length > 0) {
+        return `${field.label}: ${field.sharedValues.join(', ')}`;
+      }
+      return `${field.label} matches`;
+    });
+  }
+
+  return [normalizeText(item.reasonSummary, 'Recently active online world member.')];
+}
+
+function projectModerationEntryProfileSchema(schema = null) {
+  if (!schema || typeof schema !== 'object' || Array.isArray(schema)) return null;
+  return {
+    fields: Array.isArray(schema.fields)
+      ? schema.fields.map((field) => ({
+        fieldId: field.fieldId,
+        label: field.label,
+        type: field.type,
+        required: typeof field.required === 'boolean' ? field.required : null,
+        searchable: typeof field.searchable === 'boolean' ? field.searchable : null,
+        description: field.description || null,
+        examples: normalizeStringList(field.examples),
+      }))
+      : [],
+  };
+}
+
+function projectModerationSessionTemplate(sessionTemplate = null) {
+  if (!sessionTemplate || typeof sessionTemplate !== 'object' || Array.isArray(sessionTemplate)) return null;
+
+  return {
+    mode: normalizeText(sessionTemplate.mode, null),
+    maxTurns: normalizePositiveInteger(sessionTemplate.maxTurns, null),
+    turnTimeoutMs: normalizePositiveInteger(sessionTemplate.turnTimeoutMs, null),
+    raiseHandPolicy: sessionTemplate.raiseHandPolicy && typeof sessionTemplate.raiseHandPolicy === 'object'
+      ? {
+        mode: normalizeText(sessionTemplate.raiseHandPolicy.mode, null),
+        summary: normalizeText(sessionTemplate.raiseHandPolicy.summary, null),
+      }
+      : null,
+  };
+}
+
+function projectModerationBroadcastConfig(broadcast = null) {
+  if (!broadcast || typeof broadcast !== 'object' || Array.isArray(broadcast)) return null;
+
+  return {
+    enabled: normalizeOptionalBoolean(broadcast.enabled, null),
+    audience: normalizeText(broadcast.audience, null),
+    replyPolicy: normalizeText(broadcast.replyPolicy, null),
+    excludeSelf: typeof broadcast.excludeSelf === 'boolean' ? broadcast.excludeSelf : null,
+  };
+}
+
+function projectWorldRole(worldRole, fallback = null) {
+  const normalized = normalizeText(worldRole, fallback);
+  return ['owner', 'admin', 'member'].includes(normalized) ? normalized : fallback;
+}
+
+function projectWorldStats(stats = null) {
+  if (!stats || typeof stats !== 'object' || Array.isArray(stats)) return null;
+  return {
+    totalParticipants: normalizeOptionalInteger(stats.totalParticipants, null),
+    activeParticipants: normalizeOptionalInteger(stats.activeParticipants, null),
+    totalConversationCount: normalizeOptionalInteger(stats.totalConversationCount, null),
+  };
+}
+
+function projectOrchestration(orchestration = null) {
+  if (!orchestration || typeof orchestration !== 'object' || Array.isArray(orchestration)) return null;
+  return {
+    stage: normalizeText(orchestration.stage, null),
+    system: normalizeText(orchestration.system, null),
+    confirmation: normalizeText(orchestration.confirmation, null),
+    user: normalizeText(orchestration.user, null),
+    followUp: normalizeText(orchestration.followUp, null),
+  };
+}
+
+export function projectToolWorldList(worldDirectory = {}) {
+  const worlds = Array.isArray(worldDirectory.items)
+    ? [...worldDirectory.items]
+      .map((world) => ({
+        worldId: world.worldId,
+        displayName: world.displayName,
+        summary: world.summary,
+        hotness: normalizeInteger(world.hotness, 0),
+      }))
+      .sort((left, right) => right.hotness - left.hotness || left.displayName.localeCompare(right.displayName))
+    : [];
+
+  return {
+    worlds,
+    pagination: worldDirectory.pagination && typeof worldDirectory.pagination === 'object'
+      ? {
+        page: normalizeInteger(worldDirectory.pagination.page, 1),
+        totalPages: normalizeInteger(worldDirectory.pagination.totalPages, 0),
+        totalCount: normalizeInteger(worldDirectory.pagination.totalCount, worlds.length),
+      }
+      : {
+        page: 1,
+        totalPages: worlds.length > 0 ? 1 : 0,
+        totalCount: worlds.length,
+      },
+  };
+}
+
+export function projectToolWorldDetail(worldDetail = {}) {
+  return {
+    worldId: worldDetail.worldId,
+    displayName: worldDetail.displayName,
+    description: normalizeText(worldDetail.description, worldDetail.summary || ''),
+    entryProfileSchema: {
+      fields: projectEntryProfileFields(worldDetail),
+    },
+    interactionRules: normalizeText(worldDetail.interactionRules, ''),
+    prohibitedRules: normalizeText(worldDetail.prohibitedRules, ''),
+    ratingRules: normalizeText(worldDetail.ratingRules, ''),
+    adminAgentIds: Array.isArray(worldDetail.adminAgentIds) ? worldDetail.adminAgentIds : [],
+    eligibility: normalizeText(worldDetail.eligibility, null),
+    broadcast: projectModerationBroadcastConfig(worldDetail.broadcast),
+  };
+}
+
+export function projectToolWorldProfileCollectionResponse(
+  flow = {},
+  {
+    accountId = null,
+    continueToolName = null,
+    joinToolName = null,
+  } = {},
+) {
+  const profileDraft = flow.profile && typeof flow.profile === 'object' ? flow.profile : {};
+  const missingRequiredFields = Array.isArray(flow.joinCheck?.missingFields)
+    ? flow.joinCheck.missingFields.map((field) => projectProfileField(field))
+    : [];
+  const promptFields = Array.isArray(flow.promptFields)
+    ? flow.promptFields.map((field) => projectProfileField(field))
+    : [];
+  const nextMissingField = flow.joinCheck?.nextMissingField
+    ? projectProfileField(flow.joinCheck.nextMissingField)
+    : (promptFields[0] || null);
+  const normalizedAccountId = normalizeText(accountId, null);
+  const normalizedWorldId = normalizeText(flow.worldId, null);
+  const readyToJoin = flow.accepted === true;
+
+  return {
+    status: readyToJoin ? 'ready_to_join' : 'needs_profile',
+    worldId: normalizedWorldId,
+    accountId: normalizedAccountId,
+    profileDraft,
+    providedRequiredFieldIds: normalizeStringList(flow.providedRequiredFieldIds),
+    missingRequiredFields,
+    nextMissingField,
+    promptFields,
+    remainingRequiredFieldCount: normalizeInteger(
+      flow.remainingRequiredFieldCount,
+      missingRequiredFields.length,
+    ),
+    revalidationCheckpoint: flow.revalidationCheckpoint && typeof flow.revalidationCheckpoint === 'object'
+      ? {
+        mode: normalizeText(
+          flow.revalidationCheckpoint.mode,
+          readyToJoin ? 'complete' : 'after_each_reply',
+        ),
+        promptFieldIds: normalizeStringList(flow.revalidationCheckpoint.promptFieldIds),
+      }
+      : {
+        mode: readyToJoin ? 'complete' : 'after_each_reply',
+        promptFieldIds: promptFields.map((field) => field.fieldId).filter(Boolean),
+      },
+    nextAction: readyToJoin
+      ? 'retry_join_with_profile_draft'
+      : 'collect_missing_profile_fields_and_recheck',
+    nextTool: readyToJoin ? normalizeText(joinToolName, null) : normalizeText(continueToolName, null),
+    continueTool: normalizeText(continueToolName, null),
+    joinTool: normalizeText(joinToolName, null),
+    joinPayload: readyToJoin && normalizedWorldId
+      ? {
+        accountId: normalizedAccountId,
+        worldId: normalizedWorldId,
+        profileSnapshot: profileDraft,
+      }
+      : null,
+    orchestration: projectOrchestration(flow.orchestration),
+    guidance: flow.orchestration && typeof flow.orchestration === 'object'
+      ? {
+        user: normalizeText(flow.orchestration.user, null),
+        followUp: normalizeText(flow.orchestration.followUp, null),
+      }
+      : null,
+  };
+}
+
+export function projectToolJoinWorldResponse(
+  joinResult = {},
+  {
+    accountId = null,
+    continueToolName = 'claworld_prepare_world_join',
+    joinToolName = 'claworld_join_world',
+  } = {},
+) {
+  if (joinResult.status === 'needs_profile') {
+    if (joinResult.profileCollectionFlow && typeof joinResult.profileCollectionFlow === 'object') {
+      return {
+        ...projectToolWorldProfileCollectionResponse(joinResult.profileCollectionFlow, {
+          accountId,
+          continueToolName,
+          joinToolName,
+        }),
+        membershipStatus: joinResult.membershipStatus || 'inactive',
+        searchEnabled: false,
+        nextAction: 'collect_missing_profile_fields_and_retry_join',
+      };
+    }
+
+    const profileDraft = joinResult.normalizedProfile && typeof joinResult.normalizedProfile === 'object'
+      ? joinResult.normalizedProfile
+      : {};
+    return {
+    status: 'needs_profile',
+    worldId: joinResult.worldId,
+    accountId: normalizeText(accountId, null),
+    membershipStatus: joinResult.membershipStatus || 'inactive',
+    searchEnabled: false,
+      missingRequiredFields: Array.isArray(joinResult.missingRequiredFields) ? joinResult.missingRequiredFields : [],
+      nextMissingField: joinResult.nextMissingField || null,
+      profileDraft,
+      nextAction: 'collect_missing_profile_fields_and_retry_join',
+      nextTool: normalizeText(continueToolName, null),
+      continueTool: normalizeText(continueToolName, null),
+      joinTool: normalizeText(joinToolName, null),
+      orchestration: projectOrchestration(joinResult.orchestration),
+      guidance: joinResult.orchestration && typeof joinResult.orchestration === 'object'
+        ? {
+          user: normalizeText(joinResult.orchestration.user, null),
+          followUp: normalizeText(joinResult.orchestration.followUp, null),
+        }
+        : null,
+    };
+  }
+
+  return {
+    status: joinResult.status === 'activated' ? 'activated' : 'accepted',
+    worldId: joinResult.worldId,
+    accountId: normalizeText(accountId, null),
+    membershipStatus: joinResult.membershipStatus || 'unknown',
+    searchEnabled: joinResult.searchEnabled === true,
+    orchestration: projectOrchestration(joinResult.orchestration),
+    guidance: joinResult.orchestration && typeof joinResult.orchestration === 'object'
+      ? {
+        user: normalizeText(joinResult.orchestration.user, null),
+        followUp: normalizeText(joinResult.orchestration.followUp, null),
+      }
+      : null,
+  };
+}
+
+export function projectToolSearchWorldResponse(searchResult = {}, { accountId = null } = {}) {
+  if (searchResult.status === 'not_joined') {
+    return {
+      status: 'not_joined',
+      worldId: searchResult.worldId,
+      accountId: normalizeText(accountId, null),
+      query: searchResult.query || {},
+      limit: normalizeInteger(searchResult.limit, 10),
+      results: [],
+      message: normalizeText(searchResult.message, 'Join the world before searching it.'),
+    };
+  }
+
+  const results = Array.isArray(searchResult.results)
+    ? searchResult.results.map((item) => ({
+      agentId: normalizeText(item.agentId, normalizeText(item.playerId, null)),
+      playerId: normalizeText(item.playerId, normalizeText(item.agentId, null)),
+      displayName: item.displayName,
+      headline: item.headline || null,
+      score: normalizeInteger(item.score, 0),
+      matchReasons: projectSearchMatchReasons(item),
+      profileSnippet: summarizeProfileSnippet(item.profileSummary),
+      online: item.online === true,
+    }))
+    : [];
+
+  return {
+    status: results.length > 0 ? 'ready' : 'empty',
+    worldId: searchResult.worldId,
+    accountId: normalizeText(accountId, null),
+    query: searchResult.query || {},
+    limit: normalizeInteger(searchResult.limit, results.length || 10),
+    results,
+  };
+}
+
+export function projectToolCreateWorldResponse(world = {}, { accountId = null } = {}) {
+  return {
+    worldId: world.worldId,
+    accountId: normalizeText(accountId, null),
+    status: normalizeText(world.status, null),
+    enabled: normalizeOptionalBoolean(world.enabled, null),
+    worldRole: projectWorldRole(world.worldRole, null),
+    schemaVersion: normalizeOptionalInteger(world.schemaVersion, null),
+    createdAt: normalizeText(world.createdAt, null),
+    adminAgentIds: Array.isArray(world.adminAgentIds) ? world.adminAgentIds : [],
+    eligibility: normalizeText(world.eligibility, null),
+    broadcast: projectModerationBroadcastConfig(world.broadcast),
+    sessionTemplate: projectModerationSessionTemplate(world.sessionTemplate),
+  };
+}
+
+export function projectToolOwnedWorldsResponse(payload = {}, { accountId = null } = {}) {
+  const worlds = Array.isArray(payload.items)
+    ? payload.items.map((world) => ({
+      worldId: world.worldId,
+      displayName: world.displayName,
+      summary: world.summary,
+      enabled: normalizeOptionalBoolean(world.enabled, null),
+      status: normalizeText(world.status, null),
+      worldRole: projectWorldRole(world.worldRole, null),
+      createdAt: normalizeText(world.createdAt, null),
+      updatedAt: normalizeText(world.updatedAt, null),
+      stats: projectWorldStats(world.stats),
+    }))
+    : [];
+
+  return {
+    accountId: normalizeText(accountId, null),
+    worlds,
+  };
+}
+
+export function projectToolManagedWorldResponse(world = {}, { accountId = null } = {}) {
+  return {
+    worldId: world.worldId,
+    accountId: normalizeText(accountId, null),
+    displayName: world.displayName,
+    summary: world.summary,
+    description: world.description,
+    enabled: normalizeOptionalBoolean(world.enabled, null),
+    status: normalizeText(world.status, null),
+    worldRole: projectWorldRole(world.worldRole, null),
+    schemaVersion: normalizeOptionalInteger(world.schemaVersion, null),
+    createdAt: normalizeText(world.createdAt, null),
+    updatedAt: normalizeText(world.updatedAt, null),
+    adminAgentIds: Array.isArray(world.adminAgentIds) ? world.adminAgentIds : [],
+    eligibility: normalizeText(world.eligibility, null),
+    broadcast: projectModerationBroadcastConfig(world.broadcast),
+    entryProfileSchema: projectModerationEntryProfileSchema(world.entryProfileSchema),
+    interactionRules: normalizeText(world.interactionRules, null),
+    prohibitedRules: normalizeText(world.prohibitedRules, null),
+    ratingRules: normalizeText(world.ratingRules, null),
+    sessionTemplate: projectModerationSessionTemplate(world.sessionTemplate),
+    stats: projectWorldStats(world.stats),
+  };
+}
+
+export function projectToolBroadcastWorldResponse(result = {}, { accountId = null } = {}) {
+  const requests = Array.isArray(result.requests)
+    ? result.requests.map((request) => ({
+      agentId: normalizeText(
+        request.agentId,
+        request.chatRequest?.toAgent?.agentId || request.chatRequest?.counterparty?.agentId || null,
+      ),
+      status: normalizeText(request.status, 'created'),
+      chatRequest: projectChatRequestItem(request.chatRequest),
+    }))
+    : [];
+  const failures = Array.isArray(result.failures)
+    ? result.failures.map((failure) => ({
+      agentId: normalizeText(failure.agentId, null),
+      status: normalizeText(failure.status, 'failed'),
+      httpStatus: normalizeInteger(failure.httpStatus, 0),
+      error: normalizeText(failure.error, null),
+      reason: normalizeText(failure.reason, null),
+      message: normalizeText(failure.message, null),
+    }))
+    : [];
+
+  return {
+    status: normalizeText(result.status, null),
+    accountId: normalizeText(accountId, null),
+    worldId: normalizeText(result.worldId, null),
+    senderAgentId: normalizeText(result.senderAgentId, null),
+    senderRole: normalizeText(result.senderRole, null),
+    audience: normalizeText(result.audience, null),
+    excludeSelf: normalizeOptionalBoolean(result.excludeSelf, null),
+    eligibility: normalizeText(result.eligibility, null),
+    broadcastId: normalizeText(result.broadcastId, null),
+    totalTargets: normalizeInteger(result.totalTargets, requests.length + failures.length),
+    createdCount: normalizeInteger(result.createdCount, requests.length),
+    failedCount: normalizeInteger(result.failedCount, failures.length),
+    nextAction: normalizeText(result.nextAction, null),
+    requests,
+    failures,
+  };
+}
+
+export function projectToolFeedbackSubmissionResponse(result = {}) {
+  const feedback = result.feedback && typeof result.feedback === 'object' ? result.feedback : {};
+  const reporter = feedback.reporter && typeof feedback.reporter === 'object' ? feedback.reporter : {};
+  const context = feedback.context && typeof feedback.context === 'object' ? feedback.context : {};
+  const runtimeContext = feedback.runtimeContext && typeof feedback.runtimeContext === 'object'
+    ? feedback.runtimeContext
+    : {};
+
+  return {
+    status: normalizeText(result.status, 'recorded'),
+    feedbackId: normalizeText(feedback.feedbackId, null),
+    category: normalizeText(feedback.category, null),
+    impact: normalizeText(feedback.impact, 'medium'),
+    title: normalizeText(feedback.title, null),
+    accountId: normalizeText(feedback.accountId, null),
+    reporterAgentId: normalizeText(reporter.agentId, null),
+    reporterAgentCode: normalizeText(reporter.agentCode, null),
+    worldId: normalizeText(context.worldId, null),
+    sessionId: normalizeText(context.sessionId, null),
+    tags: normalizeStringList(context.tags),
+    createdAt: normalizeText(feedback.createdAt, null),
+    runtime: {
+      channelId: normalizeText(runtimeContext.channelId, null),
+      toolName: normalizeText(runtimeContext.toolName, null),
+      toolCallId: normalizeText(runtimeContext.toolCallId, null),
+      pluginVersion: normalizeText(runtimeContext.pluginVersion, null),
+    },
+    nextAction: 'keep_feedback_id_for_follow_up',
+  };
+}
+
+function projectToolAgentSummary(agent = {}) {
+  if (!agent || typeof agent !== 'object') return null;
+  return {
+    agentId: normalizeText(agent.agentId, null),
+    agentCode: normalizeText(agent.agentCode, null),
+    address: normalizeText(agent.address, null),
+    displayName: normalizeText(agent.displayName, null),
+    online: agent.online === true,
+    discoverable: typeof agent.discoverable === 'boolean' ? agent.discoverable : null,
+    contactable: typeof agent.contactable === 'boolean' ? agent.contactable : null,
+  };
+}
+
+function projectFriendshipSummary(friendship = {}) {
+  if (!friendship || typeof friendship !== 'object') return null;
+  return {
+    friendshipId: normalizeText(friendship.friendshipId, null),
+    status: normalizeText(friendship.status, null),
+    peerAgentId: normalizeText(friendship.peerAgentId, null),
+    peerAgent: projectToolAgentSummary(friendship.peerAgent),
+    acceptedAt: normalizeText(friendship.acceptedAt, null),
+    updatedAt: normalizeText(friendship.updatedAt, null),
+  };
+}
+
+function projectToolWorldSummary(world = {}) {
+  if (!world || typeof world !== 'object') return null;
+  return {
+    worldId: normalizeText(world.worldId, null),
+    slug: normalizeText(world.slug, null),
+    displayName: normalizeText(world.displayName, null),
+    summary: normalizeText(world.summary, null),
+  };
+}
+
+function normalizeConversationScopeDetails(input = {}) {
+  const conversation = input && typeof input === 'object' && !Array.isArray(input) ? input : {};
+  const worldId = normalizeText(conversation.worldId, null);
+  const maxTurns = normalizePositiveInteger(conversation.maxTurns, null);
+  const turnTimeoutMs = normalizePositiveInteger(conversation.turnTimeoutMs, null);
+  const raiseHandPolicy = conversation.raiseHandPolicy && typeof conversation.raiseHandPolicy === 'object' && !Array.isArray(conversation.raiseHandPolicy)
+    ? {
+        mode: normalizeText(conversation.raiseHandPolicy.mode, null),
+        summary: normalizeText(conversation.raiseHandPolicy.summary, null),
+      }
+    : null;
+  const episodePolicy = maxTurns != null || turnTimeoutMs != null || raiseHandPolicy
+    ? {
+        ...(maxTurns != null ? { maxTurns } : {}),
+        ...(turnTimeoutMs != null ? { turnTimeoutMs } : {}),
+        ...(raiseHandPolicy ? { raiseHandPolicy } : {}),
+      }
+    : null;
+  return {
+    mode: worldId ? 'world' : 'direct',
+    worldId,
+    world: projectToolWorldSummary(conversation.world),
+    ...(episodePolicy ? { episodePolicy } : {}),
+  };
+}
+
+function projectFriendRequestItem(request = {}) {
+  if (!request || typeof request !== 'object') return null;
+  return {
+    friendRequestId: normalizeText(request.friendRequestId, null),
+    status: normalizeText(request.status, 'pending'),
+    direction: normalizeText(request.direction, null),
+    message: normalizeText(request.message, null),
+    createdAt: normalizeText(request.createdAt, null),
+    respondedAt: normalizeText(request.respondedAt, null),
+    fromAgent: projectToolAgentSummary(request.fromAgent),
+    toAgent: projectToolAgentSummary(request.toAgent),
+  };
+}
+
+function projectChatRequestKickoff(kickoff = {}) {
+  if (!kickoff || typeof kickoff !== 'object') return null;
+  return {
+    status: normalizeText(kickoff.status, 'skipped'),
+    deliveredAt: normalizeText(kickoff.deliveredAt, null),
+    reason: normalizeText(kickoff.reason, null),
+  };
+}
+
+function projectChatRequestOrigin(origin = {}) {
+  if (!origin || typeof origin !== 'object' || Array.isArray(origin)) return null;
+  return {
+    type: normalizeText(origin.type, 'chat_request'),
+    broadcastId: normalizeText(origin.broadcastId, null),
+  };
+}
+
+function projectChatRequestItem(request = {}) {
+  if (!request || typeof request !== 'object') return null;
+  const requestContext = request.requestContext && typeof request.requestContext === 'object' && !Array.isArray(request.requestContext)
+    ? request.requestContext
+    : {};
+  const kickoffBrief = request.kickoffBrief && typeof request.kickoffBrief === 'object' && !Array.isArray(request.kickoffBrief)
+    ? request.kickoffBrief
+    : requestContext.kickoffBrief && typeof requestContext.kickoffBrief === 'object' && !Array.isArray(requestContext.kickoffBrief)
+      ? requestContext.kickoffBrief
+      : null;
+  const conversation = normalizeConversationScopeDetails(
+    request.conversation && typeof request.conversation === 'object' && !Array.isArray(request.conversation)
+      ? request.conversation
+      : requestContext.conversation,
+  );
+  return {
+    chatRequestId: normalizeText(request.chatRequestId || request.requestId, null),
+    status: normalizeText(request.status, 'pending'),
+    direction: normalizeText(request.direction, null),
+    openingMessage: normalizeText(
+      request.openingMessage,
+      normalizeText(kickoffBrief?.text, normalizeText(requestContext.openingPayload?.text, normalizeText(requestContext.message, null))),
+    ),
+    kickoffBrief: kickoffBrief
+      ? {
+          text: normalizeText(kickoffBrief.text, null),
+          payload: kickoffBrief.payload && typeof kickoffBrief.payload === 'object' && !Array.isArray(kickoffBrief.payload)
+            ? kickoffBrief.payload
+            : null,
+          source: normalizeText(kickoffBrief.source, 'chat_request_brief'),
+        }
+      : null,
+    createdAt: normalizeText(request.createdAt, null),
+    respondedAt: normalizeText(request.respondedAt, null),
+    expiresAt: normalizeText(request.expiresAt, null),
+    origin: projectChatRequestOrigin(request.origin),
+    fromAgent: projectToolAgentSummary(request.fromAgent),
+    toAgent: projectToolAgentSummary(request.toAgent),
+    counterparty: projectToolAgentSummary(request.counterparty),
+    conversation,
+  };
+}
+
+export function projectToolFriendRequestMutationResponse(result = {}, { accountId = null } = {}) {
+  return {
+    status: result.alreadyFriends === true
+      ? 'already_friends'
+      : normalizeText(result.request?.status, 'pending'),
+    accountId: normalizeText(accountId, null),
+    created: result.created === true,
+    alreadyFriends: result.alreadyFriends === true,
+    request: projectFriendRequestItem(result.request),
+    friendship: projectFriendshipSummary(result.friendship),
+    nextAction: result.alreadyFriends === true
+      ? 'friendship_active'
+      : normalizeText(result.request?.status, 'pending') === 'pending'
+        ? 'wait_for_peer_friend_request_decision'
+        : 'friendship_active',
+  };
+}
+
+export function projectToolFriendRequestListResponse(result = {}, { accountId = null } = {}) {
+  const items = Array.isArray(result.items)
+    ? result.items.map((request) => projectFriendRequestItem(request)).filter(Boolean)
+    : [];
+  return {
+    accountId: normalizeText(accountId, null),
+    items,
+  };
+}
+
+export function projectToolChatRequestMutationResponse(result = {}, { accountId = null } = {}) {
+  const request = result.chatRequest && typeof result.chatRequest === 'object'
+    ? result.chatRequest
+    : result.request && typeof result.request === 'object'
+      ? result.request
+      : result;
+  const projectedRequest = projectChatRequestItem(request);
+  const kickoff = projectChatRequestKickoff(result.kickoff || result.request?.kickoff);
+  const normalizedStatus = normalizeText(result.status, projectedRequest?.status || 'pending');
+  return {
+    status: normalizedStatus,
+    accountId: normalizeText(accountId, null),
+    chatRequest: projectedRequest,
+    kickoff,
+    nextAction: normalizeText(
+      result.nextAction,
+      normalizedStatus === 'accepted'
+        ? kickoff?.status === 'sent'
+          ? 'runtime_owns_live_conversation'
+          : kickoff?.status === 'failed'
+            ? 'backend_kickoff_failed'
+            : 'chat_request_accepted_without_opening_message'
+        : normalizedStatus === 'pending'
+          ? 'wait_for_peer_acceptance'
+          : 'chat_request_closed',
+    ),
+  };
+}
+
+export function projectToolChatRequestListResponse(result = {}, { accountId = null } = {}) {
+  const items = Array.isArray(result.items)
+    ? result.items.map((request) => projectChatRequestItem(request)).filter(Boolean)
+    : [];
+  return {
+    accountId: normalizeText(accountId, null),
+    items,
+  };
+}