@pikku/core 0.12.17 → 0.12.19

package/src/services/user-session-service.ts

@@ -1,5 +1,5 @@
-import type { ChannelStore } from '../wirings/channel/channel-store.js'
 import type { CoreUserSession } from '../types/core.types.js'
+import type { SessionStore } from './session-store.js'
 
 export interface SessionService<UserSession extends CoreUserSession> {
   sessionChanged: boolean
@@ -8,7 +8,7 @@ export interface SessionService<UserSession extends CoreUserSession> {
   freezeInitial(): UserSession | undefined
   set(session: UserSession): Promise<void> | void
   clear(): Promise<void> | void
-  get(): Promise<UserSession> | UserSession | undefined
+  get(): UserSession | undefined
 }
 
 export class PikkuSessionService<UserSession extends CoreUserSession>
@@ -17,13 +17,16 @@ export class PikkuSessionService<UserSession extends CoreUserSession>
   public sessionChanged = false
   public initial: UserSession | undefined
   private session: UserSession | undefined
-  constructor(
-    private channelStore?: ChannelStore<unknown, unknown, UserSession>,
-    private channelId?: string
-  ) {
-    if (channelStore && !channelId) {
-      throw new Error('Channel ID is required when using channel store')
-    }
+  private pikkuUserId?: string
+
+  constructor(private sessionStore?: SessionStore<UserSession>) {}
+
+  public setPikkuUserId(id: string) {
+    this.pikkuUserId = id
+  }
+
+  public getPikkuUserId(): string | undefined {
+    return this.pikkuUserId
   }
 
   public setInitial(session: UserSession) {
@@ -37,27 +40,23 @@ export class PikkuSessionService<UserSession extends CoreUserSession>
     return this.initial
   }
 
-  public set(session: UserSession) {
+  public async set(session: UserSession) {
     this.sessionChanged = true
     this.session = session
-    return this.channelStore?.setUserSession(this.channelId!, session)
+    if (this.sessionStore && this.pikkuUserId) {
+      await this.sessionStore.set(this.pikkuUserId, session)
+    }
   }
 
-  public clear() {
+  public async clear() {
     this.sessionChanged = true
     this.session = undefined
-    return this.channelStore?.setUserSession(this.channelId!, null)
+    if (this.sessionStore && this.pikkuUserId) {
+      await this.sessionStore.clear(this.pikkuUserId)
+    }
   }
 
-  public get(): Promise<UserSession> | UserSession | undefined {
-    if (this.channelStore) {
-      const channel = this.channelStore.getChannelAndSession(this.channelId!)
-      if (channel instanceof Promise) {
-        return channel.then(({ session }) => session)
-      } else {
-        return channel.session
-      }
-    }
+  public get(): UserSession | undefined {
     return this.session
   }
 }

package/src/services/workflow-service.ts

@@ -1,6 +1,7 @@
 import type { SerializedError } from '../types/core.types.js'
 import type {
   WorkflowRun,
+  WorkflowPlannedStep,
   WorkflowRunWire,
   WorkflowRunStatus,
   StepState,
@@ -19,7 +20,11 @@ export interface WorkflowService {
     input: any,
     inline: boolean,
     graphHash: string,
-    wire: WorkflowRunWire
+    wire: WorkflowRunWire,
+    options?: {
+      deterministic?: boolean
+      plannedSteps?: WorkflowPlannedStep[]
+    }
   ): Promise<string>
   getRun(id: string): Promise<WorkflowRun | null>
   getRunStatus(id: string): Promise<WorkflowRunStatus | null>

package/src/testing/service-tests.ts

@@ -11,6 +11,7 @@ import type { AIRunStateService } from '../services/ai-run-state-service.js'
 import type { SecretService } from '../services/secret-service.js'
 import type { CredentialService } from '../services/credential-service.js'
 import type { AgentRunService } from '../wirings/ai-agent/ai-agent.types.js'
+import type { SessionStore } from '../services/session-store.js'
 
 export interface ServiceTestConfig {
   name: string
@@ -34,6 +35,7 @@ export interface ServiceTestConfig {
       keyVersion?: number
       previousKey?: string
     }) => Promise<CredentialService & { rotateKEK?(): Promise<number> }>
+    sessionStore?: () => Promise<SessionStore>
   }
 }
 
@@ -49,32 +51,38 @@ export function defineServiceTests(config: ServiceTestConfig): void {
         store = await factory()
       })
 
-      test('addChannel and getChannelAndSession', async () => {
+      test('addChannel and getChannel', async () => {
         await store.addChannel({
           channelId: 'ch-1',
           channelName: 'test-channel',
           openingData: { foo: 'bar' },
         })
 
-        const result = await store.getChannelAndSession('ch-1')
+        const result = await store.getChannel('ch-1')
         assert.equal(result.channelId, 'ch-1')
         assert.equal(result.channelName, 'test-channel')
         assert.deepEqual(result.openingData, { foo: 'bar' })
-        assert.deepEqual(result.session, {})
+        assert.equal(result.pikkuUserId, undefined)
       })
 
-      test('setUserSession', async () => {
-        const session = { userId: 'user-1' } as any
-        await store.setUserSession('ch-1', session)
+      test('setPikkuUserId', async () => {
+        await store.setPikkuUserId('ch-1', 'user-1')
 
-        const result = await store.getChannelAndSession('ch-1')
-        assert.deepEqual(result.session, session)
+        const result = await store.getChannel('ch-1')
+        assert.equal(result.pikkuUserId, 'user-1')
       })
 
-      test('getChannelAndSession throws for missing channel', async () => {
+      test('setPikkuUserId to null', async () => {
+        await store.setPikkuUserId('ch-1', null)
+
+        const result = await store.getChannel('ch-1')
+        assert.equal(result.pikkuUserId, undefined)
+      })
+
+      test('getChannel throws for missing channel', async () => {
         await assert.rejects(
           async () => {
-            await store.getChannelAndSession('missing')
+            await store.getChannel('missing')
           },
           { message: 'Channel not found: missing' }
         )
@@ -87,7 +95,7 @@ export function defineServiceTests(config: ServiceTestConfig): void {
         })
         await store.removeChannels(['ch-2'])
         await assert.rejects(async () => {
-          await store.getChannelAndSession('ch-2')
+          await store.getChannel('ch-2')
         })
       })
 
@@ -999,4 +1007,49 @@ export function defineServiceTests(config: ServiceTestConfig): void {
       })
     })
   }
+
+  if (services.sessionStore) {
+    const factory = services.sessionStore
+    describe(`SessionStore [${name}]`, () => {
+      let store: SessionStore
+
+      before(async () => {
+        store = await factory()
+      })
+
+      test('get returns undefined for unknown user', async () => {
+        const result = await store.get('unknown-user')
+        assert.equal(result, undefined)
+      })
+
+      test('set and get round-trip', async () => {
+        const session = { userId: 'user-1', organizationId: 'org-1' } as any
+        await store.set('user-1', session)
+
+        const result = await store.get('user-1')
+        assert.deepEqual(result, session)
+      })
+
+      test('set overwrites previous session', async () => {
+        await store.set('user-2', { userId: 'user-2', role: 'admin' } as any)
+        await store.set('user-2', { userId: 'user-2', role: 'member' } as any)
+
+        const result = await store.get('user-2')
+        assert.deepEqual(result, { userId: 'user-2', role: 'member' })
+      })
+
+      test('clear removes session', async () => {
+        await store.set('user-3', { userId: 'user-3' } as any)
+        assert.ok(await store.get('user-3'))
+
+        await store.clear('user-3')
+        const result = await store.get('user-3')
+        assert.equal(result, undefined)
+      })
+
+      test('clear is no-op for unknown user', async () => {
+        await store.clear('nonexistent')
+      })
+    })
+  }
 }

package/src/types/core.types.ts

@@ -35,6 +35,7 @@ import type { PikkuAIMiddlewareHooks } from '../wirings/ai-agent/ai-agent.types.
 import type { WorkflowRunService } from '../wirings/workflow/workflow.types.js'
 import type { CredentialService } from '../services/credential-service.js'
 import type { MetaService } from '../services/meta-service.js'
+import type { SessionStore } from '../services/session-store.js'
 
 export type PikkuWiringTypes =
   | 'http'
@@ -236,6 +237,8 @@ export interface CoreSingletonServices<Config extends CoreConfig = CoreConfig> {
   credentialService?: CredentialService
   /** Meta service for reading .pikku metadata files (filesystem on Node, R2/KV on CF) */
   metaService?: MetaService
+  /** Session store for persisting user sessions keyed by pikkuUserId */
+  sessionStore?: SessionStore
 }
 
 /**

package/src/wirings/channel/channel-store.ts

@@ -1,5 +1,3 @@
-import type { CoreUserSession } from '../../types/core.types.js'
-
 export type Channel<ChannelType = unknown, OpeningData = unknown> = {
   channelId: string
   channelName: string
@@ -10,20 +8,19 @@ export type Channel<ChannelType = unknown, OpeningData = unknown> = {
 export abstract class ChannelStore<
   ChannelType = unknown,
   OpeningData = unknown,
-  UserSession extends CoreUserSession = CoreUserSession,
   TypedChannel = Channel<ChannelType, OpeningData>,
 > {
   public abstract addChannel(
     channel: Channel<ChannelType, OpeningData>
   ): Promise<void> | void
   public abstract removeChannels(channelId: string[]): Promise<void> | void
-  public abstract setUserSession(
+  public abstract setPikkuUserId(
     channelId: string,
-    userSession: UserSession | null
+    pikkuUserId: string | null
   ): Promise<void> | void
-  public abstract getChannelAndSession(
+  public abstract getChannel(
     channelId: string
   ):
-    | Promise<TypedChannel & { session: UserSession }>
-    | (TypedChannel & { session: UserSession })
+    | Promise<TypedChannel & { pikkuUserId?: string }>
+    | (TypedChannel & { pikkuUserId?: string })
 }

package/src/wirings/channel/local/local-channel-runner.ts

@@ -45,7 +45,7 @@ export const runLocalChannel = async ({
   let closedWireServices = false
 
   let channelHandler: PikkuLocalChannelHandler | undefined
-  const userSession = new PikkuSessionService()
+  const userSession = new PikkuSessionService(singletonServices.sessionStore)
 
   let http: PikkuHTTP | undefined
   if (request) {
@@ -125,7 +125,9 @@ export const runLocalChannel = async ({
             singletonServices.logger.error(`Error handling onConnect: ${e}`)
             const errorResponse = getErrorResponse(e)
             channel.send({
-              error: errorResponse?.message ?? (isProduction() ? 'Internal server error' : e.message),
+              error:
+                errorResponse?.message ??
+                (isProduction() ? 'Internal server error' : e.message),
               ...(!isProduction() && { errorName: e.constructor?.name }),
             })
           }
@@ -148,7 +150,9 @@ export const runLocalChannel = async ({
             singletonServices.logger.error(`Error handling onDisconnect: ${e}`)
             const errorResponse = getErrorResponse(e)
             channel.send({
-              error: errorResponse?.message ?? (isProduction() ? 'Internal server error' : e.message),
+              error:
+                errorResponse?.message ??
+                (isProduction() ? 'Internal server error' : e.message),
               ...(!isProduction() && { errorName: e.constructor?.name }),
             })
           }
@@ -171,7 +175,9 @@ export const runLocalChannel = async ({
           singletonServices.logger.error(e)
           const errorResponse = getErrorResponse(e)
           channel.send({
-            error: errorResponse?.message ?? (isProduction() ? 'Internal server error' : e.message),
+            error:
+              errorResponse?.message ??
+              (isProduction() ? 'Internal server error' : e.message),
             ...(!isProduction() && { errorName: e.constructor?.name }),
           })
           setTimeout(() => channel.close(), 200)

package/src/wirings/channel/local/local-eventhub-service.test.ts

@@ -1,7 +1,6 @@
 import * as assert from 'assert'
 import { test } from 'node:test'
 import type { PikkuChannelHandler } from '../channel.types.js'
-import type { CoreUserSession } from '../../../types/core.types.js'
 import { LocalEventHubService } from './local-eventhub-service.js'
 
 class MockChannelHandler implements PikkuChannelHandler {
@@ -11,10 +10,6 @@ class MockChannelHandler implements PikkuChannelHandler {
     this.channelId = channelId
   }
 
-  setUserSession(session: CoreUserSession): Promise<void> | void {
-    throw new Error('Method not needed.')
-  }
-
   getChannel() {
     return { channelId: this.channelId } as any
   }

package/src/wirings/channel/serverless/serverless-channel-runner.ts

@@ -89,7 +89,7 @@ export const runChannelConnect = async ({
     http = createHTTPWire(new PikkuFetchHTTPRequest(request), response)
   }
 
-  const userSession = new PikkuSessionService(channelStore, channelId)
+  const userSession = new PikkuSessionService(singletonServices.sessionStore)
 
   const { channelConfig, openingData, meta } = await openChannel({
     channelId,
@@ -138,6 +138,13 @@ export const runChannelConnect = async ({
         channelMiddlewareMeta: meta.channelMiddleware,
       })
     }
+
+    // Store the pikkuUserId mapping after auth middleware has run
+    const pikkuUserId = userSession.getPikkuUserId()
+    if (pikkuUserId) {
+      await channelStore.setPikkuUserId(channelId, pikkuUserId)
+    }
+
     http?.response?.status(101)
   } catch (e: any) {
     handleHTTPError(
@@ -171,7 +178,7 @@ export const runChannelDisconnect = async ({
   // there's nothing to disconnect, so we can return early.
   let channelData
   try {
-    channelData = await channelStore.getChannelAndSession(channelId)
+    channelData = await channelStore.getChannel(channelId)
   } catch {
     singletonServices.logger.info(
       `Channel ${channelId} not found during disconnect - already cleaned up`
@@ -179,7 +186,7 @@ export const runChannelDisconnect = async ({
     return
   }
 
-  const { openingData, channelName, session } = channelData
+  const { openingData, channelName, pikkuUserId } = channelData
   const { channel, channelConfig, meta } = getVariablesForChannel({
     channelId,
     channelHandlerFactory,
@@ -187,8 +194,15 @@ export const runChannelDisconnect = async ({
     channelName,
   })
 
-  const userSession = new PikkuSessionService(channelStore, channelId)
-  userSession.setInitial(session)
+  const userSession = new PikkuSessionService(singletonServices.sessionStore)
+  if (pikkuUserId) {
+    userSession.setPikkuUserId(pikkuUserId)
+    const session = await singletonServices.sessionStore?.get(pikkuUserId)
+    if (session) {
+      userSession.setInitial(session)
+    }
+  }
+
   const wire: PikkuWire = {
     channel,
     ...createMiddlewareSessionWireProps(userSession),
@@ -237,8 +251,8 @@ export const runChannelMessage = async (
   const singletonServices = getSingletonServices()
   const createWireServices = getCreateWireServices()
   let wireServices: WireServices | undefined
-  const { openingData, channelName, session } =
-    await channelStore.getChannelAndSession(channelId)
+  const { openingData, channelName, pikkuUserId } =
+    await channelStore.getChannel(channelId)
 
   const { channel, channelHandler, channelConfig } = getVariablesForChannel({
     channelId,
@@ -247,8 +261,15 @@ export const runChannelMessage = async (
     channelName,
   })
 
-  const userSession = new PikkuSessionService(channelStore, channelId)
-  userSession.setInitial(session)
+  const userSession = new PikkuSessionService(singletonServices.sessionStore)
+  if (pikkuUserId) {
+    userSession.setPikkuUserId(pikkuUserId)
+    const session = await singletonServices.sessionStore?.get(pikkuUserId)
+    if (session) {
+      userSession.setInitial(session)
+    }
+  }
+
   const wire: PikkuWire = {
     channel,
     ...createMiddlewareSessionWireProps(userSession),

package/src/wirings/cli/channel/cli-channel-runner.ts

@@ -3,10 +3,12 @@ import type { CorePikkuCLIRender, CLIMeta } from '../cli.types.js'
 import { generateCommandHelp, parseCLIArguments } from '../command-parser.js'
 
 /**
- * Default JSON renderer for CLI output
+ * Default JSON renderer for CLI output. Emits single-line NDJSON so
+ * the output stays machine-parseable when the CLI is run with
+ * `--output json`; pretty-printing here would break NDJSON consumers.
  */
 const defaultJSONRenderer: CorePikkuCLIRender<any> = (_services, data) => {
-  console.log(JSON.stringify(data, null, 2))
+  console.log(JSON.stringify(data))
 }
 
 /**

package/src/wirings/cli/cli-runner.ts

@@ -45,10 +45,12 @@ export class CLIError extends Error {
 }
 
 /**
- * Default JSON renderer for CLI output
+ * Default JSON renderer for CLI output. Emits single-line NDJSON so
+ * the output stays machine-parseable when the CLI is run with
+ * `--output json`; pretty-printing here would break NDJSON consumers.
  */
 const defaultJSONRenderer: CorePikkuCLIRender<any> = (_services, data) => {
-  console.log(JSON.stringify(data, null, 2))
+  console.log(JSON.stringify(data))
 }
 
 /**
@@ -341,7 +343,9 @@ export async function runCLICommand({
     state: 'open',
   }
 
-  const userSession = new PikkuSessionService<CoreUserSession>()
+  const userSession = new PikkuSessionService<CoreUserSession>(
+    singletonServices.sessionStore
+  )
 
   const wire: PikkuWire = {
     cli: {

package/src/wirings/http/http-runner.ts

@@ -303,10 +303,12 @@ const executeRoute = async (
     coerceDataFromSchema: boolean
   }
 ) => {
-  const userSession = new PikkuSessionService<CoreUserSession>()
   const { params, route, meta } = matchedRoute
   const { singletonServices, createWireServices, skipUserSession, requestId } =
     services
+  const userSession = new PikkuSessionService<CoreUserSession>(
+    singletonServices.sessionStore
+  )
 
   // Attach URL parameters to the request object
   http?.request?.setParams(params)

package/src/wirings/mcp/mcp-runner.ts

@@ -214,7 +214,9 @@ async function runMCPPikkuFunc(
 
     singletonServices.logger.debug(`Running MCP ${type}: ${name}`)
 
-    const mcpSessionService = new PikkuSessionService()
+    const mcpSessionService = new PikkuSessionService(
+      singletonServices.sessionStore
+    )
     const wire: PikkuWire = {
       mcp: mcpWire,
       ...createMiddlewareSessionWireProps(mcpSessionService),

package/src/wirings/scheduler/scheduler-runner.ts

@@ -82,7 +82,7 @@ export async function runScheduledTask({
   const task = pikkuState(null, 'scheduler', 'tasks').get(name)
   const meta = pikkuState(null, 'scheduler', 'meta')[name]
 
-  const userSession = new PikkuSessionService()
+  const userSession = new PikkuSessionService(singletonServices.sessionStore)
   if (session) {
     userSession.set(session)
   }

package/src/wirings/workflow/graph/graph-runner.ts

@@ -852,7 +852,11 @@ export async function runWorkflowGraph(
     triggerInput,
     inline ?? false,
     meta.graphHash,
-    wire ?? { type: 'unknown' }
+    wire ?? { type: 'unknown' },
+    {
+      deterministic: meta.deterministic,
+      plannedSteps: meta.plannedSteps,
+    }
   )
 
   if (inline) {

package/src/wirings/workflow/index.ts

@@ -42,6 +42,7 @@ export type {
 export type {
   WorkflowService,
   WorkflowServiceConfig,
+  WorkflowPlannedStep,
   WorkflowRunWire,
   WorkflowStatus,
   WorkflowVersionStatus,

package/src/wirings/workflow/pikku-workflow-service.ts

@@ -49,6 +49,7 @@ import type {
   PikkuWorkflowWire,
   StepState,
   StepStatus,
+  WorkflowPlannedStep,
   WorkflowRun,
   WorkflowRunStatus,
   WorkflowRunWire,
@@ -272,7 +273,11 @@ export abstract class PikkuWorkflowService implements WorkflowService {
     input: any,
     inline: boolean,
     graphHash: string,
-    wire: WorkflowRunWire
+    wire: WorkflowRunWire,
+    options?: {
+      deterministic?: boolean
+      plannedSteps?: WorkflowPlannedStep[]
+    }
   ): Promise<string>
 
   /**
@@ -323,6 +328,8 @@ export abstract class PikkuWorkflowService implements WorkflowService {
       status: run.status,
       startedAt: run.createdAt,
       completedAt: terminalStatuses.has(run.status) ? run.updatedAt : undefined,
+      deterministic: run.deterministic,
+      plannedSteps: run.plannedSteps,
       steps,
       output: run.status === 'completed' ? run.output : undefined,
       error: run.error
@@ -689,7 +696,11 @@ export abstract class PikkuWorkflowService implements WorkflowService {
       input,
       shouldInline,
       workflowMeta.graphHash,
-      wire
+      wire,
+      {
+        deterministic: workflowMeta.deterministic,
+        plannedSteps: workflowMeta.plannedSteps,
+      }
     )
 
     if (shouldInline) {
@@ -831,7 +842,6 @@ export abstract class PikkuWorkflowService implements WorkflowService {
       const wire: PikkuWire = {
         workflow: workflowWire,
         pikkuUserId: run.wire?.pikkuUserId,
-        session: rpcService.wire?.session,
         rpc: rpcService.wire?.rpc,
       }
       try {

package/src/wirings/workflow/workflow.types.ts

@@ -53,6 +53,11 @@ export interface WorkflowServiceConfig {
   sleeperRPCName: string
 }
 
+export interface WorkflowPlannedStep {
+  /** Human-readable step label for UI timeline */
+  stepName: string
+}
+
 /**
  * Workflow run status
  */
@@ -99,6 +104,10 @@ export interface WorkflowRun {
   inline?: boolean
   /** Graph hash of the workflow definition at run creation time */
   graphHash?: string
+  /** True when the workflow has a static, pre-computable step timeline */
+  deterministic?: boolean
+  /** Static planned steps snapshot captured at run start */
+  plannedSteps?: WorkflowPlannedStep[]
   /** Wire origin info (how this run was started) */
   wire: WorkflowRunWire
   /** Creation timestamp */
@@ -146,6 +155,8 @@ export interface WorkflowRunStatus {
   status: WorkflowStatus
   startedAt: Date
   completedAt?: Date
+  deterministic?: boolean
+  plannedSteps?: WorkflowPlannedStep[]
   steps: Array<{
     name: string
     status: StepStatus
@@ -270,6 +281,10 @@ export interface WorkflowRuntimeMeta {
   entryNodeIds?: string[]
   /** Hash of graph topology (nodes, edges, input mappings) */
   graphHash?: string
+  /** True when the workflow has a static, pre-computable step timeline */
+  deterministic?: boolean
+  /** Static planned steps metadata for deterministic workflows */
+  plannedSteps?: WorkflowPlannedStep[]
 }
 
 /**