Merge branch 'main' into dependabot/github_actions/github/codeql-action/upload-sarif-4.37.4

Author: heimanba

apps/server/openapi.json

@@ -1300,6 +1300,33 @@
 																			},
 																			"required": ["type", "name", "provider"]
 																		},
+																		"previousAddress": {
+																			"type": "object",
+																			"properties": {
+																				"type": {
+																					"type": "string",
+																					"enum": [
+																						"environment",
+																						"vault",
+																						"memory_store",
+																						"skill",
+																						"agent",
+																						"template",
+																						"deployment",
+																						"file",
+																						"identity",
+																						"channel"
+																					]
+																				},
+																				"name": {
+																					"type": "string"
+																				},
+																				"provider": {
+																					"type": "string"
+																				}
+																			},
+																			"required": ["type", "name", "provider"]
+																		},
 																		"reason": {
 																			"type": "string"
 																		},

apps/webui/src/lib/api/generated/schema.d.ts

@@ -731,6 +731,22 @@ export interface paths {
 											name: string;
 											provider: string;
 										};
+										previousAddress?: {
+											/** @enum {string} */
+											type:
+												| "environment"
+												| "vault"
+												| "memory_store"
+												| "skill"
+												| "agent"
+												| "template"
+												| "deployment"
+												| "file"
+												| "identity"
+												| "channel";
+											name: string;
+											provider: string;
+										};
 										reason: string;
 										/** @enum {string} */
 										driftKind?: "none" | "local" | "remote" | "both";

bun.lock

@@ -59,10 +59,16 @@ environments:
       packages:
         apt: [git, curl]
         npm: [typescript]
+      setup_script: |
+        set -euo pipefail
+        install -d /data/workspace/.openagentpack
+        test -f /data/workspace/.openagentpack/ready || date -u > /data/workspace/.openagentpack/ready
 ```
 
 Reference an environment from an agent with `environment: dev`.
 
+Qoder supports `config.setup_script` for both cloud and self-hosted environments. It runs the script with `/bin/bash -lc` after declared packages are installed. The UTF-8 limit is 64 KB and the timeout is 10 minutes; a non-zero exit prevents the Session from starting. The script runs once per sandbox and runs again when that sandbox is rebuilt, so make it idempotent. Do not embed credentials—use vaults or environment-backed secret references. Other providers currently reject `setup_script` rather than silently ignoring it.
+
 ## Instructions
 
 `instructions` accepts either an inline string or a path to a file:

docs/guides/configure-an-agent.md

@@ -95,6 +95,10 @@ environments:
       packages:
         apt: [git, curl]
         npm: [typescript]
+      setup_script: |
+        set -euo pipefail
+        install -d /data/workspace/.openagentpack
+        test -f /data/workspace/.openagentpack/ready || date -u > /data/workspace/.openagentpack/ready
     metadata:
       team: platform
 ```
@@ -122,6 +126,14 @@ packages:
   go: [golang.org/x/tools/gopls@latest]
 ```
 
+Qoder 请求目前只支持 `apt`、`npm` 和 `pip`。`cargo`、`gem`、`go` 是 Qoder 响应中的保留字段，不能在投向 Qoder 的配置中声明非空值；如有需要，可通过 `setup_script` 安装。
+
+### 启动脚本（Qoder）
+
+Qoder 的 cloud 与 self-hosted Environment 都支持 `config.setup_script`。依赖包安装完成后，脚本会通过 `/bin/bash -lc` 执行；UTF-8 最大 64 KB，超时 10 分钟，非零退出会导致 Session 启动失败。脚本在同一 sandbox 中只执行一次，sandbox 重建后会再次执行，因此必须保持幂等。不要把令牌或密码写入脚本，应使用 Vault 或环境变量引用。其他 Provider 当前会明确拒绝 `setup_script`，不会静默忽略。
+
+受管理的 Qoder `self_hosted` Environment，其 `config` 只能包含 `type` 和可选的 `setup_script`；网络与预装包配置仅适用于 cloud Environment。带 `environment_id` 的外部引用仍不由 OpenAgentPack 修改。
+
 ---
 
 ## 挂载技能包

docs/guides/configure-an-agent.zh-CN.md

@@ -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.
@@ -61,6 +78,12 @@ environments:
       type: cloud
       networking:
         type: unrestricted
+      packages:
+        npm: ["pnpm@9"]
+      setup_script: |
+        set -euo pipefail
+        install -d /data/workspace/.openagentpack
+        test -f /data/workspace/.openagentpack/ready || printf 'ready\n' > /data/workspace/.openagentpack/ready
 
 agents:
   assistant:
@@ -73,6 +96,8 @@ agents:
       builtin: [read, glob, grep, web_search, web_fetch]
 ```
 
+Qoder runs `setup_script` after package installation with `/bin/bash -lc`. Scripts are limited to 64 KB of UTF-8 text and 10 minutes, and a non-zero exit prevents Session startup. Make them idempotent because they run again whenever the sandbox is rebuilt. Use vaults for credentials; never place secrets directly in a script. Qoder package declarations accept `apt`, `npm`, and `pip` only.
+
 ## What Qoder uniquely supports
 
 - **Memory stores** — persistent context for an agent. See [`examples/qoder/with-memory/`](../../examples/qoder/with-memory/).

docs/guides/deploy-to-qoder.md

@@ -133,6 +133,7 @@ environments:
       type: cloud | self_hosted
       networking: { ... }
       packages: { ... }
+      setup_script: <string>
     metadata: { <key>: <string> }
 ```
 
@@ -145,8 +146,13 @@ environments:
 | `config.networking.allow_package_managers` | boolean | no | Allow package managers. |
 | `config.networking.allowed_hosts` | string[] | no | Allow-list for `limited` networks. |
 | `config.packages.apt` \| `pip` \| `npm` \| `cargo` \| `gem` \| `go` | string[] | no | Preinstalled packages. |
+| `config.setup_script` | string | no | Sandbox setup script. Qoder runs it with `/bin/bash -lc` after package installation; maximum UTF-8 size is 64 KB. Other providers currently reject this field. |
 | `metadata` | map<string,string> | no | Free-form metadata. |
 
+Qoder accepts only `apt`, `npm`, and `pip` in package requests. Its API may return empty `cargo`, `gem`, and `go` arrays as reserved response fields, but declaring non-empty values for them is rejected locally. Setup scripts run while a new sandbox is prepared, time out after 10 minutes, and a non-zero exit prevents the Session from starting. Keep scripts idempotent and use vault-backed credentials instead of embedding secrets.
+
+For a managed Qoder `self_hosted` environment, `config` accepts only `type` and optional `setup_script`; networking and packages belong to cloud environments. External `environment_id` references remain unmanaged.
+
 ## Tunnel (Qoder BYOC)
 
 ```yaml
@@ -246,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> }
@@ -266,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

@@ -32,6 +32,10 @@ environments:
       packages:
         apt: [git, curl]
         pip: [requests]
+      setup_script: |
+        set -euo pipefail
+        install -d /data/workspace/.openagentpack
+        test -f /data/workspace/.openagentpack/ready || printf 'ready\n' > /data/workspace/.openagentpack/ready
     metadata:
       team: platform
 

examples/qoder/full/agents.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-08-12

openspec/changes/qoder-environment-setup-script/.openspec.yaml

@@ -0,0 +1,45 @@
+## Context
+
+Environment declarations flow through the public TypeScript model and Zod parser, provider-aware validation, provider request mapping, and provider-specific reverse/normalization paths used by sync and drift detection. Qoder now exposes `config.setup_script` for both cloud and self-hosted environments, with a 64 KB UTF-8 limit, but every stage currently drops or rejects it. The same API documentation establishes POST update semantics, whole-config replacement, metadata patching, and a narrower writable package set than the shared model.
+
+## Goals / Non-Goals
+
+**Goals:**
+
+- Make setup scripts converge through create, update, sync, export, and drift detection.
+- Fail locally for script-size and Qoder package-manager violations.
+- Normalize response-only Qoder defaults without hiding declarative differences.
+- Correct update and metadata-deletion behavior without changing BYOC ownership rules.
+- Prove the contract with focused automated tests and a disposable live Qoder environment.
+
+**Non-Goals:**
+
+- Execute setup scripts locally or expose their Session-time logs through a new API.
+- Add file-path indirection for script content; the declaration remains an inline YAML string.
+- Claim setup-script support for providers whose current API contract has not been verified.
+- Manage externally referenced environments.
+
+## Decisions
+
+1. Add `setup_script?: string` to the shared environment config, but gate actual use per provider. This keeps the declaration portable while preventing adapters from silently dropping unsupported behavior. A Qoder-only extension object was considered, but would make the common Environment model needlessly provider-shaped.
+2. Enforce the documented maximum with `Buffer.byteLength(value, "utf8")`, not JavaScript string length, because the remote limit is byte-oriented and scripts may contain non-ASCII content.
+3. Keep the shared package union for other providers, while Qoder validation rejects non-empty `cargo`, `gem`, and `go`. Qoder normalization retains only writable `apt`, `npm`, and `pip` values and removes empty response defaults plus `packages.type`.
+4. Include setup scripts in both reverse mapping and comparable normalization. Absence and an empty string remain distinct because clearing a saved script must be representable and reconciled.
+5. Change Qoder environment update to POST and construct metadata tombstones from the current remote object before updating. This matches Qoder's metadata patch semantics while still sending the complete desired config.
+6. Exercise live behavior with a uniquely named disposable environment loaded from `.env`, verify create/get/update/readback, then delete it in a `finally` cleanup path. No secret or `.env` content is printed.
+
+## Risks / Trade-offs
+
+- [Provider documentation changes again] → Keep Qoder-specific validation and normalization isolated and back it with request-contract tests.
+- [A live setup script can cause Session startup failure] → Use a harmless marker script in live testing and document idempotency, failure, and secret-handling guidance.
+- [Metadata tombstones could target management metadata] → Diff only non-`agents.*` remote metadata and continue injecting management metadata normally.
+- [Empty arrays from Qoder cause false drift] → Canonicalize package objects on both desired and remote sides before hashing.
+- [Live cleanup fails] → Print only the disposable resource ID/name and an explicit cleanup command, leaving credentials undisclosed.
+
+## Migration Plan
+
+The field is optional, so existing declarations retain their current hashes after normalization. Deploy the parser, validation, mapper, adapter, tests, and documentation together. Rollback is code-only; environments already containing scripts continue to exist remotely, though an older client would no longer manage that field.
+
+## Open Questions
+
+None. The current Qoder documentation is explicit about accepted fields, execution semantics, and update behavior.