Skip to content

Releases

Workspace Operator 2.2.5 - cached clients, durable staged operations, typed errors

Choose a tag to compare

@Artoxem Artoxem released this 18 Nov 12:52

Workspace Operator 2.2.5

Performance and durability, plus a cleaner contract for tool errors. The MCP tool list and every schema are unchanged — no client configuration or prompt needs to change.

Faster calls: one Google client per configuration

Every handler used to call get_creds(config) and build(api, version, ...) on each invocation, so the token file was read again and the discovery document parsed again for every tool call and every bulk worker. Clients are now cached per (configuration, api, version) and the credentials are read once and refreshed on expiry.

The cache belongs to the configuration object, so a second server with different settings (another token, scopes or profile) never inherits the first one's clients.

Staged Apps Script operations survive a restart

script_write → prepare, then execute or cancel, kept its state in memory: a restart, a second process or a container recreate lost the prepared operation. Prepared updates now live as JSON files under operation_dir (default data/operations), written atomically with owner-only permissions because they contain script source, and carrying an expiry:

  • operation_ttl / MCP_OPERATION_TTL — seconds a prepared operation stays executable (default 600);
  • operation_dir / MCP_OPERATION_DIR — where they are kept; the Docker template uses /home/app/data/operations;
  • the directory is now in the protected paths, so drive_write(action="upload") refuses to upload it;
  • an executed operation is removed atomically, so two concurrent execute calls cannot both apply the same update, and a failed update puts the operation back for a retry.

Tool errors: explicit signals instead of guessing from the text

The router treated any handler reply beginning with "Error" as a failure. A legitimate answer such as "Errors found: 0" was therefore reported with isError, and a handler had no way to say "this text is not an error". Handlers can now raise ToolError("...") or return ToolResult(text, is_error=...), and the legacy string convention is matched strictly (^Error(?=:|\s|$)).

Visible change: text that merely starts with the word "Error" (for example "Errors found: 0", or "ERROR: …" in capitals) is now a normal result. Every real handler error message keeps the old shape and is still reported as an error.

Compose: choose the profile in .env

docker-compose.yml now passes MCP_TOOL_PROFILE through (default core), so a deployment can select full, read-write or read-only in .env without editing the tracked config.docker.yaml. The shipped default stays conservative.

Under the hood

448 tests, coverage 58.6% (floor raised to 56%), CI green on Linux and Windows for Python 3.10/3.12/3.13.


Workspace Operator 2.2.5 (русский)

Производительность и надёжность, плюс более чистой контракт ошибок инструментов. Список инструментов и все схемы не изменились — настраивать клиентов и промпты заново не нужно.

Быстрее: один Google-клиент на конфигурацию

Каждый хендлер вызывал get_creds(config) и build(api, version, ...) при каждом обращении: файл токена перечитывался, а документ discovery парсился заново на каждый вызов инструмента и на каждый поток bulk. Теперь клиенты кэшируются по (конфигурация, api, версия), а учётные данные читаются один раз и обновляются по истечении.

Кэш привязан к объекту конфигурации, поэтому второй сервер с другими настройками (другой токен, скоупы или профиль) не получит клиентов первого.

Подготовленные операции Apps Script переживают перезапуск

script_write → prepare, затем execute или cancel: состояние жило в памяти, и перезапуск, второй процесс или пересоздание контейнера теряли подготовленную операцию. Теперь подготовленные изменения лежат JSON-файлами в operation_dir (по умолчанию data/operations), пишутся атомарно с правами владельца (внутри исходники скрипта) и имеют срок жизни:

  • operation_ttl / MCP_OPERATION_TTL — сколько секунд операция остаётся выполнимой (по умолчанию 600);
  • operation_dir / MCP_OPERATION_DIR — где она хранится; в Docker-шаблоне это /home/app/data/operations;
  • каталог добавлен в защищённые пути, поэтому drive_write(action="upload") его не выгрузит;
  • выполненная операция удаляется атомарно, поэтому два одновременных execute не применят одно и то же изменение дважды, а неудачное обновление возвращает операцию для повторной попытки.

Ошибки инструментов: явные сигналы вместо догадок по тексту

Роутер считал ошибкой любой ответ хендлера, начинающийся с «Error». Поэтому нормальный ответ вроде «Errors found: 0» помечался как isError, а хендлер не мог сказать «этот текст — не ошибка». Теперь хендлер может возбудить ToolError("...") или вернуть ToolResult(text, is_error=...), а прежняя строковая конвенция проверяется строго (^Error(?=:|\s|$)).

Заметное изменение: текст, который лишь начинается со слова «Error» (например «Errors found: 0» или «ERROR: …» заглавными), теперь считается обычным результатом. Все настоящие сообщения об ошибках хендлеров сохранили прежний вид и по-прежнему помечаются как ошибки.

Compose: профиль выбирается в .env

docker-compose.yml теперь передаёт MCP_TOOL_PROFILE (по умолчанию core), поэтому деплой может выбрать full, read-write или read-only в .env, не редактируя отслеживаемый config.docker.yaml. Значение по умолчанию осталось консервативным.

Внутри

448 тестов, покрытие 58,6% (порог поднят до 56%), CI зелёный на Linux и Windows для Python 3.10/3.12/3.13.

Workspace Operator 2.2.4 - security hardening and internal refactor

Choose a tag to compare

@Artoxem Artoxem released this 18 Nov 12:12

Workspace Operator 2.2.4

First PyPI/GHCR release since 2.1.2. Versions 2.2.0 to 2.2.3 were internal steps and were not published, so these notes cover everything since 2.1.2.

The MCP surface is unchanged: the tools, their order and JSON schemas, annotations, prompts, resources and server instructions are identical to 2.1.2 in all four profiles (compared programmatically). What changes is security behaviour, listed first because some of it needs action.

⚠️ Read before upgrading

  • Docker: the image now binds 127.0.0.1 by default. A plain docker run -p 8765:8765 IMAGE no longer answers. Add --http --host 0.0.0.0 --allow-network --insecure and keep the -p 127.0.0.1:8765:8765 mapping (docker-compose does this already).
  • HTTP token: the server refuses to start over HTTP with a placeholder (change_me, …) or a token shorter than 24 characters. Generate one: python -c "import secrets; print(secrets.token_urlsafe(32))" and prefer the MCP_AUTH_TOKEN environment variable over config.yaml.
  • Approval links: the agent no longer receives a browser link. Run workspace-operator approvals link <id> to get it (it carries a per-approval secret). Old links without ?k= return 404.
  • drive_write(action="upload") refuses OAuth secrets, .env*, keys and ~/.google, ~/.ssh, ~/.aws, and files outside upload_roots when you set it (MCP_UPLOAD_ROOTS).

Security fixes

  • Path traversal: a mail attachment named ..\..\x could be written outside the target folder. Names from remote data are now reduced to a plain file name.
  • An agent that knew an approval id and the server URL could approve its own request over HTTP. Approvals now need a secret the agent never sees, an Origin/Host check and strict headers.
  • token.json is refreshed under a file lock, written atomically and readable by the owner only. workspace-operator doctor now flags a token stored in config.yaml, stray credentials (token.json.bak-*, service-account.json) and files readable by other users.

Fixes

  • Bulk jobs lost results on cancel: items already running when a job was cancelled changed Google data but were not recorded, so bulk_undo skipped them and resume repeated them. They are recorded now.
  • handlers.__all__ listed a name that does not exist; the server.json package version lagged one release.

Under the hood

  • server.py went from 3,740 to 325 lines: tool definitions are JSON data (workspace_operator/definitions/), the handler table is dispatch.py, the call path is ToolRouter, prompts and resources have their own modules. Each step was pinned by characterisation tests taken from the old code.
  • CI (Linux and Windows, Python 3.10/3.12/3.13, ruff, mypy, bandit, pip-audit) now gates both publish workflows. mypy: 152 errors to 0. 421 tests (one skipped on Linux/macOS by design), coverage 56%.
  • New contributor guide ("Adding a tool or action") in both READMEs.

Full list: docs/VERSIONS.md.


Workspace Operator 2.2.4 (русский)

Первый релиз в PyPI/GHCR после 2.1.2. Версии 2.2.0–2.2.3 были внутренними этапами и не публиковались, поэтому заметки охватывают всё с 2.1.2.

MCP-поверхность не изменилась: инструменты, их порядок и JSON-схемы, аннотации, промпты, ресурсы и инструкции сервера идентичны 2.1.2 во всех четырёх профилях (сравнивалось программно). Меняется поведение безопасности; оно вынесено вперёд, потому что часть изменений требует действий.

⚠️ Прочитайте перед обновлением

  • Docker: образ по умолчанию слушает 127.0.0.1. Обычный docker run -p 8765:8765 IMAGE больше не отвечает. Добавьте --http --host 0.0.0.0 --allow-network --insecure и оставьте проброс -p 127.0.0.1:8765:8765 (docker-compose это уже делает).
  • Токен HTTP: сервер не запустится по HTTP с заглушкой (change_me, …) или токеном короче 24 символов. Сгенерируйте: python -c "import secrets; print(secrets.token_urlsafe(32))", лучше в переменной MCP_AUTH_TOKEN, а не в config.yaml.
  • Ссылки одобрений: агент больше не получает ссылку для браузера. Получите её командой workspace-operator approvals link <id> (в ней секрет конкретного одобрения). Старые ссылки без ?k= дают 404.
  • drive_write(action="upload") отклоняет секреты OAuth, .env*, ключи и ~/.google, ~/.ssh, ~/.aws, а также файлы вне upload_roots, если он задан (MCP_UPLOAD_ROOTS).

Исправления безопасности

  • Path traversal: вложение письма с именем ..\..\x могло записаться за пределы целевой папки. Имена из удалённых данных теперь сводятся к простому имени файла.
  • Агент, знающий id одобрения и адрес сервера, мог одобрить свой запрос по HTTP. Теперь нужны секрет, которого агент не видит, проверка Origin/Host и строгие заголовки.
  • token.json обновляется под файловой блокировкой, пишется атомарно и доступен только владельцу. workspace-operator doctor теперь находит токен в config.yaml, лишние учётные данные (token.json.bak-*, service-account.json) и файлы, доступные другим пользователям.

Исправления

  • Bulk-задачи теряли результаты при отмене: элементы, уже запущенные к моменту отмены, меняли данные в Google, но не записывались, поэтому bulk_undo их пропускал, а возобновление повторяло. Теперь они записываются.
  • В handlers.__all__ было несуществующее имя; версия пакета в server.json отставала на один релиз.

Внутри

  • server.py: 3740 → 325 строк. Определения инструментов теперь JSON-данные (workspace_operator/definitions/), таблица handler'ов в dispatch.py, путь вызова в ToolRouter, у промптов и ресурсов свои модули. Каждый шаг закреплён тестами, снятыми со старого кода.
  • CI (Linux и Windows, Python 3.10/3.12/3.13, ruff, mypy, bandit, pip-audit) теперь блокирует оба workflow публикации. mypy: 152 ошибки → 0. 421 тест (один пропускается на Linux/macOS намеренно), покрытие 56%.
  • Руководство для контрибьюторов («Как добавить инструмент или действие») в обоих README.

Полный список: docs/VERSIONS.md.

Workspace Operator 2.1.2

Choose a tag to compare

@Artoxem Artoxem released this 16 Nov 17:54

Browser approval fallback.

  • Native in-chat elicitation remains the primary path on clients that support it.
  • Clients without elicitation (including current DSH) now get a clickable local approval link in the tool result.
  • /approvals/{id} serves an Approve/Deny page; no terminal needed.
  • Added approval_url / MCP_APPROVAL_URL, HTTP page tests and docs.
  • 308 tests green.

Workspace Operator 2.1.1

Choose a tag to compare

@Artoxem Artoxem released this 16 Nov 17:48

In-chat approval release.

  • Destructive calls now ask for approval directly in the chat when the MCP client supports elicitation (elicitation/create).
  • Accept runs the action once; decline/cancel changes nothing.
  • If the client does not support elicitation, the server falls back to the existing approval_id + local CLI flow.
  • The session remains stable in both paths; failures fall back cleanly.
  • 305 tests, including accepted/declined elicitation paths.

Workspace Operator 2.1.0

Choose a tag to compare

@Artoxem Artoxem released this 16 Nov 17:11

Human-in-the-loop safety release.

  • Destructive tools now return a normal APPROVAL_REQUIRED result with an approval_id; they do not execute.
  • A human approves the exact call locally: workspace-operator approvals approve <id> (or denies it).
  • The agent retries the same call with approval_id; approval is one-time, TTL-bound and hash-bound to tool/action/arguments.
  • Pending, expired, denied, reused and changed-argument cases return clear results without crashing the MCP session.
  • New workspace-operator approvals list/show/approve/deny commands; approval_dir and approval_ttl config.
  • 303 tests green.

Workspace Operator 2.0.6

Choose a tag to compare

@Artoxem Artoxem released this 16 Nov 16:47

Documentation accuracy release. No code or OAuth changes.

  • Removed the stale sheet_brief prompt row from both READMEs.
  • Added exact tests: README tool table, English prompt table, Russian prompt table.
  • Tool descriptions/actions, prompts, resources and templates rechecked against code.
  • Counts corrected to 293 tests.

Workspace Operator 2.0.5

Choose a tag to compare

@Artoxem Artoxem released this 16 Nov 16:18

Documentation accuracy release. No code or OAuth changes.

  • README/RU now mention all four profiles and both HTTP profile endpoints.
  • Added MCP_SCOPE_ROUTING and MCP_ALLOW_PUBLIC_SHARING to the operations table.
  • Corrected local-file capabilities: upload/export only, no download, no pptx.
  • Completed both documentation tables (profiles, migration, versions).
  • Updated SECURITY/TROUBLESHOOTING/LEARN to current tool names and Trash semantics.
  • 290 tests green.

Workspace Operator 2.0.4

Choose a tag to compare

@Artoxem Artoxem released this 15 Nov 10:36

Documentation release. No code or OAuth changes.

  • README/RU now state 39 consolidated tools (20 in the default core profile) at the top.
  • Added a complete scope → tools matrix to docs/PROFILES.md and its Russian copy.
  • Documented minimal scope sets, missing-token behaviour, routing-off caveats and missing-tool troubleshooting.
  • AUTH_SETUP links to the matrix.
  • 290 tests green.

Workspace Operator 2.0.3

Choose a tag to compare

@Artoxem Artoxem released this 14 Nov 20:16

Documentation consolidation release. No tool or OAuth changes.

  • Removed duplicate troubleshooting lines in README/RU.
  • Replaced 38 per-version release/spec files with one docs/VERSIONS.md.
  • Corrected prompt count to 7 and test count to 290.
  • Updated PUBLISHING, IDE_SETUP, DISTRIBUTION, LAUNCH_PACKAGE, SCREENSHOTS and LEARN.
  • Added PROFILES and MIGRATION links to both README documentation tables.
  • 290 tests green.

Workspace Operator 2.0.2

Choose a tag to compare

@Artoxem Artoxem released this 14 Nov 18:27

Workspace Operator 2.0.2

Code cleanup release. No new tools and no new OAuth scopes.

Removed dead code

  • Deleted handlers/slides.py, handlers/comments.py, handlers/deck.py,
    handlers/report.py, handlers/template.py.
  • Removed their imports, exports, tool definitions and dispatch branches.
  • Removed obsolete handler functions: find_files, drive_download,
    create_event, calendar_find_free_slots, doc_export_pdf,
    doc_fill_template, drive_empty_trash, drive_transfer_ownership,
    drive_create_shortcut, batch_delete_emails.
  • Removed Slides conversion/export from drive_upload/drive_export.
  • Removed the remaining Slides domain handling from the bulk engine.
  • Removed sheet_brief prompt because it depended on the removed report handler;
    prompt count is now 7.
  • Removed stale 1.x live scripts from tests/; the executable suite is the
    290-test unit/in-memory suite.

Preserved

  • 39 consolidated tools; core = 20, read-only = 17, read-write = 30,
    full = 39.
  • Hidden 1.x aliases from 2.0.1.
  • Scope routing, profile endpoints, no permanent Drive deletion, public sharing
    disabled by default.
  • Removed capabilities return the migration error instead of an unknown tool.

Verification

  • 290 tests, all green.
  • CLI catalog: core 20, full 39.
  • Live read/write check on a synthetic Google Doc; removed after the test.
  • HTTP endpoints /mcp, /mcp/read, /mcp/read-write, /mcp/full.