qwen-code/packages/managed-agent-server/AGENTS.md

Managed Agent Server

These instructions apply to this directory and its descendants. They supplement the repository AGENTS.md; its simplicity, design, self-audit, and PR requirements still apply. When changing another module, also read the instructions that apply there.

Scope and References

This is the standalone Spring Boot control plane for the Hosted Harness. Keep DataWorks and other product-specific integrations outside this module. Preserve the ownership boundary between control-plane lifecycle state, Runtime Broker execution bindings, and Hosted Harness execution.

Use the README for setup, authentication, deployment, and test profiles. Keep detailed procedures there rather than duplicating them here.

Library Reuse

• Prefer JDK APIs and the declared Apache Commons libraries over new generic helpers. Use org.apache.commons.lang3.StringUtils for null-safe blank checks and truncation; do not introduce another string utility class or wrappers that only repeat those operations.
• Use Commons Codec DigestUtils for raw SHA-256 operations and getSha256Digest() for incremental digest initialization. Keep streaming limits, heartbeat checks, and length-prefixed inputs intact. Use HmacUtils for HMAC with a fresh instance per call; preserve signature input bytes, output encoding, constant-time comparisons, and exception mappings.
• Use StringUtils.isNumeric when the existing validation accepts Unicode digits. Keep ASCII-only protocol checks explicit.
• Preserve UTF-8 encoding, digest prefixes, and the existing JSON canonicalization rules.
• Preserve domain-specific semantics: title unicodeBlank also recognizes NBSP and BOM, so it is not interchangeable with StringUtils.isBlank.
• Reuse fully configured ObjectMapper instances and inject existing Spring components rather than constructing them for each call. Keep protocol JSON configuration fixed; application-wide mapper settings must not change stored bytes or digests.
• Declare directly used libraries in this module's POM. Let Spring Boot manage their versions rather than relying on sibling or storage SDK dependencies.

Build and Verification

The repository's General workflow delegates Java-only verification to this file. The policy below governs this module's local verification, including invoked skills, subagents, automations and PR follow-ups. Reference this section instead of copying its rules into prompts or monitoring skills such as babysit-pr. Changes in other packages still follow their applicable root and module rules, including the root build/typecheck requirement for cross-language changes.

Local validation scope and budget

1. Select by changed behavior. Cover the current increment and affected callers, contracts and consumers. A new commit SHA, rebase or review round alone does not require repeating tests; inspect what actually changed.
2. Reuse valid evidence. Do not repeat a successful check while its tested source, tests, dependencies, toolchain, generated inputs and runtime configuration remain applicable. Record the command, tested state and outcome. When an input changes, rerun only checks whose evidence it invalidates. Preserve failed attempts; an isolated pass does not clear an unexplained wider failure.
3. Preflight the environment. Check required toolchain versions, build prerequisites and service configuration before expensive tests. Fix an environment mismatch before retrying the affected check; a full suite is not an environment diagnostic.
4. Share one local budget. Unless the user explicitly sets another budget, spend at most 10 minutes on this module's local verification per requested change, including prerequisite setup, builds, tests and retries. Subagents and review rounds share that budget; a new SHA or continuation message does not reset it. Give commands a timeout bounded by the remaining budget. At exhaustion, stop local checks, clean up task-owned resources and record incomplete checks for CI. Do not silently extend the budget or keep adding checks. This budget does not waive checks required for other changed packages.
5. Keep full gates in CI. Local validation prioritizes focused regression and the minimum real integration path. CI owns this module's required full suites and profiles; do not weaken their selectors or coverage guards. Report local passes, failures, skips and CI gaps separately. Until the required CI gates pass on the revision being accepted, say acceptance is pending; if CI does not cover a required check, keep that gap explicit.
6. Expand only with evidence. Name a concrete failure, changed shared contract or specific unresolved risk and the additional check that would resolve it. "More confidence" alone is insufficient. Expansion remains within the local budget; otherwise hand it to CI. Self-audit checks the validity of evidence without automatically rerunning it.

Maven and MySQL checks

Use JDK 21 and Maven 3.8.9 or newer; run Maven from this directory.

Before testing, check the toolchain and that the installed sibling SDK matches the source being tested. Reuse a valid build; otherwise install it once into the task's isolated Maven repository to avoid another checkout's same-version artifact. Use the same task-specific -Dmaven.repo.local setting for installation and subsequent Maven commands (it may be supplied through MAVEN_ARGS):

mvn -f ../sdk-java/qwencode/pom.xml -DskipTests -Dgpg.skip=true install

Native CSI conformance tests also load built Core and CLI JavaScript. When selecting those tests, check packages/core/dist and packages/cli/dist and build missing or stale prerequisites under the root dependency instructions. Maven does not build them. Setup and build time count toward the local budget.

For local Java changes, select the affected classes and their consumers:

mvn -Dtest=ChangedClassTest test checkstyle:check

Replace ChangedClassTest with the affected test classes. Do not follow a successful focused run with unconditional local mvn verify. CI runs the full unit/H2 suite, Checkstyle and SpotBugs through mvn verify; broader local checks need the concrete evidence and remaining budget required by this module's policy. Java formatting and style follow the existing Checkstyle rules. Justify any new SpotBugs exclusion in the PR; do not disable a gate to make verification pass.

SQL, transaction, concurrency, or recovery changes require real MySQL evidence: locally select the affected mysql-integration cases against a disposable MySQL 8.4 database within budget, and leave the complete profile to CI. Hosted execution or failure recovery changes similarly need the relevant real-process path locally and the matching full Hosted/fault profiles in CI. Profiles are in pom.xml. Focused local reports prove only their selected cases; the complete-source-tree report guard belongs to unfiltered full runs. Use the README and the repository's Java workflow for setup and profile parameters. H2 tests alone do not establish MySQL or process-recovery behavior. If the required real path cannot run locally within budget, record it as pending CI rather than substituting H2 or claiming acceptance.

Before MySQL tests, verify the effective server version, task-owned database URL/credentials and required permissions. Check settings needed by the selected cases: large-object tests require max_allowed_packet >= 134217728; the mysql-integration Linux CI containers disable native AIO with --innodb-use-native-aio=0; the MySQL leg also uses --skip-log-bin. Follow the workflow's actual startup settings and record local platform deviations. Multi-fork runs need a distinct MySQL instance per fork to isolate server-wide deadlock counters. Repair an invalid environment before running tests; report unavailable checks and remaining CI work explicitly.

For shared-contract or TypeScript-consumer changes, also follow the root build/typecheck requirements and run affected consumer tests. The local Maven work follows this module's budget; CI retains the full cross-language gates. Documentation-only changes need formatting and reference checks and do not invalidate unchanged Java test results.

Maven report output under target/ (javadoc reports/apidocs, JaCoCo site/jacoco) contains generated JavaScript that the repository-root ESLint sweep does not ignore, so a root npm run lint fails while those directories exist. Run mvn clean or delete the target/ directories before running root checks in the same checkout.

Code Review

• Preserve each changed route's tenant isolation, actor checks, Workspace grants, and internal credentials. A tenant header alone must not authorize protected Workspace or artifact access; preserve the documented loopback and signed-authentication boundaries.
• Keep admitted operations and recovery decisions durable in SQL. Verify retry idempotency and writer lease/generation checks across restarts: a stale owner must not commit durable state or release a newer owner's resources.
• Server and Broker use the shared schema baseline. Keep initialization and validation consistent across Server and Broker. Preserve refusal of legacy, partial, and foreign catalogs; do not revive archived migrations or use Flyway repair/history edits to bypass that refusal. Follow the README's current schema policy rather than assuming an upgrade path.
• Public and WebShell API changes must keep the OpenAPI contract, mapped routes, SurfaceRegistry, and contract tests consistent. Run ManagedAgentApiContractTest and SurfaceRegistryGateTest for those changes. Regenerate WebShell types from the repository root with npm run generate:managed-agent-api --workspace=packages/web-shell and verify affected consumers; update the contract rather than hand-editing generated types.