@canonmsg/core 0.15.2 → 0.15.3

package/dist/host-runtime.js

@@ -82,7 +82,7 @@ function describeContactCard(card) {
             ? 'reject pending requests'
             : null,
     ].filter(Boolean).join(', ');
-    const hint = `This host can inspect the card, but Canon admission actions are missing here. Missing capabilities: ${missingCapabilities}. Use another Canon surface for userId ${card.userId}.`;
+    const hint = `This host can inspect the card, but this wrapper does not expose callable Canon admission actions yet. Missing capabilities here: ${missingCapabilities}. Use an SDK/OpenClaw reach-out surface or another Canon client for userId ${card.userId}.`;
     return `${identity}\n${hint}`;
 }
 function describeAttachment(attachment, materialized) {

package/dist/index.d.ts

@@ -37,6 +37,8 @@ export type { HostInboundParticipantContext, } from './host-runtime.js';
 export { createRuntimeStatePublisher, } from './runtime-state-publisher.js';
 export type { RuntimeStatePublisher, RuntimeStatePublisherOptions, RuntimeStreamingPayload, } from './runtime-state-publisher.js';
 export { formatCanonMessageAsText } from './message-format.js';
+export { reachOutToCanonContact } from './reach-out.js';
+export type { CanonReachOutClient, CanonReachOutOptions, CanonReachOutResult, } from './reach-out.js';
 export { DEFAULT_BASE_URL, DEFAULT_STREAM_URL, DEFAULT_RTDB_URL, FIREBASE_WEB_API_KEY } from './constants.js';
 export { resolveCanonBaseUrl } from './base-url.js';
 export { handleCliMetadataRequest, isDirectExecution, readCliPackageVersion, runCli, } from './cli-metadata.js';

package/dist/index.js

@@ -35,6 +35,8 @@ export { buildCanonHostPrompt, buildHydratedInboundContext, createConversationMe
 export { createRuntimeStatePublisher, } from './runtime-state-publisher.js';
 // Message formatting (LLM-facing text projection)
 export { formatCanonMessageAsText } from './message-format.js';
+// Admission-aware reach-out helpers for runtime clients
+export { reachOutToCanonContact } from './reach-out.js';
 // Constants
 export { DEFAULT_BASE_URL, DEFAULT_STREAM_URL, DEFAULT_RTDB_URL, FIREBASE_WEB_API_KEY } from './constants.js';
 // Base URL resolver

package/dist/message-format.js

@@ -10,11 +10,12 @@
  * regression in every consumer plugin.
  */
 export function formatCanonMessageAsText(message) {
+    const trimmedText = typeof message.text === 'string' ? message.text.trim() : '';
     if (message.contentType === 'contact_card' && message.contactCard) {
-        return formatContactCard(message.contactCard);
+        const cardText = formatContactCard(message.contactCard);
+        return trimmedText ? `${cardText}\n${trimmedText}` : cardText;
     }
     const attachment = pickPrimaryAttachment(message.attachments);
-    const trimmedText = typeof message.text === 'string' ? message.text.trim() : '';
     if (attachment?.kind === 'image') {
         return trimmedText ? `[image] ${trimmedText}` : '[image]';
     }

package/dist/reach-out.d.ts

@@ -0,0 +1,37 @@
+import type { CanonResolveAdmissionResult, CreateContactRequestResult, CreateConversationOptions, SendMessageOptions } from './types.js';
+export interface CanonReachOutClient {
+    resolveAdmission(targetUserId: string): Promise<CanonResolveAdmissionResult>;
+    createConversation(options: CreateConversationOptions): Promise<{
+        conversationId: string;
+    }>;
+    sendMessage(conversationId: string, text: string, options?: SendMessageOptions): Promise<{
+        messageId: string;
+    }>;
+    createContactRequest(targetUserId: string, message?: string | null): Promise<CreateContactRequestResult>;
+}
+export interface CanonReachOutOptions {
+    targetUserId: string;
+    text?: string | null;
+    requestMessage?: string | null;
+    sendMessageOptions?: SendMessageOptions;
+}
+export type CanonReachOutResult = {
+    status: 'messaged';
+    conversationId: string;
+    messageId?: string;
+} | {
+    status: 'requested';
+    requestId: string | null;
+} | {
+    status: 'pending';
+    requestId: string | null;
+} | {
+    status: 'blocked' | 'unavailable';
+    reason: string;
+};
+/**
+ * Admission-aware direct reach-out for runtime clients. It deliberately keeps
+ * backend conversation creation fail-closed; callers choose this helper when
+ * their product behavior is "message if reachable, otherwise request access."
+ */
+export declare function reachOutToCanonContact(client: CanonReachOutClient, options: CanonReachOutOptions): Promise<CanonReachOutResult>;

package/dist/reach-out.js

@@ -0,0 +1,73 @@
+const CONTACT_REQUEST_MESSAGE_LIMIT = 500;
+function normalizeOptionalText(value) {
+    const trimmed = typeof value === 'string' ? value.trim() : '';
+    return trimmed.length > 0 ? trimmed : null;
+}
+function normalizeContactRequestMessage(requestMessage, fallbackText) {
+    const text = normalizeOptionalText(requestMessage) ?? normalizeOptionalText(fallbackText);
+    if (!text)
+        return null;
+    if (text.length <= CONTACT_REQUEST_MESSAGE_LIMIT)
+        return text;
+    return `${text.slice(0, CONTACT_REQUEST_MESSAGE_LIMIT - 3)}...`;
+}
+function isConnectionRequiredError(error) {
+    const status = error && typeof error === 'object' && 'status' in error
+        ? Number(error.status)
+        : null;
+    const message = error instanceof Error ? error.message : String(error ?? '');
+    return status === 403 && /CONNECTION_REQUIRED|connection required/i.test(message);
+}
+async function openConversationAndMaybeMessage(client, options) {
+    const { conversationId } = await client.createConversation({
+        type: 'direct',
+        targetUserId: options.targetUserId,
+    });
+    const text = normalizeOptionalText(options.text);
+    if (text) {
+        const { messageId } = options.sendMessageOptions
+            ? await client.sendMessage(conversationId, text, options.sendMessageOptions)
+            : await client.sendMessage(conversationId, text);
+        return { status: 'messaged', conversationId, messageId };
+    }
+    return { status: 'messaged', conversationId };
+}
+async function requestContact(client, options) {
+    const result = await client.createContactRequest(options.targetUserId, normalizeContactRequestMessage(options.requestMessage, options.text));
+    if (result.status === 'open') {
+        return openConversationAndMaybeMessage(client, { ...options, requestMessage: null });
+    }
+    if (result.status === 'duplicate') {
+        return { status: 'pending', requestId: result.requestId };
+    }
+    return { status: 'requested', requestId: result.requestId };
+}
+/**
+ * Admission-aware direct reach-out for runtime clients. It deliberately keeps
+ * backend conversation creation fail-closed; callers choose this helper when
+ * their product behavior is "message if reachable, otherwise request access."
+ */
+export async function reachOutToCanonContact(client, options) {
+    const { admission } = await client.resolveAdmission(options.targetUserId);
+    if (admission.state === 'allowed' && admission.canMessage) {
+        try {
+            return await openConversationAndMaybeMessage(client, options);
+        }
+        catch (error) {
+            if (isConnectionRequiredError(error)) {
+                return requestContact(client, options);
+            }
+            throw error;
+        }
+    }
+    if (admission.state === 'pending-outbound') {
+        return { status: 'pending', requestId: admission.pendingRequestId ?? null };
+    }
+    if (admission.state === 'request-required' && admission.canRequestContact) {
+        return requestContact(client, options);
+    }
+    if (admission.state === 'blocked') {
+        return { status: 'blocked', reason: 'blocked' };
+    }
+    return { status: 'unavailable', reason: admission.state };
+}

package/dist/types.d.ts

@@ -21,9 +21,9 @@ export interface ForwardedFrom {
 /**
  * Server-serialized contact-card payload. Emitted on messages with
  * `contentType: 'contact_card'` so agents receive the referenced user's
- * identity alongside the card. Agents use the referenced `userId` with the
- * standard send-message path; if the target's inbound policy blocks cold
- * contact, they first send a contact request and retry after approval.
+ * identity alongside the card. Agents use the referenced `userId` with an
+ * admission-aware reach-out path; if the target's inbound policy blocks cold
+ * contact, they create a contact request and retry after approval.
  */
 export interface ContactCardPayload {
     userId: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@canonmsg/core",
-  "version": "0.15.2",
+  "version": "0.15.3",
   "description": "Canon core — shared types, REST client, SSE stream, and registration for Canon messaging",
   "type": "module",
   "main": "dist/index.js",