@poncho-ai/harness 0.14.0 → 0.14.2

package/src/harness.ts

@@ -22,7 +22,7 @@ import {
   type MemoryStore,
 } from "./memory.js";
 import { LocalMcpBridge } from "./mcp.js";
-import { createModelProvider, getModelContextWindow, type ModelProviderFactory } from "./model-factory.js";
+import { createModelProvider, getModelContextWindow, type ModelProviderFactory, type ProviderConfig } from "./model-factory.js";
 import { buildSkillContextWindow, loadSkillMetadata } from "./skill-context.js";
 import { streamText, type ModelMessage } from "ai";
 import { addPromptCacheBreakpoints } from "./prompt-cache.js";
@@ -37,20 +37,13 @@ import {
   matchesSlashPattern,
   normalizeRelativeScriptPattern,
 } from "./tool-policy.js";
-import { ToolDispatcher } from "./tool-dispatcher.js";
+import { ToolDispatcher, type ToolCall, type ToolExecutionResult } from "./tool-dispatcher.js";
 import { ensureAgentIdentity } from "./agent-identity.js";
 
 export interface HarnessOptions {
   workingDir?: string;
   environment?: "development" | "staging" | "production";
   toolDefinitions?: ToolDefinition[];
-  approvalHandler?: (request: {
-    tool: string;
-    input: Record<string, unknown>;
-    runId: string;
-    step: number;
-    approvalId: string;
-  }) => Promise<boolean> | boolean;
   modelProvider?: ModelProviderFactory;
   uploadStore?: UploadStore;
 }
@@ -374,18 +367,51 @@ When configuring Latitude telemetry, use **exactly** these field names:
 telemetry: {
   enabled: true,
   latitude: {
-    apiKey: process.env.LATITUDE_API_KEY,       // NOT "apiKeyEnv"
-    projectId: process.env.LATITUDE_PROJECT_ID, // string or number
-    path: "your/prompt-path",                   // optional, defaults to agent name
+    apiKeyEnv: "LATITUDE_API_KEY",       // env var name (default)
+    projectIdEnv: "LATITUDE_PROJECT_ID", // env var name (default)
+    path: "your/prompt-path",            // optional, defaults to agent name
   },
 },
 \`\`\`
 
-- The field is \`apiKey\` (not \`apiKeyEnv\`, \`api_key\`, or \`key\`).
-- The field is \`projectId\` (not \`project_id\`, \`projectID\`, or \`project\`).
+- \`apiKeyEnv\` specifies the environment variable name for the Latitude API key (defaults to \`"LATITUDE_API_KEY"\`).
+- \`projectIdEnv\` specifies the environment variable name for the project ID (defaults to \`"LATITUDE_PROJECT_ID"\`).
+- With defaults, you only need \`telemetry: { latitude: {} }\` if the env vars are already named \`LATITUDE_API_KEY\` and \`LATITUDE_PROJECT_ID\`.
 - \`path\` must only contain letters, numbers, hyphens, underscores, dots, and slashes.
 - For a generic OTLP endpoint instead: \`telemetry: { otlp: process.env.OTEL_EXPORTER_OTLP_ENDPOINT }\`.
-- Always read the env vars from \`process.env\` — do not hardcode secrets in \`poncho.config.js\`.
+
+## Credential Configuration Pattern
+
+All credentials in \`poncho.config.js\` use the **env var name** pattern (\`*Env\` fields). Config specifies which environment variable to read — never the secret itself. Sensible defaults mean zero config when using conventional env var names.
+
+\`\`\`javascript
+// poncho.config.js — credentials use *Env fields with defaults
+export default {
+  // Model provider API keys (optional, defaults shown)
+  providers: {
+    anthropic: { apiKeyEnv: "ANTHROPIC_API_KEY" },
+    openai: { apiKeyEnv: "OPENAI_API_KEY" },
+  },
+  auth: {
+    required: true,
+    tokenEnv: "PONCHO_AUTH_TOKEN",  // default
+  },
+  storage: {
+    provider: "upstash",
+    urlEnv: "UPSTASH_REDIS_REST_URL",       // default (falls back to KV_REST_API_URL)
+    tokenEnv: "UPSTASH_REDIS_REST_TOKEN",   // default (falls back to KV_REST_API_TOKEN)
+  },
+  telemetry: {
+    latitude: {
+      apiKeyEnv: "LATITUDE_API_KEY",       // default
+      projectIdEnv: "LATITUDE_PROJECT_ID", // default
+    },
+  },
+  messaging: [{ platform: "slack" }],      // reads SLACK_BOT_TOKEN, SLACK_SIGNING_SECRET by default
+}
+\`\`\`
+
+Since all fields have defaults, you only need to specify \`*Env\` when your env var name differs from the convention.
 
 ## When users ask about customization:
 
@@ -400,6 +426,7 @@ telemetry: {
 - To scope tools to a skill: keep server config in \`poncho.config.js\`, add desired \`allowed-tools\`/ \`approval-required\` patterns in that skill's \`SKILL.md\`, and remove global \`AGENT.md\` patterns if you do not want global availability.
 - Do not invent unsupported top-level config keys (for example \`model\` in \`poncho.config.js\`). Keep existing config structure unless README/spec explicitly says otherwise.
 - Keep \`poncho.config.js\` valid JavaScript and preserve existing imports/types/comments. If there is a JSDoc type import, do not rewrite it to a different package name.
+- Credentials always use \`*Env\` fields (env var names), never raw \`process.env.*\` values. For example, use \`apiKeyEnv: "MY_KEY"\` not \`apiKey: process.env.MY_KEY\`.
 - Preferred MCP config shape in \`poncho.config.js\`:
   \`mcp: [{ name: "linear", url: "https://mcp.linear.app/mcp", auth: { type: "bearer", tokenEnv: "LINEAR_TOKEN" } }]\`
 - If shell/CLI access exists, you can use \`poncho mcp add --url ... --name ... --auth-bearer-env ...\`, then \`poncho mcp tools list <server>\` and \`poncho mcp tools select <server>\`.
@@ -414,7 +441,6 @@ export class AgentHarness {
   private modelProvider: ModelProviderFactory;
   private readonly modelProviderInjected: boolean;
   private readonly dispatcher = new ToolDispatcher();
-  private readonly approvalHandler?: HarnessOptions["approvalHandler"];
   readonly uploadStore?: UploadStore;
   private skillContextWindow = "";
   private memoryStore?: MemoryStore;
@@ -500,7 +526,6 @@ export class AgentHarness {
     this.environment = options.environment ?? "development";
     this.modelProviderInjected = !!options.modelProvider;
     this.modelProvider = options.modelProvider ?? createModelProvider("anthropic");
-    this.approvalHandler = options.approvalHandler;
     this.uploadStore = options.uploadStore;
 
     if (options.toolDefinitions?.length) {
@@ -767,10 +792,8 @@ export class AgentHarness {
     this.registerConfiguredBuiltInTools(config);
     const provider = this.parsedAgent.frontmatter.model?.provider ?? "anthropic";
     const memoryConfig = resolveMemoryConfig(config);
-    // Only create modelProvider if one wasn't injected (for production use)
-    // Tests can inject a mock modelProvider via constructor options
     if (!this.modelProviderInjected) {
-      this.modelProvider = createModelProvider(provider);
+      this.modelProvider = createModelProvider(provider, config?.providers);
     }
     const bridge = new LocalMcpBridge(config);
     this.mcpBridge = bridge;
@@ -802,14 +825,13 @@ export class AgentHarness {
     // Creating a new LatitudeTelemetry per run would break on the second call
     // because @opentelemetry/api silently ignores repeated global registrations.
     const telemetryEnabled = config?.telemetry?.enabled !== false;
-    const latitudeApiKey = config?.telemetry?.latitude?.apiKey;
-    const rawProjectId = config?.telemetry?.latitude?.projectId;
-    const latitudeProjectId = typeof rawProjectId === 'string' ? parseInt(rawProjectId, 10) : rawProjectId;
     const latitudeBlock = config?.telemetry?.latitude;
+    const latApiKeyEnv = latitudeBlock?.apiKeyEnv ?? "LATITUDE_API_KEY";
+    const latProjectIdEnv = latitudeBlock?.projectIdEnv ?? "LATITUDE_PROJECT_ID";
+    const latitudeApiKey = process.env[latApiKeyEnv];
+    const rawProjectId = process.env[latProjectIdEnv];
+    const latitudeProjectId = rawProjectId ? parseInt(rawProjectId, 10) : undefined;
     if (telemetryEnabled && latitudeApiKey && latitudeProjectId) {
-      // Surface genuine OTLP export failures. Suppress "duplicate registration"
-      // errors that fire when the dev server re-initializes the harness — the
-      // first registration persists and telemetry keeps working.
       diag.setLogger(
         {
           error: (msg, ...args) => {
@@ -826,16 +848,10 @@ export class AgentHarness {
       this.latitudeTelemetry = new LatitudeTelemetry(latitudeApiKey, { disableBatch: true });
     } else if (telemetryEnabled && latitudeBlock && (!latitudeApiKey || !latitudeProjectId)) {
       const missing: string[] = [];
-      if (!latitudeApiKey) missing.push("apiKey");
-      if (!latitudeProjectId) missing.push("projectId");
-      const unknownKeys = Object.keys(latitudeBlock).filter(
-        (k) => !["apiKey", "projectId", "path", "documentPath"].includes(k),
-      );
-      const hint = unknownKeys.length > 0
-        ? ` (found unknown key${unknownKeys.length > 1 ? "s" : ""}: ${unknownKeys.join(", ")} – did you mean "apiKey"?)`
-        : "";
+      if (!latitudeApiKey) missing.push(`${latApiKeyEnv} env var`);
+      if (!latitudeProjectId) missing.push(`${latProjectIdEnv} env var`);
       console.warn(
-        `[poncho][telemetry] Latitude telemetry is configured but missing: ${missing.join(", ")}${hint}. Traces will NOT be sent.`,
+        `[poncho][telemetry] Latitude telemetry is configured but missing: ${missing.join(", ")}. Traces will NOT be sent.`,
       );
     }
   }
@@ -867,8 +883,8 @@ export class AgentHarness {
     const telemetry = this.latitudeTelemetry;
 
     if (telemetry) {
-      const rawProjectId = config?.telemetry?.latitude?.projectId;
-      const projectId = (typeof rawProjectId === 'string' ? parseInt(rawProjectId, 10) : rawProjectId) as number;
+      const latProjectIdEnv2 = config?.telemetry?.latitude?.projectIdEnv ?? "LATITUDE_PROJECT_ID";
+      const projectId = parseInt(process.env[latProjectIdEnv2] ?? "", 10) as number;
       const rawPath = config?.telemetry?.latitude?.path ?? this.parsedAgent?.frontmatter.name ?? 'agent';
       // Sanitize path for Latitude's DOCUMENT_PATH_REGEXP: /^([\w-]+\/)*([\w-.])+$/
       const path = rawPath.replace(/[^\w\-./]/g, '-').replace(/-+/g, '-').replace(/^-+|-+$/g, '') || 'agent';
@@ -963,6 +979,7 @@ export class AgentHarness {
       ? platformMaxDurationSec * 800
       : 0;
     const messages: Message[] = [...(input.messages ?? [])];
+    const inputMessageCount = messages.length;
     const events: AgentEvent[] = [];
 
     const systemPrompt = renderAgentPrompt(agent, {
@@ -1024,41 +1041,43 @@ ${boundedMainMemory.trim()}`
       contextWindow,
     });
 
-    if (input.files && input.files.length > 0) {
-      const parts: ContentPart[] = [
-        { type: "text", text: input.task } satisfies TextContentPart,
-      ];
-      for (const file of input.files) {
-        if (this.uploadStore) {
-          const buf = Buffer.from(file.data, "base64");
-          const key = deriveUploadKey(buf, file.mediaType);
-          const ref = await this.uploadStore.put(key, buf, file.mediaType);
-          parts.push({
-            type: "file",
-            data: ref,
-            mediaType: file.mediaType,
-            filename: file.filename,
-          } satisfies FileContentPart);
-        } else {
-          parts.push({
-            type: "file",
-            data: file.data,
-            mediaType: file.mediaType,
-            filename: file.filename,
-          } satisfies FileContentPart);
+    if (input.task != null) {
+      if (input.files && input.files.length > 0) {
+        const parts: ContentPart[] = [
+          { type: "text", text: input.task } satisfies TextContentPart,
+        ];
+        for (const file of input.files) {
+          if (this.uploadStore) {
+            const buf = Buffer.from(file.data, "base64");
+            const key = deriveUploadKey(buf, file.mediaType);
+            const ref = await this.uploadStore.put(key, buf, file.mediaType);
+            parts.push({
+              type: "file",
+              data: ref,
+              mediaType: file.mediaType,
+              filename: file.filename,
+            } satisfies FileContentPart);
+          } else {
+            parts.push({
+              type: "file",
+              data: file.data,
+              mediaType: file.mediaType,
+              filename: file.filename,
+            } satisfies FileContentPart);
+          }
         }
+        messages.push({
+          role: "user",
+          content: parts,
+          metadata: { timestamp: now(), id: randomUUID() },
+        });
+      } else {
+        messages.push({
+          role: "user",
+          content: input.task,
+          metadata: { timestamp: now(), id: randomUUID() },
+        });
       }
-      messages.push({
-        role: "user",
-        content: parts,
-        metadata: { timestamp: now(), id: randomUUID() },
-      });
-    } else {
-      messages.push({
-        role: "user",
-        content: input.task,
-        metadata: { timestamp: now(), id: randomUUID() },
-      });
     }
 
     let responseText = "";
@@ -1346,9 +1365,7 @@ ${boundedMainMemory.trim()}`
         const modelInstance = this.modelProvider(modelName);
         const cachedMessages = addPromptCacheBreakpoints(coreMessages, modelInstance);
 
-        // Stream response using Vercel AI SDK with telemetry enabled
         const telemetryEnabled = this.loadedConfig?.telemetry?.enabled !== false;
-        const latitudeApiKey = this.loadedConfig?.telemetry?.latitude?.apiKey;
 
         const result = await streamText({
           model: modelInstance,
@@ -1359,7 +1376,7 @@ ${boundedMainMemory.trim()}`
           abortSignal: input.abortSignal,
           ...(typeof maxTokens === "number" ? { maxTokens } : {}),
           experimental_telemetry: {
-            isEnabled: telemetryEnabled && !!latitudeApiKey,
+            isEnabled: telemetryEnabled && !!this.latitudeTelemetry,
           },
         });
         // Stream text chunks — enforce overall run timeout per chunk.
@@ -1597,47 +1614,35 @@ ${boundedMainMemory.trim()}`
             input: call.input,
             approvalId,
           });
-          const approved = this.approvalHandler
-            ? await this.approvalHandler({
-                tool: runtimeToolName,
-                input: call.input,
-                runId,
-                step,
-                approvalId,
-              })
-            : false;
-          if (isCancelled()) {
-            yield emitCancellation();
-            return;
-          }
-          if (!approved) {
-            if (this.insideTelemetryCapture && this.latitudeTelemetry) {
-              const deniedSpan = this.latitudeTelemetry.span.tool({
-                name: runtimeToolName,
-                call: { id: call.id, arguments: call.input },
-              });
-              deniedSpan.end({ result: { value: "Tool execution denied by approval policy", isError: true } });
-            }
-            yield pushEvent({
-              type: "tool:approval:denied",
-              approvalId,
-              reason: "No approval handler granted execution",
-            });
-            yield pushEvent({
-              type: "tool:error",
-              tool: call.name,
-              error: "Tool execution denied by approval policy",
-              recoverable: true,
-            });
-            toolResultsForModel.push({
-              type: "tool_result",
-              tool_use_id: call.id,
-              tool_name: runtimeToolName,
-              content: "Tool error: Tool execution denied by approval policy",
-            });
-            continue;
-          }
-          yield pushEvent({ type: "tool:approval:granted", approvalId });
+
+          const assistantContent = JSON.stringify({
+            text: fullText,
+            tool_calls: toolCalls.map(tc => ({
+              id: tc.id,
+              name: exposedToolNames.get(tc.name) ?? tc.name,
+              input: tc.input,
+            })),
+          });
+          const assistantMsg: Message = {
+            role: "assistant",
+            content: assistantContent,
+            metadata: { timestamp: now(), id: randomUUID(), step },
+          };
+          const deltaMessages = [...messages.slice(inputMessageCount), assistantMsg];
+          yield pushEvent({
+            type: "tool:approval:checkpoint",
+            approvalId,
+            tool: runtimeToolName,
+            toolCallId: call.id,
+            input: call.input,
+            checkpointMessages: deltaMessages,
+            pendingToolCalls: toolCalls.map(tc => ({
+              id: tc.id,
+              name: exposedToolNames.get(tc.name) ?? tc.name,
+              input: tc.input,
+            })),
+          });
+          return;
         }
         approvedCalls.push({
           id: call.id,
@@ -1790,12 +1795,87 @@ ${boundedMainMemory.trim()}`
     }
   }
 
+  async executeTools(
+    calls: ToolCall[],
+    context: ToolContext,
+  ): Promise<ToolExecutionResult[]> {
+    return this.dispatcher.executeBatch(calls, context);
+  }
+
+  async *continueFromToolResult(input: {
+    messages: Message[];
+    toolResults: Array<{ callId: string; toolName: string; result?: unknown; error?: string }>;
+    conversationId?: string;
+    parameters?: Record<string, unknown>;
+    abortSignal?: AbortSignal;
+  }): AsyncGenerator<AgentEvent> {
+    const messages = [...input.messages];
+    const lastMsg = messages[messages.length - 1];
+    if (!lastMsg || lastMsg.role !== "assistant") {
+      throw new Error("continueFromToolResult: last message must be an assistant message with tool calls");
+    }
+
+    let allToolCalls: Array<{ id: string; name: string; input: Record<string, unknown> }> = [];
+    try {
+      const parsed = JSON.parse(typeof lastMsg.content === "string" ? lastMsg.content : "");
+      allToolCalls = parsed.tool_calls ?? [];
+    } catch {
+      throw new Error("continueFromToolResult: could not parse tool calls from last assistant message");
+    }
+
+    const providedMap = new Map(
+      input.toolResults.map(r => [r.callId, r]),
+    );
+    const toolResultsForModel: Array<{
+      type: "tool_result";
+      tool_use_id: string;
+      tool_name: string;
+      content: string;
+    }> = [];
+
+    for (const tc of allToolCalls) {
+      const provided = providedMap.get(tc.id);
+      if (provided) {
+        toolResultsForModel.push({
+          type: "tool_result",
+          tool_use_id: tc.id,
+          tool_name: provided.toolName,
+          content: provided.error
+            ? `Tool error: ${provided.error}`
+            : JSON.stringify(provided.result ?? null),
+        });
+      } else {
+        toolResultsForModel.push({
+          type: "tool_result",
+          tool_use_id: tc.id,
+          tool_name: tc.name,
+          content: "Tool error: Tool execution deferred (pending approval checkpoint)",
+        });
+      }
+    }
+
+    messages.push({
+      role: "tool",
+      content: JSON.stringify(toolResultsForModel),
+      metadata: { timestamp: Date.now(), id: randomUUID() },
+    });
+
+    yield* this.runWithTelemetry({
+      messages,
+      conversationId: input.conversationId,
+      parameters: input.parameters,
+      abortSignal: input.abortSignal,
+    });
+  }
+
   async runToCompletion(input: RunInput): Promise<HarnessRunOutput> {
     const events: AgentEvent[] = [];
     let runId = "";
     let finalResult: RunResult | undefined;
     const messages: Message[] = [...(input.messages ?? [])];
-    messages.push({ role: "user", content: input.task });
+    if (input.task != null) {
+      messages.push({ role: "user", content: input.task });
+    }
 
     for await (const event of this.runWithTelemetry(input)) {
       events.push(event);

package/src/latitude-capture.ts

@@ -10,8 +10,8 @@
  */
 
 export interface LatitudeCaptureConfig {
-  apiKey?: string;
-  projectId?: string | number;
+  apiKeyEnv?: string;
+  projectIdEnv?: string;
   path?: string;
   defaultPath?: string;
 }
@@ -26,15 +26,14 @@ export class LatitudeCapture {
   private readonly path?: string;
 
   constructor(config?: LatitudeCaptureConfig) {
-    this.apiKey = config?.apiKey ?? process.env.LATITUDE_API_KEY;
+    const apiKeyEnv = config?.apiKeyEnv ?? "LATITUDE_API_KEY";
+    this.apiKey = process.env[apiKeyEnv];
 
-    const rawProjectId = config?.projectId ?? process.env.LATITUDE_PROJECT_ID;
-    const projectIdNumber =
-      typeof rawProjectId === "number"
-        ? rawProjectId
-        : rawProjectId
-          ? Number.parseInt(rawProjectId, 10)
-          : Number.NaN;
+    const projectIdEnv = config?.projectIdEnv ?? "LATITUDE_PROJECT_ID";
+    const rawProjectId = process.env[projectIdEnv];
+    const projectIdNumber = rawProjectId
+      ? Number.parseInt(rawProjectId, 10)
+      : Number.NaN;
     this.projectId = Number.isFinite(projectIdNumber) ? projectIdNumber : undefined;
 
     const rawPath =

package/src/memory.ts

@@ -17,8 +17,8 @@ export interface MainMemory {
 export interface MemoryConfig {
   enabled?: boolean;
   provider?: StateProviderName;
-  url?: string;
-  token?: string;
+  urlEnv?: string;
+  tokenEnv?: string;
   table?: string;
   region?: string;
   ttl?: number;
@@ -495,16 +495,10 @@ export const createMemoryStore = (
     return new InMemoryMemoryStore(ttl);
   }
   if (provider === "upstash") {
-    const url =
-      config?.url ??
-      process.env.UPSTASH_REDIS_REST_URL ??
-      process.env.KV_REST_API_URL ??
-      "";
-    const token =
-      config?.token ??
-      process.env.UPSTASH_REDIS_REST_TOKEN ??
-      process.env.KV_REST_API_TOKEN ??
-      "";
+    const urlEnv = config?.urlEnv ?? (process.env.UPSTASH_REDIS_REST_URL ? "UPSTASH_REDIS_REST_URL" : "KV_REST_API_URL");
+    const tokenEnv = config?.tokenEnv ?? (process.env.UPSTASH_REDIS_REST_TOKEN ? "UPSTASH_REDIS_REST_TOKEN" : "KV_REST_API_TOKEN");
+    const url = process.env[urlEnv] ?? "";
+    const token = process.env[tokenEnv] ?? "";
     if (url && token) {
       return new UpstashMemoryStore({
         baseUrl: url,
@@ -516,7 +510,8 @@ export const createMemoryStore = (
     return new InMemoryMemoryStore(ttl);
   }
   if (provider === "redis") {
-    const url = config?.url ?? process.env.REDIS_URL ?? "";
+    const urlEnv = config?.urlEnv ?? "REDIS_URL";
+    const url = process.env[urlEnv] ?? "";
     if (url) {
       return new RedisMemoryStore({
         url,

package/src/model-factory.ts

@@ -49,23 +49,30 @@ export const getModelContextWindow = (modelName: string): number => {
   return best ? MODEL_CONTEXT_WINDOWS[best]! : DEFAULT_CONTEXT_WINDOW;
 };
 
+export interface ProviderConfig {
+  openai?: { apiKeyEnv?: string };
+  anthropic?: { apiKeyEnv?: string };
+}
+
 /**
- * Creates a model provider factory for the specified AI provider
- * @param provider - The provider name ('openai' or 'anthropic')
- * @returns A function that takes a model name and returns a LanguageModel instance
+ * Creates a model provider factory for the specified AI provider.
+ * API keys are read from environment variables; override the env var
+ * name via the `providers` config in `poncho.config.js`.
  */
-export const createModelProvider = (provider?: string): ModelProviderFactory => {
+export const createModelProvider = (provider?: string, config?: ProviderConfig): ModelProviderFactory => {
   const normalized = (provider ?? "anthropic").toLowerCase();
 
   if (normalized === "openai") {
+    const apiKeyEnv = config?.openai?.apiKeyEnv ?? "OPENAI_API_KEY";
     const openai = createOpenAI({
-      apiKey: process.env.OPENAI_API_KEY,
+      apiKey: process.env[apiKeyEnv],
     });
     return (modelName: string) => openai(modelName);
   }
 
+  const apiKeyEnv = config?.anthropic?.apiKeyEnv ?? "ANTHROPIC_API_KEY";
   const anthropic = createAnthropic({
-    apiKey: process.env.ANTHROPIC_API_KEY,
+    apiKey: process.env[apiKeyEnv],
   });
   return (modelName: string) => anthropic(modelName);
 };

package/src/state.ts

@@ -30,7 +30,11 @@ export interface Conversation {
     approvalId: string;
     runId: string;
     tool: string;
+    toolCallId?: string;
     input: Record<string, unknown>;
+    checkpointMessages?: Message[];
+    baseMessageCount?: number;
+    pendingToolCalls?: Array<{ id: string; name: string; input: Record<string, unknown> }>;
   }>;
   ownerId: string;
   tenantId: string | null;
@@ -57,8 +61,8 @@ export type StateProviderName =
 export interface StateConfig {
   provider?: StateProviderName;
   ttl?: number;
-  url?: string;
-  token?: string;
+  urlEnv?: string;
+  tokenEnv?: string;
   table?: string;
   region?: string;
 }
@@ -1162,15 +1166,18 @@ export const createStateStore = (
     return new InMemoryStateStore(ttl);
   }
   if (provider === "upstash") {
-    const url = config?.url ?? process.env.UPSTASH_REDIS_REST_URL ?? "";
-    const token = config?.token ?? process.env.UPSTASH_REDIS_REST_TOKEN ?? "";
+    const urlEnv = config?.urlEnv ?? (process.env.UPSTASH_REDIS_REST_URL ? "UPSTASH_REDIS_REST_URL" : "KV_REST_API_URL");
+    const tokenEnv = config?.tokenEnv ?? (process.env.UPSTASH_REDIS_REST_TOKEN ? "UPSTASH_REDIS_REST_TOKEN" : "KV_REST_API_TOKEN");
+    const url = process.env[urlEnv] ?? "";
+    const token = process.env[tokenEnv] ?? "";
     if (url && token) {
       return new UpstashStateStore(url, token, ttl);
     }
     return new InMemoryStateStore(ttl);
   }
   if (provider === "redis") {
-    const url = config?.url ?? process.env.REDIS_URL ?? "";
+    const urlEnv = config?.urlEnv ?? "REDIS_URL";
+    const url = process.env[urlEnv] ?? "";
     if (url) {
       return new RedisLikeStateStore(url, ttl);
     }
@@ -1200,19 +1207,18 @@ export const createConversationStore = (
     return new InMemoryConversationStore(ttl);
   }
   if (provider === "upstash") {
-    const url =
-      config?.url ??
-      (process.env.UPSTASH_REDIS_REST_URL || process.env.KV_REST_API_URL || "");
-    const token =
-      config?.token ??
-      (process.env.UPSTASH_REDIS_REST_TOKEN || process.env.KV_REST_API_TOKEN || "");
+    const urlEnv = config?.urlEnv ?? (process.env.UPSTASH_REDIS_REST_URL ? "UPSTASH_REDIS_REST_URL" : "KV_REST_API_URL");
+    const tokenEnv = config?.tokenEnv ?? (process.env.UPSTASH_REDIS_REST_TOKEN ? "UPSTASH_REDIS_REST_TOKEN" : "KV_REST_API_TOKEN");
+    const url = process.env[urlEnv] ?? "";
+    const token = process.env[tokenEnv] ?? "";
     if (url && token) {
       return new UpstashConversationStore(url, token, workingDir, ttl, options?.agentId);
     }
     return new InMemoryConversationStore(ttl);
   }
   if (provider === "redis") {
-    const url = config?.url ?? process.env.REDIS_URL ?? "";
+    const urlEnv = config?.urlEnv ?? "REDIS_URL";
+    const url = process.env[urlEnv] ?? "";
     if (url) {
       return new RedisLikeConversationStore(url, workingDir, ttl, options?.agentId);
     }

package/src/telemetry.ts

@@ -4,8 +4,8 @@ export interface TelemetryConfig {
   enabled?: boolean;
   otlp?: string;
   latitude?: {
-    apiKey?: string;
-    projectId?: string | number;
+    apiKeyEnv?: string;
+    projectIdEnv?: string;
     path?: string;
     documentPath?: string;
   };

package/test/telemetry.test.ts

@@ -15,7 +15,7 @@ describe("telemetry emitter", () => {
 
     const emitter = new TelemetryEmitter({
       otlp: "https://otel.example.com/v1/logs",
-      latitude: { apiKey: "lat_test" },
+      latitude: { apiKeyEnv: "LATITUDE_API_KEY" },
     });
 
     await expect(
@@ -32,8 +32,8 @@ describe("telemetry emitter", () => {
 
     const emitter = new TelemetryEmitter({
       latitude: {
-        apiKey: "lat_test",
-        projectId: "proj_123",
+        apiKeyEnv: "LATITUDE_API_KEY",
+        projectIdEnv: "LATITUDE_PROJECT_ID",
         documentPath: "agents/support-agent/AGENT.md",
       },
     });