@pikku/core 0.12.18 → 0.12.20

package/CHANGELOG.md

@@ -1,3 +1,79 @@
+## 0.12.20
+
+### Patch Changes
+
+- 18acebe: feat(core): scope bare `rpc.invoke()` calls to the caller's addon package
+
+  Addon functions calling `rpc.invoke('foo')` (bare, no colon) previously only
+  resolved against root RPC meta and threw `RPCNotFoundError` for the addon's
+  own functions, forcing authors to prefix every call with their consumer-facing
+  namespace (`'cli:foo'`) — which couples the addon to its caller's `wireAddon({ name })`.
+
+  `ContextAwareRPCService` now carries an optional `packageName` passed through
+  from `runPikkuFunc` via `getContextRPCService`. For bare names from inside an
+  addon, resolution first checks the caller's package function meta, then falls
+  back to root. Applies to both `rpc.invoke()` and `rpc.rpcWithWire()`. Explicit
+  namespaced calls (`'stripe:createCharge'`) and root-namespace calls are unchanged.
+
+- 66d1b4f: feat(content)!: bucket-aware ContentService with typed object args
+
+  BREAKING CHANGE: All `ContentService` methods now take object args with a
+  required `bucket` field. The interface is generic over `TBucket extends string`
+  so callers can constrain bucket names to a typed union.
+
+  Migration:
+
+  ```ts
+  // Before
+  content.getUploadURL(fileKey, contentType)
+  content.signContentKey(key, expiresAt)
+  content.writeFile(assetKey, stream)
+  content.readFile(assetKey)
+  content.deleteFile(assetKey)
+
+  // After
+  content.getUploadURL({ bucket, fileKey, contentType })
+  content.signContentKey({ bucket, contentKey, dateLessThan: expiresAt })
+  content.writeFile({ bucket, key, stream })
+  content.readFile({ bucket, key })
+  content.deleteFile({ bucket, key })
+  ```
+
+  - New exported types: `SignContentKeyArgs`, `SignURLArgs`, `GetUploadURLArgs`,
+    `UploadURLResult`, `BucketKeyArgs`, `WriteFileArgs`, `CopyFileArgs`.
+  - `LocalContent` stores objects under `<base>/<bucket>/<key>`.
+  - `S3Content` and `B2Content` treat the logical bucket as a key prefix within
+    the configured underlying storage bucket.
+  - `workflow-screenshot` addon takes `bucket?` / `key?` input; default bucket
+    resolved from `PIKKU_WORKFLOW_SCREENSHOT_BUCKET` variable, no hardcoded
+    fallback.
+
+- 3e35b99: feat(core): scope bare workflow names to the caller's addon package
+
+  Parallel to the RPC scoping fix for addon functions. Addon code calling
+  `services.workflowService.runToCompletion('myWorkflow', ...)` (bare name,
+  no colon) previously missed workflows registered under the addon's package
+  scope and threw `WorkflowNotFoundError`, forcing authors to hard-code
+  the consumer-facing namespace (`'cli:myWorkflow'`) — which couples the
+  addon to its caller's `wireAddon({ name })`.
+
+  `getOrCreatePackageSingletonServices` in the function-runner now wraps
+  the package's `workflowService` with a Proxy that auto-prefixes bare
+  workflow names on `startWorkflow` / `runToCompletion` with the addon's
+  consumer-defined namespace (looked up from `pikkuState(null, 'addons',
+'packages')`). Explicit `'ns:name'` calls and root-namespace workflows
+  are unchanged.
+
+## 0.12.19
+
+### Patch Changes
+
+- b9ed73e: Add deterministic workflow planned-step metadata support and SSE init stream payload generation.
+  - Persist `deterministic` and `plannedSteps` on workflow runs in core and service adapters.
+  - Expose planned-step metadata on workflow run status responses.
+  - Emit an initial `type: 'init'` SSE event for deterministic workflow streams before incremental updates.
+  - Add CLI tests covering serialized stream route output for init/update/done event behavior.
+
 ## 0.12.4
 
 ## 0.12.18
@@ -5,7 +81,6 @@
 ### Patch Changes
 
 - 311c0c4: Unify session persistence through SessionStore, remove session blob from ChannelStore
-
   - PikkuSessionService now persists sessions via SessionStore on set()/clear() instead of every function call
   - ChannelStore no longer stores session data — maps channelId to pikkuUserId only
   - ChannelStore API: setUserSession/getChannelAndSession replaced with setPikkuUserId/getChannel
@@ -50,14 +125,12 @@
 ### Patch Changes
 
 - 9e8605f: Add Workers for Platforms dispatch namespace support and AI agent fixes.
-
   - deploy-cloudflare: Thread dispatchNamespace through deploy pipeline, reads CF_DISPATCH_NAMESPACE env var
   - core: Fix auth-gated tools visible to unauthenticated sessions (null session now hides permission-gated items)
   - core: Recursive null stripping in AI agent tool call resume path
   - ai-vercel: Handle anyOf/oneOf/array types when making optional fields nullable for strict providers
 
 - 624097e: Add deploy pipeline with provider-agnostic architecture
-
   - Add MetaService with explicit typed API, absorb WiringService reads
   - Add deployment service, traceId propagation, scoped logger
   - Rewrite analyzer: one function = one worker, gateways dispatch via RPC
@@ -80,7 +153,6 @@
 ### Patch Changes
 
 - f85c234: Add unified credential system with per-user OAuth and AI agent pre-flight checks
-
   - Unified CredentialService with lazy loading per user via pikkuUserId
   - wire.getCredential() for typed single credential lookup
   - MissingCredentialError with structured payload for client-side connect flows
@@ -187,7 +259,6 @@
 - 7d369f3: Fix agent sub-agent tool execution failures: use UUID for sub-agent thread IDs (was exceeding varchar(36) DB column), and synthesize error results for failed tool calls in non-streaming run() to prevent "Tool result is missing" cascading errors.
 - 508a796: Fix MCP server not exposing addon tools: resolve namespaced function IDs in MCP runner, load addon schemas after schema generation, and use resolveFunctionMeta for MCP JSON serialization
 - ffe83af: Add Web Response passthrough support and fix close() flushing
-
   - HTTP runner detects when a function returns a Web `Response` object and applies it directly via `applyWebResponse()`, enabling seamless integration with libraries like Auth.js
   - Add `send()` method to `PikkuHTTPResponse` for setting body without Content-Type headers
   - Add `headers()` method to `PikkuHTTPRequest` for retrieving all headers as a record
@@ -201,7 +272,6 @@
 ### Patch Changes
 
 - cc4c9e9: Add gateway meta-wiring for messaging platforms:
-
   - New `wireGateway()` API with three transport types: webhook, websocket, listener
   - `GatewayAdapter` interface for platform-specific parse/send logic
   - `PikkuGateway` wire object (`wire.gateway`) with senderId, platform, and send()
@@ -218,7 +288,6 @@
 
 - 62a8725: Rename 'external' to 'addon' throughout the codebase. All types, functions, config keys, and CLI options previously named `external` or `External` are now named `addon` or `Addon` (e.g. `ExternalPackageConfig` → `AddonConfig`, `externalPackages` → `addons`, `function-external` → `function-addon`).
 - a3bdb0d: Add AI middleware hooks for per-tool-call lifecycle and post-step observability:
-
   - `beforeToolCall` / `afterToolCall`: per-tool-call hooks for logging, caching, input sanitization, and result transformation
   - `afterStep`: post-step observation hook with full step context (text, toolCalls, toolResults, usage, finishReason)
   - `onError`: error-specific hook for alerting and diagnostics (non-throwing, won't affect error flow)
@@ -317,18 +386,15 @@
 - ea652dc: Refactor channel middleware handling and add lifecycle middleware support
 
   **Breaking Changes:**
-
   - Improved middleware resolution for channel message handlers to properly combine channel-level and message-level middleware
   - Fixed cache key collisions when multiple message handlers use the same function
 
   **New Features:**
-
   - Add `runChannelLifecycleWithMiddleware` helper in `channel-common.ts` for consistent lifecycle function execution
   - Support middleware on `onConnect` and `onDisconnect` lifecycle functions
   - Channel-level middleware now properly applies to all messages in the channel
 
   **Bug Fixes:**
-
   - Fix middleware ordering: channel middleware → message middleware → inherited middleware
   - Fix cache key generation to include routing information (prevents cache collisions)
   - Properly detect wrapper objects vs direct function configs for message handlers
@@ -336,13 +402,11 @@
 - 4349ec5: Add file-based storage implementations for serverless environments
 
   **New Services:**
-
   - Add `FileChannelStore` for file-based channel storage (suitable for AWS Lambda /tmp)
   - Add `FileEventHubStore` for file-based event hub subscriptions
   - Export new services in package.json for use in serverless runtimes
 
   **Bug Fixes:**
-
   - Fix serverless channel runner to handle disconnect gracefully when channel is already cleaned up
   - Fix MCP runner to pass `mcp` service to functions and use correct function type
 
@@ -418,7 +482,6 @@ For complete details, see https://pikku.dev/changelogs/0_10_0.md
   ### Ordered Execution System
 
   Both middleware and permissions now execute in a specific hierarchical order:
-
   1. **Wiring Tags** - Tag-based middleware/permissions from wiring level (e.g., HTTP route tags)
   2. **Wiring Middleware/Permissions** - Direct wiring-level middleware/permissions
   3. **Function Middleware** - Function-level middleware
@@ -483,7 +546,6 @@ For complete details, see https://pikku.dev/changelogs/0_10_0.md
 - 7c592b8: feat: support for required services and improved service configuration
 
   This release includes several enhancements to service management and configuration:
-
   - Added support for required services configuration
   - Improved service discovery and registration
   - Added typed RPC clients for service communication

package/dist/function/function-runner.js

@@ -37,6 +37,51 @@ async function resolveSession(wire, singletonServices, sessionService) {
  * @param parentServices - The parent/caller's singleton services (used as base)
  * @returns The package's singleton services
  */
+/**
+ * Find the consumer-defined namespace (from wireAddon) for a given addon package.
+ * Returns null if the package isn't registered as an addon.
+ */
+const findAddonNamespaceForPackage = (packageName) => {
+    const addons = pikkuState(null, 'addons', 'packages');
+    if (!addons)
+        return null;
+    for (const [namespace, cfg] of addons.entries()) {
+        if (cfg?.package === packageName)
+            return namespace;
+    }
+    return null;
+};
+/**
+ * Wrap a workflow service so that bare workflow names passed from inside an
+ * addon function are auto-prefixed with the addon's consumer-facing namespace.
+ * Without this, `runToCompletion('myWorkflow')` from inside an addon misses
+ * the workflow registered under the addon's package scope and throws
+ * WorkflowNotFoundError — forcing addons to hardcode their consumer-defined
+ * namespace, which couples the addon to its caller.
+ *
+ * Explicit `'ns:name'` and bare names that already exist in root meta are
+ * unaffected; only bare names that would otherwise miss resolution get
+ * prefixed.
+ */
+const wrapWorkflowServiceForPackage = (service, packageName) => {
+    return new Proxy(service, {
+        get(target, prop, receiver) {
+            if (prop === 'startWorkflow' || prop === 'runToCompletion') {
+                const original = Reflect.get(target, prop, receiver);
+                return function (name, ...rest) {
+                    if (typeof name === 'string' && !name.includes(':')) {
+                        const namespace = findAddonNamespaceForPackage(packageName);
+                        if (namespace) {
+                            name = `${namespace}:${name}`;
+                        }
+                    }
+                    return original.call(this, name, ...rest);
+                };
+            }
+            return Reflect.get(target, prop, receiver);
+        },
+    });
+};
 const getOrCreatePackageSingletonServices = async (packageName, parentServices) => {
     // Check if we already have cached singleton services for this package
     const cachedServices = pikkuState(packageName, 'package', 'singletonServices');
@@ -56,6 +101,12 @@ const getOrCreatePackageSingletonServices = async (packageName, parentServices)
     }
     // Create singleton services for the package, passing parent services as existing
     const packageServices = await factories.createSingletonServices(config, parentServices);
+    // Wrap workflowService so that bare names used inside the addon's functions
+    // resolve to workflows registered under the addon's package scope.
+    if (packageServices.workflowService &&
+        typeof packageServices.workflowService === 'object') {
+        packageServices.workflowService = wrapWorkflowServiceForPackage(packageServices.workflowService, packageName);
+    }
     // Cache the services
     pikkuState(packageName, 'package', 'singletonServices', packageServices);
     return packageServices;
@@ -223,11 +274,10 @@ export const runPikkuFunc = async (wireType, wireId, funcName, { singletonServic
             const services = wireServices && Object.keys(wireServices).length > 0
                 ? { ...resolvedSingletonServices, ...wireServices }
                 : resolvedSingletonServices;
+            const callerPackageName = packageName;
             Object.defineProperty(resolvedWire, 'rpc', {
                 get() {
-                    const rpc = rpcService.getContextRPCService(services, resolvedWire, {
-                        sessionService,
-                    });
+                    const rpc = rpcService.getContextRPCService(services, resolvedWire, { sessionService }, 0, callerPackageName);
                     Object.defineProperty(resolvedWire, 'rpc', {
                         value: rpc,
                         writable: true,

package/dist/function/functions.types.d.ts

@@ -146,6 +146,7 @@ export type CorePikkuFunctionConfig<PikkuFunction extends CorePikkuFunction<any,
     remote?: boolean;
     mcp?: boolean;
     readonly?: boolean;
+    deploy?: 'serverless' | 'server' | 'auto';
     approvalRequired?: boolean;
     approvalDescription?: any;
     func: PikkuFunction;

package/dist/index.d.ts

@@ -24,7 +24,7 @@ export type { QueueService } from './wirings/queue/queue.types.js';
 export type { JWTService } from './services/jwt-service.js';
 export type { SecretService } from './services/secret-service.js';
 export type { VariablesService } from './services/variables-service.js';
-export type { ContentService } from './services/content-service.js';
+export type { ContentService, SignContentKeyArgs, SignURLArgs, GetUploadURLArgs, UploadURLResult, BucketKeyArgs, WriteFileArgs, CopyFileArgs, } from './services/content-service.js';
 export type { DeploymentService } from './services/deployment-service.js';
 export type { WorkflowService } from './services/workflow-service.js';
 export type { GatewayService } from './services/gateway-service.js';

package/dist/services/content-service.d.ts

@@ -1,60 +1,89 @@
-export interface ContentService {
+/**
+ * Arguments for signing a content key into a time-limited URL.
+ */
+export interface SignContentKeyArgs<TBucket extends string = string> {
+    bucket: TBucket;
+    contentKey: string;
+    dateLessThan: Date;
+    dateGreaterThan?: Date;
+}
+/**
+ * Arguments for signing an arbitrary URL.
+ */
+export interface SignURLArgs {
+    url: string;
+    dateLessThan: Date;
+    dateGreaterThan?: Date;
+}
+/**
+ * Arguments for minting a presigned upload URL.
+ */
+export interface GetUploadURLArgs<TBucket extends string = string> {
+    bucket: TBucket;
+    fileKey: string;
+    contentType: string;
+    size?: number;
+}
+/**
+ * Result of minting a presigned upload URL.
+ */
+export interface UploadURLResult {
+    uploadUrl: string;
+    assetKey: string;
+    uploadHeaders?: Record<string, string>;
+    uploadMethod?: 'PUT' | 'POST';
+}
+/**
+ * Arguments for an operation that targets a single object by key.
+ */
+export interface BucketKeyArgs<TBucket extends string = string> {
+    bucket: TBucket;
+    key: string;
+}
+/**
+ * Arguments for writing a stream to storage.
+ */
+export interface WriteFileArgs<TBucket extends string = string> extends BucketKeyArgs<TBucket> {
+    stream: ReadableStream | NodeJS.ReadableStream;
+}
+/**
+ * Arguments for copying a local file into storage.
+ */
+export interface CopyFileArgs<TBucket extends string = string> extends BucketKeyArgs<TBucket> {
+    fromAbsolutePath: string;
+}
+export interface ContentService<TBucket extends string = string> {
     /**
      * Signs a content key to generate a secure, time-limited access URL.
-     * @param contentKey - The key representing the content object.
-     * @param dateLessThan - The expiration time for the signed URL.
-     * @param dateGreaterThan - (Optional) Start time before which access is denied.
      */
-    signContentKey(contentKey: string, dateLessThan: Date, dateGreaterThan?: Date): Promise<string>;
+    signContentKey(args: SignContentKeyArgs<TBucket>): Promise<string>;
     /**
      * Signs an arbitrary URL to generate a secure, time-limited access URL.
-     * @param url - The full URL that needs signing.
-     * @param dateLessThan - The expiration time for the signed URL.
-     * @param dateGreaterThan - (Optional) Start time before which access is denied.
      */
-    signURL(url: string, dateLessThan: Date, dateGreaterThan?: Date): Promise<string>;
+    signURL(args: SignURLArgs): Promise<string>;
     /**
      * Generates a signed URL for uploading a file directly to storage.
-     * @param fileKey - The desired key/location of the uploaded file.
-     * @param contentType - The MIME type of the file.
-     * @returns A signed upload URL and the finalized asset key.
+     * Bucket policy (size limits, MIME allowlist) is enforced by the implementation.
      */
-    getUploadURL(fileKey: string, contentType: string): Promise<{
-        uploadUrl: string;
-        assetKey: string;
-        uploadHeaders?: Record<string, string>;
-        uploadMethod?: 'PUT' | 'POST';
-    }>;
+    getUploadURL(args: GetUploadURLArgs<TBucket>): Promise<UploadURLResult>;
     /**
      * Deletes a file from the storage backend.
-     * @param fileName - The name or key of the file to delete.
-     * @returns A boolean indicating success.
      */
-    deleteFile(fileName: string): Promise<boolean>;
+    deleteFile(args: BucketKeyArgs<TBucket>): Promise<boolean>;
     /**
-     * Uploads a file stream to storage under a specified asset key.
-     * @param assetKey - The key where the file will be saved.
-     * @param stream - A readable stream of the file contents.
-     * @returns A boolean indicating success.
+     * Uploads a file stream to storage under the specified bucket + key.
      */
-    writeFile(assetKey: string, stream: ReadableStream | NodeJS.ReadableStream): Promise<boolean>;
+    writeFile(args: WriteFileArgs<TBucket>): Promise<boolean>;
     /**
-     * Copies a file from a local absolute path into storage under a new asset key.
-     * @param assetKey - The destination key.
-     * @param fromAbsolutePath - The local absolute file path.
-     * @returns A boolean indicating success.
+     * Copies a file from a local absolute path into storage.
      */
-    copyFile(assetKey: string, fromAbsolutePath: string): Promise<boolean>;
+    copyFile(args: CopyFileArgs<TBucket>): Promise<boolean>;
     /**
      * Reads a file from storage as a readable stream.
-     * @param assetKey - The key of the file to read.
-     * @returns A readable file stream.
      */
-    readFile(assetKey: string): Promise<ReadableStream | NodeJS.ReadableStream>;
+    readFile(args: BucketKeyArgs<TBucket>): Promise<ReadableStream | NodeJS.ReadableStream>;
     /**
      * Reads an entire file from storage into a Buffer.
-     * @param assetKey - The key of the file to read.
-     * @returns The file contents as a Buffer.
      */
-    readFileAsBuffer(assetKey: string): Promise<Buffer>;
+    readFileAsBuffer(args: BucketKeyArgs<TBucket>): Promise<Buffer>;
 }

package/dist/services/in-memory-workflow-service.d.ts

@@ -1,6 +1,6 @@
 import { PikkuWorkflowService } from '../wirings/workflow/pikku-workflow-service.js';
 import type { SerializedError } from '../types/core.types.js';
-import type { WorkflowRun, WorkflowRunService, WorkflowRunWire, StepState, WorkflowStatus, WorkflowVersionStatus, WorkflowStepOptions } from '../wirings/workflow/workflow.types.js';
+import type { WorkflowPlannedStep, WorkflowRun, WorkflowRunService, WorkflowRunWire, StepState, WorkflowStatus, WorkflowVersionStatus, WorkflowStepOptions } from '../wirings/workflow/workflow.types.js';
 /**
  * In-memory implementation of WorkflowService for inline-only execution
  *
@@ -24,7 +24,10 @@ export declare class InMemoryWorkflowService extends PikkuWorkflowService implem
     private runState;
     private branchKeys;
     private workflowVersions;
-    createRun(workflowName: string, input: any, inline: boolean, graphHash: string, wire: WorkflowRunWire): Promise<string>;
+    createRun(workflowName: string, input: any, inline: boolean, graphHash: string, wire: WorkflowRunWire, options?: {
+        deterministic?: boolean;
+        plannedSteps?: WorkflowPlannedStep[];
+    }): Promise<string>;
     getRun(id: string): Promise<WorkflowRun | null>;
     getRunHistory(runId: string): Promise<Array<StepState & {
         stepName: string;

package/dist/services/in-memory-workflow-service.js

@@ -23,7 +23,7 @@ export class InMemoryWorkflowService extends PikkuWorkflowService {
     runState = new Map(); // keyed by runId
     branchKeys = new Map(); // keyed by stepId
     workflowVersions = new Map(); // keyed by `${name}:${graphHash}`
-    async createRun(workflowName, input, inline, graphHash, wire) {
+    async createRun(workflowName, input, inline, graphHash, wire, options) {
         const runId = randomUUID();
         const now = new Date();
         const run = {
@@ -33,6 +33,8 @@ export class InMemoryWorkflowService extends PikkuWorkflowService {
             input,
             inline,
             graphHash,
+            deterministic: options?.deterministic,
+            plannedSteps: options?.plannedSteps,
             wire,
             createdAt: now,
             updatedAt: now,

package/dist/services/index.d.ts

@@ -16,7 +16,7 @@ export { InMemoryQueueService } from './in-memory-queue-service.js';
 export { InMemoryTriggerService } from './in-memory-trigger-service.js';
 export { InMemoryAIRunStateService } from './in-memory-ai-run-state-service.js';
 export { LocalGatewayService } from './local-gateway-service.js';
-export type { ContentService } from './content-service.js';
+export type { ContentService, SignContentKeyArgs, SignURLArgs, GetUploadURLArgs, UploadURLResult, BucketKeyArgs, WriteFileArgs, CopyFileArgs, } from './content-service.js';
 export type { JWTService } from './jwt-service.js';
 export type { Logger } from './logger.js';
 export type { SecretService } from './secret-service.js';

package/dist/services/local-content.d.ts

@@ -1,4 +1,4 @@
-import type { ContentService, JWTService, Logger } from '@pikku/core/services';
+import type { BucketKeyArgs, ContentService, CopyFileArgs, GetUploadURLArgs, JWTService, Logger, SignContentKeyArgs, SignURLArgs, UploadURLResult, WriteFileArgs } from '@pikku/core/services';
 export interface LocalContentConfig {
     localFileUploadPath: string;
     uploadUrlPrefix: string;
@@ -12,18 +12,16 @@ export declare class LocalContent implements ContentService {
     private jwt?;
     constructor(config: LocalContentConfig, logger: Logger, jwt?: JWTService | undefined);
     private safePath;
+    private joinKey;
     init(): Promise<void>;
     private signParams;
-    signURL(url: string, dateLessThan: Date, dateGreaterThan?: Date): Promise<string>;
-    signContentKey(assetKey: string, dateLessThan: Date, dateGreaterThan?: Date): Promise<string>;
-    getUploadURL(assetKey: string): Promise<{
-        uploadUrl: string;
-        assetKey: string;
-    }>;
-    writeFile(assetKey: string, stream: ReadableStream | NodeJS.ReadableStream): Promise<boolean>;
-    copyFile(assetKey: string, fromAbsolutePath: string): Promise<boolean>;
-    readFile(assetKey: string): Promise<ReadableStream | NodeJS.ReadableStream>;
-    readFileAsBuffer(assetKey: string): Promise<Buffer>;
-    deleteFile(assetKey: string): Promise<boolean>;
+    signURL(args: SignURLArgs): Promise<string>;
+    signContentKey(args: SignContentKeyArgs): Promise<string>;
+    getUploadURL(args: GetUploadURLArgs): Promise<UploadURLResult>;
+    writeFile(args: WriteFileArgs): Promise<boolean>;
+    copyFile(args: CopyFileArgs): Promise<boolean>;
+    readFile(args: BucketKeyArgs): Promise<ReadableStream | NodeJS.ReadableStream>;
+    readFileAsBuffer(args: BucketKeyArgs): Promise<Buffer>;
+    deleteFile(args: BucketKeyArgs): Promise<boolean>;
     private createDirectoryForFile;
 }

package/dist/services/local-content.js

@@ -11,14 +11,18 @@ export class LocalContent {
         this.logger = logger;
         this.jwt = jwt;
     }
-    safePath(assetKey) {
+    safePath(bucket, key) {
         const base = resolve(this.config.localFileUploadPath);
-        const target = resolve(base, normalize(assetKey));
+        const scoped = resolve(base, normalize(bucket));
+        const target = resolve(scoped, normalize(key));
         if (!target.startsWith(base + '/') && target !== base) {
             throw new Error('Invalid asset key');
         }
         return target;
     }
+    joinKey(bucket, key) {
+        return `${bucket}/${key}`;
+    }
     async init() { }
     async signParams(dateLessThan, dateGreaterThan) {
         const signedAt = Date.now();
@@ -37,81 +41,86 @@ export class LocalContent {
         }
         return params.toString();
     }
-    async signURL(url, dateLessThan, dateGreaterThan) {
-        const params = await this.signParams(dateLessThan, dateGreaterThan);
-        return `${url}?${params}`;
+    async signURL(args) {
+        const params = await this.signParams(args.dateLessThan, args.dateGreaterThan);
+        return `${args.url}?${params}`;
     }
-    async signContentKey(assetKey, dateLessThan, dateGreaterThan) {
+    async signContentKey(args) {
+        const fullKey = this.joinKey(args.bucket, args.contentKey);
         const base = this.config.server
-            ? `${this.config.server}${this.config.assetUrlPrefix}/${assetKey}`
-            : `${this.config.assetUrlPrefix}/${assetKey}`;
-        return this.signURL(base, dateLessThan, dateGreaterThan);
+            ? `${this.config.server}${this.config.assetUrlPrefix}/${fullKey}`
+            : `${this.config.assetUrlPrefix}/${fullKey}`;
+        return this.signURL({
+            url: base,
+            dateLessThan: args.dateLessThan,
+            dateGreaterThan: args.dateGreaterThan,
+        });
     }
-    async getUploadURL(assetKey) {
-        this.logger.debug(`Going to upload with key: ${assetKey}`);
+    async getUploadURL(args) {
+        const fullKey = this.joinKey(args.bucket, args.fileKey);
+        this.logger.debug(`Going to upload with key: ${fullKey}`);
         return {
-            uploadUrl: `${this.config.uploadUrlPrefix}/${assetKey}`,
-            assetKey,
+            uploadUrl: `${this.config.uploadUrlPrefix}/${fullKey}`,
+            assetKey: fullKey,
         };
     }
-    async writeFile(assetKey, stream) {
-        this.logger.debug(`Writing file: ${assetKey}`);
-        const path = this.safePath(assetKey);
+    async writeFile(args) {
+        this.logger.debug(`Writing file: ${args.bucket}/${args.key}`);
+        const path = this.safePath(args.bucket, args.key);
         try {
             await this.createDirectoryForFile(path);
             const fileStream = createWriteStream(path);
-            // Use pipeline to properly manage stream piping and errors
-            await pipeline(stream, fileStream);
+            await pipeline(args.stream, fileStream);
             return true;
         }
         catch (e) {
             console.error(e);
-            this.logger.error(`Error writing content ${assetKey}`, e);
+            this.logger.error(`Error writing content ${args.bucket}/${args.key}`, e);
             return false;
         }
     }
-    async copyFile(assetKey, fromAbsolutePath) {
-        this.logger.debug(`Writing file: ${assetKey}`);
+    async copyFile(args) {
+        this.logger.debug(`Writing file: ${args.bucket}/${args.key}`);
         try {
-            const path = this.safePath(assetKey);
+            const path = this.safePath(args.bucket, args.key);
             await this.createDirectoryForFile(path);
-            await promises.copyFile(fromAbsolutePath, path);
+            await promises.copyFile(args.fromAbsolutePath, path);
+            return true;
         }
         catch (e) {
             console.error(e);
-            this.logger.error(`Error inserting content ${assetKey}`, e);
+            this.logger.error(`Error inserting content ${args.bucket}/${args.key}`, e);
         }
         return false;
     }
-    async readFile(assetKey) {
-        this.logger.debug(`Getting key: ${assetKey}`);
-        const filePath = this.safePath(assetKey);
+    async readFile(args) {
+        this.logger.debug(`Getting key: ${args.bucket}/${args.key}`);
+        const filePath = this.safePath(args.bucket, args.key);
         try {
             const stream = createReadStream(filePath);
-            // Handle early stream errors (like file not found, permission denied, etc.)
             stream.on('error', (err) => {
-                this.logger.error(`Error getting content ${assetKey}`, err);
+                this.logger.error(`Error getting content ${args.bucket}/${args.key}`, err);
             });
             return stream;
         }
         catch (e) {
-            this.logger.error(`Error setting up stream for ${assetKey}`, e);
+            this.logger.error(`Error setting up stream for ${args.bucket}/${args.key}`, e);
             throw e;
         }
     }
-    async readFileAsBuffer(assetKey) {
-        const filePath = this.safePath(assetKey);
-        this.logger.debug(`Reading file as buffer: ${assetKey}`);
+    async readFileAsBuffer(args) {
+        const filePath = this.safePath(args.bucket, args.key);
+        this.logger.debug(`Reading file as buffer: ${args.bucket}/${args.key}`);
         return readFile(filePath);
     }
-    async deleteFile(assetKey) {
-        this.logger.debug(`deleting key: ${assetKey}`);
+    async deleteFile(args) {
+        this.logger.debug(`deleting key: ${args.bucket}/${args.key}`);
         try {
-            await promises.unlink(this.safePath(assetKey));
+            await promises.unlink(this.safePath(args.bucket, args.key));
             return true;
         }
         catch (e) {
-            this.logger.error(`Error deleting content ${assetKey}`, e);
+            this.logger.error(`Error deleting content ${args.bucket}/${args.key}`, e);
         }
         return false;
     }

package/dist/services/workflow-service.d.ts

@@ -1,11 +1,14 @@
 import type { SerializedError } from '../types/core.types.js';
-import type { WorkflowRun, WorkflowRunWire, WorkflowRunStatus, StepState, WorkflowStatus, WorkflowVersionStatus } from '../wirings/workflow/workflow.types.js';
+import type { WorkflowRun, WorkflowPlannedStep, WorkflowRunWire, WorkflowRunStatus, StepState, WorkflowStatus, WorkflowVersionStatus } from '../wirings/workflow/workflow.types.js';
 /**
  * Interface for workflow orchestration
  * Handles workflow execution, replay, orchestration logic, and run-level state
  */
 export interface WorkflowService {
-    createRun(workflowName: string, input: any, inline: boolean, graphHash: string, wire: WorkflowRunWire): Promise<string>;
+    createRun(workflowName: string, input: any, inline: boolean, graphHash: string, wire: WorkflowRunWire, options?: {
+        deterministic?: boolean;
+        plannedSteps?: WorkflowPlannedStep[];
+    }): Promise<string>;
     getRun(id: string): Promise<WorkflowRun | null>;
     getRunStatus(id: string): Promise<WorkflowRunStatus | null>;
     getRunHistory(runId: string): Promise<Array<StepState & {