@kaoruisaac/pedelec 0.4.10 → 0.4.12

package/README.md

@@ -91,9 +91,9 @@ npm install ../path/to/pedelec/sdk
 
 ---
 
-## Deno Modules
+## Runtime Modules
 
-Vite applications can package local or installed JavaScript/TypeScript libraries for Agent-authored `pedelec-deno` scripts.
+Vite applications can package local or installed JavaScript/TypeScript libraries for Agent-authored `pedelec-ts-runtime` scripts.
 
 ### Setup
 
@@ -110,15 +110,15 @@ export default defineConfig({
 ### Authoring
 
 ```ts
-import { Pedelec, defineDenoModule } from "@kaoruisaac/pedelec";
+import { Pedelec, defineRuntimeModule } from "@kaoruisaac/pedelec";
 
 const pedelec = new Pedelec();
 const session = await pedelec.createSession({
   skills: {
     guidance: "Use sprite-tools for sprite authoring tasks.",
     tools: [],
-    denoModules: [
-      defineDenoModule({
+    runtimeModules: [
+      defineRuntimeModule({
         name: "sprite-tools",
         description: "Sprite authoring and preview utilities.",
         entry: "./agent/sprite-tools.ts",
@@ -133,7 +133,7 @@ const session = await pedelec.createSession({
 For an installed package, use its package specifier as the build-time entry:
 
 ```ts
-defineDenoModule({
+defineRuntimeModule({
   name: "gsap",
   description: "Animation utilities.",
   entry: "gsap",
@@ -145,9 +145,9 @@ defineDenoModule({
 
 The generated declaration describes the module's Agent-facing API, so implementation-only dependency types are omitted. Module-owned types are supported; packages that expose dependency-owned or Node-specific external types directly in their public API are not guaranteed to produce a standalone declaration in V1. `name` is the Agent import specifier, and `usage` is required common-case guidance. `createSession()` transfers the prepared artifact automatically; a session keeps an immutable module snapshot, and `session.end()`/`session.resume()` reuse it while Core still knows the thread.
 
-Deno Modules are imported inside JavaScript/TypeScript run with `pedelec-deno`. They are different from `skills.tools`, whose browser/App RPC capabilities use `pedelec-cli` tool-spec and tool-call commands.
+Runtime Modules are imported inside JavaScript/TypeScript run with `pedelec-ts-runtime`. They are different from `skills.tools`, whose browser/App RPC capabilities use `pedelec-cli` tool-spec and tool-call commands.
 
-Set the optional `preferStdinExecution: true` when short scripts primarily use a module and should be steered toward stdin execution. Host Context then adds that module's concrete `runCommandTemplate` (`@'\n<typescript-source>\n'@ | pedelec-deno --thread-id <thread-id> run -`), so the Agent only needs to replace the TypeScript source placeholder instead of deciding how to serialize stdin. This is a preference, not a restriction: file-backed execution remains valid, and omitting the field or setting it to `false` preserves the default behavior. It does not change bundling, artifact contents, or runtime permissions.
+Set optional `preferStdinExecution: true` when short scripts primarily use a module. Host Context then exposes `preferredExecution: "stdin"` for that module; the Agent uses the global `runStdinCommand` with `pedelec-ts-runtime`. This is a preference: file-backed execution remains valid. Omitting the field or setting it to `false` preserves default authoring behavior. It does not change bundling, artifacts, or permissions.
 
 ---
 
@@ -311,7 +311,7 @@ const session = await workspace.createSession({
 const workspace = await pedelec.openWorkspace("C:\\workspace\\project-a");
 ```
 
-Pedelec initializes `.pedelec-runtime` for Workspace-owned runtime data without clearing project files or existing private data. Assets, logs, and temporary data are Workspace-level, while generated Session skills and Deno Module state are isolated per Thread. Applications should not depend on the private `.pedelec-runtime` subdirectory layout. Explicit Workspaces are application-managed, are never deleted by Pedelec, and can own multiple Sessions. An explicit path must not overlap Pedelec's managed workspace root.
+Pedelec initializes `.pedelec-runtime` for Workspace-owned runtime data without clearing project files or existing private data. Assets, logs, and temporary data are Workspace-level, while generated Session skills and Runtime Module state are isolated per Thread. Applications should not depend on the private `.pedelec-runtime` subdirectory layout. Explicit Workspaces are application-managed, are never deleted by Pedelec, and can own multiple Sessions. An explicit path must not overlap Pedelec's managed workspace root.
 
 ### Managed convenience
 
@@ -339,7 +339,7 @@ const text = await workspace.readFile("README.md", "text");
 
 `session.uploadAsset()`, `readAsset()`, and `listAssets()` stay available as Session-scoped conveniences. Their root is `.pedelec-runtime/assets`, which suits provider artifacts and Agent-shared assets. Use the Workspace methods for general filesystem access.
 
-`workspace.run(script, options?)` executes application-supplied Deno code in the Workspace:
+`workspace.run(script, options?)` executes application-supplied TypeScript code in the Workspace:
 
 ```ts
 const result = await workspace.run(
@@ -355,25 +355,25 @@ const value = JSON.parse(result.stdout);
 
 The default timeout is 60 seconds; `timeoutMs` must be a positive integer. The return value is the raw `DenoRunOutput` shape: `exitCode`, `stdout`, `stderr`, `stdoutTruncated`, and `stderrTruncated`. A non-zero `exitCode` still resolves normally. The application parses `stdout` when it wants a function-like return value. Check truncation flags before relying on output; an oversized browser response fails with `WORKSPACE_RUN_OUTPUT_TOO_LARGE`.
 
-`workspace.run()` has read and write access to the Workspace, but no network, host environment, subprocess execution, FFI, or `sys` permission. The existing no-remote, cached-only, and no-npm runtime restrictions still apply. This is a direct deterministic capability for an approved Web application to read and modify the opened Workspace; it is not unrestricted host code execution and is not mediated by an Agent.
+By default, `workspace.run()` has read and write access to the Workspace, but no network, host environment, subprocess execution, FFI, or `sys` permission. In Sandbox, the existing no-remote, cached-only, and no-npm runtime restrictions still apply. This default mode is a direct capability for an approved Web application and is not mediated by an Agent.
 
 Multiple Sessions, Agent/provider operations, and `workspace.run()` executions may operate concurrently in the same Workspace. A second turn on the same Session is still rejected while that Session is busy. Pedelec does not provide filesystem-level locking, snapshots, transactions, or conflict resolution between concurrent Workspace actors. Applications are responsible for coordinating shared file access when required.
 
-Session `skills.denoModules` belong to the Session/Thread that declares them and are available only to Agent-side `pedelec-deno` execution for that Thread. Workspace runs accept the same Vite-prepared declarations explicitly:
+Session `skills.runtimeModules` belong to the Session/Thread that declares them and are available only to Agent-side `pedelec-ts-runtime` execution for that Thread. Workspace runs accept the same Vite-prepared declarations explicitly:
 
 ```ts
-const sceneTools = defineDenoModule({
+const sceneTools = defineRuntimeModule({
   name: "scene-tools",
   entry: "./deno/scene-tools.ts",
 });
 
 const result = await workspace.run(
   `import { buildScene } from "scene-tools";\nawait buildScene();`,
-  { denoModules: [sceneTools] },
+  { runtimeModules: [sceneTools] },
 );
 ```
 
-`workspace.run()` does not inherit any Session Deno Modules, and Sessions do not inherit modules used by Workspace runs. The Vite-prepared package is cached privately per Workspace and authorized SDK origin; each run receives an import map containing exactly its requested names. A ready module name is immutable for the lifetime of the Core process, and Workspace-run modules never appear in Agent Host Context. The private Workspace-run cache is reset when Core restarts; project files, assets, and Thread module snapshots are preserved.
+`workspace.run()` does not inherit any Session Runtime Modules, and Sessions do not inherit modules used by Workspace runs. The Vite-prepared package is cached privately per Workspace and authorized SDK origin; each run receives an import map containing exactly its requested names. A ready module name is immutable for the lifetime of the Core process, and Workspace-run modules never appear in Agent Host Context. The private Workspace-run cache is reset when Core restarts; project files, assets, and Thread module snapshots are preserved.
 
 The Workspace handle outlives an individual Session conceptually. Ending a Session does not close or delete a custom Workspace, and Pedelec does not delete it during app cleanup. Managed Workspaces remain under Desktop cleanup ownership and are not promised to disappear immediately when a Thread ends. The browser capability is runtime-scoped; reopen the custom Workspace after a Desktop/Core restart when necessary. `pedelec.resumeSession(sessionId)` returns a Session that already includes `session.workspace`; the application does not need to call `openWorkspace()` separately. Same-handle `session.resume()` preserves the existing Workspace handle, subject to the existing Core/thread and transport caveats.
 
@@ -449,7 +449,7 @@ const modelSession = await pedelec.createSession({
 
 Model-only requests are valid and use the provider's default effort behavior. `effort` requires `model`; `model` cannot be combined with `effortLevel`. The SDK does not expose or maintain a model catalog, and it does not translate the identifier into provider CLI flags. Model validity, effort support, and account entitlement remain provider-dependent, so an invalid or unavailable configuration may fail when the provider starts.
 
-Explicit model requests require an `explicitModelConfigApplied` acknowledgment from Core before the SDK exposes the session or starts Deno Module setup. If the connected Extension/Desktop is too old to provide that acknowledgment, the SDK aborts the newly created setup and reports a compatibility error instead of silently using a different configuration.
+Explicit model requests require an `explicitModelConfigApplied` acknowledgment from Core before the SDK exposes the session or starts Runtime Module setup. If the connected Extension/Desktop is too old to provide that acknowledgment, the SDK aborts the newly created setup and reports a compatibility error instead of silently using a different configuration.
 
 Currently supported provider codes in the SDK:
 
@@ -465,3 +465,29 @@ Currently supported provider codes in the SDK:
 Ollama sessions are executed by the bundled `pedelec-agent`. In profile mode, the selected Ollama effort profile must contain a model; otherwise Core returns `MODEL_REQUIRED`. In explicit model mode, `{ model }` supplies the model directly. Ollama currently does not accept an explicit `effort`. Low and high profiles are optional, but there is no fallback between profiles.
 
 `getSettings()` returns only `{ defaultProvider }`. It never exposes provider settings, effort arguments, credentials, or model names.
+
+
+## Explicit Full Runtime Access
+
+Sandbox is the default. Full Access requires three separate conditions: an Instance created with `runtimeFullAccess: true`, explicit user approval of both **Allow Agent Sessions** and **Allow Full Runtime Access** in the Extension, and `runtimeFullAccess: true` on session creation.
+
+The first `createSession()` automatically opens the approval Popup when required grants are missing. Choosing only Agent Sessions leaves a Full Instance incomplete and rejects either Session mode with `CREATE_SESSION_NOT_APPROVED`. `getApprovalStatus()` and `checkAvailability()` only read approval state.
+
+```ts
+const privileged = new Pedelec({ runtimeFullAccess: true });
+// After the user explicitly grants both permissions in the Extension:
+const sandbox = await privileged.createSession({ runtimeFullAccess: false });
+const full = await privileged.createSession({ runtimeFullAccess: true });
+```
+
+Review the Extension permissions before creating sessions. An Instance requesting Full Access cannot create any session with only the Agent Sessions grant, including a Sandbox session. A standard Instance cannot request a Full Access session, even if another Instance on the same Origin has permission. Ordinary Origin approval never substitutes for the Full Access grant; the Popup offers an additional permission review with Full Access unchecked by default. `getApprovalStatus()` only reads status and does not open that review.
+
+The Thread mode is fixed at creation and preserved on resume. Instances on the same Origin and Threads in the same Workspace retain their own requested modes. `workspace.run()` independently defaults to Sandbox. With a Full Instance and both Extension grants, `workspace.run(script, { runtimeFullAccess: true })` selects Full Access for that run only; no Session is required. Provider sandbox settings are unchanged. Full Access changes the TypeScript Runtime's OS permissions only. Revoking the Full Access grant rejects subsequent high-privilege execution and attempts to cancel affected running processes; unrelated Origins retain their grants.
+
+Upgrade the SDK, Extension, and Desktop together when using Full Access. Missing mode acknowledgment is an error, never a successful downgrade. See [Error Codes](https://kaoruisaac.github.io/pedelec/reference/error-codes/) for authorization and protocol failures.
+
+## Runtime compatibility
+
+New code uses `defineRuntimeModule`, `RuntimeModuleDefinition`, and `runtimeModules`. `defineDenoModule`, `DenoModuleDefinition`, and `denoModules` remain supported deprecated aliases. Never pass both module fields in one options object (`INVALID_INPUT`). `pedelec-ts-runtime --thread-id <id> run scripts/task.ts` and stdin `run -` are the standard CLI; `pedelec-deno` is a legal legacy alias with identical behavior. Actual `Deno.*` APIs, `DENO_DIR`, Deno flags, and `DENO_*` error codes retain their existing meanings.
+
+A Full Access Workspace run uses the same host permissions as a Full Access Session, including network, host environment, subprocesses and files outside the Workspace. Revoking Full Runtime Access cancels affected running Full Access executions. A standard Instance cannot request it. Older peers may omit the Sandbox acknowledgment, but a Full Access request fails unless the connected Extension and Desktop confirm the requested mode.

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 export type PedelecOptions = {
+    runtimeFullAccess?: boolean;
     bridgeTimeoutMs?: number;
 };
 export type ProviderCode = "codex" | "antigravity" | "opencode" | "cursor" | "claude" | "ollama";
@@ -32,14 +33,16 @@ export type ProviderArtifact = {
     providerArtifactId?: string;
     toolCallId?: string;
 };
-export type DenoModuleDefinition<TName extends string = string> = {
+export type RuntimeModuleDefinition<TName extends string = string> = {
     name: TName;
     description?: string;
     entry: string;
     usage?: string;
     preferStdinExecution?: boolean;
 };
-type AgentDenoModuleDefinition<TName extends string = string> = DenoModuleDefinition<TName> & {
+/** @deprecated Use RuntimeModuleDefinition. */
+export type DenoModuleDefinition<TName extends string = string> = RuntimeModuleDefinition<TName>;
+type AgentRuntimeModuleDefinition<TName extends string = string> = RuntimeModuleDefinition<TName> & {
     description: string;
     usage: string;
 };
@@ -99,7 +102,9 @@ export type ToolDefinition<TArgs = unknown, TResult = unknown, TName extends str
 export type SkillsInput<TTools extends readonly ToolDefinition[] = readonly ToolDefinition[]> = {
     guidance: string;
     tools: TTools;
-    denoModules?: readonly AgentDenoModuleDefinition[];
+    runtimeModules?: readonly AgentRuntimeModuleDefinition[];
+    /** @deprecated Use runtimeModules. */
+    denoModules?: readonly AgentRuntimeModuleDefinition[];
 };
 export type WebMcpSkillsInput<TTools extends readonly ToolDefinition[] = readonly ToolDefinition[]> = {
     tools: TTools;
@@ -118,7 +123,7 @@ export type SerializableToolManifest = {
     argsSchema: ToolArgsSchema;
     timeoutMs?: number;
 };
-type SerializableDenoModuleManifest = {
+type SerializableRuntimeModuleManifest = {
     name: string;
     description: string;
     usage: string;
@@ -127,10 +132,15 @@ type SerializableDenoModuleManifest = {
 export type SerializableSkillsManifest = {
     guidance: string;
     tools: SerializableToolManifest[];
-    denoModules?: SerializableDenoModuleManifest[];
+    runtimeModules?: SerializableRuntimeModuleManifest[];
+    /** @deprecated Use runtimeModules. Legacy wire field. */
+    denoModules?: SerializableRuntimeModuleManifest[];
 };
 export type WorkspaceRunOptions = {
     timeoutMs?: number;
+    runtimeFullAccess?: boolean;
+    runtimeModules?: readonly RuntimeModuleDefinition[];
+    /** @deprecated Use runtimeModules. */
     denoModules?: readonly DenoModuleDefinition[];
 };
 export type WorkspaceRunResult = {
@@ -141,6 +151,7 @@ export type WorkspaceRunResult = {
     stderrTruncated: boolean;
 };
 type CreateSessionSharedInput<TTools extends readonly ToolDefinition[] = readonly ToolDefinition[]> = {
+    runtimeFullAccess?: boolean;
     skills?: SkillsInput<TTools>;
     autoEndOnDisconnect?: boolean;
 };
@@ -170,6 +181,8 @@ export type PedelecSettings = {
     defaultProvider: ProviderCode | null;
 };
 export type ApprovalStatus = {
+    /** Explicit Full Runtime Access user grant reported by the Extension. */
+    runtimeFullAccessApproved?: boolean;
     installed: boolean;
     approved: boolean;
     origin: string | null;
@@ -356,8 +369,10 @@ type ErrorHandler = (error: PedelecError, ctx: ErrorEventContext) => void;
 type StatusHandler = (status: PedelecSessionStatus, ctx: StatusEventContext) => void;
 type EndedHandler = (ctx: EndedEventContext) => void;
 export declare function defineTool<TArgs = unknown, TResult = unknown, const TName extends string = string>(tool: ToolDefinition<TArgs, TResult, TName>): ToolDefinition<TArgs, TResult, TName>;
-export declare function defineDenoModule<const TModule extends DenoModuleDefinition>(module: TModule): TModule;
-type PreparedWorkspaceDenoModule = {
+export declare function defineRuntimeModule<const TModule extends RuntimeModuleDefinition>(module: TModule): TModule;
+/** @deprecated Use defineRuntimeModule. */
+export declare const defineDenoModule: typeof defineRuntimeModule;
+type PreparedWorkspaceRuntimeModule = {
     name: string;
     runtimeSource: string;
     typesSource: string;
@@ -388,6 +403,9 @@ export declare class Pedelec {
     private readonly pageWindow;
     private readonly channelId;
     private readonly bridgeTimeoutMs;
+    private readonly runtimeFullAccess;
+    /** @internal */
+    get runtimeFullAccessInternal(): boolean;
     private readonly pendingRequests;
     private readonly sessions;
     private readonly lastSeqBySession;
@@ -403,7 +421,7 @@ export declare class Pedelec {
     createSessionInternal<const TTools extends readonly ToolDefinition[]>(input?: CreateSessionInput<TTools>, workspace?: PedelecWorkspace): Promise<PedelecSession<ToolNameOf<TTools>>>;
     private uploadDenoModuleArtifact;
     /** @internal */
-    uploadWorkspaceDenoModuleArtifact(workspaceId: string, module: PreparedWorkspaceDenoModule): Promise<void>;
+    uploadWorkspaceDenoModuleArtifact(workspaceId: string, module: PreparedWorkspaceRuntimeModule): Promise<void>;
     private uploadDenoModuleArtifactWithTicket;
     private abortSessionSetup;
     private completeSessionSetup;

package/dist/index.js

@@ -149,9 +149,23 @@ const WEBMCP_TOOL_NAME_MAX_LENGTH = 128;
 export function defineTool(tool) {
     return tool;
 }
-export function defineDenoModule(module) {
+export function defineRuntimeModule(module) {
     return module;
 }
+/** @deprecated Use defineRuntimeModule. */
+export const defineDenoModule = defineRuntimeModule;
+function resolveRuntimeModules(options) {
+    if ("runtimeModules" in options && "denoModules" in options) {
+        throw makeError("INVALID_INPUT", "runtimeModules and denoModules cannot be combined");
+    }
+    return "runtimeModules" in options ? options.runtimeModules : options.denoModules;
+}
+function normalizeRuntimeFullAccess(value) {
+    if (value !== undefined && typeof value !== "boolean") {
+        throw makeError("INVALID_INPUT", "runtimeFullAccess must be a boolean");
+    }
+    return value === true;
+}
 function normalizeWorkspaceDenoModules(value) {
     if (value === undefined)
         return [];
@@ -254,7 +268,7 @@ function normalizeToolDefinitions(value, options = {}) {
 }
 function normalizeSkillsInput(value) {
     if (value === undefined)
-        return { handlers: new Map(), denoModules: [] };
+        return { handlers: new Map(), runtimeModules: [] };
     if (!value || typeof value !== "object" || Array.isArray(value)) {
         throw makeError("INVALID_INPUT", "skills must be an object");
     }
@@ -265,12 +279,13 @@ function normalizeSkillsInput(value) {
     if (!Array.isArray(skills.tools)) {
         throw makeError("INVALID_INPUT", "skills.tools must be an array");
     }
-    if (skills.denoModules !== undefined && !Array.isArray(skills.denoModules)) {
+    const modules = resolveRuntimeModules(skills);
+    if (modules !== undefined && !Array.isArray(modules)) {
         throw makeError("INVALID_INPUT", "skills.denoModules must be an array");
     }
     const { tools, handlers } = normalizeToolDefinitions(skills.tools);
-    const seenDenoModuleNames = new Set();
-    const denoModules = (skills.denoModules ?? []).map((module, index) => {
+    const seenRuntimeModuleNames = new Set();
+    const runtimeModules = (modules ?? []).map((module, index) => {
         if (!module || typeof module !== "object" || Array.isArray(module)) {
             throw makeError("INVALID_INPUT", "skills.denoModules entries must be objects", { index });
         }
@@ -281,12 +296,12 @@ function normalizeSkillsInput(value) {
                 moduleName: rawModule.name,
             });
         }
-        if (seenDenoModuleNames.has(rawModule.name)) {
+        if (seenRuntimeModuleNames.has(rawModule.name)) {
             throw makeError("INVALID_INPUT", "duplicate Deno Module name", {
                 moduleName: rawModule.name,
             });
         }
-        seenDenoModuleNames.add(rawModule.name);
+        seenRuntimeModuleNames.add(rawModule.name);
         if (typeof rawModule.description !== "string" || rawModule.description.trim().length === 0) {
             throw makeError("INVALID_INPUT", "Deno Module description must be a non-empty string", {
                 moduleName: rawModule.name,
@@ -324,9 +339,10 @@ function normalizeSkillsInput(value) {
         manifest: {
             guidance: skills.guidance,
             tools,
-            ...(denoModules.length > 0
+            ...(runtimeModules.length > 0
                 ? {
-                    denoModules: denoModules.map(({ name, description, usage, preferStdinExecution }) => ({
+                    // Legacy Extension wire field; normalized data uses Runtime names.
+                    denoModules: runtimeModules.map(({ name, description, usage, preferStdinExecution }) => ({
                         name,
                         description,
                         usage,
@@ -336,7 +352,7 @@ function normalizeSkillsInput(value) {
                 : {}),
         },
         handlers,
-        denoModules: denoModules.map(({ name, artifact }) => ({
+        runtimeModules: runtimeModules.map(({ name, artifact }) => ({
             name,
             runtimeSource: artifact.runtimeSource,
             typesSource: artifact.typesSource,
@@ -477,8 +493,13 @@ export class PedelecWorkspace {
             return Promise.reject(makeError("INVALID_INPUT", "timeoutMs must be a positive integer"));
         }
         let modules;
+        let runtimeFullAccess;
         try {
-            modules = normalizeWorkspaceDenoModules(options.denoModules);
+            runtimeFullAccess = normalizeRuntimeFullAccess(options.runtimeFullAccess);
+            if (runtimeFullAccess && !this.client.runtimeFullAccessInternal) {
+                throw makeError("INVALID_INPUT", "Workspace runtimeFullAccess requires an Instance with runtimeFullAccess enabled");
+            }
+            modules = normalizeWorkspaceDenoModules(resolveRuntimeModules(options));
         }
         catch (error) {
             return Promise.reject(error);
@@ -502,9 +523,10 @@ export class PedelecWorkspace {
             return this.client.requestWithOptions("workspace_run", {
                 workspaceId: this.workspaceId,
                 script,
+                ...(options.runtimeFullAccess === undefined ? {} : { runtimeFullAccess }),
                 ...(timeoutMs === undefined ? {} : { timeoutMs }),
                 ...(modules.length === 0 ? {} : { denoModules: modules.map(({ name }) => name) }),
-            }, { timeoutMs: null }).then(normalizeWorkspaceRunResponse);
+            }, { timeoutMs: null }).then((value) => normalizeWorkspaceRunResponse(value, runtimeFullAccess));
         };
         return run();
     }
@@ -534,6 +556,9 @@ export class Pedelec {
     pageWindow;
     channelId;
     bridgeTimeoutMs;
+    runtimeFullAccess;
+    /** @internal */
+    get runtimeFullAccessInternal() { return this.runtimeFullAccess; }
     pendingRequests = new Map();
     sessions = new Map();
     lastSeqBySession = new Map();
@@ -542,6 +567,7 @@ export class Pedelec {
     pageActivityListenersAttached = false;
     lastReportedPageActive = null;
     constructor(options = {}) {
+        this.runtimeFullAccess = normalizeRuntimeFullAccess(options.runtimeFullAccess);
         this.pageWindow = typeof window === "undefined" ? null : window;
         this.channelId = createChannelId();
         this.bridgeTimeoutMs = Math.max(1, options.bridgeTimeoutMs ?? DEFAULT_BRIDGE_TIMEOUT_MS);
@@ -591,10 +617,17 @@ export class Pedelec {
     }
     /** @internal */
     async createSessionInternal(input = {}, workspace) {
+        const runtimeFullAccess = normalizeRuntimeFullAccess(input?.runtimeFullAccess);
+        if (runtimeFullAccess && !this.runtimeFullAccess) {
+            throw makeError("INVALID_INPUT", "Session runtimeFullAccess requires an Instance with runtimeFullAccess enabled");
+        }
+        // Admission belongs to the Extension: create_session must reach its pending
+        // approval queue so the first Full Instance request can open the Popup.
         const resolvedOrPromise = this.resolveCreateSessionInput(input);
         const resolvedInput = resolvedOrPromise instanceof Promise ? await resolvedOrPromise : resolvedOrPromise;
         const result = await this.request("create_session", {
             input: {
+                runtimeFullAccess,
                 provider: resolvedInput.provider,
                 model: resolvedInput.model,
                 effort: resolvedInput.effort,
@@ -604,6 +637,14 @@ export class Pedelec {
                 autoEndOnDisconnect: resolvedInput.autoEndOnDisconnect,
             },
         });
+        // Check the raw acknowledgment before other response validation so a known
+        // thread can still be cleaned up when a peer returns an invalid mode flag.
+        if (runtimeFullAccess && (!isPlainObject(result) || result.runtimeFullAccessApplied !== true)) {
+            if (isPlainObject(result) && typeof result.sessionId === "string" && result.sessionId.trim()) {
+                await this.abortSessionSetup(result.sessionId);
+            }
+            throw makeError("SDK_PROTOCOL_ERROR", "The connected Pedelec Extension/Desktop did not confirm Full Runtime Access", { feature: "runtimeFullAccess" });
+        }
         const normalizedResult = normalizeCreateSessionResponse(result);
         if (workspace && normalizedResult.workspace.workspaceId !== workspace.workspaceIdInternal) {
             throw makeError("SDK_PROTOCOL_ERROR", "create_session response returned a different Workspace", {
@@ -617,10 +658,10 @@ export class Pedelec {
             throw error;
         }
         try {
-            for (const module of resolvedInput.denoModules) {
+            for (const module of resolvedInput.runtimeModules) {
                 await this.uploadDenoModuleArtifact(normalizedResult.sessionId, module);
             }
-            if (resolvedInput.denoModules.length > 0) {
+            if (resolvedInput.runtimeModules.length > 0) {
                 await this.completeSessionSetup(normalizedResult.sessionId);
             }
         }
@@ -730,7 +771,7 @@ export class Pedelec {
     async getApprovalStatus() {
         try {
             const result = await this.request("get_approval_status");
-            return result;
+            return { ...result, approved: result.approved === true && (!this.runtimeFullAccess || result.runtimeFullAccessApproved === true) };
         }
         catch (err) {
             const error = normalizeError(err, "EXTENSION_UNAVAILABLE", "Pedelec extension is unavailable.");
@@ -885,7 +926,7 @@ export class Pedelec {
     }
     postSdkHello(port) {
         try {
-            port.postMessage({ type: SDK_HELLO_MESSAGE_TYPE, sdkVersion: SDK_VERSION });
+            port.postMessage({ type: SDK_HELLO_MESSAGE_TYPE, sdkVersion: SDK_VERSION, runtimeFullAccess: this.runtimeFullAccess });
         }
         catch (err) {
             const error = normalizeError(err, "EXTENSION_DISCONNECTED", "Pedelec extension disconnected.");
@@ -927,7 +968,7 @@ export class Pedelec {
                 effort,
                 skills: normalizedSkills.manifest,
                 inlineToolHandlers: normalizedSkills.handlers,
-                denoModules: normalizedSkills.denoModules,
+                runtimeModules: normalizedSkills.runtimeModules,
                 autoEndOnDisconnect,
             };
         }
@@ -948,7 +989,7 @@ export class Pedelec {
             effortLevel,
             skills: normalizedSkills.manifest,
             inlineToolHandlers: normalizedSkills.handlers,
-            denoModules: normalizedSkills.denoModules,
+            runtimeModules: normalizedSkills.runtimeModules,
             autoEndOnDisconnect,
         };
     }
@@ -1017,7 +1058,7 @@ export class Pedelec {
             effortLevel,
             skills: normalizedSkills.manifest,
             inlineToolHandlers: normalizedSkills.handlers,
-            denoModules: normalizedSkills.denoModules,
+            runtimeModules: normalizedSkills.runtimeModules,
             autoEndOnDisconnect,
         };
     }
@@ -2098,12 +2139,17 @@ function normalizeWorkspaceDenoModulePrepareResponse(value, requestedNames) {
     }
     return value.missingModuleNames;
 }
-function normalizeWorkspaceRunResponse(value) {
+function normalizeWorkspaceRunResponse(value, runtimeFullAccess) {
     if (!isPlainObject(value) || !Number.isInteger(value.exitCode) || typeof value.stdout !== "string" ||
         typeof value.stderr !== "string" || typeof value.stdoutTruncated !== "boolean" ||
         typeof value.stderrTruncated !== "boolean") {
         throw makeError("SDK_PROTOCOL_ERROR", "workspace_run response had an invalid shape");
     }
+    if ((runtimeFullAccess && value.runtimeFullAccessApplied !== true) ||
+        (!runtimeFullAccess && value.runtimeFullAccessApplied === true) ||
+        (value.runtimeFullAccessApplied !== undefined && typeof value.runtimeFullAccessApplied !== "boolean")) {
+        throw makeError("SDK_PROTOCOL_ERROR", "The connected Pedelec Extension/Desktop did not confirm the requested Runtime mode");
+    }
     return {
         exitCode: value.exitCode,
         stdout: value.stdout,

package/dist/index.type-test.js

@@ -1,4 +1,4 @@
-import { Pedelec, defineTool, defineDenoModule, } from "./index";
+import { Pedelec, defineTool, defineDenoModule, defineRuntimeModule, } from "./index";
 const spriteTools = defineDenoModule({
     name: "sprite-tools",
     description: "Sprite authoring utilities.",
@@ -347,3 +347,24 @@ const baseContext = {
     source: "sdk",
 };
 void baseContext;
+const runtimeTools = defineRuntimeModule({
+    name: "runtime-tools", entry: "./helpers.ts", description: "Helpers", usage: 'import "runtime-tools";',
+});
+const runtimeName = runtimeTools.name;
+const runtimeDefinition = runtimeTools;
+void runtimeName;
+void runtimeDefinition;
+// @ts-expect-error Runtime Module entry is required
+defineRuntimeModule({ name: "missing-entry" });
+// @ts-expect-error Instance flag must be boolean
+new Pedelec({ runtimeFullAccess: "true" });
+async function runtimePublicContracts(workspace) {
+    const client = new Pedelec({ runtimeFullAccess: true });
+    await client.createSession({ runtimeFullAccess: true, skills: { guidance: "", tools: [], runtimeModules: [runtimeTools] } });
+    await client.createSession({ model: "model", runtimeFullAccess: true });
+    await workspace.createSession({ provider: "codex", runtimeFullAccess: true, skills: { guidance: "", tools: [], runtimeModules: [runtimeTools] } });
+    await workspace.run("", { runtimeModules: [runtimeTools] });
+    // @ts-expect-error Session flag must be boolean
+    await client.createSession({ runtimeFullAccess: 1 });
+}
+void runtimePublicContracts;

package/dist/version.generated.d.ts

@@ -1 +1 @@
-export declare const SDK_VERSION = "0.4.10";
+export declare const SDK_VERSION = "0.4.12";

package/dist/version.generated.js

@@ -1,2 +1,2 @@
 // Generated from sdk/package.json. Do not edit manually.
-export const SDK_VERSION = "0.4.10";
+export const SDK_VERSION = "0.4.12";

package/dist/vite.js

@@ -5,7 +5,7 @@ import * as ts from "typescript";
 import { build } from "vite";
 import { PREPARED_DENO_MODULE_ARTIFACT_PROPERTY, } from "./deno-module-internal.js";
 const PACKAGE_NAME = "@kaoruisaac/pedelec";
-const DEFINE_DENO_MODULE_NAME = "defineDenoModule";
+const DEFINE_RUNTIME_MODULE_NAMES = new Set(["defineRuntimeModule", "defineDenoModule"]);
 const ARTIFACT_HASH_VERSION = "pedelec-deno-module-artifact-v1";
 const SCRIPT_EXTENSIONS = new Set([".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs"]);
 const DECLARATION_LIKE_EXTENSIONS = new Set([".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs", ".d.ts", ".json"]);
@@ -913,10 +913,10 @@ function findDenoModuleImportNames(sourceFile) {
         if (!namedBindings || !ts.isNamedImports(namedBindings))
             continue;
         for (const element of namedBindings.elements) {
-            if (element.isTypeOnly || element.propertyName?.text !== DEFINE_DENO_MODULE_NAME && element.name.text !== DEFINE_DENO_MODULE_NAME)
+            if (element.isTypeOnly)
                 continue;
             const importedName = element.propertyName?.text ?? element.name.text;
-            if (importedName === DEFINE_DENO_MODULE_NAME)
+            if (DEFINE_RUNTIME_MODULE_NAMES.has(importedName))
                 names.add(element.name.text);
         }
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kaoruisaac/pedelec",
-  "version": "0.4.10",
+  "version": "0.4.12",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -49,7 +49,7 @@
   },
   "devDependencies": {
     "@types/node": "24.13.6",
-    "vite": "8.3.0",
-    "vitest": "4.1.11"
+    "vite": "^8.3.5",
+    "vitest": "^4.1.12"
   }
 }