@kaoruisaac/pedelec 0.4.3 → 0.4.5

package/README.md

@@ -233,6 +233,20 @@ 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.
 
+### Provider-generated assets
+
+When a supported provider generates an image or file, Pedelec imports it under `.pedelec-runtime/assets/provider-artifacts/` before notifying the application. `onArtifact()` receives metadata only; binary bytes and provider-private absolute paths are not included in the event. The public `artifact.path` works immediately with `readAsset()` and the same file is included by `listAssets()`.
+
+```ts
+const offArtifact = session.onArtifact(async (artifact) => {
+  if (artifact.kind !== "image") return;
+  const file = await session.readAsset(artifact.path, "file");
+  renderImage(file);
+});
+```
+
+Use `listAssets()` to discover files from earlier turns; registering an artifact handler does not replay history. Provider artifacts follow the existing per-file 100 MiB asset limit. Availability depends on the selected provider emitting a supported generated artifact, so not every provider or model can generate every artifact kind.
+
 ## Workspace
 
 Workspace is the filesystem root in which the Agent works. Pedelec stores its private runtime data under `<workspace>/.pedelec-runtime/`. There are two supported flows:
@@ -290,7 +304,7 @@ The default timeout is 60 seconds; `timeoutMs` must be a positive integer. The r
 
 `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.
 
-Several `workspace.run()` calls in one Workspace may execute concurrently. A Workspace run cannot start while any Session in that Workspace has an active Agent/provider operation. Conversely, a Session in that Workspace cannot begin `sendText()` or provider preparation while one or more Workspace runs are active. This rule is Workspace-wide, including operations started through another `PedelecSession` handle; conflicts reject with `WORKSPACE_BUSY`.
+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:
 

package/dist/index.d.ts

@@ -16,6 +16,21 @@ export type Asset = {
     sizeBytes: number;
     modifiedAt: number;
 };
+export type ProviderArtifactKind = "image" | "audio" | "video" | "file";
+export type ProviderArtifactSource = "image_generation" | "tool_result" | "provider_artifact";
+/** Metadata for a provider-generated file already materialized in Workspace assets. */
+export type ProviderArtifact = {
+    id: string;
+    provider: ProviderCode;
+    path: AssetPath;
+    name: string;
+    mimeType: string;
+    sizeBytes: number;
+    kind: ProviderArtifactKind;
+    source: ProviderArtifactSource;
+    providerArtifactId?: string;
+    toolCallId?: string;
+};
 export type DenoModuleDefinition<TName extends string = string> = {
     name: TName;
     description?: string;
@@ -197,6 +212,14 @@ export type ChatDeltaEventContext = PedelecEventContext & {
     turnStartedAt: number;
     eventReceivedAt: number;
 };
+export type ProviderArtifactEventContext = PedelecEventContext & {
+    type: "provider_artifact";
+    turnId: string;
+    turnStartedAt: number;
+    turnKind: "user";
+    eventReceivedAt: number;
+    source: "core";
+};
 export type ToolCallContext = PedelecEventContext & {
     type: "tool_call";
     toolRequestId: string;
@@ -230,6 +253,13 @@ type SessionEvent = {
     seq?: number;
     operationId?: string;
     text: string;
+} | {
+    type: "provider_artifact";
+    channelId: string;
+    sessionId: string;
+    seq?: number;
+    operationId: string;
+    artifact: unknown;
 } | {
     type: "status_changed";
     channelId: string;
@@ -309,6 +339,7 @@ type EventDispatchMeta = {
 };
 type ChatHandler = (text: string, ctx: ChatEventContext) => void;
 type ChatDeltaHandler = (text: string, ctx: ChatDeltaEventContext) => void;
+export type ProviderArtifactHandler = (artifact: ProviderArtifact, ctx: ProviderArtifactEventContext) => void;
 type GenericToolHandler<TToolName extends string = string> = (tool: TToolName, args: unknown, ctx: ToolCallContext) => unknown | Promise<unknown>;
 type ErrorHandler = (error: PedelecError, ctx: ErrorEventContext) => void;
 type StatusHandler = (status: PedelecSessionStatus, ctx: StatusEventContext) => void;
@@ -418,6 +449,7 @@ export declare class PedelecSession<TToolName extends string = string> {
     private readonly namedToolHandlers;
     private readonly chatHandlers;
     private readonly chatDeltaHandlers;
+    private readonly artifactHandlers;
     private readonly errorHandlers;
     private readonly statusHandlers;
     private readonly endedHandlers;
@@ -429,6 +461,7 @@ export declare class PedelecSession<TToolName extends string = string> {
     sendText(text: string): Promise<void>;
     onChat(handler: ChatHandler): () => void;
     onChatDelta(handler: ChatDeltaHandler): () => void;
+    onArtifact(handler: ProviderArtifactHandler): () => void;
     onTool(handler: GenericToolHandler<TToolName>): () => void;
     onTool<TArgs = unknown, TResult = unknown>(toolName: TToolName, handler: ToolSpecificHandler<TArgs, TResult>): () => void;
     uploadAsset(file: File): Promise<AssetPath>;
@@ -475,6 +508,7 @@ export declare class PedelecSession<TToolName extends string = string> {
     private createBaseContext;
     private createChatContext;
     private createChatDeltaContext;
+    private createProviderArtifactContext;
     private createToolCallContext;
     private createStatusContext;
     private createErrorContext;

package/dist/index.js

@@ -955,6 +955,7 @@ export class PedelecSession {
     namedToolHandlers = new Map();
     chatHandlers = new Set();
     chatDeltaHandlers = new Set();
+    artifactHandlers = new Set();
     errorHandlers = new Set();
     statusHandlers = new Set();
     endedHandlers = new Set();
@@ -1072,6 +1073,10 @@ export class PedelecSession {
         this.chatDeltaHandlers.add(handler);
         return () => this.chatDeltaHandlers.delete(handler);
     }
+    onArtifact(handler) {
+        this.artifactHandlers.add(handler);
+        return () => this.artifactHandlers.delete(handler);
+    }
     onTool(toolNameOrHandler, maybeHandler) {
         if (typeof toolNameOrHandler === "string") {
             const toolName = toolNameOrHandler;
@@ -1307,6 +1312,26 @@ export class PedelecSession {
             }
             return;
         }
+        if (event.type === "provider_artifact") {
+            let artifact;
+            try {
+                artifact = normalizeProviderArtifact(event.artifact);
+            }
+            catch (error) {
+                this.emitError(normalizeError(error, "SDK_PROTOCOL_ERROR", "provider_artifact event had an invalid payload"), {
+                    source: "sdk",
+                    eventReceivedAt: meta.eventReceivedAt,
+                });
+                return;
+            }
+            const turn = this.requireOperationTurn(event.operationId, "provider_artifact", meta);
+            if (!turn || turn.kind === "prepare")
+                return;
+            for (const handler of this.artifactHandlers) {
+                handler(artifact, this.createProviderArtifactContext(meta, turn));
+            }
+            return;
+        }
         if (event.type === "status_changed") {
             if (event.operationId && !this.matchesActiveOperation(event.operationId))
                 return;
@@ -1690,6 +1715,17 @@ export class PedelecSession {
             source: "core",
         };
     }
+    createProviderArtifactContext(meta, turn) {
+        return {
+            ...this.createBaseContext(meta, turn),
+            type: "provider_artifact",
+            turnId: turn.turnId,
+            turnStartedAt: turn.turnStartedAt,
+            turnKind: "user",
+            eventReceivedAt: meta.eventReceivedAt ?? Date.now(),
+            source: "core",
+        };
+    }
     createToolCallContext(event, meta, turn) {
         return {
             ...this.createBaseContext(meta, turn),
@@ -1726,6 +1762,7 @@ export class PedelecSession {
 function isSessionEvent(message) {
     return (message.type === "chat_delta" ||
         message.type === "chat_message" ||
+        message.type === "provider_artifact" ||
         message.type === "status_changed" ||
         message.type === "tool_call" ||
         message.type === "operation_completed" ||
@@ -1746,6 +1783,39 @@ function isEffort(value) {
 function isPlainObject(value) {
     return !!value && typeof value === "object" && !Array.isArray(value);
 }
+function normalizeProviderArtifact(value) {
+    if (!isPlainObject(value)) {
+        throw makeError("SDK_PROTOCOL_ERROR", "provider_artifact event had an invalid artifact object");
+    }
+    const { id, provider, path, name, mimeType, sizeBytes, kind, source } = value;
+    const optionalIdIsValid = (key) => !(key in value) || (typeof value[key] === "string" && value[key].trim().length > 0);
+    const validName = typeof name === "string" && name.trim().length > 0 &&
+        !name.includes("/") && !name.includes("\\") && name !== "." && name !== "..";
+    // Core persists a collision-safe basename (`<artifact-id>-<name>`). Logical `name`
+    // and public `path` are validated independently.
+    const validPath = isValidAssetPath(path);
+    const validSize = typeof sizeBytes === "number" && Number.isFinite(sizeBytes) &&
+        Number.isInteger(sizeBytes) && sizeBytes >= 0;
+    const validKind = kind === "image" || kind === "audio" || kind === "video" || kind === "file";
+    const validSource = source === "image_generation" || source === "tool_result" || source === "provider_artifact";
+    if (typeof id !== "string" || id.trim().length === 0 || !isProviderCode(provider) || !validPath ||
+        !validName || typeof mimeType !== "string" || mimeType.trim().length === 0 || !validSize ||
+        !validKind || !validSource || !optionalIdIsValid("providerArtifactId") || !optionalIdIsValid("toolCallId")) {
+        throw makeError("SDK_PROTOCOL_ERROR", "provider_artifact event had an invalid artifact payload");
+    }
+    return {
+        id,
+        provider,
+        path,
+        name,
+        mimeType,
+        sizeBytes,
+        kind,
+        source,
+        ...(value.providerArtifactId === undefined ? {} : { providerArtifactId: value.providerArtifactId }),
+        ...(value.toolCallId === undefined ? {} : { toolCallId: value.toolCallId }),
+    };
+}
 function normalizePedelecSettings(value) {
     if (!isPlainObject(value) || (value.defaultProvider !== null && !isProviderCode(value.defaultProvider))) {
         throw makeError("SDK_PROTOCOL_ERROR", "get_settings response had invalid shape");

package/dist/index.type-test.js

@@ -92,6 +92,18 @@ async function typedOnToolNameFromCreateSession() {
         void deltaType;
         void chatDeltaCtx;
     });
+    session.onArtifact((artifact, ctx) => {
+        const publicArtifact = artifact;
+        const artifactContext = ctx;
+        const turnKind = ctx.turnKind;
+        const origin = ctx.source;
+        const file = session.readAsset(artifact.path, "file");
+        void publicArtifact;
+        void artifactContext;
+        void turnKind;
+        void origin;
+        void file;
+    });
     session.onStatus((_status, ctx) => {
         const statusCtx = ctx;
         const previous = ctx.previousStatus;

package/dist/version.generated.d.ts

@@ -1 +1 @@
-export declare const SDK_VERSION = "0.4.3";
+export declare const SDK_VERSION = "0.4.5";

package/dist/version.generated.js

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

package/package.json

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