@deepraxis/sdk 0.1.0-dev.06cf3b8 → 0.1.0-dev.13103a0

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";
@@ -1485,6 +1511,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 +2734,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",
@@ -1833,6 +1872,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 +3382,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",