Merge branch 'main' into codex/qoder-environment-setup-script

Author: heimanba

bun.lock

@@ -27,6 +27,23 @@ providers:
 
 A `deployment run` on Qoder creates a native Deployment Run and associated Session. Cron schedules run server-side.
 
+## Runtime environment variables
+
+Declare `environment_variables` on an Agent to inject variables into its Qoder runtime:
+
+```yaml
+agents:
+  assistant:
+    model: { qoder: auto }
+    instructions: Help the user.
+    environment: dev
+    environment_variables:
+      FEATURE_FLAG: "on"
+      LOG_LEVEL: debug
+```
+
+OpenAgentPack maps this to each Qoder API's native shape: a top-level object on Forward Templates, `config.environment_variables` on Forward Sessions, and the required `KEY=VALUE;...` string on managed Sessions. Other providers reject this Qoder-specific field during validation.
+
 ## Tool naming
 
 Qoder uses PascalCase tool names natively (`Read`, `Glob`, `Grep`, `WebFetch`, `WebSearch`, `Write`, `Edit`, `Bash`). Write tools **lowercase** in config and OpenAgentPack converts them automatically when applying to Qoder — this keeps the same config portable to Bailian, Claude, and Volcengine Ark.

docs/guides/deploy-to-qoder.md

@@ -252,6 +252,7 @@ agents:
     skills: [ <string> | { type, skill_id, version? } ]
     vault: <string>
     memory_stores: [ <string> ]
+    environment_variables: { <key>: <string> }  # Qoder only
     resources: [ SessionResource ]
     multiagent: { type: "coordinator", agents: [...] }
     metadata: { <key>: <string> }
@@ -272,6 +273,7 @@ agents:
 | `skills[]` | string \| AgentSkillRef | no | Skill name or `{ type: "official"\|"custom", skill_id, version? }`. |
 | `vault` | string | no | Vault name. |
 | `memory_stores` | string[] | no | Bound memory stores. |
+| `environment_variables` | map<string,string> | no | Qoder runtime variables. Managed Sessions use Qoder's `KEY=VALUE;...` wire format; Forward Templates store the map as defaults and Forward Sessions send it under `config.environment_variables`. |
 | `resources` | SessionResource[] | no | Resources attached to every managed Session created for the Agent. |
 | `multiagent.type` | `"coordinator"` | no | Declare a coordinator agent. |
 | `multiagent.agents` | string[] | yes (with multiagent) | Agents it orchestrates. |

docs/reference/configuration.md

@@ -67,15 +67,16 @@
 		"@changesets/cli": "^2.31.0",
 		"@types/bun": "^1.3.14",
 		"dependency-cruiser": "^17.4.3",
-		"js-yaml": "4.3.0",
+		"js-yaml": "4.3.1",
 		"tsup": "^8.5.1",
 		"typescript": "^6.0.3"
 	},
 	"overrides": {
-		"brace-expansion": "5.0.8",
+		"brace-expansion": "5.0.9",
 		"esbuild": "0.28.1",
 		"fast-equals": "5.3.3",
-		"js-yaml": "4.3.0",
+		"js-yaml": "4.3.1",
+		"nanoid": "3.3.17",
 		"postcss": "8.5.23"
 	},
 	"trustedDependencies": [

package.json

@@ -154,6 +154,7 @@ export async function createSessionForAgent(
 		resources: options.resources,
 		title: options.title,
 		metadata: options.metadata,
+		environmentVariables: options.environmentVariables,
 	});
 	const session = await adapter.createSession(bindings);
 	return { agentName, provider, session };
@@ -178,6 +179,7 @@ export async function startSessionRun(
 		resources: options.resources,
 		title: options.title,
 		metadata: options.metadata,
+		environmentVariables: options.environmentVariables,
 	});
 	const session = await adapter.createSession(bindings);
 	return {

packages/sdk/src/internal/core/session-runtime.ts

@@ -379,6 +379,13 @@ export function collectProviderCapabilities(
 				}
 			}
 			for (const [name, agent] of Object.entries(config.agents ?? {})) {
+				if (agent.environment_variables && (!agent.provider || agent.provider === providerName)) {
+					diagnostics.error(
+						`${providerName}.agent.environment_variables.unsupported`,
+						`agent.${name}: environment_variables is supported only by Qoder; remove it or pin this agent to qoder.`,
+						{ type: "agent", name, provider: providerName },
+					);
+				}
 				if (agent.tunnel && (!agent.provider || agent.provider === providerName)) {
 					diagnostics.error(
 						`${providerName}.agent.tunnel.unsupported`,

packages/sdk/src/internal/core/validate-config.ts

@@ -260,6 +260,7 @@ const agentSchema = z.object({
 	resources: z.array(sessionGithubRepoResourceSchema).optional(),
 	multiagent: multiagentSchema.optional(),
 	metadata: z.record(z.string(), z.string()).optional(),
+	environment_variables: z.record(z.string().min(1), z.string()).optional(),
 	delivery: z.record(z.string(), agentDeliverySchema).optional(),
 });
 

packages/sdk/src/internal/parser/schema.ts

@@ -800,6 +800,9 @@ export class QoderAdapter implements ProviderAdapter {
 			};
 			if (bindings.title) body.title = bindings.title;
 			if (bindings.metadata) body.metadata = bindings.metadata;
+			if (bindings.environment_variables) {
+				body.config = { environment_variables: bindings.environment_variables };
+			}
 			if (bindings.files?.length) {
 				body.resources = bindings.files.map((file) => ({
 					type: "file",

packages/sdk/src/internal/providers/qoder/adapter.ts

@@ -492,6 +492,7 @@ export function mapForwardTemplate(
 	if (refs.tunnel_id) body.tunnel_id = refs.tunnel_id;
 	if (projectName) body.metadata = injectMetadata(decl.metadata, projectName, name);
 	else body.metadata = decl.metadata ?? {};
+	if (decl.environment_variables) body.environment_variables = decl.environment_variables;
 
 	if (decl.tools) {
 		body.tools = [
@@ -663,6 +664,11 @@ export function mapSession(bindings: ManagedSessionBindings): unknown {
 	if (bindings.tunnel_id) body.tunnel_id = bindings.tunnel_id;
 	if (bindings.title) body.title = bindings.title;
 	if (bindings.metadata) body.metadata = bindings.metadata;
+	if (bindings.environment_variables) {
+		body.environment_variables = Object.entries(bindings.environment_variables)
+			.map(([key, value]) => `${key}=${value}`)
+			.join(";");
+	}
 	if (bindings.vault_ids.length) body.vault_ids = bindings.vault_ids;
 	// Memory stores and user-uploaded files share the `resources` array (vaults are separate
 	// via `vault_ids`). Every entry needs a non-empty `type`; file shape mirrors qoder's

packages/sdk/src/internal/providers/qoder/mapper.ts

@@ -37,6 +37,8 @@ export interface SessionCreateOptions {
 	title?: string;
 	provider?: string;
 	metadata?: Record<string, string>;
+	/** Session-level environment variables. Currently supported by Qoder. */
+	environmentVariables?: Record<string, string>;
 }
 
 export function resolveSessionProvider(agentName: string, config: ProjectConfig, overrideProvider?: string): string {
@@ -71,6 +73,10 @@ export function buildSessionBindings(
 		throw new UserError(`Agent '${agentName}' not found in config. Available agents: ${available || "(none)"}`);
 	}
 	const sessionResources = options.resources ?? agent.resources;
+	const environmentVariables = options.environmentVariables ?? agent.environment_variables;
+	if (environmentVariables && provider !== "qoder") {
+		throw new UserError("Session environment variables are supported only by Qoder.");
+	}
 	const providerFeatures = getProvider(provider)?.features;
 	for (const resource of sessionResources ?? []) {
 		if (!providerFeatures?.session_resources.includes(resource.type)) {
@@ -102,6 +108,7 @@ export function buildSessionBindings(
 			files: (options.files ?? []).map((file) => ({ file_id: file.fileId, mount_path: file.mountPath })),
 			title: options.title,
 			metadata: options.metadata,
+			environment_variables: environmentVariables,
 		};
 	}
 
@@ -157,6 +164,7 @@ export function buildSessionBindings(
 		resources: sessionResources,
 		title: options.title,
 		metadata: options.metadata,
+		environment_variables: environmentVariables,
 	};
 }