Feat/managed agent api commands

.changeset/calm-otters-list.md

@@ -0,0 +1,5 @@
+---
+"@openagentpack/sdk": minor
+---
+
+Expose Bailian Managed Agents operation-level reads, cursor pagination, session events, file downloads, deployment actions, provider capability metadata, generic scoped create-only planning/apply, local Skill source inspection, scoped Vault Credential creation, and display names independent from logical YAML keys.

apps/server/openapi.json

@@ -1520,6 +1520,12 @@
 													"archived_at": {
 														"type": "string",
 														"nullable": true
+													},
+													"attributes": {
+														"type": "object",
+														"additionalProperties": {
+															"nullable": true
+														}
 													}
 												},
 												"required": ["id"]
@@ -1793,6 +1799,12 @@
 													"archived_at": {
 														"type": "string",
 														"nullable": true
+													},
+													"attributes": {
+														"type": "object",
+														"additionalProperties": {
+															"nullable": true
+														}
 													}
 												},
 												"required": ["id"]
@@ -2062,6 +2074,12 @@
 													"archived_at": {
 														"type": "string",
 														"nullable": true
+													},
+													"attributes": {
+														"type": "object",
+														"additionalProperties": {
+															"nullable": true
+														}
 													}
 												},
 												"required": ["id"]

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

@@ -870,6 +870,9 @@ export interface paths {
 								created_at?: string;
 								updated_at?: string;
 								archived_at?: string | null;
+								attributes?: {
+									[key: string]: unknown;
+								};
 							}[];
 						};
 					};
@@ -1116,6 +1119,9 @@ export interface paths {
 								created_at?: string;
 								updated_at?: string;
 								archived_at?: string | null;
+								attributes?: {
+									[key: string]: unknown;
+								};
 							}[];
 						};
 					};
@@ -1346,6 +1352,9 @@ export interface paths {
 								created_at?: string | null;
 								updated_at?: string | null;
 								archived_at?: string | null;
+								attributes?: {
+									[key: string]: unknown;
+								};
 							}[];
 						};
 					};

docs/contributing/release.md

@@ -35,12 +35,14 @@ Choose the SemVer impact and describe the change for the generated changelog. On
 ## Publish a beta
 
 1. In GitHub, open **Actions → Publish npm → Run workflow**.
-2. Keep the workflow branch set to `main`, choose `beta`, type `PUBLISH`, and run it.
+2. Select the exact branch to publish, choose `beta`, type `PUBLISH`, and run it.
 3. Approve the `npm-release` Environment deployment after reviewing the commit, generated version, and job summary.
 
-The workflow derives an immutable version from the GitHub Actions run ID and current `main` commit without changing Git history, for example `0.0.0-beta.run-123456789.sha-a1b2c3d`. It publishes with the npm `beta` dist-tag and creates the matching immutable Git tag. It then installs that exact version from the public npm registry on Linux, Windows, and macOS under Node.js 22 and 24. The GitHub prerelease is created only after all six consumer jobs pass.
+The workflow derives an immutable version from the selected commit without changing Git history, for example `0.4.0-beta-a1b2c3d-20260827`, and creates the matching immutable Git tag. A beta from `main` publishes to npm's shared `beta` dist-tag. A beta from another branch publishes to a branch-scoped tag such as `beta-feat-managed-agent-api-commands`, so it cannot replace the shared `beta` channel. The job summary prints the exact tag. It then installs that exact version from the public npm registry on Linux, Windows, and macOS under Node.js 22 and 24. The GitHub prerelease is created only after all six consumer jobs pass.
 
-For another beta, merge fixes into `main` and run **Publish npm** again. Every run gets a new Actions-run-and-commit-derived version; no beta branch is created and changesets are not consumed.
+For another beta, run **Publish npm** from the updated branch. Every new commit gets a new immutable snapshot version; changesets are not consumed. If the `npm-release` Environment has deployment-branch restrictions, its allowed branch patterns must include the selected beta branch while required reviewers remain enabled.
+
+Install a branch beta with its printed dist-tag, for example `npm install @openagentpack/sdk@beta-feat-managed-agent-api-commands`. Pinning the exact generated version is the most reproducible option.
 
 ## Publish a stable release
 
@@ -91,7 +93,7 @@ npm install --global @openagentpack/cli
 npm install --global @openagentpack/cli@beta
 
 # Pin or test an exact version without a global install
-npx @openagentpack/cli@0.0.0-beta.run-123456789.sha-a1b2c3d --version
+npx @openagentpack/cli@0.4.0-beta-a1b2c3d-20260827 --version
 
 # SDK
 npm install @openagentpack/sdk
@@ -106,4 +108,4 @@ After installing the CLI, run `agents --help`. A beta user returns to stable wit
 - If all packages published but a post-release consumer job fails, keep the immutable tag, do not unpublish or move the tag, and do not create the GitHub Release. Fix the compatibility issue and publish a new patch version; npm package versions cannot be overwritten.
 - Registry visibility is retried for five minutes before it is classified as a release failure. Retry the same workflow only when npm propagation, rather than package compatibility, was the cause.
 - If a version tag already points at another commit, stop. Tags are immutable; investigate the repository history instead of moving or deleting the tag.
-- Beta publishing must be manually dispatched from `main`; the release identity check rejects other branches.
+- Beta publishing may be manually dispatched from any branch; non-`main` branches receive an isolated npm dist-tag. Stable publishing and npm's `latest` tag remain restricted to `main`.

docs/contributing/release.zh-CN.md

@@ -35,12 +35,14 @@ bun run changeset
 ## 发布 Beta
 
 1. 打开 GitHub 的 **Actions → Publish npm → Run workflow**。
-2. workflow branch 保持 `main`，channel 选择 `beta`，输入 `PUBLISH`，然后运行。
+2. 选择要发布的准确分支，channel 选择 `beta`，输入 `PUBLISH`，然后运行。
 3. 检查提交、自动生成的精确版本和 job 信息后，批准 `npm-release` Environment deployment。
 
-工作流根据 GitHub Actions run ID 和 `main` 当前提交生成不修改 Git 历史的版本，例如 `0.0.0-beta.run-123456789.sha-a1b2c3d`。通过后使用 npm 的 `beta` dist-tag 发布，并创建对应的不可变 Git tag。随后，它会在 Linux、Windows、macOS 的 Node.js 22 和 24 环境中，从公共 npm registry 安装该精确版本。只有六个消费者 job 全部通过，才创建 GitHub prerelease。
+工作流根据所选提交生成不修改 Git 历史的不可变版本，例如 `0.4.0-beta-a1b2c3d-20260827`，并创建对应的不可变 Git tag。从 `main` 发布时仍使用 npm 的共享 `beta` dist-tag；从其他分支发布时使用分支独立标签，例如 `beta-feat-managed-agent-api-commands`，因此不会覆盖共享 `beta` 渠道。job 信息会输出准确标签。随后，它会在 Linux、Windows、macOS 的 Node.js 22 和 24 环境中，从公共 npm registry 安装该精确版本。只有六个消费者 job 全部通过，才创建 GitHub prerelease。
 
-需要下一个 Beta 时，把修复合并到 `main` 后再次运行 **Publish npm**。每次运行都会根据 Actions run ID 和提交生成新的不可变版本，不需要 Beta 分支，也不会消费 changeset。
+需要下一个 Beta 时，从更新后的分支再次运行 **Publish npm**。每个新提交都会生成新的不可变快照版本，并且不会消费 changeset。如果 `npm-release` Environment 配置了 deployment branch 限制，需要在保留 Required reviewers 的同时，把目标 Beta 分支模式加入允许范围。
+
+可以使用 job 输出的分支标签安装，例如 `npm install @openagentpack/sdk@beta-feat-managed-agent-api-commands`；固定自动生成的精确版本最可复现。
 
 ## 发布稳定版
 
@@ -91,7 +93,7 @@ npm install --global @openagentpack/cli
 npm install --global @openagentpack/cli@beta
 
 # 固定或临时体验某个精确 Beta 版本
-npx @openagentpack/cli@0.0.0-beta.run-123456789.sha-a1b2c3d --version
+npx @openagentpack/cli@0.4.0-beta-a1b2c3d-20260827 --version
 
 # SDK
 npm install @openagentpack/sdk
@@ -106,4 +108,4 @@ npm install @openagentpack/sdk
 - 所有包都已发布，但发布后消费者 job 失败：保留不可变 tag，不执行 unpublish、不移动 tag，也不创建 GitHub Release。修复兼容性问题后发布新的 patch 版本；npm 上的版本不能被覆盖。
 - registry 可见性会重试五分钟，之后才判定 release 失败。只有确认失败原因是 npm 同步延迟而不是包兼容性时，才从同一个提交重试。
 - 版本 tag 已指向其他提交：立即停止。tag 必须保持不可变，应排查历史，不能移动或删除 tag。
-- Beta 发布必须从 `main` 手动触发；其他分支会被发布身份检查拒绝。
+- Beta 可以从任意分支手动触发；非 `main` 分支会获得隔离的 npm dist-tag。稳定版和 npm `latest` 标签仍只能从 `main` 发布。

packages/sdk/docs/public-api-layers.md

@@ -18,10 +18,17 @@ The public entry exposes domain workflows that return structured domain results.
 New CLI and WebUI behavior should start here.
 
 - Project/resource workflows: config resolution, planning, apply, and destroy.
-- Agent workflows: agent listing, readiness, resource planning, and sync.
-- Session workflows: creation, runs, follow-up messages, event listing, and
-  summaries.
-- Deployment workflows: listing, details, and runs.
+- Agent workflows: agent listing/detail/version reads, readiness, resource
+  planning, and sync.
+- Managed-resource reads: environment, skill/version/download, vault, and file
+  metadata/content APIs with opaque cursor preservation.
+- Session workflows: creation, list/get/update/archive/delete, runs, follow-up
+  messages, raw event send/list/stream, and summaries. Managed Agents child
+  threads remain event metadata (`session_thread_id`); there is no independent
+  public Thread resource API.
+- Deployment workflows: list/get/search, run history, run, pause, and unpause.
+- Operation capabilities: provider-scoped support/auth/reason metadata for
+  API-oriented command hosts.
 - State workflows: a file/in-memory `StateManager` plus state-address parsing.
 - Validation/model workflows: config validation and provider/model discovery.
 

packages/sdk/src/index.ts

@@ -23,7 +23,15 @@ export {
 	writeProjectRuntime,
 } from "./internal/core/project-runtime.ts";
 
-export type { ResolvedProjectConfig } from "./internal/types/config.ts";
+export type {
+	CredentialDecl,
+	DeploymentDecl,
+	EnvironmentDecl,
+	ProjectConfig,
+	ResolvedProjectConfig,
+	SkillDecl,
+	VaultDecl,
+} from "./internal/types/config.ts";
 export type { LoadedProjectConfig } from "./internal/parser/index.ts";
 export {
 	resolveProjectConfig,
@@ -34,6 +42,7 @@ export {
 	decideDestructive,
 	executePlannedProject,
 	importResource,
+	planProjectWithStateBackend,
 	planProjectContext,
 	syncProjectResourcesWithStateBackend,
 } from "./internal/core/resource-runtime.ts";
@@ -42,8 +51,10 @@ export type {
 	ResourceActionResult,
 	ResourceExecutionResult,
 	ResourcePlanResult,
+	ResourcePlanScope,
 	ResourceRefreshResult,
 	ResourceRuntimeOptions,
+	ResourceSyncMode,
 	ResourceSyncRun,
 } from "./internal/core/resource-runtime.ts";
 
@@ -79,7 +90,81 @@ export {
 	runDeploymentForContext,
 } from "./internal/core/deployment-runtime.ts";
 
-export type { DeploymentListFilter, DeploymentListResult } from "./internal/providers/interface.ts";
+export type {
+	DeploymentInfo,
+	DeploymentListFilter,
+	DeploymentListResult,
+	DeploymentRunResult,
+} from "./internal/providers/interface.ts";
+
+export {
+	archiveRemoteSession,
+	downloadRemoteFile,
+	downloadRemoteSkill,
+	getManagedAgentProviderCapabilities,
+	getRemoteAgent,
+	getRemoteDeployment,
+	getRemoteDeploymentRun,
+	getRemoteEnvironment,
+	getRemoteSkill,
+	getRemoteSkillDownloadInfo,
+	getRemoteSkillVersion,
+	getRemoteVault,
+	listRemoteAgents,
+	listRemoteAgentVersions,
+	listRemoteDeploymentRuns,
+	listRemoteDeployments,
+	listRemoteEnvironments,
+	listRemoteFiles,
+	listRemoteSkills,
+	listRemoteSkillVersions,
+	listRemoteVaults,
+	runRemoteDeployment,
+	sendRemoteSessionEvents,
+	setRemoteDeploymentPaused,
+	updateRemoteSession,
+} from "./internal/core/managed-api-runtime.ts";
+export type { ManagedApiTarget } from "./internal/core/managed-api-runtime.ts";
+export type {
+	AgentListOptions,
+	AgentPage,
+	AgentVersionListOptions,
+	CursorListOptions,
+	CursorPage,
+	DeploymentRunInfo,
+	DeploymentRunPage,
+	EnvironmentListOptions,
+	EnvironmentPage,
+	FileListOptions,
+	FilePage,
+	ManagedAgentOperationAuth,
+	ManagedAgentOperationCapability,
+	ManagedAgentProviderCapabilities,
+	SessionEventInput,
+	SessionEventSendResult,
+	SessionUpdateInput,
+	SkillDownloadInfo,
+	SkillListOptions,
+	SkillPage,
+	SkillVersionInfo,
+	SkillVersionListOptions,
+	SkillVersionPage,
+	VaultListOptions,
+	VaultPage,
+	VaultCredentialInfo,
+} from "./internal/types/managed-api.ts";
+
+export {
+	createVaultCredential,
+	createVaultCredentialWithStateBackend,
+	planVaultCredentialCreate,
+	planVaultCredentialCreateWithStateBackend,
+} from "./internal/core/vault-credential-runtime.ts";
+export type {
+	VaultCredentialCreateOptions,
+	VaultCredentialCreatePlan,
+	VaultCredentialCreateResult,
+} from "./internal/core/vault-credential-runtime.ts";
 
 export type {
 	DestroyDefaultMemoryStoreResult,
@@ -148,8 +233,16 @@ export {
 	listCloudAgents,
 	listCloudEnvironments,
 	listCloudVaults,
+	planAgentResources,
+	planAgentResourcesWithStateBackend,
 	syncAgentResourcesWithStateBackend,
 } from "./internal/core/agent-runtime.ts";
+export type {
+	AgentResourcePlan,
+	AgentResourcePlanOptions,
+	AgentResourceSyncMode,
+	AgentResourceSyncOptions,
+} from "./internal/core/agent-runtime.ts";
 
 export type { CollectedSessionEvents } from "./internal/core/session-runtime.ts";
 export {
@@ -198,8 +291,13 @@ export {
 	type ProviderConfig,
 	type ProviderConfigProvider,
 } from "./internal/provider-config.ts";
-export type { ProviderSessionInfo } from "./internal/types/session.ts";
-export type { ProviderSessionEvent } from "./internal/types/session-event.ts";
+export type { ProviderSessionInfo, SessionFilter, SessionListResult } from "./internal/types/session.ts";
+export type {
+	EventListOptions,
+	EventStreamOptions,
+	ProviderSessionEvent,
+	ProviderSessionEventList,
+} from "./internal/types/session-event.ts";
 export type { ProviderFileInfo } from "./internal/types/file.ts";
 export type { ProviderSkillInfo } from "./internal/types/skill-info.ts";
 
@@ -212,6 +310,8 @@ export { LocalFileStateBackend } from "./internal/state/local-file-state-backend
 export type { StateScope } from "./internal/state/backend.ts";
 
 export { extractSkillZipFiles } from "./internal/utils/normalize-skill-zip.ts";
+export { inspectSkillSource } from "./internal/core/skill-source.ts";
+export type { SkillSourceInspection } from "./internal/core/skill-source.ts";
 
 export type {
 	RuntimeFeedbackEvent,

packages/sdk/src/internal/core/agent-builder.ts

@@ -20,6 +20,7 @@ export interface AgentMcpBuildInput {
 }
 
 export interface AgentBuildInput {
+	name?: string;
 	description?: string;
 	model?: AgentDecl["model"];
 	instructions?: string;
@@ -79,6 +80,7 @@ export function buildAgentDecl(base: AgentDecl | undefined, input: AgentBuildInp
 
 	const agent: AgentDecl = {
 		...(base ?? {}),
+		name: input.name ?? base?.name,
 		description: input.description ?? base?.description,
 		model,
 		instructions: input.instructions ?? base?.instructions ?? "",