diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 98715bc4..d503226e 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -50,7 +50,9 @@ jobs: uses: actions/checkout@v6 - name: Setup pnpm - uses: pnpm/action-setup@v4 + uses: pnpm/action-setup@v6 + with: + version: 10.33.0 - name: Setup Node.js uses: actions/setup-node@v6 @@ -59,7 +61,7 @@ jobs: cache: pnpm - name: Install dependencies - run: pnpm install --no-frozen-lockfile + run: pnpm install --frozen-lockfile - name: Restore ESLint cache uses: actions/cache@v5 @@ -67,9 +69,6 @@ jobs: path: .eslintcache key: eslint-${{ runner.os }}-${{ hashFiles('pnpm-lock.yaml', 'eslint.config.*', 'src/**/*.ts', 'src/**/*.tsx') }} - - name: Auto-fix import sort (Node version parity) - run: npx eslint src/ --fix --no-cache || true - - name: Validate workspace truth gate run: pnpm check:ci @@ -81,7 +80,9 @@ jobs: uses: actions/checkout@v6 - name: Setup pnpm - uses: pnpm/action-setup@v4 + uses: pnpm/action-setup@v6 + with: + version: 10.33.0 - name: Setup Node.js uses: actions/setup-node@v6 @@ -90,7 +91,7 @@ jobs: cache: pnpm - name: Install dependencies - run: pnpm install --no-frozen-lockfile + run: pnpm install --frozen-lockfile - name: Test run: pnpm test:workspace:ci @@ -108,7 +109,9 @@ jobs: run: git config --global core.longpaths true - name: Setup pnpm - uses: pnpm/action-setup@v4 + uses: pnpm/action-setup@v6 + with: + version: 10.33.0 - name: Setup Node.js uses: actions/setup-node@v6 @@ -117,7 +120,7 @@ jobs: cache: pnpm - name: Install dependencies - run: pnpm install --no-frozen-lockfile + run: pnpm install --frozen-lockfile - name: Test task change ledger run: pnpm test:task-change-ledger diff --git a/.github/workflows/codex-runtime-smoke.yml b/.github/workflows/codex-runtime-smoke.yml index 1657aa33..c162a884 100644 --- a/.github/workflows/codex-runtime-smoke.yml +++ b/.github/workflows/codex-runtime-smoke.yml @@ -51,7 +51,9 @@ jobs: run: git config --global core.longpaths true - name: Setup pnpm - uses: pnpm/action-setup@v4 + uses: pnpm/action-setup@v6 + with: + version: 10.33.0 - name: Setup Node.js uses: actions/setup-node@v6 @@ -60,7 +62,7 @@ jobs: cache: pnpm - name: Install dependencies - run: pnpm install --no-frozen-lockfile --ignore-scripts + run: pnpm install --frozen-lockfile --ignore-scripts - name: Smoke Codex app-managed runtime install run: pnpm smoke:codex-runtime-install diff --git a/.github/workflows/landing.yml b/.github/workflows/landing.yml index 51d075da..f457394c 100644 --- a/.github/workflows/landing.yml +++ b/.github/workflows/landing.yml @@ -4,15 +4,15 @@ on: push: branches: [main] paths: [landing/**] + pull_request: + paths: [landing/**] workflow_dispatch: permissions: contents: read - pages: write - id-token: write concurrency: - group: pages + group: landing-${{ github.event_name == 'pull_request' && github.event.pull_request.number || github.ref }} cancel-in-progress: true jobs: @@ -24,6 +24,8 @@ jobs: - uses: actions/setup-node@v6 with: node-version: 22 + cache: npm + cache-dependency-path: landing/package-lock.json - name: Install dependencies working-directory: landing @@ -37,18 +39,24 @@ jobs: NUXT_PUBLIC_GITHUB_REPO: 777genius/agent-teams-ai run: npm run generate:all - - uses: actions/configure-pages@v5 + - uses: actions/configure-pages@v6 + if: github.event_name != 'pull_request' - - uses: actions/upload-pages-artifact@v3 + - uses: actions/upload-pages-artifact@v5 + if: github.event_name != 'pull_request' with: path: landing/.output/public deploy: needs: build runs-on: ubuntu-latest + if: github.event_name != 'pull_request' + permissions: + pages: write + id-token: write environment: name: github-pages url: ${{ steps.deployment.outputs.page_url }} steps: - id: deployment - uses: actions/deploy-pages@v4 + uses: actions/deploy-pages@v5 diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 1ab97a28..6421e4d4 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -18,7 +18,9 @@ jobs: uses: actions/checkout@v6 - name: Setup pnpm - uses: pnpm/action-setup@v4 + uses: pnpm/action-setup@v6 + with: + version: 10.33.0 - name: Setup Node.js uses: actions/setup-node@v6 @@ -27,7 +29,7 @@ jobs: cache: pnpm - name: Install dependencies - run: pnpm install --no-frozen-lockfile + run: pnpm install --frozen-lockfile - name: Set version from tag if: startsWith(github.ref, 'refs/tags/v') @@ -57,7 +59,7 @@ jobs: --draft=false 2>/dev/null || echo "Release $TAG already exists, skipping creation" - name: Upload dist artifact - uses: actions/upload-artifact@v6 + uses: actions/upload-artifact@v7 with: name: dist path: | @@ -67,13 +69,13 @@ jobs: prepare-runtime: runs-on: ubuntu-latest - if: startsWith(github.ref, 'refs/tags/v') steps: - name: Checkout uses: actions/checkout@v6 - name: Create GitHub Release + if: startsWith(github.ref, 'refs/tags/v') env: GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} run: | @@ -84,7 +86,12 @@ jobs: --generate-notes \ --draft=false 2>/dev/null || echo "Release $TAG already exists, skipping creation" + - name: Skip runtime asset preparation for manual builds + if: ${{ !startsWith(github.ref, 'refs/tags/v') }} + run: echo "Runtime asset preparation is only needed for tagged releases." + - name: Check runtime assets + if: startsWith(github.ref, 'refs/tags/v') id: runtime-assets env: GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} @@ -116,10 +123,10 @@ jobs: --method POST \ "repos/${SOURCE_REPO}/actions/workflows/release-runtime.yml/dispatches" \ -f ref=main \ - -f inputs[source_ref]="$SOURCE_REF" \ - -f inputs[runtime_version]="$RUNTIME_VERSION" \ - -f inputs[target_release_repo]="$GITHUB_REPOSITORY" \ - -f inputs[target_release_tag]="$TARGET_TAG" + -f "inputs[source_ref]=$SOURCE_REF" \ + -f "inputs[runtime_version]=$RUNTIME_VERSION" \ + -f "inputs[target_release_repo]=$GITHUB_REPOSITORY" \ + -f "inputs[target_release_tag]=$TARGET_TAG" - name: Wait for runtime assets if: steps.runtime-assets.outputs.missing == '1' @@ -175,7 +182,9 @@ jobs: name: dist - name: Setup pnpm - uses: pnpm/action-setup@v4 + uses: pnpm/action-setup@v6 + with: + version: 10.33.0 - name: Setup Node.js uses: actions/setup-node@v6 @@ -184,12 +193,12 @@ jobs: cache: pnpm - name: Setup Python for node-gyp - uses: actions/setup-python@v5 + uses: actions/setup-python@v6 with: python-version: '3.11' - name: Install dependencies - run: pnpm install --no-frozen-lockfile + run: pnpm install --frozen-lockfile - name: Set version from tag if: startsWith(github.ref, 'refs/tags/v') @@ -256,6 +265,9 @@ jobs: - name: Validate packaged bundle (macOS ${{ matrix.arch }}) run: node ./scripts/electron-builder/verifyBundle.cjs "release/mac-${{ matrix.arch }}/Agent Teams UI.app" darwin ${{ matrix.arch }} + - name: Smoke packaged app (macOS ${{ matrix.arch }}) + run: node ./scripts/electron-builder/smokePackagedApp.cjs "release/mac-${{ matrix.arch }}/Agent Teams UI.app" darwin + - name: Upload assets to release if: startsWith(github.ref, 'refs/tags/v') env: @@ -284,7 +296,9 @@ jobs: name: dist - name: Setup pnpm - uses: pnpm/action-setup@v4 + uses: pnpm/action-setup@v6 + with: + version: 10.33.0 - name: Setup Node.js uses: actions/setup-node@v6 @@ -293,12 +307,12 @@ jobs: cache: pnpm - name: Setup Python for node-gyp - uses: actions/setup-python@v5 + uses: actions/setup-python@v6 with: python-version: '3.11' - name: Install dependencies - run: pnpm install --no-frozen-lockfile + run: pnpm install --frozen-lockfile - name: Set version from tag if: startsWith(github.ref, 'refs/tags/v') @@ -359,6 +373,10 @@ jobs: shell: bash run: node ./scripts/electron-builder/verifyBundle.cjs "release/win-unpacked" win32 x64 + - name: Smoke packaged app (Windows) + shell: bash + run: node ./scripts/electron-builder/smokePackagedApp.cjs "release/win-unpacked" win32 + - name: Upload assets to release if: startsWith(github.ref, 'refs/tags/v') shell: bash @@ -388,7 +406,9 @@ jobs: name: dist - name: Setup pnpm - uses: pnpm/action-setup@v4 + uses: pnpm/action-setup@v6 + with: + version: 10.33.0 - name: Setup Node.js uses: actions/setup-node@v6 @@ -397,17 +417,17 @@ jobs: cache: pnpm - name: Setup Python for node-gyp - uses: actions/setup-python@v5 + uses: actions/setup-python@v6 with: python-version: '3.11' - name: Install Linux packaging dependencies run: | sudo apt-get update - sudo apt-get install -y libarchive-tools rpm + sudo apt-get install -y libarchive-tools rpm xvfb - name: Install dependencies - run: pnpm install --no-frozen-lockfile + run: pnpm install --frozen-lockfile - name: Set version from tag if: startsWith(github.ref, 'refs/tags/v') @@ -463,6 +483,9 @@ jobs: - name: Validate packaged bundle (Linux) run: node ./scripts/electron-builder/verifyBundle.cjs "release/linux-unpacked" linux x64 + - name: Smoke packaged app (Linux) + run: xvfb-run -a node ./scripts/electron-builder/smokePackagedApp.cjs "release/linux-unpacked" linux + - name: Upload assets to release if: startsWith(github.ref, 'refs/tags/v') env: @@ -542,8 +565,8 @@ jobs: # Canonical Windows feed download_asset "Claude-Agent-Teams-UI-Setup.exe" - WIN_SHA="$(sha512_base64 Claude-Agent-Teams-UI-Setup.exe)" - WIN_SIZE="$(file_size Claude-Agent-Teams-UI-Setup.exe)" + WIN_SHA="$(sha512_base64 "Claude-Agent-Teams-UI-Setup.exe")" + WIN_SIZE="$(file_size "Claude-Agent-Teams-UI-Setup.exe")" cat > latest.yml < latest-linux.yml < latest-mac.yml < { ? [ { icon: "◈", title: "Концепции", desc: "Команды, задачи, роли и уровни автономности.", link: "/ru/reference/concepts" }, { icon: "⌁", title: "Рантаймы", desc: "Claude, Codex, OpenCode и multimodel-режим.", link: "/ru/reference/providers-runtimes" }, + { icon: "▦", title: "Архитектура", desc: "Feature layout, guardrails и границы runtime/provider.", link: "/ru/reference/contributor-architecture" }, { icon: "⌘", title: "Локальные данные", desc: "Что хранится на машине и что уходит провайдерам.", link: "/ru/reference/privacy-local-data" }, { icon: "?", title: "FAQ", desc: "Короткие ответы на частые вопросы.", link: "/ru/reference/faq" } ] @@ -30,6 +31,7 @@ const cards = computed(() => { ? [ { icon: "◈", title: "Concepts", desc: "Teams, tasks, roles, and autonomy levels.", link: "/reference/concepts" }, { icon: "⌁", title: "Runtimes", desc: "Claude, Codex, OpenCode, and multimodel mode.", link: "/reference/providers-runtimes" }, + { icon: "▦", title: "Architecture", desc: "Feature layout, guardrails, and runtime/provider boundaries.", link: "/reference/contributor-architecture" }, { icon: "⌘", title: "Local data", desc: "What stays on disk and what providers receive.", link: "/reference/privacy-local-data" }, { icon: "?", title: "FAQ", desc: "Short answers to common questions.", link: "/reference/faq" } ] diff --git a/landing/product-docs/developers/index.md b/landing/product-docs/developers/index.md new file mode 100644 index 00000000..516de9e0 --- /dev/null +++ b/landing/product-docs/developers/index.md @@ -0,0 +1,67 @@ +--- +title: Developers - Agent Teams Docs +description: Contributor and developer entry point for Agent Teams architecture, guardrails, debugging, and MCP extension paths. +--- + +# Developers + +Use this page when you want to change Agent Teams itself, debug a team launch, or extend a runtime with MCP tools. The links below point to the canonical repo documents so implementation rules stay in one place. + +## Start here + +| Need | Go to | +| --- | --- | +| Repo overview, scripts, and source setup | [README.md](https://github.com/777genius/agent-teams-ai/blob/main/README.md) | +| Working conventions for agents and contributors | [CLAUDE.md](https://github.com/777genius/agent-teams-ai/blob/main/CLAUDE.md) | +| Hard implementation guardrails | [AGENT_CRITICAL_GUARDRAILS.md](https://github.com/777genius/agent-teams-ai/blob/main/AGENT_CRITICAL_GUARDRAILS.md) | +| Medium and large feature structure | [Feature architecture standard](https://github.com/777genius/agent-teams-ai/blob/main/docs/FEATURE_ARCHITECTURE_STANDARD.md) | +| Launch, bootstrap, and teammate messaging debugging | [Agent team debugging runbook](https://github.com/777genius/agent-teams-ai/blob/main/docs/team-management/debugging-agent-teams.md) | +| Contribution process | [Contributing guide](https://github.com/777genius/agent-teams-ai/blob/main/.github/CONTRIBUTING.md) | +| Release notes / Changelog | [RELEASE.md](https://github.com/777genius/agent-teams-ai/blob/main/docs/RELEASE.md) — [CHANGELOG.md](https://github.com/777genius/agent-teams-ai/blob/main/docs/CHANGELOG.md) | + +## Local development path + +Run the desktop Electron app for normal development: + +```bash +pnpm install +pnpm dev +``` + +The browser/web path is not a replacement for the desktop runtime. Desktop mode is the supported local path because it includes IPC, terminals, provider auth, team lifecycle handling, launch diagnostics, and the runtime bridges used by real teams. + +## Architecture checkpoints + +Before changing a feature, identify its boundary: + +| Area | Expected home | +| --- | --- | +| Medium or large product feature | `src/features//` | +| Electron main process orchestration | `src/main/` | +| Preload-safe API surface | `src/preload/` | +| Renderer UI and app state | `src/renderer/` | +| Shared types and pure helpers | `src/shared/` | +| Agent Teams board MCP server | `mcp-server/` | +| Board data controller | `agent-teams-controller/` | + +Use `src/features/recent-projects` as the reference slice for feature organization. Keep cross-process contracts explicit, and avoid deep imports across feature boundaries. + +## Debugging path + +For launch hangs, OpenCode `registered` / bootstrap-unconfirmed states, missing teammate replies, or suspicious task logs: + +1. Start with the [debugging runbook](https://github.com/777genius/agent-teams-ai/blob/main/docs/team-management/debugging-agent-teams.md). +2. Inspect the newest artifact pack under `~/.claude/teams//launch-failure-artifacts/latest.json`. +3. Open the artifact `manifest.json` and check `classification`, bootstrap breadcrumbs, launch diagnostics, member spawn statuses, and redacted log tails. +4. Clean up only the team, run, pane, or process you can identify as owned by the smoke test or failed launch. + +## MCP development path + +Agent Teams uses a built-in MCP server named `agent-teams` for board operations. User and project MCP servers can add external capabilities for runtimes. See [MCP integration](/guide/mcp-integration) for setup examples, `.mcp.json` structure, and tool registration guidance. + +## Related docs + +- [Contributor architecture](/reference/contributor-architecture) +- [Runtime setup](/guide/runtime-setup) +- [MCP integration](/guide/mcp-integration) +- [Troubleshooting](/guide/troubleshooting) diff --git a/landing/product-docs/guide/code-review.md b/landing/product-docs/guide/code-review.md index 9bb15f03..48bc9a62 100644 --- a/landing/product-docs/guide/code-review.md +++ b/landing/product-docs/guide/code-review.md @@ -86,6 +86,8 @@ Prioritize these areas when reviewing: - **Parsing and task lifecycle logic** — changes to task references, chunking, or filtering can break message delivery - **Persistence and code review flows** — changes to task storage or review state must stay consistent across IPC layers +For the canonical feature layout and hard guardrail links, use [Contributor Architecture](/reference/contributor-architecture). + ## Verification Prefer focused verification commands. Broad formatting or lint-fix commands should not be used unless the task explicitly intends broad formatting churn. diff --git a/landing/product-docs/guide/create-team.md b/landing/product-docs/guide/create-team.md index df2b8dd5..342d6ccd 100644 --- a/landing/product-docs/guide/create-team.md +++ b/landing/product-docs/guide/create-team.md @@ -30,7 +30,7 @@ Each team member runs on a provider backend. In the team editor, pick a provider Mixing providers in one team is supported — for example, a Claude lead with OpenCode builders. ::: info -Gemini support is in development and will appear in the provider list when available. +Gemini provider support is in development. See [Providers and runtimes](/reference/providers-runtimes) for current provider status. ::: ## Write a good team brief diff --git a/landing/product-docs/guide/git-worktree-strategy.md b/landing/product-docs/guide/git-worktree-strategy.md new file mode 100644 index 00000000..6e3a3f54 --- /dev/null +++ b/landing/product-docs/guide/git-worktree-strategy.md @@ -0,0 +1,100 @@ +--- +title: Git and Worktree Strategy - Agent Teams Docs +description: Decide when to use the main worktree, feature branches, or OpenCode worktree isolation for parallel agent work. +--- + +# Git and Worktree Strategy + +Git gives Agent Teams the strongest review path: narrow diffs, branch visibility, task-scoped changes, and safer parallel work. + +## Choose a strategy + +| Strategy | Use when | Tradeoff | +| --- | --- | --- | +| Main worktree | Solo work, docs-only edits, or one teammate at a time | Simple, but parallel edits can collide | +| Feature branch | One team is working on one coherent change | Clean review target, but teammates still share files | +| Worktree isolation | Multiple OpenCode teammates may edit the same repo in parallel | Better isolation, but merge/review needs more discipline | + +Start simple. Add worktree isolation when parallel edits are likely, not because every task needs a separate checkout. + +## When to enable worktree isolation + +Enable it for OpenCode teammates when: + +- two or more teammates may edit the same repository at once +- a task may run formatters, code generators, or broad tests +- you want each teammate's branch and diff to stay separate +- the lead workspace is dirty and should not receive direct edits + +Keep it off when: + +- the task is read-only +- one teammate owns all edits +- the repo is not Git-tracked +- you need a runtime path that does not support this isolation mode + +::: warning +Worktree isolation currently applies to OpenCode members and requires a Git-tracked project. +::: + +## Branch hygiene + +Before starting parallel work: + +```bash +git status --short +git branch --show-current +``` + +Use a clean branch when possible. If the main worktree already has user changes, tell agents not to revert unrelated files and keep task scope narrow. + +Recommended branch style: + +```text +agent// +``` + +Examples: + +```text +agent/docs/mcp-guide +agent/review/task-log-filtering +agent/ui/code-review-polish +``` + +## Review flow + +For isolated worktrees, review the teammate's diff before merging or applying changes back to the main workspace. + +1. Confirm the task result comment names changed scope and verification. +2. Inspect the task diff in the review UI. +3. Ask for changes on the task if the diff touches unrelated files. +4. Approve only after tests or manual checks match the task risk. +5. Merge or apply changes deliberately. + +Do not auto-merge worktree output just because the task is complete. Completion means the agent believes the work is ready for review. + +## Conflict policy + +Use this policy for parallel teams: + +| Situation | Action | +| --- | --- | +| Two teammates edit the same file | Pause one task or make one owner responsible for integration | +| Generated files changed broadly | Require a comment explaining the generator and command | +| Main worktree has unrelated changes | Preserve them and review only task-owned changes | +| Worktree branch diverges | Rebase or merge manually after review, not inside a vague agent task | + +## Task prompt example + +```text +Implement the settings validation fix in your assigned worktree. Keep edits inside src/features/settings and focused tests. Do not touch provider auth or task storage. Post the test command and result before completing the task. +``` + +This prompt works because it names the allowed area, sensitive boundaries, and completion evidence. + +## Related guides + +- [Create a team](/guide/create-team) +- [Code review](/guide/code-review) +- [Team brief examples](/guide/team-brief-examples) diff --git a/landing/product-docs/guide/installation.md b/landing/product-docs/guide/installation.md index 720bb1a9..fe04b621 100644 --- a/landing/product-docs/guide/installation.md +++ b/landing/product-docs/guide/installation.md @@ -34,7 +34,7 @@ To use agent runtimes, you need access to at least one provider: | OpenCode | API key for a supported backend (e.g. OpenRouter) | ::: info -Gemini provider support is in development. You can prepare access now, but it will not appear in the team editor until it is ready. +Gemini provider support is in development. See [Providers and runtimes](/reference/providers-runtimes) for current status across all providers. ::: For source development, you also need: diff --git a/landing/product-docs/guide/mcp-integration.md b/landing/product-docs/guide/mcp-integration.md new file mode 100644 index 00000000..e1fed198 --- /dev/null +++ b/landing/product-docs/guide/mcp-integration.md @@ -0,0 +1,224 @@ +--- +title: MCP Integration - Agent Teams Docs +description: Configure MCP in Agent Teams for board operations, teammate coordination, external tool servers, and custom tool development. +--- + +# MCP Integration + +Agent Teams uses MCP in two practical layers: + +| Layer | What it does | Who uses it | +| --- | --- | --- | +| Built-in board server | Exposes Agent Teams task, message, review, process, runtime, and cross-team tools | Leads and teammates launched by the app | +| External MCP servers | Add optional tools such as browser automation, design context, docs search, or company systems | Users and configured runtimes | + +Keep those layers separate. The built-in `agent-teams` MCP server is how agents coordinate inside Agent Teams. External MCP servers are optional runtime tools. + +## How Agent Teams injects MCP + +When the desktop app launches Claude-based team members, it writes a temporary `--mcp-config` JSON file containing the built-in `agent-teams` server: + +```json +{ + "mcpServers": { + "agent-teams": { + "command": "node", + "args": ["/path/to/agent-teams-mcp/index.js"], + "env": { + "AGENT_TEAMS_MCP_CLAUDE_DIR": "/Users/you/.claude" + } + } + } +} +``` + +In development, the command may point at `mcp-server/src/index.ts` through `tsx`. In packaged builds, the app copies the bundled MCP server to a stable app-data path and runs it with Node. The generated file is app-owned and cleaned up best effort. + +User and project MCP servers remain separate. The app reads installed servers from: + +| Scope | Location | +| --- | --- | +| User | `~/.claude.json` under `mcpServers` | +| Local project entry in Claude config | `~/.claude.json` under `projects[projectPath].mcpServers` | +| Project | `/.mcp.json` under `mcpServers` | + +Prefer project scope for tools that belong to one repository. Prefer user scope for tools you reuse across unrelated projects. + +## Project `.mcp.json` example + +Place this file at the project root when a team should see the same project-scoped server: + +```json +{ + "mcpServers": { + "docs-search": { + "command": "npx", + "args": ["-y", "@acme/docs-search-mcp"], + "env": { + "DOCS_INDEX_PATH": "./docs-index" + } + }, + "local-browser": { + "command": "node", + "args": ["./tools/mcp/browser-server.js"] + } + } +} +``` + +Keep secrets out of committed `.mcp.json` files. Put credentials in your shell, a user-scoped config, or the app's custom MCP install flow if the value must stay local. + +## Board MCP workflow + +Agents should use board MCP tools when the work belongs to a task: + +1. Read the latest task context. +2. Start the task only when actually beginning work. +3. Add task comments for blockers, plans, and final results. +4. Mark the task complete after the result comment is posted. +5. Send a short message when a lead or teammate needs to know the result. + +Example agent flow: + +```text +task_get -> task_start -> edit/test -> task_add_comment -> task_complete -> message_send +``` + +Use a direct message for coordination. Use a task comment for durable task history. + +::: tip +If the note affects review, verification, changed scope, or a blocker, put it on the task. +::: + +## Built-in Agent Teams tools + +The MCP server registers tools from `agent-teams-controller/src/mcpToolCatalog.js`. The registration loop lives in `mcp-server/src/tools/index.ts`, and each group has its own file under `mcp-server/src/tools/`. + +Common operational tools: + +| Tool | Use | +| --- | --- | +| `task_get` | Read the latest task context, comments, attachments, status, and relations | +| `task_start` | Mark a task in progress when work actually begins | +| `task_add_comment` | Add blocker notes, verification notes, plans, and final result summaries | +| `task_complete` | Complete a task after the final result comment is posted | +| `message_send` | Send a visible inbox message to a lead, teammate, or user | +| `review_request`, `review_start`, `review_approve`, `review_request_changes` | Move task-scoped review workflows | +| `process_register`, `process_list`, `process_stop`, `process_unregister` | Track teammate-owned dev servers, watchers, and other background services | + +Tool names may appear to runtimes with MCP namespace prefixes, for example `mcp__agent-teams__task_get`. The canonical tool name inside the MCP server remains `task_get`. + +## Register a new built-in tool + +For Agent Teams repository work, add built-in board tools through the existing FastMCP structure: + +1. Add the tool implementation to the matching file in `mcp-server/src/tools/`, or create a new group file if the domain is genuinely new. +2. Add the tool name to the appropriate group in `agent-teams-controller/src/mcpToolCatalog.js`. +3. Wire a new group through `mcp-server/src/tools/index.ts` only when a new domain group is needed. +4. Validate input with `zod` and call the controller API instead of reading board files directly. +5. Add focused tests in `mcp-server/test/tools.test.ts` or an e2e case when the transport matters. + +Minimal shape: + +```ts +server.addTool({ + name: 'task_example', + description: 'Explain what this tool does for agents.', + parameters: z.object({ + teamName: z.string().min(1), + claudeDir: z.string().min(1).optional(), + taskId: z.string().min(1) + }), + execute: async ({ teamName, claudeDir, taskId }) => { + assertConfiguredTeam(teamName, claudeDir); + const controller = getController(teamName, claudeDir); + return jsonTextContent(controller.tasks.getTask(taskId)); + } +}); +``` + +Do not create a tool that bypasses controller validation, mutates unrelated team files, or exposes broad filesystem/process access without a narrow task need. + +## External MCP servers + +Use external MCP servers when a teammate needs a durable tool connection, not just one prompt with pasted context. + +Good fits: + +- browser or website testing tools +- design or product data tools +- internal docs and search systems +- issue tracker or support systems +- database inspection tools with read-only credentials + +Poor fits: + +- secrets pasted into prompts +- one-off files that can be attached directly +- tools that mutate production systems without review +- broad local filesystem access when a narrower project scope is enough + +## Scopes + +Agent Teams recognizes shared and project-oriented MCP scopes. + +| Scope | Use when | +| --- | --- | +| User or Global | The same server should be available across projects | +| Project or Local | The server belongs to one repository, workspace, or team context | + +Prefer the narrowest scope that still makes the workflow usable. Project-scoped servers are easier to reason about during review because the tool belongs to the project being changed. + +## Setup checklist + +Before assigning a task that depends on an MCP server: + +1. Install or configure the server. +2. Confirm it appears in the app's installed MCP list for the intended scope. +3. Run diagnostics from the MCP registry or extensions UI when available. +4. Start with a low-risk read-only task. +5. Mention the expected MCP tool use in the task description or team brief. + +If a server fails diagnostics, fix that first. A better task prompt will not repair a missing command, wrong config path, or rejected credentials. + +## Install a custom server from the app + +The desktop app exposes MCP registry APIs through Electron IPC for search, browse, install, custom install, uninstall, installed-state reading, and diagnostics. Custom installs validate the server name, scope, project path, env var names, and HTTP headers before calling the runtime install path. + +Use custom install when you have an MCP package that is not in the registry yet: + +| Field | Example | +| --- | --- | +| Server name | `docs-search` | +| Scope | `project` for this repository, `user` for all projects | +| Type | `stdio` for local commands, `http` or `sse` for remote servers | +| Package | `@acme/docs-search-mcp` | +| Env | `DOCS_INDEX_PATH=./docs-index` | + +After install, run diagnostics and create a small read-only task to prove the tool surface before assigning larger work. + +## Task example + +```text +Audit the docs home page with the browser MCP. Check desktop and mobile widths, capture any layout issue as a task comment, and only edit landing/product-docs files. Run the docs build before completion. +``` + +This works because it names the tool, the surface, the write boundary, and the verification step. + +## Safety rules + +- Do not give every teammate every MCP server by default. +- Keep write-capable tools out of broad teams unless review requires them. +- Prefer read-only credentials for inspection tasks. +- Put production-impacting tool use behind explicit task comments and review. +- Treat MCP diagnostic failures as setup failures, not agent failures. +- Avoid committing secrets in `.mcp.json` or prompts. +- Use absolute `projectPath` values when installing project-scoped servers through the app. +- Do not edit the app-generated `agent-teams-mcp-*.json` files; they are temporary launch artifacts. + +## Related guides + +- [Runtime setup](/guide/runtime-setup) +- [Team brief examples](/guide/team-brief-examples) +- [Agent workflow](/guide/agent-workflow) +- [Developers](/developers/) diff --git a/landing/product-docs/guide/quickstart.md b/landing/product-docs/guide/quickstart.md index ac4c1216..e5ee63ee 100644 --- a/landing/product-docs/guide/quickstart.md +++ b/landing/product-docs/guide/quickstart.md @@ -15,6 +15,10 @@ Download the latest release for your platform from the ## Product preview - diff --git a/landing/product-docs/reference/concepts.md b/landing/product-docs/reference/concepts.md index 4277d17d..481c3037 100644 --- a/landing/product-docs/reference/concepts.md +++ b/landing/product-docs/reference/concepts.md @@ -45,7 +45,7 @@ Messages are durable local records. Delivery still depends on the selected runti An agent block is hidden, agent-only instruction text wrapped with `...`. The UI strips these blocks from normal human-facing display, but agents and runtime delivery can use them for coordination details. -The current canonical marker is `info_for_agent`; older documents may still contain legacy agent block formats. +The current canonical marker is `info_for_agent`. Older documents may use block formats wrapped with `` or `[AGENT_BLOCK]` markers — these are legacy patterns and should be migrated to `info_for_agent` when encountered. ## Context Phase diff --git a/landing/product-docs/reference/contributor-architecture.md b/landing/product-docs/reference/contributor-architecture.md new file mode 100644 index 00000000..48357d78 --- /dev/null +++ b/landing/product-docs/reference/contributor-architecture.md @@ -0,0 +1,54 @@ +--- +title: Contributor Architecture – Agent Teams Docs +description: Contributor guide to feature layout, runtime/provider boundaries, hard guardrails, and canonical architecture documents. +--- + +# Contributor Architecture + +This page is a map for contributors. It points to the canonical repo guidance instead of restating every implementation rule. + +## Canonical sources + +Use these files as the source of truth when changing the app: + +| Need | Canonical source | +| --- | --- | +| Repo overview and commands | [README.md](https://github.com/777genius/agent-teams-ai/blob/main/README.md) | +| Local working conventions | [CLAUDE.md](https://github.com/777genius/agent-teams-ai/blob/main/CLAUDE.md) | +| Hard guardrails | [AGENT_CRITICAL_GUARDRAILS.md](https://github.com/777genius/agent-teams-ai/blob/main/AGENT_CRITICAL_GUARDRAILS.md) | +| Medium and large feature layout | [docs/FEATURE_ARCHITECTURE_STANDARD.md](https://github.com/777genius/agent-teams-ai/blob/main/docs/FEATURE_ARCHITECTURE_STANDARD.md) | +| Agent team launch debugging | [docs/team-management/debugging-agent-teams.md](https://github.com/777genius/agent-teams-ai/blob/main/docs/team-management/debugging-agent-teams.md) | + +## Feature layout + +Medium and large features should live under `src/features//` and follow the feature architecture standard. Keep feature internals behind public entrypoints, and avoid deep imports across feature boundaries. + +For new work, start with the existing `src/features/recent-projects` slice as the local reference implementation. Small fixes can stay close to the existing code path when creating a feature slice would add more structure than value. + +## Runtime and provider boundaries + +Agent Teams owns orchestration: teams, tasks, messages, launch state, review UI, diagnostics, and local persistence. + +The selected runtime/provider path owns model execution, auth, model availability, rate limits, tool semantics, and runtime-specific transcript evidence. Do not make prompts or UI state compensate for missing auth, missing binaries, rejected model ids, or provider outages. For user-facing setup details, see [Providers and Runtimes](/reference/providers-runtimes). + +## Agent team debugging + +For launch hangs, OpenCode `registered` / bootstrap-unconfirmed states, missing teammate replies, or suspicious task logs, start from the dedicated debugging runbook. Inspect the newest launch failure artifact under `~/.claude/teams//launch-failure-artifacts/latest.json`, then correlate UI state with persisted files and runtime-specific evidence. + +Avoid broad cleanup while debugging. Stop only the process, lane, team, or smoke run you can identify as belonging to the issue. + +## Contributor conventions + +- Use `pnpm dev` for the desktop Electron app during normal development. +- Do not use browser dev mode as a substitute for desktop runtime, IPC, terminal, provider auth, or team lifecycle behavior. +- Keep Electron main, preload, renderer, shared, and feature responsibilities separate. +- Use `wrapAgentBlock(text)` for agent-only blocks instead of manually concatenating markers. +- Prefer focused verification. Avoid broad `lint:fix` or formatting churn unless the task is explicitly about formatting. +- Treat parsing, task lifecycle, provider/runtime detection, persistence, IPC, Git, and review flows as high-risk areas that need targeted tests or a clear verification path. + +## Related pages + +- [Runtime setup](/guide/runtime-setup) +- [Troubleshooting](/guide/troubleshooting) +- [Code review](/guide/code-review) +- [Privacy and local data](/reference/privacy-local-data) diff --git a/landing/product-docs/reference/faq.md b/landing/product-docs/reference/faq.md index 8950695e..a9089a51 100644 --- a/landing/product-docs/reference/faq.md +++ b/landing/product-docs/reference/faq.md @@ -41,7 +41,7 @@ No. Agent Teams is not a cloud code-sync service. Provider-backed model calls ma ## Where are team files stored? -Team coordination data is stored locally under `~/.claude/teams//`, task files under `~/.claude/tasks//`, and project session data under `~/.claude/projects//` when available. +Team coordination data is stored locally under `~/.claude/teams//` (macOS/Linux) or `%APPDATA%\Claude\teams\\` (Windows), task files under `~/.claude/tasks//` or `%APPDATA%\Claude\tasks\\`, and project session data under `~/.claude/projects//` when available. ## What can leave my machine? diff --git a/landing/product-docs/reference/privacy-local-data.md b/landing/product-docs/reference/privacy-local-data.md index ce968712..f76643a1 100644 --- a/landing/product-docs/reference/privacy-local-data.md +++ b/landing/product-docs/reference/privacy-local-data.md @@ -22,13 +22,16 @@ The desktop app runs on your machine and reads local project/runtime data to pow Important local locations include: -| Location | Purpose | -| --- | --- | -| `~/.claude/teams//` | Team config, member metadata, inboxes, launch state, bootstrap evidence, runtime diagnostics, sent-message records, kanban state, and review-related team files. | -| `~/.claude/tasks//` | Durable task JSON files for the team board. | -| `~/.claude/projects//` | Claude/Codex-style project session files used for session history, context analysis, and transcript-backed UI. | +| Platform | Location | Purpose | +| --- | --- | --- | +| macOS/Linux | `~/.claude/teams//` | Team config, member metadata, inboxes, launch state, bootstrap evidence, runtime diagnostics, sent-message records, kanban state, and review-related team files. | +| Windows | `%APPDATA%\Claude\teams\\` | Same — team config, member metadata, inboxes, launch state, and diagnostics. | +| macOS/Linux | `~/.claude/tasks//` | Durable task JSON files for the team board. | +| Windows | `%APPDATA%\Claude\tasks\\` | Same — durable task JSON files. | +| macOS/Linux | `~/.claude/projects//` | Claude/Codex-style project session files used for session history, context analysis, and transcript-backed UI. | +| Windows | `%APPDATA%\Claude\projects\\` | Same — project session files. | -Exact files can vary by runtime and app version. For launch debugging, the newest evidence is usually under the relevant `~/.claude/teams//` folder. +Exact files can vary by runtime and app version. For launch debugging, the newest evidence is usually under the relevant `~/.claude/teams//` (or `%APPDATA%\Claude\teams\\`) folder. ## What can leave your machine diff --git a/landing/product-docs/reference/providers-runtimes.md b/landing/product-docs/reference/providers-runtimes.md index d112e7f5..b6d7f4df 100644 --- a/landing/product-docs/reference/providers-runtimes.md +++ b/landing/product-docs/reference/providers-runtimes.md @@ -76,6 +76,8 @@ Agent Teams keeps orchestration provider-aware but not provider-owned: - model availability, auth, rate limits, and tool behavior remain runtime/provider responsibilities - OpenCode is the broadest routing path when you want one team to use multiple provider/model lanes +For contributor-facing boundaries and canonical implementation guidance, see [Contributor Architecture](/reference/contributor-architecture). + Recommended patterns: | Pattern | When it helps | Risk | diff --git a/landing/product-docs/reference/release-notes.md b/landing/product-docs/reference/release-notes.md new file mode 100644 index 00000000..92befff7 --- /dev/null +++ b/landing/product-docs/reference/release-notes.md @@ -0,0 +1,41 @@ +--- +title: Release Notes – Agent Teams Docs +description: Release notes and changelog for Agent Teams. Links to the canonical RELEASE.md and CHANGELOG.md for full details. +--- + +# Release Notes + +Current version: **v1.2.0** (2026-03-31) + +## How releases work + +Agent Teams follows [Semantic Versioning](https://semver.org/). Tags pushed to the repository trigger an automated [release workflow](https://github.com/777genius/agent-teams-ai/blob/main/docs/RELEASE.md) that builds signed packages for macOS, Windows, and Linux, then publishes them to GitHub Releases. + +## Recent releases + +### v1.2.0 — Agent Graph, per-team tool approval, interactive AskUserQuestion + +Agent Graph with force-directed visualization and kanban task layout, per-team tool approval controls with readable permission prompts, task comment notifications, and interactive AskUserQuestion buttons. Permission system overhaul with Write/Edit/NotebookEdit seeding and MCP tool catalog integration. See [full changelog](https://github.com/777genius/agent-teams-ai/blob/main/docs/CHANGELOG.md#120---2026-03-31). + +### v1.1.0 — React 19 + Electron 40, user-initiated task starts + +React 19 + Electron 40 migration, user-initiated task starts from the kanban board, auth troubleshooting guide, syntax highlighting for R/Ruby/PHP/SQL, 3x faster transcript search, WSL/Windows path fixes, and XSS vulnerability fix. See [full changelog](https://github.com/777genius/agent-teams-ai/blob/main/docs/CHANGELOG.md#110---2026-03-25). + +### v1.0.0 — Initial public release + +First stable build: CLI/auth reliability in packaged apps, IPC hardening, cross-platform packaging with signed macOS builds, open-source governance docs (LICENSE, CONTRIBUTING, CODE_OF_CONDUCT, SECURITY). See [full changelog](https://github.com/777genius/agent-teams-ai/blob/main/docs/CHANGELOG.md#100---2026-03-23). + +## Canonical sources + +| Document | Description | +| --- | --- | +| [RELEASE.md](https://github.com/777genius/agent-teams-ai/blob/main/docs/RELEASE.md) | Release process, versioning guide, artifact naming, auto-update setup, and release notes template. | +| [CHANGELOG.md](https://github.com/777genius/agent-teams-ai/blob/main/docs/CHANGELOG.md) | Full changelog with all versions, features, improvements, and bug fixes from the user perspective. | +| [GitHub Releases](https://github.com/777genius/agent-teams-ai/releases) | Downloadable installers for all platforms. | + +## Related pages + +- [Installation](/guide/installation) +- [Quickstart](/guide/quickstart) +- [Contributor architecture](/reference/contributor-architecture) +- [Developers](/developers/) diff --git a/landing/product-docs/ru/developers/index.md b/landing/product-docs/ru/developers/index.md new file mode 100644 index 00000000..91e59e43 --- /dev/null +++ b/landing/product-docs/ru/developers/index.md @@ -0,0 +1,67 @@ +--- +title: Разработчикам - Agent Teams Docs +description: Входная страница для contributor docs, архитектуры, guardrails, debugging и MCP extension paths в Agent Teams. +--- + +# Разработчикам + +Эта страница нужна, когда вы меняете Agent Teams, разбираете зависший запуск команды или расширяете runtime через MCP tools. Ссылки ведут в canonical repo docs, чтобы правила реализации не расходились между страницами. + +## С чего начать + +| Нужно | Открыть | +| --- | --- | +| Обзор репозитория, scripts и setup из исходников | [README.md](https://github.com/777genius/agent-teams-ai/blob/main/README.md) | +| Рабочие правила для агентов и contributors | [CLAUDE.md](https://github.com/777genius/agent-teams-ai/blob/main/CLAUDE.md) | +| Жёсткие implementation guardrails | [AGENT_CRITICAL_GUARDRAILS.md](https://github.com/777genius/agent-teams-ai/blob/main/AGENT_CRITICAL_GUARDRAILS.md) | +| Структура medium и large features | [Feature architecture standard](https://github.com/777genius/agent-teams-ai/blob/main/docs/FEATURE_ARCHITECTURE_STANDARD.md) | +| Debugging launch, bootstrap и teammate messaging | [Agent team debugging runbook](https://github.com/777genius/agent-teams-ai/blob/main/docs/team-management/debugging-agent-teams.md) | +| Contribution process | [Contributing guide](https://github.com/777genius/agent-teams-ai/blob/main/.github/CONTRIBUTING.md) | +| Релизы / Changelog | [RELEASE.md](https://github.com/777genius/agent-teams-ai/blob/main/docs/RELEASE.md) — [CHANGELOG.md](https://github.com/777genius/agent-teams-ai/blob/main/docs/CHANGELOG.md) | + +## Локальный development path + +Для обычной разработки запускайте desktop Electron app: + +```bash +pnpm install +pnpm dev +``` + +Browser/web path не заменяет desktop runtime. Desktop mode - поддерживаемый локальный путь, потому что в нём есть IPC, terminals, provider auth, team lifecycle handling, launch diagnostics и runtime bridges, которые используют реальные команды. + +## Architecture checkpoints + +Перед изменением feature определите её границу: + +| Область | Ожидаемое место | +| --- | --- | +| Medium или large product feature | `src/features//` | +| Electron main process orchestration | `src/main/` | +| Preload-safe API surface | `src/preload/` | +| Renderer UI и app state | `src/renderer/` | +| Shared types и pure helpers | `src/shared/` | +| Agent Teams board MCP server | `mcp-server/` | +| Board data controller | `agent-teams-controller/` | + +Используйте `src/features/recent-projects` как reference slice для feature organization. Держите cross-process contracts явными и не делайте deep imports через feature boundaries. + +## Debugging path + +Для launch hangs, OpenCode `registered` / bootstrap-unconfirmed states, missing teammate replies или suspicious task logs: + +1. Начните с [debugging runbook](https://github.com/777genius/agent-teams-ai/blob/main/docs/team-management/debugging-agent-teams.md). +2. Проверьте самый новый artifact pack в `~/.claude/teams//launch-failure-artifacts/latest.json`. +3. Откройте `manifest.json` и посмотрите `classification`, bootstrap breadcrumbs, launch diagnostics, member spawn statuses и redacted log tails. +4. Очищайте только team, run, pane или process, который точно принадлежит smoke test или failed launch. + +## MCP development path + +Agent Teams использует встроенный MCP server `agent-teams` для board operations. User и project MCP servers добавляют внешние capabilities для runtimes. См. [MCP integration](/ru/guide/mcp-integration) для setup examples, структуры `.mcp.json` и tool registration guidance. + +## Related docs + +- [Contributor architecture](/ru/reference/contributor-architecture) +- [Настройка рантайма](/ru/guide/runtime-setup) +- [MCP integration](/ru/guide/mcp-integration) +- [Диагностика](/ru/guide/troubleshooting) diff --git a/landing/product-docs/ru/guide/code-review.md b/landing/product-docs/ru/guide/code-review.md index 7c91c8fb..873f1d38 100644 --- a/landing/product-docs/ru/guide/code-review.md +++ b/landing/product-docs/ru/guide/code-review.md @@ -87,6 +87,8 @@ Team lead — ревьюер по умолчанию. Вы можете наст - **Parsing и task lifecycle logic** — изменения в task references, chunking или filtering могут сломать доставку сообщений - **Persistence и code review flows** — изменения в хранении задач или review state должны оставаться консистентными через IPC layers +Canonical feature layout и hard guardrail links смотрите в [Архитектуре для контрибьюторов](/ru/reference/contributor-architecture). + ## Верификация Лучше запускать focused verification commands. Broad formatting или lint-fix команды не стоит использовать, если задача явно не про форматирование. diff --git a/landing/product-docs/ru/guide/create-team.md b/landing/product-docs/ru/guide/create-team.md index 771af2bc..09e3f5cb 100644 --- a/landing/product-docs/ru/guide/create-team.md +++ b/landing/product-docs/ru/guide/create-team.md @@ -31,7 +31,7 @@ lang: ru-RU Микс провайдеров в одной команде поддерживается — например, Claude lead с OpenCode builder-ами. ::: info -Поддержка Gemini в разработке и появится в списке провайдеров, когда будет готова. +Поддержка провайдера Gemini в разработке. Текущий статус провайдеров смотрите в разделе [Провайдеры и рантаймы](/ru/reference/providers-runtimes). ::: ## Хороший team brief diff --git a/landing/product-docs/ru/guide/git-worktree-strategy.md b/landing/product-docs/ru/guide/git-worktree-strategy.md new file mode 100644 index 00000000..0f2b4cb7 --- /dev/null +++ b/landing/product-docs/ru/guide/git-worktree-strategy.md @@ -0,0 +1,98 @@ +--- +title: Git and Worktree Strategy - Agent Teams Docs +description: Как выбирать main worktree, feature branches или OpenCode worktree isolation для parallel agent work. +--- + +# Git and Worktree Strategy + +Git даёт Agent Teams самый сильный review path: narrow diffs, branch visibility, task-scoped changes и более безопасную parallel work. + +## Choose a strategy + +| Strategy | Когда использовать | Tradeoff | +| --- | --- | --- | +| Main worktree | Solo work, docs-only edits или один teammate за раз | Просто, но parallel edits могут конфликтовать | +| Feature branch | Одна team работает над одним coherent change | Чистый review target, но teammates всё ещё делят files | +| Worktree isolation | Несколько OpenCode teammates могут параллельно менять один repo | Лучше isolation, но merge/review требует дисциплины | + +Начинайте просто. Включайте worktree isolation, когда parallel edits вероятны, а не потому что каждому task нужен отдельный checkout. + +## When to enable worktree isolation + +Включайте для OpenCode teammates, когда: + +- два или больше teammates могут менять один repository одновременно +- task может запускать formatters, code generators или broad tests +- нужно держать branch и diff каждого teammate отдельно +- lead workspace dirty и не должен получать прямые edits + +Оставляйте выключенным, когда: + +- task read-only +- один teammate владеет всеми edits +- repo не Git-tracked +- нужен runtime path, который не поддерживает этот isolation mode + +::: warning +Worktree isolation сейчас применяется к OpenCode members и требует Git-tracked project. +::: + +## Branch hygiene + +Перед parallel work: + +```bash +git status --short +git branch --show-current +``` + +По возможности используйте clean branch. Если main worktree уже содержит user changes, скажите agents не revert unrelated files и держать task scope узким. + +Рекомендуемый branch style: + +```text +agent// +``` + +Примеры: + +```text +agent/docs/mcp-guide +agent/review/task-log-filtering +agent/ui/code-review-polish +``` + +## Review flow + +Для isolated worktrees проверяйте diff teammate до merge или apply в main workspace. + +1. Убедитесь, что task result comment называет changed scope и verification. +2. Проверьте task diff в review UI. +3. Запросите changes в task, если diff трогает unrelated files. +4. Approve только когда tests или manual checks соответствуют risk. +5. Merge или apply changes осознанно. + +Не auto-merge worktree output только потому, что task complete. Completion значит, что agent считает работу ready for review. + +## Conflict policy + +| Situation | Action | +| --- | --- | +| Два teammates меняют один file | Pause one task или назначьте одного owner для integration | +| Generated files changed broadly | Требуйте comment с generator и command | +| Main worktree имеет unrelated changes | Preserve them и review только task-owned changes | +| Worktree branch diverges | Rebase или merge manually после review, не внутри vague agent task | + +## Task prompt example + +```text +Implement the settings validation fix in your assigned worktree. Keep edits inside src/features/settings and focused tests. Do not touch provider auth or task storage. Post the test command and result before completing the task. +``` + +Этот prompt работает, потому что называет allowed area, sensitive boundaries и completion evidence. + +## Related guides + +- [Создание команды](/ru/guide/create-team) +- [Код-ревью](/ru/guide/code-review) +- [Team brief examples](/ru/guide/team-brief-examples) diff --git a/landing/product-docs/ru/guide/installation.md b/landing/product-docs/ru/guide/installation.md index 80001327..ad765bee 100644 --- a/landing/product-docs/ru/guide/installation.md +++ b/landing/product-docs/ru/guide/installation.md @@ -35,7 +35,7 @@ Agent Teams распространяется как desktop-приложение | OpenCode | API key для поддерживаемого бэкенда (например, OpenRouter) | ::: info -Поддержка провайдера Gemini в разработке. Вы можете подготовить доступ сейчас, но он не появится в редакторе команды, пока не будет готов. +Поддержка провайдера Gemini в разработке. Текущий статус всех провайдеров смотрите в разделе [Провайдеры и рантаймы](/ru/reference/providers-runtimes). ::: Для запуска из исходников также нужны: diff --git a/landing/product-docs/ru/guide/mcp-integration.md b/landing/product-docs/ru/guide/mcp-integration.md new file mode 100644 index 00000000..fd5285d9 --- /dev/null +++ b/landing/product-docs/ru/guide/mcp-integration.md @@ -0,0 +1,101 @@ +--- +title: MCP Integration - Agent Teams Docs +description: Как использовать MCP в Agent Teams для board operations, координации teammates и внешних tool servers. +--- + +# MCP Integration + +Agent Teams использует MCP двумя практическими способами: + +| Слой | Что делает | Кто использует | +| --- | --- | --- | +| Board MCP tools | Создают, стартуют, комментируют, завершают и читают tasks | Agents и leads | +| External MCP servers | Добавляют инструменты вроде browser, design, docs или company systems | Users и настроенные runtimes | + +Держите эти слои отдельно. Board MCP нужен для координации внутри Agent Teams. External MCP servers - это дополнительные инструменты для runtimes. + +## Board MCP workflow + +Agents должны использовать board MCP tools, когда работа относится к task: + +1. Прочитать свежий task context. +2. Стартовать task только когда реально начинают работу. +3. Добавлять task comments для blockers, plan и final results. +4. Завершать task после result comment. +5. Отправлять короткое сообщение, если lead или teammate должен увидеть результат. + +Пример flow: + +```text +task_get -> task_start -> edit/test -> task_add_comment -> task_complete -> message_send +``` + +Direct message подходит для координации. Task comment подходит для durable task history. + +::: tip +Если заметка влияет на review, verification, changed scope или blocker, пишите её в task. +::: + +## External MCP servers + +Используйте external MCP servers, когда teammate нужен устойчивый tool connection, а не один prompt с pasted context. + +Хорошие случаи: + +- browser или website testing tools +- design или product data tools +- internal docs и search systems +- issue tracker или support systems +- database inspection tools с read-only credentials + +Плохие случаи: + +- secrets, вставленные в prompts +- one-off files, которые проще attached напрямую +- tools, которые меняют production systems без review +- широкий local filesystem access, когда достаточно project scope + +## Scopes + +Agent Teams распознаёт shared и project-oriented MCP scopes. + +| Scope | Когда использовать | +| --- | --- | +| User или Global | Один server нужен в разных projects | +| Project или Local | Server относится к одному repository, workspace или team context | + +Выбирайте самый узкий scope, который всё ещё удобен. Project-scoped servers легче проверять на review, потому что tool привязан к изменяемому project. + +## Setup checklist + +Перед task, который зависит от MCP server: + +1. Установите или настройте server. +2. Проверьте, что он виден в installed MCP list. +3. Запустите diagnostics, если app их предлагает. +4. Начните с low-risk read-only task. +5. Укажите ожидаемый MCP tool use в task description или team brief. + +Если diagnostics падают, сначала чините setup. Лучший prompt не исправит missing command, неправильный config path или rejected credentials. + +## Task example + +```text +Audit the docs home page with the browser MCP. Check desktop and mobile widths, capture any layout issue as a task comment, and only edit landing/product-docs files. Run the docs build before completion. +``` + +Такой task работает, потому что называет tool, surface, write boundary и verification step. + +## Safety rules + +- Не выдавайте каждому teammate все MCP servers по умолчанию. +- Не добавляйте write-capable tools в broad teams без review. +- Для inspection tasks предпочитайте read-only credentials. +- Production-impacting tool use фиксируйте через explicit task comments и review. +- MCP diagnostic failures считайте setup failures, а не agent failures. + +## Related guides + +- [Runtime setup](/ru/guide/runtime-setup) +- [Team brief examples](/ru/guide/team-brief-examples) +- [Работа агентов](/ru/guide/agent-workflow) diff --git a/landing/product-docs/ru/guide/quickstart.md b/landing/product-docs/ru/guide/quickstart.md index c79dbb74..6c20ec3e 100644 --- a/landing/product-docs/ru/guide/quickstart.md +++ b/landing/product-docs/ru/guide/quickstart.md @@ -16,6 +16,10 @@ lang: ru-RU Приложение бесплатное и с открытым кодом. Выбранный runtime может требовать доступ к провайдеру — подробности в разделе [Установка](/ru/guide/installation). ::: +::: info +Desktop-приложение — основной продукт. Agent Teams также работает в браузере для разработки, но браузерный режим не имеет полного desktop IPC, терминала, provider auth и lifecycle. Для обычной разработки используйте `pnpm dev` (Electron), а не браузерный режим. +::: + ## 2. Откройте проект Запустите приложение и выберите директорию проекта, где агенты будут работать. Agent Teams читает локальные файлы проекта и runtime/session state, чтобы показывать задачи, логи, diffs и активность команды. @@ -43,7 +47,7 @@ git status --short | OpenCode | Для multi-model команд и большого числа provider backends | ::: info -Поддержка Gemini в разработке и появится в списке рантаймов, когда будет готова. +Поддержка провайдера Gemini в разработке. Текущий статус провайдеров смотрите в разделе [Провайдеры и рантаймы](/ru/reference/providers-runtimes). ::: Подробная настройка каждого провайдера — в разделе [Настройка рантайма](/ru/guide/runtime-setup). diff --git a/landing/product-docs/ru/guide/team-brief-examples.md b/landing/product-docs/ru/guide/team-brief-examples.md new file mode 100644 index 00000000..577a5c72 --- /dev/null +++ b/landing/product-docs/ru/guide/team-brief-examples.md @@ -0,0 +1,112 @@ +--- +title: Team Brief Examples - Agent Teams Docs +description: Практические шаблоны team brief для small fixes, docs work, implementation tasks, review и risky areas. +--- + +# Team Brief Examples + +Хороший team brief даёт lead достаточно структуры, чтобы создать small tasks, но не требует заранее расписать каждую деталь реализации. + +Используйте форму: + +```text +Outcome: +Scope: +Boundaries: +Coordination: +Verification: +Review: +``` + +## Minimal brief + +Для маленькой low-risk работы. + +```text +Outcome: Improve the quickstart so a new user can launch one team successfully. +Scope: Keep edits inside landing/product-docs. +Boundaries: Do not rewrite the whole docs structure. +Coordination: Create one or two tasks, keep comments on the task. +Verification: Run the docs build. +Review: Summarize changed pages and any remaining gaps. +``` + +## Implementation brief + +Для code changes внутри одной feature area. + +```text +Outcome: Add a focused improvement to task comment filtering. +Scope: Work inside the task/comment feature files unless a shared helper is clearly needed. +Boundaries: Do not change task storage format or review state semantics. +Coordination: Split parser, UI, and tests into separate tasks if they can be reviewed independently. +Verification: Run the focused unit tests first, then the feature typecheck if touched. +Review: Call out parsing edge cases and any behavior that affects existing task comments. +``` + +## Docs brief + +Для documentation и guide work. + +```text +Outcome: Draft practical workflow guides from the docs audit. +Scope: Add concise VitePress pages under landing/product-docs/guide. +Boundaries: Avoid moving existing navigation hubs owned by other tasks. +Coordination: Check related docs tasks before editing nav. +Verification: Run the VitePress docs build. +Review: Include links added to sidebar and any pages intentionally left as drafts. +``` + +## Review-heavy brief + +Для risky areas: IPC, provider auth, persistence, Git или task lifecycle logic. + +```text +Outcome: Fix the launch failure without changing successful launch behavior. +Scope: Start from the newest launch-failure artifact and the affected runtime adapter. +Boundaries: Do not change provider prompts until setup and runtime evidence are inspected. +Coordination: Make one diagnostic task and one fix task if the cause is confirmed. +Verification: Run focused tests and one desktop smoke check when practical. +Review: Lead must inspect the diff before approval. +``` + +## Mixed provider brief + +Когда teammates работают на разных provider/model lanes. + +```text +Outcome: Implement and review a small feature using separate builder and reviewer lanes. +Scope: Builder edits the feature. Reviewer inspects only the task diff and tests. +Boundaries: Do not switch model ids mid-task unless launch fails before work begins. +Coordination: Builder posts result comment first. Reviewer posts findings as task comments. +Verification: Builder runs focused tests. Reviewer checks failure output and changed scope. +Review: Lead approves only after reviewer comments are resolved. +``` + +## What to avoid + +| Weak brief | Better replacement | +| --- | --- | +| "Improve the app" | Назовите workflow, files и success check | +| "Fix all docs" | Выберите одну guide group и build command | +| "Use the best model" | Назовите provider/model choices или оставьте app defaults | +| "Refactor as needed" | Укажите modules, которые можно менять | +| "Make it production ready" | Определите review, tests и rollout checks | + +## Before launch + +Проверьте перед стартом: + +1. Brief называет concrete outcome. +2. Risk boundaries explicit. +3. Lead может разделить работу на reviewable tasks. +4. Verification commands указаны, если известны. +5. Sensitive areas требуют review before approval. + +Если brief всё ещё широкий, запустите solo или small team и попросите сначала task plan, а не implementation. + +## Related guides + +- [Создание команды](/ru/guide/create-team) +- [MCP integration](/ru/guide/mcp-integration) +- [Git and worktree strategy](/ru/guide/git-worktree-strategy) diff --git a/landing/product-docs/ru/guide/troubleshooting.md b/landing/product-docs/ru/guide/troubleshooting.md index bb5f435a..77f72987 100644 --- a/landing/product-docs/ru/guide/troubleshooting.md +++ b/landing/product-docs/ru/guide/troubleshooting.md @@ -31,6 +31,8 @@ lang: ru-RU Если OpenCode показывает `registered`, но bootstrap не подтверждён, сначала inspect artifacts, прежде чем менять team prompts. +Contributor/debugging details находятся в [Архитектуре для контрибьюторов](/ru/reference/contributor-architecture), где есть ссылка на canonical debugging runbook для agent teams. + Посмотрите на последний artifact неудачного запуска: ```bash diff --git a/landing/product-docs/ru/index.md b/landing/product-docs/ru/index.md index 88b84ee8..8fbf17a5 100644 --- a/landing/product-docs/ru/index.md +++ b/landing/product-docs/ru/index.md @@ -59,11 +59,10 @@ Agent Teams - бесплатное desktop-приложение для орке ## Справочник -Используйте справочник, когда нужны точные термины, поведение провайдеров или границы приватности. +Используйте справочник, когда нужны точные термины, поведение провайдеров, contributor architecture или границы приватности. ## Превью продукта - diff --git a/landing/product-docs/ru/reference/concepts.md b/landing/product-docs/ru/reference/concepts.md index 559a8db6..6bbfb079 100644 --- a/landing/product-docs/ru/reference/concepts.md +++ b/landing/product-docs/ru/reference/concepts.md @@ -51,7 +51,7 @@ Messages - долговечные локальные записи. Но дост Agent Block - скрытый agent-only instruction text, обёрнутый в `...`. UI убирает такие блоки из обычного human-facing display, но agents и runtime delivery могут использовать их для coordination details. -Текущий canonical marker - `info_for_agent`; в старых документах могут встречаться legacy agent block formats. +Текущий canonical marker - `info_for_agent`. В старых документах могут встречаться block formats с маркерами `` или `[AGENT_BLOCK]` — это устаревшие паттерны, которые стоит заменить на `info_for_agent` при встрече. ## Context Phase diff --git a/landing/product-docs/ru/reference/contributor-architecture.md b/landing/product-docs/ru/reference/contributor-architecture.md new file mode 100644 index 00000000..ec95528a --- /dev/null +++ b/landing/product-docs/ru/reference/contributor-architecture.md @@ -0,0 +1,55 @@ +--- +title: Архитектура для контрибьюторов – Документация Agent Teams +description: Карта для контрибьюторов по feature layout, runtime/provider boundaries, hard guardrails и canonical architecture docs. +lang: ru-RU +--- + +# Архитектура для контрибьюторов + +Эта страница - карта для контрибьюторов. Она ведёт к canonical repo guidance и не дублирует все implementation rules. + +## Канонические источники + +Используйте эти файлы как source of truth при изменениях в приложении: + +| Нужно | Канонический источник | +| --- | --- | +| Обзор репозитория и команды | [README.md](https://github.com/777genius/agent-teams-ai/blob/main/README.md) | +| Локальные рабочие conventions | [CLAUDE.md](https://github.com/777genius/agent-teams-ai/blob/main/CLAUDE.md) | +| Жёсткие guardrails | [AGENT_CRITICAL_GUARDRAILS.md](https://github.com/777genius/agent-teams-ai/blob/main/AGENT_CRITICAL_GUARDRAILS.md) | +| Layout средних и больших features | [docs/FEATURE_ARCHITECTURE_STANDARD.md](https://github.com/777genius/agent-teams-ai/blob/main/docs/FEATURE_ARCHITECTURE_STANDARD.md) | +| Диагностика запуска agent teams | [docs/team-management/debugging-agent-teams.md](https://github.com/777genius/agent-teams-ai/blob/main/docs/team-management/debugging-agent-teams.md) | + +## Feature layout + +Средние и большие features должны жить в `src/features//` и следовать feature architecture standard. Держите internals за public entrypoints и не делайте deep imports через границы feature. + +Для новой работы ориентируйтесь на существующий slice `src/features/recent-projects`. Маленькие fixes можно оставлять рядом с текущим code path, если новый feature slice добавит больше структуры, чем пользы. + +## Runtime и provider boundaries + +Agent Teams отвечает за orchestration: teams, tasks, messages, launch state, review UI, diagnostics и local persistence. + +Выбранный runtime/provider path отвечает за model execution, auth, model availability, rate limits, tool semantics и runtime-specific transcript evidence. Не пытайтесь чинить prompts или UI state вместо missing auth, missing binaries, rejected model ids или provider outages. User-facing детали настройки смотрите в [Провайдерах и рантаймах](/ru/reference/providers-runtimes). + +## Диагностика agent teams + +При launch hangs, OpenCode `registered` / bootstrap-unconfirmed states, missing teammate replies или подозрительных task logs начинайте с dedicated debugging runbook. Сначала смотрите newest launch failure artifact в `~/.claude/teams//launch-failure-artifacts/latest.json`, затем сопоставляйте UI state с persisted files и runtime-specific evidence. + +Не делайте broad cleanup во время диагностики. Останавливайте только process, lane, team или smoke run, который точно относится к проблеме. + +## Contributor conventions + +- Используйте `pnpm dev` для desktop Electron app при обычной разработке. +- Не используйте browser dev mode как замену desktop runtime, IPC, terminal, provider auth или team lifecycle behavior. +- Разделяйте ответственности Electron main, preload, renderer, shared и features. +- Используйте `wrapAgentBlock(text)` для agent-only blocks вместо ручной склейки markers. +- Предпочитайте focused verification. Избегайте broad `lint:fix` или formatting churn, если задача не про formatting. +- Parsing, task lifecycle, provider/runtime detection, persistence, IPC, Git и review flows считайте high-risk зонами, где нужны targeted tests или clear verification path. + +## Связанные страницы + +- [Настройка рантайма](/ru/guide/runtime-setup) +- [Диагностика](/ru/guide/troubleshooting) +- [Код-ревью](/ru/guide/code-review) +- [Приватность и локальные данные](/ru/reference/privacy-local-data) diff --git a/landing/product-docs/ru/reference/faq.md b/landing/product-docs/ru/reference/faq.md index 7d79fbed..82a15635 100644 --- a/landing/product-docs/ru/reference/faq.md +++ b/landing/product-docs/ru/reference/faq.md @@ -47,7 +47,7 @@ opencode --version ## Где хранятся team files? -Team coordination data хранится локально в `~/.claude/teams//`, task files - в `~/.claude/tasks//`, а project session data - в `~/.claude/projects//`, когда она доступна. +Team coordination data хранится локально в `~/.claude/teams//` (macOS/Linux) или `%APPDATA%\Claude\teams\\` (Windows), task files - в `~/.claude/tasks//` или `%APPDATA%\Claude\tasks\\`, а project session data - в `~/.claude/projects//`, когда она доступна. ## Что может выйти с моей машины? diff --git a/landing/product-docs/ru/reference/privacy-local-data.md b/landing/product-docs/ru/reference/privacy-local-data.md index a62dbd98..ad233b7b 100644 --- a/landing/product-docs/ru/reference/privacy-local-data.md +++ b/landing/product-docs/ru/reference/privacy-local-data.md @@ -28,13 +28,16 @@ Desktop app работает на вашей машине и читает local Важные local locations: -| Location | Purpose | -| --- | --- | -| `~/.claude/teams//` | Team config, member metadata, inboxes, launch state, bootstrap evidence, runtime diagnostics, sent-message records, kanban state и review-related team files. | -| `~/.claude/tasks//` | Durable task JSON files для team board. | -| `~/.claude/projects//` | Claude/Codex-style project session files для session history, context analysis и transcript-backed UI. | +| Платформа | Location | Purpose | +| --- | --- | --- | +| macOS/Linux | `~/.claude/teams//` | Team config, member metadata, inboxes, launch state, bootstrap evidence, runtime diagnostics, sent-message records, kanban state и review-related team files. | +| Windows | `%APPDATA%\Claude\teams\\` | То же — team config, member metadata, inboxes, launch state и diagnostics. | +| macOS/Linux | `~/.claude/tasks//` | Durable task JSON files для team board. | +| Windows | `%APPDATA%\Claude\tasks\\` | То же — durable task JSON files. | +| macOS/Linux | `~/.claude/projects//` | Claude/Codex-style project session files для session history, context analysis и transcript-backed UI. | +| Windows | `%APPDATA%\Claude\projects\\` | То же — project session files. | -Точные файлы зависят от runtime и версии app. Для launch debugging самые свежие evidence обычно лежат в соответствующей папке `~/.claude/teams//`. +Точные файлы зависят от runtime и версии app. Для launch debugging самые свежие evidence обычно лежат в соответствующей папке `~/.claude/teams//` (или `%APPDATA%\Claude\teams\\`). ## Что может выйти с машины diff --git a/landing/product-docs/ru/reference/providers-runtimes.md b/landing/product-docs/ru/reference/providers-runtimes.md index f633569c..0bb21485 100644 --- a/landing/product-docs/ru/reference/providers-runtimes.md +++ b/landing/product-docs/ru/reference/providers-runtimes.md @@ -82,6 +82,8 @@ Agent Teams остаётся provider-aware, но не provider-owned: - model availability, auth, rate limits и tool behavior остаются ответственностью runtime/provider - OpenCode - основной путь, когда одной team нужны разные provider/model lanes +Contributor-facing границы и canonical implementation guidance смотрите в [Архитектуре для контрибьюторов](/ru/reference/contributor-architecture). + Рекомендуемые patterns: | Pattern | When it helps | Risk | diff --git a/landing/product-docs/ru/reference/release-notes.md b/landing/product-docs/ru/reference/release-notes.md new file mode 100644 index 00000000..bf4be4c2 --- /dev/null +++ b/landing/product-docs/ru/reference/release-notes.md @@ -0,0 +1,42 @@ +--- +title: Релизы – Документация Agent Teams +description: Release notes и changelog для Agent Teams. Ссылки на канонические RELEASE.md и CHANGELOG.md. +lang: ru-RU +--- + +# Релизы + +Текущая версия: **v1.2.0** (2026-03-31) + +## Как публикуются релизы + +Agent Teams следует [Semantic Versioning](https://semver.org/). Пуш тега в репозиторий запускает автоматический [release workflow](https://github.com/777genius/agent-teams-ai/blob/main/docs/RELEASE.md), который собирает подписанные пакеты для macOS, Windows и Linux и публикует их в GitHub Releases. + +## Последние релизы + +### v1.2.0 — Agent Graph, per-team tool approval, interactive AskUserQuestion + +Agent Graph с force-directed визуализацией и kanban layout, per-team tool approval controls с понятными permission prompts, уведомления о комментариях к задачам и интерактивные AskUserQuestion кнопки. Permission system overhaul с Write/Edit/NotebookEdit seeding и MCP tool catalog. Полный [changelog](https://github.com/777genius/agent-teams-ai/blob/main/docs/CHANGELOG.md#120---2026-03-31). + +### v1.1.0 — React 19 + Electron 40, user-initiated task starts + +React 19 + Electron 40 migration, запуск задач пользователем с kanban board, auth troubleshooting guide, подсветка синтаксиса для R/Ruby/PHP/SQL, ускорение поиска транскриптов в 3 раза, исправления WSL/Windows paths и XSS vulnerability. Полный [changelog](https://github.com/777genius/agent-teams-ai/blob/main/docs/CHANGELOG.md#110---2026-03-25). + +### v1.0.0 — Первый публичный релиз + +Первый стабильный билд: надёжность CLI/auth в packaged apps, IPC hardening, cross-platform packaging с подписанными macOS сборками, open-source governance docs (LICENSE, CONTRIBUTING, CODE_OF_CONDUCT, SECURITY). Полный [changelog](https://github.com/777genius/agent-teams-ai/blob/main/docs/CHANGELOG.md#100---2026-03-23). + +## Канонические источники + +| Документ | Описание | +| --- | --- | +| [RELEASE.md](https://github.com/777genius/agent-teams-ai/blob/main/docs/RELEASE.md) | Процесс релиза, версионирование, имена артефактов, auto-update setup и шаблон release notes. | +| [CHANGELOG.md](https://github.com/777genius/agent-teams-ai/blob/main/docs/CHANGELOG.md) | Полный changelog со всеми версиями, фичами, улучшениями и исправлениями. | +| [GitHub Releases](https://github.com/777genius/agent-teams-ai/releases) | Установочные файлы для всех платформ. | + +## Связанные страницы + +- [Установка](/ru/guide/installation) +- [Быстрый старт](/ru/guide/quickstart) +- [Архитектура для контрибьюторов](/ru/reference/contributor-architecture) +- [Разработчикам](/ru/developers/) diff --git a/package.json b/package.json index e1956806..449bfee1 100644 --- a/package.json +++ b/package.json @@ -38,6 +38,7 @@ "dist:mac:x64": "electron-builder --mac --x64", "dist:win": "electron-builder --win", "dist:linux": "electron-builder --linux", + "smoke:packaged": "node ./scripts/electron-builder/smokePackagedApp.cjs", "preview": "electron-vite preview", "typecheck": "tsc --noEmit", "typecheck:workspace": "pnpm typecheck && pnpm --filter agent-teams-mcp typecheck && pnpm --filter agent-teams-mcp typecheck:test", @@ -147,10 +148,12 @@ "diff": "^8.0.3", "dompurify": "^3.4.2", "electron-updater": "^6.7.3", + "fast-json-stringify": "^6.4.0", "fastify": "^5.8.5", "highlight.js": "^11.11.1", "idb-keyval": "^6.2.2", "isbinaryfile": "^6.0.0", + "json-schema-ref-resolver": "^3.0.0", "lucide-react": "^0.577.0", "mdast-util-to-hast": "^13.2.1", "mermaid": "^11.15.0", diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index 6b7e307e..4bb07233 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -213,6 +213,9 @@ importers: electron-updater: specifier: ^6.7.3 version: 6.7.3 + fast-json-stringify: + specifier: ^6.4.0 + version: 6.4.0 fastify: specifier: ^5.8.5 version: 5.8.5 @@ -225,6 +228,9 @@ importers: isbinaryfile: specifier: ^6.0.0 version: 6.0.0 + json-schema-ref-resolver: + specifier: ^3.0.0 + version: 3.0.0 lucide-react: specifier: ^0.577.0 version: 0.577.0(react@19.2.4) @@ -6792,8 +6798,8 @@ packages: fast-json-stable-stringify@2.1.0: resolution: {integrity: sha512-lhd/wF+Lk98HZoTCtlVraHtfh5XYijIjalXck7saUtuanSDyLMxnHhSXEDJqHxD7msR8D0uCmqlkwjCV8xvwHw==} - fast-json-stringify@6.3.0: - resolution: {integrity: sha512-oRCntNDY/329HJPlmdNLIdogNtt6Vyjb1WuT01Soss3slIdyUp8kAcDU3saQTOquEK8KFVfwIIF7FebxUAu+yA==} + fast-json-stringify@6.4.0: + resolution: {integrity: sha512-ibRCQ0GZKJIQ+P3Et1h0LhPgp3PMTYk0MH8O+kW3lNYsvmaQww5Nn3f1jf73Q0jR1Yz3a1CDP4/NZD3vOajWJQ==} fast-levenshtein@2.0.6: resolution: {integrity: sha512-DCXu6Ifhqcks7TZKY3Hxp3y6qphY5SJZmrWMDrKcERSOXWQdMhU9Ig/PYrzyw/ul9jOIyh0N4M0tbC5hodg8dw==} @@ -12337,7 +12343,7 @@ snapshots: '@fastify/fast-json-stringify-compiler@5.0.3': dependencies: - fast-json-stringify: 6.3.0 + fast-json-stringify: 6.4.0 '@fastify/forwarded@3.0.1': {} @@ -18240,7 +18246,7 @@ snapshots: fast-json-stable-stringify@2.1.0: {} - fast-json-stringify@6.3.0: + fast-json-stringify@6.4.0: dependencies: '@fastify/merge-json-schemas': 0.2.1 ajv: 8.18.0 @@ -18269,7 +18275,7 @@ snapshots: '@fastify/proxy-addr': 5.1.0 abstract-logging: 2.0.1 avvio: 9.1.0 - fast-json-stringify: 6.3.0 + fast-json-stringify: 6.4.0 find-my-way: 9.4.0 light-my-request: 6.6.0 pino: 10.3.1 diff --git a/resources/runtime/COMMIT_SHA b/resources/runtime/COMMIT_SHA new file mode 100644 index 00000000..e22468f2 --- /dev/null +++ b/resources/runtime/COMMIT_SHA @@ -0,0 +1 @@ +4968c54bb28f62ce55220de3437fa6d610729736 diff --git a/resources/runtime/VERSION b/resources/runtime/VERSION new file mode 100644 index 00000000..78bae5bb --- /dev/null +++ b/resources/runtime/VERSION @@ -0,0 +1 @@ +0.0.32 diff --git a/resources/runtime/claude-multimodel b/resources/runtime/claude-multimodel new file mode 100755 index 00000000..a41da7f6 Binary files /dev/null and b/resources/runtime/claude-multimodel differ diff --git a/scripts/electron-builder/smokePackagedApp.cjs b/scripts/electron-builder/smokePackagedApp.cjs new file mode 100644 index 00000000..68594830 --- /dev/null +++ b/scripts/electron-builder/smokePackagedApp.cjs @@ -0,0 +1,130 @@ +const fs = require('node:fs'); +const os = require('node:os'); +const path = require('node:path'); +const { spawn } = require('node:child_process'); + +const STARTUP_TIMEOUT_MS = Number(process.env.PACKAGED_SMOKE_TIMEOUT_MS ?? 30_000); +const POST_STARTUP_STABLE_MS = Number(process.env.PACKAGED_SMOKE_STABLE_MS ?? 8_000); +const REQUIRED_LOG_MARKERS = ['renderer did-finish-load']; +const FAILURE_PATTERNS = [ + /Cannot find module/i, + /MODULE_NOT_FOUND/i, + /Failed to start HTTP server/i, + /Unable to set login item/i, + /\[DEP0180\]/i, + /DeprecationWarning: fs\.Stats constructor is deprecated/i, +]; + +function fail(message, log = '') { + console.error(`[smokePackagedApp] ${message}`); + if (log.trim()) { + console.error('--- packaged app log ---'); + console.error(log.trim()); + } + process.exit(1); +} + +function findExecutable(bundlePath, platform) { + if (platform === 'darwin') { + const macOsDir = path.join(bundlePath, 'Contents', 'MacOS'); + const entries = fs.readdirSync(macOsDir); + const executable = entries.find((entry) => { + const fullPath = path.join(macOsDir, entry); + return fs.statSync(fullPath).isFile() && (fs.statSync(fullPath).mode & 0o111) !== 0; + }); + if (!executable) fail(`No executable found in ${macOsDir}`); + return path.join(macOsDir, executable); + } + + if (platform === 'win32') { + const executable = fs + .readdirSync(bundlePath) + .find((entry) => entry.toLowerCase().endsWith('.exe') && !entry.toLowerCase().includes('uninstall')); + if (!executable) fail(`No .exe found in ${bundlePath}`); + return path.join(bundlePath, executable); + } + + if (platform === 'linux') { + const packageJsonPath = path.join(bundlePath, 'resources', 'app.asar.unpacked', 'package.json'); + const packageJson = fs.existsSync(packageJsonPath) + ? JSON.parse(fs.readFileSync(packageJsonPath, 'utf8')) + : {}; + const preferredNames = [packageJson.name, 'agent-teams-ai', 'Agent Teams UI'].filter(Boolean); + for (const name of preferredNames) { + const candidate = path.join(bundlePath, name); + if (fs.existsSync(candidate)) return candidate; + } + + const executable = fs.readdirSync(bundlePath).find((entry) => { + const fullPath = path.join(bundlePath, entry); + return fs.statSync(fullPath).isFile() && (fs.statSync(fullPath).mode & 0o111) !== 0; + }); + if (!executable) fail(`No executable found in ${bundlePath}`); + return path.join(bundlePath, executable); + } + + fail(`Unsupported platform: ${platform}`); +} + +async function main() { + const [bundlePathArg, platform] = process.argv.slice(2); + if (!bundlePathArg || !platform) { + fail('Usage: node ./scripts/electron-builder/smokePackagedApp.cjs '); + } + + const bundlePath = path.resolve(bundlePathArg); + const executable = findExecutable(bundlePath, platform); + const userDataDir = fs.mkdtempSync(path.join(os.tmpdir(), 'agent-teams-smoke-')); + const args = [`--user-data-dir=${userDataDir}`]; + const child = spawn(executable, args, { + env: { + ...process.env, + AGENT_TEAMS_PACKAGED_SMOKE: '1', + }, + stdio: ['ignore', 'pipe', 'pipe'], + }); + + let log = ''; + child.stdout.on('data', (chunk) => { + log += chunk.toString(); + }); + child.stderr.on('data', (chunk) => { + log += chunk.toString(); + }); + + const exitPromise = new Promise((resolve) => { + child.on('exit', (code, signal) => resolve({ code, signal })); + }); + + const deadline = Date.now() + STARTUP_TIMEOUT_MS; + let startupSeenAt = null; + while (Date.now() < deadline) { + if (FAILURE_PATTERNS.some((pattern) => pattern.test(log))) { + child.kill(); + fail('Detected startup failure pattern', log); + } + + if (startupSeenAt === null && REQUIRED_LOG_MARKERS.every((marker) => log.includes(marker))) { + startupSeenAt = Date.now(); + } + + if (startupSeenAt !== null && Date.now() - startupSeenAt >= POST_STARTUP_STABLE_MS) { + child.kill(); + console.log(`[smokePackagedApp] OK ${platform}: ${bundlePath}`); + return; + } + + const exit = await Promise.race([ + exitPromise, + new Promise((resolve) => setTimeout(() => resolve(null), 250)), + ]); + if (exit) { + fail(`Packaged app exited before startup completed: code=${exit.code} signal=${exit.signal}`, log); + } + } + + child.kill(); + fail(`Timed out after ${STARTUP_TIMEOUT_MS}ms waiting for packaged startup`, log); +} + +main().catch((error) => fail(error?.stack || String(error))); diff --git a/src/features/agent-graph/renderer/ui/GraphMemberLogPreviewHud.tsx b/src/features/agent-graph/renderer/ui/GraphMemberLogPreviewHud.tsx index 354cd6f1..f4fbc58b 100644 --- a/src/features/agent-graph/renderer/ui/GraphMemberLogPreviewHud.tsx +++ b/src/features/agent-graph/renderer/ui/GraphMemberLogPreviewHud.tsx @@ -108,6 +108,25 @@ function itemIcon(item: MemberLogPreviewItem): React.JSX.Element { return ; } +function hasOpenCodeRuntimeWarning(preview: MemberLogPreviewMember | undefined): boolean { + return ( + preview?.warnings.some( + (warning) => + warning.code === 'opencode_runtime_timeout' || + warning.code === 'opencode_runtime_unavailable' || + warning.code === 'opencode_ambiguous_lane' + ) === true + ); +} + +function hasOpenCodeDeliveryDelayedWarning(preview: MemberLogPreviewMember | undefined): boolean { + return preview?.warnings.some((warning) => warning.code === 'opencode_delivery_delayed') === true; +} + +function hasOpenCodeEmptyStateWarning(preview: MemberLogPreviewMember | undefined): boolean { + return hasOpenCodeDeliveryDelayedWarning(preview) || hasOpenCodeRuntimeWarning(preview); +} + function resolveEmptyText( preview: MemberLogPreviewMember | undefined, loading: boolean, @@ -123,13 +142,10 @@ function resolveEmptyText( if (hasOnlyCodexUnsupportedCoverage) { return 'Unsupported provider'; } - const hasOpenCodeRuntimeWarning = preview?.warnings.some( - (warning) => - warning.code === 'opencode_runtime_timeout' || - warning.code === 'opencode_runtime_unavailable' || - warning.code === 'opencode_ambiguous_lane' - ); - if ((preview?.items.length ?? 0) === 0 && hasOpenCodeRuntimeWarning) { + if ((preview?.items.length ?? 0) === 0 && hasOpenCodeDeliveryDelayedWarning(preview)) { + return 'OpenCode logs delayed'; + } + if ((preview?.items.length ?? 0) === 0 && hasOpenCodeRuntimeWarning(preview)) { return 'Logs unavailable'; } if (loading && !preview) return 'Loading logs'; @@ -568,7 +584,8 @@ export const GraphMemberLogPreviewHud = ({ : node.label; const preview = previewsByMember.get(normalizeMemberName(memberName)); const items = preview?.items ?? []; - const isInitialLoading = loading && !preview; + const isEmptyLoading = + loading && (!preview || (items.length === 0 && hasOpenCodeEmptyStateWarning(preview))); return (
{items.length > 0 ? ( items.slice(0, 3).map((item) => renderItem(memberName, item)) - ) : isInitialLoading ? ( + ) : isEmptyLoading ? (