@poncho-ai/harness 0.14.1 → 0.14.2

package/.turbo/turbo-build.log

@@ -1,5 +1,5 @@
 
-> @poncho-ai/harness@0.14.1 build /home/runner/work/poncho-ai/poncho-ai/packages/harness
+> @poncho-ai/harness@0.14.2 build /Users/cesar/Dev/latitude/poncho-ai/packages/harness
 > tsup src/index.ts --format esm --dts
 
 CLI Building entry: src/index.ts
@@ -7,8 +7,8 @@
 CLI tsup v8.5.1
 CLI Target: es2022
 ESM Build start
-ESM dist/index.js 175.01 KB
-ESM ⚡️ Build success in 76ms
+ESM dist/index.js 177.01 KB
+ESM ⚡️ Build success in 73ms
 DTS Build start
-DTS ⚡️ Build success in 5663ms
-DTS dist/index.d.ts 21.38 KB
+DTS ⚡️ Build success in 3459ms
+DTS dist/index.d.ts 21.71 KB

package/.turbo/turbo-lint.log

@@ -0,0 +1,6 @@
+
+> @poncho-ai/harness@0.11.2 lint /Users/cesar/Dev/latitude/poncho-ai/packages/harness
+> eslint src/
+
+sh: eslint: command not found
+ ELIFECYCLE  Command failed.

package/.turbo/turbo-test.log

@@ -0,0 +1,137 @@
+
+> @poncho-ai/harness@0.14.0 test /Users/cesar/Dev/latitude/poncho-ai/packages/harness
+> vitest
+
+
+ RUN  v1.6.1 /Users/cesar/Dev/latitude/poncho-ai/packages/harness
+
+[event] step:completed {"type":"step:completed","step":1,"duration":1}
+[event] step:started {"type":"step:started","step":2}
+ ✓ test/telemetry.test.ts  (3 tests) 11ms
+ ✓ test/schema-converter.test.ts  (27 tests) 21ms
+stdout | test/mcp.test.ts > mcp bridge protocol transports > discovers and calls tools over streamable HTTP
+[poncho][mcp] {"event":"catalog.loaded","server":"remote","discoveredCount":1}
+[poncho][mcp] {"event":"tools.selected","requestedPatternCount":1,"registeredCount":1,"filteredByPolicyCount":0,"filteredByIntentCount":0}
+
+stdout | test/mcp.test.ts > mcp bridge protocol transports > selects discovered tools by requested patterns
+[poncho][mcp] {"event":"catalog.loaded","server":"remote","discoveredCount":2}
+[poncho][mcp] {"event":"tools.selected","requestedPatternCount":1,"registeredCount":1,"filteredByPolicyCount":0,"filteredByIntentCount":1}
+[poncho][mcp] {"event":"tools.selected","requestedPatternCount":1,"registeredCount":2,"filteredByPolicyCount":0,"filteredByIntentCount":0}
+
+stdout | test/mcp.test.ts > mcp bridge protocol transports > skips discovery when bearer token env value is missing
+[poncho][mcp] {"event":"tools.selected","requestedPatternCount":1,"registeredCount":0,"filteredByPolicyCount":0,"filteredByIntentCount":0}
+
+stderr | test/mcp.test.ts > mcp bridge protocol transports > skips discovery when bearer token env value is missing
+[poncho][mcp] {"event":"auth.token_missing","server":"remote","tokenEnv":"MISSING_TOKEN_ENV"}
+
+stdout | test/mcp.test.ts > mcp bridge protocol transports > returns actionable errors for 403 permission failures
+[poncho][mcp] {"event":"catalog.loaded","server":"remote","discoveredCount":1}
+[poncho][mcp] {"event":"tools.selected","requestedPatternCount":1,"registeredCount":1,"filteredByPolicyCount":0,"filteredByIntentCount":0}
+
+ ✓ test/mcp.test.ts  (6 tests) 516ms
+ ✓ test/agent-parser.test.ts  (10 tests) 130ms
+ ✓ test/memory.test.ts  (4 tests) 192ms
+ ✓ test/state.test.ts  (5 tests) 294ms
+ ✓ test/model-factory.test.ts  (4 tests) 8ms
+ ✓ test/agent-identity.test.ts  (2 tests) 33ms
+stdout | test/harness.test.ts > agent harness > registers default filesystem tools
+[poncho][mcp] {"event":"tools.cleared","reason":"initialize","requestedPatterns":[]}
+
+stdout | test/harness.test.ts > agent harness > disables write_file by default in production environment
+[poncho][mcp] {"event":"tools.cleared","reason":"initialize","requestedPatterns":[]}
+
+stdout | test/harness.test.ts > agent harness > allows disabling built-in tools via poncho.config.js
+[poncho][mcp] {"event":"tools.cleared","reason":"initialize","requestedPatterns":[]}
+
+stdout | test/harness.test.ts > agent harness > supports per-environment tool overrides
+[poncho][mcp] {"event":"tools.cleared","reason":"initialize","requestedPatterns":[]}
+
+stdout | test/harness.test.ts > agent harness > supports per-environment tool overrides
+[poncho][mcp] {"event":"tools.cleared","reason":"initialize","requestedPatterns":[]}
+
+stdout | test/harness.test.ts > agent harness > does not auto-register exported tool objects from skill scripts
+[poncho][mcp] {"event":"tools.cleared","reason":"initialize","requestedPatterns":[]}
+
+stdout | test/harness.test.ts > agent harness > refreshes skill metadata and tools in development mode
+[poncho][mcp] {"event":"tools.cleared","reason":"initialize","requestedPatterns":[]}
+
+stdout | test/harness.test.ts > agent harness > refreshes skill metadata and tools in development mode
+[poncho][mcp] {"event":"tools.cleared","reason":"skills:changed","requestedPatterns":[]}
+[poncho][mcp] {"event":"tools.cleared","reason":"activate:beta","requestedPatterns":[]}
+
+stdout | test/harness.test.ts > agent harness > prunes removed active skills after refresh in development mode
+[poncho][mcp] {"event":"tools.cleared","reason":"initialize","requestedPatterns":[]}
+[poncho][mcp] {"event":"tools.cleared","reason":"activate:obsolete","requestedPatterns":[]}
+
+stdout | test/harness.test.ts > agent harness > prunes removed active skills after refresh in development mode
+[poncho][mcp] {"event":"tools.cleared","reason":"skills:changed","requestedPatterns":[]}
+
+stdout | test/harness.test.ts > agent harness > does not refresh skills outside development mode
+[poncho][mcp] {"event":"tools.cleared","reason":"initialize","requestedPatterns":[]}
+
+stdout | test/harness.test.ts > agent harness > clears active skills when skill metadata changes in development mode
+[poncho][mcp] {"event":"tools.cleared","reason":"initialize","requestedPatterns":[]}
+
+stdout | test/harness.test.ts > agent harness > clears active skills when skill metadata changes in development mode
+[poncho][mcp] {"event":"tools.cleared","reason":"activate:alpha","requestedPatterns":[]}
+
+stdout | test/harness.test.ts > agent harness > clears active skills when skill metadata changes in development mode
+[poncho][mcp] {"event":"tools.cleared","reason":"skills:changed","requestedPatterns":[]}
+
+stdout | test/harness.test.ts > agent harness > lists skill scripts through list_skill_scripts
+[poncho][mcp] {"event":"tools.cleared","reason":"initialize","requestedPatterns":[]}
+
+stdout | test/harness.test.ts > agent harness > runs JavaScript/TypeScript skill scripts through run_skill_script
+[poncho][mcp] {"event":"tools.cleared","reason":"initialize","requestedPatterns":[]}
+
+stdout | test/harness.test.ts > agent harness > runs AGENT-scope scripts from root scripts directory
+[poncho][mcp] {"event":"tools.cleared","reason":"initialize","requestedPatterns":[]}
+
+stdout | test/harness.test.ts > agent harness > blocks path traversal in run_skill_script
+[poncho][mcp] {"event":"tools.cleared","reason":"initialize","requestedPatterns":[]}
+
+stdout | test/harness.test.ts > agent harness > requires allowed-tools entries for non-standard script directories
+[poncho][mcp] {"event":"tools.cleared","reason":"initialize","requestedPatterns":[]}
+
+stdout | test/harness.test.ts > agent harness > registers MCP tools dynamically for stacked active skills and supports deactivation
+[poncho][mcp] {"event":"catalog.loaded","server":"remote","discoveredCount":2}
+[poncho][mcp] {"event":"tools.cleared","reason":"initialize","requestedPatterns":[]}
+[poncho][mcp] {"event":"tools.selected","requestedPatternCount":1,"registeredCount":1,"filteredByPolicyCount":0,"filteredByIntentCount":1}
+[poncho][mcp] {"event":"tools.refreshed","reason":"activate:skill-a","requestedPatterns":["remote/a"],"registeredCount":1,"activeSkills":["skill-a"]}
+[poncho][mcp] {"event":"tools.selected","requestedPatternCount":2,"registeredCount":2,"filteredByPolicyCount":0,"filteredByIntentCount":0}
+[poncho][mcp] {"event":"tools.refreshed","reason":"activate:skill-b","requestedPatterns":["remote/a","remote/b"],"registeredCount":2,"activeSkills":["skill-a","skill-b"]}
+[poncho][mcp] {"event":"tools.selected","requestedPatternCount":1,"registeredCount":1,"filteredByPolicyCount":0,"filteredByIntentCount":1}
+[poncho][mcp] {"event":"tools.refreshed","reason":"deactivate:skill-a","requestedPatterns":["remote/b"],"registeredCount":1,"activeSkills":["skill-b"]}
+
+stdout | test/harness.test.ts > agent harness > supports flat tool access config format
+[poncho][mcp] {"event":"tools.cleared","reason":"initialize","requestedPatterns":[]}
+
+stdout | test/harness.test.ts > agent harness > flat tool access takes priority over legacy defaults
+[poncho][mcp] {"event":"tools.cleared","reason":"initialize","requestedPatterns":[]}
+
+stdout | test/harness.test.ts > agent harness > byEnvironment overrides flat tool access
+[poncho][mcp] {"event":"tools.cleared","reason":"initialize","requestedPatterns":[]}
+
+stdout | test/harness.test.ts > agent harness > registerTools skips tools disabled via config
+[poncho][mcp] {"event":"tools.cleared","reason":"initialize","requestedPatterns":[]}
+
+stdout | test/harness.test.ts > agent harness > approval access level registers the tool but marks it for approval
+[poncho][mcp] {"event":"tools.cleared","reason":"initialize","requestedPatterns":[]}
+
+stdout | test/harness.test.ts > agent harness > tools without approval config do not require approval
+[poncho][mcp] {"event":"tools.cleared","reason":"initialize","requestedPatterns":[]}
+
+stdout | test/harness.test.ts > agent harness > allows in-flight MCP calls to finish after skill deactivation
+[poncho][mcp] {"event":"catalog.loaded","server":"remote","discoveredCount":1}
+[poncho][mcp] {"event":"tools.cleared","reason":"initialize","requestedPatterns":[]}
+[poncho][mcp] {"event":"tools.selected","requestedPatternCount":1,"registeredCount":1,"filteredByPolicyCount":0,"filteredByIntentCount":0}
+[poncho][mcp] {"event":"tools.refreshed","reason":"activate:skill-slow","requestedPatterns":["remote/slow"],"registeredCount":1,"activeSkills":["skill-slow"]}
+[poncho][mcp] {"event":"tools.cleared","reason":"deactivate:skill-slow","requestedPatterns":[]}
+
+ ✓ test/harness.test.ts  (25 tests) 429ms
+
+ Test Files  9 passed (9)
+      Tests  86 passed (86)
+   Start at  10:02:54
+   Duration  4.19s (transform 2.16s, setup 0ms, collect 7.51s, tests 1.63s, environment 1ms, prepare 1.97s)
+

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # @poncho-ai/harness
 
+## 0.14.2
+
+### Patch Changes
+
+- [`1f47bb4`](https://github.com/cesr/poncho-ai/commit/1f47bb49e5d48dc17644172012b057190b316469) Thanks [@cesr](https://github.com/cesr)! - Add conversation rename via double-click on the title in the web UI, standardize all credential config fields to the `*Env` naming pattern, and sync the init README template with the repo README.
+
+- Updated dependencies [[`1f47bb4`](https://github.com/cesr/poncho-ai/commit/1f47bb49e5d48dc17644172012b057190b316469)]:
+  - @poncho-ai/sdk@1.0.3
+
 ## 0.14.1
 
 ### Patch Changes

package/dist/index.d.ts

@@ -111,8 +111,8 @@ type StateProviderName = "local" | "memory" | "redis" | "upstash" | "dynamodb";
 interface StateConfig {
     provider?: StateProviderName;
     ttl?: number;
-    url?: string;
-    token?: string;
+    urlEnv?: string;
+    tokenEnv?: string;
     table?: string;
     region?: string;
 }
@@ -154,8 +154,8 @@ interface MainMemory {
 interface MemoryConfig {
     enabled?: boolean;
     provider?: StateProviderName;
-    url?: string;
-    token?: string;
+    urlEnv?: string;
+    tokenEnv?: string;
     table?: string;
     region?: string;
     ttl?: number;
@@ -218,8 +218,8 @@ declare class LocalMcpBridge {
 
 interface StorageConfig {
     provider?: "local" | "memory" | "redis" | "upstash" | "dynamodb";
-    url?: string;
-    token?: string;
+    urlEnv?: string;
+    tokenEnv?: string;
     table?: string;
     region?: string;
     ttl?: number | {
@@ -274,6 +274,7 @@ interface PonchoConfig extends McpConfig {
         required?: boolean;
         type?: "bearer" | "header" | "custom";
         headerName?: string;
+        tokenEnv?: string;
         validate?: (token: string, req?: unknown) => Promise<boolean> | boolean;
     };
     state?: {
@@ -283,12 +284,20 @@ interface PonchoConfig extends McpConfig {
     };
     memory?: MemoryConfig;
     storage?: StorageConfig;
+    providers?: {
+        openai?: {
+            apiKeyEnv?: string;
+        };
+        anthropic?: {
+            apiKeyEnv?: string;
+        };
+    };
     telemetry?: {
         enabled?: boolean;
         otlp?: string;
         latitude?: {
-            apiKey?: string;
-            projectId?: string | number;
+            apiKeyEnv?: string;
+            projectIdEnv?: string;
             path?: string;
             documentPath?: string;
         };
@@ -363,12 +372,20 @@ type ModelProviderFactory = (modelName: string) => LanguageModel;
  * resolve via the base prefix. Longest match wins.
  */
 declare const getModelContextWindow: (modelName: string) => number;
+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`.
  */
-declare const createModelProvider: (provider?: string) => ModelProviderFactory;
+declare const createModelProvider: (provider?: string, config?: ProviderConfig) => ModelProviderFactory;
 
 interface ToolCall {
     id: string;
@@ -489,8 +506,8 @@ declare class AgentHarness {
  * Vercel AI SDK support.
  */
 interface LatitudeCaptureConfig {
-    apiKey?: string;
-    projectId?: string | number;
+    apiKeyEnv?: string;
+    projectIdEnv?: string;
     path?: string;
     defaultPath?: string;
 }
@@ -585,8 +602,8 @@ interface TelemetryConfig {
     enabled?: boolean;
     otlp?: string;
     latitude?: {
-        apiKey?: string;
-        projectId?: string | number;
+        apiKeyEnv?: string;
+        projectIdEnv?: string;
         path?: string;
         documentPath?: string;
     };
@@ -599,4 +616,4 @@ declare class TelemetryEmitter {
     private sendOtlp;
 }
 
-export { type AgentFrontmatter, AgentHarness, type AgentIdentity, type AgentLimitsConfig, type AgentModelConfig, type BuiltInToolToggles, type Conversation, type ConversationState, type ConversationStore, type CronJobConfig, type HarnessOptions, type HarnessRunOutput, InMemoryConversationStore, InMemoryStateStore, LatitudeCapture, type LatitudeCaptureConfig, LocalMcpBridge, LocalUploadStore, type MainMemory, type McpConfig, type MemoryConfig, type MemoryStore, type MessagingChannelConfig, type ModelProviderFactory, PONCHO_UPLOAD_SCHEME, type ParsedAgent, type PonchoConfig, type RemoteMcpServerConfig, type RuntimeRenderContext, S3UploadStore, STORAGE_SCHEMA_VERSION, type SkillContextEntry, type SkillMetadata, type StateConfig, type StateProviderName, type StateStore, type StorageConfig, type TelemetryConfig, TelemetryEmitter, type ToolAccess, type ToolCall, ToolDispatcher, type ToolExecutionResult, type UploadStore, type UploadsConfig, VercelBlobUploadStore, buildAgentDirectoryName, buildSkillContextWindow, createConversationStore, createDefaultTools, createMemoryStore, createMemoryTools, createModelProvider, createSkillTools, createStateStore, createUploadStore, createWriteTool, deriveUploadKey, ensureAgentIdentity, generateAgentId, getAgentStoreDirectory, getModelContextWindow, getPonchoStoreRoot, jsonSchemaToZod, loadPonchoConfig, loadSkillContext, loadSkillInstructions, loadSkillMetadata, normalizeScriptPolicyPath, parseAgentFile, parseAgentMarkdown, readSkillResource, renderAgentPrompt, resolveAgentIdentity, resolveMemoryConfig, resolveSkillDirs, resolveStateConfig, slugifyStorageComponent };
+export { type AgentFrontmatter, AgentHarness, type AgentIdentity, type AgentLimitsConfig, type AgentModelConfig, type BuiltInToolToggles, type Conversation, type ConversationState, type ConversationStore, type CronJobConfig, type HarnessOptions, type HarnessRunOutput, InMemoryConversationStore, InMemoryStateStore, LatitudeCapture, type LatitudeCaptureConfig, LocalMcpBridge, LocalUploadStore, type MainMemory, type McpConfig, type MemoryConfig, type MemoryStore, type MessagingChannelConfig, type ModelProviderFactory, PONCHO_UPLOAD_SCHEME, type ParsedAgent, type PonchoConfig, type ProviderConfig, type RemoteMcpServerConfig, type RuntimeRenderContext, S3UploadStore, STORAGE_SCHEMA_VERSION, type SkillContextEntry, type SkillMetadata, type StateConfig, type StateProviderName, type StateStore, type StorageConfig, type TelemetryConfig, TelemetryEmitter, type ToolAccess, type ToolCall, ToolDispatcher, type ToolExecutionResult, type UploadStore, type UploadsConfig, VercelBlobUploadStore, buildAgentDirectoryName, buildSkillContextWindow, createConversationStore, createDefaultTools, createMemoryStore, createMemoryTools, createModelProvider, createSkillTools, createStateStore, createUploadStore, createWriteTool, deriveUploadKey, ensureAgentIdentity, generateAgentId, getAgentStoreDirectory, getModelContextWindow, getPonchoStoreRoot, jsonSchemaToZod, loadPonchoConfig, loadSkillContext, loadSkillInstructions, loadSkillMetadata, normalizeScriptPolicyPath, parseAgentFile, parseAgentMarkdown, readSkillResource, renderAgentPrompt, resolveAgentIdentity, resolveMemoryConfig, resolveSkillDirs, resolveStateConfig, slugifyStorageComponent };

package/dist/index.js

@@ -330,8 +330,8 @@ var resolveStateConfig = (config) => {
   if (config?.storage) {
     return {
       provider: config.storage.provider,
-      url: config.storage.url,
-      token: config.storage.token,
+      urlEnv: config.storage.urlEnv,
+      tokenEnv: config.storage.tokenEnv,
       table: config.storage.table,
       region: config.storage.region,
       ttl: resolveTtl(config.storage.ttl, "conversations")
@@ -344,8 +344,8 @@ var resolveMemoryConfig = (config) => {
     return {
       enabled: config.storage.memory?.enabled ?? config.memory?.enabled,
       provider: config.storage.provider,
-      url: config.storage.url,
-      token: config.storage.token,
+      urlEnv: config.storage.urlEnv,
+      tokenEnv: config.storage.tokenEnv,
       table: config.storage.table,
       region: config.storage.region,
       ttl: resolveTtl(config.storage.ttl, "memory"),
@@ -1121,8 +1121,10 @@ var createMemoryStore = (agentId, config, options) => {
     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,
@@ -1134,7 +1136,8 @@ var createMemoryStore = (agentId, config, options) => {
     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,
@@ -1763,16 +1766,18 @@ var getModelContextWindow = (modelName) => {
   }
   return best ? MODEL_CONTEXT_WINDOWS[best] : DEFAULT_CONTEXT_WINDOW;
 };
-var createModelProvider = (provider) => {
+var createModelProvider = (provider, config) => {
   const normalized = (provider ?? "anthropic").toLowerCase();
   if (normalized === "openai") {
+    const apiKeyEnv2 = config?.openai?.apiKeyEnv ?? "OPENAI_API_KEY";
     const openai = createOpenAI({
-      apiKey: process.env.OPENAI_API_KEY
+      apiKey: process.env[apiKeyEnv2]
     });
     return (modelName) => 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) => anthropic(modelName);
 };
@@ -2812,18 +2817,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\` \u2014 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 \u2014 never the secret itself. Sensible defaults mean zero config when using conventional env var names.
+
+\`\`\`javascript
+// poncho.config.js \u2014 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:
 
@@ -2838,6 +2876,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>\`.
@@ -3157,7 +3196,7 @@ var AgentHarness = class {
     const provider = this.parsedAgent.frontmatter.model?.provider ?? "anthropic";
     const memoryConfig = resolveMemoryConfig(config);
     if (!this.modelProviderInjected) {
-      this.modelProvider = createModelProvider(provider);
+      this.modelProvider = createModelProvider(provider, config?.providers);
     }
     const bridge = new LocalMcpBridge(config);
     this.mcpBridge = bridge;
@@ -3184,10 +3223,12 @@ var AgentHarness = class {
     await bridge.discoverTools();
     await this.refreshMcpTools("initialize");
     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) : void 0;
     if (telemetryEnabled && latitudeApiKey && latitudeProjectId) {
       diag.setLogger(
         {
@@ -3209,14 +3250,10 @@ var AgentHarness = class {
       this.latitudeTelemetry = new LatitudeTelemetry(latitudeApiKey, { disableBatch: true });
     } else if (telemetryEnabled && latitudeBlock && (!latitudeApiKey || !latitudeProjectId)) {
       const missing = [];
-      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(", ")} \u2013 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.`
       );
     }
   }
@@ -3242,8 +3279,8 @@ var AgentHarness = class {
     const config = this.loadedConfig;
     const telemetry = this.latitudeTelemetry;
     if (telemetry) {
-      const rawProjectId = config?.telemetry?.latitude?.projectId;
-      const projectId = typeof rawProjectId === "string" ? parseInt(rawProjectId, 10) : rawProjectId;
+      const latProjectIdEnv2 = config?.telemetry?.latitude?.projectIdEnv ?? "LATITUDE_PROJECT_ID";
+      const projectId = parseInt(process.env[latProjectIdEnv2] ?? "", 10);
       const rawPath = config?.telemetry?.latitude?.path ?? this.parsedAgent?.frontmatter.name ?? "agent";
       const path = rawPath.replace(/[^\w\-./]/g, "-").replace(/-+/g, "-").replace(/^-+|-+$/g, "") || "agent";
       const conversationUuid = input.conversationId ?? (typeof input.parameters?.__activeConversationId === "string" ? input.parameters.__activeConversationId : void 0);
@@ -3641,7 +3678,6 @@ ${textContent}` };
         const modelInstance = this.modelProvider(modelName);
         const cachedMessages = addPromptCacheBreakpoints(coreMessages, modelInstance);
         const telemetryEnabled = this.loadedConfig?.telemetry?.enabled !== false;
-        const latitudeApiKey = this.loadedConfig?.telemetry?.latitude?.apiKey;
         const result = await streamText({
           model: modelInstance,
           system: integrityPrompt,
@@ -3651,7 +3687,7 @@ ${textContent}` };
           abortSignal: input.abortSignal,
           ...typeof maxTokens === "number" ? { maxTokens } : {},
           experimental_telemetry: {
-            isEnabled: telemetryEnabled && !!latitudeApiKey
+            isEnabled: telemetryEnabled && !!this.latitudeTelemetry
           }
         });
         let fullText = "";
@@ -4114,9 +4150,11 @@ var LatitudeCapture = class {
   projectId;
   path;
   constructor(config) {
-    this.apiKey = config?.apiKey ?? process.env.LATITUDE_API_KEY;
-    const rawProjectId = config?.projectId ?? process.env.LATITUDE_PROJECT_ID;
-    const projectIdNumber = typeof rawProjectId === "number" ? rawProjectId : rawProjectId ? Number.parseInt(rawProjectId, 10) : Number.NaN;
+    const apiKeyEnv = config?.apiKeyEnv ?? "LATITUDE_API_KEY";
+    this.apiKey = process.env[apiKeyEnv];
+    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 : void 0;
     const rawPath = config?.path ?? process.env.LATITUDE_PATH ?? process.env.LATITUDE_DOCUMENT_PATH ?? config?.defaultPath;
     this.path = rawPath;
@@ -5024,15 +5062,18 @@ var createStateStore = (config, options) => {
     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);
     }
@@ -5058,15 +5099,18 @@ var createConversationStore = (config, options) => {
     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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@poncho-ai/harness",
-  "version": "0.14.1",
+  "version": "0.14.2",
   "description": "Agent execution runtime - conversation loop, tool dispatch, streaming",
   "repository": {
     "type": "git",
@@ -31,7 +31,7 @@
     "redis": "^5.10.0",
     "yaml": "^2.4.0",
     "zod": "^3.22.0",
-    "@poncho-ai/sdk": "1.0.2"
+    "@poncho-ai/sdk": "1.0.3"
   },
   "devDependencies": {
     "@types/mustache": "^4.2.6",

package/src/config.ts

@@ -7,8 +7,8 @@ import type { StateConfig } from "./state.js";
 
 export interface StorageConfig {
   provider?: "local" | "memory" | "redis" | "upstash" | "dynamodb";
-  url?: string;
-  token?: string;
+  urlEnv?: string;
+  tokenEnv?: string;
   table?: string;
   region?: string;
   ttl?:
@@ -76,6 +76,7 @@ export interface PonchoConfig extends McpConfig {
     required?: boolean;
     type?: "bearer" | "header" | "custom";
     headerName?: string;
+    tokenEnv?: string;
     validate?: (token: string, req?: unknown) => Promise<boolean> | boolean;
   };
   state?: {
@@ -85,12 +86,16 @@ export interface PonchoConfig extends McpConfig {
   };
   memory?: MemoryConfig;
   storage?: StorageConfig;
+  providers?: {
+    openai?: { apiKeyEnv?: string };
+    anthropic?: { apiKeyEnv?: string };
+  };
   telemetry?: {
     enabled?: boolean;
     otlp?: string;
     latitude?: {
-      apiKey?: string;
-      projectId?: string | number;
+      apiKeyEnv?: string;
+      projectIdEnv?: string;
       path?: string;
       documentPath?: string;
     };
@@ -130,8 +135,8 @@ export const resolveStateConfig = (
   if (config?.storage) {
     return {
       provider: config.storage.provider,
-      url: config.storage.url,
-      token: config.storage.token,
+      urlEnv: config.storage.urlEnv,
+      tokenEnv: config.storage.tokenEnv,
       table: config.storage.table,
       region: config.storage.region,
       ttl: resolveTtl(config.storage.ttl, "conversations"),
@@ -147,8 +152,8 @@ export const resolveMemoryConfig = (
     return {
       enabled: config.storage.memory?.enabled ?? config.memory?.enabled,
       provider: config.storage.provider,
-      url: config.storage.url,
-      token: config.storage.token,
+      urlEnv: config.storage.urlEnv,
+      tokenEnv: config.storage.tokenEnv,
       table: config.storage.table,
       region: config.storage.region,
       ttl: resolveTtl(config.storage.ttl, "memory"),

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";
@@ -367,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:
 
@@ -393,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>\`.
@@ -758,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;
@@ -793,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) => {
@@ -817,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.`,
       );
     }
   }
@@ -858,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';
@@ -1340,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,
@@ -1353,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.

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

@@ -61,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;
 }
@@ -1166,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);
     }
@@ -1204,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",
       },
     });