@modesto_ma/dsh-channels 0.2.0 → 0.4.0

package/src/session/isolation.ts

@@ -0,0 +1,277 @@
+/**
+ * Per-topic Session placement: which directory each Feishu conversation works
+ * in, without growing the host workspace list with every topic.
+ *
+ * A Session's **header cwd** is fixed at creation and decides two things:
+ * its workspace-registry membership (the GUI project it is grouped under) and
+ * the sandbox write boundary. The **effective working directory** is a mutable
+ * Session projection (`ctx.workingDirectory`), persisted in the Session log
+ * and restored on resume; the bash/fs/terminal tools resolve it before every
+ * call.
+ *
+ * This module plans one topic's placement:
+ *
+ * - `subdir`: `<workspace>/topics/<token>` — a plain directory switched to via
+ *   `workingDirectory.set`.
+ * - `worktree`: a Git worktree created through `ctx.worktrees` (branch
+ *   `feishu-<token>`), used when the workspace is a Git repository or when the
+ *   deployment forces it.
+ *
+ * Both modes keep the Session's header cwd on the workspace root, so the
+ * Session stays grouped under the user's project. When the host exposes no
+ * `workingDirectory` service (unusual: it ships with `dsh-base`), the Session
+ * is created directly in the topic directory instead — file isolation still
+ * holds, but the Session can no longer be attached to the workspace.
+ *
+ * @module dsh-channels/session/isolation
+ */
+
+import { randomUUID } from 'node:crypto'
+import { mkdir, stat } from 'node:fs/promises'
+import path from 'node:path'
+import type { Agent, HostContext, Session } from '../dsh-types.ts'
+import type { FeishuConfig } from '../config.ts'
+import { topicDirFor, worktreeBranchFor } from '../workspaces.ts'
+
+// ---- Host service slices (structural, resolved through ctx.get) ----------
+
+/**
+ * The effective-directory service (`@deepseek-ai/dsh-working-directory`,
+ * mounted by every base-backed profile). `set` appends a durable
+ * `working-directory/change` event and queues a user-context notice.
+ */
+export interface WorkingDirectoryService {
+  get(session: Session): string
+  set(agent: Agent, path: string, signal?: AbortSignal): Promise<string>
+}
+
+/** One created Git worktree checkout (`ctx.worktrees.create` result). */
+export interface CreatedWorktree {
+  path: string
+  branch: string
+  baseCommit: string
+  repositoryRoot: string
+}
+
+/**
+ * The optional Git-worktree service (`@deepseek-ai/dsh-experimental-worktree`).
+ * It is not mounted everywhere, so every use is guarded.
+ */
+export interface WorktreeService {
+  create(
+    agent: Agent,
+    request?: { name?: string; from?: string },
+    signal?: AbortSignal,
+  ): Promise<CreatedWorktree>
+}
+
+/** Placement capabilities resolved once per call site. */
+export interface PlacementServices {
+  workingDirectory?: WorkingDirectoryService
+  worktrees?: WorktreeService
+}
+
+/** Resolve the placement capabilities from the host context (all optional). */
+export function placementServices(ctx: HostContext): PlacementServices {
+  const get = <T>(name: string): T | undefined => ctx.get?.(name) as T | undefined
+  return {
+    workingDirectory: get<WorkingDirectoryService>('workingDirectory'),
+    worktrees: get<WorktreeService>('worktrees'),
+  }
+}
+
+/** Isolation mode actually used for one topic. */
+export type TopicMode = 'subdir' | 'worktree'
+
+/** What the caller needs before creating the Session. */
+export interface TopicPlan {
+  /** Isolation mode chosen for this topic. */
+  readonly mode: TopicMode
+  /** Directory to pass as `meta.cwd` (the Session header cwd). */
+  readonly cwd: string
+  /** Topic directory for `subdir` mode (already created). */
+  readonly subdir?: string
+  /** Whether the deployment can switch the Session's working directory. */
+  readonly switchable: boolean
+}
+
+/** Where one topic's Session actually works. */
+export interface TopicPlacement {
+  /** Effective working directory (`working-directory` projection value). */
+  readonly sessionDir: string
+  /** Git branch owning `sessionDir` when it is a worktree checkout. */
+  readonly worktreeBranch?: string
+}
+
+/** Structured logger slice; best-effort warnings never throw. */
+export type PlacementWarn = (message: string, ...args: unknown[]) => void
+
+/** Whether the workspace directory is itself a Git working tree. */
+export async function workspaceHasGitRepository(workspacePath: string): Promise<boolean> {
+  try {
+    const info = await stat(path.join(workspacePath, '.git'))
+    return info.isDirectory() || info.isFile()
+  } catch {
+    return false
+  }
+}
+
+/**
+ * Pick the isolation mode for one topic. `auto` upgrades to a worktree only
+ * when both the capability and a Git repository are present; an explicit
+ * `worktree` preference still falls back (with a warning) when unavailable.
+ */
+async function chooseTopicMode(
+  services: PlacementServices,
+  config: FeishuConfig,
+  workspacePath: string,
+  warn: PlacementWarn,
+): Promise<TopicMode> {
+  const requested = config.topicIsolation
+  if (requested === 'subdir') return 'subdir'
+  const capable = services.workingDirectory !== undefined && services.worktrees !== undefined
+  if (!capable) {
+    if (requested === 'worktree') {
+      warn('dsh-channels: topicIsolation=worktree needs the workingDirectory and worktrees host services; using a plain topic directory')
+    }
+    return 'subdir'
+  }
+  if (requested === 'worktree') return 'worktree'
+  return await workspaceHasGitRepository(workspacePath) ? 'worktree' : 'subdir'
+}
+
+/**
+ * Decide how a new Session is placed and materialize everything that must
+ * exist before the Session is created.
+ *
+ * The returned `cwd` is the header cwd: the workspace root when the runtime
+ * can switch directories (so the Session is grouped under the user's project),
+ * otherwise the topic directory itself.
+ */
+export async function planTopic(
+  services: PlacementServices,
+  config: FeishuConfig,
+  workspacePath: string,
+  topicToken: string,
+  warn: PlacementWarn,
+): Promise<TopicPlan> {
+  const mode = await chooseTopicMode(services, config, workspacePath, warn)
+  if (services.workingDirectory !== undefined) {
+    const subdir = mode === 'subdir' ? topicDirFor(workspacePath, topicToken) : undefined
+    if (subdir !== undefined) await mkdir(subdir, { recursive: true })
+    return {
+      mode,
+      cwd: workspacePath,
+      ...(subdir === undefined ? {} : { subdir }),
+      switchable: true,
+    }
+  }
+  // No effective-directory service: create the Session inside the topic
+  // directory itself. Isolation is preserved; workspace membership is lost.
+  const subdir = topicDirFor(workspacePath, topicToken)
+  await mkdir(subdir, { recursive: true })
+  return { mode: 'subdir', cwd: subdir, subdir, switchable: false }
+}
+
+/** Enter the planned topic directory once the Session (and its Agent) exists. */
+export async function enterTopic(
+  services: PlacementServices,
+  agent: Agent,
+  plan: TopicPlan,
+  workspacePath: string,
+  topicToken: string,
+  warn: PlacementWarn,
+): Promise<TopicPlacement> {
+  if (plan.mode === 'worktree' && services.worktrees !== undefined) {
+    try {
+      const created = await services.worktrees.create(agent, { name: worktreeBranchFor(topicToken) })
+      return { sessionDir: created.path, worktreeBranch: created.branch }
+    } catch (error) {
+      warn(
+        'dsh-channels: creating a worktree for topic %s failed, using a plain topic directory instead: %s',
+        topicToken, String(error),
+      )
+    }
+  }
+  const dir = plan.subdir ?? topicDirFor(workspacePath, topicToken)
+  await mkdir(dir, { recursive: true })
+  if (plan.switchable) await alignWorkingDirectory(services, agent, dir, warn)
+  return { sessionDir: dir }
+}
+
+/**
+ * Align one live Session with its recorded topic directory: make sure the
+ * directory exists, recreate it (or a fresh worktree) when it disappeared,
+ * and restore the effective working directory the route expects.
+ *
+ * The returned placement may carry a new directory/branch after recovery; the
+ * caller persists it back into the route record.
+ */
+export async function restoreTopicDir(
+  services: PlacementServices,
+  agent: Agent,
+  input: {
+    readonly workspacePath: string
+    readonly sessionDir: string
+    readonly worktreeBranch?: string
+  },
+  warn: PlacementWarn,
+): Promise<TopicPlacement> {
+  const { sessionDir, worktreeBranch } = input
+  if (await isDirectory(sessionDir)) {
+    await alignWorkingDirectory(services, agent, sessionDir, warn)
+    return worktreeBranch === undefined ? { sessionDir } : { sessionDir, worktreeBranch }
+  }
+  // The directory is gone (manual deletion, external cleanup, lost host):
+  // give the Session a fresh directory so it never silently falls back to the
+  // shared workspace root.
+  if (worktreeBranch !== undefined
+    && services.worktrees !== undefined
+    && services.workingDirectory !== undefined) {
+    try {
+      const created = await services.worktrees.create(agent, {
+        name: `${worktreeBranch}-r${randomUUID().slice(0, 8)}`,
+      })
+      return { sessionDir: created.path, worktreeBranch: created.branch }
+    } catch (error) {
+      warn(
+        'dsh-channels: recreating the worktree for session %s failed, using a plain directory: %s',
+        agent.id, String(error),
+      )
+    }
+  }
+  await mkdir(sessionDir, { recursive: true })
+  await alignWorkingDirectory(services, agent, sessionDir, warn)
+  return { sessionDir }
+}
+
+/** Best-effort check used only for placement decisions, never for security. */
+async function isDirectory(dir: string): Promise<boolean> {
+  try {
+    return (await stat(dir)).isDirectory()
+  } catch {
+    return false
+  }
+}
+
+/** Point the Session's effective working directory at `dir`. */
+async function alignWorkingDirectory(
+  services: PlacementServices,
+  agent: Agent,
+  dir: string,
+  warn: PlacementWarn,
+): Promise<void> {
+  const workingDirectory = services.workingDirectory
+  if (workingDirectory === undefined) return
+  try {
+    if (workingDirectory.get(agent.session) === dir) return
+    await workingDirectory.set(agent, dir)
+  } catch (error) {
+    // The durable Session keeps its previous directory; the caller cannot do
+    // better than warning because the turn is still deliverable.
+    warn(
+      'dsh-channels: switching session %s to its topic directory failed: %s',
+      agent.id, String(error),
+    )
+  }
+}

package/src/session/manager.ts

@@ -25,12 +25,15 @@ import type {
 } from '../dsh-types.ts'
 import type { FeishuConfig } from '../config.ts'
 import { mountChannelCommands } from '../commands.ts'
-import { appendSessionHistory } from '../domain.ts'
+import { appendSessionHistory, sessionDirOf } from '../domain.ts'
 import type { RouteRecord } from '../domain.ts'
 import { mountChannelGuidance } from '../feishu/agent-context.ts'
 import { attachmentsDir } from '../feishu/inbound-attachments.ts'
+import { effectiveAttachmentMode, resolveAttachmentService } from '../feishu/native-attachments.ts'
 import { installRequestPolicy } from './request-policy.ts'
 import type { RequestPolicyController } from './request-policy.ts'
+import { placementServices, restoreTopicDir } from './isolation.ts'
+import type { PlacementServices, TopicPlacement } from './isolation.ts'
 import { workspaceTitleFor } from '../workspaces.ts'
 
 /** One live agent plus this plugin's ownership handle. */
@@ -63,6 +66,14 @@ export interface SessionManagerDeps {
   started(): boolean
   /** Drop streamer state for a session whose owner handle is being released. */
   detachStream(sessionId: string): void
+  /**
+   * Register this channel's model tools inside one Agent scope. Called from
+   * the agent-preset `setup` after the preset is mounted (tools live inside
+   * presets in web-profile deployments), and once more for a BORROWED live
+   * agent as a best-effort race guard (D7). Optional: unit tests that do not
+   * compose model tools omit it.
+   */
+  mountTools?(agentCtx: AgentContext, sessionId: string): Promise<void> | void
   warn(message: string, ...args: unknown[]): void
 }
 
@@ -80,6 +91,8 @@ export class SessionManager {
   private readonly live = new Map<string, LiveAgent>()
   private readonly pendingResume = new Map<string, Promise<LiveAgent>>()
   private readonly policies = new WeakMap<AgentContext, RequestPolicyController>()
+  /** Agent scopes this plugin already attempted to mount model tools into. */
+  private readonly toolMounts = new WeakSet<AgentContext>()
 
   constructor(private readonly deps: SessionManagerDeps) {}
 
@@ -105,14 +118,16 @@ export class SessionManager {
 
   /**
    * Create the root agent for one freshly routed session and register it live.
-   * The caller owns the workspace attachment and the failure card.
+   * `cwd` is the Session header cwd (the user workspace when the deployment can
+   * switch directories). The caller owns placement, the workspace attachment,
+   * the attachment guidance, and the failure card.
    */
   async createSession(
     sessionId: SessionId,
     cwd: string,
     agentOptions: Record<string, unknown> = this.agentOptions(),
   ): Promise<AgentHandle> {
-    const composition = await this.presetComposition(undefined, true, attachmentsDir(cwd))
+    const composition = await this.presetComposition(undefined, true, sessionId)
     const handle = await this.deps.ctx.agents.create({
       sessionId,
       meta: {
@@ -127,6 +142,40 @@ export class SessionManager {
     return handle
   }
 
+  /**
+   * Register the attachment guidance for one Session. Called after the
+   * effective working directory is known (a worktree checkout path is only
+   * returned once the worktree exists), so the archive guidance can name the
+   * absolute directory. The guidance flavor follows the *effective* attachment
+   * backend: an explicitly configured archive deployment, or a native
+   * deployment whose host does not mount `ctx.attachments`, keeps the legacy
+   * workspace-directory instructions. Best-effort: a missing system-prompt
+   * service (headless) is a no-op and a late registration never blocks the turn.
+   */
+  async mountGuidance(agent: Agent, directory: string): Promise<void> {
+    // With inbound attachments disabled the Agent has no attachment workflow to
+    // discover (and the legacy guidance would wrongly claim files are archived).
+    if (!this.deps.config.acceptAttachments) return
+    const mode = effectiveAttachmentMode(
+      this.deps.config.attachmentStore,
+      resolveAttachmentService(this.deps.ctx),
+      this.deps.config.feishuTools.attachmentFetch,
+      this.deps.config.acceptAttachments,
+    )
+    try {
+      await mountChannelGuidance(
+        agent.ctx,
+        mode,
+        mode === 'archive' ? attachmentsDir(directory) : undefined,
+      )
+    } catch (error) {
+      this.deps.warn(
+        'dsh-channels: mounting attachment guidance for session %s failed: %s',
+        agent.id, String(error),
+      )
+    }
+  }
+
   /**
    * Live agent for a route: this plugin's own → a foreign live agent (borrow)
    * → a serialized cold resume.
@@ -144,7 +193,7 @@ export class SessionManager {
     if (own !== undefined) return own
 
     const foreign = this.deps.ctx.agents.get(sessionId as SessionId)
-    if (foreign !== undefined) return this.borrow(sessionId, foreign)
+    if (foreign !== undefined) return await this.borrow(sessionId, foreign)
 
     let pending = this.pendingResume.get(sessionId)
     if (pending === undefined) {
@@ -157,9 +206,14 @@ export class SessionManager {
   }
 
   /** Borrow one foreign live agent and mount this channel's scoped policy. */
-  private borrow(sessionId: string, agent: Agent): LiveAgent {
+  private async borrow(sessionId: string, agent: Agent): Promise<LiveAgent> {
     const borrowed = borrowLiveAgent(agent, this.mountRequestPolicy(agent.ctx, agent.session))
     this.live.set(sessionId, borrowed)
+    // Best-effort tool backfill (D7): the foreign owner may have composed the
+    // session without this plugin's setup (web UI resolver, previous plugin
+    // instance). mountToolsFor swallows failures, so the borrow itself never
+    // fails; awaiting it makes the tool available before the first turn.
+    await this.mountToolsFor(agent.ctx, sessionId)
     return borrowed
   }
 
@@ -171,9 +225,7 @@ export class SessionManager {
       // (config override or roster default). A session persisted before the
       // preset fix has no preset recorded on its header; re-resolving here is
       // what repairs it on the first resume after a restart.
-      const composition = await this.presetComposition(
-        undefined, true, attachmentsDir(record.workspacePath),
-      )
+      const composition = await this.presetComposition(undefined, true, sessionId)
       const handle = await this.deps.ctx.agents.resume({
         resumeSessionId: sessionId,
         agentOptions: this.agentOptions(),
@@ -187,6 +239,7 @@ export class SessionManager {
         throw new Error('dsh-channels: session resume aborted by shutdown')
       }
       this.requestPolicy(handle.agent)
+      await this.mountGuidance(handle.agent, sessionDirOf(record))
       const liveAgent: LiveAgent = { agent: handle.agent, handle }
       this.live.set(sessionId, liveAgent)
       return liveAgent
@@ -194,7 +247,7 @@ export class SessionManager {
       // Lost a cold-resume race: another owner published the session while our
       // resume was in flight. Borrow the winner instead of failing the turn.
       const winner = this.deps.ctx.agents.get(sessionId)
-      if (winner !== undefined) return this.borrow(sessionId, winner)
+      if (winner !== undefined) return await this.borrow(sessionId, winner)
       throw error
     }
   }
@@ -224,17 +277,23 @@ export class SessionManager {
     return controller
   }
 
-  /** Create, workspace-attach, and atomically publish one renewed route. */
+  /**
+   * Create, place, workspace-attach, and atomically publish one renewed route.
+   *
+   * A renewal keeps the topic's working directory: the new Session is created
+   * with the user workspace as its header cwd (so it stays grouped under the
+   * project) and then re-entered into the same topic directory or worktree.
+   */
   async renew(record: RouteRecord, oldLive: LiveAgent): Promise<RenewCommit> {
     const sessionId = randomUUID() as SessionId
     const preset = this.effectivePreset(oldLive.agent.session)
-    const composition = await this.presetComposition(preset, false, attachmentsDir(record.workspacePath))
+    const composition = await this.presetComposition(preset, false, sessionId)
+    const services: PlacementServices = placementServices(this.deps.ctx)
+    const switchable = services.workingDirectory !== undefined
+    const workspacePath = record.workspacePath
     const workspace = await this.deps.ctx.workspaceRegistry.create(
-      record.workspacePath,
-      workspaceTitleFor(
-        record.chatType, record.chatId, record.senderOpenId,
-        record.kind === 'thread' ? record.key : record.sessionId,
-      ),
+      workspacePath,
+      workspaceTitleFor(record.chatType, record.chatId, record.senderOpenId),
     )
 
     let newHandle: AgentHandle | undefined
@@ -243,23 +302,38 @@ export class SessionManager {
       newHandle = await this.deps.ctx.agents.create({
         sessionId,
         meta: {
-          cwd: record.workspacePath,
+          // Without an effective-directory service the Session must be born in
+          // its topic directory; otherwise the workspace root keeps it grouped.
+          cwd: switchable ? workspacePath : sessionDirOf(record),
           ...(composition.agentPreset === undefined ? {} : { agentPreset: composition.agentPreset }),
         },
         agentOptions: { ...oldLive.agent.options },
         setup: composition.setup,
       })
       this.requestPolicy(newHandle.agent)
-      await workspace.attachSession(sessionId)
-      attached = true
+      const placement: TopicPlacement = await restoreTopicDir(services, newHandle.agent, {
+        workspacePath,
+        sessionDir: sessionDirOf(record),
+        ...(record.worktreeBranch === undefined ? {} : { worktreeBranch: record.worktreeBranch }),
+      }, this.deps.warn.bind(this.deps))
+      if (switchable) {
+        await workspace.attachSession(sessionId)
+        attached = true
+      }
+      await this.mountGuidance(newHandle.agent, placement.sessionDir)
       const createdAt = newHandle.agent.session.header.createdAt
 
-      const current: RouteRecord = {
+      const base: RouteRecord = {
         ...record,
         sessionId,
         sessionHistory: appendSessionHistory(record, sessionId, createdAt),
         lastActivityAt: Date.now(),
+        sessionDir: placement.sessionDir,
       }
+      delete base.worktreeBranch
+      const current: RouteRecord = placement.worktreeBranch === undefined
+        ? base
+        : { ...base, worktreeBranch: placement.worktreeBranch }
       await this.deps.persistRoute(record.key, current)
       this.live.set(sessionId, { agent: newHandle.agent, handle: newHandle })
       return { previous: record, current, oldLive }
@@ -308,11 +382,15 @@ export class SessionManager {
    * resumes. The id resolves BEFORE the session exists because the session
    * boundary snapshots `meta` before asynchronous setup begins; mounting stays
    * inside `setup`, where a failure rolls the whole creation back.
+   *
+   * The attachment guidance is mounted later through {@link mountGuidance},
+   * because a Git worktree's checkout path only exists after the Agent (and so
+   * the worktree) has been created.
    */
   private async presetComposition(
     requestedPreset: string | undefined = this.deps.config.agentPreset,
     useRosterDefault = true,
-    attachmentsDir?: string,
+    sessionId?: string,
   ): Promise<PresetComposition> {
     // Read through ctx.get (safe lookup): only the web profile ships a roster,
     // and direct property access on a cordis context throws for services the
@@ -324,7 +402,7 @@ export class SessionManager {
       // cannot guarantee that the explicit channel value wins.
       this.mountRequestPolicy(agentCtx)
       await mountChannelCommands(agentCtx)
-      await mountChannelGuidance(agentCtx, attachmentsDir)
+      if (sessionId !== undefined) await this.mountToolsFor(agentCtx, sessionId)
     }
     if (presets === undefined || (requestedPreset === undefined && !useRosterDefault)) {
       return { setup: channelCommandsOnly }
@@ -336,11 +414,30 @@ export class SessionManager {
         this.mountRequestPolicy(agentCtx)
         await presets.mount(agentCtx, resolved.id)
         await mountChannelCommands(agentCtx)
-        await mountChannelGuidance(agentCtx, attachmentsDir)
+        if (sessionId !== undefined) await this.mountToolsFor(agentCtx, sessionId)
       },
     }
   }
 
+  /**
+   * Mount the channel model tools into one Agent scope, at most once per
+   * scope. A failure is logged and swallowed: missing tools never fail a
+   * session (attachment fetch degrades to its structured failures).
+   */
+  private async mountToolsFor(agentCtx: AgentContext, sessionId: string): Promise<void> {
+    if (this.deps.mountTools === undefined) return
+    if (this.toolMounts.has(agentCtx)) return
+    try {
+      await this.deps.mountTools(agentCtx, sessionId)
+      this.toolMounts.add(agentCtx)
+    } catch (error) {
+      this.deps.warn(
+        'dsh-channels: mounting channel tools for session %s failed: %s',
+        sessionId, String(error),
+      )
+    }
+  }
+
   /** Effective preset after folding any durable runtime preset switch. */
   private effectivePreset(session: Session): string | undefined {
     let selected = session.header.agentPreset

package/src/session/repair.ts

@@ -11,7 +11,7 @@
  * @module dsh-channels/session/repair
  */
 
-import { buildInterruptionCard } from '../cards/streaming.ts'
+import { buildInterruptionCard, segmentCardOptions } from '../cards/streaming.ts'
 import type { InflightSnapshot } from '../domain.ts'
 import type { FeishuChannel } from '../feishu-channel.ts'
 import type { FeishuDomainHandle } from '../domain.ts'
@@ -146,8 +146,7 @@ export class InflightRepair {
       if (card.mode !== 'card') continue
       // Full replacement: the interrupted card's streamed content lived only
       // in the previous process. Continuation cards keep their segment header.
-      const options = index === 0 ? {} : { panel: false, segment: index + 1 }
-      await channel.updateCard(card.messageId, buildInterruptionCard(options))
+      await channel.updateCard(card.messageId, buildInterruptionCard(segmentCardOptions(index)))
     }
     if (snapshot.reactionId !== undefined) {
       await channel.removeReaction(snapshot.triggerMessageId, snapshot.reactionId).catch(() => {})

package/src/session/routes.ts

@@ -148,6 +148,8 @@ export class RouteStore {
       senderOpenId: record.senderOpenId,
       expiredAt: now,
       workspacePath: record.workspacePath,
+      ...(record.sessionDir === undefined ? {} : { sessionDir: record.sessionDir }),
+      ...(record.worktreeBranch === undefined ? {} : { worktreeBranch: record.worktreeBranch }),
       lastActivityAt: record.lastActivityAt,
     }
     await this.deps.domain()?.expiredRoutes.put(key, tombstone)