@economic/agents 0.0.1-alpha.3 → 0.0.1-alpha.5

package/dist/index.d.mts

@@ -75,27 +75,15 @@ declare global {
 }
 //#endregion
 //#region src/features/skills/types.d.ts
-/**
- * A single tool with a name, JSON Schema parameters, and an execute function.
- *
- * Tools are defined in this SDK-agnostic format and converted to the
- * target SDK's format by the adapter layer (createSkills).
- */
-interface Tool {
-  name: string;
-  description: string;
-  /** JSON Schema object describing the tool's input parameters */
-  parameters: Record<string, unknown>;
-  execute(args: Record<string, unknown>, options: {
-    toolCallId: string;
-  }): Promise<string>;
-}
 /**
  * A named group of related tools that can be loaded together on demand.
  *
  * The agent starts with only its always-on tools active. When the LLM calls
  * activate_skill with a skill name, that skill's tools become available for
  * the rest of the conversation.
+ *
+ * Define tools using the AI SDK's `tool()` helper — Zod schemas are supported
+ * natively via the `parameters` field.
  */
 interface Skill {
   name: string;
@@ -107,16 +95,24 @@ interface Skill {
    * skill that is loaded, keeping the `system` prompt static and cacheable.
    */
   guidance?: string;
-  tools: Tool[];
+  tools: ToolSet;
 }
 /**
  * Configuration passed to createSkills().
  */
 interface SkillsConfig {
   /** Tools that are always active regardless of loaded skills */
-  tools: Tool[];
+  tools: ToolSet;
   /** All available skills that can be loaded on demand */
   skills: Skill[];
+  /**
+   * The base system prompt for the agent. When provided, createSkills uses
+   * this to compose the full system string (base + guidance) returned by
+   * getSystem() and from prepareStep. Guidance is kept in the system
+   * parameter rather than the messages array — Anthropic/Gemini only allow
+   * system messages at the start of the conversation.
+   */
+  systemPrompt?: string;
   /**
    * Skill names that were loaded in previous turns, read from D1 at turn
    * start. Seeds the in-memory loadedSkills set so prior state is restored
@@ -161,14 +157,17 @@ interface SkillContext {
   /** Currently active tool names — spread into streamText */
   activeTools: string[];
   /**
-   * Updates active tools and the guidance system message before each LLM step.
-   * Spread into streamText.
+   * Updates activeTools before each LLM step. Spread into streamText.
    */
   prepareStep: ai.PrepareStepFunction;
   /**
-   * Conversation messages read from D1 with current skill guidance already
-   * injected just before the last message (the current user turn). Pass
-   * directly as the `messages` param of streamText.
+   * Guidance text from all currently-loaded skills. Compose your system
+   * prompt as: `${myBase}${guidance ? '\n\n' + guidance : ''}`
+   */
+  guidance: string;
+  /**
+   * Plain conversation history from DO SQLite — no guidance injected.
+   * Pass directly as the `messages` param of streamText.
    */
   messages: ai.ModelMessage[];
 }
@@ -181,6 +180,12 @@ interface SkillsResult {
   getLoadedGuidance(): string;
   /** Current loaded skill names */
   getLoadedSkills(): string[];
+  /**
+   * Full system string: base system prompt concatenated with guidance from
+   * all currently-loaded skills. Only meaningful when `systemPrompt` was
+   * passed to createSkills. Use as the `system` param of streamText.
+   */
+  getSystem(): string;
 }
 //#endregion
 //#region src/agents/chat/AIChatAgentBase.d.ts
@@ -240,7 +245,7 @@ declare abstract class AIChatAgentBase<Env extends Cloudflare.Env = Cloudflare.E
    */
   maxPersistedMessages: number;
   /** Tools that are always active regardless of loaded skills */
-  abstract getTools(): Tool[];
+  abstract getTools(): ToolSet;
   /** All skills available for on-demand loading */
   abstract getSkills(): Skill[];
   /**
@@ -343,13 +348,14 @@ declare abstract class AIChatAgentBase<Env extends Cloudflare.Env = Cloudflare.E
   /**
    * Called by the @withSkills decorator at the start of each turn.
    *
-   * Reads loaded skill state from D1, seeds createSkills, injects guidance,
-   * and returns a SkillContext ready to use in a streamText call.
+   * Reads loaded skill state from D1, seeds createSkills, and returns a
+   * SkillContext ready to use in a streamText call.
+   *
+   * Guidance is exposed as `ctx.guidance` — compose your system prompt as:
+   * `${myBase}${ctx.guidance ? '\n\n' + ctx.guidance : ''}`
    *
-   * The returned `messages` already has guidance injected just before the
-   * current user turn — pass it directly as the `messages` param of streamText.
-   * Guidance is never stored in DO SQLite, so loaded_skills in D1 is the
-   * single source of truth for which skills are active.
+   * Messages are plain (no guidance injected). Guidance stays out of the
+   * messages array — Anthropic/Gemini only allow system messages at position 0.
    */
   protected _prepareSkillContext(): Promise<SkillContext>;
 }
@@ -370,10 +376,11 @@ declare abstract class AIChatAgentBase<Env extends Cloudflare.Env = Cloudflare.E
  *   ctx: SkillContext,
  *   options?: OnChatMessageOptions,
  * ) {
- *   const { messages, ...skillArgs } = ctx;
+ *   const { messages, guidance, ...skillArgs } = ctx;
+ *   const base = "Your base prompt";
  *   return streamText({
  *     model: this.getModel(),
- *     system: "Your base prompt — static, never includes guidance",
+ *     system: guidance ? `${base}\n\n${guidance}` : base,
  *     messages,
  *     ...skillArgs,
  *     onFinish,
@@ -417,7 +424,7 @@ declare abstract class AIChatAgent<Env extends Cloudflare.Env = Cloudflare.Env>
   /** Return the Vercel AI SDK LanguageModel to use for this agent */
   abstract getModel(): LanguageModel;
   /** Tools that are always active regardless of loaded skills */
-  abstract getTools(): Tool[];
+  abstract getTools(): ToolSet;
   /** All skills available for on-demand loading */
   abstract getSkills(): Skill[];
   /**
@@ -558,4 +565,4 @@ declare function compactMessages(messages: UIMessage[], model: LanguageModel, ta
  */
 declare function compactIfNeeded(messages: UIMessage[], model: LanguageModel | undefined, tailSize: number): Promise<UIMessage[]>;
 //#endregion
-export { AIChatAgent, AIChatAgentBase, COMPACT_TOKEN_THRESHOLD, type Skill, type SkillContext, type SkillsConfig, type SkillsResult, type Tool, compactIfNeeded, compactMessages, createSkills, estimateMessagesTokens, filterEphemeralMessages, injectGuidance, withSkills };
+export { AIChatAgent, AIChatAgentBase, COMPACT_TOKEN_THRESHOLD, type Skill, type SkillContext, type SkillsConfig, type SkillsResult, compactIfNeeded, compactMessages, createSkills, estimateMessagesTokens, filterEphemeralMessages, injectGuidance, withSkills };

package/dist/index.mjs

@@ -62,35 +62,29 @@ function createSkills(config) {
 	const loadedSkills = new Set(config.initialLoadedSkills ?? []);
 	const skillMap = new Map(skills.map((s) => [s.name, s]));
 	const allTools = {};
-	const registeredNames = /* @__PURE__ */ new Set();
-	function registerTool(t) {
-		if (registeredNames.has(t.name)) return;
-		allTools[t.name] = tool({
-			description: t.description,
-			inputSchema: jsonSchema(t.parameters),
-			execute: async (args, options) => t.execute(args, { toolCallId: options.toolCallId })
-		});
-		registeredNames.add(t.name);
-	}
-	for (const t of alwaysOnTools) registerTool(t);
-	for (const skill of skills) for (const t of skill.tools) registerTool(t);
+	Object.assign(allTools, alwaysOnTools);
+	for (const skill of skills) Object.assign(allTools, skill.tools);
 	function getActiveToolNames() {
 		const names = [
 			ACTIVATE_SKILL,
 			LIST_CAPABILITIES,
-			...alwaysOnTools.map((t) => t.name)
+			...Object.keys(alwaysOnTools)
 		];
 		for (const skillName of loadedSkills) {
 			const skill = skillMap.get(skillName);
 			if (!skill) continue;
-			for (const t of skill.tools) if (!names.includes(t.name)) names.push(t.name);
+			for (const toolName of Object.keys(skill.tools)) if (!names.includes(toolName)) names.push(toolName);
 		}
 		return names;
 	}
 	function getLoadedGuidance() {
 		return [...loadedSkills].map((name) => skillMap.get(name)?.guidance).filter((g) => Boolean(g)).join("\n\n");
 	}
-	let previousGuidance = getLoadedGuidance();
+	function getSystem() {
+		const guidance = getLoadedGuidance();
+		if (!config.systemPrompt) return guidance;
+		return guidance ? `${config.systemPrompt}\n\n${guidance}` : config.systemPrompt;
+	}
 	allTools[ACTIVATE_SKILL] = tool({
 		description: buildActivateSkillDescription(skills),
 		inputSchema: jsonSchema({
@@ -146,13 +140,10 @@ function createSkills(config) {
 			].join("\n");
 		}
 	});
-	const prepareStep = async ({ messages }) => {
-		const guidance = getLoadedGuidance();
-		const updatedMessages = injectGuidance(messages, guidance, previousGuidance);
-		previousGuidance = guidance;
+	const prepareStep = async () => {
 		return {
 			activeTools: getActiveToolNames(),
-			messages: updatedMessages
+			...config.systemPrompt !== void 0 && { system: getSystem() }
 		};
 	};
 	return {
@@ -160,6 +151,7 @@ function createSkills(config) {
 		activeTools: getActiveToolNames(),
 		prepareStep,
 		getLoadedGuidance,
+		getSystem,
 		getLoadedSkills() {
 			return [...loadedSkills];
 		}
@@ -247,13 +239,14 @@ function filterEphemeralMessages(messages, guidanceToStrip) {
 function injectGuidance(messages, guidance, previousGuidance) {
 	if (!guidance) return messages;
 	const base = previousGuidance ? messages.filter((m) => !(m.role === "system" && m.content === previousGuidance)) : messages;
+	const insertAt = base.findLastIndex((m) => m.role === "user");
 	return [
-		...base.slice(0, -1),
+		...base.slice(0, insertAt),
 		{
 			role: "system",
 			content: guidance
 		},
-		base.at(-1)
+		...base.slice(insertAt)
 	];
 }
 //#endregion
@@ -575,13 +568,14 @@ var AIChatAgentBase = class extends AIChatAgent$1 {
 	/**
 	* Called by the @withSkills decorator at the start of each turn.
 	*
-	* Reads loaded skill state from D1, seeds createSkills, injects guidance,
-	* and returns a SkillContext ready to use in a streamText call.
+	* Reads loaded skill state from D1, seeds createSkills, and returns a
+	* SkillContext ready to use in a streamText call.
+	*
+	* Guidance is exposed as `ctx.guidance` — compose your system prompt as:
+	* `${myBase}${ctx.guidance ? '\n\n' + ctx.guidance : ''}`
 	*
-	* The returned `messages` already has guidance injected just before the
-	* current user turn — pass it directly as the `messages` param of streamText.
-	* Guidance is never stored in DO SQLite, so loaded_skills in D1 is the
-	* single source of truth for which skills are active.
+	* Messages are plain (no guidance injected). Guidance stays out of the
+	* messages array — Anthropic/Gemini only allow system messages at position 0.
 	*/
 	async _prepareSkillContext() {
 		const loadedSkills = await this._readSkillState();
@@ -594,13 +588,12 @@ var AIChatAgentBase = class extends AIChatAgent$1 {
 			},
 			filterSkill: (name) => this.filterSkill(name)
 		});
-		const guidance = skills.getLoadedGuidance();
-		const messages = injectGuidance(await convertToModelMessages(this.messages), guidance);
 		return {
 			tools: skills.tools,
 			activeTools: skills.activeTools,
 			prepareStep: skills.prepareStep,
-			messages
+			guidance: skills.getLoadedGuidance(),
+			messages: await convertToModelMessages(this.messages)
 		};
 	}
 };
@@ -658,18 +651,17 @@ var AIChatAgent = class extends AIChatAgentBase {
 		const skills = createSkills({
 			tools: this.getTools(),
 			skills: this.getSkills(),
+			systemPrompt: this.getSystemPrompt(),
 			initialLoadedSkills: loadedSkills,
 			onSkillsChanged: async (updated) => {
 				this._pendingSkills = updated;
 			},
 			filterSkill: (name) => this.filterSkill(name)
 		});
-		const guidance = skills.getLoadedGuidance();
-		const messages = injectGuidance(await convertToModelMessages(this.messages), guidance);
 		return streamText({
 			model: this.getModel(),
-			system: this.getSystemPrompt(),
-			messages,
+			system: skills.getSystem(),
+			messages: await convertToModelMessages(this.messages),
 			tools: skills.tools,
 			activeTools: skills.activeTools,
 			prepareStep: skills.prepareStep,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@economic/agents",
-  "version": "0.0.1-alpha.3",
+  "version": "0.0.1-alpha.5",
   "description": "A starter for creating a TypeScript package.",
   "homepage": "https://github.com/author/library#readme",
   "bugs": {