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

package/dist/index.d.mts

@@ -136,16 +136,17 @@ interface SkillsConfig {
 /**
  * Skill context injected by the @withSkills decorator.
  *
- * Spread the context fields directly into streamText — messages already has
- * guidance injected at the correct position:
+ * Spread the skill fields into streamText and pass headers via
+ * experimental_context so tools can read them from their second execute arg:
  *
  * ```typescript
- * const { messages, ...skillArgs } = ctx;
+ * const { messages, headers, guidance, ...skillArgs } = ctx;
  * return streamText({
  *   model: this.getModel(),
  *   system: "Your base prompt — static, never includes guidance",
  *   messages,
  *   ...skillArgs,
+ *   experimental_context: { headers },
  *   onFinish,
  *   stopWhen: stepCountIs(20),
  * }).toUIMessageStreamResponse();
@@ -170,6 +171,12 @@ interface SkillContext {
    * Pass directly as the `messages` param of streamText.
    */
   messages: ai.ModelMessage[];
+  /**
+   * Headers captured from the WebSocket upgrade request, filtered to the
+   * names returned by getTrackedHeaders(). Pass to tools via
+   * experimental_context: `streamText({ experimental_context: { headers }, ... })`
+   */
+  headers: Record<string, string>;
 }
 /**
  * The object returned by createSkills().
@@ -244,6 +251,21 @@ declare abstract class AIChatAgentBase<Env extends Cloudflare.Env = Cloudflare.E
    * tail is maxPersistedMessages - 1 recent messages. Raise or lower per agent.
    */
   maxPersistedMessages: number;
+  /**
+   * Query parameter names to read from the WebSocket connection URL and
+   * forward to tools via experimental_context.
+   *
+   * Browsers cannot set custom headers on WebSocket upgrade requests, so
+   * auth tokens and other metadata must be passed as query parameters instead.
+   *
+   * ```typescript
+   * passthroughRequestHeaders = ['authorization', 'x-user-id'];
+   * ```
+   *
+   * Values are read from the URL at connect time and stored in _requestHeaders
+   * for the lifetime of the Durable Object instance.
+   */
+  passthroughRequestHeaders: string[];
   /** Tools that are always active regardless of loaded skills */
   abstract getTools(): ToolSet;
   /** All skills available for on-demand loading */
@@ -276,6 +298,8 @@ declare abstract class AIChatAgentBase<Env extends Cloudflare.Env = Cloudflare.E
    * skill when activate_skill is called. Defaults to allow-all.
    */
   protected filterSkill(_skillName: string): Promise<boolean>;
+  /** @internal Captured header values, keyed by lowercase name. */
+  protected _requestHeaders: Record<string, string>;
   /**
    * Buffered skill state from the current turn.
    *
@@ -409,13 +433,30 @@ declare function withSkills(fn: WithSkillsFn, _context: ClassMethodDecoratorCont
  * ```typescript
  * export class MyAgent extends AIChatAgent {
  *   getModel()        { return openai("gpt-4o"); }
- *   getTools()        { return []; }
+ *   getTools()        { return tools; }
  *   getSkills()       { return [searchSkill, codeSkill]; }
  *   getSystemPrompt() { return "You are a helpful assistant."; }
  *   getDB()           { return this.env.AGENT_DB; }
  * }
  * ```
  *
+ * ## Passing auth headers to tools
+ *
+ * Set `passthroughRequestHeaders` to capture headers from the WebSocket upgrade
+ * request. They are forwarded automatically to every tool via `experimental_context`:
+ *
+ * ```typescript
+ * passthroughRequestHeaders = ['authorization', 'x-user-id'];
+ * ```
+ *
+ * Tools receive them as the second `execute` argument:
+ *
+ * ```typescript
+ * execute: async (args, { experimental_context }) => {
+ *   const { authorization } = experimental_context?.headers ?? {};
+ * }
+ * ```
+ *
  * If you need full control over the `streamText` call (custom model options,
  * streaming transforms, varying the model per request, etc.) use
  * `AIChatAgentBase` with the `@withSkills` decorator instead.
@@ -446,6 +487,24 @@ declare abstract class AIChatAgent<Env extends Cloudflare.Env = Cloudflare.Env>
   onChatMessage(onFinish: StreamTextOnFinishCallback<ToolSet>, options?: OnChatMessageOptions): Promise<Response | undefined>;
 }
 //#endregion
+//#region src/agents/chat/types.d.ts
+/**
+ * The shape of experimental_context passed to tool execute functions.
+ *
+ * Cast experimental_context to this type to access forwarded request headers:
+ *
+ * ```typescript
+ * import type { AgentToolContext } from '@economic/agents';
+ *
+ * execute: async (args, { experimental_context }) => {
+ *   const { authorization } = experimental_context as AgentToolContext;
+ * }
+ * ```
+ */
+interface AgentToolContext {
+  headers: Record<string, string>;
+}
+//#endregion
 //#region src/features/skills/index.d.ts
 /**
  * Creates a skill loading system for use with the Vercel AI SDK.
@@ -565,4 +624,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, compactIfNeeded, compactMessages, createSkills, estimateMessagesTokens, filterEphemeralMessages, injectGuidance, withSkills };
+export { AIChatAgent, AIChatAgentBase, type AgentToolContext, COMPACT_TOKEN_THRESHOLD, type Skill, type SkillContext, type SkillsConfig, type SkillsResult, compactIfNeeded, compactMessages, createSkills, estimateMessagesTokens, filterEphemeralMessages, injectGuidance, withSkills };

package/dist/index.mjs

@@ -447,6 +447,21 @@ var AIChatAgentBase = class extends AIChatAgent$1 {
 	*/
 	maxPersistedMessages = 50;
 	/**
+	* Query parameter names to read from the WebSocket connection URL and
+	* forward to tools via experimental_context.
+	*
+	* Browsers cannot set custom headers on WebSocket upgrade requests, so
+	* auth tokens and other metadata must be passed as query parameters instead.
+	*
+	* ```typescript
+	* passthroughRequestHeaders = ['authorization', 'x-user-id'];
+	* ```
+	*
+	* Values are read from the URL at connect time and stored in _requestHeaders
+	* for the lifetime of the Durable Object instance.
+	*/
+	passthroughRequestHeaders = [];
+	/**
 	* Return a LanguageModel to use for compaction summarisation.
 	*
 	* Return undefined (default) to disable compaction — messages are kept up
@@ -476,6 +491,8 @@ var AIChatAgentBase = class extends AIChatAgent$1 {
 	async filterSkill(_skillName) {
 		return true;
 	}
+	/** @internal Captured header values, keyed by lowercase name. */
+	_requestHeaders = {};
 	/**
 	* Buffered skill state from the current turn.
 	*
@@ -519,6 +536,14 @@ var AIChatAgentBase = class extends AIChatAgent$1 {
 	* that case and replays in-progress chunks via its own protocol.
 	*/
 	async onConnect(connection, ctx) {
+		if (this.passthroughRequestHeaders.length > 0) {
+			this._requestHeaders = {};
+			const params = new URL(ctx.request.url).searchParams;
+			for (const name of this.passthroughRequestHeaders) {
+				const value = params.get(name);
+				if (value !== null) this._requestHeaders[name] = value;
+			}
+		}
 		await super.onConnect(connection, ctx);
 		if (!this._activeStreamId && this.messages.length > 0) connection.send(JSON.stringify({
 			type: "cf_agent_chat_messages",
@@ -593,7 +618,8 @@ var AIChatAgentBase = class extends AIChatAgent$1 {
 			activeTools: skills.activeTools,
 			prepareStep: skills.prepareStep,
 			guidance: skills.getLoadedGuidance(),
-			messages: await convertToModelMessages(this.messages)
+			messages: await convertToModelMessages(this.messages),
+			headers: this._requestHeaders
 		};
 	}
 };
@@ -622,13 +648,30 @@ function withSkills(fn, _context) {
 * ```typescript
 * export class MyAgent extends AIChatAgent {
 *   getModel()        { return openai("gpt-4o"); }
-*   getTools()        { return []; }
+*   getTools()        { return tools; }
 *   getSkills()       { return [searchSkill, codeSkill]; }
 *   getSystemPrompt() { return "You are a helpful assistant."; }
 *   getDB()           { return this.env.AGENT_DB; }
 * }
 * ```
 *
+* ## Passing auth headers to tools
+*
+* Set `passthroughRequestHeaders` to capture headers from the WebSocket upgrade
+* request. They are forwarded automatically to every tool via `experimental_context`:
+*
+* ```typescript
+* passthroughRequestHeaders = ['authorization', 'x-user-id'];
+* ```
+*
+* Tools receive them as the second `execute` argument:
+*
+* ```typescript
+* execute: async (args, { experimental_context }) => {
+*   const { authorization } = experimental_context?.headers ?? {};
+* }
+* ```
+*
 * If you need full control over the `streamText` call (custom model options,
 * streaming transforms, varying the model per request, etc.) use
 * `AIChatAgentBase` with the `@withSkills` decorator instead.
@@ -665,6 +708,7 @@ var AIChatAgent = class extends AIChatAgentBase {
 			tools: skills.tools,
 			activeTools: skills.activeTools,
 			prepareStep: skills.prepareStep,
+			experimental_context: { headers: this._requestHeaders },
 			stopWhen: stepCountIs(20),
 			abortSignal: options?.abortSignal,
 			onFinish

package/package.json

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