From b3cae4f2b09c2ec840b0a4b2d0e71e9fa4b82527 Mon Sep 17 00:00:00 2001 From: Yiling-J Date: Tue, 27 Oct 2026 14:37:26 +0800 Subject: [PATCH] feat: move MCP to /mcp and add teammate operations (#500) * feat(operations): move MCP to /mcp and add search, comment, metadata, version, and upload operations - Serve the MCP server at /mcp instead of /api/mcp - Add search_assets, copy_assets, get_folder_instructions, list_comments, create_comment, resolve_comment, list_metadata_fields, update_asset_metadata, create_version_stack, list_versions, and remove_version on the agent, MCP, and CLI - Add create_file and create_version (agent, MCP) with Creation Context metadata, and complete_upload (MCP) for presigned two-step uploads - Replace the native agent create_file/create_version tools with Operation-backed ones - Route the comment-complete, metadata, copy, version stack, and AGENTS.md read REST endpoints through their Operations * docs(readme): add built-in MCP server and CLI to features list --- AGENTS.md | 2 +- CHANGELOG.md | 13 +- README.md | 3 +- README_CN.md | 3 +- apps/cli/README.md | 67 ++- apps/cli/src/operations/generate.ts | 21 +- apps/cli/src/program.test.ts | 269 +++++++++ apps/web/src/index.ts | 2 + docs/developer/mcp-server.mdx | 54 +- docs/using-shumai/agent-tools.mdx | 55 ++ .../src/database-session-storage.test.ts | 2 + packages/agent/src/index.ts | 13 +- .../agent/src/operation-extensions/index.ts | 1 + .../src/operation-extensions/upload.test.ts | 447 ++++++++++++++ .../agent/src/operation-extensions/upload.ts | 158 +++++ packages/agent/src/operation-tools.test.ts | 18 + packages/agent/src/operation-tools.ts | 59 +- .../src/reproduce-tool-null-coercion.test.ts | 117 ---- packages/agent/src/tools/create-file.test.ts | 408 ------------- packages/agent/src/tools/create-file.ts | 160 ----- .../agent/src/tools/create-version.test.ts | 256 -------- packages/agent/src/tools/create-version.ts | 110 ---- packages/api/src/file.test.ts | 86 ++- packages/api/src/file.ts | 99 +--- packages/api/src/folder.test.ts | 30 +- packages/api/src/folder.ts | 23 +- packages/api/src/index.ts | 11 +- .../api/src/mcp-server.integration.test.ts | 71 ++- packages/api/src/mcp-server.test.ts | 14 + packages/api/src/mcp-server.ts | 11 +- packages/api/src/project.test.ts | 29 +- packages/api/src/project.ts | 47 +- packages/api/src/versionStack.test.ts | 53 +- packages/api/src/versionStack.ts | 49 +- packages/core/src/asset/asset.ts | 53 +- packages/core/src/comment/comment.ts | 62 ++ .../core/src/operations/asset/copy-assets.ts | 35 ++ .../asset/get-folder-instructions.ts | 13 + .../src/operations/asset/search-assets.ts | 39 ++ .../core/src/operations/collaboration.test.ts | 545 ++++++++++++++++++ .../src/operations/comment/create-comment.ts | 31 + .../src/operations/comment/list-comments.ts | 47 ++ .../src/operations/comment/resolve-comment.ts | 29 + packages/core/src/operations/errors.ts | 22 + packages/core/src/operations/index.ts | 14 + .../metadata/list-metadata-fields.ts | 40 ++ .../metadata/update-asset-metadata.ts | 61 ++ .../core/src/operations/operations.test.ts | 1 + packages/core/src/operations/registry.ts | 28 + packages/core/src/operations/upload.test.ts | 298 ++++++++++ .../src/operations/upload/complete-upload.ts | 61 ++ .../core/src/operations/upload/create-file.ts | 20 + .../src/operations/upload/create-version.ts | 20 + .../src/operations/upload/start-upload.ts | 70 +++ .../version/create-version-stack.ts | 39 ++ .../src/operations/version/list-versions.ts | 32 + .../src/operations/version/remove-version.ts | 33 ++ packages/core/src/upload/pending-upload.ts | 130 +++++ packages/dtos/src/auditLog.ts | 2 + .../e2e/workflow/agent-operations.test.ts | 196 +++++-- packages/operations/src/asset/copy-assets.ts | 36 ++ .../src/asset/get-folder-instructions.ts | 26 + .../operations/src/asset/search-assets.ts | 116 ++++ .../operations/src/comment/create-comment.ts | 40 ++ .../operations/src/comment/list-comments.ts | 79 +++ .../operations/src/comment/resolve-comment.ts | 30 + packages/operations/src/index.ts | 14 + .../src/metadata/list-metadata-fields.ts | 68 +++ .../src/metadata/update-asset-metadata.ts | 36 ++ packages/operations/src/registry.test.ts | 51 +- packages/operations/src/registry.ts | 28 + .../operations/src/upload/complete-upload.ts | 19 + packages/operations/src/upload/create-file.ts | 55 ++ .../operations/src/upload/create-version.ts | 31 + .../src/version/create-version-stack.ts | 29 + .../operations/src/version/list-versions.ts | 40 ++ .../operations/src/version/remove-version.ts | 25 + .../components/settings/AgentFormDialog.tsx | 55 ++ .../components/settings/QuotaRuleDialog.tsx | 4 + packages/webui/messages/en.json | 22 + packages/webui/messages/zh.json | 22 + 81 files changed, 4111 insertions(+), 1397 deletions(-) create mode 100644 packages/agent/src/operation-extensions/upload.test.ts create mode 100644 packages/agent/src/operation-extensions/upload.ts delete mode 100644 packages/agent/src/reproduce-tool-null-coercion.test.ts delete mode 100644 packages/agent/src/tools/create-file.test.ts delete mode 100644 packages/agent/src/tools/create-file.ts delete mode 100644 packages/agent/src/tools/create-version.test.ts delete mode 100644 packages/agent/src/tools/create-version.ts create mode 100644 packages/core/src/comment/comment.ts create mode 100644 packages/core/src/operations/asset/copy-assets.ts create mode 100644 packages/core/src/operations/asset/get-folder-instructions.ts create mode 100644 packages/core/src/operations/asset/search-assets.ts create mode 100644 packages/core/src/operations/collaboration.test.ts create mode 100644 packages/core/src/operations/comment/create-comment.ts create mode 100644 packages/core/src/operations/comment/list-comments.ts create mode 100644 packages/core/src/operations/comment/resolve-comment.ts create mode 100644 packages/core/src/operations/errors.ts create mode 100644 packages/core/src/operations/metadata/list-metadata-fields.ts create mode 100644 packages/core/src/operations/metadata/update-asset-metadata.ts create mode 100644 packages/core/src/operations/upload.test.ts create mode 100644 packages/core/src/operations/upload/complete-upload.ts create mode 100644 packages/core/src/operations/upload/create-file.ts create mode 100644 packages/core/src/operations/upload/create-version.ts create mode 100644 packages/core/src/operations/upload/start-upload.ts create mode 100644 packages/core/src/operations/version/create-version-stack.ts create mode 100644 packages/core/src/operations/version/list-versions.ts create mode 100644 packages/core/src/operations/version/remove-version.ts create mode 100644 packages/core/src/upload/pending-upload.ts create mode 100644 packages/operations/src/asset/copy-assets.ts create mode 100644 packages/operations/src/asset/get-folder-instructions.ts create mode 100644 packages/operations/src/asset/search-assets.ts create mode 100644 packages/operations/src/comment/create-comment.ts create mode 100644 packages/operations/src/comment/list-comments.ts create mode 100644 packages/operations/src/comment/resolve-comment.ts create mode 100644 packages/operations/src/metadata/list-metadata-fields.ts create mode 100644 packages/operations/src/metadata/update-asset-metadata.ts create mode 100644 packages/operations/src/upload/complete-upload.ts create mode 100644 packages/operations/src/upload/create-file.ts create mode 100644 packages/operations/src/upload/create-version.ts create mode 100644 packages/operations/src/version/create-version-stack.ts create mode 100644 packages/operations/src/version/list-versions.ts create mode 100644 packages/operations/src/version/remove-version.ts diff --git a/AGENTS.md b/AGENTS.md index cfecb79e..0ca59655 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -236,7 +236,7 @@ An **Operation** is a capability agents can use, defined once and exposed automa - **Tests**: real-database tests per Operation covering success, permission denial (no side effects), and audit entries. - **CLI spec**: object input fields must be listed in `cli.flatten` (one flag per sub-field, e.g. `{ videoConfig: 'video' }` → `--video-start`) or in `cli.omit` (optional fields the CLI doesn't expose). - **Surface presentation**: by default each surface shows the Operation output as JSON. To add surface-only parameters or render output differently, add an extension for that surface: - - agent: `AgentToolExtension` in `packages/agent/src/operation-extensions/` (e.g. image blocks, saving downloads into the sandbox). `parameterOverrides` and `intercept` support agent-only modes, such as `download_asset` by storage key; + - agent: `AgentToolExtension` in `packages/agent/src/operation-extensions/` (e.g. image blocks, saving downloads into the sandbox). `parameterOverrides` and `intercept` support agent-only modes, such as `download_asset` by storage key; `hiddenParameters` and `adjustParameters` reshape the tool for a session, such as `create_file` taking a sandbox path and the project's Creation Context schema; - MCP: `McpToolExtension` in `packages/api/src/mcp-extensions/` (`structuredContent` must still match the output schema); - CLI: `CliCommandExtension` in `apps/cli/src/operations/extensions/` (local I/O such as downloads). diff --git a/CHANGELOG.md b/CHANGELOG.md index 79e2399b..92b66127 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -8,25 +8,20 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). ### Added -* **mcp**: Shumai now has a built-in MCP server, so external AI agents such as Claude Code, Cursor, or Kiro can browse projects and create, rename, move, or delete folders and files with your API token and permissions +* **mcp**: Shumai now has a built-in MCP server at `https:///mcp`, so external AI agents such as Claude Code, Cursor, or Kiro can browse projects and create, rename, move, or delete folders and files with your API token and permissions. Like other MCP servers, it can also be served from its own host name, such as `https://mcp.example.com/mcp` * **agent**: The built-in agent can now list the projects you have access to, so it can find a project's root folder on its own. Team owners can turn this off per agent like other tools * **mcp**: External AI agents connected to Shumai's MCP server can now look at your files: images, video frames, PDF pages, 3D model views, and text files. Images are attached so the AI can see them, along with links that stay valid for about an hour. They can also get download links for files, as the web preview or the original upload * **cli**: New `shumai-cli download` command saves files to your computer, up to 50 at a time: the smaller web preview by default, or the original upload with `--original` * **cli**: New `shumai-cli read` command shows an image, video frames, PDF pages, a 3D model view, or the text of a file, and `--out` downloads the images into a folder. If rendering takes a while, `shumai-cli render ` picks up the result later +* **agent**: The built-in agent can now work more like a teammate: it can search for files by name, meaning, or metadata, read and post review comments (as you) and mark them resolved, set metadata such as a file's status, copy files, stack files into versions or take a version out of its stack, and read a folder's instructions for AI agents (AGENTS.md). Team owners can turn each of these off per agent +* **mcp**: External AI agents connected to Shumai's MCP server can do the same, and can now upload files and new versions: Shumai gives them a link to upload the file to, then creates the file once it's uploaded. They can also fill in a project's Creation Context fields (such as the prompt or model used) for the files they create +* **cli**: New `shumai-cli` commands to search files (`search`), copy them (`copy`), work with comments (`comment ls`, `comment add`, `comment resolve`), list and set metadata (`field ls`, `meta set`), manage versions (`version stack`, `version ls`, `version unstack`), and show a folder's instructions (`instructions`) ### Fixed -* **asset**: Fix an issue where folders created in the web app didn't record who created them -* **agent**: Fix an issue where an agent could read a comment thread from a project or team the user doesn't have access to by referencing its ID -* **agent**: Fix an issue where an agent creating a file or a new version in a folder the user can't edit still uploaded the file to storage before the request was rejected ### Changed -* **cli**: `shumai-cli` has clearer help for every command (`shumai-cli --help`), suggests the right command when you mistype one, and can print raw JSON with `--json`. `ls` can now filter by type and page through very large folders. Existing commands work as before; the npm package now needs Node.js 22.12 or later -* **agent**: When the agent lists a folder's contents, large folders are now paged with a "next page" marker instead of page numbers, and items appear in the same order as in the file browser -* **agent**: When the agent looks at a long video or a large document that takes more than about a minute to render, it no longer fails with a timeout. The agent is told the render is still in progress and picks up the frames or pages when they're ready, using the new "Get Asset Render" tool. Each call can now read at most 20 video frames, the same limit as PDF pages -* **agent**: The agent can now download several files at once (up to 50), and can get the original upload instead of the smaller web preview. Downloaded files keep the preview's file type in their name (e.g. `photo.webp`). Team owners can now turn the Download Asset tool on or off per agent in agent settings -* **api-token**: API tokens are now stored securely, so they can no longer be read back from the database. A new token is shown only once when you create it, so copy it right away; the token list now shows just the last few characters. Existing tokens keep working without any changes. ## [0.6.1] - 2026-10-24 diff --git a/README.md b/README.md index 765552d1..c526ec2f 100644 --- a/README.md +++ b/README.md @@ -38,6 +38,7 @@ Shumai is an open-source Frame.io alternative built for creative teams to collab * **Office & Document PDF Proxying via Gotenberg**: Convert Word, PowerPoint, Excel, Markdown, HTML, and CSV documents to high-quality PDF proxies for in-browser previewing using [Gotenberg](https://docs.shumai.one/using-shumai/gotenberg). * **Semantic Search**: Find assets by visual or conceptual meaning using vector embeddings. See [documentation](https://docs.shumai.one/using-shumai/semantic-search). * **NLE Export & Premiere Pro Plugin (Experimental)**: Export timestamped review comments to your favorite non-linear editor (Premiere Pro XML, DaVinci Resolve EDL, Final Cut Pro, Avid Media Composer) or use the experimental Premiere Pro UXP plugin to import media assets and auto-sync comments directly to sequence timeline markers. See [documentation](https://docs.shumai.one/using-shumai/nle-and-premiere). +* **Built-in MCP Server & CLI**: Connect external AI agents to Shumai via `/mcp` or manage projects, assets, comments, and metadata from the terminal with `shumai-cli`. But Shumai goes beyond being a Frame.io alternative. With modern models like GPT-Image-2 and Seedance 2.5, AI can already handle a surprising amount of creative work. That means you can create or update videos and images from a simple prompt without having to jump back into Photoshop, Premiere or Houdini. That is why Shumai includes a powerful agent system: @@ -231,4 +232,4 @@ For more details on installation and usage, see the [CLI Readme](apps/cli/README ## MCP Server -Shumai includes a built-in MCP server at `/api/mcp`, so external agents such as Claude Code, Cursor, or Kiro can browse and organize your projects with an API token. See the [MCP server guide](docs/developer/mcp-server.mdx) for setup. +Shumai includes a built-in MCP server at `/mcp`, so external agents such as Claude Code, Cursor, or Kiro can browse and organize your projects with an API token. See the [MCP server guide](docs/developer/mcp-server.mdx) for setup. diff --git a/README_CN.md b/README_CN.md index 8dde4fc1..efcea715 100644 --- a/README_CN.md +++ b/README_CN.md @@ -38,6 +38,7 @@ Shumai 是一个开源的 Frame.io 替代方案,专为创意团队打造,让 * **基于 Gotenberg 的文档 PDF 转码代理**:通过集成 [Gotenberg](https://docs.shumai.one/using-shumai/gotenberg) 支持将 Word、PowerPoint、Excel、Markdown、HTML 和 CSV 文档高质量转换为 PDF 代理文件进行在线预览。 * **语义搜索**:支持按画面内容或概念含义搜索素材,底层基于向量嵌入技术。详见[相关文档](https://docs.shumai.one/using-shumai/semantic-search)。 * **非编剪辑导出与 Premiere 插件(实验性)**:支持将时间戳审阅评论导出至常用非编软件(Premiere Pro XML、DaVinci Resolve EDL、Final Cut Pro、Avid Media Composer),或使用实验性的 Premiere Pro 原生 UXP 插件导入媒体素材并将评论自动同步为时间轴标记。详见[相关文档](https://docs.shumai.one/using-shumai/nle-and-premiere)。 +* **内置 MCP 服务端与 CLI 工具**:支持通过 `/mcp` 将外部 AI Agent 接入 Shumai,或使用 `shumai-cli` 在终端中管理项目、素材、评论与元数据。 但 Shumai 不仅仅只满足于 Frame.io 的开源替代。随着 GPT-Image-2、Seedance 2.5 这类强大模型的问世,AI已经生成产品级的图片/视频。很多时候,你只要给一句提示词,就能直接生成或修改图片和视频,而不用再打开 Photoshop、Premiere 或者 Houdini。也正因为这样,Shumai 才把 AI Agent 做成了核心能力: @@ -262,4 +263,4 @@ Shumai 自带一个功能完备的命令行工具(CLI),支持您直接在 ## MCP 服务器 -Shumai 内置 MCP 服务器(地址为 `/api/mcp`),Claude Code、Cursor、Kiro 等外部智能体可以使用 API 令牌连接,浏览并整理您的项目。配置方法请参阅 [MCP 服务器指南](docs/developer/mcp-server.mdx)。 +Shumai 内置 MCP 服务器(地址为 `/mcp`),Claude Code、Cursor、Kiro 等外部智能体可以使用 API 令牌连接,浏览并整理您的项目。配置方法请参阅 [MCP 服务器指南](docs/developer/mcp-server.mdx)。 diff --git a/apps/cli/README.md b/apps/cli/README.md index 4257bcab..57ca6d22 100644 --- a/apps/cli/README.md +++ b/apps/cli/README.md @@ -180,6 +180,71 @@ shumai-cli download --original - `-o`, `--out `: Folder to save the files in (default: the current folder). With `--json`, each file also gets a `path`. - `--original`: Download the original uploaded files instead of the web previews. +#### 12. Search Files + +Search a folder and all of its subfolders by name, or by meaning with `--semantic` (when AI search is enabled for the team). + +```bash +shumai-cli search -p +shumai-cli search "a calm beach at sunset" -p --semantic +``` + +- **Options:** + - `-p`, `--parent `: The folder to search in (required). + - `--type `: Search files (default) or folders. + - `--first `, `--after `: Page through many results. + +#### 13. Copy Assets + +Copy files or folders into another folder of the same team. Prints the IDs of the copies. + +```bash +shumai-cli copy -p [--with-comments] +# or using the short alias: +shumai-cli cp -p +``` + +#### 14. Comments + +```bash +# List the comments on a file, with their replies +shumai-cli comment ls +# Comment on a file, optionally at a timecode (seconds), or reply to a comment +shumai-cli comment add "The logo is too small" --at 12.5 +shumai-cli comment add "Fixed in v2" --reply-to +# Mark a comment as resolved, or unresolved again +shumai-cli comment resolve +shumai-cli comment resolve --reopen +``` + +#### 15. Metadata + +```bash +# List a project's metadata fields and their choices +shumai-cli field ls +# Set metadata values on a file, as JSON keyed by field key (select fields take an option id) +shumai-cli meta set --values '{"status": "approved", "rating": 4}' +``` + +#### 16. Version Stacks + +```bash +# Stack files in the same folder as versions; the first file is the latest +shumai-cli version stack +# List the versions in a stack, latest first +shumai-cli version ls +# Take a version out of its stack (the file is kept) +shumai-cli version unstack +``` + +#### 17. Folder Instructions + +Show a folder's instructions for AI agents (its AGENTS.md). + +```bash +shumai-cli instructions +``` + --- ## Development @@ -192,4 +257,4 @@ bun run apps/cli/src/index.ts project ls ### Adding Commands -Most commands are generated from the shared Operation definitions in `packages/operations` (see "Operations" in `AGENTS.md`). An Operation with the `cli` surface and a `cli` spec becomes a command automatically, with arguments, options, and help text derived from its input schema. It is also available to Shumai's built-in agent and MCP server. Behavior that needs the local machine, such as downloading files, goes in a CLI extension in `src/operations/extensions/` (extra options, input mapping, and output). Only commands that stream local files (`upload`, `create-version`) are written by hand in `src/program.ts`. +Most commands are generated from the shared Operation definitions in `packages/operations` (see "Operations" in `AGENTS.md`). An Operation with the `cli` surface and a `cli` spec becomes a command automatically, with arguments, options, and help text derived from its input schema (key/value inputs such as `meta set --values` take a JSON object). It is also available to Shumai's built-in agent and MCP server. Behavior that needs the local machine, such as downloading files, goes in a CLI extension in `src/operations/extensions/` (extra options, input mapping, and output). Only commands that stream local files (`upload`, `create-version`) are written by hand in `src/program.ts`; the `create_file`, `create_version`, and `complete_upload` Operations are for the agent and MCP only. diff --git a/apps/cli/src/operations/generate.ts b/apps/cli/src/operations/generate.ts index 9377498a..4dbf5427 100644 --- a/apps/cli/src/operations/generate.ts +++ b/apps/cli/src/operations/generate.ts @@ -36,6 +36,8 @@ type FieldKind = | { type: 'boolean' } | { type: 'enum'; values: string[] } | { type: 'array' } + /** A key/value object (`z.record`), passed as a JSON object. */ + | { type: 'json' } interface FieldInfo { name: string @@ -73,6 +75,7 @@ function describeSchema( else if (base instanceof z.ZodEnum) kind = { type: 'enum', values: base.options.map(String) } else if (base instanceof z.ZodArray) kind = { type: 'array' } else if (base instanceof z.ZodString) kind = { type: 'string' } + else if (base instanceof z.ZodRecord) kind = { type: 'json' } else { throw new Error(`${definition.name}.${name}: unsupported input type for the CLI`) } @@ -114,6 +117,19 @@ function parseNumber(value: string): number { return parsed } +function parseJsonObject(value: string): Record { + let parsed: unknown + try { + parsed = JSON.parse(value) + } catch { + throw new InvalidArgumentError('Not valid JSON.') + } + if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) { + throw new InvalidArgumentError('Expected a JSON object, e.g. \'{"key": "value"}\'.') + } + return parsed as Record +} + function kebab(name: string): string { return name.replace(/[A-Z]/g, (c) => `-${c.toLowerCase()}`) } @@ -166,9 +182,12 @@ export function registerOperationCommands( ? '' : field.kind.type === 'array' ? ` <${field.name}...>` - : ` <${field.name}>` + : field.kind.type === 'json' + ? ` ` + : ` <${field.name}>` const option = new Option(`${spellings.join(', ')}${valueHint}`, field.description) if (field.kind.type === 'number') option.argParser(parseNumber) + if (field.kind.type === 'json') option.argParser(parseJsonObject) if (field.kind.type === 'enum') option.choices(field.kind.values) if (field.required) option.makeOptionMandatory() cmd.addOption(option) diff --git a/apps/cli/src/program.test.ts b/apps/cli/src/program.test.ts index 04b8f1bf..5acce9bf 100644 --- a/apps/cli/src/program.test.ts +++ b/apps/cli/src/program.test.ts @@ -1,15 +1,26 @@ import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest' import type { Command } from 'commander' import { + copyAssets, + createComment, createFolder, + createVersionStack, deleteAsset, downloadAsset, getAssetRender, + getFolderInstructions, readAsset, listAssets, + listComments, + listMetadataFields, listProjects, + listVersions, moveAssets, + removeVersion, renameAsset, + resolveComment, + searchAssets, + updateAssetMetadata, } from '@shumai/operations' import type { CallOperation } from './operations/call-operation' import { CliError, formatCliError } from './operations/errors' @@ -560,6 +571,264 @@ describe('shumai-cli', () => { expect(help).not.toContain('--image') }) }) + + describe('search', () => { + it('searches a folder by name with the maximum page size', async () => { + const cli = setup() + cli.callOperation.mockResolvedValue({ + data: [{ id: 'f1', name: 'sunset.png', type: 'file', size: 10, projectId: 'p' }], + pageInfo: { hasNextPage: false, endCursor: null }, + total: 1, + }) + + await cli.run('search', 'sunset', '-p', 'root-1') + + expect(cli.callOperation).toHaveBeenCalledWith(searchAssets, { + parent: 'root-1', + query: 'sunset', + first: 200, + }) + expect(cli.stdout()).toContain('sunset.png') + }) + + it('searches by meaning with --semantic', async () => { + const cli = setup() + cli.callOperation.mockResolvedValue({ + data: [], + pageInfo: { hasNextPage: false, endCursor: null }, + total: 0, + }) + + await cli.run('search', 'a calm beach', '-p', 'root-1', '--semantic') + + expect(cli.callOperation).toHaveBeenCalledWith( + searchAssets, + expect.objectContaining({ query: 'a calm beach', semantic: true }), + ) + }) + }) + + describe('copy', () => { + it.each(['copy', 'cp'])('copies assets with %s', async (command) => { + const cli = setup() + cli.callOperation.mockResolvedValue({ copiedAssetIds: ['c-1', 'c-2'], newParentId: 'f-2' }) + + await cli.run(command, 'a-1', 'a-2', '-p', 'f-2', '--with-comments') + + expect(cli.callOperation).toHaveBeenCalledWith(copyAssets, { + assetIds: ['a-1', 'a-2'], + newParentId: 'f-2', + withComments: true, + }) + expect(cli.stdout()).toBe('Copied 2 asset(s) to parent f-2: c-1, c-2\n') + }) + }) + + describe('comment', () => { + const thread = { + id: 'c-1', + message: 'Too dark here', + author: { id: 'u-1', name: 'Ana' }, + second: 12.5, + hasMarkup: false, + attachmentCount: 0, + createdAt: '2026-01-01T00:00:00.000Z', + resolved: true, + replies: [ + { + id: 'c-2', + message: 'Fixed in v2', + author: { id: 'u-2', name: 'Bo' }, + second: null, + hasMarkup: false, + attachmentCount: 0, + createdAt: '2026-01-02T00:00:00.000Z', + }, + ], + } + + it('lists threads with their replies', async () => { + const cli = setup() + cli.callOperation.mockResolvedValue({ + data: [thread], + pageInfo: { hasNextPage: false, endCursor: null }, + total: 1, + }) + + await cli.run('comment', 'ls', 'vid-1') + + expect(cli.callOperation).toHaveBeenCalledWith(listComments, { + assetId: 'vid-1', + first: 200, + }) + expect(cli.stdout()).toBe( + 'c-1 @12.5s [resolved] Ana: Too dark here\n ↳ c-2 Bo: Fixed in v2\n', + ) + }) + + it('posts a reply at a timecode', async () => { + const cli = setup() + cli.callOperation.mockResolvedValue({ id: 'c-3', assetId: 'vid-1', replyToId: 'c-1' }) + + await cli.run('comment', 'add', 'vid-1', 'Looks good now', '--reply-to', 'c-1', '--at', '3') + + expect(cli.callOperation).toHaveBeenCalledWith(createComment, { + assetId: 'vid-1', + message: 'Looks good now', + replyToId: 'c-1', + second: 3, + }) + expect(cli.stdout()).toBe('Posted comment c-3\n') + }) + + it('resolves and reopens comments', async () => { + const cli = setup() + cli.callOperation.mockResolvedValueOnce({ commentId: 'c-1', resolved: true }) + cli.callOperation.mockResolvedValueOnce({ commentId: 'c-1', resolved: false }) + + await cli.run('comment', 'resolve', 'c-1') + await cli.run('comment', 'resolve', 'c-1', '--reopen') + + expect(cli.callOperation).toHaveBeenNthCalledWith(1, resolveComment, { commentId: 'c-1' }) + expect(cli.callOperation).toHaveBeenNthCalledWith(2, resolveComment, { + commentId: 'c-1', + reopen: true, + }) + expect(cli.stdout()).toBe('Comment c-1 is resolved\nComment c-1 is unresolved\n') + }) + }) + + describe('meta set', () => { + it('passes --values as a JSON object', async () => { + const cli = setup() + cli.callOperation.mockResolvedValue({ assetId: 'a-1', updatedKeys: ['status', 'rating'] }) + + await cli.run('meta', 'set', 'a-1', '--values', '{"status":"approved","rating":4}') + + expect(cli.callOperation).toHaveBeenCalledWith(updateAssetMetadata, { + assetId: 'a-1', + values: { status: 'approved', rating: 4 }, + }) + expect(cli.stdout()).toBe('Updated status, rating on a-1\n') + }) + + it.each([ + ['{not json', 'Not valid JSON.'], + ['["status"]', 'Expected a JSON object'], + ])('rejects --values %s', async (value, message) => { + const cli = setup() + + await expect(cli.run('meta', 'set', 'a-1', '--values', value)).rejects.toThrow() + expect(cli.stderr()).toContain(message) + expect(cli.callOperation).not.toHaveBeenCalled() + }) + }) + + describe('field ls', () => { + it("lists a project's fields with their choices", async () => { + const cli = setup() + cli.callOperation.mockResolvedValue({ + fields: [ + { + key: 'status', + name: 'Status', + type: 'select', + description: '', + readOnly: false, + creationContext: false, + options: [{ id: 'approved', name: 'Approved' }], + }, + { + key: 'prompt', + name: 'Prompt', + type: 'text', + description: '', + readOnly: false, + creationContext: true, + }, + ], + }) + + await cli.run('field', 'ls', 'p-1') + + expect(cli.callOperation).toHaveBeenCalledWith(listMetadataFields, { projectId: 'p-1' }) + expect(cli.stdout()).toBe( + 'status Status (select) [approved=Approved]\nprompt Prompt (text, creation)\n', + ) + }) + }) + + describe('version', () => { + it('stacks files, lists versions, and unstacks one', async () => { + const cli = setup() + cli.callOperation.mockResolvedValueOnce({ + id: 's-1', + name: 'cut_v2.mp4', + type: 'version_stack', + size: 20, + projectId: 'p-1', + }) + cli.callOperation.mockResolvedValueOnce({ + versions: [ + { + id: 'v-2', + version: 2, + name: 'cut_v2.mp4', + current: true, + createdAt: '2026-01-02T00:00:00.000Z', + creator: null, + agent: null, + }, + { + id: 'v-1', + version: 1, + name: 'cut_v1.mp4', + current: false, + createdAt: '2026-01-01T00:00:00.000Z', + creator: null, + agent: null, + }, + ], + }) + cli.callOperation.mockResolvedValueOnce({ versionId: 'v-1', stackId: 's-1' }) + + await cli.run('version', 'stack', 'v-2', 'v-1') + await cli.run('version', 'ls', 's-1') + await cli.run('version', 'unstack', 'v-1') + + expect(cli.callOperation).toHaveBeenNthCalledWith(1, createVersionStack, { + fileIds: ['v-2', 'v-1'], + }) + expect(cli.callOperation).toHaveBeenNthCalledWith(2, listVersions, { stackId: 's-1' }) + expect(cli.callOperation).toHaveBeenNthCalledWith(3, removeVersion, { versionId: 'v-1' }) + expect(cli.stdout()).toBe( + 'Created version stack s-1\n' + + 'v2 (current) v-2 cut_v2.mp4\nv1 v-1 cut_v1.mp4\n' + + 'Removed v-1 from version stack s-1\n', + ) + }) + }) + + describe('instructions', () => { + it("prints a folder's instructions, or says it has none", async () => { + const cli = setup() + cli.callOperation.mockResolvedValueOnce({ folderId: 'f-1', content: '# Rules' }) + cli.callOperation.mockResolvedValueOnce({ folderId: 'f-2', content: null }) + + await cli.run('instructions', 'f-1') + await cli.run('instructions', 'f-2') + + expect(cli.callOperation).toHaveBeenCalledWith(getFolderInstructions, { folderId: 'f-1' }) + expect(cli.stdout()).toBe('# Rules\n(This folder has no instructions.)\n') + }) + }) + + it('has no upload Operation commands: upload and create-version stream local files', () => { + const program = createProgram({ callOperation: vi.fn() }) + const names = program.commands.map((c) => c.name()) + expect(names).not.toContain('complete-upload') + expect(names.filter((n) => n === 'create-version')).toHaveLength(1) + }) }) describe('formatCliError', () => { diff --git a/apps/web/src/index.ts b/apps/web/src/index.ts index 80aef47e..6819a52b 100644 --- a/apps/web/src/index.ts +++ b/apps/web/src/index.ts @@ -134,6 +134,8 @@ async function run() { const routes: Record = { '/api/*': app.fetch, '/files/*': app.fetch, + // Shumai's MCP server; without this entry the SPA catch-all (`/*`) would serve it HTML. + '/mcp': app.fetch, } if (isProd) { diff --git a/docs/developer/mcp-server.mdx b/docs/developer/mcp-server.mdx index 78a1e678..19082417 100644 --- a/docs/developer/mcp-server.mdx +++ b/docs/developer/mcp-server.mdx @@ -17,7 +17,7 @@ Shumai includes a built-in [Model Context Protocol](https://modelcontextprotocol The server uses the Streamable HTTP transport at: ``` -https:///api/mcp +https:///mcp ``` It authenticates with an **API token**: @@ -31,7 +31,7 @@ Then add the server to your client, sending the token as a Bearer header. **Claude Code** ```bash -claude mcp add --transport http shumai https:///api/mcp \ +claude mcp add --transport http shumai https:///mcp \ --header "Authorization: Bearer " ``` @@ -41,7 +41,7 @@ claude mcp add --transport http shumai https:///api/mcp \ { "mcpServers": { "shumai": { - "url": "https:///api/mcp", + "url": "https:///mcp", "headers": { "Authorization": "Bearer " } } } @@ -58,17 +58,31 @@ claude mcp add --transport http shumai https:///api/mcp \ ## Available Tools -| Tool | What it does | -| ------------------ | ---------------------------------------------------------------------------------------------------------------- | -| `list_projects` | Lists the projects you can access, with each project's root folder. | -| `list_assets` | Lists files and folders in a folder, page by page. | -| `create_folder` | Creates a folder. | -| `rename_asset` | Renames a file or folder. | -| `move_assets` | Moves files or folders into another folder. | -| `delete_asset` | Moves a file or folder to the project trash. Marked as destructive so clients can ask you to confirm. | -| `read_asset` | Looks at a file: an image, video frames, PDF pages, a 3D model view, or the text of a text file. | -| `get_asset_render` | Gets the result of a `read_asset` call that was still rendering. | -| `download_asset` | Gets download links for up to 50 files: the web preview version by default, or the original with `proxy: false`. | +| Tool | What it does | +| ------------------------- | ---------------------------------------------------------------------------------------------------------------- | +| `list_projects` | Lists the projects you can access, with each project's root folder. | +| `list_assets` | Lists files and folders in a folder, page by page. | +| `search_assets` | Searches a folder and its subfolders by name, by meaning (when AI search is enabled), or by metadata. | +| `create_folder` | Creates a folder. | +| `rename_asset` | Renames a file or folder. | +| `move_assets` | Moves files or folders into another folder. | +| `copy_assets` | Copies files or folders into another folder of the same team. | +| `delete_asset` | Moves a file or folder to the project trash. Marked as destructive so clients can ask you to confirm. | +| `read_asset` | Looks at a file: an image, video frames, PDF pages, a 3D model view, or the text of a text file. | +| `get_asset_render` | Gets the result of a `read_asset` call that was still rendering. | +| `download_asset` | Gets download links for up to 50 files: the web preview version by default, or the original with `proxy: false`. | +| `get_folder_instructions` | Reads a folder's instructions for AI agents (its AGENTS.md). | +| `create_file` | Starts uploading a new file into a folder (see [Uploading Files](#uploading-files)). | +| `create_version` | Starts uploading a new version of a file. | +| `complete_upload` | Finishes an upload started with `create_file` or `create_version`. | +| `list_comments` | Lists the review comments on a file, with their replies. | +| `create_comment` | Comments on a file (optionally at a timecode) or replies to a comment. | +| `resolve_comment` | Marks a comment as resolved, or unresolved again. | +| `list_metadata_fields` | Lists a project's metadata fields, such as status, rating, and custom fields, with their choices. | +| `update_asset_metadata` | Sets metadata values on a file. | +| `create_version_stack` | Stacks files in the same folder as versions of one asset. | +| `list_versions` | Lists the versions in a version stack, latest first. | +| `remove_version` | Takes a version out of its stack. The file is kept. | ### Reading Files @@ -76,6 +90,18 @@ claude mcp add --transport http shumai https:///api/mcp \ Rendering video frames or PDF pages can take a while. If it takes longer than about 20 seconds, `read_asset` returns `status: "pending"` with a `taskId`, and the model calls `get_asset_render` with that `taskId` to get the result. Only the user who started the read can get its result. +### Uploading Files + +Uploading takes three steps, so large files never pass through the AI model: + +1. `create_file` (or `create_version`) returns an `uploadUrl` and an `uploadId`. +2. The agent uploads the file's bytes to `uploadUrl` with an HTTP `PUT`, for example `curl -T video.mp4 ""`. +3. `complete_upload` with the `uploadId` creates the file and starts processing it (previews, transcoding). + +The upload URL and ID are valid for about an hour, and only you can complete your upload. If the project has **Creation Context** metadata fields (for example, the prompt or model used to make a file), pass their values as `metadata` to `create_file` or `create_version`; `list_metadata_fields` shows which fields they are. + +The agent must be able to reach the upload URL. With Shumai's local storage, it points to your Shumai server; with S3 storage, to your S3 endpoint. + Every call runs with your permissions: for example, a **Reviewer** can list assets but cannot create or rename them. Actions are recorded in the team audit log and attributed to you, marked as coming from MCP. --- diff --git a/docs/using-shumai/agent-tools.mdx b/docs/using-shumai/agent-tools.mdx index b3656688..5c94c803 100644 --- a/docs/using-shumai/agent-tools.mdx +++ b/docs/using-shumai/agent-tools.mdx @@ -98,6 +98,61 @@ The following tools can be individually toggled in the agent configuration dialo - **Description:** Allows the agent to delete a single file or folder by moving it to the Trash bin. - **Why it matters:** Provides agents with the ability to clean up outdated or redundant assets. To prevent accidental data loss, this tool is **disabled by default** and strictly limited to deleting one asset at a time. Team Owners must explicitly enable this tool for an agent. +### 16. Search Assets (`search_assets`) + +- **Description:** Allows the agent to search a folder and its subfolders by name, by meaning (when AI search is enabled for the team), or by metadata such as status. +- **Why it matters:** Lets the agent find the files a request is about without browsing folder by folder. + +### 17. Copy Assets (`copy_assets`) + +- **Description:** Allows the agent to copy files or folders, with everything inside them, into another folder of the same team. +- **Why it matters:** Lets the agent reuse assets across projects or set up working copies while keeping the originals unchanged. + +### 18. Read Folder Instructions (`get_folder_instructions`) + +- **Description:** Allows the agent to read a folder's instructions for AI agents (its AGENTS.md). +- **Why it matters:** Lets the agent follow the team's conventions, such as naming rules or deliverable specs, before adding files to a folder. + +### 19. Read Comments (`list_comments`) + +- **Description:** Allows the agent to read the review comments and replies on a file, including their timecodes. +- **Why it matters:** Lets the agent act on review feedback, for example to summarize open notes or address them in a new version. + +### 20. Post Comment (`create_comment`) + +- **Description:** Allows the agent to comment on a file, optionally at a timecode, or reply to a comment. Comments are posted as the user the agent works for; the audit log records that the agent wrote them. +- **Why it matters:** Lets the agent take part in reviews like a teammate. Mentions in the agent's comments don't start other agents. + +### 21. Resolve Comment (`resolve_comment`) + +- **Description:** Allows the agent to mark comments as resolved, or reopen them. +- **Why it matters:** Lets the agent close the feedback it has addressed. + +### 22. List Metadata Fields (`list_metadata_fields`) + +- **Description:** Allows the agent to see a project's metadata fields, such as status, rating, and custom fields, with their choices. +- **Why it matters:** Tells the agent which values it can search by or set. + +### 23. Update Metadata (`update_asset_metadata`) + +- **Description:** Allows the agent to set metadata values on a file, such as its status or tags. Read-only fields can't be changed. +- **Why it matters:** Lets the agent keep a file's review status and other fields up to date. + +### 24. Create Version Stack (`create_version_stack`) + +- **Description:** Allows the agent to stack existing files in the same folder as versions of one asset. +- **Why it matters:** Lets the agent tidy up loose revisions (for example `cut_v1.mp4` and `cut_v2.mp4`) into one versioned asset. + +### 25. List Versions (`list_versions`) + +- **Description:** Allows the agent to list the versions in a version stack, latest first. +- **Why it matters:** Lets the agent compare a file with earlier versions. + +### 26. Remove Version (`remove_version`) + +- **Description:** Allows the agent to take a version out of its stack. The file isn't deleted; it goes back into the folder as a separate file. +- **Why it matters:** Lets the agent fix a version that was stacked by mistake. + --- ## Restricting Tools diff --git a/packages/agent/src/database-session-storage.test.ts b/packages/agent/src/database-session-storage.test.ts index e2e91b68..8d1d6450 100644 --- a/packages/agent/src/database-session-storage.test.ts +++ b/packages/agent/src/database-session-storage.test.ts @@ -471,6 +471,7 @@ describe('DatabaseSessionStorage', () => { // 4. Assert that the tools were built for the user expect(buildOperationToolsSpy).toHaveBeenCalledWith( expect.objectContaining({ userId: user.id }), + expect.objectContaining({}), ) }) @@ -525,6 +526,7 @@ describe('DatabaseSessionStorage', () => { // 4. Assert that the tools were built for the user expect(buildOperationToolsSpy).toHaveBeenCalledWith( expect.objectContaining({ userId: user.id }), + expect.objectContaining({}), ) }) diff --git a/packages/agent/src/index.ts b/packages/agent/src/index.ts index bb3003b0..8dedd020 100644 --- a/packages/agent/src/index.ts +++ b/packages/agent/src/index.ts @@ -18,8 +18,6 @@ import * as fs from 'fs' import * as path from 'path' import { DatabaseSessionStorage } from './database-session-storage' import { metadataService } from '@shumai/core/src/metadata/metadata' -import { createCreateFileTool } from './tools/create-file' -import { createCreateVersionTool } from './tools/create-version' import { createReadSkillTool } from './tools/read-skill' import { createReadThreadTool } from './tools/read-thread' import { createSandboxedBashTool } from './tools/sandboxed-bash' @@ -332,14 +330,11 @@ export async function createAgentSession(params: CreateAgentSessionParams) { const systemTools: AgentTool[] = [] if (userId) { - const metadataSchema = await buildProjectMetadataSchema(projectId) - const agentContext = { teamId, agentId } + const creationMetadataSchema = await buildProjectMetadataSchema(projectId) systemTools.push( - // Shared Operations (also exposed via MCP and the CLI): list/create/rename/move/delete, - // read_asset, get_asset_render, and download_asset - ...buildOperationTools({ userId, agentId, teamId, projectId }), - createCreateFileTool(userId, metadataSchema, agentContext), - createCreateVersionTool(userId, metadataSchema, agentContext), + // Shared Operations (also exposed via MCP and the CLI): browsing, searching, organizing, + // reading and downloading assets, creating files and versions, comments and metadata + ...buildOperationTools({ userId, agentId, teamId, projectId }, { creationMetadataSchema }), ) } diff --git a/packages/agent/src/operation-extensions/index.ts b/packages/agent/src/operation-extensions/index.ts index d0aa97a1..6ed49f80 100644 --- a/packages/agent/src/operation-extensions/index.ts +++ b/packages/agent/src/operation-extensions/index.ts @@ -1,3 +1,4 @@ // Registers agent-specific presentation for Operations. Import once before building tools. export { createAutofillReadAssetTool, presentReadOutput } from './read-asset' export { presentDownloadOutput } from './download-asset' +import './upload' diff --git a/packages/agent/src/operation-extensions/upload.test.ts b/packages/agent/src/operation-extensions/upload.test.ts new file mode 100644 index 00000000..50404f24 --- /dev/null +++ b/packages/agent/src/operation-extensions/upload.test.ts @@ -0,0 +1,447 @@ +import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest' +import { Value } from 'typebox/value' +import { validateToolArguments } from '@earendil-works/pi-ai' +import * as fs from 'fs' +import * as os from 'os' +import * as path from 'path' +import { AuditAction, type AssetInfo } from '@shumai/dtos' +import { assetService } from '@shumai/core/src/asset/asset' +import { auditLogService } from '@shumai/core/src/auditLog/auditLog' +import { authzService, Permission, ResourceType } from '@shumai/core/src/authz/authz' +import { metadataService } from '@shumai/core/src/metadata/metadata' +import { getOperation } from '@shumai/core/src/operations' +import { s3Service } from '@shumai/core/src/s3/s3' +import { fieldsToTypeBoxSchema } from '../index' +import { toAgentTool, type AgentToolOptions } from '../operation-tools' +import './upload' + +const ctx = { userId: 'user-1', agentId: 'agent-1', teamId: 'team-1', projectId: 'proj-1' } +const bucket = process.env.S3_BUCKET || 'shumai' + +function tool(name: 'create_file' | 'create_version', options: AgentToolOptions = {}) { + return toAgentTool(getOperation(name)!, ctx, options) +} + +function assetInfo(overrides: Partial): AssetInfo { + return { + id: 'file-1', + name: 'test', + sizeByte: 100, + fileCount: 0, + type: 'file', + status: 'uploaded', + createdAt: '2026-01-01T00:00:00.000Z', + updatedAt: '2026-01-01T00:00:00.000Z', + projectId: 'proj-1', + ...overrides, + } +} + +function outputOf(result: { content: unknown[] }) { + return JSON.parse((result.content[0] as { text: string }).text) as unknown +} + +const promptField = { + field: { + id: 'f1', + key: 'prompt', + scope: 'PROJECT', + readOnly: false, + description: '', + config: { name: 'Prompt', type: 'text', autofillSource: 'CREATION_CONTEXT' }, + }, + visible: true, +} + +describe('create_file and create_version agent tools', () => { + const tempFiles: string[] = [] + const tempFile = (content: string, filename: string): string => { + const filePath = path.join(os.tmpdir(), filename) + fs.writeFileSync(filePath, content) + tempFiles.push(filePath) + return filePath + } + + beforeEach(() => { + vi.spyOn(authzService, 'hasPermission').mockResolvedValue(undefined) + vi.spyOn(auditLogService, 'logAction').mockResolvedValue(null) + vi.spyOn(assetService, 'getAssetContext').mockResolvedValue({ + teamId: 'team-1', + projectId: 'proj-1', + }) + vi.spyOn(assetService, 'getAssetMeta').mockImplementation(async (id) => ({ + id, + name: id, + type: id.startsWith('folder') ? 'folder' : 'file', + parentId: 'root', + teamId: 'team-1', + projectId: 'proj-1', + })) + vi.spyOn(assetService, 'findAssetByStorageKey').mockResolvedValue(null) + vi.spyOn(assetService, 'createFile').mockResolvedValue(assetInfo({})) + vi.spyOn(assetService, 'createVersion').mockResolvedValue(assetInfo({ name: 'v2' })) + vi.spyOn(metadataService, 'listProjectFields').mockResolvedValue([promptField] as never) + vi.spyOn(s3Service, 'presign').mockResolvedValue('https://storage.example/upload') + // Read file streams to the end, as real storage would. + vi.spyOn(s3Service, 'putObject').mockImplementation(async (_bucket, _key, body) => { + if (body && typeof body === 'object' && Symbol.asyncIterator in body) { + for await (const chunk of body as AsyncIterable) void chunk + } + }) + vi.spyOn(s3Service, 'headObject').mockImplementation(async (_bucket, key) => ({ + key, + size: 17, + lastModified: new Date(), + contentType: 'text/markdown', + eTag: '', + })) + }) + + afterEach(() => { + vi.restoreAllMocks() + for (const f of tempFiles.splice(0)) fs.rmSync(f, { force: true }) + }) + + describe('create_file', () => { + it('uploads a local file to storage and creates the file as the agent', async () => { + const filePath = tempFile('# Hello from disk', 'agent-create-file.md') + + const result = await tool('create_file').execute('call-1', { + parent: 'folder-1', + path: filePath, + } as never) + + expect(authzService.hasPermission).toHaveBeenCalledWith({ + user: { id: 'user-1' }, + permission: Permission.Edit, + type: ResourceType.Asset, + id: 'folder-1', + }) + const [putBucket, key, , size, contentType] = vi.mocked(s3Service.putObject).mock.calls[0] + expect(putBucket).toBe(bucket) + expect(key).toMatch(/^files\/.+\/agent-create-file\.md$/) + expect(size).toBe(Buffer.byteLength('# Hello from disk')) + expect(contentType).toBe('text/markdown') + + expect(assetService.createFile).toHaveBeenCalledWith({ + parentId: 'folder-1', + name: 'agent-create-file.md', + key, + sizeByte: 17, + contentType: 'text/markdown', + creatorId: 'user-1', + agentId: 'agent-1', + metadata: undefined, + }) + expect(auditLogService.logAction).toHaveBeenCalledWith( + expect.objectContaining({ + action: AuditAction.file_create, + teamId: 'team-1', + projectId: 'proj-1', + userId: 'user-1', + agentId: 'agent-1', + itemId: 'file-1', + via: 'agent', + }), + ) + expect(result.details).toEqual({}) + expect(outputOf(result)).toEqual({ + id: 'file-1', + name: 'test', + type: 'file', + size: 100, + projectId: 'proj-1', + }) + }) + + it('creates a text file from name and content', async () => { + await tool('create_file').execute('call-1', { + parent: 'folder-1', + name: 'notes.md', + content: '# Notes\n\nHello', + } as never) + + const [, key, body, size, contentType] = vi.mocked(s3Service.putObject).mock.calls[0] + expect(key).toMatch(/^files\/.+\/notes\.md$/) + expect((body as Buffer).toString('utf-8')).toBe('# Notes\n\nHello') + expect(size).toBe(Buffer.byteLength('# Notes\n\nHello')) + expect(contentType).toBe('text/markdown') + expect(assetService.createFile).toHaveBeenCalledWith( + expect.objectContaining({ name: 'notes.md', contentType: 'text/markdown' }), + ) + }) + + it('defaults unknown extensions to text/plain when creating from content', async () => { + await tool('create_file').execute('call-1', { + parent: 'folder-1', + name: 'script.ts', + content: 'const x = 1', + } as never) + + expect(vi.mocked(s3Service.putObject).mock.calls[0][4]).toBe('text/plain') + expect(assetService.createFile).toHaveBeenCalledWith( + expect.objectContaining({ contentType: 'text/plain' }), + ) + }) + + it('sanitizes the name', async () => { + await tool('create_file').execute('call-1', { + parent: 'folder-1', + name: 'my/notes.md', + content: 'hello', + } as never) + + expect(vi.mocked(s3Service.putObject).mock.calls[0][1]).toContain('my_notes.md') + expect(assetService.createFile).toHaveBeenCalledWith( + expect.objectContaining({ name: 'my_notes.md' }), + ) + }) + + it('forwards Creation Context metadata, including new select options', async () => { + const filePath = tempFile('# Hello', 'agent-create-file-meta.md') + + await tool('create_file').execute('call-1', { + parent: 'folder-1', + path: filePath, + metadata: { prompt: { newOption: { value: 'Kling' } } }, + } as never) + + expect(assetService.createFile).toHaveBeenCalledWith( + expect.objectContaining({ metadata: { prompt: { newOption: { value: 'Kling' } } } }), + ) + }) + + it('treats null metadata as omitted', async () => { + const filePath = tempFile('# Hello', 'agent-create-file-null.md') + + await tool('create_file').execute('call-1', { + parent: 'folder-1', + path: filePath, + metadata: null, + } as never) + + expect(vi.mocked(assetService.createFile).mock.calls[0][0].metadata).toBeUndefined() + }) + + it('rejects metadata keys that are not Creation Context fields before uploading', async () => { + const filePath = tempFile('# Hello', 'agent-create-file-bad-meta.md') + + await expect( + tool('create_file').execute('call-1', { + parent: 'folder-1', + path: filePath, + metadata: { status: 'approved' }, + } as never), + ).rejects.toThrow(/not allowed: status/) + + expect(s3Service.putObject).not.toHaveBeenCalled() + expect(assetService.createFile).not.toHaveBeenCalled() + }) + + it('rejects a call with neither or both of "path" and "content"', async () => { + await expect( + tool('create_file').execute('call-1', { parent: 'folder-1' } as never), + ).rejects.toThrow('Provide exactly one of "path" (a local file) or "content" (with "name").') + await expect( + tool('create_file').execute('call-1', { + parent: 'folder-1', + path: '/some/file.md', + name: 'notes.md', + content: 'hello', + } as never), + ).rejects.toThrow('Provide exactly one of') + expect(s3Service.putObject).not.toHaveBeenCalled() + }) + + it('requires a name with "content"', async () => { + await expect( + tool('create_file').execute('call-1', { parent: 'folder-1', content: 'x' } as never), + ).rejects.toThrow('"name" is required') + }) + + it('fails when the local file does not exist, without touching storage', async () => { + await expect( + tool('create_file').execute('call-1', { + parent: 'folder-1', + path: '/nonexistent/file.md', + } as never), + ).rejects.toThrow('Local file not found at path: /nonexistent/file.md') + expect(s3Service.putObject).not.toHaveBeenCalled() + expect(assetService.createFile).not.toHaveBeenCalled() + }) + + it('does not write to storage when the user lacks Edit permission', async () => { + vi.mocked(authzService.hasPermission).mockRejectedValue( + new Error('User is not a member of the team'), + ) + const filePath = tempFile('# Not allowed', 'agent-create-file-denied.md') + + await expect( + tool('create_file').execute('call-1', { parent: 'folder-1', path: filePath } as never), + ).rejects.toThrow('User is not a member of the team') + await expect( + tool('create_file').execute('call-1', { + parent: 'folder-1', + name: 'notes.md', + content: 'x', + } as never), + ).rejects.toThrow('User is not a member of the team') + + expect(s3Service.putObject).not.toHaveBeenCalled() + expect(s3Service.presign).not.toHaveBeenCalled() + expect(assetService.createFile).not.toHaveBeenCalled() + }) + + it('passes harness validation with only one source set', async () => { + const t = tool('create_file') + const validated = validateToolArguments( + { name: t.name, description: '', parameters: t.parameters } as Parameters< + typeof validateToolArguments + >[0], + { + type: 'toolCall', + id: 'call-1', + name: t.name, + arguments: { parent: 'folder-1', name: 'random.txt', content: 'hello' }, + } as Parameters[1], + ) + + await t.execute('call-1', validated as never) + expect(assetService.createFile).toHaveBeenCalledWith( + expect.objectContaining({ name: 'random.txt' }), + ) + }) + + it('shows the agent its own parameters', () => { + const properties = Object.keys( + (tool('create_file').parameters as unknown as { properties: object }).properties, + ) + expect(properties.sort()).toEqual(['content', 'name', 'parent', 'path']) + }) + }) + + describe('create_version', () => { + it('uploads a local file and creates a version as the agent', async () => { + const filePath = tempFile('# Hello from disk', 'agent-create-version.md') + + const result = await tool('create_version').execute('call-1', { + parent: 'file-1', + path: filePath, + } as never) + + const key = vi.mocked(s3Service.putObject).mock.calls[0][1] + expect(assetService.createVersion).toHaveBeenCalledWith({ + parentId: 'file-1', + name: 'agent-create-version.md', + key, + sizeByte: 17, + contentType: 'text/markdown', + creatorId: 'user-1', + agentId: 'agent-1', + metadata: undefined, + }) + expect(outputOf(result)).toMatchObject({ id: 'file-1', name: 'v2' }) + expect(auditLogService.logAction).toHaveBeenCalledWith( + expect.objectContaining({ action: AuditAction.file_create, agentId: 'agent-1' }), + ) + }) + + it('forwards Creation Context metadata', async () => { + const filePath = tempFile('# Hello', 'agent-create-version-meta.md') + + await tool('create_version').execute('call-1', { + parent: 'file-1', + path: filePath, + metadata: { prompt: 'Generated using gemini' }, + } as never) + + expect(assetService.createVersion).toHaveBeenCalledWith( + expect.objectContaining({ metadata: { prompt: 'Generated using gemini' } }), + ) + }) + + it('does not upload when the user lacks Edit permission', async () => { + vi.mocked(authzService.hasPermission).mockRejectedValueOnce( + new Error('User is not a member of the team'), + ) + const filePath = tempFile('# Not allowed', 'agent-create-version-denied.md') + + await expect( + tool('create_version').execute('call-1', { parent: 'file-1', path: filePath } as never), + ).rejects.toThrow('User is not a member of the team') + expect(s3Service.putObject).not.toHaveBeenCalled() + expect(assetService.createVersion).not.toHaveBeenCalled() + }) + + it('fails when the local file does not exist', async () => { + await expect( + tool('create_version').execute('call-1', { + parent: 'file-1', + path: '/nonexistent/file.md', + } as never), + ).rejects.toThrow('Local file not found at path: /nonexistent/file.md') + expect(s3Service.putObject).not.toHaveBeenCalled() + }) + + it('shows the agent its own parameters', () => { + const properties = Object.keys( + (tool('create_version').parameters as unknown as { properties: object }).properties, + ) + expect(properties.sort()).toEqual(['parent', 'path']) + }) + }) + + describe('Creation Context metadata parameter', () => { + const creationMetadataSchema = fieldsToTypeBoxSchema([ + { id: 'prompt', config: { name: 'Prompt', type: 'text' } }, + { + id: 'source', + config: { + name: 'Source', + type: 'select', + select: { options: [{ id: 'gemini', displayName: 'Gemini', color: '#ffffff' }] }, + }, + }, + ]) + + it.each(['create_file', 'create_version'] as const)( + '%s exposes the project schema as a strict, nullable metadata parameter', + (name) => { + const parameters = tool(name, { creationMetadataSchema }).parameters as unknown as { + properties: { metadata: { anyOf: [{ required: string[] }, { type: string }] } } + } + const meta = parameters.properties.metadata + expect(meta.anyOf[0].required).toEqual(['prompt', 'source']) + expect(meta.anyOf[1].type).toBe('null') + + expect(Value.Check(meta, { prompt: 'hello', source: 'gemini' })).toBe(true) + expect(Value.Check(meta, { prompt: null, source: null })).toBe(true) + expect(Value.Check(meta, null)).toBe(true) + expect(Value.Check(meta, { prompt: 'hello' })).toBe(false) + expect(Value.Check(meta, { prompt: 'x', source: 'gemini', other: 1 })).toBe(false) + expect(Value.Check(meta, { prompt: 'x', source: 'not-an-option' })).toBe(false) + }, + ) + + it('keeps null values inside metadata through harness validation', () => { + const t = tool('create_file', { + creationMetadataSchema: fieldsToTypeBoxSchema([ + { id: 'prompt', config: { name: 'Prompt', type: 'text' } }, + ]), + }) + const validated = validateToolArguments( + { name: t.name, description: '', parameters: t.parameters } as Parameters< + typeof validateToolArguments + >[0], + { + type: 'toolCall', + id: 'call-1', + name: t.name, + arguments: { parent: 'folder-1', name: 'a.md', content: 'x', metadata: { prompt: null } }, + } as Parameters[1], + ) as { metadata?: unknown } + + expect(validated.metadata).toEqual({ prompt: null }) + }) + }) +}) diff --git a/packages/agent/src/operation-extensions/upload.ts b/packages/agent/src/operation-extensions/upload.ts new file mode 100644 index 00000000..6adf6b97 --- /dev/null +++ b/packages/agent/src/operation-extensions/upload.ts @@ -0,0 +1,158 @@ +import * as fs from 'fs' +import * as path from 'path' +import { z } from 'zod' +import { Type } from 'typebox' +import type { AgentToolResult } from '@earendil-works/pi-agent-core' +import { createFile, type StartedUploadOutput } from '@shumai/operations' +import { storageBucket } from '@shumai/core/src/asset-read' +import { completeUploadOp, runOperation } from '@shumai/core/src/operations' +import { s3Service } from '@shumai/core/src/s3/s3' +import { getFileMimeType, readFileMimeType } from '@shumai/core/src/utils/file-mime' +import { + registerAgentToolExtension, + type AgentOperationContext, + type AgentToolExtension, + type AgentToolOptions, + type ToolParametersSchema, +} from '../operation-tools' + +const METADATA_HINT = + 'The optional "metadata" parameter accepts only the CREATION_CONTEXT fields declared in its schema; never invent field keys, and use null for fields you do not know.' + +/** + * The agent gets the conversation project's Creation Context fields as a strict schema + * (so it knows exactly what to fill in) instead of the open record MCP clients see. Without + * such fields the parameter is left out. + */ +function setCreationMetadata(schema: ToolParametersSchema, options: AgentToolOptions): void { + if (options.creationMetadataSchema) { + schema.properties.metadata = Type.Union([options.creationMetadataSchema, Type.Null()]) + } else { + delete schema.properties.metadata + } +} + +function resolveLocalFile(localPath: string): string { + const absolutePath = path.resolve(process.cwd(), localPath) + if (!fs.existsSync(absolutePath) || !fs.statSync(absolutePath).isFile()) { + throw new Error(`Local file not found at path: ${localPath}`) + } + return absolutePath +} + +/** + * Writes the file straight to the upload's storage key (the agent runs next to storage, so + * it doesn't need the upload URL), then completes the upload as the agent. + */ +async function uploadAndComplete( + raw: unknown, + extra: Record, + ctx: AgentOperationContext, +): Promise> { + const started = raw as StartedUploadOutput + if (!started.key) throw new Error('The upload did not return a storage key') + + if (typeof extra.path === 'string') { + const absolutePath = resolveLocalFile(extra.path) + await s3Service.putObject( + storageBucket(), + started.key, + fs.createReadStream(absolutePath), + fs.statSync(absolutePath).size, + readFileMimeType(absolutePath), + ) + } else { + const content = Buffer.from(typeof extra.content === 'string' ? extra.content : '', 'utf-8') + // The key ends with the file name, which gives the same type as the upload's. + const contentType = getFileMimeType(null, started.key, 'text/plain') + await s3Service.putObject( + storageBucket(), + started.key, + content, + content.byteLength, + contentType, + ) + } + + const asset = await runOperation( + completeUploadOp, + { ...ctx, via: 'agent' }, + { uploadId: started.uploadId }, + ) + return { content: [{ type: 'text', text: JSON.stringify(asset, null, 2) }], details: {} } +} + +const createFileExtension: AgentToolExtension = { + description: + 'Create a new file in a folder. Choose exactly ONE source: ' + + '(1) "path" to upload a local file (e.g. one you made in .pi), OR ' + + '(2) "name" and "content" to create a text file with that content. ' + + METADATA_HINT, + parameterOverrides: z.object({ + name: createFile.input.shape.name + .optional() + .describe( + 'File name including its extension (e.g. "notes.md"). Required with "content"; defaults to the local file\'s name with "path".', + ), + }), + extraParameters: z.object({ + path: z + .string() + .min(1) + .optional() + .describe('Absolute or relative path of a local file to upload. Omit when using "content".'), + content: z + .string() + .optional() + .describe('Full text content of a new text file. Requires "name"; omit when using "path".'), + }), + hiddenParameters: ['contentType'], + adjustParameters: setCreationMetadata, + toInput(input, extra) { + const hasPath = typeof extra.path === 'string' + const hasContent = typeof extra.content === 'string' + if (hasPath === hasContent) { + throw new Error('Provide exactly one of "path" (a local file) or "content" (with "name").') + } + if (hasPath) { + const absolutePath = resolveLocalFile(extra.path as string) + return { + ...input, + name: input.name ?? path.basename(absolutePath), + contentType: readFileMimeType(absolutePath), + } + } + if (typeof input.name !== 'string' || !input.name.trim()) { + throw new Error('"name" is required when creating a file from "content".') + } + return { ...input, contentType: getFileMimeType(null, input.name, 'text/plain') } + }, + present: uploadAndComplete, +} + +const createVersionExtension: AgentToolExtension = { + description: + 'Create a new version of an existing file (or version stack) from a local file path. ' + + 'The new version becomes the current one. ' + + METADATA_HINT, + extraParameters: z.object({ + path: z + .string() + .min(1) + .describe('Absolute or relative path of the local file to upload as the new version.'), + }), + hiddenParameters: ['name', 'contentType'], + adjustParameters: setCreationMetadata, + toInput(input, extra) { + const absolutePath = resolveLocalFile(extra.path as string) + return { + ...input, + name: path.basename(absolutePath), + contentType: readFileMimeType(absolutePath), + } + }, + present: uploadAndComplete, +} + +registerAgentToolExtension('create_file', createFileExtension) +registerAgentToolExtension('create_version', createVersionExtension) diff --git a/packages/agent/src/operation-tools.test.ts b/packages/agent/src/operation-tools.test.ts index 327a459d..1acdead5 100644 --- a/packages/agent/src/operation-tools.test.ts +++ b/packages/agent/src/operation-tools.test.ts @@ -67,18 +67,35 @@ describe('operation-backed agent tools', () => { .map((t) => t.name) .sort(), ).toEqual([ + 'copy_assets', + 'create_comment', + 'create_file', 'create_folder', + 'create_version', + 'create_version_stack', 'delete_asset', 'download_asset', 'get_asset_render', + 'get_folder_instructions', 'list_assets', + 'list_comments', + 'list_metadata_fields', 'list_projects', + 'list_versions', 'move_assets', 'read_asset', + 'remove_version', 'rename_asset', + 'resolve_comment', + 'search_assets', + 'update_asset_metadata', ]) }) + it('does not give the agent complete_upload: its create tools finish uploads themselves', () => { + expect(buildOperationTools(ctx).map((t) => t.name)).not.toContain('complete_upload') + }) + it('keeps the existing parameter names', () => { const params = (name: string) => Object.keys((getTool(name).parameters as unknown as { properties: object }).properties) @@ -353,6 +370,7 @@ describe('operation-backed agent tools', () => { id: 'asset-1', name: 'x', type, + parentId: null, teamId: 'team-1', projectId: 'proj-1', }) diff --git a/packages/agent/src/operation-tools.ts b/packages/agent/src/operation-tools.ts index da5dbb06..88a68e5b 100644 --- a/packages/agent/src/operation-tools.ts +++ b/packages/agent/src/operation-tools.ts @@ -13,6 +13,23 @@ import { /** Context for agent-invoked Operations; `via` is always `agent`. */ export type AgentOperationContext = Omit +/** Per-session settings for building tools, e.g. schemas that depend on the project. */ +export interface AgentToolOptions { + /** + * Schema of the conversation project's Creation Context fields, for the `metadata` + * parameter of tools that create files. Undefined when the project has none. + */ + creationMetadataSchema?: TSchema +} + +/** The JSON Schema of a tool's parameters (an object schema). */ +export interface ToolParametersSchema { + type?: string + properties: Record + required?: string[] + [key: string]: unknown +} + /** * Agent-specific presentation for an Operation. By default a tool returns the Operation output * as JSON text; an extension can add agent-only parameters, map them into the Operation input, @@ -29,6 +46,10 @@ export interface AgentToolExtension { * input when it runs. */ parameterOverrides?: z.ZodObject + /** Operation input fields the agent doesn't see because `toInput` fills them in. */ + hiddenParameters?: readonly string[] + /** Adjust the parameters' JSON Schema for this session (e.g. a project-specific field). */ + adjustParameters?(schema: ToolParametersSchema, options: AgentToolOptions): void /** Adjust the Operation input using the extra parameters. */ toInput?(input: Record, extra: Record): Record /** @@ -40,7 +61,11 @@ export interface AgentToolExtension { extra: Record, ctx: AgentOperationContext, ): Promise | undefined> - present(output: unknown, extra: Record): Promise> + present( + output: unknown, + extra: Record, + ctx: AgentOperationContext, + ): Promise> } const extensions = new Map() @@ -62,12 +87,21 @@ function toolInputSchema(op: Operation, extension?: AgentToolExtension): z.ZodOb * TypeBox schemas are plain JSON Schema at runtime, so the converted schema is used as-is. * Throws when the schema cannot be compiled, so a bad definition fails loudly in tests. */ -export function toToolParameters(op: Operation, extension?: AgentToolExtension): TSchema { - const schema: Record = z.toJSONSchema(toolInputSchema(op, extension), { +export function toToolParameters( + op: Operation, + extension?: AgentToolExtension, + options: AgentToolOptions = {}, +): TSchema { + const schema = z.toJSONSchema(toolInputSchema(op, extension), { io: 'input', - }) + }) as unknown as ToolParametersSchema // `$schema` is not understood by the harness validator or every model provider. delete schema.$schema + for (const name of extension?.hiddenParameters ?? []) { + delete schema.properties[name] + schema.required = schema.required?.filter((field) => field !== name) + } + extension?.adjustParameters?.(schema, options) Compile(schema) return schema as unknown as TSchema } @@ -92,14 +126,18 @@ export function splitAgentParams( } /** Expose an Operation as a native agent tool that runs through `runOperation`. */ -export function toAgentTool(op: Operation, ctx: AgentOperationContext): AgentTool { +export function toAgentTool( + op: Operation, + ctx: AgentOperationContext, + options: AgentToolOptions = {}, +): AgentTool { const { definition } = op const extension = extensions.get(definition.name) return { name: definition.name, label: definition.title, description: extension?.description ?? definition.description, - parameters: toToolParameters(op, extension), + parameters: toToolParameters(op, extension, options), execute: async (_toolCallId, params) => { const { input, extra } = splitAgentParams(op, extension, params) if (extension?.intercept) { @@ -108,7 +146,7 @@ export function toAgentTool(op: Operation, ctx: AgentOperationContext): AgentToo } const output = await runOperation(op, { ...ctx, via: 'agent' }, input) if (extension) { - return extension.present(output, extra) + return extension.present(output, extra, ctx) } return { content: [{ type: 'text', text: JSON.stringify(output, null, 2) }], @@ -119,6 +157,9 @@ export function toAgentTool(op: Operation, ctx: AgentOperationContext): AgentToo } /** Agent tools for every Operation with the `agent` surface. */ -export function buildOperationTools(ctx: AgentOperationContext): AgentTool[] { - return getOperationsForSurface('agent').map((op) => toAgentTool(op, ctx)) +export function buildOperationTools( + ctx: AgentOperationContext, + options: AgentToolOptions = {}, +): AgentTool[] { + return getOperationsForSurface('agent').map((op) => toAgentTool(op, ctx, options)) } diff --git a/packages/agent/src/reproduce-tool-null-coercion.test.ts b/packages/agent/src/reproduce-tool-null-coercion.test.ts deleted file mode 100644 index ba242670..00000000 --- a/packages/agent/src/reproduce-tool-null-coercion.test.ts +++ /dev/null @@ -1,117 +0,0 @@ -import { describe, it, expect, vi, beforeEach } from 'vitest' -import { validateToolArguments } from '@earendil-works/pi-ai' -import { createCreateFileTool } from './tools/create-file' -import { fieldsToTypeBoxSchema } from './index' -import { s3Service } from '@shumai/core/src/s3/s3' -import { assetService } from '@shumai/core/src/asset/asset' -import { authzService } from '@shumai/core/src/authz/authz' - -vi.mock('@shumai/core/src/s3/s3', () => ({ - s3Service: { - uploadFileToKey: vi.fn(), - putObject: vi.fn(), - }, -})) - -vi.mock('@shumai/core/src/authz/authz', () => ({ - authzService: { - hasPermission: vi.fn().mockResolvedValue(undefined), - }, - Permission: { Edit: 'edit', Read: 'read' }, - ResourceType: { Asset: 'asset' }, -})) - -vi.mock('@shumai/core/src/asset/asset', () => ({ - assetService: { - createFile: vi - .fn() - .mockResolvedValue({ id: 'file-1', name: 'test', type: 'file', sizeByte: 100 }), - }, -})) - -/** - * Reproduce: pi-ai <= 0.82.1 runs its lenient coercion on typebox v1 schemas and - * converts `null` in a `[string, null]` union into `""` (see - * coerceWithUnionSchema in @earendil-works/pi-ai/dist/utils/validation.js). - * - * When the agent calls create_file with `path: null, data: {...}`, the harness - * validates first: the `null` path becomes `""`, so the tool's - * assertExactlyOneSource believes BOTH path and data were provided and throws - * "Provide exactly one of ..." even though the call is valid. - * - * Fixed upstream in pi-ai 0.84.0 (#7328): values that already match a union arm - * are preserved before coercion. This test should pass once @earendil-works/pi-ai - * is upgraded to >= 0.84.0. - */ -describe('reproduce null coercion in harness tool validation', () => { - beforeEach(() => { - vi.clearAllMocks() - }) - - it('keeps path: null when data is provided (no false "exactly one" error)', async () => { - const tool = createCreateFileTool('user-1') - - const validated = validateToolArguments( - { - name: 'create_file', - description: '', - parameters: tool.parameters, - } as Parameters[0], - { - type: 'toolCall', - id: 'call-1', - name: 'create_file', - arguments: { - parent: '01KYKNP52YERGJ6Q4GTPF5FRQF', - path: null, - data: { name: 'random_text.txt', content: 'hello' }, - }, - } as Parameters[1], - ) as { path?: unknown; data?: unknown } - - // The `null` path must survive validation untouched; coercion to "" makes - // the tool think both path and data were provided. - expect(validated.path).toBeNull() - expect(validated.data).toEqual({ name: 'random_text.txt', content: 'hello' }) - - // execute must accept the valid call (data-only) without throwing - const result = await tool.execute('call-1', validated as never) - expect(result.details).toEqual({}) - expect(JSON.parse((result.content[0] as { text: string }).text)).toEqual({ - id: 'file-1', - name: 'test', - type: 'file', - size: 100, - }) - expect(s3Service.putObject).toHaveBeenCalledTimes(1) - expect(authzService.hasPermission).toHaveBeenCalledTimes(1) - expect(assetService.createFile).toHaveBeenCalledTimes(1) - }) - - it('keeps null metadata values (the "unknown" sentinel) through validation', () => { - const tool = createCreateFileTool( - 'user-1', - fieldsToTypeBoxSchema([{ id: 'prompt', config: { name: 'Prompt', type: 'text' } }]), - ) - const validated = validateToolArguments( - { - name: 'create_file', - description: '', - parameters: tool.parameters, - } as Parameters[0], - { - type: 'toolCall', - id: 'call-1', - name: 'create_file', - arguments: { - parent: 'folder-1', - path: null, - data: { name: 'a.md', content: 'x' }, - metadata: { prompt: null }, - }, - } as Parameters[1], - ) as { metadata?: Record } - - expect(validated.metadata).toEqual({ prompt: null }) - }) -}) diff --git a/packages/agent/src/tools/create-file.test.ts b/packages/agent/src/tools/create-file.test.ts deleted file mode 100644 index 1a2df37f..00000000 --- a/packages/agent/src/tools/create-file.test.ts +++ /dev/null @@ -1,408 +0,0 @@ -import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest' -import { createCreateFileTool } from './create-file' -import { fieldsToTypeBoxSchema } from '../index' -import { s3Service } from '@shumai/core/src/s3/s3' -import { assetService } from '@shumai/core/src/asset/asset' -import { auditLogService } from '@shumai/core/src/auditLog/auditLog' -import { authzService } from '@shumai/core/src/authz/authz' -import { AuditAction } from '@shumai/dtos' -import { Value } from 'typebox/value' -import * as fs from 'fs' -import * as os from 'os' -import * as path from 'path' - -vi.mock('@shumai/core/src/s3/s3', () => ({ - s3Service: { - uploadFileToKey: vi.fn(), - putObject: vi.fn(), - }, -})) - -vi.mock('@shumai/core/src/authz/authz', () => ({ - authzService: { - hasPermission: vi.fn().mockResolvedValue(undefined), - }, - Permission: { Edit: 'edit', Read: 'read' }, - ResourceType: { Asset: 'asset' }, -})) - -vi.mock('@shumai/core/src/asset/asset', () => ({ - assetService: { - createFile: vi - .fn() - .mockResolvedValue({ id: 'file-1', name: 'test', type: 'file', sizeByte: 100 }), - }, -})) - -vi.mock('@shumai/core/src/auditLog/auditLog', () => ({ - auditLogService: { - logAction: vi.fn().mockResolvedValue(undefined), - }, -})) - -describe('createCreateFileTool', () => { - const createdFiles: string[] = [] - - beforeEach(() => { - vi.clearAllMocks() - }) - - afterEach(() => { - for (const f of createdFiles) { - if (fs.existsSync(f)) { - fs.unlinkSync(f) - } - } - createdFiles.length = 0 - }) - - const createTempFile = (content: string | Buffer, filename: string): string => { - const filePath = path.join(os.tmpdir(), filename) - fs.writeFileSync(filePath, content) - createdFiles.push(filePath) - return filePath - } - - it('should upload a local file when "path" is provided', async () => { - const filePath = createTempFile('# Hello from disk', 'create-file-test.md') - - const tool = createCreateFileTool('user-1') - const result = await tool.execute('call-1', { parent: 'folder-1', path: filePath, data: null }) - - expect(s3Service.uploadFileToKey).toHaveBeenCalledTimes(1) - expect(s3Service.putObject).not.toHaveBeenCalled() - - const uploadArgs = vi.mocked(s3Service.uploadFileToKey).mock.calls[0] - const s3Key = uploadArgs[1] - expect(s3Key).toMatch(/^files\/.+\.md$/) - expect(uploadArgs[2]).toBe('text/markdown') - - expect(authzService.hasPermission).toHaveBeenCalledWith({ - user: { id: 'user-1' }, - permission: 'edit', - type: 'asset', - id: 'folder-1', - }) - - expect(assetService.createFile).toHaveBeenCalledWith({ - parentId: 'folder-1', - name: 'create-file-test.md', - key: s3Key, - sizeByte: Buffer.byteLength('# Hello from disk', 'utf-8'), - contentType: 'text/markdown', - creatorId: 'user-1', - metadata: undefined, - }) - - expect(result.details).toEqual({}) - expect(JSON.parse((result.content[0] as { text: string }).text)).toEqual({ - id: 'file-1', - name: 'test', - type: 'file', - size: 100, - }) - }) - - it('should forward the metadata to assetService.createFile when provided', async () => { - const filePath = createTempFile('# Hello from disk', 'create-file-metadata.md') - const metadataSchema = fieldsToTypeBoxSchema([ - { id: 'prompt', config: { name: 'Prompt', type: 'text' } }, - ]) - - const tool = createCreateFileTool('user-1', metadataSchema) - await tool.execute('call-1', { - parent: 'folder-1', - path: filePath, - data: null, - metadata: { prompt: 'Generated using gemini' }, - }) - - expect(assetService.createFile).toHaveBeenCalledWith( - expect.objectContaining({ - metadata: { prompt: 'Generated using gemini' }, - }), - ) - }) - - it('should forward select and selectMulti newOption metadata', async () => { - const filePath = createTempFile('# Hello from disk', 'create-file-new-option.md') - const metadataSchema = fieldsToTypeBoxSchema([ - { - id: 'provider', - config: { - name: 'Provider', - type: 'select', - select: { options: [{ id: 'openai', displayName: 'OpenAI', color: '#f43f5e' }] }, - }, - }, - { - id: 'tags', - config: { - name: 'Tags', - type: 'selectMulti', - selectMulti: { options: [{ id: 'tag1', displayName: 'Tag 1', color: '#3b82f6' }] }, - }, - }, - ]) - - const tool = createCreateFileTool('user-1', metadataSchema) - await tool.execute('call-1', { - parent: 'folder-1', - path: filePath, - data: null, - metadata: { - provider: { newOption: { value: 'Kling' } }, - tags: ['tag1', { newOption: { value: 'Tag 2' } }], - }, - }) - - expect(assetService.createFile).toHaveBeenCalledWith( - expect.objectContaining({ - metadata: { - provider: { newOption: { value: 'Kling' } }, - tags: ['tag1', { newOption: { value: 'Tag 2' } }], - }, - }), - ) - }) - - it('should not include metadata when metadata is null', async () => { - const filePath = createTempFile('# Hello from disk', 'create-file-no-metadata.md') - const metadataSchema = fieldsToTypeBoxSchema([ - { id: 'prompt', config: { name: 'Prompt', type: 'text' } }, - ]) - - const tool = createCreateFileTool('user-1', metadataSchema) - await tool.execute('call-1', { - parent: 'folder-1', - path: filePath, - data: null, - metadata: null, - }) - - const callArgs = vi.mocked(assetService.createFile).mock.calls[0][0] - expect(callArgs.metadata).toBeUndefined() - }) - - it('should throw when the local file does not exist', async () => { - const tool = createCreateFileTool('user-1') - await expect( - tool.execute('call-1', { parent: 'folder-1', path: '/nonexistent/file.md', data: null }), - ).rejects.toThrow('Local file not found at path: /nonexistent/file.md') - expect(s3Service.uploadFileToKey).not.toHaveBeenCalled() - expect(assetService.createFile).not.toHaveBeenCalled() - }) - - it('should create a file directly from name and content', async () => { - const tool = createCreateFileTool('user-1') - const result = await tool.execute('call-1', { - parent: 'folder-1', - path: null, - data: { name: 'notes.md', content: '# Notes\n\nHello' }, - }) - - expect(s3Service.putObject).toHaveBeenCalledTimes(1) - expect(s3Service.uploadFileToKey).not.toHaveBeenCalled() - - const [bucket, s3Key, body, size, contentType] = vi.mocked(s3Service.putObject).mock - .calls[0] as unknown as [string, string, Buffer, number, string] - - expect(bucket).toBe(process.env.S3_BUCKET || 'shumai') - expect(s3Key).toMatch(/^files\/.+notes\.md$/) - expect(body.toString('utf-8')).toBe('# Notes\n\nHello') - expect(size).toBe(Buffer.byteLength('# Notes\n\nHello', 'utf-8')) - expect(contentType).toBe('text/markdown') - - expect(assetService.createFile).toHaveBeenCalledWith({ - parentId: 'folder-1', - name: 'notes.md', - key: s3Key, - sizeByte: Buffer.byteLength('# Notes\n\nHello', 'utf-8'), - contentType: 'text/markdown', - creatorId: 'user-1', - metadata: undefined, - }) - - expect(result.details).toEqual({}) - expect(JSON.parse((result.content[0] as { text: string }).text)).toEqual({ - id: 'file-1', - name: 'test', - type: 'file', - size: 100, - }) - }) - - it('should default unknown extensions to text/plain when creating from content', async () => { - const tool = createCreateFileTool('user-1') - await tool.execute('call-1', { - parent: 'folder-1', - path: null, - data: { name: 'script.ts', content: 'const x = 1' }, - }) - - const [, , , , contentType] = vi.mocked(s3Service.putObject).mock.calls[0] as unknown as [ - string, - string, - Buffer, - number, - string, - ] - expect(contentType).toBe('text/plain') - }) - - it('should sanitize the name when creating from content', async () => { - const tool = createCreateFileTool('user-1') - await tool.execute('call-1', { - parent: 'folder-1', - path: null, - data: { name: 'my/notes.md', content: 'hello' }, - }) - - const [, s3Key] = vi.mocked(s3Service.putObject).mock.calls[0] as unknown as [ - string, - string, - Buffer, - number, - string, - ] - expect(s3Key).toContain('my_notes.md') - - expect(assetService.createFile).toHaveBeenCalledWith( - expect.objectContaining({ name: 'my_notes.md' }), - ) - }) - - it('should throw when neither "path" nor "data" is provided', async () => { - const tool = createCreateFileTool('user-1') - await expect( - tool.execute('call-1', { parent: 'folder-1', path: null, data: null }), - ).rejects.toThrow('Provide exactly one of "path" (a local file) or "data" (name and content).') - }) - - it('should throw when both "path" and "data" are provided', async () => { - const tool = createCreateFileTool('user-1') - await expect( - tool.execute('call-1', { - parent: 'folder-1', - path: '/some/file.md', - data: { name: 'notes.md', content: 'hello' }, - }), - ).rejects.toThrow('Provide exactly one of "path" (a local file) or "data" (name and content).') - expect(s3Service.uploadFileToKey).not.toHaveBeenCalled() - expect(s3Service.putObject).not.toHaveBeenCalled() - expect(assetService.createFile).not.toHaveBeenCalled() - }) - - it('should expose a strict, all-required (nullable) metadata schema when fields are provided', () => { - const metadataSchema = fieldsToTypeBoxSchema([ - { id: 'prompt', config: { name: 'Prompt', type: 'text' } }, - { - id: 'source', - config: { - name: 'Source', - type: 'select', - select: { options: [{ id: 'gemini', displayName: 'Gemini', color: '#ffffff' }] }, - }, - }, - { id: 'rating', config: { name: 'Rating', type: 'rating' } }, - ]) - - const tool = createCreateFileTool('user-1', metadataSchema) - // eslint-disable-next-line @typescript-eslint/no-explicit-any -- inspecting the runtime schema shape of the dynamically-built tool - const meta = (tool.parameters as any).properties.metadata - // `metadata` is a nullable union: [strict object, null] - const metaObject = meta.anyOf[0] - - expect(meta).toBeDefined() - expect(metaObject.required).toEqual(['prompt', 'source', 'rating']) - expect(metaObject.additionalProperties).toBe(false) - expect(metaObject.properties.prompt.anyOf[0].type).toBe('string') - expect(metaObject.properties.prompt.anyOf[1].type).toBe('null') - expect(metaObject.properties.source.anyOf[0].anyOf[0].enum).toEqual(['gemini']) - expect(metaObject.properties.rating.anyOf[0].type).toBe('number') - - // Every field must be present (use null when unknown); unknown keys and bad enums are rejected - expect(Value.Check(meta, { prompt: 'hello', source: 'gemini', rating: 5 })).toBe(true) - expect( - Value.Check(meta, { - prompt: 'hello', - source: { newOption: { value: 'kling' } }, - rating: 5, - }), - ).toBe(true) - expect(Value.Check(meta, { prompt: null, source: null, rating: null })).toBe(true) - expect(Value.Check(meta, { prompt: 'hello', source: null, rating: null })).toBe(true) - expect(Value.Check(meta, { prompt: 'hello' })).toBe(false) - expect( - Value.Check(meta, { prompt: 'hello', source: 'gemini', rating: 5, unknownKey: 'x' }), - ).toBe(false) - expect(Value.Check(meta, { prompt: 'hello', source: 'not-an-option', rating: null })).toBe( - false, - ) - }) - - it('should omit the metadata parameter when no schema is provided', () => { - const tool = createCreateFileTool('user-1') - // eslint-disable-next-line @typescript-eslint/no-explicit-any -- inspecting the runtime schema shape of the dynamically-built tool - expect((tool.parameters as any).properties.metadata).toBeUndefined() - }) - - describe('when the user lacks Edit permission on the parent', () => { - const denied = new Error('User is not a member of the team') - - beforeEach(() => { - vi.mocked(authzService.hasPermission).mockRejectedValueOnce(denied) - }) - - it('does not upload a local file to storage', async () => { - const filePath = createTempFile('# Not allowed', 'create-file-denied.md') - - const tool = createCreateFileTool('user-1') - await expect( - tool.execute('call-1', { parent: 'folder-1', path: filePath, data: null }), - ).rejects.toThrow(denied.message) - - expect(s3Service.uploadFileToKey).not.toHaveBeenCalled() - expect(s3Service.putObject).not.toHaveBeenCalled() - expect(assetService.createFile).not.toHaveBeenCalled() - }) - - it('does not write inline content to storage', async () => { - const tool = createCreateFileTool('user-1') - await expect( - tool.execute('call-1', { - parent: 'folder-1', - path: null, - data: { name: 'notes.md', content: 'hello' }, - }), - ).rejects.toThrow(denied.message) - - expect(s3Service.putObject).not.toHaveBeenCalled() - expect(s3Service.uploadFileToKey).not.toHaveBeenCalled() - expect(assetService.createFile).not.toHaveBeenCalled() - }) - }) - - it('should pass agentId and record audit log when agentContext is provided', async () => { - const filePath = createTempFile('# Agent file', 'agent-file.md') - - const tool = createCreateFileTool('user-1', undefined, { teamId: 'team-1', agentId: 'agent-1' }) - await tool.execute('call-1', { parent: 'folder-1', path: filePath, data: null }) - - expect(assetService.createFile).toHaveBeenCalledWith( - expect.objectContaining({ - creatorId: 'user-1', - agentId: 'agent-1', - }), - ) - - expect(auditLogService.logAction).toHaveBeenCalledWith({ - action: AuditAction.file_create, - teamId: 'team-1', - userId: 'user-1', - agentId: 'agent-1', - projectId: undefined, - itemId: 'file-1', - }) - }) -}) diff --git a/packages/agent/src/tools/create-file.ts b/packages/agent/src/tools/create-file.ts deleted file mode 100644 index ba14730b..00000000 --- a/packages/agent/src/tools/create-file.ts +++ /dev/null @@ -1,160 +0,0 @@ -import { type AgentTool } from '@earendil-works/pi-agent-core' -import { assetService } from '@shumai/core/src/asset/asset' -import { auditLogService } from '@shumai/core/src/auditLog/auditLog' -import { authzService, Permission, ResourceType } from '@shumai/core/src/authz/authz' -import { s3Service } from '@shumai/core/src/s3/s3' -import { getFileMimeType, readFileMimeType } from '@shumai/core/src/utils/file-mime' -import { sanitizeFilename } from '@shumai/core/src/utils/filename' -import { type User } from '@shumai/db' -import { AuditAction } from '@shumai/dtos' -import { Type, type TSchema } from 'typebox' -import * as fs from 'fs' -import * as path from 'path' -import { ulid } from 'ulid' - -interface CreateFileToolParams { - parent: string - path: string | null - data: { name: string; content: string } | null - metadata?: Record | null -} - -function assertExactlyOneSource(params: CreateFileToolParams) { - const hasPath = params.path !== null - const hasData = params.data !== null - if (hasPath === hasData) { - throw new Error('Provide exactly one of "path" (a local file) or "data" (name and content).') - } - return hasPath ? params.path! : params.data! -} - -export function createCreateFileTool( - userId: string, - metadataSchema?: TSchema, - agentContext?: { teamId?: string; agentId?: string }, -): AgentTool { - const createFileSchema = Type.Object( - { - parent: Type.String({ - description: - 'The parent folder ID under which to create the file. This parameter is required.', - }), - path: Type.Union([ - Type.String({ - description: - 'The absolute or relative local path to an existing file on disk. Provide a value here OR in "data", but not both. Use null if you are providing "data".', - }), - Type.Null(), - ]), - data: Type.Union([ - Type.Object( - { - name: Type.String({ - minLength: 1, - description: - 'The desired name for the new file, including its extension (e.g. "notes.md").', - }), - content: Type.String({ - description: 'The full content of the file as a plain string.', - }), - }, - { additionalProperties: false }, - ), - Type.Null(), - ]), - ...(metadataSchema ? { metadata: Type.Union([metadataSchema, Type.Null()]) } : {}), - }, - { additionalProperties: false }, - ) - - const tool: AgentTool = { - name: 'create_file', - label: 'Create File', - description: - 'Create a new file under a folder. You MUST choose exactly ONE creation method: ' + - '(1) provide "path" to upload an existing local file, OR ' + - '(2) provide "data" with name and content to create a new text file. ' + - 'Set the unused parameter to null. ' + - 'The optional "metadata" parameter accepts only the CREATION_CONTEXT fields declared in its schema; never invent field keys, and use null for fields you do not know.', - parameters: createFileSchema, - execute: async (_toolCallId, params) => { - // The harness validates tool args against `createFileSchema` before calling - // execute, so `params` is guaranteed to match this shape. - const p = params as CreateFileToolParams - const source = assertExactlyOneSource(p) - - // Authorize before touching storage so a denied call leaves no orphaned object behind. - await authzService.hasPermission({ - user: { id: userId } as User, - permission: Permission.Edit, - type: ResourceType.Asset, - id: p.parent, - }) - - let name: string - let size: number - let mimeType: string - let s3Key: string - - if (typeof source === 'string') { - // Branch A: upload an existing local file - const absolutePath = path.resolve(process.cwd(), source) - if (!fs.existsSync(absolutePath)) { - throw new Error(`Local file not found at path: ${source}`) - } - - name = path.basename(absolutePath) - size = fs.statSync(absolutePath).size - mimeType = readFileMimeType(absolutePath) - - // Generate compliant S3 key matching normal file upload format - s3Key = `files/${ulid()}/${sanitizeFilename(name)}` - await s3Service.uploadFileToKey(absolutePath, s3Key, mimeType) - } else { - // Branch B: create the file directly from provided name and content - name = sanitizeFilename(source.name) - const content = Buffer.from(source.content, 'utf-8') - size = content.byteLength - mimeType = getFileMimeType(null, source.name, 'text/plain') - - s3Key = `files/${ulid()}/${name}` - await s3Service.putObject(process.env.S3_BUCKET || 'shumai', s3Key, content, size, mimeType) - } - - const asset = await assetService.createFile({ - parentId: p.parent, - name, - key: s3Key, - sizeByte: size, - contentType: mimeType, - creatorId: userId, - agentId: agentContext?.agentId, - metadata: p.metadata ?? undefined, - }) - - if (agentContext?.teamId) { - await auditLogService.logAction({ - action: AuditAction.file_create, - teamId: agentContext.teamId, - userId, - agentId: agentContext.agentId, - projectId: asset.projectId ?? undefined, - itemId: asset.id, - }) - } - - const result = { - id: asset.id, - name: asset.name, - type: asset.type, - size: Number(asset.sizeByte), - } - - return { - content: [{ type: 'text', text: JSON.stringify(result, null, 2) }], - details: {}, - } - }, - } - return tool -} diff --git a/packages/agent/src/tools/create-version.test.ts b/packages/agent/src/tools/create-version.test.ts deleted file mode 100644 index c0f06571..00000000 --- a/packages/agent/src/tools/create-version.test.ts +++ /dev/null @@ -1,256 +0,0 @@ -import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest' -import { createCreateVersionTool } from './create-version' -import { fieldsToTypeBoxSchema } from '../index' -import { s3Service } from '@shumai/core/src/s3/s3' -import { assetService } from '@shumai/core/src/asset/asset' -import { auditLogService } from '@shumai/core/src/auditLog/auditLog' -import { authzService } from '@shumai/core/src/authz/authz' -import { AuditAction } from '@shumai/dtos' -import { Value } from 'typebox/value' -import * as fs from 'fs' -import * as os from 'os' -import * as path from 'path' - -vi.mock('@shumai/core/src/s3/s3', () => ({ - s3Service: { - uploadFileToKey: vi.fn(), - }, -})) - -vi.mock('@shumai/core/src/authz/authz', () => ({ - authzService: { - hasPermission: vi.fn().mockResolvedValue(undefined), - }, - Permission: { Edit: 'edit', Read: 'read' }, - ResourceType: { Asset: 'asset' }, -})) - -vi.mock('@shumai/core/src/asset/asset', () => ({ - assetService: { - createVersion: vi - .fn() - .mockResolvedValue({ id: 'file-1', name: 'v2', type: 'file', sizeByte: 100 }), - }, -})) - -vi.mock('@shumai/core/src/auditLog/auditLog', () => ({ - auditLogService: { - logAction: vi.fn().mockResolvedValue(undefined), - }, -})) - -describe('createCreateVersionTool', () => { - const createdFiles: string[] = [] - - beforeEach(() => { - vi.clearAllMocks() - }) - - afterEach(() => { - for (const f of createdFiles) { - if (fs.existsSync(f)) { - fs.unlinkSync(f) - } - } - createdFiles.length = 0 - }) - - const createTempFile = (content: string | Buffer, filename: string): string => { - const filePath = path.join(os.tmpdir(), filename) - fs.writeFileSync(filePath, content) - createdFiles.push(filePath) - return filePath - } - - it('should not upload to storage when the user lacks Edit permission on the parent', async () => { - vi.mocked(authzService.hasPermission).mockRejectedValueOnce( - new Error('User is not a member of the team'), - ) - const filePath = createTempFile('# Not allowed', 'create-version-denied.md') - - const tool = createCreateVersionTool('user-1') - await expect(tool.execute('call-1', { parent: 'file-1', path: filePath })).rejects.toThrow( - 'User is not a member of the team', - ) - - expect(s3Service.uploadFileToKey).not.toHaveBeenCalled() - expect(assetService.createVersion).not.toHaveBeenCalled() - }) - - it('should upload a local file and create a version via assetService.createVersion', async () => { - const filePath = createTempFile('# Hello from disk', 'create-version-test.md') - - const tool = createCreateVersionTool('user-1') - const result = await tool.execute('call-1', { parent: 'file-1', path: filePath }) - - expect(s3Service.uploadFileToKey).toHaveBeenCalledTimes(1) - const uploadArgs = vi.mocked(s3Service.uploadFileToKey).mock.calls[0] - const s3Key = uploadArgs[1] - expect(s3Key).toMatch(/^files\/.+\.md$/) - expect(uploadArgs[2]).toBe('text/markdown') - - expect(authzService.hasPermission).toHaveBeenCalledWith({ - user: { id: 'user-1' }, - permission: 'edit', - type: 'asset', - id: 'file-1', - }) - - expect(assetService.createVersion).toHaveBeenCalledWith({ - parentId: 'file-1', - name: 'create-version-test.md', - key: s3Key, - sizeByte: Buffer.byteLength('# Hello from disk', 'utf-8'), - contentType: 'text/markdown', - creatorId: 'user-1', - metadata: undefined, - }) - - expect(result.details).toEqual({}) - expect(JSON.parse((result.content[0] as { text: string }).text)).toEqual({ - id: 'file-1', - name: 'v2', - type: 'file', - size: 100, - }) - }) - - it('should forward the metadata to assetService.createVersion when provided', async () => { - const filePath = createTempFile('# Hello from disk', 'create-version-metadata.md') - const metadataSchema = fieldsToTypeBoxSchema([ - { id: 'prompt', config: { name: 'Prompt', type: 'text' } }, - ]) - - const tool = createCreateVersionTool('user-1', metadataSchema) - await tool.execute('call-1', { - parent: 'file-1', - path: filePath, - metadata: { prompt: 'Generated using gemini' }, - }) - - expect(assetService.createVersion).toHaveBeenCalledWith( - expect.objectContaining({ - metadata: { prompt: 'Generated using gemini' }, - }), - ) - }) - - it('should forward select and selectMulti newOption metadata', async () => { - const filePath = createTempFile('# Hello from disk', 'create-version-new-option.md') - const metadataSchema = fieldsToTypeBoxSchema([ - { - id: 'provider', - config: { - name: 'Provider', - type: 'select', - select: { options: [{ id: 'openai', displayName: 'OpenAI', color: '#f43f5e' }] }, - }, - }, - { - id: 'tags', - config: { - name: 'Tags', - type: 'selectMulti', - selectMulti: { options: [{ id: 'tag1', displayName: 'Tag 1', color: '#3b82f6' }] }, - }, - }, - ]) - - const tool = createCreateVersionTool('user-1', metadataSchema) - await tool.execute('call-1', { - parent: 'file-1', - path: filePath, - metadata: { - provider: { newOption: { value: 'Kling' } }, - tags: ['tag1', { newOption: { value: 'Tag 2' } }], - }, - }) - - expect(assetService.createVersion).toHaveBeenCalledWith( - expect.objectContaining({ - metadata: { - provider: { newOption: { value: 'Kling' } }, - tags: ['tag1', { newOption: { value: 'Tag 2' } }], - }, - }), - ) - }) - - it('should not include metadata when metadata is null', async () => { - const filePath = createTempFile('# Hello from disk', 'create-version-no-metadata.md') - const metadataSchema = fieldsToTypeBoxSchema([ - { id: 'prompt', config: { name: 'Prompt', type: 'text' } }, - ]) - - const tool = createCreateVersionTool('user-1', metadataSchema) - await tool.execute('call-1', { parent: 'file-1', path: filePath, metadata: null }) - - const callArgs = vi.mocked(assetService.createVersion).mock.calls[0][0] - expect(callArgs.metadata).toBeUndefined() - }) - - it('should throw when the local file does not exist', async () => { - const tool = createCreateVersionTool('user-1') - await expect( - tool.execute('call-1', { parent: 'file-1', path: '/nonexistent/file.md' }), - ).rejects.toThrow('Local file not found at path: /nonexistent/file.md') - expect(s3Service.uploadFileToKey).not.toHaveBeenCalled() - expect(assetService.createVersion).not.toHaveBeenCalled() - }) - - it('should expose a strict, all-required (nullable) metadata schema when fields are provided', () => { - const metadataSchema = fieldsToTypeBoxSchema([ - { id: 'prompt', config: { name: 'Prompt', type: 'text' } }, - { id: 'toggle', config: { name: 'Active', type: 'toggle' } }, - ]) - - const tool = createCreateVersionTool('user-1', metadataSchema) - // eslint-disable-next-line @typescript-eslint/no-explicit-any -- inspecting the runtime schema shape of the dynamically-built tool - const meta = (tool.parameters as any).properties.metadata - // `metadata` is a nullable union: [strict object, null] - const metaObject = meta.anyOf[0] - - expect(meta).toBeDefined() - expect(metaObject.required).toEqual(['prompt', 'toggle']) - expect(metaObject.additionalProperties).toBe(false) - expect(metaObject.properties.prompt.anyOf[0].type).toBe('string') - expect(metaObject.properties.prompt.anyOf[1].type).toBe('null') - expect(metaObject.properties.toggle.anyOf[0].type).toBe('boolean') - - expect(Value.Check(meta, { prompt: 'p', toggle: true })).toBe(true) - expect(Value.Check(meta, { prompt: null, toggle: null })).toBe(true) - expect(Value.Check(meta, { prompt: 'p', toggle: null, unknownKey: 'x' })).toBe(false) - }) - - it('should omit the metadata parameter when no schema is provided', () => { - const tool = createCreateVersionTool('user-1') - // eslint-disable-next-line @typescript-eslint/no-explicit-any -- inspecting the runtime schema shape of the dynamically-built tool - expect((tool.parameters as any).properties.metadata).toBeUndefined() - }) - - it('should pass agentId and record audit log when agentContext is provided', async () => { - const filePath = createTempFile('# Agent version file', 'agent-ver-file.md') - - const tool = createCreateVersionTool('user-1', undefined, { - teamId: 'team-1', - agentId: 'agent-1', - }) - await tool.execute('call-1', { parent: 'file-1', path: filePath }) - - expect(assetService.createVersion).toHaveBeenCalledWith( - expect.objectContaining({ - creatorId: 'user-1', - agentId: 'agent-1', - }), - ) - - expect(auditLogService.logAction).toHaveBeenCalledWith({ - action: AuditAction.file_create, - teamId: 'team-1', - userId: 'user-1', - agentId: 'agent-1', - projectId: undefined, - itemId: 'file-1', - }) - }) -}) diff --git a/packages/agent/src/tools/create-version.ts b/packages/agent/src/tools/create-version.ts deleted file mode 100644 index dff8001e..00000000 --- a/packages/agent/src/tools/create-version.ts +++ /dev/null @@ -1,110 +0,0 @@ -import { type AgentTool } from '@earendil-works/pi-agent-core' -import { assetService } from '@shumai/core/src/asset/asset' -import { auditLogService } from '@shumai/core/src/auditLog/auditLog' -import { authzService, Permission, ResourceType } from '@shumai/core/src/authz/authz' -import { s3Service } from '@shumai/core/src/s3/s3' -import { readFileMimeType } from '@shumai/core/src/utils/file-mime' -import { sanitizeFilename } from '@shumai/core/src/utils/filename' -import { type User } from '@shumai/db' -import { AuditAction } from '@shumai/dtos' -import { Type, type TSchema } from 'typebox' -import * as fs from 'fs' -import * as path from 'path' -import { ulid } from 'ulid' - -interface CreateVersionToolParams { - parent: string - path: string - metadata?: Record | null -} - -export function createCreateVersionTool( - userId: string, - metadataSchema?: TSchema, - agentContext?: { teamId?: string; agentId?: string }, -): AgentTool { - const createVersionSchema = Type.Object( - { - parent: Type.String({ - description: - 'The parent file ID for which to create a new version. This parameter is required.', - }), - path: Type.String({ - description: - 'The absolute or relative local path to the file on disk. This parameter is required.', - }), - ...(metadataSchema ? { metadata: Type.Union([metadataSchema, Type.Null()]) } : {}), - }, - { additionalProperties: false }, - ) - - const tool: AgentTool = { - name: 'create_version', - label: 'Create Version', - description: - 'Create a new version of an existing file from a local file path. ' + - 'The optional "metadata" parameter accepts only the CREATION_CONTEXT fields declared in its schema; never invent field keys, and use null for fields you do not know.', - parameters: createVersionSchema, - execute: async (_toolCallId, params) => { - // The harness validates tool args against `createVersionSchema` before calling - // execute, so `params` is guaranteed to match this shape. - const p = params as CreateVersionToolParams - - // Authorize before touching storage so a denied call leaves no orphaned object behind. - await authzService.hasPermission({ - user: { id: userId } as User, - permission: Permission.Edit, - type: ResourceType.Asset, - id: p.parent, - }) - - const absolutePath = path.resolve(process.cwd(), p.path) - if (!fs.existsSync(absolutePath)) { - throw new Error(`Local file not found at path: ${p.path}`) - } - - const fileSize = fs.statSync(absolutePath).size - const mimeType = readFileMimeType(absolutePath) - const name = path.basename(absolutePath) - - // Generate compliant S3 key matching normal file upload format - const s3Key = `files/${ulid()}/${sanitizeFilename(name)}` - await s3Service.uploadFileToKey(absolutePath, s3Key, mimeType) - - const asset = await assetService.createVersion({ - parentId: p.parent, - name, - key: s3Key, - sizeByte: fileSize, - contentType: mimeType, - creatorId: userId, - agentId: agentContext?.agentId, - metadata: p.metadata ?? undefined, - }) - - if (agentContext?.teamId) { - await auditLogService.logAction({ - action: AuditAction.file_create, - teamId: agentContext.teamId, - userId, - agentId: agentContext.agentId, - projectId: asset.projectId ?? undefined, - itemId: asset.id, - }) - } - - const result = { - id: asset.id, - name: asset.name, - type: asset.type, - size: Number(asset.sizeByte), - } - - return { - content: [{ type: 'text', text: JSON.stringify(result, null, 2) }], - details: {}, - } - }, - } - return tool -} diff --git a/packages/api/src/file.test.ts b/packages/api/src/file.test.ts index 15243388..cbd85b5f 100644 --- a/packages/api/src/file.test.ts +++ b/packages/api/src/file.test.ts @@ -1,5 +1,6 @@ import { describe, expect, it, vi, beforeEach, afterEach } from 'vitest' import { Hono, type Context, type Next } from 'hono' +import { HTTPException } from 'hono/http-exception' import fileRoute from './file' import { assetService } from '@shumai/core/src/asset/asset' import { metadataService } from '@shumai/core/src/metadata/metadata' @@ -8,7 +9,12 @@ import { s3Service } from '@shumai/core/src/s3/s3' import { transcodeService } from '@shumai/core' import { authMiddleware } from './middleware/auth' import { authzService, ResourceType, Permission } from '@shumai/core/src/authz/authz' -import { renameAssetOp, runOperation } from '@shumai/core/src/operations' +import { + renameAssetOp, + resolveCommentOp, + runOperation, + updateAssetMetadataOp, +} from '@shumai/core/src/operations' vi.mock('fs', async (importOriginal) => { const actual = (await importOriginal()) as Record @@ -450,8 +456,9 @@ describe('file api', () => { expect(resInvalidTz.status).toBe(400) }) - it('POST /comments/:commentId/complete', async () => { - vi.mocked(assetService.completeComment).mockResolvedValue({ + it('POST /comments/:commentId/complete runs resolve_comment and returns the comment', async () => { + vi.mocked(runOperation).mockResolvedValue({ commentId: 'comment-id', resolved: true }) + vi.mocked(assetService.getComment).mockResolvedValue({ id: 'comment-id', assetId: 'file-id', message: 'hello', @@ -483,12 +490,33 @@ describe('file api', () => { expect(json.isCompleted).toBe(true) expect(json.completionLastChangedBy.id).toBe('user1') - expect(authzService.hasPermission).toHaveBeenCalledWith({ - user: { id: 'user1', name: 'Test User' }, - permission: Permission.Read, - type: ResourceType.Comment, + expect(runOperation).toHaveBeenCalledWith( + resolveCommentOp, + { userId: 'user1', via: 'api' }, + { commentId: 'comment-id', reopen: false }, + ) + expect(assetService.getComment).toHaveBeenCalledWith('comment-id', 'user1') + }) + + it('POST /comments/:commentId/complete reopens with isCompleted false', async () => { + vi.mocked(runOperation).mockResolvedValue({ commentId: 'comment-id', resolved: false }) + vi.mocked(assetService.getComment).mockResolvedValue({ id: 'comment-id', + isCompleted: false, + } as any) // eslint-disable-line @typescript-eslint/no-explicit-any + + const app = new Hono().use('*', authMiddleware).route('/', fileRoute) + await app.request('/comments/comment-id/complete', { + method: 'POST', + headers: { 'Content-Type': 'application/json' }, + body: JSON.stringify({ isCompleted: false }), }) + + expect(runOperation).toHaveBeenCalledWith( + resolveCommentOp, + { userId: 'user1', via: 'api' }, + { commentId: 'comment-id', reopen: true }, + ) }) it('DELETE /comments/:commentId', async () => { @@ -625,41 +653,43 @@ describe('file api', () => { ) }) - it('PATCH /files/:fileId/metadata', async () => { - vi.mocked(metadataService.updateAssetMetadata).mockResolvedValue(undefined) - // Mock assetService.getAsset to return teamId for notification - vi.mocked(assetService.getAsset).mockResolvedValue({ - id: 'test-id', - project: { teamId: 'test-team' }, - } as any) // eslint-disable-line @typescript-eslint/no-explicit-any + it('PATCH /files/:fileId/metadata runs update_asset_metadata', async () => { + vi.mocked(runOperation).mockResolvedValue({ assetId: 'test-id', updatedKeys: ['status'] }) const app = new Hono().use('*', authMiddleware).route('/', fileRoute) const res = await app.request('/files/test-id/metadata', { method: 'PATCH', headers: { 'Content-Type': 'application/json' }, - body: JSON.stringify([{ key: 'status', value: 'approved' }]), + body: JSON.stringify([ + { key: 'status', value: 'approved' }, + { key: 'rating', value: 4 }, + ]), }) expect(res.status).toBe(200) + expect(runOperation).toHaveBeenCalledWith( + updateAssetMetadataOp, + { userId: 'user1', via: 'api' }, + { assetId: 'test-id', values: { status: 'approved', rating: 4 } }, + ) + }) - expect(authzService.hasPermission).toHaveBeenCalledWith({ - user: { id: 'user1', name: 'Test User' }, - permission: Permission.Edit, - type: ResourceType.Asset, - id: 'test-id', + it('PATCH /files/:fileId/metadata does nothing for an empty list', async () => { + vi.mocked(runOperation).mockClear() + const app = new Hono().use('*', authMiddleware).route('/', fileRoute) + const res = await app.request('/files/test-id/metadata', { + method: 'PATCH', + headers: { 'Content-Type': 'application/json' }, + body: JSON.stringify([]), }) - expect(notificationService.create).toHaveBeenCalledWith({ - type: 'metadata_field_updated_status', - teamId: 'test-team', - creatorId: 'user1', - assetId: 'test-id', - }) + expect(res.status).toBe(200) + expect(runOperation).not.toHaveBeenCalled() }) it('PATCH /files/:fileId/metadata rejects readonly fields with 422', async () => { - vi.mocked(metadataService.updateAssetMetadata).mockRejectedValue( - new Error('Field some-key is read-only'), + vi.mocked(runOperation).mockRejectedValue( + new HTTPException(422, { message: 'Field some-key is read-only' }), ) const app = new Hono().use('*', authMiddleware).route('/', fileRoute) diff --git a/packages/api/src/file.ts b/packages/api/src/file.ts index e9d7d4ad..67e0da48 100644 --- a/packages/api/src/file.ts +++ b/packages/api/src/file.ts @@ -1,12 +1,16 @@ import { zValidator } from '@hono/zod-validator' import { assetService } from '@shumai/core/src/asset/asset' import { authzService, Permission, ResourceType } from '@shumai/core/src/authz/authz' -import { metadataService } from '@shumai/core/src/metadata/metadata' -import { notificationService } from '@shumai/core/src/notification/notification' +import { commentService } from '@shumai/core/src/comment/comment' import { s3Service } from '@shumai/core/src/s3/s3' import type { Prisma } from '@shumai/db' import { auditLogService } from '@shumai/core/src/auditLog/auditLog' -import { renameAssetOp, runOperation } from '@shumai/core/src/operations' +import { + renameAssetOp, + resolveCommentOp, + runOperation, + updateAssetMetadataOp, +} from '@shumai/core/src/operations' import { createCommentRequestSchema, deleteFilesRequestSchema, @@ -26,6 +30,7 @@ import { import { transcodeService, buildContentDisposition } from '@shumai/core' import fs from 'fs' import { Hono } from 'hono' +import { HTTPException } from 'hono/http-exception' import os from 'os' import path from 'path' import { ulid } from 'ulid' @@ -106,37 +111,23 @@ const route = new Hono<{ Variables: { user: User } }>() '/files/:fileId/metadata', zValidator('json', z.array(updateAssetMetadataRequestSchema)), async (c) => { - const fileId = c.req.param('fileId') - const user = c.get('user') const req = c.req.valid('json') - - await authzService.hasPermission({ - user, - permission: Permission.Edit, - type: ResourceType.Asset, - id: fileId, - }) - + if (req.length === 0) return c.json('') try { - await metadataService.updateAssetMetadata(fileId, req) + await runOperation( + updateAssetMetadataOp, + { userId: c.get('user').id, via: 'api' }, + { + assetId: c.req.param('fileId'), + values: Object.fromEntries(req.map((m) => [m.key, m.value])), + }, + ) } catch (err) { - if (err instanceof Error && err.message.includes('is read-only')) { + if (err instanceof HTTPException && err.status === 422) { return c.json({ error: err.message }, 422) } throw err } - - const hasStatus = req.some((m) => m.key === 'status') - if (hasStatus) { - const context = await assetService.getAssetContext(fileId) - notificationService.create({ - type: 'metadata_field_updated_status', - teamId: context.teamId, - creatorId: user.id, - assetId: fileId, - }) - } - return c.json('') }, ) @@ -155,7 +146,9 @@ const route = new Hono<{ Variables: { user: User } }>() id: fileId, }) - const comment = await assetService.createComment({ + // The web app can attach markup and files, which the create_comment Operation doesn't + // expose; both post through the same service, so notifications are the same. + const comment = await commentService.postComment({ assetId: fileId, userId: user.id, replyToId: req.replyToId, @@ -165,27 +158,7 @@ const route = new Hono<{ Variables: { user: User } }>() attachmentIds: req.attachmentIds, }) - const notifType = req.replyToId ? 'reply_created' : 'comment_created' - const context = await assetService.getAssetContext(fileId) - - let targetUserId: string | undefined - if (req.replyToId) { - const parentComment = await assetService.getComment(req.replyToId).catch(() => null) - if (parentComment?.creator?.id) { - targetUserId = parentComment.creator.id - } - } - - notificationService.create({ - type: notifType, - teamId: context.teamId, - creatorId: user.id, - assetId: fileId, - userId: targetUserId, - commentMessage: req.message, - }) - await auditLogService.logAction({ action: AuditAction.comment_create, teamId: context.teamId, @@ -282,29 +255,13 @@ const route = new Hono<{ Variables: { user: User } }>() const user = c.get('user') const req = c.req.valid('json') - await authzService.hasPermission({ - user, - permission: Permission.Read, - type: ResourceType.Comment, - id: commentId, - }) - - const commentData = await assetService.getComment(commentId).catch(() => null) - - const updated = await assetService.completeComment(commentId, req.isCompleted, user.id) - - if (commentData?.assetId) { - const context = await assetService.getAssetContext(commentData.assetId) - await auditLogService.logAction({ - action: AuditAction.comment_complete, - teamId: context.teamId, - userId: user.id, - projectId: context.projectId, - itemId: commentId, - }) - } - - return c.json(updated) + await runOperation( + resolveCommentOp, + { userId: user.id, via: 'api' }, + { commentId, reopen: !req.isCompleted }, + ) + // The web app shows the whole comment, so respond with it rather than the summary. + return c.json(await assetService.getComment(commentId, user.id)) }, ) .delete('/comments/:commentId', async (c) => { diff --git a/packages/api/src/folder.test.ts b/packages/api/src/folder.test.ts index 1ead8fa5..c10d15ce 100644 --- a/packages/api/src/folder.test.ts +++ b/packages/api/src/folder.test.ts @@ -6,7 +6,12 @@ import { searchService } from '@shumai/core/src/search/search' import { authzService, ResourceType, Permission } from '@shumai/core/src/authz/authz' import { authMiddleware } from './middleware/auth' import { HTTPException } from 'hono/http-exception' -import { createFolderOp, renameAssetOp, runOperation } from '@shumai/core/src/operations' +import { + createFolderOp, + getFolderInstructionsOp, + renameAssetOp, + runOperation, +} from '@shumai/core/src/operations' import { auditLogService } from '@shumai/core/src/auditLog/auditLog' @@ -357,23 +362,22 @@ describe('folder api', () => { }) }) - it('GET /folders/:folderId/agentsmd', async () => { - vi.spyOn(assetService, 'getAgentsMd').mockResolvedValue('# Folder Guidelines') + it('GET /folders/:folderId/agentsmd runs get_folder_instructions', async () => { + vi.mocked(runOperation).mockResolvedValue({ + folderId: 'test-id', + content: '# Folder Guidelines', + }) const app = new Hono().use('*', authMiddleware).route('/', folderRoute) const res = await app.request('/folders/test-id/agentsmd') expect(res.status).toBe(200) - const json = await res.json() - expect(json.content).toBe('# Folder Guidelines') - - expect(authzService.hasPermission).toHaveBeenCalledWith({ - user: { id: 'user1', name: 'Test User' }, - permission: Permission.Read, - type: ResourceType.Asset, - id: 'test-id', - }) - expect(assetService.getAgentsMd).toHaveBeenCalledWith('test-id') + expect(await res.json()).toEqual({ content: '# Folder Guidelines' }) + expect(runOperation).toHaveBeenCalledWith( + getFolderInstructionsOp, + { userId: 'user1', via: 'api' }, + { folderId: 'test-id' }, + ) }) it('PATCH /folders/:folderId/agentsmd', async () => { diff --git a/packages/api/src/folder.ts b/packages/api/src/folder.ts index 9e3dcb32..a969e997 100644 --- a/packages/api/src/folder.ts +++ b/packages/api/src/folder.ts @@ -14,7 +14,12 @@ import { listChildrenRequestSchema, updateAssetOrderRequestSchema, AuditAction } import { searchRequestSchema } from '@shumai/dtos' import type { Prisma } from '@shumai/db' import { auditLogService } from '@shumai/core/src/auditLog/auditLog' -import { createFolderOp, renameAssetOp, runOperation } from '@shumai/core/src/operations' +import { + createFolderOp, + getFolderInstructionsOp, + renameAssetOp, + runOperation, +} from '@shumai/core/src/operations' type User = Prisma.UserGetPayload> @@ -150,17 +155,11 @@ const route = new Hono<{ Variables: { user: User } }>() return c.json(result) }) .get('/folders/:folderId/agentsmd', async (c) => { - const folderId = c.req.param('folderId') - const user = c.get('user') - - await authzService.hasPermission({ - user, - permission: Permission.Read, - type: ResourceType.Asset, - id: folderId, - }) - - const content = await assetService.getAgentsMd(folderId) + const { content } = await runOperation( + getFolderInstructionsOp, + { userId: c.get('user').id, via: 'api' }, + { folderId: c.req.param('folderId') }, + ) return c.json({ content }) }) .patch( diff --git a/packages/api/src/index.ts b/packages/api/src/index.ts index f81bffb2..581c05e5 100644 --- a/packages/api/src/index.ts +++ b/packages/api/src/index.ts @@ -42,11 +42,9 @@ const apiRoute = new Hono<{ Variables: { user: User } }>() .route('/', localUploadRoute) .route('/', mcpOauthCallbackRoute) - // Programmatic endpoints: API token required, session cookies not accepted + // Programmatic endpoint for the CLI: API token required, session cookies not accepted .use('/ops/*', requireApiTokenMiddleware) - .use('/mcp', requireApiTokenMiddleware) .route('/', operationsRoute) - .route('/', mcpServerRoute) // Selected routes supporting API token authentication .use('/projects', tokenAuthMiddleware) @@ -82,6 +80,13 @@ const apiRoute = new Hono<{ Variables: { user: User } }>() .route('/', kanbanRoute) .route('/', mediaGenerationRoute) +// Shumai's MCP server lives at the root (`/mcp`), next to the API rather than inside it, so +// it can also be served from a dedicated host (e.g. `https://mcp.example.com/mcp`). It takes +// API tokens only. The `/api/mcp/servers` routes are a separate feature: external MCP servers +// that Shumai's own agent connects to. +app.use('/mcp', requireApiTokenMiddleware) +app.route('/', mcpServerRoute) + app.route('/files', s3Route) // eslint-disable-next-line @typescript-eslint/no-unused-vars diff --git a/packages/api/src/mcp-server.integration.test.ts b/packages/api/src/mcp-server.integration.test.ts index 97d97b51..4c2af599 100644 --- a/packages/api/src/mcp-server.integration.test.ts +++ b/packages/api/src/mcp-server.integration.test.ts @@ -11,7 +11,7 @@ import { apiTokenService } from '@shumai/core/src/user/api-token' import app from './index' /** - * End-to-end through the composed API app: API token auth → /api/mcp and /api/ops → + * End-to-end through the composed API app: API token auth → /mcp and /api/ops → * runOperation → core services → database. Nothing is mocked. */ describe('MCP server and /api/ops (integration)', () => { @@ -49,7 +49,7 @@ describe('MCP server and /api/ops (integration)', () => { }) async function connect(token: string): Promise { - const transport = new StreamableHTTPClientTransport(new URL('http://shumai.test/api/mcp'), { + const transport = new StreamableHTTPClientTransport(new URL('http://shumai.test/mcp'), { requestInit: { headers: { Authorization: `Bearer ${token}` } }, fetch: async (input, init) => app.request(String(input), init), }) @@ -110,11 +110,11 @@ describe('MCP server and /api/ops (integration)', () => { Accept: 'application/json, text/event-stream', } - const missing = await app.request('/api/mcp', { method: 'POST', headers, body: initialize }) + const missing = await app.request('/mcp', { method: 'POST', headers, body: initialize }) expect(missing.status).toBe(401) expect(missing.headers.get('WWW-Authenticate')).toContain('Bearer') - const invalid = await app.request('/api/mcp', { + const invalid = await app.request('/mcp', { method: 'POST', headers: { ...headers, Authorization: 'Bearer shumai_invalid' }, body: initialize, @@ -163,6 +163,21 @@ describe('MCP server and /api/ops (integration)', () => { expect(res.status).toBe(401) }) + it('no longer serves the MCP server under /api', async () => { + const res = await app.request('/api/mcp', { + method: 'POST', + headers: { + Authorization: `Bearer ${ownerToken}`, + 'Content-Type': 'application/json', + Accept: 'application/json, text/event-stream', + }, + body: JSON.stringify({ jsonrpc: '2.0', id: 1, method: 'tools/list' }), + }) + // It falls through to the session-only API routes instead of answering as MCP. + expect(res.status).toBe(401) + expect(await res.text()).not.toContain('jsonrpc') + }) + describe('read_asset', () => { const bucket = 'shumai-test-mcp-read' const originalBucket = process.env.S3_BUCKET @@ -303,5 +318,53 @@ describe('MCP server and /api/ops (integration)', () => { expect(result.isError).toBe(true) }) + + it('lets an MCP client upload a file: create_file, PUT the bytes, complete_upload', async () => { + const client = await connect(ownerToken) + + const started = await client.callTool({ + name: 'create_file', + arguments: { parent: rootFolderId, name: 'upload.png' }, + }) + expect(started.isError).toBeFalsy() + const { uploadId, uploadUrl, method } = started.structuredContent as { + uploadId: string + uploadUrl: string + method: string + key?: string + } + expect(method).toBe('PUT') + expect(started.structuredContent).not.toHaveProperty('key') + + // Upload the bytes the way an agent would with curl, to the API's local storage + const link = new URL(uploadUrl) + const put = await app.request(link.pathname + link.search, { + method: 'PUT', + headers: { 'Content-Type': 'image/png', 'Content-Length': String(png.length) }, + body: png, + }) + expect(put.status).toBe(200) + + const completed = await client.callTool({ name: 'complete_upload', arguments: { uploadId } }) + expect(completed.isError).toBeFalsy() + const file = completed.structuredContent as { id: string; name: string; size: number } + expect(file).toMatchObject({ name: 'upload.png', size: png.length }) + + const row = await prisma.asset.findUniqueOrThrow({ where: { id: file.id } }) + expect(row).toMatchObject({ parentId: rootFolderId, creatorId: owner.id }) + const audit = await prisma.auditLog.findFirstOrThrow({ + where: { action: 'file_create', itemId: file.id }, + }) + expect(audit).toMatchObject({ userId: owner.id, teamId, projectId, via: 'mcp' }) + }) + + it('does not let a reviewer start an upload over MCP', async () => { + const client = await connect(reviewerToken) + const result = await client.callTool({ + name: 'create_file', + arguments: { parent: rootFolderId, name: 'nope.png' }, + }) + expect(result.isError).toBe(true) + }) }) }) diff --git a/packages/api/src/mcp-server.test.ts b/packages/api/src/mcp-server.test.ts index 324b51db..78da987d 100644 --- a/packages/api/src/mcp-server.test.ts +++ b/packages/api/src/mcp-server.test.ts @@ -53,15 +53,29 @@ describe('MCP server', () => { const { tools } = await client.listTools() expect(tools.map((t) => t.name).sort()).toEqual([ + 'complete_upload', + 'copy_assets', + 'create_comment', + 'create_file', 'create_folder', + 'create_version', + 'create_version_stack', 'delete_asset', 'download_asset', 'get_asset_render', + 'get_folder_instructions', 'list_assets', + 'list_comments', + 'list_metadata_fields', 'list_projects', + 'list_versions', 'move_assets', 'read_asset', + 'remove_version', 'rename_asset', + 'resolve_comment', + 'search_assets', + 'update_asset_metadata', ]) const createFolder = tools.find((t) => t.name === 'create_folder')! diff --git a/packages/api/src/mcp-server.ts b/packages/api/src/mcp-server.ts index f9045fe8..3ebad03b 100644 --- a/packages/api/src/mcp-server.ts +++ b/packages/api/src/mcp-server.ts @@ -15,10 +15,15 @@ export const MCP_SERVER_VERSION = '1.0.0' export const MCP_SERVER_INSTRUCTIONS = [ 'Shumai is a media asset workspace organized as teams > projects > folders > files.', 'Start with list_projects to find a project and its rootFolderId, then pass folder IDs as', - '`parent` to list_assets and create_folder. list_assets is paginated: when', - 'pageInfo.hasNextPage is true, call it again with after = pageInfo.endCursor.', + '`parent` to list_assets, search_assets, and create_folder. List and search tools are', + 'paginated: when pageInfo.hasNextPage is true, call them again with after = pageInfo.endCursor.', 'Use read_asset to look at a file (image, video frames, PDF pages, 3D views, or text);', 'if it returns status "pending", call get_asset_render with its taskId.', + 'Review feedback lives in comments: list_comments, create_comment, and resolve_comment.', + 'Files carry metadata (status, rating, custom fields): list_metadata_fields gives the keys for', + 'update_asset_metadata. Before adding files to a folder, check get_folder_instructions.', + 'To upload, call create_file (or create_version for a new version of a file), PUT the bytes', + 'to the returned uploadUrl, then call complete_upload with the uploadId.', ].join(' ') /** @@ -126,7 +131,7 @@ const mcpHandler = createMcpHandler(({ authInfo }) => { return buildMcpServer(userId) }) -/** Shumai's MCP server (Streamable HTTP). Mounted at `/api/mcp` behind API token auth. */ +/** Shumai's MCP server (Streamable HTTP). Mounted at `/mcp` behind API token auth. */ const route = new Hono<{ Variables: { user: User } }>().all('/mcp', (c) => { const user = c.get('user') return mcpHandler.fetch(c.req.raw, { diff --git a/packages/api/src/project.test.ts b/packages/api/src/project.test.ts index 21725bdb..601226e7 100644 --- a/packages/api/src/project.test.ts +++ b/packages/api/src/project.test.ts @@ -4,9 +4,8 @@ import projectRoute from './project' import { authzService, Permission, ResourceType } from '@shumai/core/src/authz/authz' import { projectService } from '@shumai/core/src/project/project' import { assetService } from '@shumai/core/src/asset/asset' -import { auditLogService } from '@shumai/core/src/auditLog/auditLog' import type { ProjectInfo } from '@shumai/dtos' -import { moveAssetsOp, runOperation } from '@shumai/core/src/operations' +import { copyAssetsOp, moveAssetsOp, runOperation } from '@shumai/core/src/operations' vi.mock('./middleware/auth', () => ({ authMiddleware: async ( @@ -209,9 +208,11 @@ describe('project api', () => { ) }) - it('POST /projects/:projectId/copy', async () => { - vi.mocked(projectService.getProjectTeam).mockResolvedValue('t1') - vi.mocked(assetService.copyAssets).mockResolvedValue(undefined) + it('POST /projects/:projectId/copy runs copy_assets', async () => { + vi.mocked(runOperation).mockResolvedValue({ + copiedAssetIds: ['copy_1'], + newParentId: 'new_parent_id', + }) const res = await app.request('/projects/p/copy', { method: 'POST', @@ -223,19 +224,11 @@ describe('project api', () => { }) expect(res.status).toBe(204) - expect(assetService.copyAssets).toHaveBeenCalledWith({ - newParentId: 'new_parent_id', - assetIds: ['asset_1'], - withComments: false, - creatorId: 'user1', - }) - expect(auditLogService.logAction).toHaveBeenCalledWith({ - action: 'asset_copy', - teamId: 't1', - userId: 'user1', - projectId: 'p', - itemId: 'asset_1', - }) + expect(runOperation).toHaveBeenCalledWith( + copyAssetsOp, + { userId: 'user1', via: 'api' }, + { assetIds: ['asset_1'], newParentId: 'new_parent_id', withComments: false }, + ) }) it('POST /projects/:projectId/empty-trash', async () => { diff --git a/packages/api/src/project.ts b/packages/api/src/project.ts index bb758b3b..0a115912 100644 --- a/packages/api/src/project.ts +++ b/packages/api/src/project.ts @@ -18,7 +18,7 @@ import { import { listMembersQuerySchema, AuditAction } from '@shumai/dtos' import type { Prisma } from '@shumai/db' import { auditLogService } from '@shumai/core/src/auditLog/auditLog' -import { moveAssetsOp, runOperation } from '@shumai/core/src/operations' +import { copyAssetsOp, moveAssetsOp, runOperation } from '@shumai/core/src/operations' type User = Prisma.UserGetPayload> @@ -303,46 +303,13 @@ const route = new Hono<{ Variables: { user: User } }>() }, ) .post('/projects/:projectId/copy', zValidator('json', copyAssetsRequestSchema), async (c) => { - const projectId = c.req.param('projectId') - const user = c.get('user') const req = c.req.valid('json') - - // Check Edit permission on target folder/project - await authzService.hasPermission({ - user, - permission: Permission.Edit, - type: ResourceType.Asset, - id: req.newParentId, - }) - - // Check Read permission on all source assets - for (const assetId of req.assetIds) { - await authzService.hasPermission({ - user, - permission: Permission.Read, - type: ResourceType.Asset, - id: assetId, - }) - } - - await assetService.copyAssets({ - ...req, - creatorId: user.id, - }) - - const teamId = await projectService.getProjectTeam(projectId).catch(() => null) - if (teamId) { - for (const assetId of req.assetIds) { - await auditLogService.logAction({ - action: AuditAction.asset_copy, - teamId, - userId: user.id, - projectId, - itemId: assetId, - }) - } - } - + // Team/project for authorization and audit come from the assets themselves, not the path. + await runOperation( + copyAssetsOp, + { userId: c.get('user').id, via: 'api' }, + { assetIds: req.assetIds, newParentId: req.newParentId, withComments: req.withComments }, + ) return c.body(null, 204) }) .patch( diff --git a/packages/api/src/versionStack.test.ts b/packages/api/src/versionStack.test.ts index 7a95fa18..6095c46a 100644 --- a/packages/api/src/versionStack.test.ts +++ b/packages/api/src/versionStack.test.ts @@ -5,6 +5,12 @@ import { authMiddleware } from './middleware/auth' import { versionStackService } from '@shumai/core/src/versionStack/versionStack' import { assetService } from '@shumai/core/src/asset/asset' import { authzService, ResourceType, Permission } from '@shumai/core/src/authz/authz' +import { createVersionStackOp, removeVersionOp, runOperation } from '@shumai/core/src/operations' + +vi.mock('@shumai/core/src/operations', async (importOriginal) => ({ + ...(await importOriginal()), + runOperation: vi.fn(), +})) vi.mock('@shumai/core/src/authz/authz', () => ({ authzService: { @@ -50,11 +56,16 @@ describe('versionStack api', () => { }) describe('POST /projects/:projectID/version_stacks', () => { - it('should create a version stack and return asset info', async () => { - const mockStack = { id: 'stack1' } + it('runs create_version_stack and returns the stack asset info', async () => { const mockAssetInfo = { id: 'stack1', type: 'version_stack', name: 'v1' } - mockCreateVersionStack.mockResolvedValue(mockStack) + vi.mocked(runOperation).mockResolvedValue({ + id: 'stack1', + name: 'v1', + type: 'version_stack', + size: 0, + projectId: 'p1', + }) mockGetAsset.mockResolvedValue(mockAssetInfo) const app = new Hono().use('*', authMiddleware).route('/', versionStackRoute) @@ -69,18 +80,12 @@ describe('versionStack api', () => { const data = await res.json() expect(data).toEqual(mockAssetInfo) - expect(authzService.hasPermission).toHaveBeenCalledWith( - expect.objectContaining({ - type: ResourceType.Project, - id: 'p1', - permission: Permission.Edit, - }), + expect(runOperation).toHaveBeenCalledWith( + createVersionStackOp, + { userId: 'user1', via: 'api' }, + { fileIds: ['f1', 'f2'] }, ) - expect(mockCreateVersionStack).toHaveBeenCalledWith({ - projectId: 'p1', - creatorId: 'user1', - fileIds: ['f1', 'f2'], - }) + expect(mockCreateVersionStack).not.toHaveBeenCalled() expect(mockGetAsset).toHaveBeenCalledWith({ assetId: 'stack1' }) }) }) @@ -150,8 +155,8 @@ describe('versionStack api', () => { }) describe('DELETE /version_stacks/:stackId/versions/:versionId', () => { - it('should remove version from stack and return 200', async () => { - mockRemoveVersionFromStack.mockResolvedValue() + it('runs remove_version and returns 200', async () => { + vi.mocked(runOperation).mockResolvedValue({ versionId: 'v1', stackId: 'stack1' }) const app = new Hono().use('*', authMiddleware).route('/', versionStackRoute) @@ -160,18 +165,12 @@ describe('versionStack api', () => { }) expect(res.status).toBe(200) - - expect(authzService.hasPermission).toHaveBeenCalledWith( - expect.objectContaining({ - type: ResourceType.Asset, - id: 'stack1', - permission: Permission.Edit, - }), + expect(runOperation).toHaveBeenCalledWith( + removeVersionOp, + { userId: 'user1', via: 'api' }, + { versionId: 'v1' }, ) - expect(mockRemoveVersionFromStack).toHaveBeenCalledWith({ - stackId: 'stack1', - fileId: 'v1', - }) + expect(mockRemoveVersionFromStack).not.toHaveBeenCalled() }) }) }) diff --git a/packages/api/src/versionStack.ts b/packages/api/src/versionStack.ts index f433945a..958424d5 100644 --- a/packages/api/src/versionStack.ts +++ b/packages/api/src/versionStack.ts @@ -3,6 +3,7 @@ import { zValidator } from '@hono/zod-validator' import { versionStackService } from '@shumai/core/src/versionStack/versionStack' import { assetService } from '@shumai/core/src/asset/asset' import { authzService, Permission, ResourceType } from '@shumai/core/src/authz/authz' +import { createVersionStackOp, removeVersionOp, runOperation } from '@shumai/core/src/operations' import { createVersionStackRequestSchema, changeStackFileVersionRequestSchema } from '@shumai/dtos' import type { Prisma } from '@shumai/db' @@ -15,26 +16,14 @@ const route = app '/projects/:projectId/version_stacks', zValidator('json', createVersionStackRequestSchema), async (c) => { - const projectId = c.req.param('projectId') - const user = c.get('user') const req = c.req.valid('json') - - await authzService.hasPermission({ - user, - permission: Permission.Edit, - type: ResourceType.Project, - id: projectId, - }) - - const stack = await versionStackService.createVersionStack({ - fileIds: req.fileIds, - projectId, - creatorId: user.id, - }) - - const stackInfo = await assetService.getAsset({ assetId: stack.id }) - - return c.json(stackInfo) + // Authorization and the stack's project come from the files, not the path. + const stack = await runOperation( + createVersionStackOp, + { userId: c.get('user').id, via: 'api' }, + { fileIds: req.fileIds }, + ) + return c.json(await assetService.getAsset({ assetId: stack.id })) }, ) .post( @@ -76,22 +65,12 @@ const route = app return c.json(versions) }) .delete('/version_stacks/:stackId/versions/:versionId', async (c) => { - const stackId = c.req.param('stackId') - const versionId = c.req.param('versionId') - const user = c.get('user') - - await authzService.hasPermission({ - user, - permission: Permission.Edit, - type: ResourceType.Asset, - id: stackId, - }) - - await versionStackService.removeVersionFromStack({ - stackId, - fileId: versionId, - }) - + // The stack is the version's parent; the path's stackId is not needed. + await runOperation( + removeVersionOp, + { userId: c.get('user').id, via: 'api' }, + { versionId: c.req.param('versionId') }, + ) return new Response(null, { status: 200 }) }) diff --git a/packages/core/src/asset/asset.ts b/packages/core/src/asset/asset.ts index b849ca0f..d65693b5 100644 --- a/packages/core/src/asset/asset.ts +++ b/packages/core/src/asset/asset.ts @@ -397,8 +397,9 @@ export class AssetService { } } - async copyAssets(req: CopyAssetsRequest): Promise { - await this.prismaClient.$transaction(async (tx) => { + /** Copies assets into a folder. Returns the IDs of the copies, in the order of `assetIds`. */ + async copyAssets(req: CopyAssetsRequest): Promise { + return this.prismaClient.$transaction(async (tx) => { const newParent = await tx.asset.findUnique({ where: { id: req.newParentId }, include: { project: { include: { team: true } } }, @@ -448,6 +449,7 @@ export class AssetService { let firstSortIndex = firstFile?.sortIndex || null let totalSize = 0 + const copiedIds: string[] = new Array(req.assetIds.length) for (let i = req.assetIds.length - 1; i >= 0; i--) { const assetId = req.assetIds[i] const asset = assetsToCopy.find((a) => a.id === assetId)! @@ -461,6 +463,7 @@ export class AssetService { req.creatorId, req.withComments, ) + copiedIds[i] = copiedAsset.id totalSize += Number(copiedAsset.sizeByte) firstSortIndex = newSortIndex } @@ -472,6 +475,7 @@ export class AssetService { }, }) await this.updateAncestorsSize(tx, newParent.id, totalSize) + return copiedIds }) } @@ -1144,12 +1148,17 @@ export class AssetService { * Lightweight lookup of an asset's type and team/project, without building a full AssetInfo * (no presigned URLs). Use it to capture context before a mutation such as a delete. */ - async getAssetMeta( - assetId: string, - ): Promise<{ id: string; name: string; type: AssetType; teamId: string; projectId?: string }> { + async getAssetMeta(assetId: string): Promise<{ + id: string + name: string + type: AssetType + parentId: string | null + teamId: string + projectId?: string + }> { const asset = await this.prismaClient.asset.findUnique({ where: { id: assetId }, - select: { id: true, name: true, type: true }, + select: { id: true, name: true, type: true, parentId: true }, }) if (!asset) { throw new HTTPException(404, { message: 'Asset not found' }) @@ -1158,6 +1167,20 @@ export class AssetService { return { ...asset, teamId, projectId } } + /** + * The asset whose file is stored under `key`, with its creator. Used to make finishing an + * upload idempotent: the same uploaded object is never attached to two assets. + */ + async findAssetByStorageKey( + key: string, + ): Promise<{ id: string; creatorId: string | null } | null> { + return this.prismaClient.asset.findFirst({ + where: { storageKey: { key } }, + select: { id: true, creatorId: true }, + orderBy: { id: 'asc' }, + }) + } + async resolveTargetAssetId(assetId: string): Promise { const asset = await this.prismaClient.asset.findUnique({ where: { id: assetId }, @@ -1734,7 +1757,16 @@ export class AssetService { } } - async createComment(req: CreateCommentRequest): Promise { + /** + * Creates a comment or reply. Mentions of agents (`<@agentId>`) start a chat with them + * unless `triggerAgents` is false, which keeps an agent's own comments from starting + * further agent runs. + */ + async createComment( + req: CreateCommentRequest, + options: { triggerAgents?: boolean } = {}, + ): Promise { + const triggerAgents = options.triggerAgents ?? true let commentId = '' const resolvedAssetId = await this.resolveLatestVersionId(req.assetId) @@ -1783,6 +1815,8 @@ export class AssetService { } } + if (!triggerAgents) return + // Parse bot mentions const botMentionMatches = [...req.message.matchAll(/<@([^>]+)>/g)] const mentionedAgentIds = new Set(botMentionMatches.map((match) => match[1])) @@ -2083,7 +2117,10 @@ export class AssetService { orderBy: { id: 'asc' }, }) }, - async () => this.prismaClient.assetComment.count({ where: { assetId, replyToId: null } }), + async () => + this.prismaClient.assetComment.count({ + where: { assetId: resolvedAssetId, replyToId: null }, + }), params, ) diff --git a/packages/core/src/comment/comment.ts b/packages/core/src/comment/comment.ts new file mode 100644 index 00000000..fe0eb7b6 --- /dev/null +++ b/packages/core/src/comment/comment.ts @@ -0,0 +1,62 @@ +import type { CommentInfo } from '@shumai/dtos' +import { assetService } from '@shumai/core/src/asset/asset' +import { notificationService } from '@shumai/core/src/notification/notification' + +export interface PostCommentParams { + assetId: string + userId: string + message: string + replyToId?: string + /** Markup drawn on the frame or page (web app only). */ + annotations?: unknown + /** Timecode in seconds (or the encoded viewing angle for 3D models). */ + second?: number + attachmentIds?: string[] + /** Whether mentions of agents start a chat with them (default true). */ + triggerAgents?: boolean +} + +export class CommentService { + /** + * Posts a comment or reply and notifies the people involved: team members for a new + * comment, the thread's author for a reply, and anyone mentioned. + */ + async postComment(params: PostCommentParams): Promise { + const comment = await assetService.createComment( + { + assetId: params.assetId, + userId: params.userId, + replyToId: params.replyToId, + message: params.message, + annotations: params.annotations, + second: params.second, + attachmentIds: params.attachmentIds ?? [], + }, + { triggerAgents: params.triggerAgents }, + ) + + const context = await assetService.getAssetContext(params.assetId) + + let targetUserId: string | undefined + if (params.replyToId) { + const parentComment = await assetService.getComment(params.replyToId).catch(() => null) + if (parentComment?.creator?.id) { + targetUserId = parentComment.creator.id + } + } + + // Delivery happens in the background; this only schedules it. + await notificationService.create({ + type: params.replyToId ? 'reply_created' : 'comment_created', + teamId: context.teamId, + creatorId: params.userId, + assetId: params.assetId, + userId: targetUserId, + commentMessage: params.message, + }) + + return comment + } +} + +export const commentService = new CommentService() diff --git a/packages/core/src/operations/asset/copy-assets.ts b/packages/core/src/operations/asset/copy-assets.ts new file mode 100644 index 00000000..e9d9cee7 --- /dev/null +++ b/packages/core/src/operations/asset/copy-assets.ts @@ -0,0 +1,35 @@ +import { copyAssets } from '@shumai/operations' +import { AuditAction } from '@shumai/dtos' +import { assetService } from '@shumai/core/src/asset/asset' +import { Permission, ResourceType } from '@shumai/core/src/authz/authz' +import { asBadRequest } from '../errors' +import { implementOperation } from '../implement' + +export const copyAssetsOp = implementOperation(copyAssets, { + authz: (input) => [ + { permission: Permission.Edit, type: ResourceType.Asset, id: input.newParentId }, + ...[...new Set(input.assetIds)].map((id) => ({ + permission: Permission.Read, + type: ResourceType.Asset, + id, + })), + ], + execute: async (input, ctx) => { + const copiedAssetIds = await asBadRequest(() => + assetService.copyAssets({ + assetIds: input.assetIds, + newParentId: input.newParentId, + withComments: input.withComments ?? false, + creatorId: ctx.userId, + }), + ) + return { copiedAssetIds, newParentId: input.newParentId } + }, + // One entry per source asset, recorded in the destination's team and project. + audit: (input) => + input.assetIds.map((assetId) => ({ + action: AuditAction.asset_copy, + itemId: assetId, + contextAssetId: input.newParentId, + })), +}) diff --git a/packages/core/src/operations/asset/get-folder-instructions.ts b/packages/core/src/operations/asset/get-folder-instructions.ts new file mode 100644 index 00000000..8e771dbe --- /dev/null +++ b/packages/core/src/operations/asset/get-folder-instructions.ts @@ -0,0 +1,13 @@ +import { getFolderInstructions } from '@shumai/operations' +import { assetService } from '@shumai/core/src/asset/asset' +import { Permission, ResourceType } from '@shumai/core/src/authz/authz' +import { asBadRequest } from '../errors' +import { implementOperation } from '../implement' + +export const getFolderInstructionsOp = implementOperation(getFolderInstructions, { + authz: (input) => [{ permission: Permission.Read, type: ResourceType.Asset, id: input.folderId }], + execute: async (input) => ({ + folderId: input.folderId, + content: await asBadRequest(() => assetService.getAgentsMd(input.folderId)), + }), +}) diff --git a/packages/core/src/operations/asset/search-assets.ts b/packages/core/src/operations/asset/search-assets.ts new file mode 100644 index 00000000..6dd954f7 --- /dev/null +++ b/packages/core/src/operations/asset/search-assets.ts @@ -0,0 +1,39 @@ +import { DEFAULT_PAGE_SIZE, searchAssets } from '@shumai/operations' +import { Permission, ResourceType } from '@shumai/core/src/authz/authz' +import { searchService } from '@shumai/core/src/search/search' +import { asBadRequest } from '../errors' +import { implementOperation } from '../implement' +import { toAssetSummary } from './to-asset-summary' + +export const searchAssetsOp = implementOperation(searchAssets, { + authz: (input) => [{ permission: Permission.Read, type: ResourceType.Asset, id: input.parent }], + execute: async (input) => { + const semantic = Boolean(input.query && input.semantic) + const conditions = (input.conditions ?? []).map((c) => ({ ...c, value: c.value ?? null })) + // Name search is a `name contains` condition (always combined with AND); only + // semantic search uses the query text itself. + if (input.query && !semantic) { + conditions.push({ field: 'name', operator: 'contains', value: input.query }) + } + const result = await asBadRequest(() => + searchService.search(input.parent, { + query: semantic ? input.query : undefined, + isSemantic: semantic, + assetType: input.type, + recursively: input.recursive ?? true, + conditions, + operator: input.matchAny ? 'OR' : 'AND', + first: input.first ?? DEFAULT_PAGE_SIZE, + after: input.after, + }), + ) + return { + data: result.data.map(toAssetSummary), + pageInfo: { + hasNextPage: Boolean(result.pageInfo.cursor), + endCursor: result.pageInfo.cursor ?? null, + }, + total: result.pageInfo.total ?? result.data.length, + } + }, +}) diff --git a/packages/core/src/operations/collaboration.test.ts b/packages/core/src/operations/collaboration.test.ts new file mode 100644 index 00000000..f39c1344 --- /dev/null +++ b/packages/core/src/operations/collaboration.test.ts @@ -0,0 +1,545 @@ +import { beforeEach, describe, expect, it } from 'vitest' +import { prisma, type User } from '@shumai/db' +import { setupTestDbHooks } from '@shumai/db/test' +import { AuditAction } from '@shumai/dtos' +import { assetService } from '@shumai/core/src/asset/asset' +import { metadataService } from '@shumai/core/src/metadata/metadata' +import { projectService } from '@shumai/core/src/project/project' +import { + copyAssetsOp, + createCommentOp, + createFolderOp, + createVersionStackOp, + getFolderInstructionsOp, + listCommentsOp, + listMetadataFieldsOp, + listVersionsOp, + removeVersionOp, + resolveCommentOp, + searchAssetsOp, + updateAssetMetadataOp, +} from './index' +import { runOperation } from './run' +import type { OperationContext } from './context' + +/** + * Real-database tests for the search, copy, folder instruction, comment, metadata, and version + * Operations: success, permission denial without side effects, and audit entries. + */ +describe('collaboration Operations', () => { + setupTestDbHooks() + + let owner: User + let reviewer: User + let outsider: User + let teamId: string + let projectId: string + let rootFolderId: string + + const as = (user: User, via: OperationContext['via'] = 'mcp', agentId?: string) => ({ + userId: user.id, + via, + agentId, + }) + + /** A file without a preview type, so creating it doesn't start transcoding. */ + async function createFile(name: string, parentId = rootFolderId) { + const asset = await assetService.createFile({ + parentId, + name, + key: `files/test/${name}-${Math.random().toString(36).slice(2)}`, + sizeByte: 10, + contentType: 'application/octet-stream', + creatorId: owner.id, + }) + return asset.id + } + + async function auditRows(action: AuditAction) { + return prisma.auditLog.findMany({ where: { action, teamId }, orderBy: { id: 'asc' } }) + } + + beforeEach(async () => { + owner = await prisma.user.create({ + data: { name: 'Owner', email: 'collab-owner@test.com', password: 'pw' }, + }) + reviewer = await prisma.user.create({ + data: { name: 'Reviewer', email: 'collab-reviewer@test.com', password: 'pw' }, + }) + outsider = await prisma.user.create({ + data: { name: 'Outsider', email: 'collab-outsider@test.com', password: 'pw' }, + }) + const team = await prisma.team.create({ data: { name: 'Collab Team' } }) + teamId = team.id + await prisma.teamMember.create({ data: { teamId, userId: owner.id, role: 'owner' } }) + await prisma.teamMember.create({ data: { teamId, userId: reviewer.id, role: 'reviewer' } }) + const project = await projectService.createProject(owner, { teamId, name: 'Collab Project' }) + projectId = project.id + rootFolderId = project.rootFolder! + }) + + describe('search_assets', () => { + it('finds files by name in subfolders and pages through results', async () => { + const sub = await runOperation(createFolderOp, as(owner), { + parent: rootFolderId, + name: 'shots', + }) + await createFile('sunset-a.bin', sub.id) + await createFile('sunset-b.bin', rootFolderId) + await createFile('night.bin', rootFolderId) + + const page1 = await runOperation(searchAssetsOp, as(reviewer), { + parent: rootFolderId, + query: 'sunset', + first: 1, + }) + expect(page1.total).toBe(2) + expect(page1.data).toHaveLength(1) + expect(page1.pageInfo.hasNextPage).toBe(true) + + const page2 = await runOperation(searchAssetsOp, as(reviewer), { + parent: rootFolderId, + query: 'sunset', + first: 1, + after: page1.pageInfo.endCursor!, + }) + const names = [...page1.data, ...page2.data].map((a) => a.name).sort() + expect(names).toEqual(['sunset-a.bin', 'sunset-b.bin']) + }) + + it('searches only the folder itself when recursive is false', async () => { + const sub = await runOperation(createFolderOp, as(owner), { + parent: rootFolderId, + name: 'shots', + }) + await createFile('sunset-a.bin', sub.id) + + const result = await runOperation(searchAssetsOp, as(owner), { + parent: rootFolderId, + query: 'sunset', + recursive: false, + }) + expect(result.data).toEqual([]) + }) + + it('filters by metadata conditions', async () => { + const field = await metadataService.createProjectField(projectId, { + config: { name: 'Approved', type: 'toggle' }, + description: '', + }) + const approved = await createFile('approved.bin') + await createFile('pending.bin') + await metadataService.updateAssetMetadata(approved, [{ key: field.key, value: true }]) + + const result = await runOperation(searchAssetsOp, as(owner), { + parent: rootFolderId, + conditions: [{ field: field.key, operator: 'eq', value: true }], + }) + expect(result.data.map((a) => a.id)).toEqual([approved]) + }) + + it('reports an unsupported operator for a field as a bad request', async () => { + await expect( + runOperation(searchAssetsOp, as(owner), { + parent: rootFolderId, + conditions: [{ field: 'name', operator: 'gt', value: 'a' }], + }), + ).rejects.toMatchObject({ status: 400 }) + }) + + it('rejects a non-member', async () => { + await expect( + runOperation(searchAssetsOp, as(outsider), { parent: rootFolderId, query: 'x' }), + ).rejects.toMatchObject({ status: 403 }) + }) + }) + + describe('copy_assets', () => { + it('copies assets, returns the copies in order, and audits each source', async () => { + const dest = await runOperation(createFolderOp, as(owner), { + parent: rootFolderId, + name: 'dest', + }) + const a = await createFile('a.bin') + const b = await createFile('b.bin') + + const result = await runOperation(copyAssetsOp, as(owner), { + assetIds: [a, b], + newParentId: dest.id, + }) + + expect(result.newParentId).toBe(dest.id) + expect(result.copiedAssetIds).toHaveLength(2) + const copies = await prisma.asset.findMany({ + where: { id: { in: result.copiedAssetIds } }, + }) + const byId = new Map(copies.map((c) => [c.id, c])) + expect(result.copiedAssetIds.map((id) => byId.get(id)?.name)).toEqual(['a.bin', 'b.bin']) + expect(copies.every((c) => c.parentId === dest.id && c.creatorId === owner.id)).toBe(true) + + const audits = await auditRows(AuditAction.asset_copy) + expect(audits.map((r) => r.itemId).sort()).toEqual([a, b].sort()) + expect(audits.every((r) => r.teamId === teamId && r.projectId === projectId)).toBe(true) + expect(audits.every((r) => r.via === 'mcp')).toBe(true) + }) + + it('rejects a reviewer without copying', async () => { + const a = await createFile('a.bin') + + await expect( + runOperation(copyAssetsOp, as(reviewer), { assetIds: [a], newParentId: rootFolderId }), + ).rejects.toMatchObject({ status: 403 }) + expect(await prisma.asset.count({ where: { name: 'a.bin', projectId } })).toBe(1) + expect(await auditRows(AuditAction.asset_copy)).toHaveLength(0) + }) + + it('reports copying a folder into itself as a bad request', async () => { + const folder = await runOperation(createFolderOp, as(owner), { + parent: rootFolderId, + name: 'loop', + }) + await expect( + runOperation(copyAssetsOp, as(owner), { assetIds: [folder.id], newParentId: folder.id }), + ).rejects.toMatchObject({ status: 400 }) + }) + }) + + describe('get_folder_instructions', () => { + it("returns the folder's AGENTS.md, or null", async () => { + const folder = await runOperation(createFolderOp, as(owner), { + parent: rootFolderId, + name: 'deliverables', + }) + await expect( + runOperation(getFolderInstructionsOp, as(reviewer), { folderId: folder.id }), + ).resolves.toEqual({ folderId: folder.id, content: null }) + + await assetService.updateAgentsMd(folder.id, '# Name files _v') + await expect( + runOperation(getFolderInstructionsOp, as(reviewer), { folderId: folder.id }), + ).resolves.toEqual({ folderId: folder.id, content: '# Name files _v' }) + }) + + it('rejects a file as a bad request and a non-member as forbidden', async () => { + const file = await createFile('a.bin') + await expect( + runOperation(getFolderInstructionsOp, as(owner), { folderId: file }), + ).rejects.toMatchObject({ status: 400 }) + await expect( + runOperation(getFolderInstructionsOp, as(outsider), { folderId: rootFolderId }), + ).rejects.toMatchObject({ status: 403 }) + }) + }) + + describe('comments', () => { + it('lets a reviewer comment, reply, list, and resolve, with audit entries', async () => { + const file = await createFile('cut.bin') + + const comment = await runOperation(createCommentOp, as(reviewer), { + assetId: file, + message: 'Too dark at the start', + second: 2.5, + }) + expect(comment).toEqual({ id: expect.any(String), assetId: file, replyToId: null }) + + const reply = await runOperation(createCommentOp, as(owner, 'agent', undefined), { + assetId: file, + message: 'Brightened in v2', + replyToId: comment.id, + }) + expect(reply.replyToId).toBe(comment.id) + + const listed = await runOperation(listCommentsOp, as(reviewer), { assetId: file }) + expect(listed.total).toBe(1) + expect(listed.data).toEqual([ + expect.objectContaining({ + id: comment.id, + message: 'Too dark at the start', + author: { id: reviewer.id, name: 'Reviewer' }, + second: 2.5, + resolved: false, + replies: [ + expect.objectContaining({ + id: reply.id, + message: 'Brightened in v2', + author: { id: owner.id, name: 'Owner' }, + }), + ], + }), + ]) + + await expect( + runOperation(resolveCommentOp, as(reviewer), { commentId: comment.id }), + ).resolves.toEqual({ commentId: comment.id, resolved: true }) + await expect( + runOperation(resolveCommentOp, as(reviewer), { commentId: comment.id, reopen: true }), + ).resolves.toEqual({ commentId: comment.id, resolved: false }) + + const created = await auditRows(AuditAction.comment_create) + expect(created.map((r) => r.itemId)).toEqual([comment.id, reply.id]) + expect(created.every((r) => r.teamId === teamId && r.projectId === projectId)).toBe(true) + const completed = await auditRows(AuditAction.comment_complete) + expect(completed).toHaveLength(2) + expect(completed[0]).toMatchObject({ itemId: comment.id, userId: reviewer.id, via: 'mcp' }) + }) + + it('notifies the team about a new comment', async () => { + const file = await createFile('cut.bin') + await runOperation(createCommentOp, as(reviewer), { assetId: file, message: 'Nice' }) + + await expect + .poll(() => prisma.notification.count({ where: { type: 'comment_created', teamId } })) + .toBeGreaterThan(0) + }) + + it('does not start agent runs from comments written by the built-in agent', async () => { + const file = await createFile('cut.bin') + await runOperation(createCommentOp, as(owner, 'agent'), { + assetId: file, + message: '<@default> please review', + }) + expect(await prisma.workflowTask.count({ where: { type: 'chat', projectId } })).toBe(0) + + await runOperation(createCommentOp, as(owner, 'mcp'), { + assetId: file, + message: '<@default> please review', + }) + expect(await prisma.workflowTask.count({ where: { type: 'chat', projectId } })).toBe(1) + }) + + it('lists the comments of a version stack, counting them on its latest version', async () => { + const v2 = await createFile('v2.bin') + const v1 = await createFile('v1.bin') + const stack = await runOperation(createVersionStackOp, as(owner), { fileIds: [v2, v1] }) + await runOperation(createCommentOp, as(owner), { assetId: stack.id, message: 'On v2' }) + + const listed = await runOperation(listCommentsOp, as(owner), { assetId: stack.id }) + expect(listed.data.map((c) => c.message)).toEqual(['On v2']) + expect(listed.total).toBe(1) + }) + + it('rejects commenting without access, and replies to threads the caller cannot see', async () => { + const file = await createFile('cut.bin') + await expect( + runOperation(createCommentOp, as(outsider), { assetId: file, message: 'hi' }), + ).rejects.toMatchObject({ status: 403 }) + expect(await prisma.assetComment.count({ where: { assetId: file } })).toBe(0) + + // A thread in another team's project + const otherTeam = await prisma.team.create({ data: { name: 'Other' } }) + await prisma.teamMember.create({ + data: { teamId: otherTeam.id, userId: outsider.id, role: 'owner' }, + }) + const otherProject = await projectService.createProject(outsider, { + teamId: otherTeam.id, + name: 'Other Project', + }) + const otherFile = await assetService.createFile({ + parentId: otherProject.rootFolder!, + name: 'secret.bin', + key: 'files/test/secret.bin', + sizeByte: 1, + contentType: 'application/octet-stream', + creatorId: outsider.id, + }) + const otherThread = await runOperation(createCommentOp, as(outsider), { + assetId: otherFile.id, + message: 'private', + }) + + await expect( + runOperation(createCommentOp, as(owner), { + assetId: file, + message: 'sneaky', + replyToId: otherThread.id, + }), + ).rejects.toMatchObject({ status: 403 }) + expect(await prisma.assetComment.count({ where: { message: 'sneaky', assetId: file } })).toBe( + 0, + ) + }) + + it('rejects resolving a comment without access, and 404s an unknown one', async () => { + const file = await createFile('cut.bin') + const comment = await runOperation(createCommentOp, as(owner), { + assetId: file, + message: 'x', + }) + await expect( + runOperation(resolveCommentOp, as(outsider), { commentId: comment.id }), + ).rejects.toMatchObject({ status: 403 }) + const row = await prisma.assetComment.findUniqueOrThrow({ where: { id: comment.id } }) + expect(row.isCompleted).toBe(false) + }) + }) + + describe('metadata', () => { + it('lists fields with choices and the Creation Context flag', async () => { + const status = await metadataService.createProjectField(projectId, { + config: { + name: 'Review', + type: 'select', + select: { options: [{ id: 'approved', displayName: 'Approved', color: '#fff' }] }, + }, + description: 'Review status', + }) + const prompt = await metadataService.createProjectField(projectId, { + config: { name: 'Prompt', type: 'text', autofillSource: 'CREATION_CONTEXT' }, + description: '', + }) + + const { fields } = await runOperation(listMetadataFieldsOp, as(reviewer), { projectId }) + + expect(fields).toContainEqual({ + key: status.key, + name: 'Review', + type: 'select', + description: 'Review status', + readOnly: false, + creationContext: false, + options: [{ id: 'approved', name: 'Approved' }], + }) + expect(fields).toContainEqual( + expect.objectContaining({ key: prompt.key, creationContext: true }), + ) + }) + + it('rejects a non-member listing fields', async () => { + await expect( + runOperation(listMetadataFieldsOp, as(outsider), { projectId }), + ).rejects.toMatchObject({ status: 403 }) + }) + + it('sets values, adds a new select option, and audits a file update', async () => { + const review = await metadataService.createProjectField(projectId, { + config: { name: 'Review', type: 'select', select: { options: [] } }, + description: '', + }) + const notes = await metadataService.createProjectField(projectId, { + config: { name: 'Notes', type: 'text' }, + description: '', + }) + const file = await createFile('a.bin') + + const result = await runOperation(updateAssetMetadataOp, as(owner, 'agent', undefined), { + assetId: file, + values: { [review.key]: { newOption: { value: 'Approved' } }, [notes.key]: 'Looks good' }, + }) + + expect(result).toEqual({ assetId: file, updatedKeys: [review.key, notes.key] }) + const values = await prisma.assetMetadataValue.findMany({ where: { assetId: file } }) + expect(values.find((v) => v.fieldKey === review.key)?.stringValue).toBe('approved') + expect(values.find((v) => v.fieldKey === notes.key)?.stringValue).toBe('Looks good') + + const [audit] = await auditRows(AuditAction.file_update) + expect(audit).toMatchObject({ itemId: file, teamId, projectId, via: 'agent' }) + }) + + it('rejects unknown and read-only fields before writing anything', async () => { + const notes = await metadataService.createProjectField(projectId, { + config: { name: 'Notes', type: 'text' }, + description: '', + }) + await prisma.metadataField.update({ where: { key: notes.key }, data: { readOnly: true } }) + const file = await createFile('a.bin') + + await expect( + runOperation(updateAssetMetadataOp, as(owner), { + assetId: file, + values: { nope: 'x' }, + }), + ).rejects.toMatchObject({ status: 400 }) + await expect( + runOperation(updateAssetMetadataOp, as(owner), { + assetId: file, + values: { [notes.key]: 'x' }, + }), + ).rejects.toMatchObject({ status: 422 }) + expect(await prisma.assetMetadataValue.count({ where: { assetId: file } })).toBe(0) + }) + + it('rejects a reviewer without writing', async () => { + const notes = await metadataService.createProjectField(projectId, { + config: { name: 'Notes', type: 'text' }, + description: '', + }) + const file = await createFile('a.bin') + + await expect( + runOperation(updateAssetMetadataOp, as(reviewer), { + assetId: file, + values: { [notes.key]: 'x' }, + }), + ).rejects.toMatchObject({ status: 403 }) + expect(await prisma.assetMetadataValue.count({ where: { assetId: file } })).toBe(0) + expect(await auditRows(AuditAction.file_update)).toHaveLength(0) + }) + }) + + describe('version stacks', () => { + it('stacks files, lists versions latest first, and unstacks one', async () => { + const v2 = await createFile('cut_v2.bin') + const v1 = await createFile('cut_v1.bin') + + const stack = await runOperation(createVersionStackOp, as(owner), { fileIds: [v2, v1] }) + expect(stack).toMatchObject({ type: 'version_stack', projectId }) + + const { versions } = await runOperation(listVersionsOp, as(reviewer), { stackId: stack.id }) + expect(versions.map((v) => [v.id, v.version, v.current])).toEqual([ + [v2, 2, true], + [v1, 1, false], + ]) + + await expect(runOperation(removeVersionOp, as(owner), { versionId: v1 })).resolves.toEqual({ + versionId: v1, + stackId: stack.id, + }) + const removed = await prisma.asset.findUniqueOrThrow({ where: { id: v1 } }) + expect(removed.parentId).toBe(rootFolderId) + expect(removed.isDeleted).toBe(false) + + const [created] = await auditRows(AuditAction.version_stack_create) + expect(created).toMatchObject({ itemId: stack.id, teamId, projectId, via: 'mcp' }) + const [updated] = await auditRows(AuditAction.version_stack_update) + expect(updated).toMatchObject({ itemId: stack.id, teamId, projectId }) + }) + + it('rejects stacking files from different folders as a bad request', async () => { + const sub = await runOperation(createFolderOp, as(owner), { parent: rootFolderId, name: 's' }) + const a = await createFile('a.bin') + const b = await createFile('b.bin', sub.id) + + await expect( + runOperation(createVersionStackOp, as(owner), { fileIds: [a, b] }), + ).rejects.toMatchObject({ status: 400 }) + expect(await prisma.asset.count({ where: { type: 'version_stack', projectId } })).toBe(0) + }) + + it('rejects a reviewer stacking or unstacking without changes', async () => { + const v2 = await createFile('v2.bin') + const v1 = await createFile('v1.bin') + + await expect( + runOperation(createVersionStackOp, as(reviewer), { fileIds: [v2, v1] }), + ).rejects.toMatchObject({ status: 403 }) + expect(await prisma.asset.count({ where: { type: 'version_stack', projectId } })).toBe(0) + + const stack = await runOperation(createVersionStackOp, as(owner), { fileIds: [v2, v1] }) + await expect( + runOperation(removeVersionOp, as(reviewer), { versionId: v1 }), + ).rejects.toMatchObject({ status: 403 }) + const row = await prisma.asset.findUniqueOrThrow({ where: { id: v1 } }) + expect(row.parentId).toBe(stack.id) + }) + + it('reports a file outside a stack and a non-stack as bad requests', async () => { + const file = await createFile('lonely.bin') + await expect( + runOperation(removeVersionOp, as(owner), { versionId: file }), + ).rejects.toMatchObject({ status: 400 }) + await expect( + runOperation(listVersionsOp, as(owner), { stackId: file }), + ).rejects.toMatchObject({ status: 400 }) + }) + }) +}) diff --git a/packages/core/src/operations/comment/create-comment.ts b/packages/core/src/operations/comment/create-comment.ts new file mode 100644 index 00000000..360944ba --- /dev/null +++ b/packages/core/src/operations/comment/create-comment.ts @@ -0,0 +1,31 @@ +import { createComment } from '@shumai/operations' +import { AuditAction } from '@shumai/dtos' +import { Permission, ResourceType } from '@shumai/core/src/authz/authz' +import { commentService } from '@shumai/core/src/comment/comment' +import { implementOperation } from '../implement' + +export const createCommentOp = implementOperation(createComment, { + // Commenting needs Read on the file, as in the web app; a reply also needs access to the + // thread it replies to. + authz: (input) => [ + { permission: Permission.Read, type: ResourceType.Asset, id: input.assetId }, + ...(input.replyToId + ? [{ permission: Permission.Read, type: ResourceType.Comment, id: input.replyToId }] + : []), + ], + execute: async (input, ctx) => { + const comment = await commentService.postComment({ + assetId: input.assetId, + userId: ctx.userId, + message: input.message, + replyToId: input.replyToId, + second: input.second, + // Mentions in comments written by Shumai's own agent must not start more agent runs. + triggerAgents: ctx.via !== 'agent', + }) + return { id: comment.id, assetId: comment.assetId, replyToId: input.replyToId ?? null } + }, + audit: (input, output) => [ + { action: AuditAction.comment_create, itemId: output.id, contextAssetId: input.assetId }, + ], +}) diff --git a/packages/core/src/operations/comment/list-comments.ts b/packages/core/src/operations/comment/list-comments.ts new file mode 100644 index 00000000..ddfeab60 --- /dev/null +++ b/packages/core/src/operations/comment/list-comments.ts @@ -0,0 +1,47 @@ +import { DEFAULT_PAGE_SIZE, listComments, type CommentThread } from '@shumai/operations' +import type { CommentInfo } from '@shumai/dtos' +import { assetService } from '@shumai/core/src/asset/asset' +import { Permission, ResourceType } from '@shumai/core/src/authz/authz' +import { implementOperation } from '../implement' + +/** Placeholder reply that anchors an agent chat session to a thread; not a real comment. */ +const CHAT_PLACEHOLDER = '__CHAT__' + +function toCommentFields(comment: CommentInfo) { + return { + id: comment.id, + message: comment.message ?? '', + author: { id: comment.creator.id, name: comment.creator.name }, + second: comment.second, + hasMarkup: Array.isArray(comment.annotations) && comment.annotations.length > 0, + attachmentCount: comment.attachments.length, + createdAt: comment.createdAt, + } +} + +export function toCommentThread(comment: CommentInfo): CommentThread { + return { + ...toCommentFields(comment), + resolved: comment.isCompleted, + replies: comment.replies.filter((r) => r.message !== CHAT_PLACEHOLDER).map(toCommentFields), + } +} + +export const listCommentsOp = implementOperation(listComments, { + authz: (input) => [{ permission: Permission.Read, type: ResourceType.Asset, id: input.assetId }], + execute: async (input, ctx) => { + const result = await assetService.listComments( + input.assetId, + { first: input.first ?? DEFAULT_PAGE_SIZE, after: input.after }, + ctx.userId, + ) + return { + data: result.data.map(toCommentThread), + pageInfo: { + hasNextPage: Boolean(result.pageInfo.cursor), + endCursor: result.pageInfo.cursor ?? null, + }, + total: result.pageInfo.total ?? result.data.length, + } + }, +}) diff --git a/packages/core/src/operations/comment/resolve-comment.ts b/packages/core/src/operations/comment/resolve-comment.ts new file mode 100644 index 00000000..38727ec2 --- /dev/null +++ b/packages/core/src/operations/comment/resolve-comment.ts @@ -0,0 +1,29 @@ +import { HTTPException } from 'hono/http-exception' +import { resolveComment } from '@shumai/operations' +import { AuditAction } from '@shumai/dtos' +import { assetService } from '@shumai/core/src/asset/asset' +import { Permission, ResourceType } from '@shumai/core/src/authz/authz' +import { implementOperation } from '../implement' + +export const resolveCommentOp = implementOperation(resolveComment, { + authz: (input) => [ + { permission: Permission.Read, type: ResourceType.Comment, id: input.commentId }, + ], + // The comment's file, for the audit entry. + prepare: async (input) => { + const comment = await assetService.getComment(input.commentId).catch(() => null) + if (!comment) throw new HTTPException(404, { message: 'Comment not found' }) + return { assetId: comment.assetId } + }, + execute: async (input, ctx) => { + const updated = await assetService.completeComment(input.commentId, !input.reopen, ctx.userId) + return { commentId: updated.id, resolved: updated.isCompleted } + }, + audit: (input, _output, _ctx, comment) => [ + { + action: AuditAction.comment_complete, + itemId: input.commentId, + contextAssetId: comment.assetId, + }, + ], +}) diff --git a/packages/core/src/operations/errors.ts b/packages/core/src/operations/errors.ts new file mode 100644 index 00000000..14e17f39 --- /dev/null +++ b/packages/core/src/operations/errors.ts @@ -0,0 +1,22 @@ +import { HTTPException } from 'hono/http-exception' + +/** + * Runs a service call whose plain `Error`s describe invalid input (e.g. "file is not in the + * stack") and reports them as 400 Bad Request instead of a server error. Other errors, such as + * `HTTPException`s and database errors, pass through unchanged. + */ +export async function asBadRequest(fn: () => Promise): Promise { + try { + return await fn() + } catch (err) { + if (err instanceof Error && err.constructor === Error) { + throw new HTTPException(400, { message: err.message }) + } + throw err + } +} + +/** A 400 Bad Request with a message for the caller. */ +export function badRequest(message: string): HTTPException { + return new HTTPException(400, { message }) +} diff --git a/packages/core/src/operations/index.ts b/packages/core/src/operations/index.ts index d04bf8b8..b5354b57 100644 --- a/packages/core/src/operations/index.ts +++ b/packages/core/src/operations/index.ts @@ -10,9 +10,11 @@ export { } from './implement' export { runOperation } from './run' export { getOperation, getOperationsForSurface, operations } from './registry' +export { copyAssetsOp } from './asset/copy-assets' export { createFolderOp } from './asset/create-folder' export { deleteAssetOp } from './asset/delete-asset' export { downloadAssetOp } from './asset/download-asset' +export { getFolderInstructionsOp } from './asset/get-folder-instructions' export { listAssetsOp } from './asset/list-assets' export { moveAssetsOp } from './asset/move-assets' export { @@ -22,4 +24,16 @@ export { waitBudgetMs, } from './asset/read-asset' export { renameAssetOp } from './asset/rename-asset' +export { searchAssetsOp } from './asset/search-assets' +export { createCommentOp } from './comment/create-comment' +export { listCommentsOp } from './comment/list-comments' +export { resolveCommentOp } from './comment/resolve-comment' +export { listMetadataFieldsOp } from './metadata/list-metadata-fields' +export { updateAssetMetadataOp } from './metadata/update-asset-metadata' export { listProjectsOp } from './project/list-projects' +export { completeUploadOp } from './upload/complete-upload' +export { createFileOp } from './upload/create-file' +export { createVersionOp } from './upload/create-version' +export { createVersionStackOp } from './version/create-version-stack' +export { listVersionsOp } from './version/list-versions' +export { removeVersionOp } from './version/remove-version' diff --git a/packages/core/src/operations/metadata/list-metadata-fields.ts b/packages/core/src/operations/metadata/list-metadata-fields.ts new file mode 100644 index 00000000..25e35757 --- /dev/null +++ b/packages/core/src/operations/metadata/list-metadata-fields.ts @@ -0,0 +1,40 @@ +import { listMetadataFields, type MetadataFieldSummary } from '@shumai/operations' +import { Permission, ResourceType } from '@shumai/core/src/authz/authz' +import { metadataService } from '@shumai/core/src/metadata/metadata' +import { implementOperation } from '../implement' + +interface FieldRecord { + key: string + readOnly: boolean + description: string | null + config: PrismaJson.FieldConfig | null +} + +export function toMetadataFieldSummary(field: FieldRecord): MetadataFieldSummary { + const config = field.config + const choices = + config?.type === 'select' + ? config.select?.options + : config?.type === 'selectMulti' + ? config.selectMulti?.options + : undefined + return { + key: field.key, + name: config?.name ?? field.key, + type: config?.type ?? 'text', + description: field.description ?? '', + readOnly: field.readOnly, + creationContext: config?.autofillSource === 'CREATION_CONTEXT', + ...(choices ? { options: choices.map((o) => ({ id: o.id, name: o.displayName })) } : {}), + } +} + +export const listMetadataFieldsOp = implementOperation(listMetadataFields, { + authz: (input) => [ + { permission: Permission.Read, type: ResourceType.Project, id: input.projectId }, + ], + execute: async (input, ctx) => { + const fields = await metadataService.listProjectFields(ctx.userId, input.projectId) + return { fields: fields.map((f) => toMetadataFieldSummary(f.field)) } + }, +}) diff --git a/packages/core/src/operations/metadata/update-asset-metadata.ts b/packages/core/src/operations/metadata/update-asset-metadata.ts new file mode 100644 index 00000000..8f9097ca --- /dev/null +++ b/packages/core/src/operations/metadata/update-asset-metadata.ts @@ -0,0 +1,61 @@ +import { HTTPException } from 'hono/http-exception' +import { updateAssetMetadata } from '@shumai/operations' +import { AuditAction } from '@shumai/dtos' +import { assetService } from '@shumai/core/src/asset/asset' +import { Permission, ResourceType } from '@shumai/core/src/authz/authz' +import { metadataService } from '@shumai/core/src/metadata/metadata' +import { notificationService } from '@shumai/core/src/notification/notification' +import { asBadRequest, badRequest } from '../errors' +import { implementOperation } from '../implement' + +export const updateAssetMetadataOp = implementOperation(updateAssetMetadata, { + authz: (input) => [{ permission: Permission.Edit, type: ResourceType.Asset, id: input.assetId }], + // Check every key before writing anything: unknown keys would otherwise fail halfway. + prepare: async (input) => { + const keys = Object.keys(input.values) + if (keys.length === 0) throw badRequest('values must set at least one field') + + const asset = await assetService.getAssetMeta(input.assetId) + if (!asset.projectId) throw badRequest('This asset does not belong to a project') + + const fields = new Map( + (await metadataService.listProjectFields(null, asset.projectId)).map((f) => [ + f.field.key, + f.field, + ]), + ) + const unknown = keys.filter((key) => !fields.has(key)) + if (unknown.length > 0) { + throw badRequest( + `Unknown metadata field(s): ${unknown.join(', ')}. Use list_metadata_fields to get the field keys.`, + ) + } + const readOnly = keys.filter((key) => fields.get(key)?.readOnly) + if (readOnly.length > 0) { + throw new HTTPException(422, { message: `Field ${readOnly.join(', ')} is read-only` }) + } + return asset + }, + execute: async (input, ctx, asset) => { + const updates = Object.entries(input.values).map(([key, value]) => ({ key, value })) + await asBadRequest(() => metadataService.updateAssetMetadata(input.assetId, updates)) + + if ('status' in input.values) { + await notificationService.create({ + type: 'metadata_field_updated_status', + teamId: asset.teamId, + creatorId: ctx.userId, + assetId: input.assetId, + }) + } + return { assetId: input.assetId, updatedKeys: updates.map((u) => u.key) } + }, + audit: (input, _output, _ctx, asset) => [ + { + action: asset.type === 'folder' ? AuditAction.folder_update : AuditAction.file_update, + itemId: input.assetId, + teamId: asset.teamId, + projectId: asset.projectId, + }, + ], +}) diff --git a/packages/core/src/operations/operations.test.ts b/packages/core/src/operations/operations.test.ts index 4b3b320b..63f90285 100644 --- a/packages/core/src/operations/operations.test.ts +++ b/packages/core/src/operations/operations.test.ts @@ -285,6 +285,7 @@ describe('asset and project Operations', () => { id: folder.id, name: 'meta', type: 'folder', + parentId: rootFolderId, teamId, projectId, }) diff --git a/packages/core/src/operations/registry.ts b/packages/core/src/operations/registry.ts index 510f8ed7..2224e0f6 100644 --- a/packages/core/src/operations/registry.ts +++ b/packages/core/src/operations/registry.ts @@ -1,13 +1,27 @@ import type { OperationName, Surface } from '@shumai/operations' +import { copyAssetsOp } from './asset/copy-assets' import { createFolderOp } from './asset/create-folder' import { deleteAssetOp } from './asset/delete-asset' import { downloadAssetOp } from './asset/download-asset' +import { getFolderInstructionsOp } from './asset/get-folder-instructions' import { listAssetsOp } from './asset/list-assets' import { moveAssetsOp } from './asset/move-assets' import { getAssetRenderOp, readAssetOp } from './asset/read-asset' import { renameAssetOp } from './asset/rename-asset' +import { searchAssetsOp } from './asset/search-assets' +import { createCommentOp } from './comment/create-comment' +import { listCommentsOp } from './comment/list-comments' +import { resolveCommentOp } from './comment/resolve-comment' import type { Operation } from './implement' +import { listMetadataFieldsOp } from './metadata/list-metadata-fields' +import { updateAssetMetadataOp } from './metadata/update-asset-metadata' import { listProjectsOp } from './project/list-projects' +import { completeUploadOp } from './upload/complete-upload' +import { createFileOp } from './upload/create-file' +import { createVersionOp } from './upload/create-version' +import { createVersionStackOp } from './version/create-version-stack' +import { listVersionsOp } from './version/list-versions' +import { removeVersionOp } from './version/remove-version' type ImplementedName = TOps[number]['definition']['name'] type MissingNames = Exclude> @@ -29,13 +43,27 @@ function defineRegistry( export const operations = defineRegistry([ listProjectsOp, listAssetsOp, + searchAssetsOp, createFolderOp, renameAssetOp, moveAssetsOp, + copyAssetsOp, deleteAssetOp, readAssetOp, getAssetRenderOp, downloadAssetOp, + getFolderInstructionsOp, + createFileOp, + createVersionOp, + completeUploadOp, + listCommentsOp, + createCommentOp, + resolveCommentOp, + listMetadataFieldsOp, + updateAssetMetadataOp, + createVersionStackOp, + listVersionsOp, + removeVersionOp, ] as const) const operationsByName = new Map() diff --git a/packages/core/src/operations/upload.test.ts b/packages/core/src/operations/upload.test.ts new file mode 100644 index 00000000..8f71661a --- /dev/null +++ b/packages/core/src/operations/upload.test.ts @@ -0,0 +1,298 @@ +import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, it, vi } from 'vitest' +import { prisma, type User } from '@shumai/db' +import { setupTestDbHooks } from '@shumai/db/test' +import { AuditAction } from '@shumai/dtos' +import { assetService } from '@shumai/core/src/asset/asset' +import { metadataService } from '@shumai/core/src/metadata/metadata' +import { projectService } from '@shumai/core/src/project/project' +import { s3Service } from '@shumai/core/src/s3/s3' +import { pendingUploadService } from '@shumai/core/src/upload/pending-upload' +import { completeUploadOp, createFileOp, createFolderOp, createVersionOp } from './index' +import { runOperation } from './run' +import type { OperationContext } from './context' + +/** Real-database and real-storage tests for create_file, create_version, and complete_upload. */ +describe('upload Operations', () => { + setupTestDbHooks() + + const bucket = 'shumai-test-upload-ops' + const originalBucket = process.env.S3_BUCKET + + let owner: User + let reviewer: User + let teamId: string + let projectId: string + let rootFolderId: string + + const as = (user: User, via: OperationContext['via'] = 'mcp', agentId?: string) => ({ + userId: user.id, + via, + agentId, + }) + + /** Uploads bytes the way a client would after create_file / create_version. */ + async function upload(uploadId: string, user: User, content = 'hello world') { + const { key } = pendingUploadService.read(uploadId, user.id) + await s3Service.putObject(bucket, key, Buffer.from(content), Buffer.byteLength(content)) + return key + } + + async function auditRows(action: AuditAction) { + return prisma.auditLog.findMany({ where: { action, teamId }, orderBy: { id: 'asc' } }) + } + + beforeAll(() => { + process.env.S3_BUCKET = bucket + }) + + afterAll(async () => { + if (originalBucket === undefined) delete process.env.S3_BUCKET + else process.env.S3_BUCKET = originalBucket + await s3Service.deletePrefix(bucket, '').catch(() => undefined) + }) + + afterEach(() => { + vi.restoreAllMocks() + }) + + beforeEach(async () => { + owner = await prisma.user.create({ + data: { name: 'Owner', email: 'upload-owner@test.com', password: 'pw' }, + }) + reviewer = await prisma.user.create({ + data: { name: 'Reviewer', email: 'upload-reviewer@test.com', password: 'pw' }, + }) + const team = await prisma.team.create({ data: { name: 'Upload Team' } }) + teamId = team.id + await prisma.teamMember.create({ data: { teamId, userId: owner.id, role: 'owner' } }) + await prisma.teamMember.create({ data: { teamId, userId: reviewer.id, role: 'reviewer' } }) + const project = await projectService.createProject(owner, { teamId, name: 'Upload Project' }) + projectId = project.id + rootFolderId = project.rootFolder! + }) + + describe('create_file + complete_upload', () => { + it('creates nothing until the upload completes, then creates the file once', async () => { + const started = await runOperation(createFileOp, as(owner), { + parent: rootFolderId, + name: 'notes.bin', + }) + + expect(started).toEqual({ + uploadId: expect.any(String), + uploadUrl: expect.stringContaining('/api/upload/local?'), + method: 'PUT', + expiresAt: expect.any(String), + }) + expect(new Date(started.expiresAt).getTime()).toBeGreaterThan(Date.now()) + expect(await prisma.asset.count({ where: { name: 'notes.bin', projectId } })).toBe(0) + + // Completing before the bytes are uploaded fails and can be retried + await expect( + runOperation(completeUploadOp, as(owner), { uploadId: started.uploadId }), + ).rejects.toMatchObject({ status: 409 }) + + const key = await upload(started.uploadId, owner) + const file = await runOperation(completeUploadOp, as(owner), { + uploadId: started.uploadId, + }) + + expect(file).toEqual({ + id: expect.any(String), + name: 'notes.bin', + type: 'file', + size: 11, + projectId, + }) + const row = await prisma.asset.findUniqueOrThrow({ + where: { id: file.id }, + include: { storageKey: true }, + }) + expect(row).toMatchObject({ parentId: rootFolderId, creatorId: owner.id }) + expect(row.storageKey?.key).toBe(key) + + const [audit] = await auditRows(AuditAction.file_create) + expect(audit).toMatchObject({ itemId: file.id, teamId, projectId, via: 'mcp' }) + + // Completing again returns the same file without another asset or audit entry + const again = await runOperation(completeUploadOp, as(owner), { + uploadId: started.uploadId, + }) + expect(again.id).toBe(file.id) + expect(await prisma.asset.count({ where: { name: 'notes.bin', projectId } })).toBe(1) + expect(await auditRows(AuditAction.file_create)).toHaveLength(1) + }) + + it('records Creation Context metadata and attributes the file to the agent', async () => { + const prompt = await metadataService.createProjectField(projectId, { + config: { name: 'Prompt', type: 'text', autofillSource: 'CREATION_CONTEXT' }, + description: '', + }) + const agentUser = await prisma.user.create({ + data: { name: 'Bot', type: 'agent', email: 'upload-bot@test.com' }, + }) + const agent = await prisma.agent.create({ + data: { + id: agentUser.id, + teamId, + type: 'chat', + config: { provider: 'test', model: 'test' }, + }, + }) + + const started = await runOperation(createFileOp, as(owner, 'agent', agent.id), { + parent: rootFolderId, + name: 'gen.bin', + metadata: { [prompt.key]: 'a red fox' }, + }) + // The built-in agent writes straight to storage, so it gets the key + expect(started.key).toMatch(/^files\/.+\/gen\.bin$/) + + await upload(started.uploadId, owner) + const file = await runOperation(completeUploadOp, as(owner, 'agent', agent.id), { + uploadId: started.uploadId, + }) + + const row = await prisma.asset.findUniqueOrThrow({ where: { id: file.id } }) + expect(row.agentId).toBe(agent.id) + const value = await prisma.assetMetadataValue.findFirstOrThrow({ + where: { assetId: file.id, fieldKey: prompt.key }, + }) + expect(value.stringValue).toBe('a red fox') + const [audit] = await auditRows(AuditAction.file_create) + expect(audit).toMatchObject({ itemId: file.id, agentId: agent.id, via: 'agent' }) + }) + + it('rejects metadata that is not a Creation Context field before uploading', async () => { + const notes = await metadataService.createProjectField(projectId, { + config: { name: 'Notes', type: 'text' }, + description: '', + }) + + await expect( + runOperation(createFileOp, as(owner), { + parent: rootFolderId, + name: 'a.bin', + metadata: { [notes.key]: 'x' }, + }), + ).rejects.toMatchObject({ status: 400, message: expect.stringContaining(notes.key) }) + }) + + it('rejects a parent that is not a folder', async () => { + const started = await runOperation(createFileOp, as(owner), { + parent: rootFolderId, + name: 'a.bin', + }) + await upload(started.uploadId, owner) + const file = await runOperation(completeUploadOp, as(owner), { uploadId: started.uploadId }) + + await expect( + runOperation(createFileOp, as(owner), { parent: file.id, name: 'b.bin' }), + ).rejects.toMatchObject({ status: 400 }) + }) + + it('rejects a reviewer without starting an upload', async () => { + const presign = vi.spyOn(s3Service, 'presign') + await expect( + runOperation(createFileOp, as(reviewer), { parent: rootFolderId, name: 'nope.bin' }), + ).rejects.toMatchObject({ status: 403 }) + expect(presign).not.toHaveBeenCalled() + }) + + it('stops an upload if the user lost access before completing it', async () => { + const folder = await runOperation(createFolderOp, as(owner), { + parent: rootFolderId, + name: 'inbox', + }) + const editor = await prisma.user.create({ + data: { name: 'Editor', email: 'upload-editor@test.com', password: 'pw' }, + }) + await prisma.teamMember.create({ data: { teamId, userId: editor.id, role: 'editor' } }) + const started = await runOperation(createFileOp, as(editor), { + parent: folder.id, + name: 'late.bin', + }) + await upload(started.uploadId, editor) + + await prisma.teamMember.update({ + where: { teamIdUserId: { teamId, userId: editor.id } }, + data: { role: 'reviewer' }, + }) + + await expect( + runOperation(completeUploadOp, as(editor), { uploadId: started.uploadId }), + ).rejects.toMatchObject({ status: 403 }) + expect(await prisma.asset.count({ where: { name: 'late.bin', projectId } })).toBe(0) + }) + + it('only lets the user who started an upload complete it', async () => { + const started = await runOperation(createFileOp, as(owner), { + parent: rootFolderId, + name: 'mine.bin', + }) + await upload(started.uploadId, owner) + + await expect( + runOperation(completeUploadOp, as(reviewer), { uploadId: started.uploadId }), + ).rejects.toMatchObject({ status: 403 }) + expect(await prisma.asset.count({ where: { name: 'mine.bin', projectId } })).toBe(0) + }) + + it('rejects a tampered or expired upload ID', async () => { + const started = await runOperation(createFileOp, as(owner), { + parent: rootFolderId, + name: 'a.bin', + }) + const [payload, signature] = started.uploadId.split('.') + const forged = Buffer.from( + JSON.stringify({ + ...JSON.parse(Buffer.from(payload, 'base64url').toString()), + parentId: 'elsewhere', + }), + ).toString('base64url') + + await expect( + runOperation(completeUploadOp, as(owner), { uploadId: `${forged}.${signature}` }), + ).rejects.toMatchObject({ status: 400 }) + await expect( + runOperation(completeUploadOp, as(owner), { uploadId: 'not-an-upload' }), + ).rejects.toMatchObject({ status: 400 }) + + vi.spyOn(Date, 'now').mockReturnValue(Date.now() + 2 * 60 * 60 * 1000) + await expect( + runOperation(completeUploadOp, as(owner), { uploadId: started.uploadId }), + ).rejects.toMatchObject({ status: 400, message: expect.stringContaining('expired') }) + }) + }) + + describe('create_version + complete_upload', () => { + it('adds the upload as the current version of a file', async () => { + const first = await runOperation(createFileOp, as(owner), { + parent: rootFolderId, + name: 'cut_v1.bin', + }) + await upload(first.uploadId, owner) + const v1 = await runOperation(completeUploadOp, as(owner), { uploadId: first.uploadId }) + + const second = await runOperation(createVersionOp, as(owner), { + parent: v1.id, + name: 'cut_v2.bin', + }) + await upload(second.uploadId, owner, 'version two') + const v2 = await runOperation(completeUploadOp, as(owner), { uploadId: second.uploadId }) + + expect(v2).toMatchObject({ name: 'cut_v2.bin', type: 'file', size: 11 }) + const stackId = (await prisma.asset.findUniqueOrThrow({ where: { id: v2.id } })).parentId! + const stack = await prisma.asset.findUniqueOrThrow({ where: { id: stackId } }) + expect(stack.type).toBe('version_stack') + expect(await assetService.resolveLatestVersionId(stackId)).toBe(v2.id) + expect(await auditRows(AuditAction.file_create)).toHaveLength(2) + }) + + it('rejects a folder as the parent', async () => { + await expect( + runOperation(createVersionOp, as(owner), { parent: rootFolderId, name: 'v.bin' }), + ).rejects.toMatchObject({ status: 400 }) + }) + }) +}) diff --git a/packages/core/src/operations/upload/complete-upload.ts b/packages/core/src/operations/upload/complete-upload.ts new file mode 100644 index 00000000..9d8fac09 --- /dev/null +++ b/packages/core/src/operations/upload/complete-upload.ts @@ -0,0 +1,61 @@ +import { HTTPException } from 'hono/http-exception' +import { completeUpload } from '@shumai/operations' +import { AuditAction } from '@shumai/dtos' +import { assetService } from '@shumai/core/src/asset/asset' +import { Permission, ResourceType } from '@shumai/core/src/authz/authz' +import { pendingUploadService } from '@shumai/core/src/upload/pending-upload' +import { asBadRequest } from '../errors' +import { implementOperation } from '../implement' +import { toAssetSummary } from '../asset/to-asset-summary' + +export const completeUploadOp = implementOperation(completeUpload, { + // The upload ID is signed and names its parent; Edit on it is still checked here, so + // losing access between starting and finishing an upload stops it. + authz: (input, ctx) => { + const pending = pendingUploadService.read(input.uploadId, ctx.userId) + return [{ permission: Permission.Edit, type: ResourceType.Asset, id: pending.parentId }] + }, + prepare: async (input, ctx) => { + const pending = pendingUploadService.read(input.uploadId, ctx.userId) + // Completing the same upload again returns the file it already created. + const existing = await assetService.findAssetByStorageKey(pending.key) + if (existing && existing.creatorId !== ctx.userId) { + throw new HTTPException(409, { message: 'This upload was already used.' }) + } + return { pending, existingId: existing?.id } + }, + execute: async (_input, ctx, { pending, existingId }) => { + if (existingId) { + return toAssetSummary(await assetService.getAsset({ assetId: existingId })) + } + + const size = await pendingUploadService.uploadedSize(pending.key) + if (size === null) { + throw new HTTPException(409, { + message: + 'The file has not been uploaded yet: PUT its bytes to uploadUrl first, then call complete_upload again.', + }) + } + + const params = { + parentId: pending.parentId, + name: pending.name, + key: pending.key, + sizeByte: size, + contentType: pending.contentType, + creatorId: ctx.userId, + agentId: ctx.agentId, + metadata: pending.metadata, + } + const asset = await asBadRequest(() => + pending.kind === 'file' + ? assetService.createFile(params) + : assetService.createVersion(params), + ) + return toAssetSummary(asset) + }, + audit: (_input, output, _ctx, { existingId }) => + existingId + ? [] + : [{ action: AuditAction.file_create, itemId: output.id, contextAssetId: output.id }], +}) diff --git a/packages/core/src/operations/upload/create-file.ts b/packages/core/src/operations/upload/create-file.ts new file mode 100644 index 00000000..39cd61c6 --- /dev/null +++ b/packages/core/src/operations/upload/create-file.ts @@ -0,0 +1,20 @@ +import { createFile } from '@shumai/operations' +import { assetService } from '@shumai/core/src/asset/asset' +import { Permission, ResourceType } from '@shumai/core/src/authz/authz' +import { badRequest } from '../errors' +import { implementOperation } from '../implement' +import { assertCreationMetadata, startUpload } from './start-upload' + +export const createFileOp = implementOperation(createFile, { + authz: (input) => [{ permission: Permission.Edit, type: ResourceType.Asset, id: input.parent }], + prepare: async (input, ctx) => { + const parent = await assetService.getAssetMeta(input.parent) + if (parent.type !== 'folder' && parent.type !== 'root') { + throw badRequest( + 'parent must be a folder. To upload a new version of a file, use create_version.', + ) + } + await assertCreationMetadata(ctx.userId, parent.projectId, input.metadata) + }, + execute: (input, ctx) => startUpload('file', input, ctx), +}) diff --git a/packages/core/src/operations/upload/create-version.ts b/packages/core/src/operations/upload/create-version.ts new file mode 100644 index 00000000..ef42463b --- /dev/null +++ b/packages/core/src/operations/upload/create-version.ts @@ -0,0 +1,20 @@ +import { createVersion } from '@shumai/operations' +import { assetService } from '@shumai/core/src/asset/asset' +import { Permission, ResourceType } from '@shumai/core/src/authz/authz' +import { badRequest } from '../errors' +import { implementOperation } from '../implement' +import { assertCreationMetadata, startUpload } from './start-upload' + +export const createVersionOp = implementOperation(createVersion, { + authz: (input) => [{ permission: Permission.Edit, type: ResourceType.Asset, id: input.parent }], + prepare: async (input, ctx) => { + const parent = await assetService.getAssetMeta(input.parent) + if (parent.type !== 'file' && parent.type !== 'version_stack') { + throw badRequest( + 'parent must be a file or a version stack. To upload a new file, use create_file.', + ) + } + await assertCreationMetadata(ctx.userId, parent.projectId, input.metadata) + }, + execute: (input, ctx) => startUpload('version', input, ctx), +}) diff --git a/packages/core/src/operations/upload/start-upload.ts b/packages/core/src/operations/upload/start-upload.ts new file mode 100644 index 00000000..ddcda2b0 --- /dev/null +++ b/packages/core/src/operations/upload/start-upload.ts @@ -0,0 +1,70 @@ +import type { StartedUploadOutput } from '@shumai/operations' +import { metadataService } from '@shumai/core/src/metadata/metadata' +import { + pendingUploadService, + type PendingUploadKind, +} from '@shumai/core/src/upload/pending-upload' +import { getFileMimeType } from '@shumai/core/src/utils/file-mime' +import { sanitizeFilename } from '@shumai/core/src/utils/filename' +import type { OperationContext } from '../context' +import { badRequest } from '../errors' + +interface StartUploadInput { + parent: string + name: string + contentType?: string + metadata?: Record +} + +/** + * Checks that `metadata` only sets the project's Creation Context fields, so a bad key fails + * before anything is uploaded rather than when the upload is completed. + */ +export async function assertCreationMetadata( + userId: string, + projectId: string | undefined, + metadata: Record | undefined, +): Promise { + const keys = Object.keys(metadata ?? {}) + if (keys.length === 0) return + if (!projectId) throw badRequest('metadata is only supported for files in a project') + + const fields = await metadataService.listProjectFields(userId, projectId) + const allowed = fields + .filter((f) => f.field.config?.autofillSource === 'CREATION_CONTEXT') + .map((f) => f.field.key) + const invalid = keys.filter((key) => !allowed.includes(key)) + if (invalid.length > 0) { + throw badRequest( + `metadata only accepts the project's Creation Context fields; not allowed: ${invalid.join(', ')}. ` + + (allowed.length > 0 + ? `Allowed: ${allowed.join(', ')} (see list_metadata_fields).` + : 'This project has none, so omit metadata.'), + ) + } +} + +/** Starts an upload and returns where to send the bytes and how to finish it. */ +export async function startUpload( + kind: PendingUploadKind, + input: StartUploadInput, + ctx: OperationContext, +): Promise { + const name = sanitizeFilename(input.name) + const started = await pendingUploadService.start({ + kind, + userId: ctx.userId, + parentId: input.parent, + name, + contentType: input.contentType ?? getFileMimeType(null, name), + metadata: input.metadata, + }) + return { + uploadId: started.uploadId, + uploadUrl: started.uploadUrl, + method: 'PUT', + expiresAt: started.expiresAt.toISOString(), + // Shumai's built-in agent writes the file straight to storage from its sandbox. + ...(ctx.via === 'agent' ? { key: started.key } : {}), + } +} diff --git a/packages/core/src/operations/version/create-version-stack.ts b/packages/core/src/operations/version/create-version-stack.ts new file mode 100644 index 00000000..9154d866 --- /dev/null +++ b/packages/core/src/operations/version/create-version-stack.ts @@ -0,0 +1,39 @@ +import { createVersionStack } from '@shumai/operations' +import { AuditAction } from '@shumai/dtos' +import { assetService } from '@shumai/core/src/asset/asset' +import { Permission, ResourceType } from '@shumai/core/src/authz/authz' +import { versionStackService } from '@shumai/core/src/versionStack/versionStack' +import { asBadRequest, badRequest } from '../errors' +import { implementOperation } from '../implement' +import { toAssetSummary } from '../asset/to-asset-summary' + +export const createVersionStackOp = implementOperation(createVersionStack, { + authz: (input) => + [...new Set(input.fileIds)].map((id) => ({ + permission: Permission.Edit, + type: ResourceType.Asset, + id, + })), + // The stack belongs to the files' project. + prepare: async (input) => { + if (new Set(input.fileIds).size !== input.fileIds.length) { + throw badRequest('fileIds must not contain the same file twice') + } + const first = await assetService.getAssetMeta(input.fileIds[0]) + if (!first.projectId) throw badRequest('The files do not belong to a project') + return { projectId: first.projectId } + }, + execute: async (input, ctx, { projectId }) => { + const stack = await asBadRequest(() => + versionStackService.createVersionStack({ + fileIds: input.fileIds, + projectId, + creatorId: ctx.userId, + }), + ) + return toAssetSummary(await assetService.getAsset({ assetId: stack.id })) + }, + audit: (_input, output) => [ + { action: AuditAction.version_stack_create, itemId: output.id, contextAssetId: output.id }, + ], +}) diff --git a/packages/core/src/operations/version/list-versions.ts b/packages/core/src/operations/version/list-versions.ts new file mode 100644 index 00000000..5a062d6e --- /dev/null +++ b/packages/core/src/operations/version/list-versions.ts @@ -0,0 +1,32 @@ +import { HTTPException } from 'hono/http-exception' +import { listVersions } from '@shumai/operations' +import { assetService } from '@shumai/core/src/asset/asset' +import { Permission, ResourceType } from '@shumai/core/src/authz/authz' +import { implementOperation } from '../implement' + +export const listVersionsOp = implementOperation(listVersions, { + authz: (input) => [{ permission: Permission.Read, type: ResourceType.Asset, id: input.stackId }], + prepare: async (input) => { + const stack = await assetService.getAssetMeta(input.stackId) + if (stack.type !== 'version_stack') { + throw new HTTPException(400, { + message: 'This asset is not a version stack. Pass the ID of a version stack.', + }) + } + }, + execute: async (input) => { + // Sorted latest first: the first entry is the current version. + const versions = await assetService.getStackVersions(input.stackId) + return { + versions: versions.map((v, index) => ({ + id: v.id, + version: v.version, + name: v.name, + current: index === 0, + createdAt: v.createdAt, + creator: v.creator ? { id: v.creator.id, name: v.creator.name } : null, + agent: v.agent ?? null, + })), + } + }, +}) diff --git a/packages/core/src/operations/version/remove-version.ts b/packages/core/src/operations/version/remove-version.ts new file mode 100644 index 00000000..e9923fcf --- /dev/null +++ b/packages/core/src/operations/version/remove-version.ts @@ -0,0 +1,33 @@ +import { removeVersion } from '@shumai/operations' +import { AuditAction } from '@shumai/dtos' +import { assetService } from '@shumai/core/src/asset/asset' +import { Permission, ResourceType } from '@shumai/core/src/authz/authz' +import { versionStackService } from '@shumai/core/src/versionStack/versionStack' +import { asBadRequest, badRequest } from '../errors' +import { implementOperation } from '../implement' + +export const removeVersionOp = implementOperation(removeVersion, { + // Editing the version means editing its stack: both are in the same project. + authz: (input) => [ + { permission: Permission.Edit, type: ResourceType.Asset, id: input.versionId }, + ], + prepare: async (input) => { + const version = await assetService.getAssetMeta(input.versionId) + const stack = version.parentId ? await assetService.getAssetMeta(version.parentId) : null + if (stack?.type !== 'version_stack') throw badRequest('This file is not in a version stack') + return { stackId: stack.id } + }, + execute: async (input, _ctx, { stackId }) => { + await asBadRequest(() => + versionStackService.removeVersionFromStack({ stackId, fileId: input.versionId }), + ) + return { versionId: input.versionId, stackId } + }, + audit: (input, output) => [ + { + action: AuditAction.version_stack_update, + itemId: output.stackId, + contextAssetId: input.versionId, + }, + ], +}) diff --git a/packages/core/src/upload/pending-upload.ts b/packages/core/src/upload/pending-upload.ts new file mode 100644 index 00000000..5d4a2fc9 --- /dev/null +++ b/packages/core/src/upload/pending-upload.ts @@ -0,0 +1,130 @@ +import * as crypto from 'crypto' +import { HTTPException } from 'hono/http-exception' +import { ulid } from 'ulid' +import { UPLOAD_TTL_SECONDS } from '@shumai/operations' +import { s3Service } from '@shumai/core/src/s3/s3' +import { sanitizeFilename } from '@shumai/core/src/utils/filename' + +/** What an upload creates once its file is in storage: a new file, or a new version of one. */ +export type PendingUploadKind = 'file' | 'version' + +/** An upload that was started but not finished yet. Carried by its signed upload ID. */ +export interface PendingUpload { + kind: PendingUploadKind + /** The user who started it; only they can finish it. */ + userId: string + /** The folder (file uploads) or the file / version stack (version uploads). */ + parentId: string + name: string + /** Storage key the file is uploaded to. */ + key: string + contentType: string + /** Creation Context metadata to record on the new file. */ + metadata?: Record + /** Expiry, in milliseconds since the epoch. */ + expiresAt: number +} + +export interface StartedUpload { + /** Opaque, signed ID that finishes the upload. */ + uploadId: string + /** Presigned URL to PUT the file's bytes to. */ + uploadUrl: string + key: string + expiresAt: Date +} + +const SIGNING_CONTEXT = 'shumai-pending-upload:v1' + +function signingSecret(): string { + return process.env.BETTER_AUTH_SECRET || 'shumai-local-storage-secret' +} + +function sign(payload: string): string { + return crypto + .createHmac('sha256', signingSecret()) + .update(`${SIGNING_CONTEXT}:${payload}`) + .digest('base64url') +} + +function invalid(): HTTPException { + return new HTTPException(400, { + message: 'Invalid upload ID: pass the uploadId returned by create_file or create_version.', + }) +} + +/** + * Two-step uploads for clients that send file bytes themselves (e.g. MCP clients): `start` + * returns a presigned URL and a signed upload ID; once the bytes are uploaded, `read` checks + * the ID so the caller can create the asset. Nothing is written to the database until then, + * so abandoned uploads leave no half-created assets behind. + */ +export class PendingUploadService { + /** How long the upload URL and the upload ID stay valid. */ + readonly ttlSeconds = UPLOAD_TTL_SECONDS + + async start(params: Omit): Promise { + const key = `files/${ulid()}/${sanitizeFilename(params.name)}` + const expiresAt = Date.now() + this.ttlSeconds * 1000 + const uploadUrl = await s3Service.presign( + this.bucket(), + key, + 'PUT', + undefined, + undefined, + undefined, + this.ttlSeconds, + ) + const pending: PendingUpload = { ...params, key, expiresAt } + const payload = Buffer.from(JSON.stringify(pending)).toString('base64url') + return { + uploadId: `${payload}.${sign(payload)}`, + uploadUrl, + key, + expiresAt: new Date(expiresAt), + } + } + + /** Verifies an upload ID for `userId` and returns the upload it describes. */ + read(uploadId: string, userId: string): PendingUpload { + const [payload, signature, ...rest] = uploadId.split('.') + if (!payload || !signature || rest.length > 0) throw invalid() + const expected = Buffer.from(sign(payload)) + const actual = Buffer.from(signature) + if (expected.length !== actual.length || !crypto.timingSafeEqual(expected, actual)) { + throw invalid() + } + + let pending: PendingUpload + try { + pending = JSON.parse(Buffer.from(payload, 'base64url').toString('utf8')) as PendingUpload + } catch { + throw invalid() + } + if (pending.userId !== userId) { + throw new HTTPException(403, { message: 'This upload was started by another user.' }) + } + if (Date.now() > pending.expiresAt) { + throw new HTTPException(400, { + message: 'This upload has expired. Start a new one with create_file or create_version.', + }) + } + return pending + } + + /** Size of the uploaded file, or null when nothing has been uploaded to the key yet. */ + async uploadedSize(key: string): Promise { + try { + const info = await s3Service.headObject(this.bucket(), key) + return info.size + } catch { + return null + } + } + + private bucket(): string { + return process.env.S3_BUCKET || 'shumai' + } +} + +export const pendingUploadService = new PendingUploadService() diff --git a/packages/dtos/src/auditLog.ts b/packages/dtos/src/auditLog.ts index db4f235d..4e99ded1 100644 --- a/packages/dtos/src/auditLog.ts +++ b/packages/dtos/src/auditLog.ts @@ -22,6 +22,8 @@ export enum AuditAction { folder_delete = 'folder_delete', asset_reparent = 'asset_reparent', asset_copy = 'asset_copy', + version_stack_create = 'version_stack_create', + version_stack_update = 'version_stack_update', share_create = 'share_create', share_update = 'share_update', share_delete = 'share_delete', diff --git a/packages/e2e/workflow/agent-operations.test.ts b/packages/e2e/workflow/agent-operations.test.ts index ac751534..19a6a0ad 100644 --- a/packages/e2e/workflow/agent-operations.test.ts +++ b/packages/e2e/workflow/agent-operations.test.ts @@ -4,6 +4,7 @@ import { setupTestDbHooks } from '@shumai/db/test' import { workflowService, TaskQueueAgent } from '@shumai/workflow-core' import { initAgentWorkflows } from '@shumai/agent' import { s3Service } from '@shumai/core/src/s3/s3' +import { metadataService } from '@shumai/core/src/metadata/metadata' import { projectService } from '@shumai/core/src/project/project' import { AgentHarness } from '@earendil-works/pi-agent-core' @@ -24,6 +25,18 @@ describe('Workflow E2E - agent Operation tools', () => { setupTestDbHooks() let rootFolderId = '' + let scenario: 'organize' | 'review' = 'organize' + // Used by the review scenario + let projectId = '' + let reviewFieldKey = '' + let promptFieldKey = '' + + const reply = (text: string) => + ({ + content: [{ type: 'text', text }], + usage: { input: 10, output: 20 }, + stopReason: 'stop', + }) as unknown as Awaited> beforeAll(async () => { process.env.S3_BUCKET = 'shumai-e2e-test-bucket-agent-ops' @@ -36,16 +49,56 @@ describe('Workflow E2E - agent Operation tools', () => { ) { const tool = (name: string) => this.getTools().find((t) => t.name === name) as unknown as ExecutableTool | undefined + const call = async (name: string, params: Record) => { + const t = tool(name) + if (!t) throw new Error(`missing tool ${name}`) + return JSON.parse(toolText(await t.execute(`call-${name}`, params))) as unknown + } + + if (scenario === 'review') { + const found = (await call('search_assets', { parent: rootFolderId, query: 'brief' })) as { + data: Array<{ id: string; name: string }> + } + const assetId = found.data[0].id + const comment = (await call('create_comment', { + assetId, + message: 'The logo is too small', + })) as { id: string } + const listed = (await call('list_comments', { assetId })) as { + data: Array<{ id: string; message: string }> + } + await call('resolve_comment', { commentId: comment.id }) + const { fields } = (await call('list_metadata_fields', { projectId })) as { + fields: Array<{ key: string; creationContext: boolean }> + } + await call('update_asset_metadata', { + assetId, + values: { [reviewFieldKey]: 'Needs changes' }, + }) + const file = (await call('create_file', { + parent: rootFolderId, + name: 'review-notes.md', + content: '# Review\n\nLogo too small.', + metadata: { [promptFieldKey]: 'Summarize the review' }, + })) as { id: string } + const creationFields = fields.filter((f) => f.creationContext).map((f) => f.key) + return reply( + [ + `found:${found.data.map((a) => a.name).join(',')}`, + `comment:${comment.id}`, + `listed:${listed.data.map((c) => c.message).join(',')}`, + `creation_fields:${creationFields.join(',')}`, + `file:${file.id}`, + `complete_tool:${tool('complete_upload') ? 'present' : 'absent'}`, + ].join('|'), + ) + } const createFolder = tool('create_folder') const listAssets = tool('list_assets') const deleteAsset = tool('delete_asset') if (!createFolder || !listAssets) { - return { - content: [{ type: 'text', text: 'MISSING_OPERATION_TOOLS' }], - usage: { input: 1, output: 1 }, - stopReason: 'stop', - } as unknown as Awaited> + return reply('MISSING_OPERATION_TOOLS') } const created = JSON.parse( @@ -63,11 +116,7 @@ describe('Workflow E2E - agent Operation tools', () => { // delete_asset is denied by default and must not be registered `delete_tool:${deleteAsset ? 'present' : 'absent'}`, ].join('|') - return { - content: [{ type: 'text', text: summary }], - usage: { input: 10, output: 20 }, - stopReason: 'stop', - } as unknown as Awaited> + return reply(summary) }) await workflowService.startWorkers(TaskQueueAgent) @@ -84,22 +133,24 @@ describe('Workflow E2E - agent Operation tools', () => { } }) - it('creates and lists assets through Operations, attributed to the user and agent', async () => { - const team = await prisma.team.create({ data: { name: 'E2E Agent Ops Team' } }) + /** A team, project, chat agent, and a user comment asking the agent to act; returns the task. */ + async function setupChat(label: string, message: string) { + const team = await prisma.team.create({ data: { name: `E2E Agent Ops Team ${label}` } }) const regularUser = await prisma.user.create({ - data: { name: 'Ops User', email: 'ops-user@example.com', type: 'human' }, + data: { name: 'Ops User', email: `ops-user-${label}@example.com`, type: 'human' }, }) await prisma.teamMember.create({ data: { teamId: team.id, userId: regularUser.id, role: 'owner' }, }) const project = await projectService.createProject(regularUser, { teamId: team.id, - name: 'E2E Agent Ops Project', + name: `E2E Agent Ops Project ${label}`, }) rootFolderId = project.rootFolder! + projectId = project.id const agentUser = await prisma.user.create({ - data: { name: 'E2E Ops Agent', email: 'e2e-ops-agent@shumai.ai', type: 'agent' }, + data: { name: 'E2E Ops Agent', email: `e2e-ops-agent-${label}@shumai.ai`, type: 'agent' }, }) await prisma.teamMember.create({ data: { teamId: team.id, userId: agentUser.id, role: 'editor' }, @@ -136,13 +187,9 @@ describe('Workflow E2E - agent Operation tools', () => { config: { provider: 'google', model: 'gemini' }, }, }) + const sessionId = `agent-ops-session-${label}` await prisma.agentSession.create({ - data: { - id: 'agent-ops-session', - agentId: agentUser.id, - userId: regularUser.id, - cwd: process.cwd(), - }, + data: { id: sessionId, agentId: agentUser.id, userId: regularUser.id, cwd: process.cwd() }, }) const asset = await prisma.asset.create({ data: { @@ -155,12 +202,7 @@ describe('Workflow E2E - agent Operation tools', () => { }, }) const userComment = await prisma.assetComment.create({ - data: { - assetId: asset.id, - message: 'Create a folder called Agent Folder and list the root', - creatorId: regularUser.id, - sessionId: 'agent-ops-session', - }, + data: { assetId: asset.id, message, creatorId: regularUser.id, sessionId }, }) const task = await prisma.workflowTask.create({ @@ -174,13 +216,29 @@ describe('Workflow E2E - agent Operation tools', () => { projectId: project.id, agent: { agentId: agentUser.id, - sessionId: 'agent-ops-session', + sessionId, userCommentId: userComment.id, userId: regularUser.id, }, }, }, }) + return { team, project, regularUser, agentUser, asset, userComment, task } + } + + async function agentReply(assetId: string, userCommentId: string) { + const [reply] = await prisma.assetComment.findMany({ + where: { assetId, replyToId: userCommentId }, + }) + return reply?.message ?? '' + } + + it('creates and lists assets through Operations, attributed to the user and agent', async () => { + scenario = 'organize' + const { team, project, regularUser, agentUser, asset, userComment, task } = await setupChat( + 'organize', + 'Create a folder called Agent Folder and list the root', + ) const completedTask = await workflowService.executeWait(task, 45000) expect(completedTask.status).toBe('completed') @@ -203,11 +261,83 @@ describe('Workflow E2E - agent Operation tools', () => { via: 'agent', }) - const [reply] = await prisma.assetComment.findMany({ - where: { assetId: asset.id, replyToId: userComment.id }, + const message = await agentReply(asset.id, userComment.id) + expect(message).toContain(`created:${folder.id}`) + expect(message).toMatch(/listed:.*Agent Folder/) + expect(message).toContain('delete_tool:absent') + }, 50000) + + it('reviews a file: search, comment, resolve, set metadata, and write notes with Creation Context', async () => { + scenario = 'review' + const setup = await setupChat('review', 'Review the brief and write up notes') + const { team, project, regularUser, agentUser, asset, userComment, task } = setup + const review = await metadataService.createProjectField(project.id, { + config: { name: 'Review', type: 'text' }, + description: '', }) - expect(reply?.message).toContain(`created:${folder.id}`) - expect(reply?.message).toMatch(/listed:.*Agent Folder/) - expect(reply?.message).toContain('delete_tool:absent') + const prompt = await metadataService.createProjectField(project.id, { + config: { name: 'Prompt', type: 'text', autofillSource: 'CREATION_CONTEXT' }, + description: 'What the agent was asked to do', + }) + reviewFieldKey = review.key + promptFieldKey = prompt.key + + const completedTask = await workflowService.executeWait(task, 45000) + expect(completedTask.status).toBe('completed') + + const message = await agentReply(asset.id, userComment.id) + expect(message).toContain('found:brief.png') + expect(message).toMatch(/listed:[^|]*The logo is too small/) + expect(message).toContain(`creation_fields:${prompt.key}`) + // The agent finishes its own uploads; complete_upload is an MCP-only tool + expect(message).toContain('complete_tool:absent') + + // The comment is posted as the user, resolved, and audited as coming from the agent + const comment = await prisma.assetComment.findFirstOrThrow({ + where: { assetId: asset.id, message: 'The logo is too small' }, + }) + expect(comment.creatorId).toBe(regularUser.id) + expect(comment.isCompleted).toBe(true) + for (const action of ['comment_create', 'comment_complete']) { + const audit = await prisma.auditLog.findFirstOrThrow({ + where: { action, itemId: comment.id }, + }) + expect(audit).toMatchObject({ + teamId: team.id, + userId: regularUser.id, + agentId: agentUser.id, + via: 'agent', + }) + } + + const reviewValue = await prisma.assetMetadataValue.findFirstOrThrow({ + where: { assetId: asset.id, fieldKey: review.key }, + }) + expect(reviewValue.stringValue).toBe('Needs changes') + + // The notes file is stored, attributed to the user and agent, with Creation Context + const fileId = /file:([A-Z0-9]+)/.exec(message)?.[1] + const notes = await prisma.asset.findUniqueOrThrow({ + where: { id: fileId }, + include: { storageKey: true, metadataValues: true }, + }) + expect(notes).toMatchObject({ + name: 'review-notes.md', + parentId: rootFolderId, + creatorId: regularUser.id, + agentId: agentUser.id, + }) + const stored = await s3Service.getObject( + 'shumai-e2e-test-bucket-agent-ops', + notes.storageKey!.key, + ) + expect(stored.buffer.toString('utf-8')).toBe('# Review\n\nLogo too small.') + expect(notes.metadataValues).toContainEqual( + expect.objectContaining({ fieldKey: prompt.key, stringValue: 'Summarize the review' }), + ) + const fileAudit = await prisma.auditLog.findFirstOrThrow({ + where: { action: 'file_create', itemId: notes.id }, + }) + expect(fileAudit).toMatchObject({ agentId: agentUser.id, via: 'agent' }) }, 50000) }) diff --git a/packages/operations/src/asset/copy-assets.ts b/packages/operations/src/asset/copy-assets.ts new file mode 100644 index 00000000..594e7430 --- /dev/null +++ b/packages/operations/src/asset/copy-assets.ts @@ -0,0 +1,36 @@ +import { z } from 'zod' +import { defineOperation } from '../define' + +export const copyAssets = defineOperation({ + name: 'copy_assets', + title: 'Copy Assets', + description: + 'Copy one or more files or folders (with everything inside them) into a folder of the ' + + 'same team, e.g. into another project. The originals are left unchanged. Returns the IDs ' + + 'of the copies, in the same order as assetIds.', + input: z.object({ + assetIds: z + .array(z.string().min(1)) + .min(1) + .describe('The IDs of the files or folders to copy. At least one asset ID is required.'), + newParentId: z.string().min(1).describe('The destination folder ID to copy the assets into.'), + withComments: z + .boolean() + .optional() + .describe('Also copy the comments on the files (default false).'), + }), + output: z.object({ + copiedAssetIds: z.array(z.string()).describe('IDs of the copies, in the order of assetIds.'), + newParentId: z.string(), + }), + surfaces: ['agent', 'mcp', 'cli'], + annotations: { readOnly: false, destructive: false }, + cli: { + command: ['copy'], + aliases: ['cp'], + positional: ['assetIds'], + flags: { newParentId: ['-p', '--parent'] }, + format: (output) => + `Copied ${output.copiedAssetIds.length} asset(s) to parent ${output.newParentId}: ${output.copiedAssetIds.join(', ')}`, + }, +}) diff --git a/packages/operations/src/asset/get-folder-instructions.ts b/packages/operations/src/asset/get-folder-instructions.ts new file mode 100644 index 00000000..d568a417 --- /dev/null +++ b/packages/operations/src/asset/get-folder-instructions.ts @@ -0,0 +1,26 @@ +import { z } from 'zod' +import { defineOperation } from '../define' + +export const getFolderInstructions = defineOperation({ + name: 'get_folder_instructions', + title: 'Get Folder Instructions', + description: + "Read a folder's instructions for AI agents (its AGENTS.md): conventions such as naming " + + 'rules, deliverable specs, or how the team reviews work in that folder. Check them before ' + + 'adding or changing files in a folder. Returns null content when the folder has none.', + input: z.object({ + folderId: z.string().min(1).describe("The folder ID (e.g. a project's rootFolderId)."), + }), + output: z.object({ + folderId: z.string(), + content: z.string().nullable().describe('The instructions (Markdown), or null when unset.'), + }), + surfaces: ['agent', 'mcp', 'cli'], + annotations: { readOnly: true, destructive: false, idempotent: true }, + cli: { + command: ['instructions'], + description: "Show a folder's instructions for AI agents (AGENTS.md).", + positional: ['folderId'], + format: (output) => output.content ?? '(This folder has no instructions.)', + }, +}) diff --git a/packages/operations/src/asset/search-assets.ts b/packages/operations/src/asset/search-assets.ts new file mode 100644 index 00000000..916bb015 --- /dev/null +++ b/packages/operations/src/asset/search-assets.ts @@ -0,0 +1,116 @@ +import { z } from 'zod' +import { defineOperation } from '../define' +import { assetSummarySchema, MAX_PAGE_SIZE, pageInfoSchema } from '../schemas' + +/** Operators the search supports (`is` in the web app's list has no search behavior). */ +export const SEARCH_CONDITION_OPERATORS = [ + 'eq', + 'neq', + 'gt', + 'gte', + 'lt', + 'lte', + 'contains', + 'notContains', + 'isEmpty', + 'isNotEmpty', + 'in', + 'notIn', + 'hasAny', + 'hasAll', + 'hasNone', + 'isWithin', +] as const + +const conditionSchema = z.object({ + field: z + .string() + .min(1) + .describe( + 'Metadata field key from list_metadata_fields (e.g. "status"), or one of "name", ' + + '"sizeByte", "createdAt", "updatedAt".', + ), + operator: z + .enum(SEARCH_CONDITION_OPERATORS) + .describe( + 'Comparison: eq/neq for exact values (text, toggle, or a select option id), ' + + 'gt/gte/lt/lte for numbers and dates, contains/notContains for text, in/notIn for ' + + 'one of a list, hasAny/hasAll/hasNone for selectMulti fields, isWithin for a date ' + + 'range, isEmpty/isNotEmpty (no value needed).', + ), + value: z + .union([z.string(), z.number(), z.boolean(), z.array(z.string())]) + .optional() + .describe( + 'Value to compare with. For select fields use option IDs from list_metadata_fields; ' + + 'for in/notIn/hasAny/hasAll/hasNone pass a list.', + ), +}) + +export const searchAssets = defineOperation({ + name: 'search_assets', + title: 'Search Assets', + description: + 'Search for files (or folders) under a folder and all of its subfolders, by name, by ' + + 'meaning ("semantic": e.g. "sunset over the sea", when the team has AI search enabled), ' + + 'and/or by metadata conditions (e.g. status is "approved"). Results are paginated: when ' + + 'pageInfo.hasNextPage is true, call again with after set to pageInfo.endCursor.', + input: z.object({ + parent: z + .string() + .min(1) + .describe("The folder to search in, e.g. a project's rootFolderId to search everything."), + query: z.string().optional().describe('Text to search for in names (or by meaning).'), + semantic: z + .boolean() + .optional() + .describe( + 'Search by meaning instead of by name (default false). Needs a query and AI search ' + + 'enabled for the team.', + ), + type: z + .enum(['file', 'folder']) + .optional() + .describe("Search 'file' (default; includes version stacks) or 'folder'."), + recursive: z + .boolean() + .optional() + .describe('Search subfolders too (default true). Set false for the folder itself only.'), + conditions: z + .array(conditionSchema) + .optional() + .describe('Metadata filters. Combined with AND unless matchAny is true.'), + matchAny: z + .boolean() + .optional() + .describe('Match assets meeting any condition instead of all of them (default false).'), + first: z + .number() + .int() + .min(1) + .max(MAX_PAGE_SIZE) + .optional() + .describe(`Maximum number of results to return (at most ${MAX_PAGE_SIZE}).`), + after: z + .string() + .optional() + .describe('Cursor from a previous response (pageInfo.endCursor) to fetch the next page.'), + }), + output: z.object({ + data: z.array(assetSummarySchema), + pageInfo: pageInfoSchema, + total: z.number(), + }), + surfaces: ['agent', 'mcp', 'cli'], + annotations: { readOnly: true, destructive: false, idempotent: true }, + cli: { + command: ['search'], + description: 'Search for files under a folder by name or by meaning (--semantic).', + positional: ['query'], + flags: { parent: ['-p', '--parent'] }, + // Metadata conditions are structured; agents pass them, the CLI searches by name. The CLI + // always searches subfolders (a boolean flag could only turn on the default). + omit: ['conditions', 'matchAny', 'recursive'], + defaults: { first: MAX_PAGE_SIZE }, + }, +}) diff --git a/packages/operations/src/comment/create-comment.ts b/packages/operations/src/comment/create-comment.ts new file mode 100644 index 00000000..42194f57 --- /dev/null +++ b/packages/operations/src/comment/create-comment.ts @@ -0,0 +1,40 @@ +import { z } from 'zod' +import { defineOperation } from '../define' + +export const createComment = defineOperation({ + name: 'create_comment', + title: 'Create Comment', + description: + 'Post a review comment on a file, or reply to an existing comment thread. The comment is ' + + 'posted as you, and the people involved are notified. For a video or audio file, set ' + + '"second" to pin the comment to a timecode. For a version stack, the comment goes on its ' + + 'latest version.', + input: z.object({ + assetId: z.string().min(1).describe('The file or version stack to comment on.'), + message: z.string().trim().min(1).max(10_000).describe('The comment text.'), + replyToId: z + .string() + .min(1) + .optional() + .describe('ID of the comment to reply to (from list_comments). Omit for a new thread.'), + second: z + .number() + .min(0) + .optional() + .describe('Timecode in seconds on a video or audio file. Omit for other files.'), + }), + output: z.object({ + id: z.string().describe('The new comment ID.'), + assetId: z.string().describe('The file the comment is on (the latest version for a stack).'), + replyToId: z.string().nullable().describe('The thread it replies to, if any.'), + }), + surfaces: ['agent', 'mcp', 'cli'], + annotations: { readOnly: false, destructive: false }, + cli: { + command: ['comment', 'add'], + description: 'Comment on a file, or reply to a comment with --reply-to.', + positional: ['assetId', 'message'], + flags: { replyToId: ['--reply-to'], second: ['-t', '--at'] }, + format: (output) => `Posted comment ${output.id}`, + }, +}) diff --git a/packages/operations/src/comment/list-comments.ts b/packages/operations/src/comment/list-comments.ts new file mode 100644 index 00000000..70590094 --- /dev/null +++ b/packages/operations/src/comment/list-comments.ts @@ -0,0 +1,79 @@ +import { z } from 'zod' +import { defineOperation } from '../define' +import { MAX_PAGE_SIZE, pageInfoSchema } from '../schemas' + +const commentAuthorSchema = z.object({ + id: z.string(), + name: z.string(), +}) + +const commentFields = { + id: z.string(), + message: z.string(), + author: commentAuthorSchema, + /** Timecode in seconds on a video or audio file (the viewing angle for 3D models). */ + second: z.number().nullable(), + /** Whether markup was drawn on the frame or page. */ + hasMarkup: z.boolean(), + attachmentCount: z.number(), + createdAt: z.string(), +} + +export const commentReplySchema = z.object(commentFields) + +export const commentThreadSchema = z.object({ + ...commentFields, + resolved: z.boolean(), + replies: z.array(commentReplySchema), +}) +export type CommentThread = z.infer + +export const listComments = defineOperation({ + name: 'list_comments', + title: 'List Comments', + description: + 'List the review comments on a file, oldest first, each with its replies. For a version ' + + 'stack, lists the comments on its latest version. "second" is the timecode on a video or ' + + 'audio file. Results are paginated: when pageInfo.hasNextPage is true, call again with ' + + 'after set to pageInfo.endCursor.', + input: z.object({ + assetId: z.string().min(1).describe('The file or version stack ID.'), + first: z + .number() + .int() + .min(1) + .max(MAX_PAGE_SIZE) + .optional() + .describe(`Maximum number of comment threads to return (at most ${MAX_PAGE_SIZE}).`), + after: z + .string() + .optional() + .describe('Cursor from a previous response (pageInfo.endCursor) to fetch the next page.'), + }), + output: z.object({ + data: z.array(commentThreadSchema), + pageInfo: pageInfoSchema, + total: z.number(), + }), + surfaces: ['agent', 'mcp', 'cli'], + annotations: { readOnly: true, destructive: false, idempotent: true }, + cli: { + command: ['comment', 'ls'], + description: 'List the comments on a file, with their replies.', + positional: ['assetId'], + defaults: { first: MAX_PAGE_SIZE }, + format: (output) => { + if (output.data.length === 0) return 'No comments.' + const lines: string[] = [] + for (const thread of output.data) { + const at = thread.second !== null ? ` @${thread.second}s` : '' + const status = thread.resolved ? ' [resolved]' : '' + lines.push(`${thread.id}${at}${status} ${thread.author.name}: ${thread.message}`) + for (const reply of thread.replies) { + lines.push(` ↳ ${reply.id} ${reply.author.name}: ${reply.message}`) + } + } + return lines.join('\n') + }, + }, +}) diff --git a/packages/operations/src/comment/resolve-comment.ts b/packages/operations/src/comment/resolve-comment.ts new file mode 100644 index 00000000..c4e78ceb --- /dev/null +++ b/packages/operations/src/comment/resolve-comment.ts @@ -0,0 +1,30 @@ +import { z } from 'zod' +import { defineOperation } from '../define' + +export const resolveComment = defineOperation({ + name: 'resolve_comment', + title: 'Resolve Comment', + description: + 'Mark a comment thread as resolved (done), e.g. after addressing the feedback in a new ' + + 'version. Set reopen to true to mark it as unresolved again.', + input: z.object({ + commentId: z.string().min(1).describe('The comment ID (from list_comments).'), + reopen: z + .boolean() + .optional() + .describe('Mark the comment as unresolved again instead (default false).'), + }), + output: z.object({ + commentId: z.string(), + resolved: z.boolean(), + }), + surfaces: ['agent', 'mcp', 'cli'], + annotations: { readOnly: false, destructive: false, idempotent: true }, + cli: { + command: ['comment', 'resolve'], + description: 'Mark a comment as resolved, or unresolved again with --reopen.', + positional: ['commentId'], + format: (output) => + `Comment ${output.commentId} is ${output.resolved ? 'resolved' : 'unresolved'}`, + }, +}) diff --git a/packages/operations/src/index.ts b/packages/operations/src/index.ts index f0e68615..022b1907 100644 --- a/packages/operations/src/index.ts +++ b/packages/operations/src/index.ts @@ -2,11 +2,25 @@ export * from './define' export * from './schemas' export * from './registry' export { dropNullOptionals } from './null-optionals' +export { copyAssets } from './asset/copy-assets' export { createFolder } from './asset/create-folder' export { deleteAsset } from './asset/delete-asset' +export { getFolderInstructions } from './asset/get-folder-instructions' export { listAssets } from './asset/list-assets' export { moveAssets } from './asset/move-assets' export { renameAsset } from './asset/rename-asset' +export * from './asset/search-assets' export * from './asset/read-asset' export * from './asset/download-asset' +export * from './comment/list-comments' +export { createComment } from './comment/create-comment' +export { resolveComment } from './comment/resolve-comment' +export * from './metadata/list-metadata-fields' +export * from './metadata/update-asset-metadata' export { listProjects } from './project/list-projects' +export * from './upload/create-file' +export { createVersion } from './upload/create-version' +export { completeUpload } from './upload/complete-upload' +export { createVersionStack } from './version/create-version-stack' +export * from './version/list-versions' +export { removeVersion } from './version/remove-version' diff --git a/packages/operations/src/metadata/list-metadata-fields.ts b/packages/operations/src/metadata/list-metadata-fields.ts new file mode 100644 index 00000000..c01fd490 --- /dev/null +++ b/packages/operations/src/metadata/list-metadata-fields.ts @@ -0,0 +1,68 @@ +import { z } from 'zod' +import { defineOperation } from '../define' + +export const METADATA_FIELD_TYPES = [ + 'text', + 'longText', + 'select', + 'selectMulti', + 'rating', + 'number', + 'toggle', + 'date', + 'user', + 'userMulti', +] as const + +export const metadataFieldSchema = z.object({ + key: z.string().describe('Key to use in update_asset_metadata, search_assets, and metadata.'), + name: z.string(), + type: z.string().describe(`One of: ${METADATA_FIELD_TYPES.join(', ')}.`), + description: z.string(), + readOnly: z.boolean().describe('Set by Shumai; cannot be changed.'), + creationContext: z + .boolean() + .describe( + 'A Creation Context field: whoever creates a file records it (e.g. the prompt or model ' + + 'used), through the metadata of create_file and create_version.', + ), + options: z + .array(z.object({ id: z.string(), name: z.string() })) + .optional() + .describe('Choices of a select or selectMulti field: values use the option id.'), +}) +export type MetadataFieldSummary = z.infer + +export const listMetadataFields = defineOperation({ + name: 'list_metadata_fields', + title: 'List Metadata Fields', + description: + "List a project's metadata fields (e.g. status, rating, tags, custom fields), with their " + + 'type and choices. Use the keys with update_asset_metadata, as search_assets conditions, ' + + 'and for the Creation Context metadata of create_file and create_version.', + input: z.object({ + projectId: z.string().min(1).describe('The project ID (from list_projects).'), + }), + output: z.object({ + fields: z.array(metadataFieldSchema), + }), + surfaces: ['agent', 'mcp', 'cli'], + annotations: { readOnly: true, destructive: false, idempotent: true }, + cli: { + command: ['field', 'ls'], + description: "List a project's metadata fields.", + positional: ['projectId'], + format: (output) => + output.fields + .map((f) => { + const flags = [f.type, f.readOnly ? 'read-only' : '', f.creationContext ? 'creation' : ''] + .filter(Boolean) + .join(', ') + const options = f.options?.length + ? ` [${f.options.map((o) => `${o.id}=${o.name}`).join(', ')}]` + : '' + return `${f.key} ${f.name} (${flags})${options}` + }) + .join('\n'), + }, +}) diff --git a/packages/operations/src/metadata/update-asset-metadata.ts b/packages/operations/src/metadata/update-asset-metadata.ts new file mode 100644 index 00000000..357a7072 --- /dev/null +++ b/packages/operations/src/metadata/update-asset-metadata.ts @@ -0,0 +1,36 @@ +import { z } from 'zod' +import { defineOperation } from '../define' + +/** Describes metadata values; shared with the Creation Context metadata of uploads. */ +export const METADATA_VALUES_DESCRIPTION = + 'Values keyed by field key (from list_metadata_fields). Text fields take a string, ' + + 'number and rating fields a number, toggle fields a boolean, date fields an ISO date ' + + 'string, select fields an option id, and selectMulti fields a list of option ids. To add a ' + + 'new choice to a select field, pass {"newOption": {"value": "Name"}} instead of an id. ' + + 'Use null to clear a value.' + +export const updateAssetMetadata = defineOperation({ + name: 'update_asset_metadata', + title: 'Update Asset Metadata', + description: + 'Set metadata values on a file, e.g. its status, rating, tags, or custom fields. Only the ' + + 'given fields change. Call list_metadata_fields first to get the field keys and choices. ' + + 'For a version stack, the values are set on its latest version.', + input: z.object({ + assetId: z.string().min(1).describe('The file or version stack ID.'), + values: z.record(z.string(), z.unknown()).describe(METADATA_VALUES_DESCRIPTION), + }), + output: z.object({ + assetId: z.string(), + updatedKeys: z.array(z.string()), + }), + surfaces: ['agent', 'mcp', 'cli'], + annotations: { readOnly: false, destructive: false, idempotent: true }, + cli: { + command: ['meta', 'set'], + description: + 'Set metadata values on a file, as JSON keyed by field key, e.g. --values \'{"status":"approved"}\'.', + positional: ['assetId'], + format: (output) => `Updated ${output.updatedKeys.join(', ')} on ${output.assetId}`, + }, +}) diff --git a/packages/operations/src/registry.test.ts b/packages/operations/src/registry.test.ts index 9b514485..f4dfd439 100644 --- a/packages/operations/src/registry.test.ts +++ b/packages/operations/src/registry.test.ts @@ -15,17 +15,31 @@ describe('operation registry', () => { expect(new Set(names).size).toBe(names.length) }) - it('contains the asset and project operations', () => { + it('contains the asset, project, comment, metadata, version, and upload operations', () => { expect(operationDefinitions.map((d) => d.name).sort()).toEqual([ + 'complete_upload', + 'copy_assets', + 'create_comment', + 'create_file', 'create_folder', + 'create_version', + 'create_version_stack', 'delete_asset', 'download_asset', 'get_asset_render', + 'get_folder_instructions', 'list_assets', + 'list_comments', + 'list_metadata_fields', 'list_projects', + 'list_versions', 'move_assets', 'read_asset', + 'remove_version', 'rename_asset', + 'resolve_comment', + 'search_assets', + 'update_asset_metadata', ]) }) @@ -50,12 +64,29 @@ describe('operation registry', () => { expect(readOnly.map((d) => d.name).sort()).toEqual([ 'download_asset', 'get_asset_render', + 'get_folder_instructions', 'list_assets', + 'list_comments', + 'list_metadata_fields', 'list_projects', + 'list_versions', 'read_asset', + 'search_assets', ]) }) + it('exposes uploads on the agent and MCP only, and complete_upload on MCP only', () => { + // The CLI uploads with its own `upload` and `create-version` commands, and the agent's + // create tools complete their uploads themselves. + const surfaces = (name: string) => getOperationDefinition(name)?.surfaces + expect(surfaces('create_file')).toEqual(['agent', 'mcp']) + expect(surfaces('create_version')).toEqual(['agent', 'mcp']) + expect(surfaces('complete_upload')).toEqual(['mcp']) + const cli = getOperationDefinitionsForSurface('cli').map((d) => d.name) + expect(cli).not.toContain('create_file') + expect(cli).not.toContain('complete_upload') + }) + it.each(operationDefinitions.map((d) => [d.name, d] as const))( '%s exports an object JSON Schema with described fields', (_name, definition) => { @@ -85,20 +116,30 @@ describe('operation registry', () => { ) it('keeps legacy CLI invocations mapped', () => { - const commands = operationDefinitions.map((d) => [ - d.name, - [...(d.cli?.command ?? []), ...(d.cli?.aliases ?? [])], - ]) + const commands = operationDefinitions + .filter((d) => d.cli) + .map((d) => [d.name, [...(d.cli?.command ?? []), ...(d.cli?.aliases ?? [])]]) expect(commands).toEqual([ ['list_projects', ['project', 'ls']], ['list_assets', ['ls']], + ['search_assets', ['search']], ['create_folder', ['mkdir']], ['rename_asset', ['rename']], ['move_assets', ['move', 'mv']], + ['copy_assets', ['copy', 'cp']], ['delete_asset', ['delete', 'rm']], ['read_asset', ['read']], ['get_asset_render', ['render']], ['download_asset', ['download']], + ['get_folder_instructions', ['instructions']], + ['list_comments', ['comment', 'ls']], + ['create_comment', ['comment', 'add']], + ['resolve_comment', ['comment', 'resolve']], + ['list_metadata_fields', ['field', 'ls']], + ['update_asset_metadata', ['meta', 'set']], + ['create_version_stack', ['version', 'stack']], + ['list_versions', ['version', 'ls']], + ['remove_version', ['version', 'unstack']], ]) }) diff --git a/packages/operations/src/registry.ts b/packages/operations/src/registry.ts index f3398115..69ebafe6 100644 --- a/packages/operations/src/registry.ts +++ b/packages/operations/src/registry.ts @@ -1,12 +1,26 @@ +import { copyAssets } from './asset/copy-assets' import { createFolder } from './asset/create-folder' import { deleteAsset } from './asset/delete-asset' import { downloadAsset } from './asset/download-asset' +import { getFolderInstructions } from './asset/get-folder-instructions' import { listAssets } from './asset/list-assets' import { moveAssets } from './asset/move-assets' import { getAssetRender, readAsset } from './asset/read-asset' import { renameAsset } from './asset/rename-asset' +import { searchAssets } from './asset/search-assets' +import { createComment } from './comment/create-comment' +import { listComments } from './comment/list-comments' +import { resolveComment } from './comment/resolve-comment' import type { AnyOperationDefinition, Surface } from './define' +import { listMetadataFields } from './metadata/list-metadata-fields' +import { updateAssetMetadata } from './metadata/update-asset-metadata' import { listProjects } from './project/list-projects' +import { completeUpload } from './upload/complete-upload' +import { createFile } from './upload/create-file' +import { createVersion } from './upload/create-version' +import { createVersionStack } from './version/create-version-stack' +import { listVersions } from './version/list-versions' +import { removeVersion } from './version/remove-version' /** * Every Operation definition. Adding one here requires a matching implementation in @@ -15,13 +29,27 @@ import { listProjects } from './project/list-projects' export const operationDefinitions = [ listProjects, listAssets, + searchAssets, createFolder, renameAsset, moveAssets, + copyAssets, deleteAsset, readAsset, getAssetRender, downloadAsset, + getFolderInstructions, + createFile, + createVersion, + completeUpload, + listComments, + createComment, + resolveComment, + listMetadataFields, + updateAssetMetadata, + createVersionStack, + listVersions, + removeVersion, ] as const export type RegisteredOperationDefinition = (typeof operationDefinitions)[number] diff --git a/packages/operations/src/upload/complete-upload.ts b/packages/operations/src/upload/complete-upload.ts new file mode 100644 index 00000000..b957a240 --- /dev/null +++ b/packages/operations/src/upload/complete-upload.ts @@ -0,0 +1,19 @@ +import { z } from 'zod' +import { defineOperation } from '../define' +import { assetSummarySchema } from '../schemas' + +export const completeUpload = defineOperation({ + name: 'complete_upload', + title: 'Complete Upload', + description: + 'Finish an upload started with create_file or create_version, after the file bytes were ' + + 'PUT to its uploadUrl. Creates the file (or the new version) and starts processing it ' + + '(previews, transcoding). Returns the new file. Calling it again for the same upload ' + + 'returns the same file.', + input: z.object({ + uploadId: z.string().min(1).describe('The uploadId returned by create_file or create_version.'), + }), + output: assetSummarySchema, + surfaces: ['mcp'], + annotations: { readOnly: false, destructive: false, idempotent: true }, +}) diff --git a/packages/operations/src/upload/create-file.ts b/packages/operations/src/upload/create-file.ts new file mode 100644 index 00000000..bfab107c --- /dev/null +++ b/packages/operations/src/upload/create-file.ts @@ -0,0 +1,55 @@ +import { z } from 'zod' +import { defineOperation } from '../define' +import { METADATA_VALUES_DESCRIPTION } from '../metadata/update-asset-metadata' + +/** How long an upload started by create_file or create_version stays valid. */ +export const UPLOAD_TTL_SECONDS = 60 * 60 + +/** Creation Context metadata, recorded by whoever creates a file. */ +export const creationMetadataSchema = z + .record(z.string(), z.unknown()) + .optional() + .describe( + "Values for the project's Creation Context fields (list_metadata_fields, creationContext: " + + 'true), such as the prompt or model used to make the file. Only those fields are ' + + `accepted. ${METADATA_VALUES_DESCRIPTION}`, + ) + +export const startedUploadSchema = z.object({ + uploadId: z.string().describe('Pass to complete_upload once the file is uploaded.'), + uploadUrl: z.string().describe('Upload the raw file bytes here with an HTTP PUT request.'), + method: z.literal('PUT'), + expiresAt: z.string().describe('When uploadUrl and uploadId stop working (about an hour).'), + /** Storage key; only returned to Shumai's built-in agent, which uploads from its sandbox. */ + key: z.string().optional(), +}) +export type StartedUploadOutput = z.infer + +const UPLOAD_STEPS = + 'Uploading takes three steps: call this tool, PUT the raw file bytes to uploadUrl (e.g. ' + + '`curl -T ""`), then call complete_upload with uploadId to create the ' + + `asset. The upload URL expires after about an hour.` + +export const createFile = defineOperation({ + name: 'create_file', + title: 'Create File', + description: `Start uploading a new file into a folder. ${UPLOAD_STEPS}`, + input: z.object({ + parent: z.string().min(1).describe('The folder to create the file in.'), + name: z + .string() + .trim() + .min(1) + .max(255) + .describe('File name including its extension, e.g. "storyboard.pdf".'), + contentType: z + .string() + .min(1) + .optional() + .describe('MIME type, e.g. "image/png". Detected from the name when omitted.'), + metadata: creationMetadataSchema, + }), + output: startedUploadSchema, + surfaces: ['agent', 'mcp'], + annotations: { readOnly: false, destructive: false }, +}) diff --git a/packages/operations/src/upload/create-version.ts b/packages/operations/src/upload/create-version.ts new file mode 100644 index 00000000..1cb1ec6b --- /dev/null +++ b/packages/operations/src/upload/create-version.ts @@ -0,0 +1,31 @@ +import { z } from 'zod' +import { defineOperation } from '../define' +import { creationMetadataSchema, startedUploadSchema } from './create-file' + +export const createVersion = defineOperation({ + name: 'create_version', + title: 'Create Version', + description: + 'Start uploading a new version of an existing file. The new version becomes the current ' + + 'one; a plain file becomes a version stack. Uploading takes three steps: call this tool, ' + + 'PUT the raw file bytes to uploadUrl (e.g. `curl -T ""`), then call ' + + 'complete_upload with uploadId. The upload URL expires after about an hour.', + input: z.object({ + parent: z.string().min(1).describe('The file or version stack to add a version to.'), + name: z + .string() + .trim() + .min(1) + .max(255) + .describe('File name of the new version including its extension, e.g. "cut_v3.mp4".'), + contentType: z + .string() + .min(1) + .optional() + .describe('MIME type, e.g. "video/mp4". Detected from the name when omitted.'), + metadata: creationMetadataSchema, + }), + output: startedUploadSchema, + surfaces: ['agent', 'mcp'], + annotations: { readOnly: false, destructive: false }, +}) diff --git a/packages/operations/src/version/create-version-stack.ts b/packages/operations/src/version/create-version-stack.ts new file mode 100644 index 00000000..adb1b720 --- /dev/null +++ b/packages/operations/src/version/create-version-stack.ts @@ -0,0 +1,29 @@ +import { z } from 'zod' +import { defineOperation } from '../define' +import { assetSummarySchema } from '../schemas' + +export const createVersionStack = defineOperation({ + name: 'create_version_stack', + title: 'Create Version Stack', + description: + 'Stack existing files in the same folder as versions of one asset, e.g. "cut_v1.mp4" and ' + + '"cut_v2.mp4". The first file in fileIds becomes the current (latest) version. To add a ' + + 'newly uploaded file as a version, use create_version instead.', + input: z.object({ + fileIds: z + .array(z.string().min(1)) + .min(2) + .describe( + 'IDs of the files to stack (at least two, all in the same folder), latest version first.', + ), + }), + output: assetSummarySchema, + surfaces: ['agent', 'mcp', 'cli'], + annotations: { readOnly: false, destructive: false }, + cli: { + command: ['version', 'stack'], + description: 'Stack files in the same folder as versions; the first file is the latest.', + positional: ['fileIds'], + format: (output) => `Created version stack ${output.id}`, + }, +}) diff --git a/packages/operations/src/version/list-versions.ts b/packages/operations/src/version/list-versions.ts new file mode 100644 index 00000000..90920aa2 --- /dev/null +++ b/packages/operations/src/version/list-versions.ts @@ -0,0 +1,40 @@ +import { z } from 'zod' +import { defineOperation } from '../define' + +export const versionSummarySchema = z.object({ + id: z.string().describe('The file ID of this version.'), + version: z.number().describe('Version number; the highest is the latest.'), + name: z.string(), + current: z.boolean().describe('Whether this is the current (latest) version.'), + createdAt: z.string(), + creator: z.object({ id: z.string(), name: z.string().nullable() }).nullable(), + agent: z + .object({ id: z.string(), name: z.string() }) + .nullable() + .describe('The AI agent that created this version, if any.'), +}) + +export const listVersions = defineOperation({ + name: 'list_versions', + title: 'List Versions', + description: + 'List the versions in a version stack, latest first. Each version is a file: pass its ID ' + + 'to read_asset or list_comments to look at an older version.', + input: z.object({ + stackId: z.string().min(1).describe('The version stack ID.'), + }), + output: z.object({ + versions: z.array(versionSummarySchema), + }), + surfaces: ['agent', 'mcp', 'cli'], + annotations: { readOnly: true, destructive: false, idempotent: true }, + cli: { + command: ['version', 'ls'], + description: 'List the versions in a version stack, latest first.', + positional: ['stackId'], + format: (output) => + output.versions + .map((v) => `v${v.version}${v.current ? ' (current)' : ''} ${v.id} ${v.name}`) + .join('\n'), + }, +}) diff --git a/packages/operations/src/version/remove-version.ts b/packages/operations/src/version/remove-version.ts new file mode 100644 index 00000000..ad994527 --- /dev/null +++ b/packages/operations/src/version/remove-version.ts @@ -0,0 +1,25 @@ +import { z } from 'zod' +import { defineOperation } from '../define' + +export const removeVersion = defineOperation({ + name: 'remove_version', + title: 'Remove Version', + description: + 'Take a version out of its version stack. The file is not deleted: it goes back into the ' + + 'folder next to the stack as a separate file.', + input: z.object({ + versionId: z.string().min(1).describe('The file ID of the version (from list_versions).'), + }), + output: z.object({ + versionId: z.string(), + stackId: z.string().describe('The stack the version was removed from.'), + }), + surfaces: ['agent', 'mcp', 'cli'], + annotations: { readOnly: false, destructive: false }, + cli: { + command: ['version', 'unstack'], + description: 'Take a version out of its version stack (the file is kept).', + positional: ['versionId'], + format: (output) => `Removed ${output.versionId} from version stack ${output.stackId}`, + }, +}) diff --git a/packages/webui/components/settings/AgentFormDialog.tsx b/packages/webui/components/settings/AgentFormDialog.tsx index 00537268..70f825c6 100644 --- a/packages/webui/components/settings/AgentFormDialog.tsx +++ b/packages/webui/components/settings/AgentFormDialog.tsx @@ -142,6 +142,61 @@ const BUILTIN_TOOLS = [ name: () => m.agent_tool_delete_asset_name(), description: () => m.agent_tool_delete_asset_desc(), }, + { + id: 'search_assets', + name: () => m.agent_tool_search_assets_name(), + description: () => m.agent_tool_search_assets_desc(), + }, + { + id: 'copy_assets', + name: () => m.agent_tool_copy_assets_name(), + description: () => m.agent_tool_copy_assets_desc(), + }, + { + id: 'get_folder_instructions', + name: () => m.agent_tool_get_folder_instructions_name(), + description: () => m.agent_tool_get_folder_instructions_desc(), + }, + { + id: 'list_comments', + name: () => m.agent_tool_list_comments_name(), + description: () => m.agent_tool_list_comments_desc(), + }, + { + id: 'create_comment', + name: () => m.agent_tool_create_comment_name(), + description: () => m.agent_tool_create_comment_desc(), + }, + { + id: 'resolve_comment', + name: () => m.agent_tool_resolve_comment_name(), + description: () => m.agent_tool_resolve_comment_desc(), + }, + { + id: 'list_metadata_fields', + name: () => m.agent_tool_list_metadata_fields_name(), + description: () => m.agent_tool_list_metadata_fields_desc(), + }, + { + id: 'update_asset_metadata', + name: () => m.agent_tool_update_asset_metadata_name(), + description: () => m.agent_tool_update_asset_metadata_desc(), + }, + { + id: 'create_version_stack', + name: () => m.agent_tool_create_version_stack_name(), + description: () => m.agent_tool_create_version_stack_desc(), + }, + { + id: 'list_versions', + name: () => m.agent_tool_list_versions_name(), + description: () => m.agent_tool_list_versions_desc(), + }, + { + id: 'remove_version', + name: () => m.agent_tool_remove_version_name(), + description: () => m.agent_tool_remove_version_desc(), + }, ] type AgentFormValues = z.infer diff --git a/packages/webui/components/settings/QuotaRuleDialog.tsx b/packages/webui/components/settings/QuotaRuleDialog.tsx index 40ee94e8..d8595b48 100644 --- a/packages/webui/components/settings/QuotaRuleDialog.tsx +++ b/packages/webui/components/settings/QuotaRuleDialog.tsx @@ -79,6 +79,10 @@ const STANDARD_TOOLS = [ { value: 'rename_asset', label: () => m.agent_tool_rename_asset_name() }, { value: 'move_assets', label: () => m.agent_tool_move_assets_name() }, { value: 'delete_asset', label: () => m.agent_tool_delete_asset_name() }, + { value: 'search_assets', label: () => m.agent_tool_search_assets_name() }, + { value: 'copy_assets', label: () => m.agent_tool_copy_assets_name() }, + { value: 'create_comment', label: () => m.agent_tool_create_comment_name() }, + { value: 'update_asset_metadata', label: () => m.agent_tool_update_asset_metadata_name() }, ] /* eslint-disable @typescript-eslint/naming-convention */ diff --git a/packages/webui/messages/en.json b/packages/webui/messages/en.json index 9657733c..93d48ce1 100644 --- a/packages/webui/messages/en.json +++ b/packages/webui/messages/en.json @@ -633,6 +633,28 @@ "agent_tool_move_assets_desc": "Allows the agent to move one or more assets to another folder in Shumai.", "agent_tool_delete_asset_name": "Delete Asset", "agent_tool_delete_asset_desc": "Allows the agent to delete a single file or folder in Shumai.", + "agent_tool_search_assets_name": "Search Assets", + "agent_tool_search_assets_desc": "Allows the agent to search for files by name, by meaning, or by metadata such as status.", + "agent_tool_copy_assets_name": "Copy Assets", + "agent_tool_copy_assets_desc": "Allows the agent to copy files or folders into another folder of the team.", + "agent_tool_get_folder_instructions_name": "Read Folder Instructions", + "agent_tool_get_folder_instructions_desc": "Allows the agent to read a folder's instructions for AI agents (AGENTS.md).", + "agent_tool_list_comments_name": "Read Comments", + "agent_tool_list_comments_desc": "Allows the agent to read the review comments and replies on a file.", + "agent_tool_create_comment_name": "Post Comment", + "agent_tool_create_comment_desc": "Allows the agent to comment on files and reply to comments on your behalf.", + "agent_tool_resolve_comment_name": "Resolve Comment", + "agent_tool_resolve_comment_desc": "Allows the agent to mark comments as resolved or reopen them.", + "agent_tool_list_metadata_fields_name": "List Metadata Fields", + "agent_tool_list_metadata_fields_desc": "Allows the agent to see a project's metadata fields and their choices.", + "agent_tool_update_asset_metadata_name": "Update Metadata", + "agent_tool_update_asset_metadata_desc": "Allows the agent to set metadata such as status, rating, or tags on files.", + "agent_tool_create_version_stack_name": "Create Version Stack", + "agent_tool_create_version_stack_desc": "Allows the agent to stack files in the same folder as versions of one asset.", + "agent_tool_list_versions_name": "List Versions", + "agent_tool_list_versions_desc": "Allows the agent to list the versions in a version stack.", + "agent_tool_remove_version_name": "Remove Version", + "agent_tool_remove_version_desc": "Allows the agent to take a version out of its stack, keeping the file.", "enabled": "Enabled", "disabled": "Disabled", "no_skills_available": "No skills available.", diff --git a/packages/webui/messages/zh.json b/packages/webui/messages/zh.json index a876eb87..1989485d 100644 --- a/packages/webui/messages/zh.json +++ b/packages/webui/messages/zh.json @@ -633,6 +633,28 @@ "agent_tool_move_assets_desc": "允许智能体将一个或多个资产移动到 Shumai 中的其他文件夹。", "agent_tool_delete_asset_name": "删除资产", "agent_tool_delete_asset_desc": "允许智能体在 Shumai 中删除单个文件或文件夹。", + "agent_tool_search_assets_name": "搜索资产", + "agent_tool_search_assets_desc": "允许智能体按名称、语义或状态等元数据搜索文件。", + "agent_tool_copy_assets_name": "复制资产", + "agent_tool_copy_assets_desc": "允许智能体将文件或文件夹复制到团队内的其他文件夹。", + "agent_tool_get_folder_instructions_name": "读取文件夹说明", + "agent_tool_get_folder_instructions_desc": "允许智能体读取文件夹中给 AI 智能体的说明(AGENTS.md)。", + "agent_tool_list_comments_name": "读取评论", + "agent_tool_list_comments_desc": "允许智能体读取文件上的审阅评论和回复。", + "agent_tool_create_comment_name": "发表评论", + "agent_tool_create_comment_desc": "允许智能体以您的身份评论文件或回复评论。", + "agent_tool_resolve_comment_name": "解决评论", + "agent_tool_resolve_comment_desc": "允许智能体将评论标记为已解决或重新打开。", + "agent_tool_list_metadata_fields_name": "列出元数据字段", + "agent_tool_list_metadata_fields_desc": "允许智能体查看项目的元数据字段及其选项。", + "agent_tool_update_asset_metadata_name": "更新元数据", + "agent_tool_update_asset_metadata_desc": "允许智能体设置文件的状态、评分或标签等元数据。", + "agent_tool_create_version_stack_name": "创建版本堆叠", + "agent_tool_create_version_stack_desc": "允许智能体将同一文件夹中的文件堆叠为同一资产的多个版本。", + "agent_tool_list_versions_name": "列出版本", + "agent_tool_list_versions_desc": "允许智能体列出版本堆叠中的各个版本。", + "agent_tool_remove_version_name": "移出版本", + "agent_tool_remove_version_desc": "允许智能体将某个版本移出堆叠,文件本身会保留。", "enabled": "已启用", "disabled": "已禁用", "no_skills_available": "暂无可用技能。",