@adecore/agents 0.37.2 → 0.37.3

package/dist/chat/chat-session.d.ts

@@ -24,8 +24,14 @@ export interface PromptNotes {
     };
     reset(): void;
 }
-export type ChatReferences = (ids: readonly string[] | undefined) => {
-    ids: string[];
+export interface ChatAttached {
+    chats: string[];
+    references: string[];
+}
+export type ChatReferences = (attached: {
+    readonly chats?: readonly string[];
+    readonly references?: readonly string[];
+}) => ChatAttached & {
     note: string | null;
 };
 export interface ChatSessionOptions {
@@ -74,6 +80,7 @@ export interface ChatSendExtras {
     chats?: string[];
     quoteSource?: ChatQuoteSource;
     attachments?: ChatAttachment[];
+    references?: string[];
 }
 export interface ResumeWords {
     prompt: string;
@@ -152,6 +159,7 @@ export declare class ChatSession {
     };
     private recordUiAnswer;
     private vetted;
+    private attached;
     sendInput(text: string, extras?: ChatSendExtras): Promise<{
         queued: boolean;
         turnId: string;

package/dist/chat/chat-session.js

@@ -260,7 +260,8 @@ export class ChatSession {
                 ...(extras.skills?.length ? { skills: extras.skills } : {}),
                 ...(extras.chats?.length ? { chats: extras.chats } : {}),
                 ...(extras.quoteSource ? { quoteSource: extras.quoteSource } : {}),
-                ...(extras.attachments?.length ? { attachments: extras.attachments } : {})
+                ...(extras.attachments?.length ? { attachments: extras.attachments } : {}),
+                ...(extras.references?.length ? { references: extras.references } : {})
             };
             this.setQueue([...this.queue, message]);
             this.lapseResume();
@@ -364,6 +365,14 @@ export class ChatSession {
         delete plain.quoteSource;
         return plain;
     }
+    /* The chats and views a message pointed at as the host names them; without a host's `references` they are dropped. */
+    attached(text, extras) {
+        // A slash command must stay the first thing the CLI reads, as `contextNote` keeps it.
+        if (text.startsWith('/') || !this.options.references) {
+            return { chats: [], references: [], note: null };
+        }
+        return this.options.references({ chats: extras.chats, references: extras.references });
+    }
     sendInput(text, extras = {}) {
         return this.submitInput(text, extras);
     }
@@ -411,11 +420,11 @@ export class ChatSession {
     }
     async steer(message, text, extras, steerTurn, turnId, queued) {
         try {
-            const references = this.options.references?.(extras.chats) ?? { ids: extras.chats ?? [], note: null };
+            const attached = this.attached(text, extras);
             const accepted = await steerTurn({
                 promptId: message.id,
                 text,
-                preamble: references.note,
+                preamble: attached.note,
                 attachments: extras.attachments ?? [],
                 mentions: extras.mentions ?? [],
                 skills: extras.skills ?? []
@@ -432,9 +441,10 @@ export class ChatSession {
                     text,
                     mentions: extras.mentions,
                     skills: extras.skills,
-                    chats: references.ids,
+                    chats: attached.chats,
                     attachments: extras.attachments,
-                    ...(extras.quoteSource ? { quoteSource: extras.quoteSource } : {})
+                    ...(extras.quoteSource ? { quoteSource: extras.quoteSource } : {}),
+                    ...(attached.references.length > 0 ? { references: attached.references } : {})
                 }),
                 this.thread.patchInfo({ queue: this.queue.filter((entry) => entry.id !== message.id) })
             ]);
@@ -524,7 +534,8 @@ export class ChatSession {
             chats: next.chats,
             attachments: next.attachments,
             uiChoice: next.uiChoice,
-            quoteSource: next.quoteSource
+            quoteSource: next.quoteSource,
+            references: next.references
         }, next.turnId);
     }
     dispatch(text, extras, requestedTurnId) {
@@ -535,13 +546,12 @@ export class ChatSession {
             this.emit([this.thread.patchInfo({ goal: undefined })]);
         }
         const { preamble, note } = this.contextNote(text);
-        // A slash command must stay the first thing the CLI reads, as `contextNote` keeps it.
-        const references = text.startsWith('/') || !this.options.references ? { ids: [], note: null } : this.options.references(extras.chats);
-        const turnId = this.openTurn(text, note, { ...extras, chats: references.ids }, requestedTurnId);
+        const attached = this.attached(text, extras);
+        const turnId = this.openTurn(text, note, { ...extras, chats: attached.chats, references: attached.references }, requestedTurnId);
         const choiceNote = extras.uiChoice
             ? `The person chose ${JSON.stringify(extras.uiChoice.label)} from your UI reply. Their message is the visible context of that choice.`
             : null;
-        const said = [preamble, references.note, choiceNote].filter((part) => part !== null);
+        const said = [preamble, attached.note, choiceNote].filter((part) => part !== null);
         const input = {
             text,
             preamble: said.length === 0 ? null : said.join('\n\n'),
@@ -1382,7 +1392,8 @@ export class ChatSession {
                 chats,
                 attachments,
                 ...(extras.uiChoice ? { uiChoice: extras.uiChoice } : {}),
-                ...(extras.quoteSource ? { quoteSource: extras.quoteSource } : {})
+                ...(extras.quoteSource ? { quoteSource: extras.quoteSource } : {}),
+                ...(extras.references?.length ? { references: extras.references } : {})
             }));
         }
         events.push(this.thread.patchInfo({ status: this.thread.statusFor(turnId), activeTurnId: turnId }));

package/dist/host/handlers.js

@@ -35,7 +35,14 @@ export function chatHandlers(chats, providers) {
             chats.detach(payload.chatId, clientId);
             return {};
         },
-        'chat.send': (payload) => chats.send(payload.chatId, payload.text, { delivery: payload.delivery, mentions: payload.mentions, skills: payload.skills, chats: payload.chats, quoteSource: payload.quoteSource }, payload.attachments),
+        'chat.send': (payload) => chats.send(payload.chatId, payload.text, {
+            delivery: payload.delivery,
+            mentions: payload.mentions,
+            skills: payload.skills,
+            chats: payload.chats,
+            quoteSource: payload.quoteSource,
+            references: payload.references
+        }, payload.attachments),
         'chat.uiChoice': (payload, clientId) => chats.choose(payload, clientId),
         'ui.link': (payload, clientId) => chats.linkUi(payload, clientId),
         'ui.query': (payload, clientId) => chats.queryUi(payload, clientId),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adecore/agents",
-  "version": "0.37.2",
+  "version": "0.37.3",
   "description": "Node-compatible agent chat hosts, providers, accounts, usage and durable task coordination.",
   "type": "module",
   "exports": {
@@ -81,8 +81,8 @@
     "test": "bun --conditions=source test"
   },
   "dependencies": {
-    "@adecore/agent-contracts": "0.37.2",
-    "@adecore/intelligent-ui": "0.37.2",
+    "@adecore/agent-contracts": "0.37.3",
+    "@adecore/intelligent-ui": "0.37.3",
     "zod": "^4.6.5"
   },
   "devDependencies": {

package/src/chat/chat-core.ts

@@ -137,7 +137,7 @@ export interface ChatCoreHooks {
     hiddenFor?(chatId: string): boolean;
     /* What the host says in front of a chat's next real prompt, beside what the chat keeps itself. */
     promptNotesFor?(chatId: string): PromptNotes | undefined;
-    /* How the chats a person attached to a message are named to the agent; without it they are dropped. */
+    /* How the chats, views and nodes a person attached to a message are named to the agent; without it they are dropped. */
     referencesFor?(chatId: string): ChatReferences | undefined;
     /* The environment of this chat's CLI before its account adds its own. */
     envFor?(chatId: string, base: Record<string, string>): Record<string, string | undefined>;

package/src/chat/chat-session.ts

@@ -57,7 +57,16 @@ export interface PromptNotes {
 }
 
 /* Chats a person attached to a message: the ones the host knows, and what the agent is told about them. */
-export type ChatReferences = (ids: readonly string[] | undefined) => { ids: string[]; note: string | null };
+/* What a message pointed at: other chats with `@`, and views and nodes with `#`, by id. */
+export interface ChatAttached {
+    chats: string[];
+    references: string[];
+}
+
+export type ChatReferences = (attached: {
+    readonly chats?: readonly string[];
+    readonly references?: readonly string[];
+}) => ChatAttached & { note: string | null };
 
 export interface ChatSessionOptions {
     info: ChatInfo;
@@ -129,6 +138,7 @@ export interface ChatSendExtras {
     chats?: string[];
     quoteSource?: ChatQuoteSource;
     attachments?: ChatAttachment[];
+    references?: string[];
 }
 
 /* How a turn the host went down in is taken up: what the CLI is told, the note a person reads, and what goes in front. */
@@ -407,7 +417,8 @@ export class ChatSession {
                 ...(extras.skills?.length ? { skills: extras.skills } : {}),
                 ...(extras.chats?.length ? { chats: extras.chats } : {}),
                 ...(extras.quoteSource ? { quoteSource: extras.quoteSource } : {}),
-                ...(extras.attachments?.length ? { attachments: extras.attachments } : {})
+                ...(extras.attachments?.length ? { attachments: extras.attachments } : {}),
+                ...(extras.references?.length ? { references: extras.references } : {})
             };
             this.setQueue([...this.queue, message]);
             this.lapseResume();
@@ -523,6 +534,15 @@ export class ChatSession {
         return plain;
     }
 
+    /* The chats and views a message pointed at as the host names them; without a host's `references` they are dropped. */
+    private attached(text: string, extras: ChatSendExtras): ChatAttached & { note: string | null } {
+        // A slash command must stay the first thing the CLI reads, as `contextNote` keeps it.
+        if (text.startsWith('/') || !this.options.references) {
+            return { chats: [], references: [], note: null };
+        }
+        return this.options.references({ chats: extras.chats, references: extras.references });
+    }
+
     sendInput(text: string, extras: ChatSendExtras = {}): Promise<{ queued: boolean; turnId: string }> {
         return this.submitInput(text, extras);
     }
@@ -580,11 +600,11 @@ export class ChatSession {
         queued: { queued: boolean; turnId: string }
     ): Promise<{ queued: boolean; turnId: string }> {
         try {
-            const references = this.options.references?.(extras.chats) ?? { ids: extras.chats ?? [], note: null };
+            const attached = this.attached(text, extras);
             const accepted = await steerTurn({
                 promptId: message.id,
                 text,
-                preamble: references.note,
+                preamble: attached.note,
                 attachments: extras.attachments ?? [],
                 mentions: extras.mentions ?? [],
                 skills: extras.skills ?? []
@@ -601,9 +621,10 @@ export class ChatSession {
                     text,
                     mentions: extras.mentions,
                     skills: extras.skills,
-                    chats: references.ids,
+                    chats: attached.chats,
                     attachments: extras.attachments,
-                    ...(extras.quoteSource ? { quoteSource: extras.quoteSource } : {})
+                    ...(extras.quoteSource ? { quoteSource: extras.quoteSource } : {}),
+                    ...(attached.references.length > 0 ? { references: attached.references } : {})
                 }),
                 this.thread.patchInfo({ queue: this.queue.filter((entry) => entry.id !== message.id) })
             ]);
@@ -700,7 +721,8 @@ export class ChatSession {
                 chats: next.chats,
                 attachments: next.attachments,
                 uiChoice: next.uiChoice,
-                quoteSource: next.quoteSource
+                quoteSource: next.quoteSource,
+                references: next.references
             },
             next.turnId
         );
@@ -714,13 +736,12 @@ export class ChatSession {
             this.emit([this.thread.patchInfo({ goal: undefined })]);
         }
         const { preamble, note } = this.contextNote(text);
-        // A slash command must stay the first thing the CLI reads, as `contextNote` keeps it.
-        const references = text.startsWith('/') || !this.options.references ? { ids: [], note: null } : this.options.references(extras.chats);
-        const turnId = this.openTurn(text, note, { ...extras, chats: references.ids }, requestedTurnId);
+        const attached = this.attached(text, extras);
+        const turnId = this.openTurn(text, note, { ...extras, chats: attached.chats, references: attached.references }, requestedTurnId);
         const choiceNote = extras.uiChoice
             ? `The person chose ${JSON.stringify(extras.uiChoice.label)} from your UI reply. Their message is the visible context of that choice.`
             : null;
-        const said = [preamble, references.note, choiceNote].filter((part): part is string => part !== null);
+        const said = [preamble, attached.note, choiceNote].filter((part): part is string => part !== null);
         const input = {
             text,
             preamble: said.length === 0 ? null : said.join('\n\n'),
@@ -1612,7 +1633,8 @@ export class ChatSession {
                     chats,
                     attachments,
                     ...(extras.uiChoice ? { uiChoice: extras.uiChoice } : {}),
-                    ...(extras.quoteSource ? { quoteSource: extras.quoteSource } : {})
+                    ...(extras.quoteSource ? { quoteSource: extras.quoteSource } : {}),
+                    ...(extras.references?.length ? { references: extras.references } : {})
                 })
             );
         }

package/src/host/handlers.ts

@@ -67,7 +67,14 @@ export function chatHandlers(chats: ChatCore, providers: ProviderRegistry): { [T
             chats.send(
                 payload.chatId,
                 payload.text,
-                { delivery: payload.delivery, mentions: payload.mentions, skills: payload.skills, chats: payload.chats, quoteSource: payload.quoteSource },
+                {
+                    delivery: payload.delivery,
+                    mentions: payload.mentions,
+                    skills: payload.skills,
+                    chats: payload.chats,
+                    quoteSource: payload.quoteSource,
+                    references: payload.references
+                },
                 payload.attachments
             ),
         'chat.uiChoice': (payload, clientId) => chats.choose(payload, clientId),