@mengruo/dsh-vision-toolkit 0.0.1

package/src/evidence-cache.ts

@@ -0,0 +1,418 @@
+/** Durable, Session-scoped cache for image descriptions used by model variants. */
+
+import { createHash } from 'node:crypto'
+import type { Context, Fiber } from '@deepseek-ai/cordis'
+import type { ContentBlock } from '@deepseek-ai/dsh-llm'
+import type { SessionHeader, SessionId } from '@deepseek-ai/dsh-session'
+import { defineDomain, domainTable } from '@deepseek-ai/dsh-storage-domain'
+import type { KvTable } from '@deepseek-ai/dsh-storage-domain'
+import { z } from 'zod'
+import type { ResolvedVisionToolkitConfig } from './config.ts'
+import { UPSTREAM_COMMIT } from './version.ts'
+
+/** Bump only when the model-visible evidence contract changes incompatibly. */
+export const EVIDENCE_CONTRACT_VERSION = 1
+
+/** Persistent cache bounds keep the Profile storage proportional and predictable. */
+const DEFAULT_PERSISTED_ENTRY_LIMIT = 512
+const DEFAULT_PERSISTED_BYTE_LIMIT = 8 * 1024 * 1024
+const DEFAULT_PERSISTED_ENTRY_BYTE_LIMIT = 64 * 1024
+const MAX_SCHEMA_TEXT_CHARS = 256 * 1024
+const MAX_SCHEMA_RECORD_CHARS = 512 * 1024
+
+const hexDigestSchema = z.string().regex(/^[0-9a-f]{64}$/u)
+const sessionIdentitySchema = z.object({
+  createdAt: z.number().int().nonnegative().max(Number.MAX_SAFE_INTEGER),
+  cwd: z.string().optional(),
+})
+const evidenceRecordSchema = z.object({
+  contractVersion: z.number().int().nonnegative(),
+  sessionId: z.string().min(1),
+  session: sessionIdentitySchema,
+  attachmentId: z.string().min(1),
+  promptHash: hexDigestSchema,
+  runtimeHash: hexDigestSchema,
+  text: z.string().min(1).max(MAX_SCHEMA_TEXT_CHARS),
+  storedAt: z.number().int().nonnegative().max(Number.MAX_SAFE_INTEGER),
+})
+
+type EvidenceRecord = z.infer<typeof evidenceRecordSchema>
+type EvidenceRecordKey = string & { readonly __evidenceRecordKey: unique symbol }
+
+/** Plugin-owned sidecar domain; the host backend handles atomicity and file safety. */
+export const evidenceCacheDomainSpec = defineDomain({
+  name: 'vision_toolkit_evidence',
+  version: 0,
+  tables: {
+    // Keep the durable boundary tolerant of one damaged cache payload: each
+    // record is parsed and validated independently below, so corruption causes
+    // a miss instead of preventing the entire optional domain from opening.
+    evidence: domainTable<EvidenceRecordKey, string>(z.string().max(MAX_SCHEMA_RECORD_CHARS)),
+  },
+})
+
+/** Stable metadata for one description lookup. Raw focus prompts are never persisted. */
+export interface EvidenceCacheKey {
+  readonly digest: string
+  readonly contractVersion: number
+  readonly sessionId?: string
+  readonly sessionCreatedAt?: number
+  readonly sessionCwd?: string
+  readonly attachmentId: string
+  readonly promptHash: string
+  readonly runtimeHash: string
+}
+
+/** Optional durable layer behind the process-local promise/LRU cache. */
+export interface EvidencePersistence {
+  read(key: EvidenceCacheKey): Promise<ContentBlock | undefined>
+  write(key: EvidenceCacheKey, block: ContentBlock): Promise<void>
+}
+
+function hash(value: string): string {
+  return createHash('sha256').update(value).digest('hex')
+}
+
+/** Fingerprint every runtime setting that can change the generated description. */
+export function evidenceRuntimeFingerprint(
+  config: ResolvedVisionToolkitConfig,
+  credentialSha256?: string,
+  sslVerify?: string,
+): string {
+  return hash(JSON.stringify({
+    upstreamCommit: UPSTREAM_COMMIT,
+    provider: {
+      baseUrl: config.provider.baseUrl,
+      credential: {
+        ref: String(config.provider.credential),
+        sha256: credentialSha256 ?? null,
+      },
+      model: config.provider.model,
+      protocol: config.provider.protocol,
+      anthropicThinking: config.provider.anthropicThinking,
+      sslVerify: sslVerify ?? null,
+      userAgent: config.provider.userAgent,
+    },
+    language: config.language,
+    timeoutMs: config.timeoutMs,
+    concurrency: config.concurrency,
+    maxImageBytes: config.maxImageBytes,
+    maxImagePixels: config.maxImagePixels,
+    runtime: config.runtime,
+  }))
+}
+
+/** Build a non-secret cache key from the Session, attachment, focus, and runtime contract. */
+export function createEvidenceCacheKey(input: {
+  sessionId?: string
+  sessionIdentity?: SessionIdentity
+  attachmentId: string
+  prompt: string
+  runtimeHash: string
+}): EvidenceCacheKey {
+  const promptHash = hash(input.prompt)
+  const digest = hash(JSON.stringify([
+    EVIDENCE_CONTRACT_VERSION,
+    input.sessionId ?? '',
+    input.sessionIdentity?.createdAt ?? '',
+    input.sessionIdentity?.cwd ?? '',
+    input.attachmentId,
+    promptHash,
+    input.runtimeHash,
+  ]))
+  return Object.freeze({
+    digest,
+    contractVersion: EVIDENCE_CONTRACT_VERSION,
+    ...(input.sessionId === undefined ? {} : { sessionId: input.sessionId }),
+    ...(input.sessionIdentity === undefined ? {} : { sessionCreatedAt: input.sessionIdentity.createdAt }),
+    ...(input.sessionIdentity?.cwd === undefined ? {} : { sessionCwd: input.sessionIdentity.cwd }),
+    attachmentId: input.attachmentId,
+    promptHash,
+    runtimeHash: input.runtimeHash,
+  })
+}
+
+/** Bounded promise cache; concurrent readers join one load and rejected loads are evicted. */
+export class EvidenceCache {
+  private readonly entries = new Map<string, Promise<ContentBlock>>()
+
+  constructor(
+    private readonly limit: number,
+    private readonly persistence?: EvidencePersistence,
+  ) {}
+
+  /** Read a memory/durable hit or compute and persist one model-visible result. */
+  read(key: string | EvidenceCacheKey, load: () => Promise<ContentBlock>): Promise<ContentBlock> {
+    const memoryKey = typeof key === 'string' ? key : key.digest
+    const existing = this.entries.get(memoryKey)
+    if (existing !== undefined) {
+      // Refresh recency: Map iteration order is insertion order.
+      this.entries.delete(memoryKey)
+      this.entries.set(memoryKey, existing)
+      return existing
+    }
+
+    const pending = (async (): Promise<ContentBlock> => {
+      if (typeof key !== 'string' && this.persistence !== undefined) {
+        try {
+          const persisted = await this.persistence.read(key)
+          if (persisted !== undefined) return persisted
+        } catch {
+          // Persistence is an optimization; a damaged/unavailable sidecar must
+          // never block the model request from recomputing evidence.
+        }
+      }
+
+      const block = await load()
+      if (typeof key !== 'string' && this.persistence !== undefined) {
+        try {
+          await this.persistence.write(key, block)
+        } catch {
+          // Keep the process-local result even when durability fails.
+        }
+      }
+      return block
+    })().then(
+      block => block,
+      (error: unknown) => {
+        // Only evict our own entry: this promise may have been LRU-evicted and
+        // the key re-populated by a newer read meanwhile.
+        if (this.entries.get(memoryKey) === pending) {
+          this.entries.delete(memoryKey)
+        }
+        throw error
+      },
+    )
+
+    this.entries.set(memoryKey, pending)
+    while (this.entries.size > this.limit) {
+      const oldest = this.entries.keys().next().value
+      if (oldest === undefined) break
+      this.entries.delete(oldest)
+    }
+    return pending
+  }
+
+  /** Drop process-local descriptions; durable rows stay versioned by their runtime fingerprint. */
+  clear(): void {
+    this.entries.clear()
+  }
+}
+
+interface StorageBinding {
+  table: KvTable<EvidenceRecordKey, string>
+}
+
+interface SessionIdentity {
+  createdAt: number
+  cwd?: string
+}
+
+export interface SessionEvidenceStoreOptions {
+  maxEntries?: number
+  maxBytes?: number
+  maxEntryBytes?: number
+  now?: () => number
+}
+
+function identityOf(header: SessionHeader): SessionIdentity {
+  return Object.freeze({
+    createdAt: header.createdAt,
+    ...(header.cwd === undefined ? {} : { cwd: header.cwd }),
+  })
+}
+
+function sameIdentity(record: EvidenceRecord, header: SessionHeader): boolean {
+  return record.session.createdAt === header.createdAt && record.session.cwd === header.cwd
+}
+
+function matchesKey(record: EvidenceRecord, key: EvidenceCacheKey): boolean {
+  return record.contractVersion === key.contractVersion
+    && record.sessionId === key.sessionId
+    && record.attachmentId === key.attachmentId
+    && record.promptHash === key.promptHash
+    && record.runtimeHash === key.runtimeHash
+}
+
+function byteLength(text: string): number {
+  return Buffer.byteLength(text, 'utf8')
+}
+
+function messageOf(error: unknown): string {
+  return error instanceof Error ? error.message : String(error)
+}
+
+function parseRecord(value: string): EvidenceRecord | undefined {
+  try {
+    const parsed: unknown = JSON.parse(value)
+    const result = evidenceRecordSchema.safeParse(parsed)
+    return result.success ? result.data : undefined
+  } catch {
+    return undefined
+  }
+}
+
+/** Official DSH storage-domain sidecar used to survive Profile restarts. */
+export class SessionEvidenceStore implements EvidencePersistence {
+  private storage: StorageBinding | undefined
+  private storageFiber: (Fiber & PromiseLike<Fiber>) | undefined
+  private storageReady: Promise<void> | undefined
+  private mutationTail: Promise<void> = Promise.resolve()
+  private readonly flushes = new Map<string, Promise<boolean>>()
+  private warned = false
+  private readonly maxEntries: number
+  private readonly maxBytes: number
+  private readonly maxEntryBytes: number
+  private readonly now: () => number
+
+  constructor(
+    private readonly ctx: Context,
+    options: SessionEvidenceStoreOptions = {},
+  ) {
+    this.maxEntries = options.maxEntries ?? DEFAULT_PERSISTED_ENTRY_LIMIT
+    this.maxBytes = options.maxBytes ?? DEFAULT_PERSISTED_BYTE_LIMIT
+    this.maxEntryBytes = options.maxEntryBytes ?? DEFAULT_PERSISTED_ENTRY_BYTE_LIMIT
+    this.now = options.now ?? Date.now
+
+    if (typeof ctx.inject !== 'function') return
+    this.storageFiber = ctx.inject(['storageDomain'], async (storageCtx: Context) => {
+      const domain = await storageCtx.storageDomain.open(evidenceCacheDomainSpec)
+      const binding: StorageBinding = { table: domain.table('evidence') }
+      try {
+        await this.enqueueMutation(async () => { await this.prune(binding.table) })
+        this.storage = binding
+      } catch (error) {
+        await domain.close()
+        throw error
+      }
+      return async () => {
+        if (this.storage === binding) this.storage = undefined
+        await this.mutationTail
+        await domain.close()
+      }
+    })
+    this.storageReady = Promise.resolve(this.storageFiber).then(
+      () => undefined,
+      (error: unknown) => { this.warnOnce(error) },
+    )
+  }
+
+  /** Release the optional storage binding with the owning variant lifecycle. */
+  dispose(): void {
+    const fiber = this.storageFiber
+    this.storageFiber = undefined
+    this.storageReady = undefined
+    if (fiber !== undefined) void fiber.dispose().catch(error => { this.warnOnce(error) })
+  }
+
+  async read(key: EvidenceCacheKey): Promise<ContentBlock | undefined> {
+    const session = this.sessionFor(key)
+    if (session === undefined) return undefined
+    const binding = await this.prepareStorage()
+    if (binding === undefined) return undefined
+    const stored = binding.table.get(key.digest as EvidenceRecordKey)
+    const record = stored === undefined ? undefined : parseRecord(stored)
+    if (record === undefined || !matchesKey(record, key) || !sameIdentity(record, session.header)) {
+      return undefined
+    }
+    if (byteLength(record.text) > this.maxEntryBytes) return undefined
+    return { type: 'text', text: record.text }
+  }
+
+  async write(key: EvidenceCacheKey, block: ContentBlock): Promise<void> {
+    if (block.type !== 'text' || block.text.length === 0 || byteLength(block.text) > this.maxEntryBytes) return
+    const session = this.sessionFor(key)
+    if (session === undefined) return
+    const binding = await this.prepareStorage()
+    if (binding === undefined) return
+
+    try {
+      const participated = await this.flushSession(session)
+      if (!participated) return
+      const record: EvidenceRecord = Object.freeze({
+        contractVersion: key.contractVersion,
+        sessionId: key.sessionId as string,
+        session: identityOf(session.header),
+        attachmentId: key.attachmentId,
+        promptHash: key.promptHash,
+        runtimeHash: key.runtimeHash,
+        text: block.text,
+        storedAt: this.now(),
+      })
+      await this.enqueueMutation(async () => {
+        await binding.table.put(key.digest as EvidenceRecordKey, JSON.stringify(record))
+        await this.prune(binding.table)
+      })
+    } catch (error) {
+      this.warnOnce(error)
+    }
+  }
+
+  private sessionFor(key: EvidenceCacheKey): ReturnType<Context['sessions']['get']> {
+    if (key.sessionId === undefined) return undefined
+    const session = this.ctx.sessions.get(key.sessionId as SessionId)
+    if (session === undefined) return undefined
+    if (key.sessionCreatedAt !== undefined
+      && (session.header.createdAt !== key.sessionCreatedAt || session.header.cwd !== key.sessionCwd)) {
+      return undefined
+    }
+    return session
+  }
+
+  private async prepareStorage(): Promise<StorageBinding | undefined> {
+    if (this.storage !== undefined) return this.storage
+    if (this.ctx.get('storageDomain') === undefined) return undefined
+    await this.storageReady
+    return this.storage
+  }
+
+  private enqueueMutation(operation: () => Promise<void>): Promise<void> {
+    const result = this.mutationTail.then(operation)
+    this.mutationTail = result.then(() => undefined, () => undefined)
+    return result
+  }
+
+  private flushSession(session: NonNullable<ReturnType<Context['sessions']['get']>>): Promise<boolean> {
+    const key = `${session.id}\u0000${session.header.createdAt}\u0000${session.header.cwd ?? ''}`
+    const existing = this.flushes.get(key)
+    if (existing !== undefined) return existing
+    const pending = this.ctx.sessions.flush(session).finally(() => {
+      if (this.flushes.get(key) === pending) this.flushes.delete(key)
+    })
+    this.flushes.set(key, pending)
+    return pending
+  }
+
+  private async prune(table: KvTable<EvidenceRecordKey, string>): Promise<void> {
+    const records = [...table.entries()].map(([key, stored]) => {
+      const record = parseRecord(stored)
+      return {
+        key,
+        bytes: byteLength(stored),
+        storedAt: record?.storedAt ?? -1,
+        valid: record !== undefined && byteLength(record.text) <= this.maxEntryBytes,
+      }
+    })
+    let totalBytes = records.reduce((sum, record) => sum + record.bytes, 0)
+    let totalEntries = records.length
+    records.sort((left, right) => Number(left.valid) - Number(right.valid)
+      || left.storedAt - right.storedAt
+      || left.key.localeCompare(right.key))
+    for (const record of records) {
+      if (record.valid && totalEntries <= this.maxEntries && totalBytes <= this.maxBytes) break
+      if (await table.delete(record.key)) {
+        totalEntries -= 1
+        totalBytes -= record.bytes
+      }
+    }
+  }
+
+  private warnOnce(error: unknown): void {
+    if (this.warned) return
+    this.warned = true
+    this.ctx.logger?.warn(
+      'dsh-vision-toolkit: persistent image evidence cache is unavailable; using the process cache only. %s',
+      messageOf(error).slice(0, 500),
+    )
+  }
+}

package/src/exposure.ts

@@ -0,0 +1,265 @@
+/**
+ * Agent-scoped progressive exposure for the model-facing visual tools.
+ * Runtime readiness is global, while tool schemas enter only an Agent through
+ * the matching Skill or its bootstrap tool; administrative diagnostics stay on
+ * the Web seam.
+ * @module dsh-vision-toolkit/exposure
+ */
+
+import type { Agent } from '@deepseek-ai/dsh-agent'
+import type { ContentBlock } from '@deepseek-ai/dsh-llm'
+import type { Session } from '@deepseek-ai/dsh-session'
+import { defineTool, type ToolDefinition } from '@deepseek-ai/dsh-tools'
+import type { Context } from '@deepseek-ai/cordis'
+import { VISION_SKILLS_CONTENT, VISION_SKILLS_NAME } from './skill.ts'
+import { VISION_TOOL_NAMES } from './tools.ts'
+
+/** Small bootstrap tool retained only until the current Agent gains visual tools. */
+export const VISION_TOOLKIT_ACTIVATE = 'vision_toolkit_activate'
+
+/** Skill name used by releases before the rename to vision-skills. */
+export const LEGACY_VISION_TOOLS_SKILL_NAME = 'vision-tools'
+
+/** Unique pre-rename line in bundled instructions, kept for Session restore. */
+export const LEGACY_VISION_TOOLS_SKILL_MARKER = 'If this content arrived through a direct `/vision-tools` invocation and the'
+
+interface AgentExposure {
+  active: boolean
+  liftRestriction?: () => void
+  toolDisposers: Array<() => void>
+  toolNames: string[]
+}
+
+/** Result returned by the one-shot activation transport. */
+export interface VisionToolkitActivationResult {
+  activated: boolean
+  tools: string[]
+}
+
+function renderJson(_args: unknown, value: unknown): ContentBlock[] {
+  return [{ type: 'text', text: JSON.stringify(value, null, 2) }]
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === 'object' && !Array.isArray(value)
+}
+
+function isBundledSkillName(name: unknown): boolean {
+  return name === VISION_SKILLS_NAME || name === LEGACY_VISION_TOOLS_SKILL_NAME
+}
+
+function isBundledSkillContent(text: string): boolean {
+  return text.includes(VISION_SKILLS_CONTENT) || text.includes(LEGACY_VISION_TOOLS_SKILL_MARKER)
+}
+
+function isVisionSkillArguments(value: unknown): boolean {
+  return isRecord(value) && isBundledSkillName(value.name)
+}
+
+function nativeSkillCall(raw: string): boolean {
+  try {
+    return isVisionSkillArguments(JSON.parse(raw))
+  } catch {
+    return false
+  }
+}
+
+function containsBundledSkillContent(blocks: readonly unknown[]): boolean {
+  return blocks.some(block => isRecord(block)
+    && block.type === 'text'
+    && typeof block.text === 'string'
+    && isBundledSkillContent(block.text))
+}
+
+function isBundledSkillResult(value: unknown): boolean {
+  return isRecord(value)
+    && isBundledSkillName(value.name)
+    && typeof value.content === 'string'
+    && isBundledSkillContent(value.content)
+}
+
+/** Whether durable history proves that this Session loaded the bundled Skill. */
+function hasLoadedVisionSkill(session: Session): boolean {
+  const nativeCalls = new Set<string>()
+  for (const event of session.events) {
+    if (event.type === 'user/message') {
+      const source = event.data.source
+      if (source.kind === 'skill-invocation'
+        && isBundledSkillName(source.name)
+        && containsBundledSkillContent(event.data.content)) return true
+      continue
+    }
+    if (event.type === 'tool/call') {
+      if (event.data.name === 'skill' && nativeSkillCall(event.data.arguments)) {
+        nativeCalls.add(String(event.data.callId))
+      }
+      continue
+    }
+    if (event.type === 'tool/result') {
+      const [block] = event.data.message.content
+      if (block?.type === 'tool-result'
+        && block.isError !== true
+        && nativeCalls.has(String(block.toolCallId))
+        && containsBundledSkillContent(block.content)) return true
+      continue
+    }
+    if (event.type === 'tool/code-dispatch'
+      && event.data.name === 'skill'
+      && event.data.isError === false
+      && isVisionSkillArguments(event.data.arguments)
+      && containsBundledSkillContent(event.data.content)) return true
+  }
+  return false
+}
+
+/**
+ * Owns one progressive-exposure generation for a ready Vision Toolkit runtime.
+ * The bootstrap tool is global; visual definitions are created and registered
+ * in an Agent scope after the Skill load is durable, just succeeded, or the
+ * model explicitly invokes the bootstrap fallback.
+ */
+export class VisionToolExposure {
+  readonly activationTool: ToolDefinition
+  private readonly states = new Map<Agent, AgentExposure>()
+  private installed = false
+
+  /**
+   * @param ctx - Plugin context with Tool and Agent registries.
+   * @param createTools - Fresh definitions bound to the current runtime generation.
+   */
+  constructor(
+    private readonly ctx: Context,
+    private readonly createTools: () => ToolDefinition[],
+  ) {
+    this.activationTool = defineTool({
+      name: VISION_TOOLKIT_ACTIVATE,
+      description: `Activate the independent Vision Toolkit execution tools for this Agent: ${Object.values(VISION_TOOL_NAMES).join(', ')}. `
+        + `Loading the ${VISION_SKILLS_NAME} Skill normally activates them automatically; call this once when the visual tools are still absent, then use them for image understanding, OCR, UI detection, and related tasks. `
+        + 'It is safe to call before the Skill is loaded, and this activation tool disappears after success.',
+      parameters: {},
+      output: {
+        schema: {
+          type: 'object',
+          additionalProperties: false,
+          properties: {
+            activated: { type: 'boolean', required: true },
+            tools: { type: 'array', items: { type: 'string' }, required: true },
+          },
+        },
+        render: renderJson,
+      },
+      execute: (_args, exec): Promise<VisionToolkitActivationResult> => {
+        if (exec.agent === undefined) {
+          throw new Error(`${VISION_TOOLKIT_ACTIVATE}: an Agent Session is required`)
+        }
+        return Promise.resolve(this.activate(exec.agent))
+      },
+      presentCall: () => ({ card: 'generic', title: 'Activate vision tools', kind: 'execute' }),
+    })
+  }
+
+  /** Install lifecycle listeners and adopt Agents that already exist. */
+  install(): () => void {
+    if (this.installed) throw new Error('dsh-vision-toolkit: progressive exposure is already installed')
+    this.installed = true
+    const listeners = [
+      this.ctx.on('agent/created', ({ agent }) => { this.attach(agent) }),
+      this.ctx.on('agent/disposed', ({ agent }) => { this.detach(agent) }),
+      this.ctx.on('session/event', (session, event) => {
+        if (event.type === 'step/end') this.applyHideActivationForSession(session)
+      }),
+      this.ctx.on('tools/result', (exec, result) => {
+        if (result.isError === false
+          && exec.name === 'skill'
+          && exec.agent !== undefined
+          && isVisionSkillArguments(exec.arguments)
+          && isBundledSkillResult(result.value)) {
+          this.activate(exec.agent)
+        }
+        return undefined
+      }),
+    ]
+    try {
+      for (const agent of this.ctx.agents.list()) this.attach(agent)
+    } catch (error) {
+      for (const dispose of listeners.reverse()) dispose()
+      this.disposeStates()
+      this.installed = false
+      throw error
+    }
+    return () => {
+      if (!this.installed) return
+      this.installed = false
+      for (const dispose of listeners.reverse()) dispose()
+      this.disposeStates()
+    }
+  }
+
+  private attach(agent: Agent): void {
+    if (this.states.has(agent)) return
+    this.states.set(agent, { active: false, toolDisposers: [], toolNames: [] })
+    if (hasLoadedVisionSkill(agent.session)) this.activate(agent)
+  }
+
+  private activate(agent: Agent): VisionToolkitActivationResult {
+    this.attach(agent)
+    const state = this.states.get(agent)
+    /* v8 ignore next -- attach() synchronously creates this exact entry. */
+    if (state === undefined) throw new Error(`dsh-vision-toolkit: Agent ${String(agent.id)} has no exposure state`)
+    if (state.active) return { activated: false, tools: [...state.toolNames] }
+
+    const definitions = this.createTools()
+    const toolDisposers: Array<() => void> = []
+    try {
+      for (const definition of definitions) toolDisposers.push(agent.ctx.tools.register(definition))
+      // A Skill call and the bootstrap can be issued in the same model step.
+      // Restricting immediately would turn the still-in-flight bootstrap call
+      // into an UNKNOWN_TOOL error, so live sessions hide at step/end.
+      if (!this.isLiveSession(agent.session)) this.applyHideActivation(agent)
+    } catch (error) {
+      for (const dispose of toolDisposers.reverse()) dispose()
+      throw error
+    }
+
+    state.active = true
+    state.toolDisposers = toolDisposers
+    state.toolNames = definitions.map(definition => definition.name)
+    return { activated: true, tools: [...state.toolNames] }
+  }
+
+  /** Whether the session is attached to the live SessionStore (production). */
+  private isLiveSession(session: Session): boolean {
+    return this.ctx.sessions.get(session.id) === session
+  }
+
+  private applyHideActivationForSession(session: Session): void {
+    for (const agent of this.ctx.agents.list()) {
+      if (agent.session === session && this.states.get(agent)?.active === true) {
+        this.applyHideActivation(agent)
+      }
+    }
+  }
+
+  private applyHideActivation(agent: Agent): void {
+    const state = this.states.get(agent)
+    if (state === undefined || state.liftRestriction !== undefined) return
+    state.liftRestriction = agent.ctx.tools.restrict({ deny: [VISION_TOOLKIT_ACTIVATE] })
+  }
+
+  private detach(agent: Agent): void {
+    const state = this.states.get(agent)
+    if (state === undefined) return
+    this.states.delete(agent)
+    this.disposeState(state)
+  }
+
+  private disposeStates(): void {
+    for (const state of this.states.values()) this.disposeState(state)
+    this.states.clear()
+  }
+
+  private disposeState(state: AgentExposure): void {
+    state.liftRestriction?.()
+    for (const dispose of state.toolDisposers.reverse()) dispose()
+  }
+}