Merge remote-tracking branch 'origin/master' into worktree/drop-create-by-name

scripts/gen-cordis-catalog.ts

@@ -48,6 +48,7 @@ export const SERVICE_PAGE: Record<string, string> = {
   agentPresets: 'core.md',
   agents: 'core.md',
   approval: 'approval.md',
+  attachments: 'attachment.md',
   bash: 'bash.md',
   bashEnv: 'bash.md',
   clientModuleHost: 'client-modules.md',
@@ -244,6 +245,9 @@ export const LINK_MAP: Readonly<Record<string, string>> = {
   ApprovalPolicy: 'approval.md',
   ApprovalRequest: 'approval.md',
   ApprovalService: 'approval.md',
+  ImageAttachmentRef: 'attachment.md',
+  SaveImageAttachment: 'attachment.md',
+  StoredImageAttachment: 'attachment.md',
   BashExecRequest: 'bash.md',
   BashExecSpec: 'bash.md',
   BashProcess: 'bash.md',

scripts/gen-doc-graphs.ts

@@ -62,6 +62,7 @@ type EventReceiverKind = 'context' | 'agent-dispatch' | 'events-service'
 
 const GROUP_ORDER = [
   'util',
+  'attachment',
   'llm',
   'core',
   'typert',
@@ -95,6 +96,15 @@ const GROUP_ORDER = [
 ]
 
 const SERVICE_ROLES: ServiceRole[] = [
+  {
+    key: 'attachments',
+    pkg: 'attachment',
+    title: 'Durable binary attachment storage',
+    mode: 'seam',
+    implementations: ['attachment-local'],
+    consumers: ['host-runtime', 'llm-pi-ai'],
+    note: 'The host commits accepted images before session events; provider adapters resolve authorized durable references into provider-native content.',
+  },
   {
     key: 'llm',
     pkg: 'llm',

scripts/test-invariants.ts

@@ -8,6 +8,13 @@
 import { expect } from 'vitest'
 import { FiberState, Inject, RegistryService } from 'cordis'
 import type { Context, Plugin } from 'cordis'
+import { AttachmentStore } from '@deepseek-ai/dsh-attachment'
+import type {
+  ImageAttachmentLimits,
+  ImageAttachmentRef,
+  SaveImageAttachment,
+  StoredImageAttachment,
+} from '@deepseek-ai/dsh-attachment'
 import InvariantService from '@deepseek-ai/dsh-invariants'
 
 declare global {
@@ -102,6 +109,29 @@ export function usesManualInvariantTree(testPath: string): boolean {
 }
 
 const ALL_COMPANION_TESTS = ['/scripts/test-invariants.spec.ts'] as const
+const ATTACHMENT_COMPANION = '../packages/attachment/attachment-local/src/invariant.ts'
+
+class TestAttachmentStore extends AttachmentStore {
+  readonly imageLimits: ImageAttachmentLimits = {
+    maxImageBytes: 1,
+    maxImagesPerMessage: 1,
+    maxMessageImageBytes: 1,
+    maxImagePixels: 1,
+    mediaTypes: ['image/png'],
+  }
+
+  validateImage(_input: SaveImageAttachment): Promise<void> {
+    return Promise.reject(new Error('test invariant attachment store does not validate images'))
+  }
+
+  saveImage(_input: SaveImageAttachment): Promise<ImageAttachmentRef> {
+    return Promise.reject(new Error('test invariant attachment store does not save images'))
+  }
+
+  readImage(_ref: ImageAttachmentRef): Promise<StoredImageAttachment> {
+    return Promise.reject(new Error('test invariant attachment store does not read images'))
+  }
+}
 
 /**
  * Select the package companions that an ordinary test root must register.
@@ -148,6 +178,9 @@ function startInvariantHost(root: Context): InvariantHost {
   const testPath = expect.getState().testPath ?? ''
   const companionPaths = testInvariantCompanionPaths(testPath)
   const ready = requireActive(serviceFiber, 'invariant service').then(async () => {
+    const attachmentFiber = companionPaths.includes(ATTACHMENT_COMPANION)
+      ? mount(TestAttachmentStore)
+      : undefined
     const companions = await Promise.all(companionPaths.map(async (path) => {
       const load = testInvariantCompanions[path]
       if (load === undefined) {
@@ -163,7 +196,12 @@ function startInvariantHost(root: Context): InvariantHost {
       fiber: mount(companion),
       path,
     }))
-    await Promise.all(companionFibers.map(({ fiber, path }) => requireActive(fiber, path)))
+    await Promise.all([
+      ...(attachmentFiber === undefined
+        ? []
+        : [requireActive(attachmentFiber, 'test attachment store')]),
+      ...companionFibers.map(({ fiber, path }) => requireActive(fiber, path)),
+    ])
     root.provide(TEST_INVARIANT_READY_SERVICE, true)
   })
   const host = { byCallback, barrierOwners, ready }

scripts/type-equiv.manifest.json

@@ -780,6 +780,31 @@
       "symbol": "ApprovalRequest",
       "source": "packages/interaction/user-approval/src/index.ts"
     },
+    {
+      "doc": "docs/subsystems/attachment.md",
+      "symbol": "ImageMediaType",
+      "source": "packages/attachment/attachment/src/types.ts"
+    },
+    {
+      "doc": "docs/subsystems/attachment.md",
+      "symbol": "ImageAttachmentRef",
+      "source": "packages/attachment/attachment/src/types.ts"
+    },
+    {
+      "doc": "docs/subsystems/attachment.md",
+      "symbol": "ImageAttachmentLimits",
+      "source": "packages/attachment/attachment/src/types.ts"
+    },
+    {
+      "doc": "docs/subsystems/attachment.md",
+      "symbol": "SaveImageAttachment",
+      "source": "packages/attachment/attachment/src/types.ts"
+    },
+    {
+      "doc": "docs/subsystems/attachment.md",
+      "symbol": "StoredImageAttachment",
+      "source": "packages/attachment/attachment/src/types.ts"
+    },
     {
       "doc": "docs/subsystems/bash.md",
       "symbol": "BashExecRequest",

scripts/verify-package-readme-model-experience.ts

@@ -42,6 +42,8 @@ const NO_MODEL_EXPERIENCE_SECTION: Readonly<Record<string, string>> = {
  * blocks. A package moves on or off this list with its context behavior.
  */
 const SENTENCE_MODEL_EXPERIENCE: Readonly<Record<string, SentenceContract>> = {
+  'packages/attachment/attachment': { kind: 'indirect', reason: 'The storage seam delegates model request rendering to provider adapters.' },
+  'packages/attachment/attachment-local': { kind: 'indirect', reason: 'The local backend delegates model request rendering to provider adapters.' },
   'packages/bash/bash': { kind: 'indirect', reason: 'The service interface delegates all model rendering to dsh-tool-bash.' },
   'packages/bash/bash-env': { kind: 'indirect', reason: 'The env service surfaces managed DSH_* facts through the shell tools (dsh-tool-bash/dsh-tool-pwsh); it registers no prompt or schema of its own.' },
   'packages/bash/bash-local': { kind: 'indirect', reason: 'The executor backend delegates model rendering to dsh-tool-bash.' },