@kaoruisaac/pedelec 0.1.16 → 0.1.18

package/README.md

@@ -128,14 +128,22 @@ await session.sendText("Please help me analyze the current page state");
 
 `sendText()` resolves after the current agent response completes. If the session is already handling a previous prompt, the new `sendText()` call is rejected to prevent multiple concurrent requests from running in the same session.
 
-## Listing uploaded assets
+## Session assets
 
 ```ts
 const path = await session.uploadAsset(file);
 const assets = await session.listAssets();
 ```
 
-`listAssets()` lists only the first level of `input/`, ordered by filesystem modification time (newest first). Each item's `name` is the actual sandbox filename and may differ from the original `File.name`; `modifiedAt` is a filesystem modification timestamp, not an exact upload time. `path` is an agent-sandbox-relative `input/...` path and never an absolute local path. It may be called while the agent is running. Ended sessions reject with `SESSION_ENDED`. Recursive listing, pagination, download, deletion, rename, and move are not supported.
+`assets/` is shared by uploads and files written by the agent. `listAssets()` lists only its first level, ordered by filesystem modification time (newest first), and may run while the agent runs. One session can only upload one file at a time, but uploads can run alongside prepare or agent execution.
+
+```ts
+const text = await session.readAsset("/report.txt", "text");
+const json = await session.readAsset<{ ok: boolean }>("/result.json", "json");
+const result = await session.readAsset("/model.glb", "file");
+```
+
+Public asset paths use `/...` with `assets/` as their implicit root; nested paths such as `/results/model.glb` are supported up to 100 MiB.
 
 ---
 

package/dist/index.d.ts

@@ -6,7 +6,8 @@ export type JsonPrimitive = string | number | boolean | null;
 export type JsonValue = JsonPrimitive | JsonValue[] | {
     [key: string]: JsonValue;
 };
-export type SandboxAssetPath = `input/${string}`;
+export type SandboxAssetPath = `/${string}`;
+export type ReadAssetType = "text" | "json" | "file";
 export type SandboxAsset = {
     name: string;
     path: SandboxAssetPath;
@@ -258,6 +259,7 @@ export declare class PedelecSession<TToolName extends string = string> {
     private pendingPrepare;
     private preparePromise;
     private uploadPromise;
+    private ending;
     private prepared;
     private activeTurn;
     private genericToolHandler;
@@ -274,7 +276,11 @@ export declare class PedelecSession<TToolName extends string = string> {
     onTool(handler: GenericToolHandler<TToolName>): () => void;
     onTool<TArgs = unknown, TResult = unknown>(toolName: TToolName, handler: ToolSpecificHandler<TArgs, TResult>): () => void;
     uploadAsset(file: File): Promise<SandboxAssetPath>;
+    uploadAsset(file: File, targetPath: SandboxAssetPath): Promise<SandboxAssetPath>;
     listAssets(): Promise<SandboxAsset[]>;
+    readAsset(path: SandboxAssetPath, type: "text"): Promise<string>;
+    readAsset<T = JsonValue>(path: SandboxAssetPath, type: "json"): Promise<T>;
+    readAsset(path: SandboxAssetPath, type: "file"): Promise<File>;
     onError(handler: ErrorHandler): () => void;
     onStatus(handler: StatusHandler): () => void;
     onEnded(handler: EndedHandler): () => void;

package/dist/index.js

@@ -12,7 +12,7 @@ function normalizeListAssetsResponse(response) {
             return invalidListAssetsResponse({ index, asset });
         const { name, path, sizeBytes, modifiedAt } = asset;
         const validName = typeof name === "string" && name.length > 0 && name !== "." && name !== ".." && !name.includes("/") && !name.includes("\\");
-        const validPath = typeof path === "string" && !path.includes("\\") && path === `input/${name}` && !path.split("/").includes("..");
+        const validPath = typeof path === "string" && path === `/${name}` && isValidAssetPath(path);
         const validNumber = (value) => typeof value === "number" && Number.isFinite(value) && Number.isInteger(value) && value >= 0;
         if (!validName || !validPath || !validNumber(sizeBytes) || !validNumber(modifiedAt)) {
             return invalidListAssetsResponse({ index, asset });
@@ -23,6 +23,10 @@ function normalizeListAssetsResponse(response) {
 function invalidListAssetsResponse(details) {
     throw makeError("SDK_PROTOCOL_ERROR", "list_assets response had an invalid shape", { response: details });
 }
+function isValidAssetPath(path) {
+    return typeof path === "string" && /^\/(?:[^/\\\x00-\x1f]+)(?:\/[^/\\\x00-\x1f]+)*$/.test(path) &&
+        path.split("/").every((part, index) => index === 0 || (part !== "." && part !== ".."));
+}
 const MAX_ASSET_UPLOAD_BYTES = 100 * 1024 * 1024;
 const TOOL_NAME_PATTERN = /^[a-zA-Z][a-zA-Z0-9_.-]*$/;
 export function defineTool(tool) {
@@ -436,6 +440,7 @@ export class PedelecSession {
     pendingPrepare = null;
     preparePromise = null;
     uploadPromise = null;
+    ending = false;
     prepared = false;
     activeTurn = null;
     genericToolHandler = null;
@@ -456,7 +461,7 @@ export class PedelecSession {
         if (this.status === "ended") {
             return Promise.reject(makeError("SESSION_ENDED", "session has ended", { sessionId: this.sessionId }));
         }
-        if (this.pendingSend || this.uploadPromise) {
+        if (this.pendingSend) {
             return Promise.reject(makeError("SESSION_BUSY", "session is already running", { sessionId: this.sessionId }));
         }
         if (this.prepared) {
@@ -492,9 +497,6 @@ export class PedelecSession {
         return this.preparePromise;
     }
     async sendText(text) {
-        if (this.uploadPromise) {
-            return Promise.reject(makeError("SESSION_BUSY", "an asset upload is in progress", { sessionId: this.sessionId }));
-        }
         if (this.preparePromise) {
             try {
                 await this.preparePromise;
@@ -557,10 +559,10 @@ export class PedelecSession {
             }
         };
     }
-    uploadAsset(file) {
-        if (this.status === "ended")
+    uploadAsset(file, targetPath) {
+        if (this.ending || this.status === "ended")
             return Promise.reject(makeError("SESSION_ENDED", "session has ended", { sessionId: this.sessionId }));
-        if (this.pendingSend || this.pendingPrepare || this.preparePromise || this.uploadPromise || this.status !== "idle") {
+        if (this.uploadPromise) {
             return Promise.reject(makeError("SESSION_BUSY", "session is busy", { sessionId: this.sessionId }));
         }
         if (typeof File === "undefined" || !(file instanceof File) || !file.name || file.size < 0) {
@@ -568,8 +570,11 @@ export class PedelecSession {
         }
         if (file.size > MAX_ASSET_UPLOAD_BYTES)
             return Promise.reject(makeError("ASSET_TOO_LARGE", "asset exceeds the 100 MiB limit"));
+        if (targetPath !== undefined && !isValidAssetPath(targetPath))
+            return Promise.reject(makeError("ASSET_PATH_INVALID", "asset target path is invalid"));
         this.uploadPromise = this.client.request("create_asset_upload", {
             sessionId: this.sessionId, filename: file.name, sizeBytes: file.size, mimeType: file.type,
+            ...(targetPath === undefined ? {} : { targetPath }),
         }).then(async (ticket) => {
             if (!ticket?.uploadUrl || !ticket.token)
                 throw makeError("SDK_PROTOCOL_ERROR", "asset upload ticket was invalid");
@@ -587,18 +592,69 @@ export class PedelecSession {
             catch { /* normalized below */ }
             if (!response.ok)
                 throw normalizeError(payload?.error, "ASSET_UPLOAD_FAILED", "asset upload failed");
-            if (typeof payload?.path !== "string" || !payload.path.startsWith("input/") || payload.path.includes(".."))
+            if (!isValidAssetPath(payload?.path))
                 throw makeError("SDK_PROTOCOL_ERROR", "asset upload response had an invalid path");
+            if (targetPath !== undefined && payload.path !== targetPath)
+                throw makeError("SDK_PROTOCOL_ERROR", "asset upload response path did not match target path");
             return payload.path;
         }).finally(() => { this.uploadPromise = null; });
         return this.uploadPromise;
     }
     listAssets() {
-        if (this.status === "ended") {
+        if (this.ending || this.status === "ended") {
             return Promise.reject(makeError("SESSION_ENDED", "session has ended", { sessionId: this.sessionId }));
         }
         return this.client.request("list_assets", { sessionId: this.sessionId }).then(normalizeListAssetsResponse);
     }
+    readAsset(path, type) {
+        if (this.ending || this.status === "ended")
+            return Promise.reject(makeError("SESSION_ENDED", "session has ended", { sessionId: this.sessionId }));
+        if (!isValidAssetPath(path) || !["text", "json", "file"].includes(type)) {
+            return Promise.reject(makeError("ASSET_PATH_INVALID", "asset path or read type is invalid"));
+        }
+        return this.client.request("create_asset_download", { sessionId: this.sessionId, path }).then(async (ticket) => {
+            if (!ticket || typeof ticket !== "object")
+                throw makeError("SDK_PROTOCOL_ERROR", "asset download ticket was invalid");
+            const value = ticket;
+            if (typeof value.downloadUrl !== "string" || typeof value.token !== "string" || typeof value.name !== "string" ||
+                typeof value.mimeType !== "string" || typeof value.modifiedAt !== "number" || !Number.isFinite(value.modifiedAt) || !isValidAssetPath(value.path)) {
+                throw makeError("SDK_PROTOCOL_ERROR", "asset download ticket was invalid");
+            }
+            let response;
+            try {
+                response = await fetch(value.downloadUrl, { headers: { Authorization: `Bearer ${value.token}` }, credentials: "omit" });
+            }
+            catch (error) {
+                throw normalizeError(error, "ASSET_READ_FAILED", "asset read failed");
+            }
+            if (!response.ok) {
+                let payload;
+                try {
+                    payload = await response.json();
+                }
+                catch { /* normalize below */ }
+                throw normalizeError(payload?.error, "ASSET_READ_FAILED", "asset read failed");
+            }
+            const bytes = await response.arrayBuffer();
+            if (type === "file")
+                return new File([bytes], value.name, { type: value.mimeType || "application/octet-stream", lastModified: value.modifiedAt });
+            let text;
+            try {
+                text = new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+            }
+            catch {
+                throw makeError("ASSET_TEXT_DECODE_FAILED", "asset is not valid UTF-8");
+            }
+            if (type === "text")
+                return text;
+            try {
+                return JSON.parse(text);
+            }
+            catch {
+                throw makeError("ASSET_INVALID_JSON", "asset does not contain valid JSON");
+            }
+        });
+    }
     onError(handler) {
         this.errorHandlers.add(handler);
         return () => this.errorHandlers.delete(handler);
@@ -615,14 +671,16 @@ export class PedelecSession {
         return this.status;
     }
     async end() {
-        if (this.status === "ended")
+        if (this.status === "ended" || this.ending)
             return;
+        this.ending = true;
         try {
             await this.client.request("end_session", {
                 sessionId: this.sessionId,
             });
         }
         catch (err) {
+            this.ending = false;
             const error = normalizeError(err, "END_SESSION_FAILED", "end failed");
             this.emitError(error, { source: "sdk" });
             throw error;

package/dist/index.type-test.js

@@ -96,6 +96,20 @@ async function listAssetsHasPublicTypes() {
     const path = assets[0].path;
     path;
 }
+async function assetPathsUseAssetsAsAnImplicitRoot() {
+    const pedelec = new Pedelec();
+    const session = await pedelec.resumeSession("thread_1");
+    const file = new File(["asset"], "original.txt", { type: "text/plain" });
+    const generated = await session.uploadAsset(file);
+    generated;
+    const exact = await session.uploadAsset(file, "/img/image.txt");
+    exact;
+    const namedAssetsDirectory = "/assets/image.txt";
+    void namedAssetsDirectory;
+    // @ts-expect-error asset paths must begin with a slash
+    const missingSlash = "assets/image.txt";
+    void missingSlash;
+}
 async function availabilityHasPublicType() {
     const pedelec = new Pedelec();
     const availability = await pedelec.checkAvailability();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kaoruisaac/pedelec",
-  "version": "0.1.16",
+  "version": "0.1.18",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",