@pikku/skills 0.12.43 → 0.12.46

package/skills/pikku-service-backends/references/mongodb.md

@@ -73,6 +73,7 @@ import {
   MongoDBChannelStore,
   MongoDBWorkflowService,
 } from '@pikku/mongodb'
+import { RedisLeaseService } from '@pikku/redis'
 
 const createSingletonServices = pikkuServices(async (config) => {
   const logger = new PinoLogger()
@@ -82,9 +83,23 @@ const createSingletonServices = pikkuServices(async (config) => {
   const channelStore = new MongoDBChannelStore(mongo.db)
   await channelStore.init()
 
-  const workflowService = new MongoDBWorkflowService(mongo.db)
+  const leaseService = new RedisLeaseService(config.redisUrl)
+  const workflowService = new MongoDBWorkflowService(mongo.db, {
+    leaseService,
+  })
   await workflowService.init()
 
-  return { config, logger, database: mongo, channelStore, workflowService }
+  return {
+    config,
+    logger,
+    database: mongo,
+    channelStore,
+    leaseService,
+    workflowService,
+  }
 })
 ```
+
+`MongoDBWorkflowService` requires a `leaseService` to lock runs and steps, and
+`@pikku/mongodb` ships none — pair it with Redis, a Kysely lease service, or
+`InMemoryLeaseService` for a single process.

package/skills/pikku-service-backends/references/redis.md

@@ -9,16 +9,17 @@ Redis-backed implementations of Pikku's core service interfaces, using
 connection — an ioredis `Redis` instance, `RedisOptions`, or a connection
 string — in its constructor. None of them need an `init()` call.
 
-| Service | Interface | Purpose |
-| --- | --- | --- |
-| `RedisChannelStore` | `ChannelStore` | WebSocket channel state persistence |
-| `RedisEventHubStore` | `EventHubStore` | Event hub state persistence |
-| `RedisWorkflowService` | `PikkuWorkflowService` | Workflow definition storage |
-| `RedisWorkflowRunService` | `WorkflowRunService` | Workflow execution tracking |
-| `RedisDeploymentService` | `DeploymentService` | Deployment state management |
-| `RedisAgentRunService` | `AgentRunService` | Agent execution tracking |
-| `RedisSecretService` | `SecretService` | Encrypted secret storage (envelope encryption) |
-| `RedisSessionStore` | `SessionStore` | Persisted user sessions |
+| Service                   | Interface              | Purpose                                        |
+| ------------------------- | ---------------------- | ---------------------------------------------- |
+| `RedisChannelStore`       | `ChannelStore`         | WebSocket channel state persistence            |
+| `RedisEventHubStore`      | `EventHubStore`        | Event hub state persistence                    |
+| `RedisWorkflowService`    | `PikkuWorkflowService` | Workflow definition storage                    |
+| `RedisWorkflowRunService` | `WorkflowRunService`   | Workflow execution tracking                    |
+| `RedisDeploymentService`  | `DeploymentService`    | Deployment state management                    |
+| `RedisAgentRunService`    | `AgentRunService`      | Agent execution tracking                       |
+| `RedisSecretService`      | `SecretService`        | Encrypted secret storage (envelope encryption) |
+| `RedisSessionStore`       | `SessionStore`         | Persisted user sessions                        |
+| `RedisLeaseService`       | `LeaseService`         | Named leases with fencing tokens               |
 
 There is no Redis implementation of `AgentStorageService` — AI conversation
 storage is MongoDB-only.
@@ -51,11 +52,38 @@ await secrets.rotateKEK(): Promise<number>
 await secrets.close(): Promise<void>
 ```
 
+## `RedisLeaseService`
+
+Each lease is a hash Redis expires itself, and every check-and-set is one Lua
+script that reads the time with `TIME`, so a lease is judged — and its
+`expiresAt` reported — on Redis's clock, never the worker's. A fast worker
+clock can neither take a live lease nor stretch its own.
+
+The token comes from a counter stored beside the lease that release never
+deletes, so the next holder always gets a higher token. That counter is one
+small key per lease name, kept forever. On a replicated Redis with async
+failover a promoted replica can miss the latest `INCR`, so a token is only as
+durable as the write it rode on.
+
+```typescript
+import { RedisLeaseService } from '@pikku/redis'
+import { holdLease } from '@pikku/core/services'
+
+const leaseService = new RedisLeaseService(config.redisUrl, {
+  keyPrefix: 'pikku', // lease keys are `<prefix>:lease:{<key>}`
+})
+
+await holdLease(leaseService, 'nightly-report', async (lease, signal) => {
+  // ...
+})
+```
+
 ## Full setup
 
 ```typescript
 import {
   RedisChannelStore,
+  RedisLeaseService,
   RedisWorkflowService,
   RedisSecretService,
 } from '@pikku/redis'
@@ -64,12 +92,22 @@ const createSingletonServices = pikkuServices(async (config) => {
   const logger = new PinoLogger()
 
   const channelStore = new RedisChannelStore(config.redisUrl)
-  const workflowService = new RedisWorkflowService(config.redisUrl)
+  const leaseService = new RedisLeaseService(config.redisUrl)
+  const workflowService = new RedisWorkflowService(config.redisUrl, {
+    leaseService,
+  })
 
   const secrets = new RedisSecretService(config.redisUrl, {
     key: config.kekPassphrase,
   })
 
-  return { config, logger, channelStore, workflowService, secrets }
+  return {
+    config,
+    logger,
+    channelStore,
+    leaseService,
+    workflowService,
+    secrets,
+  }
 })
 ```