@economic/agents 1.8.2 → 2.0.0

package/dist/telemetry-a-1XBTxr.mjs

@@ -0,0 +1,372 @@
+import { createRemoteJWKSet, decodeJwt, errors, jwtVerify } from "jose";
+import { BasicTracerProvider, SimpleSpanProcessor } from "@opentelemetry/sdk-trace-base";
+//#region src/server/shared/features/auth/index.ts
+const jwksByIssuer = /* @__PURE__ */ new Map();
+function getJwksForIssuer(issuer) {
+	const normalized = issuer.replace(/\/$/, "");
+	let jwks = jwksByIssuer.get(normalized);
+	if (!jwks) {
+		jwks = createRemoteJWKSet(new URL(`${normalized}/.well-known/openid-configuration/jwks`));
+		jwksByIssuer.set(normalized, jwks);
+	}
+	return jwks;
+}
+function isIssuerAllowed(iss, allowed) {
+	return allowed.some((rule) => typeof rule === "string" ? rule === iss : rule.test(iss));
+}
+function extractTokenFromConnectRequest(request) {
+	const authorization = request.headers.get("Authorization");
+	if (authorization) {
+		const match = authorization.match(/^Bearer\s+(.+)$/i);
+		if (match?.[1]) return match[1].trim();
+	}
+	const wsProtocol = request.headers.get("Sec-WebSocket-Protocol");
+	if (wsProtocol) {
+		const parts = wsProtocol.split(",").map((p) => p.trim());
+		const idx = parts.indexOf("bearer");
+		if (idx !== -1 && parts[idx + 1]) return parts[idx + 1];
+	}
+	return null;
+}
+function hasRequiredScopes(tokenScope, required) {
+	if (required.length === 0) return true;
+	if (tokenScope === void 0) return false;
+	const tokens = Array.isArray(tokenScope) ? tokenScope : tokenScope.split(" ").map((s) => s.trim()).filter(Boolean);
+	const granted = new Set(tokens);
+	return required.every((scope) => granted.has(scope));
+}
+/**
+* Verify a JWT from a request and extract claims.
+*
+* Extracts the token from `Authorization: Bearer` header first,
+* then falls back to `Sec-WebSocket-Protocol: bearer, <token>` for WebSocket connections.
+*
+* Expected auth failures (missing/expired token, insufficient scope) return a failure result.
+* Unexpected errors (network issues, malformed requests, untrusted issuers) throw and should
+* be caught and logged by the caller.
+*
+* @param request - The incoming request (from ConnectionContext)
+* @param config - JWT verification configuration
+* @returns Result object with either verified claims or expected auth failure
+* @throws Error for unexpected failures that should be logged
+*/
+async function verifyJwt(request, config) {
+	const token = extractTokenFromConnectRequest(request);
+	if (!token) return {
+		success: false,
+		status: 401,
+		message: "Unauthorized: Missing authentication token"
+	};
+	let unverifiedPayload;
+	try {
+		unverifiedPayload = decodeJwt(token);
+	} catch {
+		throw new Error("Invalid token format");
+	}
+	const iss = typeof unverifiedPayload.iss === "string" ? unverifiedPayload.iss : void 0;
+	if (!iss) throw new Error("Missing issuer claim in token");
+	if (!isIssuerAllowed(iss, config.allowedIssuers)) throw new Error(`Untrusted issuer: ${iss}`);
+	const jwks = getJwksForIssuer(iss);
+	let payload;
+	try {
+		payload = (await jwtVerify(token, jwks, {
+			issuer: iss,
+			audience: config.audience
+		})).payload;
+	} catch (error) {
+		if (error instanceof errors.JWTExpired) return {
+			success: false,
+			status: 401,
+			message: "Unauthorized: Token expired"
+		};
+		if (error instanceof errors.JWTClaimValidationFailed) return {
+			success: false,
+			status: 401,
+			message: "Unauthorized: Token claim validation failed"
+		};
+		if (error instanceof errors.JWSSignatureVerificationFailed || error instanceof errors.JWKSNoMatchingKey) throw new Error("Invalid token signature");
+		throw error;
+	}
+	const requiredScopes = config.requiredScopes ?? [];
+	const scopeClaim = payload.scope;
+	if (!hasRequiredScopes(scopeClaim, requiredScopes)) return {
+		success: false,
+		status: 403,
+		message: "Forbidden: Insufficient scope"
+	};
+	return {
+		success: true,
+		claims: config.getClaims(payload)
+	};
+}
+//#endregion
+//#region src/server/shared/features/telemetry/utils.ts
+function durationMs(duration) {
+	return duration[0] * 1e3 + duration[1] / 1e6;
+}
+function stringAttribute(span, key) {
+	const value = span.attributes[key];
+	return typeof value === "string" ? value : void 0;
+}
+function numberAttribute(span, key) {
+	const value = span.attributes[key];
+	return typeof value === "number" ? value : void 0;
+}
+function parseJson(value) {
+	if (!value) return;
+	try {
+		return JSON.parse(value);
+	} catch {
+		return;
+	}
+}
+//#endregion
+//#region src/server/shared/features/telemetry/audit-logs.ts
+function safePathSegment(value, fallback) {
+	return (value || fallback).replace(/[^a-zA-Z0-9._-]/g, "_");
+}
+function createAuditLogKey(agentName, conversationId) {
+	const timestamp = (/* @__PURE__ */ new Date()).toISOString().replaceAll(":", "-");
+	const id = crypto.randomUUID().slice(0, 8);
+	return [
+		safePathSegment(agentName, "unknown-agent"),
+		safePathSegment(conversationId, "unknown-conversation"),
+		`${timestamp}-${id}.json`
+	].join("/");
+}
+function textFromContent(content) {
+	if (typeof content === "string") return content;
+	if (Array.isArray(content)) return content.map((part) => {
+		if (!part || typeof part !== "object") return "";
+		const value = part.text;
+		return typeof value === "string" ? value : "";
+	}).filter(Boolean).join("\n");
+	return "";
+}
+function extractPrompt(messages) {
+	const firstUserMessage = messages.find((message) => message.role === "user");
+	return firstUserMessage ? textFromContent(firstUserMessage.content) : "";
+}
+function promptCharCount(messages) {
+	const firstUserMessage = messages.find((message) => message.role === "user");
+	return firstUserMessage ? textFromContent(firstUserMessage.content).length : 0;
+}
+function extractTools(messages) {
+	const tools = [];
+	for (const message of messages) {
+		if (message.role !== "assistant" || !Array.isArray(message.content)) continue;
+		for (const part of message.content) {
+			if (!part || typeof part !== "object") continue;
+			const record = part;
+			if (record.type !== "tool_use") continue;
+			tools.push({
+				name: typeof record.name === "string" ? record.name : void 0,
+				input: record.input,
+				status: "success"
+			});
+		}
+	}
+	return tools;
+}
+function extractSkillName(toolName, input) {
+	if (!input || typeof input !== "object") return;
+	const record = input;
+	if (toolName === "load_context") {
+		const key = record.key;
+		return typeof key === "string" ? key : void 0;
+	}
+	if (toolName === "activate_skill") {
+		const skill = record.skill ?? record.name ?? record.key;
+		return typeof skill === "string" ? skill : void 0;
+	}
+}
+function pushToolCall(map, key, toolCall) {
+	const existing = map.get(key);
+	if (existing) existing.push(toolCall);
+	else map.set(key, [toolCall]);
+}
+/**
+* Stores the last ai.streamText.doStream span per conversation.
+* Its ai.prompt.messages contains the full conversation history including all
+* intermediate tool_use + tool_result turns from the agentic loop.
+*/
+const lastDoStreamByConversation = /* @__PURE__ */ new Map();
+const toolCallsByParentSpan = /* @__PURE__ */ new Map();
+const toolCallsByConversation = /* @__PURE__ */ new Map();
+const pendingToolCalls = [];
+const currentSkillByConversation = /* @__PURE__ */ new Map();
+function rememberToolCall(span) {
+	const parentSpanId = span.parentSpanContext?.spanId;
+	const toolName = stringAttribute(span, "ai.toolCall.name");
+	const input = parseJson(stringAttribute(span, "ai.toolCall.args"));
+	const toolCall = {
+		name: toolName,
+		input,
+		status: span.status.code === 0 ? "success" : "error",
+		skillName: extractSkillName(toolName, input)
+	};
+	if (parentSpanId) pushToolCall(toolCallsByParentSpan, parentSpanId, toolCall);
+	pendingToolCalls.push(toolCall);
+}
+function attachToolCallsToConversation(span, conversationId) {
+	const spanId = span.spanContext().spanId;
+	const toolCalls = toolCallsByParentSpan.get(spanId) ?? pendingToolCalls.splice(0);
+	if (!toolCalls.length) return;
+	toolCallsByParentSpan.delete(spanId);
+	const currentSkill = currentSkillByConversation.get(conversationId);
+	const attributedToolCalls = toolCalls.map((toolCall) => {
+		const skillName = toolCall.skillName ?? currentSkill;
+		if (toolCall.skillName) currentSkillByConversation.set(conversationId, toolCall.skillName);
+		return {
+			...toolCall,
+			...skillName ? { skillName } : {}
+		};
+	});
+	toolCallsByConversation.set(conversationId, [...toolCallsByConversation.get(conversationId) ?? [], ...attributedToolCalls]);
+}
+function buildAuditLog(span, context) {
+	const lastDoStream = lastDoStreamByConversation.get(context.conversationId);
+	lastDoStreamByConversation.delete(context.conversationId);
+	const promptMessages = parseJson(stringAttribute(lastDoStream ?? span, "ai.prompt.messages"));
+	const fallbackPrompt = parseJson(stringAttribute(span, "ai.prompt"));
+	const inputMessages = promptMessages ?? fallbackPrompt?.messages ?? [];
+	const spanToolCalls = toolCallsByConversation.get(context.conversationId) ?? [];
+	toolCallsByConversation.delete(context.conversationId);
+	return {
+		id: createAuditLogKey(context.agentName, context.conversationId),
+		timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+		conversationId: context.conversationId,
+		agent: {
+			name: context.agentName,
+			llm: {
+				model: stringAttribute(span, "ai.model.id"),
+				provider: stringAttribute(span, "ai.model.provider")
+			}
+		},
+		actor: {
+			userId: context.userId,
+			ip: {
+				client: context.clientIp ?? context.forwardedFor?.split(",").map((ip) => ip.trim()).filter(Boolean)[0],
+				forwardedFor: context.forwardedFor?.split(",").map((ip) => ip.trim()).filter(Boolean) ?? []
+			}
+		},
+		prompt: extractPrompt(inputMessages),
+		response: stringAttribute(span, "ai.response.text") ?? "",
+		status: span.status.code === 0 ? "success" : "error",
+		tools: [...extractTools(inputMessages), ...spanToolCalls]
+	};
+}
+function rememberDoStream(span, conversationId) {
+	lastDoStreamByConversation.set(conversationId, span);
+}
+async function handleAuditSpan(span, auditLogs, context) {
+	const auditLog = buildAuditLog(span, context);
+	if (!auditLogs) return;
+	await auditLogs.put(auditLog.id, JSON.stringify(auditLog, null, 2), { httpMetadata: { contentType: "application/json" } });
+	console.log("[AuditLog] Created", auditLog.id);
+}
+//#endregion
+//#region src/server/shared/features/telemetry/analytics.ts
+function writeAnalyticsDatapoint(analytics, dataPoint) {
+	if (!analytics) return;
+	try {
+		analytics.writeDataPoint(dataPoint);
+	} catch (error) {
+		console.error("[Agent] Failed to write analytics datapoint", error);
+	}
+}
+function handleAnalyticsSpan(span, analytics) {
+	if (span.name === "ai.streamText.doStream") {
+		const promptMessages = parseJson(stringAttribute(span, "ai.prompt.messages"));
+		const responseText = stringAttribute(span, "ai.response.text") ?? "";
+		writeAnalyticsDatapoint(analytics, {
+			indexes: [stringAttribute(span, "ai.telemetry.metadata.userId") ?? ""],
+			blobs: [
+				"llm_call",
+				stringAttribute(span, "ai.telemetry.metadata.agentName") ?? "",
+				stringAttribute(span, "ai.telemetry.metadata.conversationId") ?? "",
+				stringAttribute(span, "ai.model.id") ?? "",
+				stringAttribute(span, "ai.model.provider") ?? "",
+				stringAttribute(span, "ai.response.finishReason") ?? ""
+			],
+			doubles: [
+				numberAttribute(span, "ai.usage.inputTokens") ?? 0,
+				numberAttribute(span, "ai.usage.outputTokens") ?? 0,
+				numberAttribute(span, "ai.usage.totalTokens") ?? 0,
+				numberAttribute(span, "ai.usage.inputTokenDetails.cacheReadTokens") ?? 0,
+				numberAttribute(span, "ai.usage.inputTokenDetails.cacheWriteTokens") ?? 0,
+				durationMs(span.duration),
+				promptCharCount(promptMessages ?? []),
+				responseText.length
+			]
+		});
+		return;
+	}
+	if (span.name === "ai.toolCall") {
+		const toolName = stringAttribute(span, "ai.toolCall.name");
+		const toolInput = parseJson(stringAttribute(span, "ai.toolCall.args"));
+		const conversationId = stringAttribute(span, "ai.telemetry.metadata.conversationId") ?? "";
+		const skillName = extractSkillName(toolName, toolInput) ?? currentSkillByConversation.get(conversationId) ?? "";
+		const success = span.status.code === 0;
+		writeAnalyticsDatapoint(analytics, {
+			indexes: [stringAttribute(span, "ai.telemetry.metadata.userId") ?? ""],
+			blobs: [
+				"tool_call",
+				stringAttribute(span, "ai.telemetry.metadata.agentName") ?? "",
+				conversationId,
+				toolName ?? "",
+				skillName,
+				success ? "success" : "error"
+			],
+			doubles: [
+				durationMs(span.duration),
+				success ? 1 : 0,
+				0,
+				0,
+				0,
+				0,
+				0,
+				0
+			]
+		});
+	}
+}
+//#endregion
+//#region src/server/shared/features/telemetry/index.ts
+var AgentSpanExporter = class {
+	auditLogs;
+	analytics;
+	context;
+	constructor(auditLogs, analytics, context) {
+		this.auditLogs = auditLogs;
+		this.analytics = analytics;
+		this.context = context;
+	}
+	export(spans, resultCallback) {
+		(async () => {
+			try {
+				for (const span of spans) if (span.name === "ai.streamText.doStream") {
+					rememberDoStream(span, this.context.conversationId);
+					attachToolCallsToConversation(span, this.context.conversationId);
+					handleAnalyticsSpan(span, this.analytics);
+				} else if (span.name === "ai.streamText") await handleAuditSpan(span, this.auditLogs, this.context);
+				else if (span.name === "ai.toolCall") {
+					rememberToolCall(span);
+					handleAnalyticsSpan(span, this.analytics);
+				}
+				resultCallback({ code: 0 });
+			} catch (error) {
+				resultCallback({
+					code: 1,
+					error: error instanceof Error ? error : new Error(String(error))
+				});
+			}
+		})();
+	}
+	async shutdown() {}
+};
+function createAgentTracer(auditLogs, analytics, context) {
+	return new BasicTracerProvider({ spanProcessors: [new SimpleSpanProcessor(new AgentSpanExporter(auditLogs, analytics, context))] }).getTracer("@economic/agents");
+}
+//#endregion
+export { extractTokenFromConnectRequest as n, verifyJwt as r, createAgentTracer as t };

package/dist/v2.d.mts

@@ -0,0 +1,164 @@
+import { t as JwtAuthConfig } from "./index-DzOC3mNl.mjs";
+import { JSONValue, LanguageModel, Tool as Tool$1, UIMessage } from "ai";
+import { Agent as Agent$1, Connection, ConnectionContext, SubAgentClass } from "agents";
+import { ChatResponseResult, Session, StepConfig, Think, ToolCallContext, ToolCallDecision, TurnConfig, TurnContext } from "@cloudflare/think";
+
+//#region src/server/v2/types.d.ts
+/**
+ * The context object available throughout an agent's lifetime — passed via
+ * `experimental_context` to tool `execute` functions. Contains the typed
+ * request body merged with platform capabilities like `logEvent`.ext = AgentToolContext<MyBody>;
+ * ```
+ */
+type ToolContext<RequestContext extends Record<string, unknown> = Record<string, unknown>, UserContext = Record<string, unknown> | undefined> = RequestContext & {
+  _userContext?: UserContext;
+};
+interface AgentEnv {
+  AGENT_DB: D1Database;
+  AGENTS_AUDIT_LOGS: R2Bucket;
+  AGENTS_ANALYTICS: AnalyticsEngineDataset;
+  SKILLS_BUCKET: R2Bucket;
+}
+//#endregion
+//#region src/server/v2/util/tools.d.ts
+type ToolSet = Record<string, Tool>;
+type Tool<Context extends Record<string, unknown> = Record<string, unknown>, INPUT extends JSONValue | unknown | never = any, OUTPUT extends JSONValue | unknown | never = any> = Tool$1<INPUT, OUTPUT> & {
+  authorize?: (ctx: Context) => boolean;
+};
+declare function tool<Context extends Record<string, unknown> = Record<string, unknown>, INPUT extends JSONValue | unknown | never = any, OUTPUT extends JSONValue | unknown | never = any>(tool: Tool<Context, INPUT, OUTPUT>): Tool$1<INPUT, OUTPUT>;
+//#endregion
+//#region src/server/v2/util/skills.d.ts
+interface Skill<Context extends Record<string, unknown> = Record<string, unknown>> {
+  name: string;
+  description: string;
+  instructions: string;
+  tools?: Record<string, Tool<Context>>;
+  authorize?: (ctx: Context) => boolean;
+}
+declare function skill<Context extends Record<string, unknown> = Record<string, unknown>>(definition: Skill<Context>): Skill<Context>;
+//#endregion
+//#region src/server/v2/agents/Agent.d.ts
+declare function getCurrentToolContext(): any;
+type AgentConnectionStatus = "connecting" | "connected" | "disconnected" | "unauthorized";
+type AgentConnectionType = "agent" | "chat" | "assistant";
+type AgentConnectionState = {
+  status: AgentConnectionStatus;
+  type: AgentConnectionType;
+};
+declare abstract class Agent<RequestContext extends Record<string, unknown> = Record<string, unknown>, UserContext extends Record<string, unknown> = Record<string, unknown>> extends Think<Cloudflare.Env & AgentEnv, AgentConnectionState> {
+  initialState: AgentConnectionState;
+  protected clientIp?: string;
+  protected forwardedFor?: string;
+  /**
+   * Returns the user ID from the durable object name.
+   */
+  protected getUserIdFromDurableObjectName(): string;
+  protected getParentAgent<T extends Agent$1>(): T | undefined;
+  abstract getModel(ctx?: ToolContext<RequestContext, UserContext>): LanguageModel;
+  abstract getSystemPrompt(ctx?: ToolContext<RequestContext, UserContext>): string;
+  configureSession(session: Session): Session;
+  onStart(): Promise<void>;
+  onConnect(connection: Connection, ctx: ConnectionContext): Promise<void>;
+  /**
+   * Merges the client request `body` into `experimental_context` for tools
+   * returned from {@link getTools} only (Think-internal tools are unchanged).
+   *
+   * If you override `beforeTurn`, call `super.beforeTurn(ctx)` and merge
+   * `returned.tools` into your own `TurnConfig.tools` if you return tools.
+   */
+  beforeTurn(ctx: TurnContext): Promise<void | TurnConfig>;
+  /**
+   * Sets active tools based on skills that might be loaded in the current turn.
+   *
+   * @param ctx - The prepare step context.
+   * @returns The step config.
+   */
+  beforeStep(): Promise<StepConfig | void>;
+  beforeToolCall(ctx: ToolCallContext): Promise<ToolCallDecision | void>;
+  private _buildToolContext;
+  getTools(): ToolSet;
+  /**
+   * Returns the remote skills to be loaded from SKILLS_BUCKET.
+   * @returns The remote skills to be loaded from SKILLS_BUCKET.
+   */
+  protected getRemoteSkills(): string[];
+  /**
+   * Returns the skills to load for the agent.
+   * @returns The skills to load for the agent.
+   */
+  protected getSkills(): Skill[];
+  private _getAuthorizedTools;
+  private _getAuthorizedSkills;
+  /** Store the pending user context request to defer awaiting it until after the connection is established */
+  private _requestContext?;
+  /**
+   * Override to enable JWT authentication on WebSocket connections.
+   * Return the auth config based on the incoming request, or undefined to skip auth.
+   * Do not add side effects to this method - return a single JwtAuthConfig from it.
+   *
+   * @param env - The worker environment variables
+   * @returns JWT auth config or undefined to skip authentication
+   */
+  static getJwtAuthConfig?(env: Cloudflare.Env): JwtAuthConfig<Record<string, unknown>> | undefined;
+  /** Store the pending user context request to defer awaiting it until after the connection is established */
+  private _pendingUserContextRequest?;
+  /**
+   * The user context for the session.
+   * Define getUserContext to set a user context.
+   */
+  private _userContext?;
+  /**
+   * Returns the identity following verification of the JWT token - getJwtAuthConfig is required.
+   * This method should not have side effects - return a single object from it.
+   * @returns The user context from the request.
+   * @param jwtToken - A valid JWT token following authentication.
+   */
+  protected getUserContext?(jwtToken: string): Promise<UserContext>;
+}
+//#endregion
+//#region src/server/v2/agents/ChatAgent.d.ts
+declare abstract class ChatAgent<RequestContext extends Record<string, unknown> = Record<string, unknown>, UserContext extends Record<string, unknown> = Record<string, unknown>> extends Agent<RequestContext, UserContext> {
+  initialState: AgentConnectionState;
+  onStart(): Promise<void>;
+  configureSession(session: Session): Session;
+  onChatResponse(_result: ChatResponseResult): Promise<void>;
+  /**
+   * Rate a message by its id.
+   * @param messageId - The id of the message to rate.
+   * @param rating - The rating to give the message. 1 = thumbs up, -1 = thumbs down.
+   * @returns The message id and the rating.
+   */
+  rateMessage(messageId: string, rating: number, comment?: string): Promise<void>;
+  /**
+   * Returns all message ratings for the current conversation.
+   * @returns All message ratings for the current conversation.
+   */
+  getMessageRatings(): Promise<any>;
+}
+//#endregion
+//#region src/server/v2/features/conversations.d.ts
+type Conversation = {
+  durable_object_name: string;
+  title?: string;
+  summary?: string;
+  created_at: number;
+  updated_at: number;
+};
+declare const DELETE_CONVERSATION_CALLBACK: "deleteConversationCallback";
+//#endregion
+//#region src/server/v2/agents/Assistant.d.ts
+declare abstract class Assistant extends Agent$1<Cloudflare.Env, AgentConnectionState> {
+  initialState: AgentConnectionState;
+  protected abstract agent: SubAgentClass<ChatAgent>;
+  protected abstract fastModel: LanguageModel;
+  onStart(): void;
+  onConnect(): Promise<void>;
+  createConversation(): Promise<string>;
+  deleteConversation(id: string): Promise<void>;
+  getConversations(): Promise<Conversation[]>;
+  recordConversationTurn(durableObjectName: string, messages: UIMessage[]): Promise<void>;
+  private [DELETE_CONVERSATION_CALLBACK];
+  private scheduleConversationForAutoDeletion;
+}
+//#endregion
+export { Agent, type AgentEnv, Assistant, ChatAgent, type Skill, type Tool, type ToolContext, type ToolSet, getCurrentToolContext, skill, tool };