typeclaw 0.1.4 → 0.1.6

package/src/channels/persistence.ts

@@ -6,7 +6,7 @@ import type { ChannelParticipant } from '@/agent/session-origin'
 import type { AdapterId } from './schema'
 import type { ChannelKey } from './types'
 
-const FILE_VERSION = 3
+const FILE_VERSION = 4
 
 // `sessionFile` is the basename (not the full path) of the JSONL transcript
 // for this (adapter, workspace, chat, thread) tuple. pi-coding-agent writes
@@ -25,11 +25,17 @@ export type ChannelSessionRecord = {
   workspace: string
   chat: string
   thread: string | null
-  sessionId: string
+  sessionId?: string
   sessionFile?: string
+  lastInboundAt?: number
   participants: ChannelParticipant[]
 }
 
+type FileV4 = {
+  version: 4
+  sessions: ChannelSessionRecord[]
+}
+
 type FileV3 = {
   version: 3
   sessions: ChannelSessionRecord[]
@@ -41,11 +47,13 @@ type FileV2 = {
 }
 
 export type ChannelSessionsLogger = {
+  info: (msg: string) => void
   warn: (msg: string) => void
   error: (msg: string) => void
 }
 
 const consoleLogger: ChannelSessionsLogger = {
+  info: (m) => console.log(m),
   warn: (m) => console.warn(m),
   error: (m) => console.error(m),
 }
@@ -82,17 +90,25 @@ export async function loadChannelSessions(
   }
   const version = (parsed as { version?: unknown }).version
   if (version === FILE_VERSION) {
-    const file = parsed as FileV3
+    const file = parsed as FileV4
     if (!Array.isArray(file.sessions)) return []
     return file.sessions.filter(isValidRecord)
   }
+  if (version === 3) {
+    const file = parsed as FileV3
+    if (!Array.isArray(file.sessions)) return []
+    return migrateV3ToV4(file.sessions.filter(isValidRecord), logger)
+  }
   if (version === 2) {
     const file = parsed as FileV2
     if (!Array.isArray(file.sessions)) return []
     const v2Records = file.sessions.filter(isValidV2Record)
-    return await migrateV2Records(agentDir, v2Records, logger)
+    const v3Records = await migrateV2Records(agentDir, v2Records, logger)
+    return migrateV3ToV4(v3Records, logger)
   }
-  logger.warn(`[channels] ${path} version ${String(version)} not supported (expected 2 or ${FILE_VERSION}); ignored`)
+  logger.warn(
+    `[channels] ${path} version ${String(version)} not supported (expected 2, 3, or ${FILE_VERSION}); ignored`,
+  )
   return []
 }
 
@@ -102,7 +118,7 @@ export async function saveChannelSessions(
   logger: ChannelSessionsLogger = consoleLogger,
 ): Promise<void> {
   const path = channelsSessionsPath(agentDir)
-  const payload: FileV3 = { version: FILE_VERSION, sessions: dedupe(sessions) }
+  const payload: FileV4 = { version: FILE_VERSION, sessions: dedupe(sessions) }
   try {
     await mkdir(dirname(path), { recursive: true })
     const tmp = `${path}.tmp`
@@ -123,7 +139,7 @@ export async function saveChannelSessions(
 // we'll be migrated forward.)
 async function migrateV2Records(
   agentDir: string,
-  v2Records: readonly Omit<ChannelSessionRecord, 'sessionFile'>[],
+  v2Records: readonly (Omit<ChannelSessionRecord, 'sessionFile' | 'sessionId'> & { sessionId: string })[],
   logger: ChannelSessionsLogger,
 ): Promise<ChannelSessionRecord[]> {
   if (v2Records.length === 0) return []
@@ -160,6 +176,13 @@ async function migrateV2Records(
   })
 }
 
+function migrateV3ToV4(v3Records: ChannelSessionRecord[], logger: ChannelSessionsLogger): ChannelSessionRecord[] {
+  logger.info(
+    `[channels] v3→v4: ${v3Records.length} record(s) migrated; first post-upgrade inbound will force fresh session`,
+  )
+  return v3Records.map((r) => ({ ...r, lastInboundAt: 0 }))
+}
+
 function dedupe(sessions: readonly ChannelSessionRecord[]): ChannelSessionRecord[] {
   const seen = new Map<string, ChannelSessionRecord>()
   for (const s of sessions) {
@@ -185,7 +208,9 @@ function isObject(v: unknown): v is Record<string, unknown> {
   return typeof v === 'object' && v !== null && !Array.isArray(v)
 }
 
-function isValidV2Record(v: unknown): v is Omit<ChannelSessionRecord, 'sessionFile'> {
+function isValidV2Record(
+  v: unknown,
+): v is Omit<ChannelSessionRecord, 'sessionFile' | 'sessionId'> & { sessionId: string } {
   if (!isObject(v)) return false
   const r = v as Record<string, unknown>
   return (
@@ -199,9 +224,18 @@ function isValidV2Record(v: unknown): v is Omit<ChannelSessionRecord, 'sessionFi
 }
 
 function isValidRecord(v: unknown): v is ChannelSessionRecord {
-  if (!isValidV2Record(v)) return false
+  if (!isObject(v)) return false
   const r = v as Record<string, unknown>
-  return r.sessionFile === undefined || typeof r.sessionFile === 'string'
+  return (
+    typeof r.adapter === 'string' &&
+    typeof r.workspace === 'string' &&
+    typeof r.chat === 'string' &&
+    (r.thread === null || typeof r.thread === 'string') &&
+    (r.sessionId === undefined || typeof r.sessionId === 'string') &&
+    (r.sessionFile === undefined || typeof r.sessionFile === 'string') &&
+    (r.lastInboundAt === undefined || typeof r.lastInboundAt === 'number') &&
+    Array.isArray(r.participants)
+  )
 }
 
 function describe(err: unknown): string {

package/src/channels/router.ts

@@ -6,7 +6,9 @@ import { SessionManager } from '@mariozechner/pi-coding-agent'
 import { createSession, type AgentSession } from '@/agent'
 import type { ChannelParticipant, SessionOrigin } from '@/agent/session-origin'
 import { createCommandRegistry } from '@/commands'
+import { CORE_PERMISSIONS, type PermissionService } from '@/permissions'
 import type { HookBus } from '@/plugin'
+import { extractClaimCode } from '@/role-claim'
 
 import { decideEngagement, grantStickyForReplyTargets, StickyLedger, type EngagementDecision } from './engagement'
 import {
@@ -75,6 +77,18 @@ export const MAX_TYPING_HEARTBEAT_MS = 2 * 60 * 1000
 export const SESSION_IDLE_MS = 30 * 60 * 1000
 export const SESSION_GC_INTERVAL_MS = 60 * 1000
 
+/**
+ * Maximum age of the last engaged inbound before the next inbound triggers a fresh session.
+ * Set to the LLM provider's KV-cache TTL (5 min) so the new session's system prompt is
+ * guaranteed to be a cache hit on the provider side.
+ *
+ * Unlike SESSION_IDLE_MS (which evicts the in-memory entry without rollover), this constant
+ * triggers a full tearDownLive + recreate on the next engaged inbound. The old session's
+ * transcript is preserved on disk; only the in-memory live entry and sessions.json pointer
+ * are replaced.
+ */
+export const SESSION_FRESHNESS_TTL_MS = 5 * 60 * 1000
+
 // Watchdog ceiling for ensureLive's full async chain (resolve names →
 // fetch membership → open session manager → persist mapping → prefetch
 // history). A legitimate cold-start completes in well under a second;
@@ -154,6 +168,12 @@ export type CreateSessionForChannel = (params: {
   existingSessionFile?: string
   participants: readonly ChannelParticipant[]
   origin: SessionOrigin
+  // Mutable holder the router updates per turn (with the current turn's
+  // lastInboundAuthorId, participants, etc.) so tool.before events stamp
+  // the live actor identity rather than the cold-start snapshot. The
+  // factory is expected to pass this through to createSession as
+  // `options.originRef`.
+  originRef: { current: SessionOrigin | undefined }
 }) => Promise<{
   session: AgentSession
   sessionId: string
@@ -201,6 +221,7 @@ type LiveSession = {
   getTranscriptPath: (() => string | undefined) | undefined
   participants: ChannelParticipant[]
   resolvedNames: ResolvedChannelNames
+  originRef: { current: SessionOrigin | undefined }
   promptQueue: QueuedInbound[]
   contextBuffer: ObservedInbound[]
   draining: boolean
@@ -308,6 +329,46 @@ export type CreateChannelRouterOptions = {
   // Test seam: bound the session.idle hook chain so the timeout path is
   // exercisable in tens of milliseconds instead of the 30s default.
   sessionIdleTimeoutMs?: number
+  // Wake-up gate: every inbound is gated by `permissions.has(partialOrigin,
+  // 'channel.respond')` BEFORE ensureLive. Required by the production
+  // wiring (manager.ts forwards `pluginsLoaded.permissions`); defaulted
+  // to a grant-all service inside the factory so existing direct test
+  // instantiations don't need to inject one. The default is intentionally
+  // permissive — the manager-to-router seam is the place where production
+  // injection is enforced; direct-router tests opt into gate semantics by
+  // passing their own service.
+  permissions?: PermissionService
+  // Optional role-claim handler. When set, the router intercepts DM
+  // inbounds whose text contains a claim code BEFORE the channel.respond
+  // gate, hands the inbound to the handler, and short-circuits the normal
+  // route path (no session creation, no permission check, no engagement
+  // pipeline). The handler returns the reply text the router should send
+  // back over the same chat, or null to fall through to normal routing
+  // when no pending claim window matches.
+  claimHandler?: ClaimHandler
+}
+
+export type ClaimHandlerInput = {
+  adapter: ChannelKey['adapter']
+  workspace: string
+  chat: string
+  isDm: boolean
+  authorId: string
+  text: string
+}
+
+export type ClaimHandlerOutcome =
+  | { kind: 'consumed'; reply: string }
+  | { kind: 'fail'; reply: string }
+  | { kind: 'fallthrough' }
+
+export type ClaimHandler = (input: ClaimHandlerInput) => Promise<ClaimHandlerOutcome>
+
+const GRANT_ALL_PERMISSIONS: PermissionService = {
+  has: () => true,
+  resolveRole: () => 'owner',
+  describe: () => ({ role: 'owner', permissions: [CORE_PERMISSIONS.channelRespond] }),
+  replaceRoles: () => {},
 }
 
 export function createChannelRouter(options: CreateChannelRouterOptions): ChannelRouter {
@@ -317,6 +378,8 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
   const resolveChannelNamesTimeoutMs = options.resolveChannelNamesTimeoutMs ?? RESOLVE_CHANNEL_NAMES_TIMEOUT_MS
   const fetchHistoryTimeoutMs = options.fetchHistoryTimeoutMs ?? FETCH_HISTORY_TIMEOUT_MS
   const sessionIdleTimeoutMs = options.sessionIdleTimeoutMs ?? SESSION_IDLE_TIMEOUT_MS
+  const permissions = options.permissions ?? GRANT_ALL_PERMISSIONS
+  const claimHandler = options.claimHandler
   const liveSessions = new Map<string, LiveSession>()
   const creating = new Map<string, Promise<LiveSession>>()
   const outboundCallbacks = new Map<ChannelKey['adapter'], Set<OutboundCallback>>()
@@ -355,6 +418,7 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
 
   let mappings: ChannelSessionRecord[] | null = null
   let loadOnce: Promise<void> | null = null
+  let persistChain: Promise<void> = Promise.resolve()
 
   const ensureLoaded = async (): Promise<void> => {
     if (mappings !== null) return
@@ -368,12 +432,16 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
 
   const persist = async (): Promise<void> => {
     if (mappings === null) return
-    await saveChannelSessions(options.agentDir, mappings, logger)
+    persistChain = persistChain.then(async () => {
+      if (mappings === null) return
+      await saveChannelSessions(options.agentDir, mappings, logger)
+    })
+    await persistChain
   }
 
   const createForChannel: CreateSessionForChannel =
     options.createSessionForChannel ??
-    (async ({ key, existingSessionId, existingSessionFile, origin }) => {
+    (async ({ key, existingSessionId, existingSessionFile, origin, originRef }) => {
       const sessionDir = options.sessionDir ?? `${options.agentDir}/sessions`
       const sessionManager =
         existingSessionId !== undefined
@@ -382,6 +450,7 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
       const session = await createSession({
         sessionManager,
         origin,
+        originRef,
       })
       const sessionId = sessionManager.getSessionId()
       void key
@@ -476,10 +545,44 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
     return membership
   }
 
-  const ensureLive = async (key: ChannelKey, triggeringMessageId?: string): Promise<LiveSession> => {
+  const ensureLive = async (
+    key: ChannelKey,
+    triggeringMessageId?: string,
+    triggeringAuthorId?: string,
+  ): Promise<LiveSession> => {
     const keyId = channelKeyId(key)
     const existing = liveSessions.get(keyId)
-    if (existing && !existing.destroyed) return existing
+    if (existing && !existing.destroyed) {
+      const idleMs = now() - existing.lastInboundAt
+      if (idleMs > SESSION_FRESHNESS_TTL_MS) {
+        logger.info(`[channels] ${keyId}: stale-rollover (live: ${idleMs}ms idle)`)
+        await tearDownLive(existing)
+        liveSessions.delete(keyId)
+        if (mappings) {
+          const idx = mappings.findIndex(
+            (s) =>
+              s.adapter === key.adapter &&
+              s.workspace === key.workspace &&
+              s.chat === key.chat &&
+              (s.thread ?? null) === (key.thread ?? null),
+          )
+          if (idx >= 0) {
+            const prev = mappings[idx]!
+            mappings[idx] = {
+              adapter: prev.adapter,
+              workspace: prev.workspace,
+              chat: prev.chat,
+              thread: prev.thread,
+              participants: prev.participants,
+              lastInboundAt: 0,
+            }
+            await persist()
+          }
+        }
+      } else {
+        return existing
+      }
+    }
 
     const inFlight = creating.get(keyId)
     if (inFlight) return inFlight
@@ -487,14 +590,51 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
     const promise = (async () => {
       await ensureLoaded()
       const record = mappings ? findRecord(mappings, key) : undefined
-      const phase = record?.sessionId === undefined ? 'cold-start' : 'rehydrate'
+      let resolvedRecord = record
+      if (
+        record?.sessionId !== undefined &&
+        existing === undefined &&
+        now() - (record.lastInboundAt ?? 0) > SESSION_FRESHNESS_TTL_MS
+      ) {
+        const idleMs = now() - (record.lastInboundAt ?? 0)
+        logger.info(`[channels] ${keyId}: stale-rollover (persisted: ${idleMs}ms idle)`)
+        resolvedRecord = {
+          adapter: record.adapter,
+          workspace: record.workspace,
+          chat: record.chat,
+          thread: record.thread,
+          participants: record.participants,
+          lastInboundAt: 0,
+        }
+        if (mappings) {
+          const idx = mappings.findIndex(
+            (s) =>
+              s.adapter === key.adapter &&
+              s.workspace === key.workspace &&
+              s.chat === key.chat &&
+              (s.thread ?? null) === (key.thread ?? null),
+          )
+          if (idx >= 0) {
+            mappings[idx] = resolvedRecord
+            await persist()
+          }
+        }
+      }
+      const phase = resolvedRecord?.sessionId === undefined ? 'cold-start' : 'rehydrate'
       logger.info(`[channels] ${keyId}: ensureLive begin (${phase})`)
-      const participants = (record?.participants ?? []) as ChannelParticipant[]
+      const participants = (resolvedRecord?.participants ?? []) as ChannelParticipant[]
       const membershipFetch = warmMembership(key)
       const resolvedNames = await resolveChannelNames(key)
       logger.info(`[channels] ${keyId}: ensureLive resolved-names`)
       const membership = await membershipForPrompt(key, membershipFetch)
       logger.info(`[channels] ${keyId}: ensureLive resolved-membership`)
+      // The session-creation origin is what the resource loader sees when it
+      // renders the role/permissions block into the system prompt. It must
+      // include the triggering author so author-scoped roles
+      // (`slack:T/C author:U_ME`) resolve to the same role here that the
+      // channel.respond gate just admitted on. Per-turn updates after this
+      // point are handled by `originRef.current = buildLiveOrigin(live)`
+      // before each prompt() call.
       const origin: SessionOrigin = {
         kind: 'channel',
         adapter: key.adapter,
@@ -503,18 +643,24 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
         chat: key.chat,
         ...(resolvedNames.chatName !== undefined ? { chatName: resolvedNames.chatName } : {}),
         thread: key.thread,
+        ...(triggeringAuthorId !== undefined ? { lastInboundAuthorId: triggeringAuthorId } : {}),
         participants,
         ...(membership !== null ? { membership } : {}),
       }
 
-      const isColdStart = record?.sessionId === undefined
+      const isColdStart = resolvedRecord?.sessionId === undefined
+
+      // The router writes into this holder before every prompt() so the
+      // tool wrappers' getOrigin() sees the current-turn origin.
+      const originRef: { current: SessionOrigin | undefined } = { current: origin }
 
       const created = await createForChannel({
         key,
-        ...(record?.sessionId ? { existingSessionId: record.sessionId } : {}),
-        ...(record?.sessionFile ? { existingSessionFile: record.sessionFile } : {}),
+        ...(resolvedRecord?.sessionId ? { existingSessionId: resolvedRecord.sessionId } : {}),
+        ...(resolvedRecord?.sessionFile ? { existingSessionFile: resolvedRecord.sessionFile } : {}),
         participants,
         origin,
+        originRef,
       })
       logger.info(`[channels] ${keyId}: ensureLive session-created sessionId=${created.sessionId}`)
 
@@ -526,6 +672,7 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
         thread: key.thread,
         sessionId: created.sessionId,
         ...(transcriptPath ? { sessionFile: basename(transcriptPath) } : {}),
+        lastInboundAt: now(),
         participants,
       }
       if (mappings) {
@@ -553,6 +700,7 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
         getTranscriptPath: created.getTranscriptPath,
         participants,
         resolvedNames,
+        originRef,
         promptQueue: [],
         contextBuffer: [],
         draining: false,
@@ -697,8 +845,6 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
     await persist()
   }
 
-  const regenerateOrigin = (live: LiveSession): SessionOrigin => buildLiveOrigin(live)
-
   const fireTyping = async (live: LiveSession, phase: 'tick' | 'stop'): Promise<void> => {
     const callbacks = typingCallbacks.get(live.key.adapter)
     if (!callbacks || callbacks.size === 0) return
@@ -860,13 +1006,13 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
         live.currentTurnAuthorIds = new Set(batch.map((m) => m.authorId))
         if (batch.length > 0) live.consecutiveSends.clear()
 
-        // The agent's view of the channel should reflect the current
-        // participants + last inbound author. We update the in-memory
-        // origin via the session-origin renderer, but the loader was
-        // captured at session creation. v0.1 keeps the per-session loader
-        // (so origin reflects participants at session-creation time);
-        // per-prompt regeneration of system prompts is a v0.2 work.
-        void regenerateOrigin
+        // Update the live origin holder so this turn's tool.before events
+        // carry the current actor's id. The DefaultResourceLoader still
+        // renders the session-creation origin into the system prompt (v0.2
+        // work to regenerate that per-turn); but permission gating off
+        // `lastInboundAuthorId` happens in the tool layer and now sees the
+        // live value.
+        live.originRef.current = buildLiveOrigin(live)
 
         // Bracketing logs around the LLM call so a hung prompt() is
         // diagnosable from logs alone (we see prompting without prompted).
@@ -906,6 +1052,19 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
     const elapsedSinceFirst = t - live.firstUnprocessedAt
     const wait = Math.max(0, Math.min(baseWait, MAX_DEBOUNCE_MS - elapsedSinceFirst))
     live.lastInboundAt = t
+    if (mappings) {
+      const idx = mappings.findIndex(
+        (s) =>
+          s.adapter === live.key.adapter &&
+          s.workspace === live.key.workspace &&
+          s.chat === live.key.chat &&
+          (s.thread ?? null) === (live.key.thread ?? null),
+      )
+      if (idx >= 0) {
+        mappings[idx] = { ...mappings[idx]!, lastInboundAt: t }
+        void persist()
+      }
+    }
     live.debounceTimer = setTimeout(() => {
       live.debounceTimer = null
       live.firstUnprocessedAt = 0
@@ -924,8 +1083,46 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
       thread: event.thread,
     }
 
+    // Role-claim intercept runs BEFORE the channel.respond gate so the
+    // operator can bootstrap permissions on a fresh agent that has no
+    // role match rules yet. Cheap pre-check: only DMs whose text contains
+    // a `claim-` prefix can be claim attempts, and only when a handler
+    // is registered. Everything else falls straight through to the gate.
+    if (claimHandler !== undefined && event.isDm && extractClaimCode(event.text) !== null) {
+      const outcome = await claimHandler({
+        adapter: event.adapter,
+        workspace: event.workspace,
+        chat: event.chat,
+        isDm: event.isDm,
+        authorId: event.authorId,
+        text: event.text,
+      })
+      if (outcome.kind !== 'fallthrough') {
+        logger.info(
+          `[channels] ${channelKeyId(key)}: claim ${outcome.kind} author=${event.authorId} id=${event.externalMessageId}`,
+        )
+        await send({
+          adapter: event.adapter,
+          workspace: event.workspace,
+          chat: event.chat,
+          thread: event.thread,
+          text: outcome.reply,
+        })
+        return
+      }
+    }
+
+    if (isChannelRespondDenied(event)) {
+      logger.info(
+        `[channels] ${channelKeyId(key)}: denied by permissions (channel.respond) author=${event.authorId} id=${event.externalMessageId}`,
+      )
+      return
+    }
+
     const parsedCommand = commands.parse(event.text)
     if (parsedCommand !== null) {
+      // Commands are control traffic, not engaged inbounds; if the session is stale,
+      // the next engaged inbound will perform the rollover before prompting.
       const keyId = channelKeyId(key)
       if (!commands.has(parsedCommand.name)) {
         logger.info(`[channels] ${keyId}: ignoring unknown command /${parsedCommand.name}`)
@@ -940,7 +1137,7 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
       if (commandResult.kind !== 'not-command') return
     }
 
-    const live = await ensureLive(key, event.externalMessageId)
+    const live = await ensureLive(key, event.externalMessageId, event.authorId)
 
     const isNewAuthor = !live.participants.some((p) => p.authorId === event.authorId)
     live.participants = updateParticipants(
@@ -1010,6 +1207,18 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
     scheduleDebouncedDrain(live)
   }
 
+  const isChannelRespondDenied = (event: InboundMessage): boolean => {
+    const partial: SessionOrigin = {
+      kind: 'channel',
+      adapter: event.adapter,
+      workspace: event.workspace,
+      chat: event.chat,
+      thread: event.thread,
+      lastInboundAuthorId: event.authorId,
+    }
+    return !permissions.has(partial, CORE_PERMISSIONS.channelRespond)
+  }
+
   const updateLoopGuard = (live: LiveSession, event: InboundMessage): void => {
     if (!event.authorIsBot) {
       live.recentEngagedPeerBotTurns.length = 0