@economic/agents 0.0.1-beta.2 → 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.d.mts

@@ -16,8 +16,9 @@ interface Skill {
   description: string;
   /**
    * Guidance text for this skill — e.g. rate limits, preferred patterns,
-   * when to use each tool. Appended to the `system` prompt each turn for any
-   * skill that is loaded, keeping `system` mostly cacheable.
+   * when to use each tool. Injected into the `## Tools` section of the
+   * system prompt via `buildSystemPrompt` in `llm.ts` whenever this skill
+   * is loaded.
    */
   guidance?: string;
   tools: ToolSet;

package/dist/index.mjs

@@ -40,12 +40,7 @@ function buildActivateSkillDescription(skills) {
 	].join("\n");
 }
 function buildAvailableSkillList(skills) {
-	return [
-		"**Loading More Tools:**",
-		"Use `activate_skill` to load these categories (BE PROACTIVE on requesting tools based on the user's request AND you DON'T need to mention that you are loading more tools):",
-		"",
-		skills.map((s) => `**${s.name}**: ${s.description}`).join("\n")
-	].join("\n");
+	return skills.map((s) => `**${s.name}**: ${s.description}`).join("\n");
 }
 const LIST_CAPABILITIES_DESCRIPTION = "List all tools currently available to you, which skills are loaded, and which can still be loaded. Call this when the user asks about your capabilities or what you can do.";
 /**
@@ -95,20 +90,7 @@ function createSkills(config) {
 			return [`**${skill.name}**\n${skill.guidance}`];
 		});
 		if (sections.length === 0) return "";
-		return [
-			"**Loaded skill instructions**",
-			"The following skills are currently active. Apply their instructions when using the corresponding tools.",
-			"",
-			sections.join("\n\n")
-		].join("\n");
-	}
-	function getSystem() {
-		const guidance = getLoadedGuidance();
-		return [
-			config.systemPrompt,
-			availableSkillList,
-			guidance
-		].filter(Boolean).join("\n\n");
+		return sections.join("\n\n");
 	}
 	allTools[ACTIVATE_SKILL] = tool({
 		description: buildActivateSkillDescription(skills),
@@ -155,17 +137,14 @@ function createSkills(config) {
 		}
 	});
 	const prepareStep = async () => {
-		return {
-			activeTools: getActiveToolNames(),
-			...config.systemPrompt !== void 0 && { system: getSystem() }
-		};
+		return { activeTools: getActiveToolNames() };
 	};
 	return {
 		tools: allTools,
 		activeTools: getActiveToolNames(),
 		prepareStep,
+		availableSkillList,
 		getLoadedGuidance,
-		getSystem,
 		getLoadedSkills() {
 			return [...loadedSkills];
 		}
@@ -304,6 +283,80 @@ async function compactIfNeeded(messages, model, tailSize) {
 //#endregion
 //#region src/server/llm.ts
 /**
+* Composes the full system prompt from its three parts: the consumer's base
+* string, the static skill roster, and the dynamic loaded-skill guidance.
+*
+* The full shape, at a glance:
+*
+*   {base}
+*
+*   ## Tools
+*
+*   Use `activate_skill` to load these skills (BE PROACTIVE on requesting
+*   tools based on the user's request AND you DON'T need to mention that you
+*   are loading more tools):
+*
+*   **{name}**: {description}
+*   ...
+*
+*   **Loaded skill instructions**
+*   The following skills are currently active. Apply their instructions when
+*   using the corresponding tools.
+*
+*   **{name}**
+*   {guidance body}
+*/
+function buildSystemPrompt(basePrompt, availableSkillList, loadedGuidance) {
+	let prompt = `${basePrompt}
+
+## Tools
+
+### Loading More Tools:
+Use \`activate_skill\` to load these skills (BE PROACTIVE on requesting tools based on the user's request AND you DON'T need to mention that you are loading more tools):
+
+${availableSkillList}`;
+	if (loadedGuidance) prompt += `
+
+### Loaded skill instructions:
+The following skills are currently active. Apply their instructions when using the corresponding tools.
+
+${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`,
@@ -318,33 +371,34 @@ async function compactIfNeeded(messages, model, tailSize) {
 * ```
 */
 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,
 		stopWhen: rest.stopWhen ?? stepCountIs(20)
 	};
 	if (!skills?.length) return baseParams;
+	const base = typeof rest.system === "string" ? rest.system : void 0;
 	const skillsCtx = createSkills({
 		tools: rest.tools ?? {},
 		skills,
-		initialLoadedSkills: activeSkills,
-		systemPrompt: typeof rest.system === "string" ? rest.system : void 0
+		initialLoadedSkills: activeSkills
 	});
 	const prepareStep = async (stepOptions) => {
-		const skillsResult = await skillsCtx.prepareStep(stepOptions) ?? {};
 		return {
-			activeTools: skillsResult.activeTools ?? [],
-			system: skillsResult.system
+			activeTools: (await skillsCtx.prepareStep(stepOptions) ?? {}).activeTools ?? [],
+			system: buildSystemPrompt(base, skillsCtx.availableSkillList, skillsCtx.getLoadedGuidance())
 		};
 	};
 	return {
 		...baseParams,
-		system: skillsCtx.getSystem() || rest.system,
+		system: buildSystemPrompt(base, skillsCtx.availableSkillList, skillsCtx.getLoadedGuidance()),
 		tools: skillsCtx.tools,
 		activeTools: skillsCtx.activeTools,
 		prepareStep

package/package.json

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