@kaoruisaac/pedelec 0.1.15 → 0.1.17

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("assets/report.txt", "text");
+const json = await session.readAsset<{ ok: boolean }>("assets/result.json", "json");
+const result = await session.readAsset("assets/model.glb", "file");
+```
+
+Reads support nested `assets/...` paths up to 100 MiB. `text` and `json` require valid UTF-8; binary content is transferred over a loopback download ticket rather than extension messages.
 
 ---
 
@@ -143,6 +151,8 @@ const assets = await session.listAssets();
 
 The first time an origin calls `createSession()` or `resumeSession()`, the extension asks the user to approve that origin in the popup. After approval, the same origin can create sessions directly.
 
+Sessions created through the SDK are bound to the creating origin. The same origin may resume them after reload, in another tab, or from another SDK instance; a different scheme, host, subdomain, or port cannot use the ID. A `sessionId` is an identifier, not a cross-origin bearer credential, and applications cannot supply or override its owner origin.
+
 You can query the current origin's approval status first to decide whether to show UI such as "Connect Pedelec":
 
 ```ts
@@ -151,7 +161,11 @@ const status = await pedelec.getApprovalStatus();
 console.log(status.installed, status.approved, status.origin);
 ```
 
-For a complete Extension, approval, and Desktop readiness probe, use `checkAvailability()`. It never creates/resumes a session or opens approval. When approved it validates Desktop by calling `getSettings()`, which may invoke the existing Native Host auto-launch fallback.
+`getApprovalStatus()` includes `appConnected`, a non-sensitive Core `ping` result. It does not require approval or open the approval popup, but it may use the Native Host's existing Desktop auto-launch fallback. `appConnected` does not mean the origin is approved or a provider is ready.
+
+`getSettings()` and `listProviders()` require origin approval and may open the approval popup. Settings expose only defaults (never provider credentials); providers expose only `name`, `code`, `available`, and `error`. Use `getApprovalStatus().appConnected` rather than `listProviders()` as a connection probe.
+
+For a complete Extension, approval, and Desktop readiness probe, use `checkAvailability()`. It never creates/resumes a session or opens approval. Its status ping may attempt Desktop launch even for an unapproved origin.
 
 ```ts
 const availability = await pedelec.checkAvailability();

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 = `assets/${string}`;
+export type ReadAssetType = "text" | "json" | "file";
 export type SandboxAsset = {
     name: string;
     path: SandboxAssetPath;
@@ -97,7 +98,6 @@ export type CreateSessionInput<TTools extends readonly ToolDefinition[] = readon
 export type ProviderInfo = {
     name: string;
     code: ProviderCode;
-    path: string | null;
     available: boolean;
     error: string | null;
 };
@@ -109,6 +109,7 @@ export type ApprovalStatus = {
     installed: boolean;
     approved: boolean;
     origin: string | null;
+    appConnected: boolean;
 };
 export type PedelecAvailability = {
     available: boolean;
@@ -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;
@@ -275,6 +277,9 @@ export declare class PedelecSession<TToolName extends string = string> {
     onTool<TArgs = unknown, TResult = unknown>(toolName: TToolName, handler: ToolSpecificHandler<TArgs, TResult>): () => void;
     uploadAsset(file: File): 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.includes("\\") && path === `assets/${name}` && !path.split("/").includes("..");
         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" && path.startsWith("assets/") && path.length > "assets/".length && !path.includes("\\") &&
+        path.split("/").every((part, index) => index === 0 || (part.length > 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) {
@@ -147,15 +151,10 @@ export class Pedelec {
         return this.registerSession(result.sessionId, resolvedInput.provider, resolvedInput.model, resolvedInput.inlineToolHandlers);
     }
     async listProviders() {
-        const result = await this.request("list_providers");
-        if (!Array.isArray(result)) {
-            throw makeError("SDK_PROTOCOL_ERROR", "list_providers response was not an array");
-        }
-        return result;
+        return normalizeProviderInfoList(await this.request("list_providers"));
     }
     async getSettings() {
-        const result = await this.request("get_settings");
-        return result;
+        return normalizePedelecSettings(await this.request("get_settings"));
     }
     async getApprovalStatus() {
         if (this.disconnectedError) {
@@ -163,13 +162,11 @@ export class Pedelec {
                 installed: false,
                 approved: false,
                 origin: getCurrentOrigin(this.pageWindow),
+                appConnected: false,
             };
         }
         try {
             const result = await this.request("get_approval_status");
-            if (!isApprovalStatus(result)) {
-                throw makeError("SDK_PROTOCOL_ERROR", "get_approval_status response had invalid shape");
-            }
             return result;
         }
         catch (err) {
@@ -179,6 +176,7 @@ export class Pedelec {
                     installed: false,
                     approved: false,
                     origin: getCurrentOrigin(this.pageWindow),
+                    appConnected: false,
                 };
             }
             throw error;
@@ -287,7 +285,7 @@ export class Pedelec {
                 available: false,
                 extension: { available: true },
                 approval: { approved: false, origin: approval.origin },
-                desktop: { available: false, launchAttempted: false },
+                desktop: { available: approval.appConnected, launchAttempted: true },
             };
         }
         try {
@@ -442,6 +440,7 @@ export class PedelecSession {
     pendingPrepare = null;
     preparePromise = null;
     uploadPromise = null;
+    ending = false;
     prepared = false;
     activeTurn = null;
     genericToolHandler = null;
@@ -462,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) {
@@ -498,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;
@@ -564,9 +560,9 @@ export class PedelecSession {
         };
     }
     uploadAsset(file) {
-        if (this.status === "ended")
+        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) {
@@ -593,18 +589,67 @@ 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");
             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);
@@ -621,14 +666,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;
@@ -894,13 +941,38 @@ function isSessionEvent(message) {
         message.type === "error" ||
         message.type === "ended");
 }
-function isApprovalStatus(value) {
-    if (!value || typeof value !== "object")
-        return false;
-    const status = value;
-    return (typeof status.installed === "boolean" &&
-        typeof status.approved === "boolean" &&
-        (status.origin === null || typeof status.origin === "string"));
+function isProviderCode(value) {
+    return value === "codex" || value === "antigravity" || value === "opencode" ||
+        value === "cursor" || value === "claude" || value === "ollama";
+}
+function isPlainObject(value) {
+    return !!value && typeof value === "object" && !Array.isArray(value);
+}
+function normalizePedelecSettings(value) {
+    if (!isPlainObject(value) || (value.defaultProvider !== null && !isProviderCode(value.defaultProvider)) ||
+        !isPlainObject(value.defaultModels)) {
+        throw makeError("SDK_PROTOCOL_ERROR", "get_settings response had invalid shape");
+    }
+    const defaultModels = {};
+    for (const [code, model] of Object.entries(value.defaultModels)) {
+        if (!isProviderCode(code) || typeof model !== "string") {
+            throw makeError("SDK_PROTOCOL_ERROR", "get_settings response had invalid shape");
+        }
+        defaultModels[code] = model;
+    }
+    return { defaultProvider: value.defaultProvider, defaultModels };
+}
+function normalizeProviderInfoList(value) {
+    if (!Array.isArray(value))
+        throw makeError("SDK_PROTOCOL_ERROR", "list_providers response was not an array");
+    return value.map((item) => {
+        if (!isPlainObject(item) || typeof item.name !== "string" || item.name.length === 0 ||
+            !isProviderCode(item.code) || typeof item.available !== "boolean" ||
+            (item.error !== null && typeof item.error !== "string")) {
+            throw makeError("SDK_PROTOCOL_ERROR", "list_providers response had invalid provider data");
+        }
+        return { name: item.name, code: item.code, available: item.available, error: item.error };
+    });
 }
 function makeError(code, message, details) {
     return details === undefined ? { code, message } : { code, message, details };

package/dist/index.type-test.js

@@ -103,11 +103,24 @@ async function availabilityHasPublicType() {
     void availability;
     void promise;
 }
+function publicSecurityTypesAreRestricted() {
+    const status = {
+        installed: true,
+        approved: true,
+        origin: "https://app.example.test",
+        appConnected: true,
+    };
+    const provider = {};
+    // @ts-expect-error SDK provider metadata must not expose executable paths
+    provider.path;
+    return status;
+}
 void typedOnToolNameFromCreateSession;
 void resumedSessionFallsBackToString;
 void noSkillsFallsBackToString;
 void listAssetsHasPublicTypes;
 void availabilityHasPublicType;
+void publicSecurityTypesAreRestricted;
 const baseContext = {
     sessionId: "thread_1",
     provider: "codex",

package/package.json

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