feat: add the agents and service-accounts command groups

[cristianrcv]

Summary

Adds the tw agents and tw service-accounts command groups, grouped in one PR because agents run under service accounts. Both build on master alone (SDK 1.233.0).

• Service accounts (API 1.230): list (org or workspace), add, view, update, delete. OrgRole.service_account now shows in members.
• Agents, which span three API versions:
  • 1.190: CRUD, enable and disable (agentInstructions);
  • 1.200: agents launch (LaunchAgentResponse.agentRunId) and agents runs list|view;
  • 1.230: --service-account-id and --github-app-credentials-id, and showing them.

Changes

• fix(build): allow PATCH requests on Java 25 (1eaca63)
• fix(build): open the JDK packages for PATCH in the native image too (a1d9606)
• feat(service-accounts): add service account commands (d1d6f3f)
• feat(agents): add agents command (f1bb1ca)
• feat(agents): add agents launch (fe392a2)
• feat(agents): add agents runs list and view (cfc4151)
• feat(agents): set an agent's service account and GitHub App credentials (9ac9cef)
• docs: document the agents and service accounts commands (65b0765)
• build(native): register reflection metadata for the agents and service accounts commands (8e8d05e)

Notes for review

• Why build.gradle changes here: tw service-accounts update is the first PATCH call tw makes. Jersey's SET_METHOD_WORKAROUND reflects into HttpURLConnection.method and HttpsURLConnectionImpl.delegate, and Java 25 blocks that. The JVM reported a bogus "Connection error", and the native binary silently sent POST. Both packages are opened:

  • for the test and run JVMs;
  • in the tw.jar manifest (Add-Opens);
  • as native-image --add-opens.

  The two fields are also registered in reflect-config.json.

• Agents scoping: every agents command needs -w. Agents are enabled per organization; when they're off, the API returns 404 "Agents are not enabled for this organization".

• agents update: the PUT replaces the whole agent, so tw fetches it first and resends every field you don't change.

• agents launch: with an agent, it sends the agent's stored instructions, as the web UI does. Instructions you pass override them. Without an agent, it's an ad-hoc run as the current user.

Verification

• ./gradlew test: 772 tests, 0 failures, including the service-account PATCH tests (which need the opens).
• From earlier runs of the same code (feat: catch tw up with Platform API 1.230.0 and stop duplicate runs from launch --wait [COMP-2645] #684): PATCH over HTTPS was checked against a local TLS server with the native binary and java -jar tw.jar; the server received PATCH.
• CI runs the full suite against the native binary on Linux, macOS and Windows.

🤖 Generated with Claude Code

[educalleja]

Usage of the new commands

This PR adds the tw agents command group: "Manage AI agents." Agents must be enabled for the workspace's organization. When they're not, the API returns 404 "Agents are not enabled for this organization". Every subcommand requires -w, --workspace.

Commands that act on an existing agent identify it by -i, --id or -n, --name. For view, update, delete, enable and disable, exactly one is required. An unknown name fails with "Unknown agent '<name>' at <workspace> workspace".

Manage agents

tw agents list

Lists agents.

Option	Description
-f, --filter	Filter agents by name
Pagination options	Standard --page / --offset / --max

• The output is a table with ID, Name, Description, Status and Updated.

tw agents view

Shows an agent: ID, Name, Description, Status, Service account, GitHub App credentials, Created by, Created and Updated, followed by its full instructions.

tw agents add

Adds an agent.

Option	Description
-n, --name	Agent name (required). Must be unique per workspace. Names can use letters, numbers, hyphens and underscores
-d, --description	Agent description (max 120 characters)
--instructions	Agent instructions: the role, behavior, and constraints for the agent
--instructions-file	File containing the agent instructions. - reads from stdin
--service-account-id	Service account user ID. The agent runs with this service account's permissions in the workspace
--github-app-credentials-id	GitHub App credentials ID. Lets the agent clone, commit and push using these credentials

• You must give exactly one of --instructions or --instructions-file.

tw agents update

Updates an agent. Fields you don't pass keep their current value.

Option	Description
--new-name	New agent name
-d, --description	New description (max 120 characters)
--instructions / --instructions-file	New instructions, inline or from a file (- reads from stdin). Use one or the other
--service-account-id	New service account
--github-app-credentials-id	New GitHub App credentials

• Because unchanged fields keep their current value, there's no way to remove a service account or GitHub App credentials from an agent. Passing nothing keeps the old value.

tw agents delete

Deletes an agent.

tw agents enable / tw agents disable

Enables an inactive agent, or disables an active one. A disabled agent can't be launched.

Run agents

tw agents launch

Starts a background agent run.

Option	Description
-i, --id / -n, --name	The configured agent to run. Optional; use one or the other
--instructions / --instructions-file	Instructions for this run. Optional; use one or the other

• With an agent: the run uses the agent's stored instructions. Instructions you pass replace them for this run.
• Without an agent: it's an ad-hoc run as the current user, and instructions are required.
• If you give neither, it fails with "Specify an agent to launch (--id or --name) or the instructions to run (--instructions or --instructions-file)".
• The output is "Agent run '<id>' submitted at <workspace> workspace (status: <status>)".

tw agents runs list

Lists agent runs, newest first.

Option	Description
-f, --filter	Filter by keyword: status (pending, running, completed, failed), agentConfigId, workflowId, sourcePipelineId, serviceAccountId and serviceAccountName. Free text isn't supported. Example: -f status:failed
Pagination options	Standard --page / --offset / --max

• The output is a table with ID, Title, Status, Trigger, Run ID and Created.

tw agents runs view

Shows the status of one agent run.

Option	Description
-i, --id	Agent run ID (required)

• The output shows ID, Status, Thread ID and Session ID.

Examples (from USAGE.md)

tw agents add -w my-org/my-workspace -n triage --instructions-file triage.md
tw agents launch -w my-org/my-workspace -n triage
tw agents runs list -w my-org/my-workspace

USAGE.md

A new "Agents" section lists all the operations (list, view, add, update, delete, enable, disable, launch, runs list|view) with the examples above.

🤖 Generated with Claude Code