@economic/agents 0.0.1-beta.3 → 0.0.1-beta.4

package/README.md

@@ -339,6 +339,33 @@ export const datetimeSkill: Skill = {
 
 ---
 
+## Surfacing source URLs from tools
+
+Any tool can surface source URLs into the message stream by including a `sources` array in its return value. `buildLLMParams` automatically detects this and emits `source-url` stream parts that the playground's Sources block renders.
+
+```typescript
+execute: async ({ query }) => {
+  const data = await fetchResults(query);
+  return {
+    results: data.results,                                          // LLM receives full content
+    sources: data.results.map(r => ({ url: r.url, title: r.title })), // rendered as source links
+  };
+},
+```
+
+The `sources` array is picked up by a built-in `experimental_transform` inside `buildLLMParams` — no agent changes, no writer passed to the tool, no additional wiring. The LLM continues to receive the full result object including `sources`. The transform fires on every `tool-result` stream part and emits a `source` part for each entry.
+
+Each source entry shape:
+
+| Field   | Type     | Required | Description             |
+| ------- | -------- | -------- | ----------------------- |
+| `url`   | `string` | Yes      | The URL to link to.     |
+| `title` | `string` | No       | Display name in the UI. |
+
+The playground's `UIMessageRenderer` collects all `source-url` parts from a message and displays them in a collapsible **Sources** block above the response text.
+
+---
+
 ## Compaction
 
 When `fastModel` is set on the agent class, compaction runs automatically before each turn:

package/dist/index.mjs

@@ -324,6 +324,39 @@ ${loadedGuidance}`;
 	return prompt.trim();
 }
 /**
+* Convention: tools can include a `sources` array in their return value to surface
+* source URLs in the message stream. This transform detects it automatically.
+*
+* ```typescript
+* // In any tool's execute function:
+* return { myContent: "...", sources: [{ url: "https://...", title: "Page title" }] };
+* ```
+*/
+function buildSourcesTransform(additional) {
+	const sourcesTransform = () => new TransformStream({ transform(chunk, controller) {
+		controller.enqueue(chunk);
+		if (chunk.type !== "tool-result") return;
+		const output = chunk.output;
+		if (!output || typeof output !== "object" || Array.isArray(output)) return;
+		const sources = output.sources;
+		if (!Array.isArray(sources)) return;
+		for (const source of sources) {
+			if (!source || typeof source !== "object") continue;
+			const s = source;
+			if (typeof s.url !== "string") continue;
+			controller.enqueue({
+				type: "source",
+				sourceType: "url",
+				id: crypto.randomUUID(),
+				url: s.url,
+				...typeof s.title === "string" ? { title: s.title } : {}
+			});
+		}
+	} });
+	if (!additional) return sourcesTransform;
+	return [sourcesTransform, ...Array.isArray(additional) ? additional : [additional]];
+}
+/**
 * Builds the parameter object for a Vercel AI SDK `streamText` or `generateText` call.
 *
 * Handles message conversion, optional compaction, skill wiring (`activate_skill`,
@@ -338,11 +371,13 @@ ${loadedGuidance}`;
 * ```
 */
 async function buildLLMParams(config) {
-	const { options, messages, activeSkills = [], skills, fastModel, maxMessagesBeforeCompaction, ...rest } = config;
+	const { options, messages, activeSkills = [], skills, fastModel, maxMessagesBeforeCompaction, experimental_transform, ...rest } = config;
 	const rawMessages = await convertToModelMessages(messages);
 	const processedMessages = fastModel && maxMessagesBeforeCompaction !== void 0 ? await compactIfNeeded(rawMessages, fastModel, maxMessagesBeforeCompaction) : rawMessages;
+	const composedTransform = buildSourcesTransform(experimental_transform);
 	const baseParams = {
 		...rest,
+		experimental_transform: composedTransform,
 		messages: processedMessages,
 		experimental_context: options?.body,
 		abortSignal: options?.abortSignal,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@economic/agents",
-  "version": "0.0.1-beta.3",
+  "version": "0.0.1-beta.4",
   "description": "A starter for creating a TypeScript package.",
   "license": "MIT",
   "files": [