@kanyun-ai-infra/agenthub 0.1.0 → 0.1.1

package/README.md

@@ -1,24 +1,54 @@
 # @kanyun-ai-infra/agenthub
 
-Typed SDK for the Pilot v2 Control Plane API.
+Typed TypeScript client for the **agenthub Control Plane API**.
+
+It talks directly to the agenthub Control Plane and is meant for backend
+services, CI, and tooling that drive the
+`project → workload → revision → session` lifecycle programmatically.
+
+Two surfaces are involved:
+
+| Surface | URL | Audience |
+| --- | --- | --- |
+| **Control Plane API** | `https://agenthub-plane.zhenguanyu.com` | This SDK / your services — pass it as `controlPlaneUrl`. |
+| **Admin portal** | `https://agenthub.zhenguanyu.com` | Humans who publish and manage agents — and where you **issue an API token**. |
+
+The two use different token audiences: a portal session token will **not** work
+against the Control Plane, and vice versa. Always pair the platform-api token
+issued from the portal with the `agenthub-plane` Control Plane URL.
+
+## Install
+
+```bash
+pnpm add @kanyun-ai-infra/agenthub
+# or: npm i @kanyun-ai-infra/agenthub
+```
+
+Requires Node 18+ (uses the global `fetch`).
+
+## Quickstart
 
 ```ts
 import { PilotPlatformClient } from "@kanyun-ai-infra/agenthub";
 
-const pilot = new PilotPlatformClient({
-  controlPlaneUrl: "https://pilot-control-plane.example.com",
-  token: process.env.PILOT_TOKEN,
+const agenthub = new PilotPlatformClient({
+  controlPlaneUrl: "https://agenthub-plane.zhenguanyu.com",
+  token: process.env.PILOT_TOKEN, // platform-api token from the admin portal
 });
 
-const project = await pilot.projects.create({
-  slug: "acme-project",
-  displayName: "Acme Project",
+// 1. Project — the tenant/root grouping. The default runtime template lets
+//    callers publish revisions without picking one each time (see below).
+const project = await agenthub.projects.create({
+  slug: "acme",
+  displayName: "Acme",
+  defaultRuntimeTemplateRefName: "pilot-v2-pod-agent",
 });
 
-await pilot.workloads.create({
+// 2. Workload — a runnable agent/app in the project
+await agenthub.workloads.create({
   projectId: project.id,
-  slug: "acme-agent",
-  displayName: "Acme Agent",
+  slug: "support-bot",
+  displayName: "Support Bot",
   kind: "managed_agent",
   defaults: {
     model: "claude-opus-4-7",
@@ -26,21 +56,216 @@ await pilot.workloads.create({
   },
 });
 
-const revision = await pilot.workloads.publishRevision({
+// 3. Revision — an immutable published version. Runtime source is inherited
+//    from the project default; override per revision with `runtime.profileRef`.
+const revision = await agenthub.workloads.publishRevision({
   projectId: project.id,
-  workloadSlug: "acme-agent",
+  workloadSlug: "support-bot",
   version: "v1",
   workerContract: { kind: "managed_agent" },
+  setDefault: true,
+  managedAgentProfileSnapshot: {
+    model: "claude-opus-4-7",
+    systemPrompt: "You are the Acme support agent.",
+  },
 });
 
-const session = await pilot.sessions.create({
+// 4. Session — a runtime allocation against the default (or a specific) revision
+const session = await agenthub.sessions.create({
   projectId: project.id,
   workloadId: revision.workloadId,
 });
 
-await pilot.sessions.wait(session.sessionId);
+const ready = await agenthub.sessions.wait(session.sessionId); // resolves when status === "ready"
+```
+
+## Client configuration
+
+`new PilotPlatformClient(config)`
+
+| Option | Required | Description |
+| --- | --- | --- |
+| `controlPlaneUrl` | yes¹ | Control Plane origin. Relative request paths are composed under it; cross-origin paths are rejected before the token is sent. |
+| `token` | yes¹ | Platform-api token. Sent as `Authorization: Bearer <token>` on every request. |
+| `fetch` | no | Custom `fetch` implementation (defaults to the global). |
+| `signal` | no | Default `AbortSignal` applied to every request. |
+| `defaultHeaders` | no | Extra headers merged into every request. |
+| `userAgent` | no | Overrides the default `@kanyun-ai-infra/agenthub/<version>` UA. |
+| `pilotApiVersion` | no | Pins the `x-pilot-api-version` header (defaults to the v2 wire version). |
+
+¹ `controlPlaneUrl` falls back to `PILOT_CONTROL_PLANE_URL` then
+`KANYUN_PILOT_CONTROL_PLANE_URL`; `token` falls back to `PILOT_TOKEN`. Missing
+either produces a typed SDK error before any request is sent.
+
+### Getting a token
+
+Sign in to the **admin portal** at <https://agenthub.zhenguanyu.com> and issue a
+**platform-api token**. That token is scoped to the Control Plane API
+(`agenthub-plane.zhenguanyu.com`); store it as `PILOT_TOKEN` (or pass it as
+`token`). Tokens are bearer credentials — keep them out of source control and
+rotate from the portal if leaked.
+
+## Core model
+
+```text
+Project  →  Workload  →  Revision  →  Session
+```
+
+- **Project** — tenant/root grouping; owns workloads and runtime templates.
+- **Workload** — a logical runnable app. `kind` is `"managed_agent"` (platform
+  runs the agent loop from `model` + `systemPrompt`) or `"self_managed"` (you
+  ship the worker).
+- **Revision** — an immutable published version of a workload, bound to one
+  runtime source. Mark one as the project/workload default with `setDefault`.
+- **Session** — a startup/runtime allocation against a revision.
+
+Workloads and runtime templates are **project-scoped**. A revision must resolve
+its workload and runtime source inside the same project (the one exception is
+platform-shared templates, below).
+
+## API reference
+
+### `agenthub.projects`
+
+| Method | Description |
+| --- | --- |
+| `create({ slug, displayName, description?, defaultRuntimeTemplateRefName? })` | Create a project. Duplicate slug → `409 PROJECT_SLUG_CONFLICT`. |
+| `list()` | List projects in the token's effective scope. |
+| `get(projectId)` | Fetch one project. |
+
+### `agenthub.workloads`
+
+| Method | Description |
+| --- | --- |
+| `create(req, { dryRun? })` | Create a workload from structured input. Returns `{ mode, status, workloadId?, workload }`. |
+| `publishRevision(req, { dryRun? })` | Publish a revision. Returns `{ mode, status, workloadId, revisionId?, runtimeTemplateId, resolved }`. |
+| `applyManifest({ projectId, manifest, dryRun? })` | Advanced/GitOps: apply a raw workload manifest. |
+| `applyRevisionManifest({ projectId, workloadSlug, manifest, dryRun? })` | Advanced/GitOps: apply a raw revision manifest. |
+
+`req` for `create`:
+
+```ts
+{
+  projectId: string;
+  slug: string;
+  displayName: string;
+  kind: "managed_agent" | "self_managed";
+  defaults?: {
+    model?: string;
+    systemPrompt?: string;
+    workerContract?: { name?: string; version?: string };
+    configValues?: Record<string, string>;
+    enabledSkills?: EnabledSkill[];
+    enabledMcpServers?: EnabledMcpServer[];
+  };
+  ui?: { /* Default-UI hints */ };
+}
+```
+
+`req` for `publishRevision`:
+
+```ts
+{
+  projectId: string;
+  workloadSlug: string;
+  version: string;
+  workerContract: { kind: "managed_agent" | "self_managed"; name?: string; version?: string };
+  runtime?: { profileRef?: { name: string }; environment?: ...; overrides?: ... };
+  setDefault?: boolean;
+  startup?: { requiredGates?: string[]; optionalGates?: string[] };
+  configValues?: Record<string, string>;
+  managedAgentProfileSnapshot?: { model?: string; systemPrompt?: string; enabledSkills?: ...; enabledMcpServers?: ... };
+}
 ```
 
-This package talks directly to `apps/control-plane`. The legacy
-`@kanyun-ai-infra/pilot` package remains available for the portal/BFF
-`agents` and `runs` workflows.
+`manifest` (for the `apply*` methods) accepts a manifest object, `{ yaml }`, or
+`{ json }`.
+
+### `agenthub.sessions`
+
+| Method | Description |
+| --- | --- |
+| `create({ projectId, workloadId, revisionId?, configValues?, metadata?, idempotencyKey?, ... })` | Start a session. Omitting `revisionId` uses the workload's default revision. Returns `{ sessionId, status }`. |
+| `get(sessionId)` | Snapshot the session (`{ session: { id, status, ... } }`). |
+| `wait(sessionId, { intervalMs?, timeoutMs?, signal? })` | Poll until `status === "ready"`; throws on `failed` or timeout. |
+
+Session `status` is one of `created`, `provisioning`, `starting`, `ready`,
+`failed`.
+
+## Runtime templates
+
+A managed-agent revision runs on a **runtime template** (a registered runtime
+source). The Control Plane resolves it in this order:
+
+1. revision `runtime.profileRef` (structured) / `spec.runtime.profileRef`
+2. revision `spec.runtimeTemplateRef` (manifest)
+3. workload defaults `spec.defaults.runtimeTemplateRef` (manifest)
+4. project `defaultRuntimeTemplateRefName`
+
+If none resolves → `PROJECT_DEFAULT_RUNTIME_MISSING`. If the named template does
+not exist in the project (or as a platform-shared template) →
+`RUNTIME_TEMPLATE_NOT_FOUND`.
+
+For the happy path, give the project a default at creation so callers never pick
+a template:
+
+```ts
+await agenthub.projects.create({
+  slug: "acme",
+  displayName: "Acme",
+  defaultRuntimeTemplateRefName: "pilot-v2-pod-agent",
+});
+```
+
+Otherwise select one explicitly per revision with
+`runtime: { profileRef: { name: "..." } }`.
+
+**Platform-shared templates.** Templates owned by the Platform Default project
+(e.g. `pilot-v2-pod-agent`) are shared infrastructure: the lookup falls back to
+Platform Default when the name is not found in the caller's project, so any
+project's revision may reference them by name. `echo-bot` is a built-in
+echo-only template useful for smoke tests — it does **not** run an LLM.
+
+## Models
+
+`model` accepts a full id (`claude-opus-4-7`, `claude-sonnet-4-6`,
+`claude-haiku-4-5`) or a legacy alias that maps to one:
+
+| Alias | Resolves to |
+| --- | --- |
+| `opus` | `claude-opus-4-7` |
+| `sonnet` | `claude-sonnet-4-6` |
+| `haiku` | `claude-haiku-4-5` |
+
+## Dry runs
+
+`workloads.create`, `publishRevision`, and the `apply*` methods accept
+`{ dryRun: true }`. A dry run validates and resolves the request without
+persisting, returning `mode: "dry_run"` and a `would_create` / `would_update`
+status. Use it to verify a runtime template resolves before publishing for real.
+
+## Errors
+
+All API failures throw a typed error carrying `status`, `code`, and
+`requestId`:
+
+| Class | HTTP |
+| --- | --- |
+| `PilotPlatformUnauthenticatedError` | 401 |
+| `PilotPlatformForbiddenError` | 403 |
+| `PilotPlatformNotFoundError` | 404 |
+| `PilotPlatformServerError` | 5xx |
+| `PilotPlatformApiError` | base class for the above |
+
+```ts
+import { PilotPlatformNotFoundError } from "@kanyun-ai-infra/agenthub";
+
+try {
+  await agenthub.sessions.get(sessionId);
+} catch (err) {
+  if (err instanceof PilotPlatformNotFoundError) {
+    // err.status === 404, err.code === "SESSION_NOT_FOUND"
+  }
+  throw err;
+}
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kanyun-ai-infra/agenthub",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "type": "module",
   "description": "Typed TypeScript client for the Pilot v2 Control Plane API",
   "exports": {
@@ -13,28 +13,25 @@
   "main": "./dist/index.cjs",
   "module": "./dist/index.js",
   "types": "./dist/index.d.ts",
-  "files": [
-    "dist",
-    "README.md"
-  ],
+  "files": ["dist", "README.md"],
+  "scripts": {
+    "build": "tsup",
+    "check": "tsc --noEmit",
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage",
+    "dev": "tsup --watch"
+  },
   "dependencies": {
     "zod": "^3.24.0"
   },
   "devDependencies": {
+    "@pilot/contracts": "workspace:*",
     "@vitest/coverage-v8": "^4.1.0",
     "tsup": "^8.4.0",
     "typescript": "^5.9.3",
-    "vitest": "^4.0.17",
-    "@pilot/contracts": "0.0.1"
+    "vitest": "^4.0.17"
   },
   "publishConfig": {
     "access": "public"
-  },
-  "scripts": {
-    "build": "tsup",
-    "check": "tsc --noEmit",
-    "test": "vitest run",
-    "test:coverage": "vitest run --coverage",
-    "dev": "tsup --watch"
   }
-}
+}