agentchatme 1.0.21 → 1.0.22

package/dist/index.d.cts

@@ -79,6 +79,30 @@ interface MessageContent {
      */
     attachment_id?: string;
 }
+type MessageSenderKind = 'agent' | 'system';
+/**
+ * Platform-AUTHORED trusted context attached to a delivered message. Distinct
+ * from `metadata` (sender-authored, untrusted): this block is asserted by the
+ * server and is safe to rely on for identity/routing. Lets a stateless agent
+ * orient — who the sender really is (not just a handle), what room this is
+ * (DM vs group, the group's NAME + size), and who was @-mentioned — without a
+ * round-trip. Optional: messages predating the enrichment omit it.
+ */
+interface MessageContext {
+    sender: {
+        handle: string;
+        display_name: string | null;
+        kind: MessageSenderKind;
+    };
+    conversation: {
+        type: 'direct' | 'group';
+        group_name: string | null;
+        member_count: number | null;
+    };
+    /** Handles @-mentioned, parsed server-side (word-boundary). Test your OWN
+     *  handle for membership — never substring-match the raw text. */
+    mentions: string[];
+}
 interface Message {
     id: string;
     conversation_id: string;
@@ -88,6 +112,8 @@ interface Message {
     type: MessageType;
     content: MessageContent;
     metadata: Record<string, unknown>;
+    /** Platform-authored trusted context (see {@link MessageContext}). */
+    context?: MessageContext;
     status: MessageStatus;
     created_at: string;
     delivered_at: string | null;
@@ -1555,6 +1581,19 @@ declare function verifyWebhook(options: VerifyWebhookOptions): Promise<WebhookPa
  */
 declare function parseRetryAfter(raw: string | null | undefined): number | null;
 
+interface RenderOptions {
+    /** This agent's handle; enables the "you were @-mentioned" line in groups. */
+    selfHandle?: string;
+    /** Wall-clock override (epoch ms) for deterministic relative time in tests. */
+    now?: number;
+}
+/**
+ * Render a received message's trusted context + body into a model-facing block.
+ * Degrades gracefully when the server sent no `context` (falls back to the bare
+ * `sender` handle and omits identity/room lines it can't assert).
+ */
+declare function renderMessageContext(message: Pick<Message, 'sender' | 'created_at' | 'content' | 'context'>, opts?: RenderOptions): string;
+
 declare const VERSION: string;
 
-export { ALLOWED_ATTACHMENT_MIME, type AddContactRequest, type AddMemberRequest, type AddMemberResult, type Agent, AgentChatClient, type AgentChatClientOptions, AgentChatError, type AgentChatErrorResponse, type AgentProfile, type AgentSettings, type AgentStatus, type ApiError, type AttachmentMime, AwaitingReplyError, type BacklogWarning, type BacklogWarningHandler, type BlockedAgent, BlockedError, type CallOptions, type ClientAction, type ConnectHandler, ConnectionError, type Contact, type Conversation, type ConversationListItem, type ConversationParticipant, type ConversationType, type CreateGroupRequest, type CreateUploadRequest, type CreateUploadResponse, type CreateWebhookRequest, DEFAULT_RETRY_POLICY, type DeletedGroupInfo, type DisconnectHandler, ErrorCode, type ErrorHandler, type ErrorInfo, ForbiddenError, type Group, GroupDeletedError, type GroupDetail, type GroupInvitation, type GroupInvitePolicy, type GroupInviteRule, type GroupMember, type GroupRole, type GroupSettings, type GroupSystemEvent, type GroupSystemEventV1, type HttpMethod, type HttpRequestOptions, type HttpResponse, HttpTransport, type HttpTransportOptions, type InboxMode, MAX_ATTACHMENT_SIZE, type Message, type MessageContent, type MessageHandler, type MessageStatus, type MessageType, type MuteEntry, type MuteTargetKind, NotFoundError, type PausedByOwner, type Presence, type PresenceBatchRequest, type PresenceBroadcast, type PresenceStatus, type PresenceUpdate, RateLimitedError, RealtimeClient, type RealtimeOptions, RecipientBackloggedError, type RegisterRequest, type ReportRequest, type RequestHooks, type RequestInfo, type ResponseInfo, RestrictedError, type RetryInfo, type RetryOption, type RetryPolicy, type SendMessageRequest, type SendMessageResult, type SequenceGapHandler, type SequenceGapInfo, ServerError, type ServerEvent, SuspendedError, type SyncEnvelope, UnauthorizedError, type UpdateAgentRequest, type UpdateContactRequest, type UpdateGroupRequest, VERSION, ValidationError, type VerifyRequest, type VerifyWebhookOptions, type WebhookConfig, type WebhookEvent, type WebhookPayload, WebhookVerificationError, type WsMessage, createAgentChatError, paginate, parseRetryAfter, verifyWebhook };
+export { ALLOWED_ATTACHMENT_MIME, type AddContactRequest, type AddMemberRequest, type AddMemberResult, type Agent, AgentChatClient, type AgentChatClientOptions, AgentChatError, type AgentChatErrorResponse, type AgentProfile, type AgentSettings, type AgentStatus, type ApiError, type AttachmentMime, AwaitingReplyError, type BacklogWarning, type BacklogWarningHandler, type BlockedAgent, BlockedError, type CallOptions, type ClientAction, type ConnectHandler, ConnectionError, type Contact, type Conversation, type ConversationListItem, type ConversationParticipant, type ConversationType, type CreateGroupRequest, type CreateUploadRequest, type CreateUploadResponse, type CreateWebhookRequest, DEFAULT_RETRY_POLICY, type DeletedGroupInfo, type DisconnectHandler, ErrorCode, type ErrorHandler, type ErrorInfo, ForbiddenError, type Group, GroupDeletedError, type GroupDetail, type GroupInvitation, type GroupInvitePolicy, type GroupInviteRule, type GroupMember, type GroupRole, type GroupSettings, type GroupSystemEvent, type GroupSystemEventV1, type HttpMethod, type HttpRequestOptions, type HttpResponse, HttpTransport, type HttpTransportOptions, type InboxMode, MAX_ATTACHMENT_SIZE, type Message, type MessageContent, type MessageHandler, type MessageStatus, type MessageType, type MuteEntry, type MuteTargetKind, NotFoundError, type PausedByOwner, type Presence, type PresenceBatchRequest, type PresenceBroadcast, type PresenceStatus, type PresenceUpdate, RateLimitedError, RealtimeClient, type RealtimeOptions, RecipientBackloggedError, type RegisterRequest, type RenderOptions, type ReportRequest, type RequestHooks, type RequestInfo, type ResponseInfo, RestrictedError, type RetryInfo, type RetryOption, type RetryPolicy, type SendMessageRequest, type SendMessageResult, type SequenceGapHandler, type SequenceGapInfo, ServerError, type ServerEvent, SuspendedError, type SyncEnvelope, UnauthorizedError, type UpdateAgentRequest, type UpdateContactRequest, type UpdateGroupRequest, VERSION, ValidationError, type VerifyRequest, type VerifyWebhookOptions, type WebhookConfig, type WebhookEvent, type WebhookPayload, WebhookVerificationError, type WsMessage, createAgentChatError, paginate, parseRetryAfter, renderMessageContext, verifyWebhook };

package/dist/index.d.ts

@@ -79,6 +79,30 @@ interface MessageContent {
      */
     attachment_id?: string;
 }
+type MessageSenderKind = 'agent' | 'system';
+/**
+ * Platform-AUTHORED trusted context attached to a delivered message. Distinct
+ * from `metadata` (sender-authored, untrusted): this block is asserted by the
+ * server and is safe to rely on for identity/routing. Lets a stateless agent
+ * orient — who the sender really is (not just a handle), what room this is
+ * (DM vs group, the group's NAME + size), and who was @-mentioned — without a
+ * round-trip. Optional: messages predating the enrichment omit it.
+ */
+interface MessageContext {
+    sender: {
+        handle: string;
+        display_name: string | null;
+        kind: MessageSenderKind;
+    };
+    conversation: {
+        type: 'direct' | 'group';
+        group_name: string | null;
+        member_count: number | null;
+    };
+    /** Handles @-mentioned, parsed server-side (word-boundary). Test your OWN
+     *  handle for membership — never substring-match the raw text. */
+    mentions: string[];
+}
 interface Message {
     id: string;
     conversation_id: string;
@@ -88,6 +112,8 @@ interface Message {
     type: MessageType;
     content: MessageContent;
     metadata: Record<string, unknown>;
+    /** Platform-authored trusted context (see {@link MessageContext}). */
+    context?: MessageContext;
     status: MessageStatus;
     created_at: string;
     delivered_at: string | null;
@@ -1555,6 +1581,19 @@ declare function verifyWebhook(options: VerifyWebhookOptions): Promise<WebhookPa
  */
 declare function parseRetryAfter(raw: string | null | undefined): number | null;
 
+interface RenderOptions {
+    /** This agent's handle; enables the "you were @-mentioned" line in groups. */
+    selfHandle?: string;
+    /** Wall-clock override (epoch ms) for deterministic relative time in tests. */
+    now?: number;
+}
+/**
+ * Render a received message's trusted context + body into a model-facing block.
+ * Degrades gracefully when the server sent no `context` (falls back to the bare
+ * `sender` handle and omits identity/room lines it can't assert).
+ */
+declare function renderMessageContext(message: Pick<Message, 'sender' | 'created_at' | 'content' | 'context'>, opts?: RenderOptions): string;
+
 declare const VERSION: string;
 
-export { ALLOWED_ATTACHMENT_MIME, type AddContactRequest, type AddMemberRequest, type AddMemberResult, type Agent, AgentChatClient, type AgentChatClientOptions, AgentChatError, type AgentChatErrorResponse, type AgentProfile, type AgentSettings, type AgentStatus, type ApiError, type AttachmentMime, AwaitingReplyError, type BacklogWarning, type BacklogWarningHandler, type BlockedAgent, BlockedError, type CallOptions, type ClientAction, type ConnectHandler, ConnectionError, type Contact, type Conversation, type ConversationListItem, type ConversationParticipant, type ConversationType, type CreateGroupRequest, type CreateUploadRequest, type CreateUploadResponse, type CreateWebhookRequest, DEFAULT_RETRY_POLICY, type DeletedGroupInfo, type DisconnectHandler, ErrorCode, type ErrorHandler, type ErrorInfo, ForbiddenError, type Group, GroupDeletedError, type GroupDetail, type GroupInvitation, type GroupInvitePolicy, type GroupInviteRule, type GroupMember, type GroupRole, type GroupSettings, type GroupSystemEvent, type GroupSystemEventV1, type HttpMethod, type HttpRequestOptions, type HttpResponse, HttpTransport, type HttpTransportOptions, type InboxMode, MAX_ATTACHMENT_SIZE, type Message, type MessageContent, type MessageHandler, type MessageStatus, type MessageType, type MuteEntry, type MuteTargetKind, NotFoundError, type PausedByOwner, type Presence, type PresenceBatchRequest, type PresenceBroadcast, type PresenceStatus, type PresenceUpdate, RateLimitedError, RealtimeClient, type RealtimeOptions, RecipientBackloggedError, type RegisterRequest, type ReportRequest, type RequestHooks, type RequestInfo, type ResponseInfo, RestrictedError, type RetryInfo, type RetryOption, type RetryPolicy, type SendMessageRequest, type SendMessageResult, type SequenceGapHandler, type SequenceGapInfo, ServerError, type ServerEvent, SuspendedError, type SyncEnvelope, UnauthorizedError, type UpdateAgentRequest, type UpdateContactRequest, type UpdateGroupRequest, VERSION, ValidationError, type VerifyRequest, type VerifyWebhookOptions, type WebhookConfig, type WebhookEvent, type WebhookPayload, WebhookVerificationError, type WsMessage, createAgentChatError, paginate, parseRetryAfter, verifyWebhook };
+export { ALLOWED_ATTACHMENT_MIME, type AddContactRequest, type AddMemberRequest, type AddMemberResult, type Agent, AgentChatClient, type AgentChatClientOptions, AgentChatError, type AgentChatErrorResponse, type AgentProfile, type AgentSettings, type AgentStatus, type ApiError, type AttachmentMime, AwaitingReplyError, type BacklogWarning, type BacklogWarningHandler, type BlockedAgent, BlockedError, type CallOptions, type ClientAction, type ConnectHandler, ConnectionError, type Contact, type Conversation, type ConversationListItem, type ConversationParticipant, type ConversationType, type CreateGroupRequest, type CreateUploadRequest, type CreateUploadResponse, type CreateWebhookRequest, DEFAULT_RETRY_POLICY, type DeletedGroupInfo, type DisconnectHandler, ErrorCode, type ErrorHandler, type ErrorInfo, ForbiddenError, type Group, GroupDeletedError, type GroupDetail, type GroupInvitation, type GroupInvitePolicy, type GroupInviteRule, type GroupMember, type GroupRole, type GroupSettings, type GroupSystemEvent, type GroupSystemEventV1, type HttpMethod, type HttpRequestOptions, type HttpResponse, HttpTransport, type HttpTransportOptions, type InboxMode, MAX_ATTACHMENT_SIZE, type Message, type MessageContent, type MessageHandler, type MessageStatus, type MessageType, type MuteEntry, type MuteTargetKind, NotFoundError, type PausedByOwner, type Presence, type PresenceBatchRequest, type PresenceBroadcast, type PresenceStatus, type PresenceUpdate, RateLimitedError, RealtimeClient, type RealtimeOptions, RecipientBackloggedError, type RegisterRequest, type RenderOptions, type ReportRequest, type RequestHooks, type RequestInfo, type ResponseInfo, RestrictedError, type RetryInfo, type RetryOption, type RetryPolicy, type SendMessageRequest, type SendMessageResult, type SequenceGapHandler, type SequenceGapInfo, ServerError, type ServerEvent, SuspendedError, type SyncEnvelope, UnauthorizedError, type UpdateAgentRequest, type UpdateContactRequest, type UpdateGroupRequest, VERSION, ValidationError, type VerifyRequest, type VerifyWebhookOptions, type WebhookConfig, type WebhookEvent, type WebhookPayload, WebhookVerificationError, type WsMessage, createAgentChatError, paginate, parseRetryAfter, renderMessageContext, verifyWebhook };

package/dist/index.js

@@ -210,7 +210,7 @@ function createAgentChatError(body, status, headers) {
 }
 
 // src/version.ts
-var VERSION = "1.0.21" ;
+var VERSION = "1.0.22" ;
 
 // src/runtime.ts
 function detectRuntime() {
@@ -2235,6 +2235,57 @@ function constantTimeEqual(a, b) {
   return mismatch === 0;
 }
 
+// src/render.ts
+var SEC = 1e3;
+var MIN = 60 * SEC;
+var HOUR = 60 * MIN;
+var DAY = 24 * HOUR;
+function relativeAge(ms) {
+  if (ms < 45 * SEC) return "just now";
+  if (ms < 90 * SEC) return "1 minute ago";
+  if (ms < 45 * MIN) return `${Math.round(ms / MIN)} minutes ago`;
+  if (ms < 90 * MIN) return "1 hour ago";
+  if (ms < 22 * HOUR) return `${Math.round(ms / HOUR)} hours ago`;
+  if (ms < 36 * HOUR) return "1 day ago";
+  return `${Math.round(ms / DAY)} days ago`;
+}
+function formatReceived(createdAt, now2) {
+  const t = Date.parse(createdAt);
+  if (Number.isNaN(t)) return "an unknown time";
+  const iso = new Date(t).toISOString();
+  const abs = `${iso.slice(0, 10)} ${iso.slice(11, 16)} UTC`;
+  return `${relativeAge(Math.max(0, now2 - t))} (${abs})`;
+}
+function renderMessageContext(message, opts = {}) {
+  const now2 = opts.now ?? Date.now();
+  const ctx = message.context;
+  const lines = [];
+  const handle = ctx?.sender.handle ?? message.sender;
+  const name = ctx?.sender.display_name;
+  const who = name ? `${name} (@${handle})` : `@${handle}`;
+  lines.push(`From: ${ctx?.sender.kind === "system" ? `${who}, a system agent` : who}`);
+  const conv = ctx?.conversation;
+  if (conv) {
+    if (conv.type === "group") {
+      let label = conv.group_name ? `group "${conv.group_name}"` : "group";
+      if (conv.member_count != null) {
+        label += ` (${conv.member_count} member${conv.member_count === 1 ? "" : "s"})`;
+      }
+      lines.push(`Conversation: ${label}`);
+    } else {
+      lines.push("Conversation: direct message");
+    }
+  }
+  lines.push(`Received: ${formatReceived(message.created_at, now2)}`);
+  const self = opts.selfHandle?.replace(/^@/, "").toLowerCase();
+  if (self && conv?.type === "group" && (ctx?.mentions ?? []).includes(self)) {
+    lines.push("You were @-mentioned in this message.");
+  }
+  const text = message.content?.text;
+  lines.push("", text ? text : `(a ${"non-text"} message \u2014 no text body)`);
+  return lines.join("\n");
+}
+
 // src/types/attachment.ts
 var MAX_ATTACHMENT_SIZE = 25 * 1024 * 1024;
 var ALLOWED_ATTACHMENT_MIME = [
@@ -2254,6 +2305,6 @@ var ALLOWED_ATTACHMENT_MIME = [
   "video/webm"
 ];
 
-export { ALLOWED_ATTACHMENT_MIME, AgentChatClient, AgentChatError, AwaitingReplyError, BlockedError, ConnectionError, DEFAULT_RETRY_POLICY, ErrorCode, ForbiddenError, GroupDeletedError, HttpTransport, MAX_ATTACHMENT_SIZE, NotFoundError, RateLimitedError, RealtimeClient, RecipientBackloggedError, RestrictedError, ServerError, SuspendedError, UnauthorizedError, VERSION, ValidationError, WebhookVerificationError, createAgentChatError, paginate, parseRetryAfter, verifyWebhook };
+export { ALLOWED_ATTACHMENT_MIME, AgentChatClient, AgentChatError, AwaitingReplyError, BlockedError, ConnectionError, DEFAULT_RETRY_POLICY, ErrorCode, ForbiddenError, GroupDeletedError, HttpTransport, MAX_ATTACHMENT_SIZE, NotFoundError, RateLimitedError, RealtimeClient, RecipientBackloggedError, RestrictedError, ServerError, SuspendedError, UnauthorizedError, VERSION, ValidationError, WebhookVerificationError, createAgentChatError, paginate, parseRetryAfter, renderMessageContext, verifyWebhook };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map