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

package/README.md

@@ -202,6 +202,18 @@ When `fastModel` is set, compaction runs automatically with a default threshold
 
 When `fastModel` is `undefined` (the default), compaction is disabled regardless of `maxMessagesBeforeCompaction`.
 
+### `getConversations` (callable)
+
+`AIChatAgent` exposes a [callable method](https://developers.cloudflare.com/agents/api-reference/callable-methods/) via the Agents SDK `@callable()` decorator (`agents` package). From any connected client (for example the object returned by `useAgent` / `useAIChatAgent`), invoke:
+
+```typescript
+const rows = await agent.call("getConversations");
+```
+
+- **User scope**: `userId` is taken from the segment before the first `:` in the Durable Object name (`userId:chatId`), the same format enforced in `onConnect`.
+- **Data**: Reads from `AGENT_DB`, returning all `conversations` rows whose `durable_object_name` matches `userId:%`, ordered by `updated_at` descending (newest first). Each row includes `durable_object_name`, `title`, `summary`, `created_at`, and `updated_at`.
+- **No D1**: If `AGENT_DB` is not bound, the method returns `undefined` and does not throw.
+
 ### `getLoadedSkills()`
 
 Protected method on `AIChatAgent`. Returns skill names persisted from previous turns (read from DO SQLite). Used internally by `this.buildLLMParams()`.
@@ -546,12 +558,14 @@ No subclass code is needed — this runs automatically when `AGENT_DB` is bound
 
 ### Querying conversation lists
 
-To fetch all conversations for a user, ordered by most recent:
+From a connected agent client, prefer the built-in callable (see **`getConversations` (callable)** under [`AIChatAgent`](#aichatagent)): `await agent.call("getConversations")`.
+
+To query D1 directly (same logic as the callable), filter by `durable_object_name` prefix — one row per chat, keyed as `userId:chatId`:
 
 ```sql
-SELECT durable_object_id, title, summary, created_at, updated_at
+SELECT durable_object_name, title, summary, created_at, updated_at
 FROM conversations
-WHERE user_id = '148583_matt'
+WHERE durable_object_name LIKE '148583_matt:%'
 ORDER BY updated_at DESC;
 ```
 
@@ -563,9 +577,9 @@ If `userId` is not set on the request body, the upsert is skipped and a `console
 
 ### Classes
 
-| Export        | Description                                                                                                           |
-| ------------- | --------------------------------------------------------------------------------------------------------------------- |
-| `AIChatAgent` | Abstract CF Durable Object base class. Implement `onChatMessage`. Manages skill state, history replay, and audit log. |
+| Export        | Description                                                                                                                                                                                                                               |
+| ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `AIChatAgent` | Abstract CF Durable Object base class. Implement `onChatMessage`. Manages skill state, history replay, audit log, and D1 `conversations` upserts. Exposes callable `getConversations` for listing a user’s conversations from the client. |
 
 ### Functions
 

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

@@ -39,6 +39,9 @@ function buildActivateSkillDescription(skills) {
 		skills.map((s) => `• ${s.name} — ${s.description}`).join("\n")
 	].join("\n");
 }
+function buildAvailableSkillList(skills) {
+	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.";
 /**
 * Sentinel appended to a successful activate_skill result.
@@ -63,6 +66,7 @@ function createSkills(config) {
 	const { tools: alwaysOnTools, skills } = config;
 	const loadedSkills = new Set(config.initialLoadedSkills ?? []);
 	const skillMap = new Map(skills.map((s) => [s.name, s]));
+	const availableSkillList = skills.length > 0 ? buildAvailableSkillList(skills) : "";
 	const allTools = {};
 	Object.assign(allTools, alwaysOnTools);
 	for (const skill of skills) Object.assign(allTools, skill.tools);
@@ -80,12 +84,13 @@ function createSkills(config) {
 		return names;
 	}
 	function getLoadedGuidance() {
-		return [...loadedSkills].map((name) => skillMap.get(name)?.guidance).filter((g) => Boolean(g)).join("\n\n");
-	}
-	function getSystem() {
-		const guidance = getLoadedGuidance();
-		if (!config.systemPrompt) return guidance;
-		return guidance ? `${config.systemPrompt}\n\n${guidance}` : config.systemPrompt;
+		const sections = [...loadedSkills].flatMap((name) => {
+			const skill = skillMap.get(name);
+			if (!skill?.guidance) return [];
+			return [`**${skill.name}**\n${skill.guidance}`];
+		});
+		if (sections.length === 0) return "";
+		return sections.join("\n\n");
 	}
 	allTools[ACTIVATE_SKILL] = tool({
 		description: buildActivateSkillDescription(skills),
@@ -132,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];
 		}
@@ -281,6 +283,47 @@ 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();
+}
+/**
 * Builds the parameter object for a Vercel AI SDK `streamText` or `generateText` call.
 *
 * Handles message conversion, optional compaction, skill wiring (`activate_skill`,
@@ -306,22 +349,21 @@ async function buildLLMParams(config) {
 		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.1",
+  "version": "0.0.1-beta.3",
   "description": "A starter for creating a TypeScript package.",
   "license": "MIT",
   "files": [