feat(sdk): consolidate project services into SDK (#111)

Move local versions and directory workspace services into SDK subpath exports. Update CLI and Workbench consumers, release configuration, documentation, and package smoke coverage.

Bump SDK, CLI, and Playground to 0.7.0 while retaining private package versions.

Author: chenanran555

.changeset/config.json

@@ -2,15 +2,7 @@
 	"$schema": "https://unpkg.com/@changesets/config@3.1.1/schema.json",
 	"changelog": "@changesets/cli/changelog",
 	"commit": false,
-	"fixed": [
-		[
-			"@openagentpack/sdk",
-			"@openagentpack/project-versions",
-			"@openagentpack/project-workspace",
-			"@openagentpack/playground",
-			"@openagentpack/cli"
-		]
-	],
+	"fixed": [["@openagentpack/sdk", "@openagentpack/playground", "@openagentpack/cli"]],
 	"linked": [],
 	"access": "public",
 	"baseBranch": "main",

.dependency-cruiser.cjs

@@ -20,22 +20,25 @@ module.exports = {
 			severity: "error",
 			comment: "@openagentpack/sdk is the shared engine and must not depend on host packages or applications.",
 			from: { path: "^packages/sdk/" },
-			to: { path: "^(packages/cli|apps/server|apps/webui)/" },
+			to: { path: "^(packages/cli|packages/playground|apps/server|apps/webui)/" },
 		},
 		{
-			name: "no-project-versions-to-hosts-or-apps",
+			name: "no-sdk-core-to-project-services",
 			severity: "error",
 			comment:
-				"@openagentpack/project-versions is a shared Node engine and must not depend on host packages or applications.",
-			from: { path: "^packages/project-versions/" },
-			to: { path: "^(packages/cli|packages/playground|apps/server|apps/webui)/" },
+				"Core SDK modules must not pull Node project services into the default entry or create dependency cycles.",
+			from: {
+				path: "^packages/sdk/src/",
+				pathNot: "^packages/sdk/src/(internal/project-(versions|workspace)/|project-(versions|workspace)\\.ts$)",
+			},
+			to: { path: "^packages/sdk/src/(internal/project-(versions|workspace)/|project-(versions|workspace)\\.ts$)" },
 		},
 		{
-			name: "no-project-workspace-to-hosts-or-apps",
+			name: "no-project-versions-to-workspace",
 			severity: "error",
-			comment: "@openagentpack/project-workspace is a shared Node engine and must not depend on hosts or applications.",
-			from: { path: "^packages/project-workspace/" },
-			to: { path: "^(packages/cli|packages/playground|apps/server|apps/webui)/" },
+			comment: "Snapshot storage must remain independent of the directory workspace adapter.",
+			from: { path: "^packages/sdk/src/(internal/project-versions/|project-versions\\.ts$)" },
+			to: { path: "^packages/sdk/src/(internal/project-workspace/|project-workspace\\.ts$)" },
 		},
 		{
 			name: "no-sdk-deep-imports",
@@ -57,20 +60,6 @@ module.exports = {
 			from: { path: "^apps/webui/src/" },
 			to: { path: "^packages/sdk/" },
 		},
-		{
-			name: "no-webui-project-versions-runtime-import",
-			severity: "error",
-			comment: "Browser-facing code must use Workbench APIs instead of importing the Node-only version engine.",
-			from: { path: "^apps/webui/src/" },
-			to: { path: "^packages/project-versions/" },
-		},
-		{
-			name: "no-webui-project-workspace-runtime-import",
-			severity: "error",
-			comment: "Browser-facing code must use Workbench APIs instead of importing the Node-only workspace engine.",
-			from: { path: "^apps/webui/src/" },
-			to: { path: "^packages/project-workspace/" },
-		},
 	],
 	options: {
 		doNotFollow: {

.github/workflows/ci.yml

@@ -64,7 +64,7 @@ jobs:
           - node: 24
             scope: all
           # Library smoke on the SDK engines floor (>=18.17.0): build and install
-          # sdk, project-versions, and project-workspace; cli/playground require Node >=22.
+          # SDK and its project subpaths; cli/playground require Node >=22.
           - node: 18.17.0
             scope: sdk
           - node: 20
@@ -86,8 +86,6 @@ jobs:
       - if: matrix.scope == 'sdk'
         run: |
           bun run build:sdk
-          bun run build:project-versions
-          bun run build:project-workspace
           bun scripts/release/smoke-packed.ts --sdk-only
 
   gate:

README.md

@@ -179,10 +179,10 @@ The [`examples/`](./examples) directory has runnable configs for every provider,
 
 ## Using the SDK
 
-Cloud runtime capabilities are available from `@openagentpack/sdk`. Directory compilation, Build/Publish, and full-tree versions are exposed by `@openagentpack/project-workspace`, backed by the storage primitives in `@openagentpack/project-versions`:
+Cloud runtime capabilities are available from `@openagentpack/sdk`. The same npm package includes Node-only subpaths: `@openagentpack/sdk/project-workspace` provides directory compilation, Build/Publish, and full-tree versions, backed by the storage primitives in `@openagentpack/sdk/project-versions`:
 
 ```ts
-import { previewProjectBuild, commitProjectBuild } from "@openagentpack/project-workspace";
+import { previewProjectBuild, commitProjectBuild } from "@openagentpack/sdk/project-workspace";
 
 const preview = await previewProjectBuild("./my-agent");
 const build = await commitProjectBuild({

README.zh-CN.md

@@ -175,11 +175,11 @@ Beta 用户可以安装 `@openagentpack/cli@beta`；固定版本及切回稳定
 
 ## 使用 SDK
 
-云端项目运行能力可通过 `@openagentpack/sdk` 以编程方式调用；仅限 Node.js 的本地项目版本能力由独立包 `@openagentpack/project-versions` 提供：
+云端项目运行能力可通过 `@openagentpack/sdk` 以编程方式调用；本地版本和目录项目能力随同一个 SDK 包发布，分别通过仅限 Node.js 的 `@openagentpack/sdk/project-versions`、`@openagentpack/sdk/project-workspace` 子路径调用：
 
 ```ts
 import { resolveProjectConfig, planProjectContext } from "@openagentpack/sdk";
-import { createProjectVersionService } from "@openagentpack/project-versions";
+import { createProjectVersionService } from "@openagentpack/sdk/project-versions";
 
 const config = await resolveProjectConfig({ configPath: "agents.yaml" });
 const plan = await planProjectContext(config);

apps/server/package.json

@@ -16,8 +16,6 @@
 	},
 	"dependencies": {
 		"@hono/zod-openapi": "^1.4.0",
-		"@openagentpack/project-versions": "workspace:*",
-		"@openagentpack/project-workspace": "workspace:*",
 		"@openagentpack/sdk": "workspace:*",
 		"chokidar": "^4.0.3",
 		"hono": "^4.12.28",

apps/server/src/routes/project.ts

@@ -1,11 +1,11 @@
 import { createRoute, OpenAPIHono, z } from "@hono/zod-openapi";
+import { planAgentResourcesWithStateBackend, syncAgentResourcesWithStateBackend } from "@openagentpack/sdk";
 import {
 	acquireDirectoryProjectMutation,
 	commitProjectBuild,
 	previewProjectBuild,
 	readValidProjectBuild,
-} from "@openagentpack/project-workspace";
-import { planAgentResourcesWithStateBackend, syncAgentResourcesWithStateBackend } from "@openagentpack/sdk";
+} from "@openagentpack/sdk/project-workspace";
 import { errorResponses } from "@/schemas/common";
 import {
 	AgentApplyBodySchema,

apps/server/src/services/project-declarations.ts

@@ -1,19 +1,19 @@
 import { randomUUID } from "node:crypto";
 import { mkdir, readFile, rename, stat, unlink, writeFile } from "node:fs/promises";
 import { basename, dirname, relative, resolve } from "node:path";
-import {
-	acquireDirectoryProjectMutation,
-	type DirectoryResourceType,
-	FILE_AUTO_ASSOCIATION_IGNORE_FILE,
-	inspectDirectoryProject,
-	locateDirectoryProjectResource,
-} from "@openagentpack/project-workspace";
 import {
 	type Diagnostic,
 	type ResolvedProjectConfig,
 	resolveProjectConfigFromObject,
 	validateProjectConfig,
 } from "@openagentpack/sdk";
+import {
+	acquireDirectoryProjectMutation,
+	type DirectoryResourceType,
+	FILE_AUTO_ASSOCIATION_IGNORE_FILE,
+	inspectDirectoryProject,
+	locateDirectoryProjectResource,
+} from "@openagentpack/sdk/project-workspace";
 import { parse, stringify } from "yaml";
 import { type ProjectRuntimeManager, projectRuntimeManager } from "@/services/project-manager";
 import { projectMutationCoordinator } from "@/services/project-mutations";

apps/server/src/services/project-manager.ts

@@ -1,14 +1,6 @@
 import { createHash } from "node:crypto";
 import { existsSync } from "node:fs";
 import { basename, resolve } from "node:path";
-import {
-	getProjectBuildStatus,
-	inspectDirectoryProject,
-	PROJECT_BUILD_FILE,
-	PROJECT_METADATA_FILE,
-	PROJECT_STATE_FILE,
-	resolveDirectoryProjectRuntime,
-} from "@openagentpack/project-workspace";
 import {
 	type AgentWithReadiness,
 	type BackendRuntimeInput,
@@ -18,6 +10,14 @@ import {
 	type ResolvedProjectConfig,
 	readProjectRuntime,
 } from "@openagentpack/sdk";
+import {
+	getProjectBuildStatus,
+	inspectDirectoryProject,
+	PROJECT_BUILD_FILE,
+	PROJECT_METADATA_FILE,
+	PROJECT_STATE_FILE,
+	resolveDirectoryProjectRuntime,
+} from "@openagentpack/sdk/project-workspace";
 import { type FSWatcher, watch } from "chokidar";
 import { type ProjectMutationSnapshot, projectMutationCoordinator } from "@/services/project-mutations";
 

apps/server/src/services/project-versions.ts

@@ -4,8 +4,8 @@ import type {
 	DirectoryProjectVersionStatus,
 	DirectoryVersionFileChange,
 	PreparedDirectoryProjectVersion,
-} from "@openagentpack/project-versions";
-import { createDirectoryWorkspaceVersionService, inspectDirectoryProject } from "@openagentpack/project-workspace";
+} from "@openagentpack/sdk/project-versions";
+import { createDirectoryWorkspaceVersionService, inspectDirectoryProject } from "@openagentpack/sdk/project-workspace";
 import { type ProjectRuntimeManager, projectRuntimeManager } from "@/services/project-manager";
 import { projectMutationCoordinator } from "@/services/project-mutations";