@deepraxis/sdk 0.1.0-dev.06cf3b8 → 0.1.0-dev.086e3bf

package/dist/helpers/application-publish.d.ts

@@ -1,5 +1,5 @@
 import type { Praxis } from '../core/client.js';
-import type { ApplicationAssetsConfig, ApplicationBinding } from '../generated/types.gen.js';
+import type { ApplicationAssetsConfig, ApplicationBinding, ApplicationVersion } from '../generated/types.gen.js';
 export type AssetsConfig = ApplicationAssetsConfig;
 export interface PublishInput {
     /** 应用名；存在同名应用时复用。 */
@@ -20,16 +20,32 @@ export interface PublishInput {
     bindings?: ApplicationBinding[];
     /** 静态资源路由配置，原样传递。 */
     assets_config?: AssetsConfig;
+    /** Register an upload session to plan changes; do not upload content or publish. Requires an existing application. */
+    dryRun?: boolean;
+    /** Preserve current paths omitted from files. Defaults to false (whole-site replacement). */
+    keepExisting?: boolean;
     /** 是否等待部署完成，默认 true。 */
     wait?: boolean;
     /** 部署等待上限（毫秒），默认 120000。超时不会撤销部署。 */
     timeout_ms?: number;
 }
 export interface PublishResult {
+    /** True when a static-only publication matches the active version. */
+    unchanged?: boolean;
+    /** Current version when unchanged or planning an existing deployment. */
+    version?: ApplicationVersion;
+    /** dryRun compares against the active version; counts are distinct content hashes. */
+    plan?: {
+        added: string[];
+        changed: string[];
+        removed: string[];
+        upload_hashes: number;
+        existing_hashes: number;
+    };
     url: string;
     worker_id: string;
-    version_id: string;
-    deployment_id: string;
+    version_id: string | null;
+    deployment_id: string | null;
     status: string;
     created: boolean;
     /** 本次上传的不同内容 hash 数量。 */
@@ -37,5 +53,9 @@ export interface PublishResult {
     /** 服务端已存在的不同内容 hash 数量。 */
     reused: number;
 }
-/** Publish through the public SDK resources, including content-addressed incremental uploads. */
+/** Publish with whole-site replacement by default; keepExisting preserves omitted paths.
+ * dryRun registers an idempotent upload session (stores its manifest), but uploads no content and does not publish.
+ * The platform does not support gradual rollout. Roll back using workers.deployments.create with
+ * strategy: 'percentage', versions: [{ version_id: previousVersionId, percentage: 100 }], while artifacts are retained.
+ */
 export declare function publish(client: Pick<Praxis, 'application'>, input: PublishInput): Promise<PublishResult>;

package/dist/helpers/application-publish.js

@@ -8,8 +8,16 @@ function base64(bytes) {
     }
     return btoa(chunks.join(''));
 }
-/** Publish through the public SDK resources, including content-addressed incremental uploads. */
+/** Publish with whole-site replacement by default; keepExisting preserves omitted paths.
+ * dryRun registers an idempotent upload session (stores its manifest), but uploads no content and does not publish.
+ * The platform does not support gradual rollout. Roll back using workers.deployments.create with
+ * strategy: 'percentage', versions: [{ version_id: previousVersionId, percentage: 100 }], while artifacts are retained.
+ */
 export async function publish(client, input) {
+    const rolloutFields = ['gradual', 'gradualRollout', 'gradual_rollout', 'canary', 'rollout', 'percentage', 'percent', 'traffic', 'traffic_percentage', 'strategy', 'versions'];
+    if (Object.keys(input).some(key => rolloutFields.includes(key) || /percentage|percent|canary|gradual|rollout|灰度/i.test(key))) {
+        throw new PraxisError({ code: 'INVALID_PARAMS', message: '平台不支持灰度 (gradual rollout is not supported). Roll back with praxis.application.workers.deployments.create({ path: { worker_id }, body: { strategy: "percentage", versions: [{ version_id: previousVersionId, percentage: 100 }] } }); the previous version artifacts must still be retained.' });
+    }
     const timeout = input.timeout_ms ?? 120_000;
     if (!Number.isFinite(timeout) || timeout < 0)
         throw new RangeError('timeout_ms must be non-negative and finite');
@@ -21,7 +29,7 @@ export async function publish(client, input) {
     const files = Object.entries(input.files);
     if (files.length > 100_000)
         throw new PraxisError({ code: 'LIMIT_EXCEEDED', message: 'At most 100000 asset paths can be published' });
-    const manifest = {};
+    let manifest = {};
     const contents = new Map();
     for (const [path, content] of files) {
         const normalized = path.startsWith('/') ? path : `/${path}`;
@@ -44,9 +52,51 @@ export async function publish(client, input) {
         }
     }
     const created = !worker;
+    if (!worker && input.dryRun)
+        throw new PraxisError({ code: 'NOT_FOUND', message: '请先创建应用 (create the application before dryRun)' });
     worker ??= await workers.create({ body: { name: input.name, subdomain: { enabled: true } } });
     const path = { worker_id: worker.id };
+    let currentVersion;
+    let currentDeployment;
+    let previous = {};
+    if (worker.praxis?.current_deployment_id) {
+        currentDeployment = await workers.deployments.retrieve({ path: { ...path, deployment_id: worker.praxis.current_deployment_id } });
+        const active = currentDeployment.versions[0];
+        if (!active)
+            throw new PraxisError({ code: 'INVALID_RESPONSE', message: 'Current deployment has no version' });
+        currentVersion = await workers.versions.retrieve({ path: { ...path, version_id: active.version_id } });
+        previous = (await workers.versions.assets.retrieveManifest({ path: { ...path, version_id: active.version_id } })).manifest;
+    }
+    // Keep the stored path order: the service hashes JSON.stringify(manifest), including property order.
+    // Reordered input with identical paths must still hash to the active version's manifest_hash.
+    manifest = {
+        ...Object.fromEntries(Object.entries(previous).filter(([key]) => input.keepExisting || Object.hasOwn(manifest, key))),
+        ...manifest,
+    };
+    if (Object.keys(manifest).length > 100_000)
+        throw new PraxisError({ code: 'LIMIT_EXCEEDED', message: 'At most 100000 asset paths can be published' });
+    const added = Object.keys(manifest).filter(key => !Object.hasOwn(previous, key));
+    const changed = Object.keys(manifest).filter(key => previous[key] && (previous[key].hash !== manifest[key].hash || previous[key].size !== manifest[key].size));
+    const removed = Object.keys(previous).filter(key => !Object.hasOwn(manifest, key));
+    const digest = new Uint8Array(await crypto.subtle.digest('SHA-256', new TextEncoder().encode(JSON.stringify(manifest))));
+    const manifestHash = Array.from(digest, byte => byte.toString(16).padStart(2, '0')).join('');
+    const staticOnly = !['main', 'bindings', 'compatibility_date', 'compatibility_flags', 'assets_config'].some(key => Object.hasOwn(input, key));
+    const unchanged = staticOnly && !!currentVersion && manifestHash === currentVersion.praxis.assets_manifest?.manifest_hash;
+    const hashes = new Set(Object.values(manifest).map(entry => entry.hash));
+    const currentResult = { url: worker.subdomain.url, worker_id: worker.id, version_id: currentVersion?.id ?? null,
+        deployment_id: currentDeployment?.id ?? null, status: currentDeployment?.praxis.status ?? 'draft', created,
+        ...(currentVersion ? { version: currentVersion } : {}), unchanged, uploaded: 0, reused: hashes.size };
+    if (unchanged && !input.dryRun)
+        return currentResult;
+    // dryRun intentionally registers the content-addressed session manifest, but never uploads or publishes.
     const session = await workers.assetsUploadSession.create({ path, body: { manifest } });
+    if (input.dryRun) {
+        const missing = new Set(session.buckets.flat());
+        if ([...missing].some(hash => !hashes.has(hash)))
+            throw new PraxisError({ code: 'INVALID_RESPONSE', message: 'Upload session requested an unknown hash' });
+        return { ...currentResult, reused: hashes.size - missing.size,
+            plan: { added, changed, removed, upload_hashes: missing.size, existing_hashes: hashes.size - missing.size } };
+    }
     let jwt = session.buckets.length ? null : session.jwt;
     const uploaded = new Set();
     for (const bucket of session.buckets) {
@@ -112,5 +162,5 @@ export async function publish(client, input) {
     }
     return { url: worker.subdomain.url, worker_id: worker.id, version_id: result.version.id,
         deployment_id: deployment.id, status: deployment.praxis.status, created,
-        uploaded: uploaded.size, reused: contents.size - uploaded.size };
+        uploaded: uploaded.size, reused: hashes.size - uploaded.size };
 }

package/dist/operations.generated.d.ts

@@ -140,6 +140,12 @@ export declare const operations: readonly [{
             readonly type: "object";
             readonly required: false;
             readonly description: "Praxis extension: switchable model ids on /agent/v1 only. The default model must be included. When omitted, only the default model is selectable.";
+        }, {
+            readonly name: "preset";
+            readonly type: "string";
+            readonly enum: readonly ["minimal", "data-editor", "full"];
+            readonly required: false;
+            readonly description: "Optional tool preset. minimal enables read, glob, grep and ask_user_question; data-editor also enables write and edit; full uses the default toolset with always_allow. Explicit tools override matching preset entries. codemode requires bash and is absent from data-editor.";
         }];
     };
 }, {
@@ -268,6 +274,12 @@ export declare const operations: readonly [{
             readonly type: "object";
             readonly required: false;
             readonly description: "Praxis extension: switchable model ids on /agent/v1 only. The default model must be included. When omitted, only the default model is selectable.";
+        }, {
+            readonly name: "preset";
+            readonly type: "string";
+            readonly enum: readonly ["minimal", "data-editor", "full"];
+            readonly required: false;
+            readonly description: "Optional tool preset. minimal enables read, glob, grep and ask_user_question; data-editor also enables write and edit; full uses the default toolset with always_allow. Explicit tools override matching preset entries. codemode requires bash and is absent from data-editor.";
         }];
     };
 }, {
@@ -420,6 +432,20 @@ export declare const operations: readonly [{
         readonly sdkName: "external_user_id";
     }];
     readonly query: readonly [];
+}, {
+    readonly resource: "agent.agents.unarchive";
+    readonly method: "create";
+    readonly summary: "Unarchive Agent";
+    readonly description: "Restore an archived agent without creating a configuration version. Already active agents are unchanged. Missing or inaccessible agents return 404. Use the returned agent id to create new sessions.";
+    readonly http: "POST";
+    readonly path: "/agent/v1/agents/{agent_id}/unarchive";
+    readonly streaming: "no";
+    readonly pagination: false;
+    readonly pathParams: readonly [{
+        readonly name: "agent_id";
+        readonly sdkName: "agent_id";
+    }];
+    readonly query: readonly [];
 }, {
     readonly resource: "agent.agents.versions";
     readonly method: "list";
@@ -582,7 +608,7 @@ export declare const operations: readonly [{
     readonly resource: "agent.computers";
     readonly method: "connect";
     readonly summary: "Connect computer";
-    readonly description: "Resume the computer and issue a sandbox connection.\n\nOwn-face extension: Managed Agents has no persistent Computer connection. Returns the public SDK sandbox_id, envd_access_token and template_id, plus the machine tier the computer is on now (light or heavy) and the lease that keeps it there (lease_id, lease_expires_at; lease_id is null when no lease exists). Keep the lease while the connection stays open: renew it about every 20 seconds (POST .../leases/{lease_id}/renew) and release it on close (DELETE .../leases/{lease_id}). An unrenewed lease simply expires, and the full machine is reclaimed only after that. Archived computers remain accessible; foreign or absent computers return 404. Never cache credentials.";
+    readonly description: "Resume the computer and issue a sandbox connection.\n\nOwn-face extension: Managed Agents has no persistent Computer connection. Returns the public SDK sandbox_id, envd_access_token and template_id, plus the machine tier the computer is on now (light or heavy) and the lease that keeps it there (lease_id, lease_expires_at; lease_id is null when no lease exists). Keep the lease while the connection stays open: renew it about every 20 seconds (POST .../leases/{lease_id}/renew) and release it on close (DELETE .../leases/{lease_id}). An unrenewed lease simply expires, and the full machine is reclaimed only after that. Archived computers remain accessible; foreign or absent computers return 404. Never cache credentials.\n\nConnect to a computer with a caller-held lease. Omit the body or send {} to request light: the lightweight shell, or the heavy instance while it is running. Send {\"need\":\"heavy\"} to request full Linux for interactive programs; files are synchronized before the heavy connection is returned with tier heavy. Heavy running time counts toward the daily budget in seconds. Renew the lease while using the connection and release it with DELETE when finished. If the daily budget is exhausted, 429 COMPUTER_BUDGET_EXHAUSTED allows you to continue with need light.";
     readonly http: "POST";
     readonly path: "/agent/v1/computers/{computer_id}/connect";
     readonly streaming: "no";
@@ -592,6 +618,16 @@ export declare const operations: readonly [{
         readonly sdkName: "computer_id";
     }];
     readonly query: readonly [];
+    readonly body: {
+        readonly required: false;
+        readonly fields: readonly [{
+            readonly name: "need";
+            readonly type: "string";
+            readonly enum: readonly ["light", "heavy"];
+            readonly required: false;
+            readonly description: "Defaults to light. light uses the lightweight shell, or the heavy instance while it is running. heavy requests a full Linux computer for interactive programs; heavy running time counts toward the daily budget in seconds.";
+        }];
+    };
 }, {
     readonly resource: "agent.computers.files";
     readonly method: "list";
@@ -1485,6 +1521,20 @@ export declare const operations: readonly [{
             readonly description: "Praxis extension: explicit session thinking effort; null inherits the pinned agent default, then the model default. none disables thinking only when model.thinking.can_disable is true. Unsupported efforts return 400 invalid_request_error.";
         }];
     };
+}, {
+    readonly resource: "agent.sessions";
+    readonly method: "delete";
+    readonly summary: "Delete session";
+    readonly description: "Delete an idle or terminated session and its event history after saving a deletion snapshot. Supply the session id from creation or listing. Running sessions return 409 INVALID_STATE: interrupt first or wait until idle or terminated. Afterwards retrieval and event listing return 404 and lists omit the session. Example: DELETE /agent/v1/sessions/sesn_example.";
+    readonly http: "DELETE";
+    readonly path: "/agent/v1/sessions/{session_id}";
+    readonly streaming: "no";
+    readonly pagination: false;
+    readonly pathParams: readonly [{
+        readonly name: "session_id";
+        readonly sdkName: "session_id";
+    }];
+    readonly query: readonly [];
 }, {
     readonly resource: "agent.sessions";
     readonly method: "retrieve";
@@ -2694,6 +2744,23 @@ export declare const operations: readonly [{
         readonly sdkName: "version_id";
     }];
     readonly query: readonly [];
+}, {
+    readonly resource: "application.workers.versions.assets";
+    readonly method: "retrieveManifest";
+    readonly summary: "Get version asset manifest";
+    readonly description: "Read the retained asset paths, content hashes and byte sizes of a version for publication planning. This read creates no session or version. A version without assets returns an empty manifest; unavailable artifacts and foreign resources return 404.";
+    readonly http: "GET";
+    readonly path: "/application/v1/workers/{worker_id}/versions/{version_id}/assets/manifest";
+    readonly streaming: "no";
+    readonly pagination: false;
+    readonly pathParams: readonly [{
+        readonly name: "worker_id";
+        readonly sdkName: "worker_id";
+    }, {
+        readonly name: "version_id";
+        readonly sdkName: "version_id";
+    }];
+    readonly query: readonly [];
 }, {
     readonly resource: "automation.actions";
     readonly method: "list";

package/dist/operations.generated.js

@@ -175,6 +175,17 @@ export const operations = [
                     "type": "object",
                     "required": false,
                     "description": "Praxis extension: switchable model ids on /agent/v1 only. The default model must be included. When omitted, only the default model is selectable."
+                },
+                {
+                    "name": "preset",
+                    "type": "string",
+                    "enum": [
+                        "minimal",
+                        "data-editor",
+                        "full"
+                    ],
+                    "required": false,
+                    "description": "Optional tool preset. minimal enables read, glob, grep and ask_user_question; data-editor also enables write and edit; full uses the default toolset with always_allow. Explicit tools override matching preset entries. codemode requires bash and is absent from data-editor."
                 }
             ]
         }
@@ -332,6 +343,17 @@ export const operations = [
                     "type": "object",
                     "required": false,
                     "description": "Praxis extension: switchable model ids on /agent/v1 only. The default model must be included. When omitted, only the default model is selectable."
+                },
+                {
+                    "name": "preset",
+                    "type": "string",
+                    "enum": [
+                        "minimal",
+                        "data-editor",
+                        "full"
+                    ],
+                    "required": false,
+                    "description": "Optional tool preset. minimal enables read, glob, grep and ask_user_question; data-editor also enables write and edit; full uses the default toolset with always_allow. Explicit tools override matching preset entries. codemode requires bash and is absent from data-editor."
                 }
             ]
         }
@@ -522,6 +544,23 @@ export const operations = [
         ],
         "query": []
     },
+    {
+        "resource": "agent.agents.unarchive",
+        "method": "create",
+        "summary": "Unarchive Agent",
+        "description": "Restore an archived agent without creating a configuration version. Already active agents are unchanged. Missing or inaccessible agents return 404. Use the returned agent id to create new sessions.",
+        "http": "POST",
+        "path": "/agent/v1/agents/{agent_id}/unarchive",
+        "streaming": "no",
+        "pagination": false,
+        "pathParams": [
+            {
+                "name": "agent_id",
+                "sdkName": "agent_id"
+            }
+        ],
+        "query": []
+    },
     {
         "resource": "agent.agents.versions",
         "method": "list",
@@ -717,7 +756,7 @@ export const operations = [
         "resource": "agent.computers",
         "method": "connect",
         "summary": "Connect computer",
-        "description": "Resume the computer and issue a sandbox connection.\n\nOwn-face extension: Managed Agents has no persistent Computer connection. Returns the public SDK sandbox_id, envd_access_token and template_id, plus the machine tier the computer is on now (light or heavy) and the lease that keeps it there (lease_id, lease_expires_at; lease_id is null when no lease exists). Keep the lease while the connection stays open: renew it about every 20 seconds (POST .../leases/{lease_id}/renew) and release it on close (DELETE .../leases/{lease_id}). An unrenewed lease simply expires, and the full machine is reclaimed only after that. Archived computers remain accessible; foreign or absent computers return 404. Never cache credentials.",
+        "description": "Resume the computer and issue a sandbox connection.\n\nOwn-face extension: Managed Agents has no persistent Computer connection. Returns the public SDK sandbox_id, envd_access_token and template_id, plus the machine tier the computer is on now (light or heavy) and the lease that keeps it there (lease_id, lease_expires_at; lease_id is null when no lease exists). Keep the lease while the connection stays open: renew it about every 20 seconds (POST .../leases/{lease_id}/renew) and release it on close (DELETE .../leases/{lease_id}). An unrenewed lease simply expires, and the full machine is reclaimed only after that. Archived computers remain accessible; foreign or absent computers return 404. Never cache credentials.\n\nConnect to a computer with a caller-held lease. Omit the body or send {} to request light: the lightweight shell, or the heavy instance while it is running. Send {\"need\":\"heavy\"} to request full Linux for interactive programs; files are synchronized before the heavy connection is returned with tier heavy. Heavy running time counts toward the daily budget in seconds. Renew the lease while using the connection and release it with DELETE when finished. If the daily budget is exhausted, 429 COMPUTER_BUDGET_EXHAUSTED allows you to continue with need light.",
         "http": "POST",
         "path": "/agent/v1/computers/{computer_id}/connect",
         "streaming": "no",
@@ -728,7 +767,22 @@ export const operations = [
                 "sdkName": "computer_id"
             }
         ],
-        "query": []
+        "query": [],
+        "body": {
+            "required": false,
+            "fields": [
+                {
+                    "name": "need",
+                    "type": "string",
+                    "enum": [
+                        "light",
+                        "heavy"
+                    ],
+                    "required": false,
+                    "description": "Defaults to light. light uses the lightweight shell, or the heavy instance while it is running. heavy requests a full Linux computer for interactive programs; heavy running time counts toward the daily budget in seconds."
+                }
+            ]
+        }
     },
     {
         "resource": "agent.computers.files",
@@ -1833,6 +1887,23 @@ export const operations = [
             ]
         }
     },
+    {
+        "resource": "agent.sessions",
+        "method": "delete",
+        "summary": "Delete session",
+        "description": "Delete an idle or terminated session and its event history after saving a deletion snapshot. Supply the session id from creation or listing. Running sessions return 409 INVALID_STATE: interrupt first or wait until idle or terminated. Afterwards retrieval and event listing return 404 and lists omit the session. Example: DELETE /agent/v1/sessions/sesn_example.",
+        "http": "DELETE",
+        "path": "/agent/v1/sessions/{session_id}",
+        "streaming": "no",
+        "pagination": false,
+        "pathParams": [
+            {
+                "name": "session_id",
+                "sdkName": "session_id"
+            }
+        ],
+        "query": []
+    },
     {
         "resource": "agent.sessions",
         "method": "retrieve",
@@ -3326,6 +3397,27 @@ export const operations = [
         ],
         "query": []
     },
+    {
+        "resource": "application.workers.versions.assets",
+        "method": "retrieveManifest",
+        "summary": "Get version asset manifest",
+        "description": "Read the retained asset paths, content hashes and byte sizes of a version for publication planning. This read creates no session or version. A version without assets returns an empty manifest; unavailable artifacts and foreign resources return 404.",
+        "http": "GET",
+        "path": "/application/v1/workers/{worker_id}/versions/{version_id}/assets/manifest",
+        "streaming": "no",
+        "pagination": false,
+        "pathParams": [
+            {
+                "name": "worker_id",
+                "sdkName": "worker_id"
+            },
+            {
+                "name": "version_id",
+                "sdkName": "version_id"
+            }
+        ],
+        "query": []
+    },
     {
         "resource": "automation.actions",
         "method": "list",