@dxos/plugin-file 0.12.0-next-73daef452f1464b62efdbca75fb0067c1066f264 → 0.13.0

package/PLUGIN.mdl

@@ -21,9 +21,10 @@ Each extension is defined in the Appendix or resolved via its URI.
 |-------------|--------------------------------|
 | `type`      | `org.dxos.mdl.type@1.0`       |
 | `feat`      | `org.dxos.mdl.feat@1.0`       |
-| `test`      | `org.dxos.mdl.test@1.0`       |
+| `scenario`  | `org.dxos.mdl.scenario@1.0`   |
 | `component` | `org.dxos.mdl.component@1.0`  |
 | `op`        | `org.dxos.mdl.op@1.0`         |
+| `test`      | `org.dxos.mdl.test@1.0`       |
 
 ## Types
 
@@ -59,11 +60,22 @@ type Settings
 ## Components
 
 ```mdl
-component FilePreview
+component Preview
   desc: |
-    Renders a File object using the appropriate HTML element for its MIME type.
-    Images use <img>, videos use <video controls>, PDFs use <iframe>, and
-    all other types fall back to a download link.
+    Composite preview of a file's content, in Radix parts. Preview.Root holds
+    the source and whatever the content discovers about it, Preview.Content
+    renders by MIME type, and Preview.Toolbar sits above with controls. Split
+    this way because the toolbar needs facts only the content discovers — a
+    PDF's page count is known after pdf.js parses the document.
+
+    Root renders no element of its own: its parts are placed into slots that
+    belong to the surrounding container (Panel.Toolbar / Panel.Content), so a
+    wrapper would break the panel's grid.
+
+    Images, video and audio go through react-ui's MediaPlayer. PDFs render
+    through pdf.js to stacked canvases — one per page — rather than an
+    <iframe>, whose built-in viewer lives in another origin and cannot be
+    themed. Everything else falls back to a download link.
   props:
     type: string             # MIME type
     url: string              # renderable data:, blob:, or http(s): URL
@@ -108,18 +120,21 @@ component FileArticle
     Full-viewport article container rendered for article, section, and slide
     roles. Loads the File's referenced Blob and resolves a renderable URL via
     Blob.url; if the backend has no getUrl, falls back to Blob.read and
-    constructs a blob: object URL (revoked on unmount). Delegates to
-    FilePreview. Shows an empty state while the URL is resolving or if the
-    File is not attached to a database.
+    constructs a blob: object URL (revoked on unmount). Composes Preview's
+    parts into the panel's toolbar and content slots. Shows an empty state
+    while the URL is resolving or if the File is not attached to a database.
+
+    Full plank width, not the reading column: `dx-document` is right for prose
+    and wrong for a preview.
   props:
     role: AppSurface.Role
     subject: File
   layout: |
     ┌──────────────────────────────┐
-    │                              │
-    │      FilePreview             │
+    │  Preview.Toolbar   (n pages) │
+    ├──────────────────────────────┤
+    │      Preview.Content         │
     │      (fills container)       │
-    │                              │
     └──────────────────────────────┘
 ```
 
@@ -129,8 +144,8 @@ component FileArticle
 op Create
   key: org.dxos.operation.file.create
   desc: |
-    Validates a browser File object's MIME type, resolves the active
-    BackendDescriptor, and composes File.fromBytes (which hashes/uploads the
+    Resolves the MIME type to store (FileLimits.toStoredMimeType), resolves the
+    active BackendDescriptor, and composes File.fromBytes (which hashes/uploads the
     bytes via the Blob API and adds the resulting Blob to the database) to
     construct a File ECHO object. Does not add the File object itself to the
     space — callers do that separately.
@@ -139,7 +154,6 @@ op Create
     db: Database
   output: { object: File }
   errors:
-    UnsupportedFileTypeError: MIME type is not image/*, video/*, or application/pdf
     FileTooLargeError: file exceeds the 4 MB inline limit (only possible when the
       resolved backend's storage is 'inline'; other backends scale beyond it)
     NoBackendError: no BackendDescriptor capability is registered
@@ -150,8 +164,9 @@ op Create
 ```mdl
 feat F-1: File upload
 
-  req F-1.1: Accepted MIME types MUST be image/* (jpg, jpeg, png, gif, webp, svg),
-    video/* (mp4, webm, mov), and application/pdf only.
+  req F-1.1: Every MIME type MUST be accepted, including an absent one. A type
+    that is absent or that a browser executes (text/html, application/xhtml+xml,
+    text/xml, application/xml) MUST be stored as application/octet-stream.
 
   req F-1.2: Maximum upload size MUST be 4 MB when the resolved backend's storage
     is 'inline'. Other backends (e.g. edge, wnfs) are not subject to this cap.
@@ -165,8 +180,8 @@ feat F-1: File upload
         renderable url resolved via Blob.url, if one is available)
 
   req F-1.4:
-    when: file MIME type is not accepted
-    then: UnsupportedFileTypeError returned; no ECHO write occurs
+    when: file MIME type is unrecognized or empty (e.g. a .ndjson.gz log bundle)
+    then: the File is created; Preview shows the no-preview message and a download
 
   req F-1.5:
     when: file size exceeds the limit and the resolved backend's storage is 'inline'
@@ -200,14 +215,23 @@ feat F-2: Backend capability system
 feat F-3: File preview
 
   req F-3.1: FileArticle MUST resolve a renderable URL via Blob.url before
-    rendering FilePreview. For inline files this is always a data: URL
+    rendering Preview. For inline files this is always a data: URL
     (constructed synchronously from the stored bytes, no Blob.read needed). For
     external files with no registered getUrl, FileArticle falls back to
     Blob.read and constructs a blob: URL, revoked on unmount.
 
-  req F-3.2: FilePreview MUST render the appropriate element for each MIME class:
-    image/* → <img>, video/* → <video controls>, application/pdf → <iframe>,
-    other → <a download>.
+  req F-3.2: Preview.Content MUST render the appropriate element for each MIME
+    class: image/*, video/* and audio/* → MediaPlayer, application/pdf → pdf.js
+    canvases, other → <a download>.
+
+  req F-3.4: A PDF MUST render every page, not one at a time. The <iframe> this
+    replaced scrolled the whole document, so paginating would silently hide
+    content behind navigation that does not exist.
+
+  req F-3.5: Rendering MUST be cancelled before the document is torn down.
+    pdf.js rejects in-flight render and getPage promises with
+    RenderingCancelledException / "Transport destroyed" once the transport is
+    destroyed, and those rejections are unhandled if nothing cancels first.
 
   req F-3.3: FileArticle surfaces are registered for article, section,
     and slide roles so files embed correctly in Markdown and Presenter layouts.
@@ -235,7 +259,7 @@ feat F-5: Settings
 ## Acceptance
 
 ```mdl
-test T-1: Upload image inline
+scenario T-1: Upload image inline
   given: only the inline BackendDescriptor is registered
   when: user uploads a 1 MB PNG via the Create Object form
   then:
@@ -245,7 +269,7 @@ test T-1: Upload image inline
 ```
 
 ```mdl
-test T-2: Reject oversized file
+scenario T-2: Reject oversized file
   given: inline backend selected, 4 MB limit
   when: user uploads a 5 MB JPEG
   then:
@@ -255,16 +279,15 @@ test T-2: Reject oversized file
 ```
 
 ```mdl
-test T-3: Reject unsupported MIME type
+scenario T-3: Store an unrecognized MIME type
   given: inline backend registered
   when: user uploads a .zip file
   then:
-    - UnsupportedFileTypeError is returned
-    - no File object is created
+    - a File object is created whose Blob type is application/zip
 ```
 
 ```mdl
-test T-4: Preview inline image
+scenario T-4: Preview inline image
   given: a File whose data Ref resolves to a Blob with data._tag === 'inline' and type === 'image/png'
   when: FileArticle is rendered
   then:
@@ -273,21 +296,21 @@ test T-4: Preview inline image
 ```
 
 ```mdl
-test T-5: Preview PDF
+scenario T-5: Preview PDF
   given: a File with type === 'application/pdf' and a Blob resolved to an HTTP or data URL
   when: FilePreview is rendered
   then: an <iframe> element is rendered with the file URL as src
 ```
 
 ```mdl
-test T-6: Backend fallback to inline
+scenario T-6: Backend fallback to inline
   given: Settings.backend is 'wnfs' but no BackendDescriptor with storage 'wnfs' is registered
   when: op:Create is invoked
   then: the inline backend is used and the file is stored inline
 ```
 
 ```mdl
-test T-7: External blob resolved via a registered BlobBackend's getUrl
+scenario T-7: External blob resolved via a registered BlobBackend's getUrl
   given: a File whose data Ref resolves to a Blob with data._tag === 'external' and a
     BlobBackend registered on the ECHO Hypergraph that resolves the Blob's URI scheme
     and implements getUrl
@@ -299,7 +322,7 @@ test T-7: External blob resolved via a registered BlobBackend's getUrl
 ```
 
 ```mdl
-test T-8: External blob without getUrl falls back to reading bytes
+scenario T-8: External blob without getUrl falls back to reading bytes
   given: a File whose data Ref resolves to an external Blob whose registered
     BlobBackend implements get but not getUrl
   when: FileArticle is rendered
@@ -310,7 +333,7 @@ test T-8: External blob without getUrl falls back to reading bytes
 ```
 
 ```mdl
-test T-9: No backend error
+scenario T-9: No backend error
   given: no BackendDescriptor capability is registered
   when: op:Create is invoked
   then: NoBackendError is returned
@@ -318,6 +341,88 @@ test T-9: No backend error
 
 ---
 
+## QA
+
+Executable tests. Each step carries a human instruction (`do`) and, where the step maps to an
+invocable operation, an agent binding (`invoke`). Report failures by test and step number.
+
+plugin-file is on by default (`FilePlugin.meta.profile.key` is in `getDefaults`; see
+`packages/apps/composer-app/src/plugin-defs.tsx`).
+
+```mdl
+test QA-1: Upload an image and preview it
+  desc: The core file round-trip — upload an inline image via the Create Object form, place it, and read the preview back.
+  actors: both
+  covers: [F-1.1, F-1.3, F-3.1, F-3.2, T-1, T-4]
+  status: unverified
+  given:
+    - an identity exists
+    - space: a space is open
+    - collection: a collection in that space, to create into
+    - only the inline BackendDescriptor is registered (default)
+    - no File named "qa-image.png" exists — ABORT rather than reusing one this test did not create
+  steps:
+    - name: Upload the image
+      do: In the navtree, click + on a collection and choose File. Drop a small PNG (e.g. 10 KB) named "qa-image.png".
+      invoke: |
+        org.dxos.operation.file.create {
+          file: new File([Uint8Array.from(atob("iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNk+A8AAQUBAScY42YAAAAASUVORK5CYII="), (c) => c.charCodeAt(0))], "qa-image.png", { type: "image/png" }),
+          db: $given.space.db
+        }
+      capture: created
+      expect: a File object is created with type "image/png", the given size, and a Blob whose
+        data resolves inline
+      assert: return $created.object.type === 'image/png' && !!$created.object.data
+      note: |
+        `file` is a browser `File` object, not a plain literal — the runner constructs it inline
+        with `new File(...)` in the invoke snippet rather than passing JSON, since `BrowserFile`
+        has no serializable shape.
+    - name: Place it in the collection
+      do: (the Create Object form places it for you)
+      invoke: org.dxos.operation.space.addObject { object: $created.object, target: $given.collection }
+      expect: "qa-image.png" appears as a row under the collection
+      assert: |
+        return $given.collection.objects.some((ref) => ref.target?.id === $created.object.id);
+      note: Coalesced with the previous step — `created.object` is live and cannot cross a snippet boundary.
+    - name: Open it and view the preview
+      do: Click "qa-image.png" in the navtree.
+      invoke: org.dxos.operation.appToolkit.open { subject: ["root/$given.space.id/content/collections/$created.object.id"] }
+      expect: FileArticle renders an <img> element showing the uploaded image, resolved via a data: URL
+      assert: |
+        const img = document.querySelector('img[src^="data:"]');
+        return !!img && img.complete && img.naturalWidth > 0;
+  after:
+    - name: Delete the File
+      do: Right-click "qa-image.png" in the navtree and choose Delete.
+      invoke: org.dxos.operation.space.removeObjects { objects: [$created.object], target: $given.collection }
+      expect: the row leaves the navtree and its plank closes
+```
+
+```mdl
+test QA-2: Reject an oversized upload
+  desc: The rejection path (F-1.5) — a validation round-trip that must leave no ECHO write behind.
+  actors: agent
+  covers: [F-1.5, T-2]
+  status: unverified
+  given:
+    - an identity exists
+    - space: a space is open
+    - only the inline BackendDescriptor is registered (4 MB cap applies)
+  steps:
+    - name: Reject an oversized file
+      do: Attempt to upload a PNG larger than 4 MB.
+      invoke: |
+        org.dxos.operation.file.create {
+          file: new File([new Uint8Array(5 * 1024 * 1024)], "qa-big.png", { type: "image/png" }),
+          db: $given.space.db
+        }
+      expect: the upload is refused with FileTooLargeError and no File object is created
+      assert: |
+        return /FileTooLarge/.test($error?.message ?? $error?._tag ?? '');
+```
+
+---
+
 ## Appendix: Extension Definitions
 
 ```mdl
@@ -342,8 +447,8 @@ ext feat
 ```
 
 ```mdl
-ext test
-  uri: org.dxos.mdl.test@1.0
+ext scenario
+  uri: org.dxos.mdl.scenario@1.0
   desc: An acceptance scenario expressed as given / when / then steps.
   fields:
     given?: Step | Step[]

package/dist/lib/FileCapabilities.mjs

@@ -1,5 +1,4 @@
 import { t as __exportAll } from "./chunk-rolldown-runtime.mjs";
-import { ACCEPTED_MIME } from "./FileLimits.mjs";
 import * as Capability from "@dxos/app-framework/Capability";
 import { meta } from "#meta";
 import * as Schema from "effect/Schema";
@@ -14,7 +13,7 @@ var SettingsAtom = Capability.makeSingleton()(`${meta.profile.key}.capability.se
 var FileAction;
 (function(_FileAction) {
 	const UploadAnnotationId = _FileAction.UploadAnnotationId = `${meta.profile.key}.annotation.upload`;
-	_FileAction.CreateFileSchema = Schema.Struct({ file: Schema.instanceOf(File).annotate({ [UploadAnnotationId]: ACCEPTED_MIME }) });
+	_FileAction.CreateFileSchema = Schema.Struct({ file: Schema.instanceOf(File).annotate({ [UploadAnnotationId]: true }) });
 })(FileAction || (FileAction = {}));
 //#endregion
 export { Backend, FileAction, SettingsAtom, FileCapabilities_exports as t };

package/dist/lib/FileCapabilities.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"FileCapabilities.mjs","names":[],"sources":["../../src/types/FileCapabilities.ts"],"sourcesContent":["//\n// Copyright 2026 DXOS.org\n//\n\nimport * as Schema from 'effect/Schema';\nimport type * as Atom from 'effect/unstable/reactivity/Atom';\n\nimport * as Capability from '@dxos/app-framework/Capability';\n\nimport { meta } from '#meta';\n\nimport { ACCEPTED_MIME } from './FileLimits';\nimport * as Settings from './Settings';\n\n/**\n * Descriptor for a registered `BlobBackend` storage option, surfaced in the file plugin's\n * settings UI. Actual upload/read logic lives in the Blob backend registered on the Hypergraph\n * under `storage` (see `client.graph.registerBlobBackend`) — this type carries no behavior.\n */\nexport type Backend = {\n  /** Display label shown in the settings UI. */\n  readonly name: string;\n  /** Description shown next to the backend in settings. */\n  readonly description?: string;\n  /**\n   * `Blob.fromBytes`'s `storage` option to use when this backend is selected. Also the settings\n   * key identifying this backend — one `BlobBackend` is registered per storage name, so the two\n   * concepts always coincide.\n   */\n  readonly storage: string;\n};\n\n// Multi capability: inline-backend and edge-backend each contribute one entry.\nexport const Backend = Capability.make<Backend>()(`${meta.profile.key}.capability.backend`);\n\nexport const SettingsAtom = Capability.makeSingleton<Atom.Writable<Settings.Settings>>()(\n  `${meta.profile.key}.capability.settings`,\n);\n\nexport namespace FileAction {\n  export const UploadAnnotationId = `${meta.profile.key}.annotation.upload`;\n\n  export const CreateFileSchema = Schema.Struct({\n    file: Schema.instanceOf(File).annotate({\n      [UploadAnnotationId]: ACCEPTED_MIME,\n    }),\n  });\n\n  export type CreateFileForm = Schema.Schema.Type<typeof CreateFileSchema>;\n}\n"],"mappings":";;;;;;;;;;;AAiCA,IAAa,UAAU,WAAW,KAAc,CAAC,CAAC,GAAG,KAAK,QAAQ,IAAI,oBAAoB;AAE1F,IAAa,eAAe,WAAW,cAAgD,CAAC,CACtF,GAAG,KAAK,QAAQ,IAAI,qBACtB;AAEO,IAAU;CAAV,SAAA,aAAA;CACE,MAAM,qBAAA,YAAA,qBAAqB,GAAG,KAAK,QAAQ,IAAI;CAEzC,YAAA,mBAAmB,OAAO,OAAO,EAC5C,MAAM,OAAO,WAAW,IAAI,CAAC,CAAC,SAAS,GACpC,qBAAqB,cACxB,CAAC,EACH,CAAC;AAGH,EAAA,CAAA,eAAA,aAAA,CAAA,EAAA"}
+{"version":3,"file":"FileCapabilities.mjs","names":[],"sources":["../../src/types/FileCapabilities.ts"],"sourcesContent":["//\n// Copyright 2026 DXOS.org\n//\n\nimport type * as Atom from 'effect/reactivity/Atom';\nimport * as Schema from 'effect/Schema';\n\nimport * as Capability from '@dxos/app-framework/Capability';\n\nimport { meta } from '#meta';\n\nimport * as Settings from './Settings.ts';\n\n/**\n * Descriptor for a registered `BlobBackend` storage option, surfaced in the file plugin's\n * settings UI. Actual upload/read logic lives in the Blob backend registered on the Hypergraph\n * under `storage` (see `client.graph.registerBlobBackend`) — this type carries no behavior.\n */\nexport type Backend = {\n  /** Display label shown in the settings UI. */\n  readonly name: string;\n  /** Description shown next to the backend in settings. */\n  readonly description?: string;\n  /**\n   * `Blob.fromBytes`'s `storage` option to use when this backend is selected. Also the settings\n   * key identifying this backend — one `BlobBackend` is registered per storage name, so the two\n   * concepts always coincide.\n   */\n  readonly storage: string;\n};\n\n// Multi capability: inline-backend and edge-backend each contribute one entry.\nexport const Backend = Capability.make<Backend>()(`${meta.profile.key}.capability.backend`);\n\nexport const SettingsAtom = Capability.makeSingleton<Atom.Writable<Settings.Settings>>()(\n  `${meta.profile.key}.capability.settings`,\n);\n\nexport namespace FileAction {\n  /** Marks a field as a file upload, so the form renders the drop zone for it. Any type is accepted. */\n  export const UploadAnnotationId = `${meta.profile.key}.annotation.upload`;\n\n  export const CreateFileSchema = Schema.Struct({\n    file: Schema.instanceOf(File).annotate({\n      [UploadAnnotationId]: true,\n    }),\n  });\n\n  export type CreateFileForm = Schema.Schema.Type<typeof CreateFileSchema>;\n}\n"],"mappings":";;;;;;;;;;AAgCA,IAAa,UAAU,WAAW,KAAc,CAAC,CAAC,GAAG,KAAK,QAAQ,IAAI,oBAAoB;AAE1F,IAAa,eAAe,WAAW,cAAgD,CAAC,CACtF,GAAG,KAAK,QAAQ,IAAI,qBACtB;AAEO,IAAU;CAAV,SAAA,aAAA;CAEE,MAAM,qBAAA,YAAA,qBAAqB,GAAG,KAAK,QAAQ,IAAI;CAEzC,YAAA,mBAAmB,OAAO,OAAO,EAC5C,MAAM,OAAO,WAAW,IAAI,CAAC,CAAC,SAAS,GACpC,qBAAqB,KACxB,CAAC,EACH,CAAC;AAGH,EAAA,CAAA,eAAA,aAAA,CAAA,EAAA"}

package/dist/lib/FileLimits.mjs

@@ -1,31 +1,38 @@
 import { t as __exportAll } from "./chunk-rolldown-runtime.mjs";
 //#region src/types/FileLimits.ts
 var FileLimits_exports = /* @__PURE__ */ __exportAll({
-	ACCEPTED_MIME: () => ACCEPTED_MIME,
-	isAcceptedMimeType: () => isAcceptedMimeType
+	FALLBACK_MIME_TYPE: () => FALLBACK_MIME_TYPE,
+	toStoredMimeType: () => toStoredMimeType
 });
-var ACCEPTED_MIME = {
-	"image/*": [
-		".jpg",
-		".jpeg",
-		".png",
-		".gif",
-		".webp",
-		".svg"
-	],
-	"video/*": [
-		".mp4",
-		".webm",
-		".mov"
-	],
-	"application/pdf": [".pdf"]
-};
-var isAcceptedMimeType = (type) => {
-	if (type === "application/pdf") return true;
-	if (type.startsWith("image/") || type.startsWith("video/")) return true;
-	return false;
+/** Stored in place of a type that is absent or would execute; the bytes are kept, only the label changes. */
+var FALLBACK_MIME_TYPE = "application/octet-stream";
+/**
+* Media types a browser executes when it renders them.
+*
+* A stored file is handed back through a presigned, public or `blob:` URL on the app's origin, and
+* HTML served from there runs with that origin — making an upload a stored-XSS primitive. Such
+* files are still accepted, but labelled {@link FALLBACK_MIME_TYPE} so they download rather than
+* render. Matches the blob service's own `ACTIVE_CONTENT_TYPES`, minus SVG, which image previews
+* rely on.
+*/
+var ACTIVE_CONTENT_TYPES = /* @__PURE__ */ new Set([
+	"text/html",
+	"application/xhtml+xml",
+	"text/xml",
+	"application/xml"
+]);
+/**
+* The media type to store for an upload. Every type is accepted — the file plugin keeps bytes it
+* cannot preview — so this never rejects; it only neutralizes types that are missing or executable.
+* Compared case-insensitively and without parameters: RFC 2045 defines type and subtype as
+* case-insensitive, and `text/html; charset=utf-8` is still HTML.
+*/
+var toStoredMimeType = (type) => {
+	const declared = type?.trim() ?? "";
+	const base = declared.split(";")[0].trim().toLowerCase();
+	return base.length === 0 || ACTIVE_CONTENT_TYPES.has(base) ? FALLBACK_MIME_TYPE : declared;
 };
 //#endregion
-export { ACCEPTED_MIME, isAcceptedMimeType, FileLimits_exports as t };
+export { FALLBACK_MIME_TYPE, FileLimits_exports as t, toStoredMimeType };
 
 //# sourceMappingURL=FileLimits.mjs.map

package/dist/lib/FileLimits.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"FileLimits.mjs","names":[],"sources":["../../src/types/FileLimits.ts"],"sourcesContent":["//\n// Copyright 2026 DXOS.org\n//\n\nexport const ACCEPTED_MIME: Record<string, string[]> = {\n  'image/*': ['.jpg', '.jpeg', '.png', '.gif', '.webp', '.svg'],\n  'video/*': ['.mp4', '.webm', '.mov'],\n  'application/pdf': ['.pdf'],\n};\n\nexport const isAcceptedMimeType = (type: string): boolean => {\n  if (type === 'application/pdf') {\n    return true;\n  }\n  if (type.startsWith('image/') || type.startsWith('video/')) {\n    return true;\n  }\n  return false;\n};\n"],"mappings":";;;;;;AAIA,IAAa,gBAA0C;CACrD,WAAW;EAAC;EAAQ;EAAS;EAAQ;EAAQ;EAAS;CAAM;CAC5D,WAAW;EAAC;EAAQ;EAAS;CAAM;CACnC,mBAAmB,CAAC,MAAM;AAC5B;AAEA,IAAa,sBAAsB,SAA0B;CAC3D,IAAI,SAAS,mBACX,OAAO;CAET,IAAI,KAAK,WAAW,QAAQ,KAAK,KAAK,WAAW,QAAQ,GACvD,OAAO;CAET,OAAO;AACT"}
+{"version":3,"file":"FileLimits.mjs","names":[],"sources":["../../src/types/FileLimits.ts"],"sourcesContent":["//\n// Copyright 2026 DXOS.org\n//\n\n/** Stored in place of a type that is absent or would execute; the bytes are kept, only the label changes. */\nexport const FALLBACK_MIME_TYPE = 'application/octet-stream';\n\n/**\n * Media types a browser executes when it renders them.\n *\n * A stored file is handed back through a presigned, public or `blob:` URL on the app's origin, and\n * HTML served from there runs with that origin — making an upload a stored-XSS primitive. Such\n * files are still accepted, but labelled {@link FALLBACK_MIME_TYPE} so they download rather than\n * render. Matches the blob service's own `ACTIVE_CONTENT_TYPES`, minus SVG, which image previews\n * rely on.\n */\nconst ACTIVE_CONTENT_TYPES = new Set(['text/html', 'application/xhtml+xml', 'text/xml', 'application/xml']);\n\n/**\n * The media type to store for an upload. Every type is accepted — the file plugin keeps bytes it\n * cannot preview — so this never rejects; it only neutralizes types that are missing or executable.\n * Compared case-insensitively and without parameters: RFC 2045 defines type and subtype as\n * case-insensitive, and `text/html; charset=utf-8` is still HTML.\n */\nexport const toStoredMimeType = (type: string | undefined): string => {\n  const declared = type?.trim() ?? '';\n  const base = declared.split(';')[0].trim().toLowerCase();\n  return base.length === 0 || ACTIVE_CONTENT_TYPES.has(base) ? FALLBACK_MIME_TYPE : declared;\n};\n"],"mappings":";;;;;;;AAKA,IAAa,qBAAqB;;;;;;;;;;AAWlC,IAAM,uCAAuB,IAAI,IAAI;CAAC;CAAa;CAAyB;CAAY;AAAiB,CAAC;;;;;;;AAQ1G,IAAa,oBAAoB,SAAqC;CACpE,MAAM,WAAW,MAAM,KAAK,KAAK;CACjC,MAAM,OAAO,SAAS,MAAM,GAAG,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC,YAAY;CACvD,OAAO,KAAK,WAAW,KAAK,qBAAqB,IAAI,IAAI,IAAI,qBAAqB;AACpF"}

package/dist/lib/FileOperation.mjs

@@ -9,7 +9,11 @@ import * as Struct from "effect/Struct";
 //#region src/types/FileOperation.ts
 var FileOperation_exports = /* @__PURE__ */ __exportAll({
 	Create: () => Create,
-	Read: () => Read
+	CreateFromSource: () => CreateFromSource,
+	CreateFromUpload: () => CreateFromUpload,
+	FileSource: () => FileSource,
+	Read: () => Read,
+	ResolveDownload: () => ResolveDownload
 });
 var Create = Operation.make({
 	meta: {
@@ -21,6 +25,71 @@ var Create = Operation.make({
 	input: FileAction.CreateFileSchema.mapFields(Struct.assign({ db: Database.Database })),
 	output: Schema.Struct({ object: Type.getSchema(File.File) })
 });
+/**
+* Where the bytes come from. Mirrors `ContentBlock.ImageSource` rather than inventing a shape — it
+* is how this repo already models "bytes, or a pointer to bytes".
+*
+* Two arms because their costs differ sharply: `base64` rides in the tool-call arguments and so
+* occupies the caller's context, while `http` is fetched by the host and never crosses it.
+*/
+var FileSource = Schema.Union([Schema.Struct({
+	type: Schema.tag("base64"),
+	mediaType: Schema.String.annotate({ description: "MIME type of the encoded bytes, e.g. image/png." }),
+	data: Schema.String.annotate({ description: "Base64-encoded file contents." })
+}), Schema.Struct({
+	type: Schema.tag("http"),
+	url: Schema.String.annotate({ description: "HTTPS URL the host downloads. Must not be a private address." })
+})]);
+/**
+* Creates a file from serializable input, so an agent can reach it.
+*
+* Separate from {@link Create} rather than replacing it: `Create` takes a live browser `File`, which
+* is right for the upload UI and cannot render as JSON Schema — an operation whose input cannot is
+* dropped from the registry silently, and so is invisible to any tool caller.
+*
+* Takes the database as a service rather than an input field, which is both what makes the input
+* serializable and what forces the caller to name a space.
+*/
+var CreateFromSource = Operation.make({
+	meta: {
+		key: DXN.make("org.dxos.operation.file.createFromSource"),
+		name: "Create File From Source",
+		description: "Creates a file in the space from base64 content or an HTTPS URL, storing it via the configured backend.",
+		icon: "ph--file-plus--regular"
+	},
+	input: Schema.Struct({
+		source: FileSource,
+		name: Schema.optional(Schema.String.annotate({ description: "Filename to record on the file object." }))
+	}),
+	output: Schema.Struct({ object: Type.getSchema(File.File) }),
+	services: [Database.Service, Capability.Service]
+});
+/**
+* Creates a file from bytes already uploaded to blob storage over a signed URL.
+*
+* The third arm alongside {@link CreateFromSource}'s two, and the one for a file that exists only
+* on the caller's disk: `base64` would have a model emit the bytes token by token, and `http`
+* requires them to already be served somewhere public. Here the caller uploads directly (see the
+* MCP server's `createUpload` tool) and passes only the id, so a screen recording costs the same
+* few tokens as a screenshot.
+*
+* No media type or size input: nothing the caller says about the bytes is trusted or needed, since
+* the blob service measured them as they arrived.
+*/
+var CreateFromUpload = Operation.make({
+	meta: {
+		key: DXN.make("org.dxos.operation.file.createFromUpload"),
+		name: "Create File From Upload",
+		description: "Creates a file in the space from a completed direct upload, given the uploadId returned by the createUpload tool. Use after the upload command has succeeded.",
+		icon: "ph--upload--regular"
+	},
+	input: Schema.Struct({
+		uploadId: Schema.String.annotate({ description: "The uploadId returned by createUpload, whose bytes have already been uploaded." }),
+		name: Schema.optional(Schema.String.annotate({ description: "Filename to record on the file object." }))
+	}),
+	output: Schema.Struct({ object: Type.getSchema(File.File) }),
+	services: [Database.Service, Capability.Service]
+});
 var Read = Operation.make({
 	meta: {
 		key: DXN.make("org.dxos.operation.file.read"),
@@ -32,7 +101,31 @@ var Read = Operation.make({
 	output: ContentBlock.ContentBlockResult,
 	services: [Database.Service]
 });
+/**
+* Names a file's bytes to the host that will sign a download URL for them — the reverse of
+* {@link CreateFromUpload}.
+*
+* Host-internal: the MCP hosts' `createDownload` tool invokes it and signs the URL, since the
+* signing secret (EDGE) or the loopback listener (`dx mcp serve`) lives in the host, not in the
+* operation runtime. No skill lists it, so it is never offered to a model directly.
+*/
+var ResolveDownload = Operation.make({
+	meta: {
+		key: DXN.make("org.dxos.operation.file.resolveDownload"),
+		name: "Resolve File Download",
+		description: "Resolves a file to the id its host signs a download URL for.",
+		icon: "ph--file-arrow-down--regular"
+	},
+	input: Schema.Struct({ file: Ref.Ref(File.File).annotate({ description: "The file to download." }) }),
+	output: Schema.Struct({
+		downloadId: Schema.String.annotate({ description: "Opaque to the caller; names the bytes to the host that signs the download URL." }),
+		name: Schema.optional(Schema.String),
+		type: Schema.String,
+		size: Schema.Number
+	}),
+	services: [Database.Service]
+});
 //#endregion
-export { Create, Read, FileOperation_exports as t };
+export { Create, CreateFromSource, CreateFromUpload, FileSource, Read, ResolveDownload, FileOperation_exports as t };
 
 //# sourceMappingURL=FileOperation.mjs.map

package/dist/lib/FileOperation.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"FileOperation.mjs","names":[],"sources":["../../src/types/FileOperation.ts"],"sourcesContent":["//\n// Copyright 2026 DXOS.org\n//\n\n// @import-as-namespace\n\nimport * as Schema from 'effect/Schema';\nimport * as Struct from 'effect/Struct';\n\nimport * as Capability from '@dxos/app-framework/Capability';\nimport * as Operation from '@dxos/compute/Operation';\nimport { Database, DXN, Ref, Type } from '@dxos/echo';\nimport { ContentBlock, File } from '@dxos/types';\n\nimport * as FileCapabilities from './FileCapabilities';\n\nexport const Create = Operation.make({\n  meta: { key: DXN.make('org.dxos.operation.file.create'), name: 'Create File', icon: 'ph--file--regular' },\n  services: [Capability.Service],\n  input: FileCapabilities.FileAction.CreateFileSchema.mapFields(Struct.assign({ db: Database.Database })),\n  output: Schema.Struct({\n    object: Type.getSchema(File.File),\n  }),\n});\n\nexport const Read = Operation.make({\n  meta: {\n    key: DXN.make('org.dxos.operation.file.read'),\n    name: 'Read File',\n    description:\n      'Reads the contents of a file and returns them as a File content block (data URL for inline files, original URL for external files).',\n    icon: 'ph--file-arrow-down--regular',\n  },\n  input: Schema.Struct({\n    file: Ref.Ref(File.File).annotate({\n      description: 'The file to read.',\n    }),\n  }),\n  output: ContentBlock.ContentBlockResult,\n  services: [Database.Service],\n});\n"],"mappings":";;;;;;;;;;;;;AAgBA,IAAa,SAAS,UAAU,KAAK;CACnC,MAAM;EAAE,KAAK,IAAI,KAAK,gCAAgC;EAAG,MAAM;EAAe,MAAM;CAAoB;CACxG,UAAU,CAAC,WAAW,OAAO;CAC7B,OAAA,WAAmC,iBAAiB,UAAU,OAAO,OAAO,EAAE,IAAI,SAAS,SAAS,CAAC,CAAC;CACtG,QAAQ,OAAO,OAAO,EACpB,QAAQ,KAAK,UAAU,KAAK,IAAI,EAClC,CAAC;AACH,CAAC;AAED,IAAa,OAAO,UAAU,KAAK;CACjC,MAAM;EACJ,KAAK,IAAI,KAAK,8BAA8B;EAC5C,MAAM;EACN,aACE;EACF,MAAM;CACR;CACA,OAAO,OAAO,OAAO,EACnB,MAAM,IAAI,IAAI,KAAK,IAAI,CAAC,CAAC,SAAS,EAChC,aAAa,oBACf,CAAC,EACH,CAAC;CACD,QAAQ,aAAa;CACrB,UAAU,CAAC,SAAS,OAAO;AAC7B,CAAC"}
+{"version":3,"file":"FileOperation.mjs","names":[],"sources":["../../src/types/FileOperation.ts"],"sourcesContent":["//\n// Copyright 2026 DXOS.org\n//\n\n// @import-as-namespace\n\nimport * as Schema from 'effect/Schema';\nimport * as Struct from 'effect/Struct';\n\nimport * as Capability from '@dxos/app-framework/Capability';\nimport * as Operation from '@dxos/compute/Operation';\nimport { Database, DXN, Ref, Type } from '@dxos/echo';\nimport { ContentBlock, File } from '@dxos/types';\n\nimport * as FileCapabilities from './FileCapabilities.ts';\n\nexport const Create = Operation.make({\n  meta: { key: DXN.make('org.dxos.operation.file.create'), name: 'Create File', icon: 'ph--file--regular' },\n  services: [Capability.Service],\n  input: FileCapabilities.FileAction.CreateFileSchema.mapFields(Struct.assign({ db: Database.Database })),\n  output: Schema.Struct({\n    object: Type.getSchema(File.File),\n  }),\n});\n\n/**\n * Where the bytes come from. Mirrors `ContentBlock.ImageSource` rather than inventing a shape — it\n * is how this repo already models \"bytes, or a pointer to bytes\".\n *\n * Two arms because their costs differ sharply: `base64` rides in the tool-call arguments and so\n * occupies the caller's context, while `http` is fetched by the host and never crosses it.\n */\nexport const FileSource = Schema.Union([\n  Schema.Struct({\n    type: Schema.tag('base64'),\n    mediaType: Schema.String.annotate({ description: 'MIME type of the encoded bytes, e.g. image/png.' }),\n    data: Schema.String.annotate({ description: 'Base64-encoded file contents.' }),\n  }),\n  Schema.Struct({\n    type: Schema.tag('http'),\n    url: Schema.String.annotate({ description: 'HTTPS URL the host downloads. Must not be a private address.' }),\n  }),\n]);\n\n/**\n * Creates a file from serializable input, so an agent can reach it.\n *\n * Separate from {@link Create} rather than replacing it: `Create` takes a live browser `File`, which\n * is right for the upload UI and cannot render as JSON Schema — an operation whose input cannot is\n * dropped from the registry silently, and so is invisible to any tool caller.\n *\n * Takes the database as a service rather than an input field, which is both what makes the input\n * serializable and what forces the caller to name a space.\n */\nexport const CreateFromSource = Operation.make({\n  meta: {\n    key: DXN.make('org.dxos.operation.file.createFromSource'),\n    name: 'Create File From Source',\n    description:\n      'Creates a file in the space from base64 content or an HTTPS URL, storing it via the configured backend.',\n    icon: 'ph--file-plus--regular',\n  },\n  input: Schema.Struct({\n    source: FileSource,\n    name: Schema.optional(Schema.String.annotate({ description: 'Filename to record on the file object.' })),\n  }),\n  output: Schema.Struct({\n    object: Type.getSchema(File.File),\n  }),\n  services: [Database.Service, Capability.Service],\n});\n\n/**\n * Creates a file from bytes already uploaded to blob storage over a signed URL.\n *\n * The third arm alongside {@link CreateFromSource}'s two, and the one for a file that exists only\n * on the caller's disk: `base64` would have a model emit the bytes token by token, and `http`\n * requires them to already be served somewhere public. Here the caller uploads directly (see the\n * MCP server's `createUpload` tool) and passes only the id, so a screen recording costs the same\n * few tokens as a screenshot.\n *\n * No media type or size input: nothing the caller says about the bytes is trusted or needed, since\n * the blob service measured them as they arrived.\n */\nexport const CreateFromUpload = Operation.make({\n  meta: {\n    key: DXN.make('org.dxos.operation.file.createFromUpload'),\n    name: 'Create File From Upload',\n    description:\n      'Creates a file in the space from a completed direct upload, given the uploadId returned by ' +\n      'the createUpload tool. Use after the upload command has succeeded.',\n    icon: 'ph--upload--regular',\n  },\n  input: Schema.Struct({\n    uploadId: Schema.String.annotate({\n      description: 'The uploadId returned by createUpload, whose bytes have already been uploaded.',\n    }),\n    name: Schema.optional(Schema.String.annotate({ description: 'Filename to record on the file object.' })),\n  }),\n  output: Schema.Struct({\n    object: Type.getSchema(File.File),\n  }),\n  services: [Database.Service, Capability.Service],\n});\n\nexport const Read = Operation.make({\n  meta: {\n    key: DXN.make('org.dxos.operation.file.read'),\n    name: 'Read File',\n    description:\n      'Reads the contents of a file and returns them as a File content block (data URL for inline files, original URL for external files).',\n    icon: 'ph--file-arrow-down--regular',\n  },\n  input: Schema.Struct({\n    file: Ref.Ref(File.File).annotate({\n      description: 'The file to read.',\n    }),\n  }),\n  output: ContentBlock.ContentBlockResult,\n  services: [Database.Service],\n});\n\n/**\n * Names a file's bytes to the host that will sign a download URL for them — the reverse of\n * {@link CreateFromUpload}.\n *\n * Host-internal: the MCP hosts' `createDownload` tool invokes it and signs the URL, since the\n * signing secret (EDGE) or the loopback listener (`dx mcp serve`) lives in the host, not in the\n * operation runtime. No skill lists it, so it is never offered to a model directly.\n */\nexport const ResolveDownload = Operation.make({\n  meta: {\n    key: DXN.make('org.dxos.operation.file.resolveDownload'),\n    name: 'Resolve File Download',\n    description: 'Resolves a file to the id its host signs a download URL for.',\n    icon: 'ph--file-arrow-down--regular',\n  },\n  input: Schema.Struct({\n    file: Ref.Ref(File.File).annotate({ description: 'The file to download.' }),\n  }),\n  output: Schema.Struct({\n    downloadId: Schema.String.annotate({\n      description: 'Opaque to the caller; names the bytes to the host that signs the download URL.',\n    }),\n    name: Schema.optional(Schema.String),\n    type: Schema.String,\n    size: Schema.Number,\n  }),\n  services: [Database.Service],\n});\n"],"mappings":";;;;;;;;;;;;;;;;;AAgBA,IAAa,SAAS,UAAU,KAAK;CACnC,MAAM;EAAE,KAAK,IAAI,KAAK,gCAAgC;EAAG,MAAM;EAAe,MAAM;CAAoB;CACxG,UAAU,CAAC,WAAW,OAAO;CAC7B,OAAA,WAAmC,iBAAiB,UAAU,OAAO,OAAO,EAAE,IAAI,SAAS,SAAS,CAAC,CAAC;CACtG,QAAQ,OAAO,OAAO,EACpB,QAAQ,KAAK,UAAU,KAAK,IAAI,EAClC,CAAC;AACH,CAAC;;;;;;;;AASD,IAAa,aAAa,OAAO,MAAM,CACrC,OAAO,OAAO;CACZ,MAAM,OAAO,IAAI,QAAQ;CACzB,WAAW,OAAO,OAAO,SAAS,EAAE,aAAa,kDAAkD,CAAC;CACpG,MAAM,OAAO,OAAO,SAAS,EAAE,aAAa,gCAAgC,CAAC;AAC/E,CAAC,GACD,OAAO,OAAO;CACZ,MAAM,OAAO,IAAI,MAAM;CACvB,KAAK,OAAO,OAAO,SAAS,EAAE,aAAa,+DAA+D,CAAC;AAC7G,CAAC,CACH,CAAC;;;;;;;;;;;AAYD,IAAa,mBAAmB,UAAU,KAAK;CAC7C,MAAM;EACJ,KAAK,IAAI,KAAK,0CAA0C;EACxD,MAAM;EACN,aACE;EACF,MAAM;CACR;CACA,OAAO,OAAO,OAAO;EACnB,QAAQ;EACR,MAAM,OAAO,SAAS,OAAO,OAAO,SAAS,EAAE,aAAa,yCAAyC,CAAC,CAAC;CACzG,CAAC;CACD,QAAQ,OAAO,OAAO,EACpB,QAAQ,KAAK,UAAU,KAAK,IAAI,EAClC,CAAC;CACD,UAAU,CAAC,SAAS,SAAS,WAAW,OAAO;AACjD,CAAC;;;;;;;;;;;;;AAcD,IAAa,mBAAmB,UAAU,KAAK;CAC7C,MAAM;EACJ,KAAK,IAAI,KAAK,0CAA0C;EACxD,MAAM;EACN,aACE;EAEF,MAAM;CACR;CACA,OAAO,OAAO,OAAO;EACnB,UAAU,OAAO,OAAO,SAAS,EAC/B,aAAa,iFACf,CAAC;EACD,MAAM,OAAO,SAAS,OAAO,OAAO,SAAS,EAAE,aAAa,yCAAyC,CAAC,CAAC;CACzG,CAAC;CACD,QAAQ,OAAO,OAAO,EACpB,QAAQ,KAAK,UAAU,KAAK,IAAI,EAClC,CAAC;CACD,UAAU,CAAC,SAAS,SAAS,WAAW,OAAO;AACjD,CAAC;AAED,IAAa,OAAO,UAAU,KAAK;CACjC,MAAM;EACJ,KAAK,IAAI,KAAK,8BAA8B;EAC5C,MAAM;EACN,aACE;EACF,MAAM;CACR;CACA,OAAO,OAAO,OAAO,EACnB,MAAM,IAAI,IAAI,KAAK,IAAI,CAAC,CAAC,SAAS,EAChC,aAAa,oBACf,CAAC,EACH,CAAC;CACD,QAAQ,aAAa;CACrB,UAAU,CAAC,SAAS,OAAO;AAC7B,CAAC;;;;;;;;;AAUD,IAAa,kBAAkB,UAAU,KAAK;CAC5C,MAAM;EACJ,KAAK,IAAI,KAAK,yCAAyC;EACvD,MAAM;EACN,aAAa;EACb,MAAM;CACR;CACA,OAAO,OAAO,OAAO,EACnB,MAAM,IAAI,IAAI,KAAK,IAAI,CAAC,CAAC,SAAS,EAAE,aAAa,wBAAwB,CAAC,EAC5E,CAAC;CACD,QAAQ,OAAO,OAAO;EACpB,YAAY,OAAO,OAAO,SAAS,EACjC,aAAa,iFACf,CAAC;EACD,MAAM,OAAO,SAAS,OAAO,MAAM;EACnC,MAAM,OAAO;EACb,MAAM,OAAO;CACf,CAAC;CACD,UAAU,CAAC,SAAS,OAAO;AAC7B,CAAC"}

package/dist/lib/FileSkill.mjs

@@ -0,0 +1,65 @@
+import { t as __exportAll } from "./chunk-rolldown-runtime.mjs";
+import { FileOperation } from "#types";
+import * as Operation from "@dxos/compute/Operation";
+import * as Skill from "@dxos/compute/Skill";
+import * as Template from "@dxos/compute/Template";
+import { trim } from "@dxos/util";
+//#region src/skills/FileSkill.ts
+var FileSkill_exports = /* @__PURE__ */ __exportAll({
+	key: () => key,
+	make: () => make,
+	operations: () => operations
+});
+var key = "org.dxos.skill.file";
+var operations = [
+	FileOperation.Read,
+	FileOperation.CreateFromSource,
+	FileOperation.CreateFromUpload
+];
+var make = () => Skill.make({
+	key,
+	name: "File",
+	description: "Read the contents of files (images, videos, PDFs), and add new files to a space.",
+	tools: Skill.toolDefinitions({ operations }),
+	instructions: Template.make({ source: trim`
+        {{! File }}
+
+        You can read the contents of files.
+        Calling the ${Operation.toolName(FileOperation.Read)} tool returns the file contents as a File content block (a data URL for
+        inline files, the original URL for external files). The model receives the file natively
+        and can describe, transcribe, or otherwise reason over its contents.
+
+        You can also add a file to the space with the ${Operation.toolName(FileOperation.CreateFromSource)} tool, from one of two sources:
+        - \`{ "type": "http", "url": "https://..." }\` when the content is already reachable at a URL.
+          Prefer this whenever it applies: the bytes are fetched by the host and never pass through
+          the conversation. The URL must be https and must not point at a private address.
+        - \`{ "type": "base64", "mediaType": "image/png", "data": "..." }\` when you hold the bytes
+          yourself, such as an image you generated. Keep this under 1MB — the encoded payload counts
+          against the conversation, so a large file is slow and expensive before it is anything else.
+
+        For a file that is already on your own disk -- a screenshot you just took, a screen
+        recording, a log bundle -- use neither arm above. Upload it directly:
+        1. Call the host's \`createUpload\` tool (with the file's \`name\`, and its \`size\` if known).
+        2. Run the \`command\` it returns in a shell; it transfers the bytes with \`curl\`.
+        3. Call ${Operation.toolName(FileOperation.CreateFromUpload)} with the returned \`uploadId\` to create the file object.
+        The bytes go from disk to storage without passing through this conversation, so the cost is
+        the same whether the file is 40KB or 90MB. Base64 is never the right choice for a video.
+
+        To save a file from the space to your own disk, download it directly:
+        1. Call the host's \`createDownload\` tool with the file's reference.
+        2. Run the \`command\` it returns in a shell; it saves the file in the working directory.
+        Use ${Operation.toolName(FileOperation.Read)} only when you need to look at a file yourself; never read one
+        just to write its bytes out. \`createUpload\` and \`createDownload\` are tools of the MCP host, not
+        operations; a host without them (the in-app chat) has no direct transfer.
+
+        Any file type is accepted; HTML and XML are stored as \`application/octet-stream\` so they
+        download rather than render. Always pass the true media type of the content; do not infer it
+        from a file extension.
+      ` }),
+	agentCanEnable: true,
+	mcpPrompt: true
+});
+//#endregion
+export { key, make, operations, FileSkill_exports as t };
+
+//# sourceMappingURL=FileSkill.mjs.map

package/dist/lib/FileSkill.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"FileSkill.mjs","names":[],"sources":["../../src/skills/FileSkill.ts"],"sourcesContent":["//\n// Copyright 2026 DXOS.org\n//\n\nimport * as Operation from '@dxos/compute/Operation';\nimport * as Skill from '@dxos/compute/Skill';\nimport * as Template from '@dxos/compute/Template';\nimport { trim } from '@dxos/util';\n\nimport { FileOperation } from '#types';\n\nexport const key = 'org.dxos.skill.file';\n\n// Carried on the definition so a host that serves it over MCP can map its tool ids back to\n// operations without the plugin being activated.\nexport const operations: readonly Operation.Definition.Any[] = [\n  FileOperation.Read,\n  FileOperation.CreateFromSource,\n  FileOperation.CreateFromUpload,\n];\n\nexport const make = () =>\n  Skill.make({\n    key: key,\n    name: 'File',\n    description: 'Read the contents of files (images, videos, PDFs), and add new files to a space.',\n    tools: Skill.toolDefinitions({\n      operations,\n    }),\n    instructions: Template.make({\n      source: trim`\n        {{! File }}\n\n        You can read the contents of files.\n        Calling the ${Operation.toolName(FileOperation.Read)} tool returns the file contents as a File content block (a data URL for\n        inline files, the original URL for external files). The model receives the file natively\n        and can describe, transcribe, or otherwise reason over its contents.\n\n        You can also add a file to the space with the ${Operation.toolName(FileOperation.CreateFromSource)} tool, from one of two sources:\n        - \\`{ \"type\": \"http\", \"url\": \"https://...\" }\\` when the content is already reachable at a URL.\n          Prefer this whenever it applies: the bytes are fetched by the host and never pass through\n          the conversation. The URL must be https and must not point at a private address.\n        - \\`{ \"type\": \"base64\", \"mediaType\": \"image/png\", \"data\": \"...\" }\\` when you hold the bytes\n          yourself, such as an image you generated. Keep this under 1MB — the encoded payload counts\n          against the conversation, so a large file is slow and expensive before it is anything else.\n\n        For a file that is already on your own disk -- a screenshot you just took, a screen\n        recording, a log bundle -- use neither arm above. Upload it directly:\n        1. Call the host's \\`createUpload\\` tool (with the file's \\`name\\`, and its \\`size\\` if known).\n        2. Run the \\`command\\` it returns in a shell; it transfers the bytes with \\`curl\\`.\n        3. Call ${Operation.toolName(FileOperation.CreateFromUpload)} with the returned \\`uploadId\\` to create the file object.\n        The bytes go from disk to storage without passing through this conversation, so the cost is\n        the same whether the file is 40KB or 90MB. Base64 is never the right choice for a video.\n\n        To save a file from the space to your own disk, download it directly:\n        1. Call the host's \\`createDownload\\` tool with the file's reference.\n        2. Run the \\`command\\` it returns in a shell; it saves the file in the working directory.\n        Use ${Operation.toolName(FileOperation.Read)} only when you need to look at a file yourself; never read one\n        just to write its bytes out. \\`createUpload\\` and \\`createDownload\\` are tools of the MCP host, not\n        operations; a host without them (the in-app chat) has no direct transfer.\n\n        Any file type is accepted; HTML and XML are stored as \\`application/octet-stream\\` so they\n        download rather than render. Always pass the true media type of the content; do not infer it\n        from a file extension.\n      `,\n    }),\n    agentCanEnable: true,\n    // Projected by the MCP hosts (`dx mcp serve`, EDGE's worker), so `file.createFromUpload` — the\n    // other half of their `createUpload` tool — is discoverable and invocable there.\n    mcpPrompt: true,\n  });\n"],"mappings":";;;;;;;;;;;;AAWA,IAAa,MAAM;AAInB,IAAa,aAAkD;CAC7D,cAAc;CACd,cAAc;CACd,cAAc;AAChB;AAEA,IAAa,aACX,MAAM,KAAK;CACJ;CACL,MAAM;CACN,aAAa;CACb,OAAO,MAAM,gBAAgB,EAC3B,WACF,CAAC;CACD,cAAc,SAAS,KAAK,EAC1B,QAAQ,IAAI;;;;sBAII,UAAU,SAAS,cAAc,IAAI,EAAE;;;;wDAIL,UAAU,SAAS,cAAc,gBAAgB,EAAE;;;;;;;;;;;;kBAYzF,UAAU,SAAS,cAAc,gBAAgB,EAAE;;;;;;;cAOvD,UAAU,SAAS,cAAc,IAAI,EAAE;;;;;;;QAQjD,CAAC;CACD,gBAAgB;CAGhB,WAAW;AACb,CAAC"}