@canonmsg/backend-contracts 8.0.0 → 8.1.0

package/dist/agentBehaviorPolicy.d.ts

@@ -81,32 +81,24 @@ export interface ParticipationHistorySnapshot {
 }
 export declare const PARTICIPATION_HISTORY_FETCH_LIMIT = 50;
 /**
- * Safety backstop for groups with no explicit turn cap: at most this many
- * consecutive agent turns before a human has to speak again.
+ * Safety backstop for conversations with no explicit turn cap: at most this
+ * many consecutive agent turns before a human speaks or a new conversation
+ * starts.
  *
  * This is a backstop, not the steering wheel — agents are expected to stop on
- * their own. Direct conversations deliberately stay unlimited: only a non-agent
- * message resets the streak, so a default cap in a pure agent-to-agent DM would
- * halt the room permanently instead of merely bounding a loop.
- *
- * The same caveat applies to the one group shape this default does cover: a
- * group whose members are all agents (reachable — agent-created groups need no
- * human member) has nothing that resets the streak, so it stops auto-replying
- * for good once the cap is reached. That is deliberate: an unattended room is
- * where a runaway loop is most expensive. Recovery needs a human member — the
- * per-conversation `null` opt-out is writable only by a group owner or admin,
- * who must be a member. Teaching the resolver "does this room contain a
- * human?" would mean loading member types at every resolution site, including
- * the stream gate, which does not read them today.
+ * their own. Every triggerable agent message counts in both direct and group
+ * conversations. An explicit `null` remains the deployer opt-out for trusted,
+ * intentionally long-running collaboration.
  */
 export declare const DEFAULT_GROUP_MAX_CONSECUTIVE_AGENT_TURNS = 4;
+export declare const DEFAULT_DIRECT_MAX_CONSECUTIVE_AGENT_TURNS = 4;
 export declare function parseAgentBehaviorSettings(raw: unknown): AgentBehaviorSettingsRecord;
 export declare function normalizeStoredAgentBehaviorPolicy(raw: Record<string, unknown> | undefined): AgentBehaviorSettingsRecord | null;
 export declare function normalizeAgentBehaviorInstructions(value: string | null | undefined): string | null;
 /**
  * The scope-independent participation defaults. `maxConsecutiveAgentTurns` is
- * `null` here because the turn cap is scope-dependent — a group with no stored
- * setting resolves to {@link DEFAULT_GROUP_MAX_CONSECUTIVE_AGENT_TURNS}. Use
+ * `null` here because the turn cap is scope-dependent — a conversation with no
+ * stored setting resolves to its direct or group safety default. Use
  * {@link resolveAgentBehaviorPolicy} with a `conversationType` to learn what a
  * given conversation actually enforces.
  */
@@ -114,9 +106,9 @@ export declare function getDefaultParticipationPolicy(): ParticipationPolicy;
 /**
  * Coalesce agent defaults and a conversation override into the resolved record
  * every runtime reads. `conversationType` selects the Canon-wide fallbacks that
- * differ per scope — today only the turn cap, which defaults to
- * {@link DEFAULT_GROUP_MAX_CONSECUTIVE_AGENT_TURNS} in groups and to unlimited
- * everywhere else. Omit it when resolving for the agent scope (no conversation);
+ * differ per scope — today only the turn cap, which defaults to 4 in direct and
+ * group conversations and to unlimited elsewhere. Omit it when resolving for
+ * the agent scope (no conversation);
  * an absent or unknown type always resolves to the unlimited default, so a call
  * site that forgets to thread it can never invent a cap.
  */

package/dist/agentBehaviorPolicy.js

@@ -1,29 +1,25 @@
 import { shouldTriggerAgentTurn } from './turnProtocol.js';
 export const PARTICIPATION_HISTORY_FETCH_LIMIT = 50;
 /**
- * Safety backstop for groups with no explicit turn cap: at most this many
- * consecutive agent turns before a human has to speak again.
+ * Safety backstop for conversations with no explicit turn cap: at most this
+ * many consecutive agent turns before a human speaks or a new conversation
+ * starts.
  *
  * This is a backstop, not the steering wheel — agents are expected to stop on
- * their own. Direct conversations deliberately stay unlimited: only a non-agent
- * message resets the streak, so a default cap in a pure agent-to-agent DM would
- * halt the room permanently instead of merely bounding a loop.
- *
- * The same caveat applies to the one group shape this default does cover: a
- * group whose members are all agents (reachable — agent-created groups need no
- * human member) has nothing that resets the streak, so it stops auto-replying
- * for good once the cap is reached. That is deliberate: an unattended room is
- * where a runaway loop is most expensive. Recovery needs a human member — the
- * per-conversation `null` opt-out is writable only by a group owner or admin,
- * who must be a member. Teaching the resolver "does this room contain a
- * human?" would mean loading member types at every resolution site, including
- * the stream gate, which does not read them today.
+ * their own. Every triggerable agent message counts in both direct and group
+ * conversations. An explicit `null` remains the deployer opt-out for trusted,
+ * intentionally long-running collaboration.
  */
 export const DEFAULT_GROUP_MAX_CONSECUTIVE_AGENT_TURNS = 4;
+export const DEFAULT_DIRECT_MAX_CONSECUTIVE_AGENT_TURNS = 4;
 function defaultMaxConsecutiveAgentTurns(conversationType) {
-    return conversationType === 'group'
-        ? DEFAULT_GROUP_MAX_CONSECUTIVE_AGENT_TURNS
-        : null;
+    if (conversationType === 'group') {
+        return DEFAULT_GROUP_MAX_CONSECUTIVE_AGENT_TURNS;
+    }
+    if (conversationType === 'direct') {
+        return DEFAULT_DIRECT_MAX_CONSECUTIVE_AGENT_TURNS;
+    }
+    return null;
 }
 const VALID_PARTICIPATION_STYLES = new Set([
     'natural',
@@ -146,8 +142,8 @@ export function normalizeAgentBehaviorInstructions(value) {
 }
 /**
  * The scope-independent participation defaults. `maxConsecutiveAgentTurns` is
- * `null` here because the turn cap is scope-dependent — a group with no stored
- * setting resolves to {@link DEFAULT_GROUP_MAX_CONSECUTIVE_AGENT_TURNS}. Use
+ * `null` here because the turn cap is scope-dependent — a conversation with no
+ * stored setting resolves to its direct or group safety default. Use
  * {@link resolveAgentBehaviorPolicy} with a `conversationType` to learn what a
  * given conversation actually enforces.
  */
@@ -157,9 +153,9 @@ export function getDefaultParticipationPolicy() {
 /**
  * Coalesce agent defaults and a conversation override into the resolved record
  * every runtime reads. `conversationType` selects the Canon-wide fallbacks that
- * differ per scope — today only the turn cap, which defaults to
- * {@link DEFAULT_GROUP_MAX_CONSECUTIVE_AGENT_TURNS} in groups and to unlimited
- * everywhere else. Omit it when resolving for the agent scope (no conversation);
+ * differ per scope — today only the turn cap, which defaults to 4 in direct and
+ * group conversations and to unlimited elsewhere. Omit it when resolving for
+ * the agent scope (no conversation);
  * an absent or unknown type always resolves to the unlimited default, so a call
  * site that forgets to thread it can never invent a cap.
  */

package/dist/agentDirectory.d.ts

@@ -0,0 +1,29 @@
+import type { CommunicationRule } from './communication.js';
+/** Shared paging bounds for Canon's discoverable-agent directory. */
+export declare const DEFAULT_DISCOVER_AGENTS_LIMIT = 20;
+export declare const MAX_DISCOVER_AGENTS_LIMIT = 25;
+export declare const MAX_DISCOVER_AGENTS_QUERY_LENGTH = 64;
+export interface DiscoverAgentsInput {
+    query?: string;
+    limit?: number;
+    cursor?: string | null;
+}
+/** Public, addressable identity returned to an authenticated agent caller. */
+export interface CanonAgentDirectoryEntry {
+    principalId: string;
+    canonContactId?: string;
+    displayName?: string;
+    description?: string;
+    /** Human principal accountable for this agent. */
+    owner: {
+        principalId: string;
+        displayName?: string;
+    };
+    inboundPolicy?: CommunicationRule;
+    groupJoinPolicy?: CommunicationRule;
+    shareable: boolean;
+}
+export interface DiscoverAgentsResult {
+    agents: CanonAgentDirectoryEntry[];
+    nextCursor: string | null;
+}

package/dist/agentDirectory.js

@@ -0,0 +1,4 @@
+/** Shared paging bounds for Canon's discoverable-agent directory. */
+export const DEFAULT_DISCOVER_AGENTS_LIMIT = 20;
+export const MAX_DISCOVER_AGENTS_LIMIT = 25;
+export const MAX_DISCOVER_AGENTS_QUERY_LENGTH = 64;

package/dist/cjs/agentBehaviorPolicy.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.DEFAULT_GROUP_MAX_CONSECUTIVE_AGENT_TURNS = exports.PARTICIPATION_HISTORY_FETCH_LIMIT = void 0;
+exports.DEFAULT_DIRECT_MAX_CONSECUTIVE_AGENT_TURNS = exports.DEFAULT_GROUP_MAX_CONSECUTIVE_AGENT_TURNS = exports.PARTICIPATION_HISTORY_FETCH_LIMIT = void 0;
 exports.parseAgentBehaviorSettings = parseAgentBehaviorSettings;
 exports.normalizeStoredAgentBehaviorPolicy = normalizeStoredAgentBehaviorPolicy;
 exports.normalizeAgentBehaviorInstructions = normalizeAgentBehaviorInstructions;
@@ -12,29 +12,25 @@ exports.evaluateParticipationPolicy = evaluateParticipationPolicy;
 const turnProtocol_js_1 = require("./turnProtocol.js");
 exports.PARTICIPATION_HISTORY_FETCH_LIMIT = 50;
 /**
- * Safety backstop for groups with no explicit turn cap: at most this many
- * consecutive agent turns before a human has to speak again.
+ * Safety backstop for conversations with no explicit turn cap: at most this
+ * many consecutive agent turns before a human speaks or a new conversation
+ * starts.
  *
  * This is a backstop, not the steering wheel — agents are expected to stop on
- * their own. Direct conversations deliberately stay unlimited: only a non-agent
- * message resets the streak, so a default cap in a pure agent-to-agent DM would
- * halt the room permanently instead of merely bounding a loop.
- *
- * The same caveat applies to the one group shape this default does cover: a
- * group whose members are all agents (reachable — agent-created groups need no
- * human member) has nothing that resets the streak, so it stops auto-replying
- * for good once the cap is reached. That is deliberate: an unattended room is
- * where a runaway loop is most expensive. Recovery needs a human member — the
- * per-conversation `null` opt-out is writable only by a group owner or admin,
- * who must be a member. Teaching the resolver "does this room contain a
- * human?" would mean loading member types at every resolution site, including
- * the stream gate, which does not read them today.
+ * their own. Every triggerable agent message counts in both direct and group
+ * conversations. An explicit `null` remains the deployer opt-out for trusted,
+ * intentionally long-running collaboration.
  */
 exports.DEFAULT_GROUP_MAX_CONSECUTIVE_AGENT_TURNS = 4;
+exports.DEFAULT_DIRECT_MAX_CONSECUTIVE_AGENT_TURNS = 4;
 function defaultMaxConsecutiveAgentTurns(conversationType) {
-    return conversationType === 'group'
-        ? exports.DEFAULT_GROUP_MAX_CONSECUTIVE_AGENT_TURNS
-        : null;
+    if (conversationType === 'group') {
+        return exports.DEFAULT_GROUP_MAX_CONSECUTIVE_AGENT_TURNS;
+    }
+    if (conversationType === 'direct') {
+        return exports.DEFAULT_DIRECT_MAX_CONSECUTIVE_AGENT_TURNS;
+    }
+    return null;
 }
 const VALID_PARTICIPATION_STYLES = new Set([
     'natural',
@@ -157,8 +153,8 @@ function normalizeAgentBehaviorInstructions(value) {
 }
 /**
  * The scope-independent participation defaults. `maxConsecutiveAgentTurns` is
- * `null` here because the turn cap is scope-dependent — a group with no stored
- * setting resolves to {@link DEFAULT_GROUP_MAX_CONSECUTIVE_AGENT_TURNS}. Use
+ * `null` here because the turn cap is scope-dependent — a conversation with no
+ * stored setting resolves to its direct or group safety default. Use
  * {@link resolveAgentBehaviorPolicy} with a `conversationType` to learn what a
  * given conversation actually enforces.
  */
@@ -168,9 +164,9 @@ function getDefaultParticipationPolicy() {
 /**
  * Coalesce agent defaults and a conversation override into the resolved record
  * every runtime reads. `conversationType` selects the Canon-wide fallbacks that
- * differ per scope — today only the turn cap, which defaults to
- * {@link DEFAULT_GROUP_MAX_CONSECUTIVE_AGENT_TURNS} in groups and to unlimited
- * everywhere else. Omit it when resolving for the agent scope (no conversation);
+ * differ per scope — today only the turn cap, which defaults to 4 in direct and
+ * group conversations and to unlimited elsewhere. Omit it when resolving for
+ * the agent scope (no conversation);
  * an absent or unknown type always resolves to the unlimited default, so a call
  * site that forgets to thread it can never invent a cap.
  */

package/dist/cjs/agentDirectory.js

@@ -0,0 +1,7 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_DISCOVER_AGENTS_QUERY_LENGTH = exports.MAX_DISCOVER_AGENTS_LIMIT = exports.DEFAULT_DISCOVER_AGENTS_LIMIT = void 0;
+/** Shared paging bounds for Canon's discoverable-agent directory. */
+exports.DEFAULT_DISCOVER_AGENTS_LIMIT = 20;
+exports.MAX_DISCOVER_AGENTS_LIMIT = 25;
+exports.MAX_DISCOVER_AGENTS_QUERY_LENGTH = 64;

package/dist/cjs/index.js

@@ -24,6 +24,7 @@ __exportStar(require("./runtimeCardStorage.js"), exports);
 __exportStar(require("./turnProtocol.js"), exports);
 __exportStar(require("./agentBehaviorPolicy.js"), exports);
 __exportStar(require("./agentSearch.js"), exports);
+__exportStar(require("./agentDirectory.js"), exports);
 __exportStar(require("./verbContract.js"), exports);
 __exportStar(require("./verbSchemas.js"), exports);
 __exportStar(require("./verbWire.js"), exports);

package/dist/communication.d.ts

@@ -1,3 +1,4 @@
+import type { DiscoverAgentsInput, DiscoverAgentsResult } from './agentDirectory.js';
 /** The deliberately small policy vocabulary for principal communication. */
 export type CommunicationRule = 'open' | 'approval-required' | 'closed';
 /** Missing or invalid policy never widens access. */
@@ -11,7 +12,9 @@ export type DirectConversationSelection = {
     mode: 'specific';
     conversationId: string;
 };
-export type CommunicateInput = {
+export type CommunicateInput = ({
+    action: 'discover_agents';
+} & DiscoverAgentsInput) | {
     action: 'message_existing';
     conversationId: string;
     text: string;
@@ -44,7 +47,9 @@ export type CommunicateInput = {
     userId: string;
     operation: 'add' | 'remove';
 };
-export type CommunicateResult = {
+export type CommunicateResult = ({
+    status: 'discovered';
+} & DiscoverAgentsResult) | {
     status: 'messaged';
     conversationId: string;
     messageId: string;

package/dist/index.d.ts

@@ -8,6 +8,7 @@ export * from './runtimeCardStorage.js';
 export * from './turnProtocol.js';
 export * from './agentBehaviorPolicy.js';
 export * from './agentSearch.js';
+export * from './agentDirectory.js';
 export * from './verbContract.js';
 export * from './verbSchemas.js';
 export * from './verbWire.js';

package/dist/index.js

@@ -8,6 +8,7 @@ export * from './runtimeCardStorage.js';
 export * from './turnProtocol.js';
 export * from './agentBehaviorPolicy.js';
 export * from './agentSearch.js';
+export * from './agentDirectory.js';
 export * from './verbContract.js';
 export * from './verbSchemas.js';
 export * from './verbWire.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@canonmsg/backend-contracts",
-  "version": "8.0.0",
+  "version": "8.1.0",
   "description": "Canon backend contract helpers shared by Functions and stream-service",
   "type": "module",
   "main": "dist/cjs/index.js",