@xfxstudio/claworld 0.1.0

package/src/lib/accepted-chat-kickoff.js

@@ -0,0 +1,192 @@
+export const ACCEPTED_CHAT_KICKOFF_PAYLOAD_KIND = 'accepted_chat_kickoff';
+
+function normalizeText(value, fallback = null) {
+  if (value == null) return fallback;
+  const normalized = String(value).trim();
+  return normalized || fallback;
+}
+
+function cloneJsonObject(value) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return null;
+  try {
+    const cloned = JSON.parse(JSON.stringify(value));
+    if (!cloned || typeof cloned !== 'object' || Array.isArray(cloned)) return null;
+    return cloned;
+  } catch {
+    return null;
+  }
+}
+
+function normalizeKickoffPayload(input) {
+  return cloneJsonObject(input);
+}
+
+function normalizeKickoffSource(value, fallback = 'chat_request_brief') {
+  return normalizeText(value, fallback);
+}
+
+export function createKickoffBrief({
+  text = null,
+  payload = null,
+  source = 'chat_request_brief',
+} = {}) {
+  const normalizedPayload = normalizeKickoffPayload(payload);
+  const normalizedText = normalizeText(text, normalizeText(normalizedPayload?.text, null));
+  if (!normalizedText && !normalizedPayload) return null;
+  const hasPayloadText = typeof normalizedPayload?.text === 'string' && normalizedPayload.text.trim().length > 0;
+  return {
+    ...(normalizedText ? { text: normalizedText } : {}),
+    ...(normalizedPayload ? {
+      payload: {
+        ...normalizedPayload,
+        ...(normalizedText && !hasPayloadText ? { text: normalizedText } : {}),
+      },
+    } : {}),
+    source: normalizeKickoffSource(source),
+  };
+}
+
+export function resolveStoredKickoffBrief(requestContext = {}) {
+  if (!requestContext || typeof requestContext !== 'object' || Array.isArray(requestContext)) return null;
+
+  const kickoffBrief = requestContext.kickoffBrief && typeof requestContext.kickoffBrief === 'object' && !Array.isArray(requestContext.kickoffBrief)
+    ? requestContext.kickoffBrief
+    : null;
+  if (kickoffBrief) {
+    return createKickoffBrief({
+      text: kickoffBrief.text,
+      payload: kickoffBrief.payload,
+      source: kickoffBrief.source,
+    });
+  }
+
+  return createKickoffBrief({
+    text: normalizeText(requestContext.openingPayload?.text, normalizeText(requestContext.message, null)),
+    payload: requestContext.openingPayload,
+    source: requestContext.openingPayload?.source || 'legacy_chat_request_opening',
+  });
+}
+
+export function resolveAcceptedChatKickoffViewer(bundle = {}, {
+  localAgentId = null,
+  fallback = 'recipient',
+} = {}) {
+  const normalizedLocalAgentId = normalizeText(localAgentId, null);
+  const participants = bundle?.participants && typeof bundle.participants === 'object' && !Array.isArray(bundle.participants)
+    ? bundle.participants
+    : {};
+  const senderAgentId = normalizeText(participants.sender?.agentId, null);
+  const recipientAgentId = normalizeText(participants.recipient?.agentId, null);
+
+  if (normalizedLocalAgentId && normalizedLocalAgentId === senderAgentId) return 'sender';
+  if (normalizedLocalAgentId && normalizedLocalAgentId === recipientAgentId) return 'recipient';
+  return fallback === 'sender' ? 'sender' : 'recipient';
+}
+
+function buildAcceptedChatKickoffRuntimeContext(bundle = {}, { viewer = 'recipient' } = {}) {
+  const resolvedViewer = viewer === 'sender' ? 'sender' : 'recipient';
+  const request = bundle.request && typeof bundle.request === 'object' && !Array.isArray(bundle.request)
+    ? bundle.request
+    : {};
+  const brief = request.brief && typeof request.brief === 'object' && !Array.isArray(request.brief)
+    ? request.brief
+    : {};
+
+  return {
+    viewer: resolvedViewer,
+    text: formatAcceptedChatKickoffMessage(bundle, { viewer: resolvedViewer }),
+    briefText: normalizeText(brief.text, null),
+  };
+}
+
+export function readAcceptedChatKickoffRuntimeContext(bundle = {}, { viewer = 'recipient' } = {}) {
+  const resolvedViewer = viewer === 'sender' ? 'sender' : 'recipient';
+  const request = bundle.request && typeof bundle.request === 'object' && !Array.isArray(bundle.request)
+    ? bundle.request
+    : {};
+  const brief = request.brief && typeof request.brief === 'object' && !Array.isArray(request.brief)
+    ? request.brief
+    : {};
+  const runtimeContext = bundle.runtimeContext && typeof bundle.runtimeContext === 'object' && !Array.isArray(bundle.runtimeContext)
+    ? bundle.runtimeContext
+    : {};
+  const candidate = runtimeContext[resolvedViewer] && typeof runtimeContext[resolvedViewer] === 'object' && !Array.isArray(runtimeContext[resolvedViewer])
+    ? runtimeContext[resolvedViewer]
+    : null;
+  if (!candidate) return null;
+
+  const text = normalizeText(candidate.text, null);
+  if (!text) return null;
+
+  return {
+    viewer: resolvedViewer,
+    text,
+    briefText: normalizeText(candidate.briefText, normalizeText(brief.text, null)),
+  };
+}
+
+export function createAcceptedChatKickoffRuntimeContext(bundle = {}, { viewer = 'recipient' } = {}) {
+  return readAcceptedChatKickoffRuntimeContext(bundle, { viewer })
+    || buildAcceptedChatKickoffRuntimeContext(bundle, { viewer });
+}
+
+export function createAcceptedChatKickoffRuntimeContexts(bundle = {}) {
+  return {
+    sender: buildAcceptedChatKickoffRuntimeContext(bundle, { viewer: 'sender' }),
+    recipient: buildAcceptedChatKickoffRuntimeContext(bundle, { viewer: 'recipient' }),
+  };
+}
+
+export function createAcceptedChatKickoffRuntimeContextForAgent(bundle = {}, {
+  localAgentId = null,
+  fallback = 'recipient',
+} = {}) {
+  return createAcceptedChatKickoffRuntimeContext(bundle, {
+    viewer: resolveAcceptedChatKickoffViewer(bundle, {
+      localAgentId,
+      fallback,
+    }),
+  });
+}
+
+export function formatAcceptedChatKickoffMessage(bundle = {}, { viewer = 'recipient' } = {}) {
+  const normalizedViewer = viewer === 'sender' ? 'sender' : 'recipient';
+  const request = bundle.request && typeof bundle.request === 'object' ? bundle.request : {};
+  const conversation = bundle.conversation && typeof bundle.conversation === 'object' ? bundle.conversation : {};
+  const participants = bundle.participants && typeof bundle.participants === 'object' ? bundle.participants : {};
+  const sender = participants.sender && typeof participants.sender === 'object' ? participants.sender : {};
+  const recipient = participants.recipient && typeof participants.recipient === 'object' ? participants.recipient : {};
+  const world = bundle.world && typeof bundle.world === 'object' ? bundle.world : null;
+  const policy = bundle.policy && typeof bundle.policy === 'object' ? bundle.policy : {};
+  const brief = request.brief && typeof request.brief === 'object' ? request.brief : {};
+
+  const worldLabel = normalizeText(world?.displayName, normalizeText(world?.worldId, null));
+  const viewerInstruction = normalizedViewer === 'recipient'
+    ? 'Use this accepted-chat kickoff context to interpret the sender opener as the first live turn of the accepted chat episode. Decide whether and how to reply. Do not echo the bundle verbatim to the peer.'
+    : 'Use this accepted-chat kickoff bundle to craft the first live opener to the recipient. Do not echo the bundle verbatim to the peer.';
+
+  const blocks = [
+    normalizedViewer === 'recipient'
+      ? 'Internal Claworld accepted-chat kickoff bundle for the recipient runtime.'
+      : 'Internal Claworld accepted-chat kickoff bundle for the sender runtime.',
+    viewerInstruction,
+    normalizeText(bundle.requestId, null) ? `Accepted episode: ${bundle.requestId}` : null,
+    normalizeText(conversation.mode, null) ? `Conversation mode: ${conversation.mode}` : null,
+    worldLabel ? `World: ${worldLabel}${world?.worldId ? ` [${world.worldId}]` : ''}` : null,
+    brief.text ? `Sender brief: ${brief.text}` : null,
+    sender.displayName || sender.agentId
+      ? `Sender: ${normalizeText(sender.displayName, sender.agentId)}${sender.agentId ? ` [${sender.agentId}]` : ''}`
+      : null,
+    recipient.displayName || recipient.agentId
+      ? `Recipient: ${normalizeText(recipient.displayName, recipient.agentId)}${recipient.agentId ? ` [${recipient.agentId}]` : ''}`
+      : null,
+    world?.summary ? `World summary: ${world.summary}` : null,
+    world?.sessionContext ? `World session context:\n${JSON.stringify(world.sessionContext, null, 2)}` : null,
+    participants.sender?.worldProfile ? `Sender world profile:\n${JSON.stringify(participants.sender.worldProfile, null, 2)}` : null,
+    participants.recipient?.worldProfile ? `Recipient world profile:\n${JSON.stringify(participants.recipient.worldProfile, null, 2)}` : null,
+    Object.keys(policy).length > 0 ? `Accepted episode policy:\n${JSON.stringify(policy, null, 2)}` : null,
+    brief.payload ? `Structured brief payload:\n${JSON.stringify(brief.payload, null, 2)}` : null,
+  ].filter(Boolean);
+
+  return blocks.join('\n\n');
+}

package/src/lib/agent-address.js

@@ -0,0 +1,46 @@
+const AGENT_HANDLE_SEGMENT_PATTERN = /^[A-Za-z0-9._:+~-]+$/i;
+
+function normalizeSegment(value) {
+  const normalized = String(value || '').trim().toLowerCase();
+  return normalized || null;
+}
+
+export function isValidAgentHandleSegment(value) {
+  const normalized = normalizeSegment(value);
+  return Boolean(normalized && AGENT_HANDLE_SEGMENT_PATTERN.test(normalized));
+}
+
+export function parseAgentHandle(value, { defaultDomain = null } = {}) {
+  const normalizedValue = String(value || '').trim().toLowerCase();
+  if (!normalizedValue) return null;
+
+  const firstAtIndex = normalizedValue.indexOf('@');
+  if (firstAtIndex === -1) {
+    const normalizedDomain = normalizeSegment(defaultDomain);
+    if (!isValidAgentHandleSegment(normalizedValue) || !isValidAgentHandleSegment(normalizedDomain)) {
+      return null;
+    }
+    return {
+      localPart: normalizedValue,
+      domain: normalizedDomain,
+      address: `${normalizedValue}@${normalizedDomain}`,
+      canonical: false,
+    };
+  }
+
+  if (firstAtIndex === 0 || firstAtIndex === normalizedValue.length - 1) return null;
+  if (normalizedValue.indexOf('@', firstAtIndex + 1) !== -1) return null;
+
+  const localPart = normalizeSegment(normalizedValue.slice(0, firstAtIndex));
+  const domain = normalizeSegment(normalizedValue.slice(firstAtIndex + 1));
+  if (!isValidAgentHandleSegment(localPart) || !isValidAgentHandleSegment(domain)) {
+    return null;
+  }
+
+  return {
+    localPart,
+    domain,
+    address: `${localPart}@${domain}`,
+    canonical: true,
+  };
+}

package/src/lib/agent-profile.js

@@ -0,0 +1,69 @@
+function normalizeOptionalString(value, { maxLength = 280 } = {}) {
+  if (value == null) return null;
+  const normalized = String(value).trim();
+  if (!normalized) return null;
+  return normalized.slice(0, maxLength);
+}
+
+function normalizeTagList(rawTags, { maxItems = 8, maxLength = 24 } = {}) {
+  if (!Array.isArray(rawTags)) return [];
+  const seen = new Set();
+  const tags = [];
+  for (const value of rawTags) {
+    const normalized = normalizeOptionalString(value, { maxLength });
+    if (!normalized) continue;
+    const key = normalized.toLowerCase();
+    if (seen.has(key)) continue;
+    seen.add(key);
+    tags.push(normalized);
+    if (tags.length >= maxItems) break;
+  }
+  return tags;
+}
+
+function normalizeBooleanFlag(value, fallback = true) {
+  if (typeof value === 'boolean') return value;
+  if (typeof value === 'number') {
+    if (value === 1) return true;
+    if (value === 0) return false;
+  }
+  if (typeof value === 'string') {
+    const normalized = value.trim().toLowerCase();
+    if (normalized === 'true' || normalized === '1') return true;
+    if (normalized === 'false' || normalized === '0') return false;
+  }
+  return fallback;
+}
+
+export function resolveAgentDisplayName(agent = {}) {
+  const displayName = normalizeOptionalString(agent.displayName, { maxLength: 80 });
+  if (displayName) return displayName;
+  return normalizeOptionalString(agent.agentCode, { maxLength: 80 }) || 'agent';
+}
+
+export function normalizeAgentProfile(profile) {
+  const source = profile && typeof profile === 'object' ? profile : {};
+  return {
+    headline: normalizeOptionalString(source.headline, { maxLength: 120 }),
+    bio: normalizeOptionalString(source.bio, { maxLength: 300 }),
+    avatarUrl: normalizeOptionalString(source.avatarUrl, { maxLength: 512 }),
+    tags: normalizeTagList(source.tags),
+  };
+}
+
+export function resolveAgentVisibility(agent = {}) {
+  const discoverable = normalizeBooleanFlag(agent.discoverable, true);
+  const requestedContactable = normalizeBooleanFlag(agent.contactable, true);
+  return {
+    discoverable,
+    contactable: discoverable ? requestedContactable : false,
+  };
+}
+
+export function normalizeAgentInputMetadata({ agentCode, displayName, profile, discoverable, contactable } = {}) {
+  return {
+    displayName: resolveAgentDisplayName({ agentCode, displayName }),
+    profile: normalizeAgentProfile(profile),
+    ...resolveAgentVisibility({ discoverable, contactable }),
+  };
+}

package/src/lib/http-auth.js

@@ -0,0 +1,151 @@
+function unauthorized(reason) {
+  return {
+    error: 'not_authenticated',
+    reason,
+  };
+}
+
+function forbidden(reason, extra = {}) {
+  return {
+    error: 'forbidden',
+    reason,
+    ...extra,
+  };
+}
+
+function isExpired(isoTs, nowMs = Date.now()) {
+  if (!isoTs) return false;
+  const expiresAtMs = Date.parse(isoTs);
+  if (Number.isNaN(expiresAtMs)) return false;
+  return expiresAtMs <= nowMs;
+}
+
+function normalizeHeaderValue(value) {
+  if (Array.isArray(value)) {
+    const [first] = value;
+    return typeof first === 'string' ? first.trim() : '';
+  }
+  if (typeof value === 'string') return value.trim();
+  return '';
+}
+
+export function readAppTokenFromRequest(req) {
+  const authorization = normalizeHeaderValue(req?.headers?.authorization);
+  if (/^bearer\s+/i.test(authorization)) {
+    const token = authorization.replace(/^bearer\s+/i, '').trim();
+    if (token) return { token, source: 'authorization' };
+  }
+
+  const appTokenHeader = normalizeHeaderValue(req?.headers?.['x-claworld-app-token']);
+  if (appTokenHeader) return { token: appTokenHeader, source: 'x-claworld-app-token' };
+
+  const legacyRelayToken = normalizeHeaderValue(req?.headers?.['x-relay-token']);
+  if (legacyRelayToken) return { token: legacyRelayToken, source: 'x-relay-token' };
+
+  return { token: null, source: null };
+}
+
+export function authenticateAppTokenRequest({ store, req }) {
+  const { token, source } = readAppTokenFromRequest(req);
+  if (!token) {
+    return {
+      present: false,
+      ok: false,
+      source: null,
+      token: null,
+      agent: null,
+      credential: null,
+      error: null,
+    };
+  }
+
+  const credential = store.getCredentialByToken(token);
+  if (!credential) {
+    return {
+      present: true,
+      ok: false,
+      source,
+      token,
+      agent: null,
+      credential: null,
+      error: unauthorized('credential_invalid'),
+    };
+  }
+  if (credential.status !== 'active' || credential.revokedAt) {
+    return {
+      present: true,
+      ok: false,
+      source,
+      token,
+      agent: null,
+      credential,
+      error: unauthorized('credential_revoked'),
+    };
+  }
+  if (isExpired(credential.expiresAt)) {
+    return {
+      present: true,
+      ok: false,
+      source,
+      token,
+      agent: null,
+      credential,
+      error: unauthorized('credential_expired'),
+    };
+  }
+
+  const agent = store.getAgent(credential.agentId);
+  if (!agent) {
+    return {
+      present: true,
+      ok: false,
+      source,
+      token,
+      agent: null,
+      credential,
+      error: unauthorized('credential_invalid'),
+    };
+  }
+
+  return {
+    present: true,
+    ok: true,
+    source,
+    token,
+    agent,
+    credential,
+    error: null,
+  };
+}
+
+export function resolveAuthenticatedAgentId({ store, req, providedAgentId = null, fieldName = 'agentId' } = {}) {
+  const auth = authenticateAppTokenRequest({ store, req });
+  if (auth.present && !auth.ok) {
+    return {
+      ok: false,
+      status: 401,
+      body: auth.error,
+    };
+  }
+
+  const explicitAgentId = String(providedAgentId || '').trim() || null;
+  const authenticatedAgentId = auth.ok ? auth.agent.agentId : null;
+
+  if (explicitAgentId && authenticatedAgentId && explicitAgentId !== authenticatedAgentId) {
+    return {
+      ok: false,
+      status: 403,
+      body: forbidden('agent_identity_mismatch', {
+        field: fieldName,
+        authenticatedAgentId,
+        providedAgentId: explicitAgentId,
+      }),
+    };
+  }
+
+  return {
+    ok: true,
+    auth,
+    agentId: explicitAgentId || authenticatedAgentId || null,
+  };
+}

package/src/lib/policy.js

@@ -0,0 +1,118 @@
+import { resolveAgentVisibility } from './agent-profile.js';
+const ALLOW_DECISION = Object.freeze({ allowed: true });
+const EMPTY_SET = Object.freeze(new Set());
+
+function parsePolicyCsvSet(rawValue) {
+  if (typeof rawValue !== 'string') return EMPTY_SET;
+  const values = rawValue
+    .split(',')
+    .map((value) => value.trim().toLowerCase())
+    .filter(Boolean);
+  return values.length > 0 ? new Set(values) : EMPTY_SET;
+}
+
+function buildRequestDenyPolicyFromEnv(env) {
+  return Object.freeze({
+    blockedAgentIds: parsePolicyCsvSet(env.RELAY_POLICY_BLOCKED_AGENT_IDS),
+    blockedAgentCodes: parsePolicyCsvSet(env.RELAY_POLICY_BLOCKED_AGENT_CODES),
+    deniedAgentIds: parsePolicyCsvSet(env.RELAY_POLICY_DENIED_AGENT_IDS),
+    deniedAgentCodes: parsePolicyCsvSet(env.RELAY_POLICY_DENIED_AGENT_CODES),
+  });
+}
+
+function agentInPolicySet(values, candidate) {
+  const normalized = String(candidate || '').trim().toLowerCase();
+  return normalized ? values.has(normalized) : false;
+}
+
+const requestDenyPolicy = buildRequestDenyPolicyFromEnv(process.env);
+
+function deny(status, error, extras = {}) {
+  return { allowed: false, status, error, ...extras };
+}
+
+export function defaultCanRequest({ fromAgentId, fromAgent, toAgent }) {
+  const visibility = resolveAgentVisibility(toAgent);
+  if (agentInPolicySet(requestDenyPolicy.blockedAgentIds, fromAgentId)
+    || agentInPolicySet(requestDenyPolicy.blockedAgentCodes, fromAgent?.agentCode)) {
+    return deny(403, 'request_blocked_by_policy');
+  }
+  if (agentInPolicySet(requestDenyPolicy.deniedAgentIds, fromAgentId)
+    || agentInPolicySet(requestDenyPolicy.deniedAgentCodes, fromAgent?.agentCode)) {
+    return deny(403, 'request_denied_by_policy');
+  }
+  if (toAgent.agentId === fromAgentId) return deny(400, 'self_request_not_allowed');
+  if (!visibility.discoverable) return deny(403, 'target_not_discoverable');
+  if (!visibility.contactable) return deny(403, 'target_not_contactable');
+  return ALLOW_DECISION;
+}
+
+export function defaultCanAccept() {
+  return ALLOW_DECISION;
+}
+
+export function defaultCanStartSession() {
+  return ALLOW_DECISION;
+}
+
+export function defaultCanDeliverTurn({ session, roundBudget, fromAgentId }) {
+  if (session.state !== 'active') {
+    const terminationReason = typeof session?.terminationReason === 'string' && session.terminationReason.trim()
+      ? session.terminationReason.trim()
+      : null;
+    return deny(terminationReason === 'session_timeout' ? 409 : 400, terminationReason || 'session_not_active');
+  }
+  if (roundBudget?.hasExplicitBudget && Number(roundBudget.remainingTurns) <= 0) {
+    return deny(400, 'max_turns_reached');
+  }
+  if (fromAgentId !== session.currentSpeakerAgentId) return deny(400, 'not_current_speaker');
+  return ALLOW_DECISION;
+}
+
+export function createRelayPolicyHooks(policy) {
+  const hooks = policy && typeof policy === 'object' ? policy : {};
+  return {
+    canRequest: typeof hooks.canRequest === 'function' ? hooks.canRequest : defaultCanRequest,
+    canAccept: typeof hooks.canAccept === 'function' ? hooks.canAccept : defaultCanAccept,
+    canStartSession: typeof hooks.canStartSession === 'function' ? hooks.canStartSession : defaultCanStartSession,
+    canDeliverTurn: typeof hooks.canDeliverTurn === 'function' ? hooks.canDeliverTurn : defaultCanDeliverTurn,
+  };
+}
+
+export function resolvePolicyDecision(decision, { defaultStatus = 403, defaultError = 'forbidden' } = {}) {
+  if (decision == null || decision === true) return { allowed: true };
+  if (decision === false) return { allowed: false, status: defaultStatus, body: { error: defaultError } };
+  if (typeof decision !== 'object') return { allowed: true };
+
+  const hasDenyShape = decision.allowed === false
+    || (decision.allowed === undefined && (decision.status !== undefined || decision.error !== undefined || decision.body !== undefined));
+
+  if (!hasDenyShape) return { allowed: true };
+
+  const status = Number.isInteger(decision.status) ? decision.status : defaultStatus;
+  if (decision.body && typeof decision.body === 'object') return { allowed: false, status, body: decision.body };
+  const error = typeof decision.error === 'string' && decision.error.trim() ? decision.error : defaultError;
+  return { allowed: false, status, body: { error } };
+}
+
+export function evaluatePolicyHook({
+  hook,
+  context,
+  hookName,
+  defaultStatus = 403,
+  defaultError = 'forbidden',
+}) {
+  try {
+    return resolvePolicyDecision(hook(context), { defaultStatus, defaultError });
+  } catch (error) {
+    return {
+      allowed: false,
+      status: 500,
+      body: {
+        error: 'policy_hook_error',
+        hook: hookName,
+        message: error instanceof Error ? error.message : String(error),
+      },
+    };
+  }
+}