@kanyun-ai-infra/agenthub 0.3.0 → 0.4.0

package/README.md

@@ -54,6 +54,16 @@ await agenthub.agents.create({
   defaults: {
     model: "claude-opus-4-7",
     systemPrompt: "You are the Acme support agent.",
+    agentPackage: {
+      format: "claude_code",
+      source: {
+        kind: "oss",
+        url: "https://bucket.oss-cn-beijing.aliyuncs.com/pilot/agent-packages/support-bot.tar.gz",
+        sha256: "sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+        sizeBytes: 4096,
+      },
+      entryCommand: "报告",
+    },
   },
 });
 
@@ -126,6 +136,7 @@ Agents 和 runtime templates 都是 **project-scoped**。Version 必须在同一
 | `create({ slug, displayName, description?, defaultRuntimeTemplateRefName? })` | 创建 Project。slug 重复时返回 `409 PROJECT_SLUG_CONFLICT`。 |
 | `list()` | 列出 token 有效 scope 内的 Project。 |
 | `get(projectId)` | 查询单个 Project。 |
+| `delete(projectId)` | 软删（停用）Project：清空 owner / members、关闭集成。**owner-only**（需 `project:settings`）。系统项目不可删。返回 `{ action: "deactivated", projectId }`。 |
 
 ### `agenthub.agents`（别名 `agenthub.workloads`）
 
@@ -137,8 +148,8 @@ Agents 和 runtime templates 都是 **project-scoped**。Version 必须在同一
 | `applyRevisionManifest({ projectId, agentSlug \| workloadSlug, manifest, dryRun? })` | 高级 / GitOps：apply raw version manifest。两个 slug 拼写都接受（互斥）。 |
 
 `create` / `publishVersion` 的 `req` 结构和 managed-agent 全部配置项（`model` /
-`systemPrompt` / `enabledSkills` / `enabledMcpServers` / `agentOptions` 安全约束 /
-`runtime` / `startup` 等），见
+`systemPrompt` / `enabledSkills` / `enabledMcpServers` / `agentPackage` /
+`agentOptions` 安全约束 / `runtime` / `startup` 等），见
 [`specs/features/agenthub-sdk.md`](../../specs/features/agenthub-sdk.md)
 的 "Managed-Agent Configuration"、"Workload API Contract"、"Revision Publish Contract" 章节。
 
@@ -157,6 +168,7 @@ Agents 和 runtime templates 都是 **project-scoped**。Version 必须在同一
 | `create({ projectId, agentId, versionId?, configValues?, metadata?, idempotencyKey?, resources?, ... })` | 启动 Session。省略 `versionId` 时使用 Agent 默认 Version。`agentId`/`versionId` 也可写成 `workloadId`/`revisionId`（互斥）。`resources` 注入 Model A 只读输入文件（见下）。返回 `{ sessionId, status }`。 |
 | `get(sessionId)` | 读取 Session 快照（`{ session: { id, status, ... } }`，字段为服务端原样返回）。 |
 | `wait(sessionId, { intervalMs?, timeoutMs?, signal? })` | 轮询到 `status === "ready"`；遇到 `failed` 或超时会抛错。 |
+| `releaseSandbox(sessionId)` | 释放 Session 当前 sandbox（保留 session，下一轮 turn 自动 revive 到新 sandbox）。需 `runs:create`。返回 `{ released, sandboxId, sandboxDestroyed, destroyError? }`；`sandboxDestroyed:false` 不代表失败（watcher 会兜底销毁）。 |
 
 Session `status` 取值为 `created`、`provisioning`、`starting`、`ready`、`failed`。
 

package/dist/index.cjs

@@ -28,11 +28,13 @@ var __privateSet = (obj, member, value, setter) => (__accessCheck(obj, member, "
 var index_exports = {};
 __export(index_exports, {
   AGENTHUB_SDK_USER_AGENT: () => AGENTHUB_SDK_USER_AGENT,
+  AgentPackageSchema: () => AgentPackageSchema,
   AgentsResource: () => WorkloadsResource,
   CreatePlatformProjectRequestSchema: () => CreatePlatformProjectRequestSchema,
   CreatePlatformSessionRequestSchema: () => CreatePlatformSessionRequestSchema,
   CreatePlatformSessionResponseSchema: () => CreatePlatformSessionResponseSchema,
   CreatePlatformWorkloadRequestSchema: () => CreatePlatformWorkloadRequestSchema,
+  DeletePlatformProjectResponseSchema: () => DeletePlatformProjectResponseSchema,
   FilesResource: () => FilesResource,
   ListPlatformProjectsResponseSchema: () => ListPlatformProjectsResponseSchema,
   PILOT_WORKLOAD_MANIFEST_API_VERSION: () => PILOT_WORKLOAD_MANIFEST_API_VERSION,
@@ -49,6 +51,7 @@ __export(index_exports, {
   PlatformWorkloadSchema: () => PlatformWorkloadSchema,
   ProjectsResource: () => ProjectsResource,
   PublishPlatformRevisionRequestSchema: () => PublishPlatformRevisionRequestSchema,
+  ReleaseSandboxResponseSchema: () => ReleaseSandboxResponseSchema,
   SessionFileResourceSchema: () => SessionFileResourceSchema,
   SessionResourcesSchema: () => SessionResourcesSchema,
   SessionsResource: () => SessionsResource,
@@ -767,6 +770,13 @@ var CreateSessionRequestSchema = import_zod6.z.object({
   idempotencyKey: import_zod6.z.string().min(1).optional(),
   configValues: SessionConfigValuesSchema.optional(),
   metadata: import_zod6.z.record(import_zod6.z.unknown()).optional(),
+  /**
+   * UI/BFF hint for managed-agent launchers: when true, an AgentHub route may
+   * try to lease a ready session from the session prewarming pool before
+   * falling back to normal session creation. Core create-session semantics
+   * remain unchanged; services that do not implement prewarming MUST ignore it.
+   */
+  preferPrewarmed: import_zod6.z.boolean().optional(),
   /**
    * GAP1-B (rush-app v2 migration) — optional caller-supplied stable runtime
    * claim name. Forwarded to the runtime provider's `create()` as the sandbox
@@ -957,6 +967,59 @@ var WORKLOAD_MANIFEST_MODEL_MAX_LENGTH = 255;
 var WorkloadManifestModelSchema = import_zod4.z.string().min(1).max(WORKLOAD_MANIFEST_MODEL_MAX_LENGTH);
 var WORKLOAD_MANIFEST_SYSTEM_PROMPT_MAX_LENGTH = 32768;
 var WorkloadManifestSystemPromptSchema = import_zod4.z.string().min(1).max(WORKLOAD_MANIFEST_SYSTEM_PROMPT_MAX_LENGTH);
+var AGENT_PACKAGE_MAX_SIZE_BYTES = 50 * 1024 * 1024;
+var AGENT_PACKAGE_SOURCE_URL_MAX_LENGTH = 2048;
+var SHA256_DIGEST_PATTERN = /^sha256:[0-9a-fA-F]{64}$/;
+var OSS_AGENT_PACKAGE_HOST_PATTERN = /^[a-z0-9][a-z0-9-]*\.oss-[a-z0-9-]+(?:-internal)?\.aliyuncs\.com$/i;
+function hasAsciiControlCharacter(value) {
+  for (let i = 0; i < value.length; i += 1) {
+    const code = value.charCodeAt(i);
+    if (code <= 31 || code === 127) return true;
+  }
+  return false;
+}
+function isApprovedAgentPackageUrl(value) {
+  let parsed;
+  try {
+    parsed = new URL(value);
+  } catch (e) {
+    return false;
+  }
+  if (parsed.protocol !== "https:") return false;
+  if (!OSS_AGENT_PACKAGE_HOST_PATTERN.test(parsed.hostname)) return false;
+  let key;
+  try {
+    key = decodeURIComponent(parsed.pathname.replace(/^\/+/, ""));
+  } catch (e) {
+    return false;
+  }
+  const segments = key.split("/");
+  if (segments.includes(".") || segments.includes("..")) return false;
+  if (!key.startsWith("pilot/agent-packages/")) return false;
+  return key.endsWith(".tar.gz") || key.endsWith(".tgz");
+}
+var ClaudeCodeAgentPackageEntryCommandSchema = import_zod4.z.string().min(1).max(100).refine((value) => value.trim() === value, {
+  message: "entryCommand must not have leading or trailing whitespace"
+}).refine((value) => !hasAsciiControlCharacter(value), {
+  message: "entryCommand must not contain control characters"
+}).refine((value) => value !== "." && value !== "..", {
+  message: "entryCommand must be a command name, not a path segment"
+}).refine((value) => !value.includes("/") && !value.includes("\\"), {
+  message: "entryCommand must not contain path separators"
+});
+var AgentPackageSourceSchema = import_zod4.z.object({
+  kind: import_zod4.z.literal("oss"),
+  url: import_zod4.z.string().url().max(AGENT_PACKAGE_SOURCE_URL_MAX_LENGTH).refine(isApprovedAgentPackageUrl, {
+    message: "url must be an approved HTTPS OSS agent package URL"
+  }),
+  sha256: import_zod4.z.string().regex(SHA256_DIGEST_PATTERN, "sha256 must be sha256:<64 hex chars>"),
+  sizeBytes: import_zod4.z.number().int().positive().max(AGENT_PACKAGE_MAX_SIZE_BYTES).optional()
+}).strict();
+var AgentPackageSchema = import_zod4.z.object({
+  format: import_zod4.z.literal("claude_code"),
+  source: AgentPackageSourceSchema,
+  entryCommand: ClaudeCodeAgentPackageEntryCommandSchema.optional()
+}).strict();
 var AGENT_OPTIONS_MAX_TURNS = 200;
 var AGENT_OPTIONS_MAX_THINKING_TOKENS = 6e4;
 var AGENT_OPTIONS_MAX_BUDGET_USD = 50;
@@ -992,7 +1055,8 @@ var ManagedAgentProfileSnapshotSchema = import_zod4.z.object({
   enabledMcpServers: EnabledMcpEntryListSchema.optional(),
   configValues: SessionConfigValuesSchema.optional(),
   resources: SessionResourcesSchema.optional(),
-  agentOptions: AgentOptionsSchema.optional()
+  agentOptions: AgentOptionsSchema.optional(),
+  agentPackage: AgentPackageSchema.optional()
 }).strict();
 var ManagedAgentOverridesSchema = import_zod4.z.object({
   model: WorkloadManifestModelSchema.nullable().optional(),
@@ -1075,7 +1139,14 @@ var WorkloadManifestDefaultsSchema = import_zod4.z.object({
    * `createClaudeCode({ defaultSettings })` by the agent-runtime
    * claude-code provider. See `AgentOptionsSchema` above and issue #840.
    */
-  agentOptions: AgentOptionsSchema.optional()
+  agentOptions: AgentOptionsSchema.optional(),
+  /**
+   * Workload-level **default agent package**. The Revision snapshot freezes
+   * this reference and the dispatch payload forwards it to the sandbox
+   * agent-worker, which downloads, verifies, and materializes the Claude Code
+   * package before the provider starts.
+   */
+  agentPackage: AgentPackageSchema.optional()
 }).strict();
 var WORKLOAD_MANIFEST_UI_DISPLAY_NAME_MAX_LENGTH = 255;
 var WORKLOAD_MANIFEST_UI_PROMPT_PLACEHOLDER_MAX_LENGTH = 500;
@@ -1826,6 +1897,8 @@ var OssCredentialSchema = import_zod22.z.object({
    * client can compose multi-key flows by requesting fresh URLs).
    */
   prefix: import_zod22.z.string().min(1),
+  /** The object key this URL is scoped to. Omitted by legacy issuers. */
+  key: import_zod22.z.string().min(1).optional(),
   /**
    * Pre-signed PUT URL for the Session's default artifact object key
    * (`${prefix}artifact.bin` by convention). Phase 1 fallback in place
@@ -1840,6 +1913,15 @@ var OssCredentialSchema = import_zod22.z.object({
   stsSecretAccessKey: import_zod22.z.string().optional(),
   stsSessionToken: import_zod22.z.string().optional()
 });
+var OssUploadRequestSchema = import_zod22.z.object({
+  /**
+   * Optional OSS object key to presign for upload. When omitted, the
+   * broker preserves the legacy `${sessionPrefix}artifact.bin` behavior.
+   * Callers may pass either a session-relative path or a fully-qualified
+   * key under `pilot/sessions/<sessionId>/`.
+   */
+  key: import_zod22.z.string().min(1).optional()
+}).strict();
 var OssDownloadRequestSchema = import_zod22.z.object({
   /** OSS object key the Worker wants to read (an input file's key). */
   key: import_zod22.z.string().min(1)
@@ -1864,7 +1946,8 @@ var CredentialsBrokerErrorCodeSchema = import_zod22.z.enum([
   "SESSION_TOKEN_REVOKED",
   "SESSION_TOKEN_EXPIRED",
   "POD_AGENT_TOKEN_INVALID",
-  // 400 — request body invalid (oss-download `key` missing/malformed)
+  // 400 — request body invalid (oss upload/download `key` missing/malformed)
+  "OSS_UPLOAD_KEY_INVALID",
   "OSS_DOWNLOAD_KEY_INVALID",
   // 403 — authorization failures
   "SESSION_TOKEN_SESSION_MISMATCH",
@@ -3924,7 +4007,8 @@ var ManagedAgentProfileSpecSchema = import_zod41.z.object({
   // Agent-level default runtime files. The envelope is exactly the session
   // resources contract so the same mount/download path handles both default
   // files and caller-supplied per-session files.
-  resources: SessionResourcesSchema.optional()
+  resources: SessionResourcesSchema.optional(),
+  agentPackage: AgentPackageSchema.optional()
 }).strict();
 var ManagedAgentProfileSchema = import_zod41.z.object({
   apiVersion: PilotWorkloadManifestApiVersionSchema,
@@ -3950,6 +4034,10 @@ var CreatePlatformProjectRequestSchema = import_zod42.z.object({
 var ListPlatformProjectsResponseSchema = import_zod42.z.object({
   projects: import_zod42.z.array(PlatformProjectSchema)
 }).strict();
+var DeletePlatformProjectResponseSchema = import_zod42.z.object({
+  action: import_zod42.z.literal("deactivated"),
+  projectId: import_zod42.z.string().uuid()
+}).strict();
 var PlatformWorkloadDefaultsSchema = import_zod42.z.object({
   workerContract: WorkloadManifestWorkerContractDefaultsSchema.optional(),
   configValues: SessionConfigValuesSchema.optional(),
@@ -3957,7 +4045,8 @@ var PlatformWorkloadDefaultsSchema = import_zod42.z.object({
   systemPrompt: import_zod42.z.string().min(1).max(32768).optional(),
   enabledSkills: EnabledSkillEntryListSchema.optional(),
   enabledMcpServers: EnabledMcpEntryListSchema.optional(),
-  agentOptions: AgentOptionsSchema.optional()
+  agentOptions: AgentOptionsSchema.optional(),
+  agentPackage: AgentPackageSchema.optional()
 }).strict();
 var CreatePlatformWorkloadRequestSchema = import_zod42.z.object({
   projectId: import_zod42.z.string().uuid(),
@@ -4016,6 +4105,12 @@ var GetPlatformSessionResponseSchema = import_zod42.z.object({
 }).strict();
 var CreatePlatformSessionRequestSchema = CreateSessionRequestSchema;
 var CreatePlatformSessionResponseSchema = CreateSessionResponseSchema;
+var ReleaseSandboxResponseSchema = import_zod42.z.object({
+  released: import_zod42.z.literal(true),
+  sandboxId: import_zod42.z.string().nullable(),
+  sandboxDestroyed: import_zod42.z.boolean(),
+  destroyError: import_zod42.z.string().optional()
+}).strict();
 var PlatformFileUploadResponseSchema = AttachmentMetaSchema.extend({
   url: import_zod42.z.string()
 });
@@ -4152,6 +4247,12 @@ var PilotCoderRunConfigV1Schema = import_zod43.z.object({
    * means contracts must ship before control-worker starts populating it.
    */
   agentOptions: AgentOptionsSchema.optional(),
+  /**
+   * Optional Claude Code agent package to install before the provider boots.
+   * The reference is checksum-pinned and originates from the managed_agent
+   * profile Revision snapshot / workload default.
+   */
+  agentPackage: AgentPackageSchema.optional(),
   /**
    * P3 L3.3 — delivery-related fields populated by control-worker from
    * `runs.*` / `agents.*` columns so the worker delivery loop can act
@@ -4625,6 +4726,22 @@ var ProjectsResource = class {
     );
     return PlatformProjectSchema.parse(response);
   }
+  /**
+   * Soft-delete (deactivate) a project: null the owner, clear members, disable
+   * integrations. Owner-only (the calling token must belong to the project
+   * owner). System projects cannot be deleted. The row is kept for audit, so
+   * the response `action` is always `"deactivated"`.
+   */
+  async delete(projectId, options = {}) {
+    const response = await this.client.request(
+      `/api/projects/${encodeURIComponent(projectId)}`,
+      {
+        method: "DELETE",
+        signal: options.signal
+      }
+    );
+    return DeletePlatformProjectResponseSchema.parse(response);
+  }
 };
 
 // src/agent-vocab.ts
@@ -4727,6 +4844,25 @@ var SessionsResource = class {
       await sleep(intervalMs, options.signal);
     }
   }
+  /**
+   * Release the session's current sandbox while keeping the session alive — a
+   * later turn transparently revives it onto a fresh sandbox. Use this to free
+   * runtime resources for an idle-but-not-finished session without terminating
+   * it. Idempotent at the sandbox layer (an already-gone sandbox still succeeds).
+   *
+   * `sandboxDestroyed: false` (with `destroyError`) is NOT a failure — the
+   * session is still correctly reclaimed; see {@link ReleaseSandboxResponse}.
+   */
+  async releaseSandbox(sessionId, options = {}) {
+    const envelope = await this.client.request(
+      `/api/sessions/${encodeURIComponent(sessionId)}/release-sandbox`,
+      {
+        method: "POST",
+        signal: options.signal
+      }
+    );
+    return ReleaseSandboxResponseSchema.parse(envelope?.data);
+  }
 };
 function sleep(ms, signal) {
   if (ms <= 0) return Promise.resolve();
@@ -5058,11 +5194,13 @@ function mergeSignals(...signals) {
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   AGENTHUB_SDK_USER_AGENT,
+  AgentPackageSchema,
   AgentsResource,
   CreatePlatformProjectRequestSchema,
   CreatePlatformSessionRequestSchema,
   CreatePlatformSessionResponseSchema,
   CreatePlatformWorkloadRequestSchema,
+  DeletePlatformProjectResponseSchema,
   FilesResource,
   ListPlatformProjectsResponseSchema,
   PILOT_WORKLOAD_MANIFEST_API_VERSION,
@@ -5079,6 +5217,7 @@ function mergeSignals(...signals) {
   PlatformWorkloadSchema,
   ProjectsResource,
   PublishPlatformRevisionRequestSchema,
+  ReleaseSandboxResponseSchema,
   SessionFileResourceSchema,
   SessionResourcesSchema,
   SessionsResource,