[ { "path": ".dockerignore", "content": "# Git and IDE\n.git\n.gitignore\n.idea\n.vscode\n*.md\n!README.md\n\n# Python dev and cache\n__pycache__\n*.py[cod]\n*$py.class\n.venv\nvenv\nuv.lock\n.pytest_cache\n.coverage\nhtmlcov\n.tox\n.mypy_cache\n.ruff_cache\n\n# Tests (not needed in runtime image)\ntests\ntest.py\n*_test.py\npytest.ini\n.pre-commit-config.yaml\n.flake8\n.eslintrc\n.stylelintrc\n\n# Frontend: exclude build artifacts; ship pre-built src/console/dist in image\nwebsite\nconsole/node_modules\nconsole/dist\nconsole/.vite\nnode_modules\n**/node_modules\n**/dist\n!src/copaw/console/dist\n!src/copaw/console/dist/**\n**/.vite\n\n# Example and local config (mount at runtime instead)\nexample\nconfig.json\njobs.json\nsessions_mount_dir\n\n# Misc\n.env\n.env.*\n!.env.example\n.DS_Store\n*.log\nlogs\ncookbook\n" }, { "path": ".flake8", "content": "[flake8]\nexclude =\n scripts/*\n src/agentscope/rpc/*\nmax-line-length = 79\ninline-quotes = \"\navoid-escape = no\nignore =\n F401\n F403\n W503\n E731" }, { "path": ".gitattributes", "content": "*.bat text eol=crlf\n" }, { "path": ".github/ISSUE_TEMPLATE/1-question.md", "content": "---\nname: Question / Discussion\nabout: Ask a question or start a discussion (consider GitHub Discussions for open-ended topics)\ntitle: \"[Question]: \"\nlabels: [\"question\", \"triage\"]\nassignees: []\n---\n\n## Question or topic\n\n[What would you like to ask or discuss?]\n\n## Context\n\n[Relevant setup: CoPaw version, channel, skill, or use case. This helps others answer.]\n\n## Tried so far\n\n[Optional: what you already tried or read (docs, issues, etc.).]\n\n---\n\n**Note:** For general questions or ideas, [GitHub Discussions](https://github.com/agentscope-ai/CoPaw/discussions) may get more visibility. Use this template when the answer might lead to a bug report, feature request, or doc change.\n" }, { "path": ".github/ISSUE_TEMPLATE/2-feature_request.md", "content": "---\nname: Feature Request\nabout: Suggest a new feature or enhancement\ntitle: \"[Feature]: \"\nlabels: [\"enhancement\", \"triage\"]\nassignees: []\n---\n\n## Summary\n\n[One or two sentences: what do you want and why?]\n\n## Component(s) Affected\n\n- [ ] Core / Backend (app, agents, config, providers, utils, local_models)\n- [ ] Console (frontend web UI)\n- [ ] Channels (DingTalk, Feishu, QQ, Discord, iMessage, etc.)\n- [ ] Skills\n- [ ] CLI\n- [ ] Documentation (website)\n- [ ] Tests\n- [ ] CI/CD\n- [ ] Scripts / Deploy\n\n## Problem / Motivation\n\n[What problem does this solve? Who benefits?]\n\n## Proposed Solution\n\n[Describe the feature or change you have in mind. Be as specific as possible.]\n\n## Alternatives Considered\n\n[Any other approaches or workarounds you thought about.]\n\n## Additional Context\n\n[Screenshots, examples, links to docs or similar features elsewhere.]\n\n## Willing to Contribute\n\n- [ ] I am willing to open a PR for this feature (after discussion).\n" }, { "path": ".github/ISSUE_TEMPLATE/3-documentation.md", "content": "---\nname: Documentation\nabout: Report docs issues or suggest documentation improvements\ntitle: \"[Docs]: \"\nlabels: [\"documentation\", \"triage\"]\nassignees: []\n---\n\n## Summary\n\n[What is wrong or missing in the docs? One or two sentences.]\n\n**Docs location:** [e.g. website, README, `website/public/docs/quickstart.en.md`, Console UI copy]\n\n## Type\n\n- [ ] Typo / wording fix\n- [ ] Outdated or incorrect content\n- [ ] Missing section or topic\n- [ ] Broken link or image\n- [ ] Translation (zh/en)\n- [ ] Other\n\n## Details\n\n[Describe the issue or the change you suggest. If possible, point to the exact file or URL.]\n\n**Current (if applicable):**\n[Quote or describe current text.]\n\n**Suggested:**\n[Proposed text or structure.]\n\n## Additional Context\n\n[Optional: related issues, screenshots, which audience this affects.]\n" }, { "path": ".github/ISSUE_TEMPLATE/4-bug_report.md", "content": "---\nname: Bug Report\nabout: Report a bug or unexpected behavior\ntitle: \"[Bug]: \"\nlabels: [\"bug\", \"triage\"]\nassignees: []\n---\n\n## CoPaw Version\n\n[Provide the version of CoPaw you are using, e.g. 0.x.x or git commit hash.]\n[Using `copaw --version` in your command line or checking the version in the console UI can help.]\n\n## Description\n\n[Describe the bug clearly and concisely. What happened vs what you expected?]\n\n**Related PR(s):** #(optional)\n\n**Security considerations:** [If applicable, e.g. auth, env/config exposure]\n\n## Component(s) Affected\n\n- [ ] Core / Backend (app, agents, config, providers, utils, local_models)\n- [ ] Console (frontend web UI)\n- [ ] Channels (DingTalk, Feishu, QQ, Discord, iMessage, etc.)\n- [ ] Skills\n- [ ] CLI\n- [ ] Documentation (website)\n- [ ] Tests\n- [ ] CI/CD\n- [ ] Scripts / Deploy\n\n## Environment\n\n- **CoPaw version:** [e.g. 0.x.x or git commit]\n- **OS:** [e.g. macOS 14, Ubuntu 22.04, Windows 11]\n- **Install method:** [pip / one-line install / Docker / from source]\n- **Python version (if applicable):** [e.g. 3.10]\n\n## Steps to Reproduce\n\n1.\n2.\n3.\n\n## Actual vs Expected\n\n- **Actual:**\n- **Expected:**\n\n## Logs / Screenshots\n\n[Paste relevant log output or attach screenshots. Use code blocks for logs.]\n\n```\n(paste logs here)\n```\n\n## Additional Notes\n\n[Optional: workarounds, similar issues, etc.]\n" }, { "path": ".github/ISSUE_TEMPLATE/5-support_environment.md", "content": "---\nname: Support / Environment\ndescription: Issues with install, Docker, platform, or runtime environment\ntitle: \"[Support]: \"\nlabels: [\"support\", \"triage\"]\nassignees: []\n---\n\n## Summary\n\n[What went wrong during install, run, or in your environment?]\n\n## Environment\n\n- **OS:** [e.g. macOS 14 (Apple Silicon / Intel), Ubuntu 22.04, Windows 11]\n- **Install method:** [pip / one-line install (install.sh or install.ps1) / Docker / from source / ModelScope]\n- **CoPaw version:** [e.g. 0.x.x or commit]\n- **Python version (if applicable):** [e.g. 3.10, 3.12]\n\n## Steps you took\n\n1.\n2.\n3.\n\n## What happened\n\n[Error message, log excerpt, or behavior. Paste relevant output in code blocks.]\n\n```\n(paste here)\n```\n\n## Expected\n\n[What you expected to happen.]\n\n## Additional context\n\n[Optional: conda/venv, WSL, proxy, firewall, or other env details.]\n" }, { "path": ".github/ISSUE_TEMPLATE/config.yml", "content": "# Issue template chooser. Templates are listed alphanumerically.\n# See: https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/configuring-issue-templates-for-your-repository\n\nblank_issues_enabled: true\n\ncontact_links:\n - name: GitHub Discussions\n url: https://github.com/agentscope-ai/CoPaw/discussions\n about: Ask questions, share ideas, or discuss CoPaw here.\n - name: View docs\n url: https://copaw.agentscope.io/\n about: CoPaw docs and guides.\n" }, { "path": ".github/PULL_REQUEST_TEMPLATE.md", "content": "## Description\n\n[Describe what this PR does and why]\n\n**Related Issue:** Fixes #(issue_number) or Relates to #(issue_number)\n\n**Security Considerations:** [If applicable, e.g. channel auth, env/config handling]\n\n## Type of Change\n\n- [ ] Bug fix\n- [ ] New feature\n- [ ] Breaking change\n- [ ] Documentation\n- [ ] Refactoring\n\n## Component(s) Affected\n\n- [ ] Core / Backend (app, agents, config, providers, utils, local_models)\n- [ ] Console (frontend web UI)\n- [ ] Channels (DingTalk, Feishu, QQ, Discord, iMessage, etc.)\n- [ ] Skills\n- [ ] CLI\n- [ ] Documentation (website)\n- [ ] Tests\n- [ ] CI/CD\n- [ ] Scripts / Deploy\n\n## Checklist\n\n- [ ] I ran `pre-commit run --all-files` locally and it passes\n- [ ] If pre-commit auto-fixed files, I committed those changes and reran checks\n- [ ] I ran tests locally (`pytest` or as relevant) and they pass\n- [ ] Documentation updated (if needed)\n- [ ] Ready for review\n\n## Testing\n\n[How to test these changes]\n\n## Local Verification Evidence\n\n```bash\npre-commit run --all-files\n# paste summary result\n\npytest\n# paste summary result\n```\n\n## Additional Notes\n\n[Optional: any other context]\n" }, { "path": ".github/condarc", "content": "# Explicit channels so conda does not warn about implicit 'defaults'\nchannels:\n - defaults\n" }, { "path": ".github/workflows/deploy-website.yml", "content": "# Deploy website to GitHub Pages (see scripts/website_build.sh).\n# Custom domain: copaw.agentscope.io (CNAME).\nname: Deploy website to GitHub Pages\n\non:\n release:\n types: [published]\n workflow_dispatch:\n\npermissions:\n contents: write\n\nconcurrency:\n group: deploy-website\n cancel-in-progress: false\n\njobs:\n deploy:\n runs-on: ubuntu-latest\n steps:\n - name: Checkout\n uses: actions/checkout@v4\n\n - name: Setup pnpm\n uses: pnpm/action-setup@v4\n with:\n version: 9\n\n - name: Setup Node\n uses: actions/setup-node@v4\n with:\n node-version: \"20\"\n cache: \"pnpm\"\n cache-dependency-path: website/pnpm-lock.yaml\n\n - name: Install dependencies\n working-directory: website\n run: pnpm install --frozen-lockfile\n\n - name: Build\n working-directory: website\n env:\n VITE_BASE_PATH: \"/\"\n run: pnpm run build\n\n # Copy installation scripts so they are served from the website\n # (e.g. copaw.agentscope.io/install.sh) instead of raw.githubusercontent.com,\n # which may be blocked by some firewalls.\n - name: Copy installation scripts to dist\n run: cp scripts/install.sh scripts/install.ps1 scripts/install.bat website/dist/\n\n # 404.html fallback for unknown paths (real routes from build script).\n - name: 404 fallback for GitHub Pages\n run: cp website/dist/index.html website/dist/404.html\n\n - name: Deploy to GitHub Pages\n uses: peaceiris/actions-gh-pages@v4\n with:\n github_token: ${{ secrets.GITHUB_TOKEN }}\n publish_dir: website/dist\n cname: copaw.agentscope.io\n" }, { "path": ".github/workflows/desktop-release.yml", "content": "# Build CoPaw Desktop: Windows (conda-pack + NSIS), macOS (conda-pack -> .app)\n# Runs automatically on release publish; also manually via Actions tab.\n\nname: CoPaw Desktop Build\n\non:\n release:\n types: [published]\n workflow_dispatch:\n\npermissions:\n contents: read\n\njobs:\n build-windows:\n runs-on: windows-latest\n steps:\n - name: Checkout\n uses: actions/checkout@v4\n with:\n submodules: recursive\n\n - name: Get version\n id: version\n shell: pwsh\n run: |\n $content = Get-Content src/copaw/__version__.py -Raw\n if ($content -match '__version__\\s*=\\s*\"([^\"]+)\"') {\n $v = $Matches[1]\n } else {\n throw \"Failed to extract version from __version__.py\"\n }\n \"version<> $GITHUB_OUTPUT\n\n - name: Set up Node\n uses: actions/setup-node@v4\n with:\n node-version: \"20\"\n cache: \"npm\"\n cache-dependency-path: console/package-lock.json\n\n - name: Set up Miniconda\n uses: conda-incubator/setup-miniconda@v3\n with:\n auto-update-conda: true\n python-version: \"3.10\"\n activate-environment: \"copaw-build\"\n condarc-file: .github/condarc\n conda-remove-defaults: false\n\n - name: Clean dist directory\n run: rm -rf dist && mkdir -p dist\n\n - name: Build macOS .app\n run: |\n chmod +x scripts/pack/build_macos.sh\n conda run -n copaw-build bash -c 'CREATE_ZIP=1 ./scripts/pack/build_macos.sh'\n\n - name: Upload macOS artifact\n uses: actions/upload-artifact@v4\n with:\n name: CoPaw-Desktop-macOS-${{ steps.version.outputs.version }}\n path: dist/CoPaw-*.zip\n\n upload-release:\n needs: [build-windows, build-macos]\n if: github.event_name == 'release'\n runs-on: ubuntu-latest\n permissions:\n contents: write\n steps:\n - name: Download all artifacts\n uses: actions/download-artifact@v4\n\n - name: Move artifacts to root for upload\n run: |\n mv CoPaw-Desktop-Windows-*/CoPaw-Setup-*.exe . 2>/dev/null || true\n mv CoPaw-Desktop-macOS-*/CoPaw-*.zip . 2>/dev/null || true\n\n - name: Upload to Release\n uses: softprops/action-gh-release@v2\n with:\n files: |\n CoPaw-Setup-*.exe\n CoPaw-*-macOS.zip\n fail-on-unmatched-files: false\n env:\n GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}\n" }, { "path": ".github/workflows/docker-release.yml", "content": "# Build CoPaw multi-arch Docker image and push to DockerHub + Aliyun ACR on release.\n# Pre-release: update and pre only.\n# Formal release: update , pre and latest.\nname: Docker Build and Push on Release\n\non:\n release:\n types: [published]\n workflow_dispatch:\n inputs:\n version:\n description: \"Image tag (e.g. v1.2.3 or v1.2.3-beta.1)\"\n required: true\n type: string\n is_prerelease:\n description: \"Pre-release (do not update latest tag)\"\n required: false\n type: boolean\n default: false\n\nenv:\n ACR_REGISTRY: agentscope-registry.ap-southeast-1.cr.aliyuncs.com\n IMAGE: agentscope/copaw\n\njobs:\n build-and-push:\n runs-on: ubuntu-latest\n steps:\n - name: Checkout\n uses: actions/checkout@v4\n with:\n submodules: recursive\n\n - name: Set up Docker Buildx\n uses: docker/setup-buildx-action@v3\n\n - name: Log in to DockerHub\n uses: docker/login-action@v3\n with:\n registry: docker.io\n username: ${{ secrets.DOCKER_USERNAME }}\n password: ${{ secrets.DOCKER_PASSWORD }}\n\n - name: Log in to Aliyun ACR\n uses: docker/login-action@v3\n with:\n registry: ${{ env.ACR_REGISTRY }}\n username: ${{ secrets.ALIYUN_ACR_USERNAME }}\n password: ${{ secrets.ALIYUN_ACR_PASSWORD }}\n\n - name: Set version and prerelease flag\n id: vars\n run: |\n if [ -n \"${{ github.event.release.tag_name }}\" ]; then\n VERSION=\"${{ github.event.release.tag_name }}\"\n echo \"version=${VERSION}\" >> $GITHUB_OUTPUT\n\n # Parse version to determine if it's a pre-release\n # Beta/alpha/rc/dev are pre-releases, but .post is NOT\n if [[ \"$VERSION\" =~ (beta|alpha|rc|dev) ]]; then\n echo \"is_prerelease=true\" >> $GITHUB_OUTPUT\n elif [[ \"$VERSION\" =~ post ]]; then\n # .post versions should update latest (post-release patches)\n echo \"is_prerelease=false\" >> $GITHUB_OUTPUT\n else\n # Use GitHub's prerelease flag as fallback\n echo \"is_prerelease=${{ github.event.release.prerelease }}\" >> $GITHUB_OUTPUT\n fi\n else\n echo \"version=${{ github.event.inputs.version }}\" >> $GITHUB_OUTPUT\n echo \"is_prerelease=${{ github.event.inputs.is_prerelease }}\" >> $GITHUB_OUTPUT\n fi\n\n - name: Build and push multi-arch (version + pre [+ latest])\n env:\n VERSION: ${{ steps.vars.outputs.version }}\n IS_PRERELEASE: ${{ steps.vars.outputs.is_prerelease }}\n COPAW_DISABLED_CHANNELS: \"imessage\"\n run: |\n TAGS=\"-t ${ACR_REGISTRY}/${IMAGE}:${VERSION} -t ${ACR_REGISTRY}/${IMAGE}:pre\"\n TAGS=\"${TAGS} -t docker.io/${IMAGE}:${VERSION} -t docker.io/${IMAGE}:pre\"\n if [ \"${IS_PRERELEASE}\" != \"true\" ]; then\n TAGS=\"${TAGS} -t ${ACR_REGISTRY}/${IMAGE}:latest -t docker.io/${IMAGE}:latest\"\n fi\n docker buildx build --platform linux/amd64,linux/arm64 \\\n -f deploy/Dockerfile \\\n --build-arg COPAW_DISABLED_CHANNELS=\"${COPAW_DISABLED_CHANNELS}\" \\\n ${TAGS} --push .\n" }, { "path": ".github/workflows/first-time-contributor-welcome.yml", "content": "name: First-Time Contributor Welcome\n\non:\n pull_request_target:\n types: [closed]\n\njobs:\n welcome-comment:\n if: >-\n github.event.pull_request.merged == true &&\n contains(toJSON(github.event.pull_request.labels.*.name), 'first-time-contributor')\n runs-on: ubuntu-latest\n permissions:\n pull-requests: write\n steps:\n - name: Post welcome comment\n uses: actions/github-script@v7\n with:\n script: |\n const author = context.payload.pull_request.user.login;\n const prNumber = context.payload.pull_request.number;\n\n const body = [\n `## Welcome to CoPaw! :tada:`,\n ``,\n `Thank you @${author} for your first contribution! Your PR has been merged. :rocket:`,\n ``,\n `We'd love to give you a shout-out in our release notes! If you're comfortable sharing, ` +\n `please reply to this comment with your social media handles using the format below:`,\n ``,\n '```',\n `discord: your_discord_handle`,\n `x: your_x_handle`,\n `xiaohongshu: your_xiaohongshu_id`,\n '```',\n ``,\n `> **Note:** Only share what you're comfortable with — all fields are optional.`,\n ``,\n `Thanks again for helping make CoPaw better!`,\n ].join('\\n');\n\n await github.rest.issues.createComment({\n owner: context.repo.owner,\n repo: context.repo.repo,\n issue_number: prNumber,\n body,\n });\n\n core.info(`Posted welcome comment on PR #${prNumber} for @${author}`);\n" }, { "path": ".github/workflows/npm-format.yml", "content": "name: NPM Format (website & console)\n\non: [push, pull_request]\n\njobs:\n website:\n name: website format check\n runs-on: ubuntu-latest\n defaults:\n run:\n working-directory: website\n steps:\n - uses: actions/checkout@v4\n\n - name: Setup pnpm\n uses: pnpm/action-setup@v4\n with:\n version: 9\n\n - name: Setup Node\n uses: actions/setup-node@v4\n with:\n node-version: \"20\"\n cache: \"pnpm\"\n cache-dependency-path: website/pnpm-lock.yaml\n\n - name: Install dependencies\n run: pnpm install --frozen-lockfile\n\n - name: Run format check\n run: pnpm run format:check\n\n console:\n name: console format check\n runs-on: ubuntu-latest\n defaults:\n run:\n working-directory: console\n steps:\n - uses: actions/checkout@v4\n\n - name: Setup Node\n uses: actions/setup-node@v4\n with:\n node-version: \"20\"\n cache: \"npm\"\n cache-dependency-path: console/package-lock.json\n\n - name: Install dependencies\n run: npm ci\n\n - name: Run format check\n run: npm run format:check\n" }, { "path": ".github/workflows/pr-label.yml", "content": "name: PR Labeler\n\non:\n pull_request_target:\n types: [opened]\n\njobs:\n first-time-contributor:\n runs-on: ubuntu-latest\n permissions:\n contents: read\n pull-requests: write\n steps:\n - name: Check if first-time contributor\n uses: actions/github-script@v7\n with:\n script: |\n const author = context.payload.pull_request.user.login;\n let isFirstTime = false;\n\n try {\n const { data: searchResult } = await github.rest.search.issuesAndPullRequests({\n q: `repo:${context.repo.owner}/${context.repo.repo} type:pr author:${author} is:closed`,\n });\n isFirstTime = searchResult.total_count === 0;\n if (!isFirstTime) {\n core.info(`${author} has ${searchResult.total_count} closed PRs, skipping label`);\n }\n } catch (err) {\n if (err.status === 422 && err.message && err.message.includes('cannot be searched')) {\n core.warning(`Search API cannot look up author ${author}, skipping first-time label`);\n return;\n }\n throw err;\n }\n\n if (isFirstTime) {\n await github.rest.issues.addLabels({\n owner: context.repo.owner,\n repo: context.repo.repo,\n issue_number: context.payload.pull_request.number,\n labels: ['first-time-contributor'],\n });\n core.info(`Labeled PR #${context.payload.pull_request.number} as first-time-contributor`);\n }\n" }, { "path": ".github/workflows/pre-commit.yml", "content": "name: Pre-commit Checks\n\non: [push, pull_request]\n\njobs:\n run:\n runs-on: ubuntu-latest\n strategy:\n fail-fast: true\n env:\n OS: ubuntu-latest\n PYTHON: \"3.10\"\n steps:\n - uses: actions/checkout@v4\n\n - name: Setup Python\n uses: actions/setup-python@v5\n with:\n python-version: \"3.10\"\n\n - name: Update setuptools and wheel\n run: |\n pip install setuptools==68.2.2 wheel==0.41.2\n\n - name: Install CoPaw with dev dependencies\n run: |\n pip install -q -e \".[dev]\"\n\n - name: Install pre-commit hooks\n run: |\n pre-commit install\n\n - name: Run pre-commit\n run: |\n pre-commit run --all-files > pre-commit.log 2>&1 || true\n cat pre-commit.log\n if grep -q Failed pre-commit.log; then\n echo -e \"\\e[41m [**FAIL**] pre-commit checks failed. Run 'pre-commit run --all-files' locally, commit any auto-fixes, then push again. \\e[0m\"\n exit 1\n fi\n echo -e \"\\e[46m ********************************Passed******************************** \\e[0m\"\n" }, { "path": ".github/workflows/publish-pypi.yml", "content": "# Publish Python package to PyPI when a release is created.\n# Build includes console frontend (see scripts/wheel_build.sh).\n\nname: Publish Python Package to PyPI\n\non:\n workflow_dispatch:\n release:\n types: [published]\n\npermissions:\n contents: read\n\njobs:\n deploy:\n runs-on: ubuntu-latest\n steps:\n - uses: actions/checkout@v4\n\n - name: Set up Python\n uses: actions/setup-python@v5\n with:\n python-version: \"3.10\"\n\n - name: Set up Node (for console build)\n uses: actions/setup-node@v4\n with:\n node-version: \"20\"\n cache: \"npm\"\n cache-dependency-path: console/package-lock.json\n\n - name: Build console frontend\n run: |\n cd console && npm ci && npm run build\n\n - name: Copy console build into package\n run: |\n rm -rf src/copaw/console/*\n mkdir -p src/copaw/console\n cp -R console/dist/* src/copaw/console/\n\n - name: Install build dependencies\n run: |\n python -m pip install --upgrade pip\n pip install setuptools wheel build\n\n - name: Build package\n run: python -m build\n\n - name: Publish package to PyPI\n uses: pypa/gh-action-pypi-publish@release/v1\n with:\n user: __token__\n password: ${{ secrets.PYPI_API_TOKEN }}\n" }, { "path": ".github/workflows/tests.yml", "content": "name: Tests\n\non:\n push:\n branches: [main, master, dev, develop]\n paths:\n - 'src/**'\n - 'tests/**'\n - 'pyproject.toml'\n - 'setup.py'\n - '.github/workflows/tests.yml'\n pull_request:\n branches: [main, master, dev, develop]\n paths:\n - 'src/**'\n - 'tests/**'\n - 'pyproject.toml'\n - 'setup.py'\n - '.github/workflows/tests.yml'\n workflow_dispatch:\n\njobs:\n approval-gate:\n name: Maintainer Approval\n runs-on: ubuntu-latest\n environment: maintainer-approved\n steps:\n - name: Approval granted\n run: echo \"Approved by maintainer\"\n\n unit-tests:\n name: Unit Tests - py${{ matrix.python-version }} - ${{ matrix.os }}\n needs: approval-gate\n if: |\n always() &&\n needs.approval-gate.result == 'success'\n runs-on: ${{ matrix.os }}\n strategy:\n fail-fast: false\n matrix:\n python-version: [\"3.10\", \"3.13\"]\n os: [ubuntu-latest]\n include:\n - os: macos-latest\n python-version: \"3.10\"\n - os: windows-latest\n python-version: \"3.10\"\n\n steps:\n - uses: actions/checkout@v4\n\n - name: Set up Node.js (for console build)\n uses: actions/setup-node@v4\n with:\n node-version: '20'\n cache: 'npm'\n cache-dependency-path: console/package-lock.json\n\n - name: Build console frontend\n shell: bash\n run: |\n cd console && npm ci && npm run build\n\n - name: Copy console build into package\n shell: bash\n run: |\n rm -rf src/copaw/console/*\n mkdir -p src/copaw/console\n cp -R console/dist/* src/copaw/console/\n\n - name: Set up Python ${{ matrix.python-version }}\n uses: actions/setup-python@v5\n with:\n python-version: ${{ matrix.python-version }}\n cache: 'pip'\n\n - name: Install dependencies\n shell: bash\n run: |\n python -m pip install --upgrade pip\n if [[ \"${{ matrix.os }}\" == \"macos-latest\" ]]; then\n pip install -e \".[dev,local,ollama]\"\n pip install 'mlx-lm>=0.10.0' || echo \"mlx-lm install skipped\"\n pip install --only-binary=llama-cpp-python 'llama-cpp-python>=0.3.0' || \\\n echo \"⚠️ llama-cpp-python prebuilt wheel not available, skipping\"\n else\n pip install -e \".[dev,full]\"\n fi\n\n - name: Run all unit tests\n shell: bash\n run: |\n pytest tests/unit -v\n\n integrated-tests:\n name: Integrated Tests - py${{ matrix.python-version }} - ${{ matrix.os }}\n needs: approval-gate\n if: |\n always() &&\n needs.approval-gate.result == 'success'\n runs-on: ${{ matrix.os }}\n strategy:\n fail-fast: false\n matrix:\n python-version: [\"3.10\", \"3.13\"]\n os: [ubuntu-latest]\n include:\n - os: macos-latest\n python-version: \"3.10\"\n - os: windows-latest\n python-version: \"3.10\"\n\n steps:\n - uses: actions/checkout@v4\n\n - name: Set up Node.js (for console build)\n uses: actions/setup-node@v4\n with:\n node-version: '20'\n cache: 'npm'\n cache-dependency-path: console/package-lock.json\n\n - name: Build console frontend\n shell: bash\n run: |\n cd console && npm ci && npm run build\n\n - name: Copy console build into package\n shell: bash\n run: |\n rm -rf src/copaw/console/*\n mkdir -p src/copaw/console\n cp -R console/dist/* src/copaw/console/\n\n - name: Set up Python ${{ matrix.python-version }}\n uses: actions/setup-python@v5\n with:\n python-version: ${{ matrix.python-version }}\n cache: 'pip'\n\n - name: Install dependencies\n shell: bash\n run: |\n python -m pip install --upgrade pip\n if [[ \"${{ matrix.os }}\" == \"macos-latest\" ]]; then\n pip install -e \".[dev,local,ollama]\"\n pip install 'mlx-lm>=0.10.0' || echo \"mlx-lm install skipped\"\n pip install --only-binary=llama-cpp-python 'llama-cpp-python>=0.3.0' || \\\n echo \"⚠️ llama-cpp-python prebuilt wheel not available, skipping\"\n else\n pip install -e \".[dev,full]\"\n fi\n\n - name: Check if integrated tests exist\n id: check-integrated\n shell: bash\n run: |\n if [ -d \"tests/integrated\" ] && compgen -G \"tests/integrated/*.py\" > /dev/null; then\n echo \"has_tests=true\" >> \"$GITHUB_OUTPUT\"\n else\n echo \"has_tests=false\" >> \"$GITHUB_OUTPUT\"\n fi\n\n - name: Run integrated tests\n if: steps.check-integrated.outputs.has_tests == 'true'\n shell: bash\n run: |\n pytest tests/integrated -v\n\n coverage-report:\n name: Coverage Report\n needs: approval-gate\n if: |\n always() &&\n needs.approval-gate.result == 'success'\n runs-on: ubuntu-latest\n permissions:\n contents: read\n pull-requests: write\n steps:\n - uses: actions/checkout@v4\n\n - name: Set up Node.js (for console build)\n uses: actions/setup-node@v4\n with:\n node-version: '20'\n cache: 'npm'\n cache-dependency-path: console/package-lock.json\n\n - name: Build console frontend\n shell: bash\n run: |\n cd console && npm ci && npm run build\n\n - name: Copy console build into package\n shell: bash\n run: |\n rm -rf src/copaw/console/*\n mkdir -p src/copaw/console\n cp -R console/dist/* src/copaw/console/\n\n - name: Set up Python 3.12\n uses: actions/setup-python@v5\n with:\n python-version: \"3.12\"\n cache: 'pip'\n\n - name: Install dependencies\n shell: bash\n run: |\n python -m pip install --upgrade pip\n pip install -e \".[dev,full]\"\n\n - name: Run all tests with coverage\n shell: bash\n run: |\n pytest tests/ \\\n -v \\\n --cov=src/copaw \\\n --cov-report=xml \\\n --cov-report=term-missing \\\n --cov-report=html\n\n - name: Generate coverage comment on PR\n if: github.event_name == 'pull_request' && github.event.pull_request.head.repo.full_name == github.repository\n uses: orgoro/coverage@v3.2\n with:\n coverageFile: coverage.xml\n token: ${{ github.token }}\n thresholdAll: 0.0\n thresholdNew: 0.0\n thresholdModified: 0.0\n\n test-summary:\n name: Test Summary\n needs: [approval-gate, unit-tests, integrated-tests, coverage-report]\n if: always()\n runs-on: ubuntu-latest\n steps:\n - name: Check test results\n shell: bash\n run: |\n echo \"Approval gate: ${{ needs.approval-gate.result }}\"\n echo \"Unit tests: ${{ needs.unit-tests.result }}\"\n echo \"Integrated tests: ${{ needs.integrated-tests.result }}\"\n\n if [ \"${{ needs.approval-gate.result }}\" != \"success\" ]; then\n echo \"❌ Approval not granted\"\n exit 1\n fi\n\n if [ \"${{ needs.unit-tests.result }}\" = \"failure\" ] || \\\n [ \"${{ needs.integrated-tests.result }}\" = \"failure\" ]; then\n echo \"❌ Some tests failed\"\n exit 1\n else\n echo \"✅ All tests passed\"\n fi\n" }, { "path": ".gitignore", "content": "# See https://help.github.com/articles/ignoring-files/ for more about ignoring files.\n\n# dependencies\n/.pnp\n.pnp.js\nnode_modules/\nsessions_mount_dir/\n\n# testing\n/coverage\n\n# cookbook\ncookbook/_build\n\n# production\n/build\ndist/\n.wheelshim/\n# Console frontend build (generated in Docker/CI, do not commit)\nsrc/copaw/console/dist/\nsrc/copaw/console/\n\n# frontend (website)\nwebsite/node_modules/\nwebsite/.vite/\nwebsite/tsconfig.tsbuildinfo\nwebsite/dist/\n# Search index generated by scripts/build-search-index.mjs (run during build)\nwebsite/public/search-index.json\n\n# misc\n.env\n.env.*\nproviders.json\nenvs.json\n!.env.example\n!.env.template\n__pycache__/\n*.db\n*.rdb\n*.egg-info/\n*.zip\nconfig.json\n\n# IDEs and editors\n.idea/\n.vscode/\n*.suo\n*.ntvs*\n*.njsproj\n*.sln\n*.sw?\n\n# Logs\nnpm-debug.log*\nyarn-debug.log*\nyarn-error.log*\nopenapi-ts*.log\n\n# MacOS\n.DS_Store\n\n# Windows\nThumbs.db\nehthumbs.db\nDesktop.ini\n\n# Linux\n*~\n\n# Python\n*.py[cod]\n*$py.class\nuv.lock\nvenv/\n.venv/\nproviders.json\n\n# Logs\nlogs/\n*.log\n\n# vibe coding\n.claude\nopenspec\n/AGENTS.md\nCLAUDE.md\n*.tmp\n\n# Build cache\n.cache/ # Includes conda_unpack_wheels/ for Windows packaging workaround\n" }, { "path": ".pre-commit-config.yaml", "content": "repos:\n - repo: https://github.com/pre-commit/pre-commit-hooks\n rev: v4.3.0\n hooks:\n - id: check-ast\n exclude: '(?x)(.*/skills/.*|^scripts/pack/)'\n - id: sort-simple-yaml\n exclude: '(?x)(.*/skills/.*|^scripts/pack/)'\n - id: check-yaml\n exclude: |\n (?x)^(\n meta.yaml\n )$\n - id: check-xml\n exclude: '(?x)(.*/skills/.*|^scripts/pack/)'\n - id: check-toml\n - id: check-docstring-first\n exclude: '(?x)(.*/skills/.*|^scripts/pack/)'\n - id: check-json\n exclude: '(?x)(.*/skills/.*|^scripts/pack/)'\n - id: fix-encoding-pragma\n exclude: '(?x)(.*/skills/.*|^scripts/pack/)'\n - id: detect-private-key\n - id: trailing-whitespace\n exclude: '(?x)(.*/skills/.*|^scripts/pack/)'\n - repo: https://github.com/asottile/add-trailing-comma\n rev: v3.1.0\n hooks:\n - id: add-trailing-comma\n exclude: '(?x)(.*/skills/.*|^scripts/pack/)'\n - repo: https://github.com/pre-commit/mirrors-mypy\n rev: v1.7.0\n hooks:\n - id: mypy\n exclude:\n (?x)(\n pb2\\.py$\n | grpc\\.py$\n | ^docs\n | \\.html$\n | .*/skills/.*\n )\n args: [\n --ignore-missing-imports,\n --disable-error-code=var-annotated,\n --disable-error-code=union-attr,\n --disable-error-code=assignment,\n --disable-error-code=attr-defined,\n --disable-error-code=import-untyped,\n --disable-error-code=truthy-function,\n --follow-imports=skip,\n --explicit-package-bases,\n ]\n - repo: https://github.com/psf/black\n rev: 23.3.0\n hooks:\n - id: black\n args: [ --line-length=79 ]\n exclude: '(?x)(.*/skills/.*|^scripts/pack/)'\n - repo: https://github.com/PyCQA/flake8\n rev: 6.1.0\n hooks:\n - id: flake8\n args: [ \"--extend-ignore=E203\"]\n exclude: '(?x)(.*/skills/.*|^scripts/pack/)'\n - repo: https://github.com/pylint-dev/pylint\n rev: v3.0.2\n hooks:\n - id: pylint\n exclude:\n (?x)(\n ^docs\n | pb2\\.py$\n | grpc\\.py$\n | \\.demo$\n | \\.md$\n | \\.html$\n | .*/skills/.*\n )\n args: [\n --disable=W0511,\n --disable=W0718,\n --disable=W0122,\n --disable=C0103,\n --disable=R0913,\n --disable=E0401,\n --disable=E1101,\n --disable=C0415,\n --disable=W0603,\n --disable=R1705,\n --disable=R0914,\n --disable=E0601,\n --disable=W0602,\n --disable=W0604,\n --disable=R0801,\n --disable=R0902,\n --disable=R0903,\n --disable=C0123,\n --disable=W0231,\n --disable=W1113,\n --disable=W0221,\n --disable=R0401,\n --disable=W0632,\n --disable=W0123,\n --disable=C3001,\n --disable=W0201,\n --disable=C0302,\n --disable=W1203,\n --disable=C2801,\n --disable=C0114, # Disable missing module docstring for quick dev\n --disable=C0115, # Disable missing class docstring for quick dev\n --disable=C0116, # Disable missing function or method docstring for quick dev\n ]\n - repo: https://github.com/pre-commit/mirrors-prettier\n rev: 'v3.0.0'\n hooks:\n - id: prettier\n additional_dependencies: [ 'prettier@3.0.0' ]\n files: \\.(tsx?)$\n exclude: '(?x)(^web/|^console/|/dist/|.*/skills/.*|^scripts/pack/)'" }, { "path": ".python-version", "content": "3.10\n" }, { "path": "CONTRIBUTING.md", "content": "# Contributing to CoPaw\n\n## Welcome! 🐾\n\nThank you for your interest in contributing to CoPaw! CoPaw is an open-source **personal AI assistant** that runs in your own environment—on your machine or in the cloud. It connects to DingTalk, Feishu, QQ, Discord, iMessage, and other chat apps, supports scheduled tasks and heartbeat, and extends its capabilities through **Skills**. We warmly welcome contributions that help make CoPaw more useful for everyone: whether you add a new channel, a new model provider, a Skill, improve docs, or fix bugs.\n\n**Quick links:** [GitHub](https://github.com/agentscope-ai/CoPaw) · [Docs](https://copaw.agentscope.io/) · [License: Apache 2.0](LICENSE)\n\n---\n\n## How to Contribute\n\nTo keep collaboration smooth and maintain quality, please follow these guidelines.\n\n### 1. Check Existing Plans and Issues\n\nBefore starting:\n\n- **Check [Open Issues](https://github.com/agentscope-ai/CoPaw/issues)** and any [Projects](https://github.com/agentscope-ai/CoPaw/projects) or roadmap labels.\n- **If a related issue exists** and is open or unassigned: comment to say you want to work on it to avoid duplicate effort.\n- **If no related issue exists**: open a new issue describing your proposal. The maintainers will respond and can help align with the project direction.\n\n### 2. Commit Message Format\n\nWe follow the [Conventional Commits](https://www.conventionalcommits.org/) specification for clear history and tooling.\n\n**Format:**\n```\n(): \n```\n\n**Types:**\n- `feat:` New feature\n- `fix:` Bug fix\n- `docs:` Documentation only\n- `style:` Code style (whitespace, formatting, etc.)\n- `refactor:` Code change that neither fixes a bug nor adds a feature\n- `perf:` Performance improvement\n- `test:` Adding or updating tests\n- `chore:` Build, tooling, or maintenance\n\n**Examples:**\n```bash\nfeat(channels): add Telegram channel stub\nfix(skills): correct SKILL.md front matter parsing\ndocs(readme): update quick start for Docker\nrefactor(providers): simplify custom provider validation\ntest(agents): add tests for skill loading\n```\n\n### 3. Pull Request Title Format\n\nPR titles should follow the same convention:\n\n**Format:** ` (): `\n\n- Use one of: `feat`, `fix`, `docs`, `test`, `refactor`, `chore`, `perf`, `style`, `build`, `revert`.\n- **Scope must be lowercase** (letters, numbers, hyphens, underscores only).\n- Keep the description short and descriptive.\n\n**Examples:**\n```\nfeat(models): add custom provider for Azure OpenAI\nfix(channels): handle empty content_parts in Discord\ndocs(skills): document Skills Hub import\n```\n\n### 4. Code and Quality\n\n- **Required local gate (must pass before push/PR):**\n ```bash\n pip install -e \".[dev,full]\"\n pre-commit install\n pre-commit run --all-files\n pytest\n ```\n- **If pre-commit modifies files:** Commit those changes, then rerun\n `pre-commit run --all-files` until it passes cleanly.\n- **CI policy:** Pull requests with failing pre-commit checks are not merge-ready.\n- **Frontend formatting:** If your changes involve the `console` or `website` directories, run the formatter before committing:\n ```bash\n cd console && npm run format\n cd website && npm run format\n ```\n- **Documentation:** Update docs and README when you add or change user-facing behavior. The docs live under `website/public/docs/`.\n\n---\n\n## Types of Contributions\n\nCoPaw is designed to be **extensible**: you can add models, channels, Skills, and more. Below are the main contribution areas we care about.\n\n---\n\n### Adding New Models / Model Providers\n\nCoPaw supports **multiple model backends**: cloud APIs (e.g. DashScope, ModelScope), **Ollama**, and local backends (**llama.cpp**, **MLX**). You can contribute in two ways:\n\n#### A. Custom provider (user configuration)\n\nUsers can add **custom providers** via the Console or `providers.json`: any OpenAI-compatible API (e.g. vLLM, SGLang, private endpoints) can be configured with a unique ID, base URL, API key, and optional model list. No code change is required for standard OpenAI-compatible APIs.\n\n#### B. New built-in provider or new ChatModel (code contribution)\n\nIf you want to add a **new built-in provider** or a **new API protocol** that is not OpenAI-compatible:\n\n1. **Provider definition** (in `src/copaw/providers/registry.py` or equivalent):\n - Add a `ProviderDefinition` with `id`, `name`, `default_base_url`, `api_key_prefix`, and optionally `models` and `chat_model`.\n - For local/self-hosted backends, set `is_local` as appropriate.\n\n2. **Chat model class** (if the API is not OpenAI-compatible):\n - Implement a class inheriting from `agentscope.model.ChatModelBase` (or CoPaw’s local/remote wrappers where applicable).\n - Support streaming and non-streaming if the agent uses both; respect `tool_choice` and tools API if used.\n - Register the class in the registry’s chat model map so the runtime can resolve it by name (see `_CHAT_MODEL_MAP` in `src/copaw/providers/registry.py`).\n\n3. **Documentation:** Document the new provider or model in the docs (e.g. under a “Models” or “Providers” section) and mention any env vars or config keys.\n\nAdding a fully new API (new message format, token counting, tools) is a larger change; we recommend opening an issue first to discuss scope and design.\n\n---\n\n### Adding New Channels\n\nChannels are how CoPaw talks to **DingTalk, Feishu, QQ, Discord, iMessage**, etc. You can add a new channel so CoPaw can work with your favorite IM or bot platform.\n\n- **Protocol:** All channels use a unified in-process contract: **native payload → `content_parts`** (e.g. `TextContent`, `ImageContent`, `FileContent`). The agent receives `AgentRequest` with these content parts; replies are sent back via the channel’s send path.\n- **Implementation:** Implement a **subclass of `BaseChannel`** (in `src/copaw/app/channels/base.py`):\n - Set the class attribute `channel` to a unique channel key (e.g. `\"telegram\"`).\n - Implement the lifecycle and message handling (e.g. receive → `content_parts` → `process` → send response).\n - Use the manager’s queue and consumer loop if the channel is long-lived (default).\n- **Discovery:** Built-in channels are registered in `src/copaw/app/channels/registry.py`. **Custom channels** are loaded from the working directory: place a module (e.g. `custom_channels/telegram.py` or a package `custom_channels/telegram/`) that defines a `BaseChannel` subclass with a `channel` attribute.\n- **CLI:** Users install/add channels with:\n - `copaw channels install ` — create a template or copy from `--path` / `--url`\n - `copaw channels add ` — install and add to config\n - `copaw channels remove ` — remove custom channel from `custom_channels/`\n - `copaw channels config` — interactive config\n\nIf you contribute a **new built-in channel**, add it to the registry and, if needed, a configurator so it appears in the Console and CLI. Document the new channel (auth, webhooks, etc.) in `website/public/docs/channels.*.md`.\n\n---\n\n### Adding Base Skills\n\n**Skills** define what CoPaw can do: cron, file reading, PDF/Office, news, browser, etc. We welcome **broadly useful** base skills (productivity, documents, communication, automation) that fit the majority of users.\n\n- **Structure:** Each skill is a **directory** containing:\n - **`SKILL.md`** — Markdown instructions for the agent. Use YAML front matter for at least `name` and `description`; optional `metadata` (e.g. for Console).\n - **`references/`** (optional) — Reference documents the agent can use.\n - **`scripts/`** (optional) — Scripts or tools the skill uses.\n- **Location:** Built-in skills live under `src/copaw/agents/skills//`. The app merges built-in and user **customized_skills** from the working dir into **active_skills**; no extra registration is needed beyond placing a valid `SKILL.md` in a directory.\n- **Content:** Write clear, task-oriented instructions. Describe **when** the skill should be used and **how** (steps, commands, file formats). Avoid overly niche or personal workflows if targeting the **base** repository; those are great as custom or community Skills.\n- **Skills Hub:** CoPaw supports importing skills from a community hub (e.g. ClawHub). If you want your skill to be installable via hub, follow the same `SKILL.md` + `references/`/`scripts/` layout and the hub’s packaging format.\n\nExamples of in-repo base skills: **cron**, **file_reader**, **news**, **pdf**, **docx**, **pptx**, **xlsx**, **browser_visible**. Contributing a new base skill usually means: add the directory under `agents/skills/`, add a short entry in the docs (e.g. Skills table in `website/public/docs/skills.*.md`), and ensure it syncs correctly to the working directory.\n\n#### Writing Effective Skill Descriptions\n\nTo help the model accurately recognize and invoke your skill, the `description` field in your SKILL.md front matter must be **clear, specific, and include trigger keywords**. Follow these best practices:\n\n**✅ Recommended format:**\n```yaml\n---\nname: example_skill\ndescription: \"Use this skill whenever user wants to [main functionality]. Trigger especially when user mentions: [trigger keywords]. Also use when [other scenarios].\"\n\n# Detailed instructions below\n...\n```\n\n**✅ Best practices:**\n1. **Clearly state when to trigger**: Use phrases like \"Use this skill whenever user wants to...\" or \"Trigger when user asks for...\"\n2. **List trigger keywords explicitly**: Make it easy for the model to recognize, for example:\n - \"Trigger especially when user mentions: \\\"call\\\", \\\"dial\\\", \\\"phone\\\", \\\"microsip\\\"\"\n - \"Also trigger for desktop automation tasks like opening apps, controlling windows\"\n3. **Be specific about the skill's scope**: Say exactly what it does, avoid vague terms\n - ✅ Good: \"Make phone calls via MicroSIP or similar desktop apps\"\n - ❌ Not ideal: \"Control desktop\"\n4. **Provide usage examples**: If the skill has specific usage patterns, explain them in the body of SKILL.md\n\n**❌ Common pitfalls:**\n- Overly abstract descriptions (like \"control desktop\", \"process files\")\n- Missing trigger keywords, making it hard for the model to identify use cases\n- Lack of usage scenario context\n\n**📝 Examples comparison:**\n\n| Skill | Description (Not ideal) | Description (Better) |\n|-------|-------------------------|----------------------|\n| Desktop Control | \"Control desktop applications\" | \"Use this skill whenever user wants to control desktop applications or make phone calls. Trigger especially when user mentions: \\\"call\\\", \\\"dial\\\", \\\"phone\\\", \\\"microsip\\\", or requests to use specific desktop apps.\" |\n| File Reader | \"Read files\" | \"Use this skill when user asks to read or summarize local text-based files. PDFs, Office documents, images are out of scope.\" |\n\n---\n\n### Platform support (Windows, Linux, macOS, etc.)\n\nCoPaw aims to run on **Windows**, **Linux**, and **macOS**. Contributions that improve support on a specific platform are welcome.\n\n- **Compatibility fixes:** Path handling, line endings, shell commands, or dependencies that behave differently per OS. For example: Windows compatibility for the memory/vector stack, or install scripts that work on both Linux and macOS.\n- **Install and run:** One-line install (`install.sh`), `pip` install, and `copaw init` / `copaw app` should work (or be clearly documented) on each supported platform. Fixes to install or startup on a given OS are valuable.\n- **Platform-specific features:** Optional integrations (e.g. notifying only when supported) are fine as long as they don’t break other platforms. Use runtime checks or optional dependencies where appropriate.\n- **Documentation:** Document any platform-specific steps, known limitations, or recommended setups (e.g. WSL on Windows, Apple Silicon vs x86) in the docs or README.\n\nIf you add or change platform support, please test on the affected OS and mention it in the PR description. Opening an issue first is recommended for larger or ambiguous platform work.\n\n---\n\n### Other Contributions\n\n- **MCP (Model Context Protocol):** CoPaw supports runtime **MCP tool** discovery and hot-plug. Contributing new MCP servers or tools (or docs on how to attach them) helps users extend the agent without changing core code.\n- **Documentation:** Fixes and improvements to [the docs](https://copaw.agentscope.io/) (under `website/public/docs/`) and README are always welcome.\n- **Bug fixes and refactors:** Small fixes, clearer error messages, and refactors that keep behavior the same are valuable. Prefer opening an issue for larger refactors so we can align on approach.\n- **Examples and workflows:** Tutorials or example workflows (e.g. “daily digest to DingTalk”, “local model + cron”) can be documented or linked from the repo/docs.\n- **Any other useful things!**\n---\n\n## Do's and Don'ts\n\n### ✅ DO\n\n- Start with small, focused changes.\n- Discuss large or design-sensitive changes in an issue first.\n- Write or update tests where applicable.\n- Update documentation for user-facing changes.\n- Use conventional commit messages and PR titles.\n- Be respectful and constructive (we follow a welcoming Code of Conduct).\n\n### ❌ DON'T\n\n- Don’t open very large PRs without prior discussion.\n- Don’t ignore CI or pre-commit failures.\n- Don’t mix unrelated changes in one PR.\n- Don’t break existing APIs without a good reason and clear migration notes.\n- Don’t add heavy or optional dependencies to the core install without discussing in an issue.\n\n---\n\n## Getting Help\n\n- **Discussions:** [GitHub Discussions](https://github.com/agentscope-ai/CoPaw/discussions)\n- **Bugs and features:** [GitHub Issues](https://github.com/agentscope-ai/CoPaw/issues)\n- **Community:** DingTalk group (see [README](README.md)) and [Discord](https://discord.gg/eYMpfnkG8h)\n\nThank you for contributing to CoPaw. Your work helps make it a better assistant for everyone. 🐾\n" }, { "path": "CONTRIBUTING_zh.md", "content": "# 为 CoPaw 贡献代码\n\n## 欢迎！🐾\n\n感谢你对 CoPaw 的关注！CoPaw 是一个开源的**个人 AI 助手**，可以在你自己的环境中运行——无论是你的机器还是云端。它可以连接钉钉、飞书、QQ、Discord、iMessage 等聊天应用，支持定时任务和心跳机制，并通过 **Skills** 扩展其能力。我们热烈欢迎能让 CoPaw 对所有人更有用的贡献：无论是添加新的频道、新的模型提供商、Skill，改进文档，还是修复 bug。\n\n**快速链接：** [GitHub](https://github.com/agentscope-ai/CoPaw) · [文档](https://copaw.agentscope.io/) · [许可证：Apache 2.0](LICENSE)\n\n---\n\n## 如何贡献\n\n为了保持协作顺畅并维护质量，请遵循以下指南。\n\n### 1. 检查现有计划和问题\n\n在开始之前：\n\n- **检查 [Open Issues](https://github.com/agentscope-ai/CoPaw/issues)** 以及任何 [Projects](https://github.com/agentscope-ai/CoPaw/projects) 或路线图标签。\n- **如果存在相关 issue** 且处于开放或未分配状态：发表评论表示你想要处理它，以避免重复工作。\n- **如果不存在相关 issue**：创建一个新 issue 描述你的提案。维护者会回复并帮助与项目方向对齐。\n\n### 2. 提交信息格式\n\n我们遵循 [Conventional Commits](https://www.conventionalcommits.org/) 规范，以保持清晰的历史记录和工具支持。\n\n**格式：**\n```\n(): \n```\n\n**类型：**\n- `feat:` 新功能\n- `fix:` Bug 修复\n- `docs:` 仅文档更改\n- `style:` 代码风格（空格、格式等）\n- `refactor:` 既不修复 bug 也不添加功能的代码更改\n- `perf:` 性能改进\n- `test:` 添加或更新测试\n- `chore:` 构建、工具或维护\n\n**示例：**\n```bash\nfeat(channels): add Telegram channel stub\nfix(skills): correct SKILL.md front matter parsing\ndocs(readme): update quick start for Docker\nrefactor(providers): simplify custom provider validation\ntest(agents): add tests for skill loading\n```\n\n### 3. Pull Request 标题格式\n\nPR 标题应遵循相同的约定：\n\n**格式：** ` (): `\n\n- 使用以下之一：`feat`、`fix`、`docs`、`test`、`refactor`、`chore`、`perf`、`style`、`build`、`revert`。\n- **scope 必须小写**（仅字母、数字、连字符、下划线）。\n- 保持描述简短且描述性强。\n\n**示例：**\n```\nfeat(models): add custom provider for Azure OpenAI\nfix(channels): handle empty content_parts in Discord\ndocs(skills): document Skills Hub import\n```\n\n### 4. 代码和质量\n\n- **本地必跑门禁（push/提 PR 前必须通过）：**\n ```bash\n pip install -e \".[dev,full]\"\n pre-commit install\n pre-commit run --all-files\n pytest\n ```\n- **如果 pre-commit 自动修改了文件：** 先提交这些修改，再重复执行\n `pre-commit run --all-files`，直到无修改且通过。\n- **CI 策略：** pre-commit 检查失败的 PR 视为未就绪（not merge-ready）。\n- **前端代码格式化：** 如果你的修改涉及到 `console` 或 `website` 目录，请在提交前运行格式化：\n ```bash\n cd console && npm run format\n cd website && npm run format\n ```\n- **文档：** 当你添加或更改面向用户的行为时，更新文档和 README。文档位于 `website/public/docs/` 下。\n\n---\n\n## 贡献类型\n\nCoPaw 设计为**可扩展的**：你可以添加模型、频道、Skills 等。以下是我们关心的主要贡献领域。\n\n---\n\n### 添加新模型 / 模型提供商\n\nCoPaw 支持**多种模型后端**：云 API（如 DashScope、ModelScope）、**Ollama** 和本地后端（**llama.cpp**、**MLX**）。你可以通过两种方式贡献：\n\n#### A. 自定义提供商（用户配置）\n\n用户可以通过 Console 或 `providers.json` 添加**自定义提供商**：任何 OpenAI 兼容的 API（如 vLLM、SGLang、私有端点）都可以通过唯一 ID、base URL、API key 和可选的模型列表进行配置。标准 OpenAI 兼容 API 无需代码更改。\n\n#### B. 新的内置提供商或新的 ChatModel（代码贡献）\n\n如果你想添加**新的内置提供商**或**不兼容 OpenAI 的新 API 协议**：\n\n1. **提供商定义**（在 `src/copaw/providers/registry.py` 或等效位置）：\n - 添加一个 `ProviderDefinition`，包含 `id`、`name`、`default_base_url`、`api_key_prefix`，以及可选的 `models` 和 `chat_model`。\n - 对于本地/自托管后端，根据需要设置 `is_local`。\n\n2. **聊天模型类**（如果 API 不兼容 OpenAI）：\n - 实现一个继承自 `agentscope.model.ChatModelBase` 的类（或适用时使用 CoPaw 的本地/远程包装器）。\n - 如果 agent 同时使用流式和非流式，则都要支持；如果使用了 tools API，则遵守 `tool_choice` 和 tools。\n - 在注册表的聊天模型映射中注册该类，以便运行时可以按名称解析它（参见 `src/copaw/providers/registry.py` 中的 `_CHAT_MODEL_MAP`）。\n\n3. **文档：** 在文档中记录新的提供商或模型（例如在\"模型\"或\"提供商\"部分下），并提及任何环境变量或配置键。\n\n添加全新的 API（新消息格式、token 计数、tools）是较大的更改；我们建议先创建 issue 讨论范围和设计。\n\n---\n\n### 添加新频道\n\n频道是 CoPaw 与**钉钉、飞书、QQ、Discord、iMessage** 等通信的方式。你可以添加新频道，以便 CoPaw 可以与你喜欢的 IM 或机器人平台配合使用。\n\n- **协议：** 所有频道使用统一的进程内契约：**原生 payload → `content_parts`**（如 `TextContent`、`ImageContent`、`FileContent`）。agent 接收带有这些内容部分的 `AgentRequest`；回复通过频道的发送路径返回。\n- **实现：** 实现 **`BaseChannel` 的子类**（在 `src/copaw/app/channels/base.py` 中）：\n - 将类属性 `channel` 设置为唯一的频道键（如 `\"telegram\"`）。\n - 实现生命周期和消息处理（如 receive → `content_parts` → `process` → send response）。\n - 如果频道是长期运行的（默认），使用 manager 的队列和消费者循环。\n- **发现：** 内置频道在 `src/copaw/app/channels/registry.py` 中注册。**自定义频道**从工作目录加载：放置一个模块（如 `custom_channels/telegram.py` 或包 `custom_channels/telegram/`），定义一个带有 `channel` 属性的 `BaseChannel` 子类。\n- **CLI：** 用户使用以下命令安装/添加频道：\n - `copaw channels install ` — 创建模板或从 `--path` / `--url` 复制\n - `copaw channels add ` — 安装并添加到配置\n - `copaw channels remove ` — 从 `custom_channels/` 中删除自定义频道\n - `copaw channels config` — 交互式配置\n\n如果你贡献**新的内置频道**，将其添加到注册表，如有需要，添加配置器以使其出现在 Console 和 CLI 中。在 `website/public/docs/channels.*.md` 中记录新频道（身份验证、webhooks 等）。\n\n---\n\n### 添加基础 Skills\n\n**Skills** 定义了 CoPaw 可以做什么：cron、文件读取、PDF/Office、新闻、浏览器等。我们欢迎**广泛有用的**基础 skills（生产力、文档、通信、自动化），适合大多数用户。\n\n- **结构：** 每个 skill 是一个**目录**，包含：\n - **`SKILL.md`** — agent 的 Markdown 指令。使用 YAML front matter 至少包含 `name` 和 `description`；可选的 `metadata`（如用于 Console）。\n - **`references/`**（可选）— agent 可以使用的参考文档。\n - **`scripts/`**（可选）— skill 使用的脚本或工具。\n- **位置：** 内置 skills 位于 `src/copaw/agents/skills//` 下。应用程序将内置和用户的 **customized_skills**（来自工作目录）合并到 **active_skills** 中；除了在目录中放置有效的 `SKILL.md` 外，不需要额外的注册。\n- **内容：** 编写清晰的、面向任务的指令。描述**何时**应该使用该 skill 以及**如何**使用（步骤、命令、文件格式）。如果针对**基础**仓库，避免过于小众或个人的工作流程；这些作为自定义或社区 Skills 非常好。\n\n#### 编写有效的 Skill Description\n\n为了让 model 能够准确识别并调用你的 skill，`description` 字段必须**清晰、具体且包含触发词**。请遵循以下最佳实践：\n\n**✅ 推荐格式：**\n```yaml\n---\nname: example_skill\ndescription: \"Use this skill whenever user wants to [主要功能]. Trigger especially when user mentions: [触发词列表]. Also use when [其他场景].\"\n\n# 详细说明\n...\n```\n\n**✅ 最佳实践：**\n1. **明确触发时机**：使用 \"Use this skill whenever user wants to...\" 或 \"Trigger when user asks for...\"\n2. **列出触发关键词**：在 description 中明确列出触发词，例如：\n - \"Trigger especially when user mentions: \\\"call\\\", \\\"dial\\\", \\\"phone\\\", \\\"microsip\\\"\"\n - \"Also trigger for desktop automation tasks like opening apps, controlling windows\"\n3. **具体描述功能范围**：说明技能做什么，不要含糊\n - ✅ 好的：\"Make phone calls via MicroSIP or similar desktop apps\"\n - ❌ 不好：\"Control desktop\"\n4. **提供使用示例**：如果技能有特定用法，在 SKILL.md 主体部分说明\n\n**❌ 常见问题：**\n- 描述过于抽象（如\"控制桌面\"、\"处理文件\"）\n- 没有列出触发关键词，导致 model 无法识别\n- 缺少使用场景说明\n\n**📝 示例对比：**\n\n| 技能 | 描述（不好） | 描述（好） |\n|------|---------------|-------------|\n| Desktop Control | \"控制桌面应用\" | \"Use this skill whenever user wants to control desktop applications or make phone calls. Trigger especially when user mentions: \\\"call\\\" (呼叫), \\\"dial\\\" (拨打), \\\"phone\\\" (电话), \\\"microsip\\\", or requests to use specific desktop apps.\" |\n| File Reader | \"读取文件\" | \"Use this skill when user asks to read or summarize local text-based files. PDFs, Office documents, and images are out of scope.\" |\n\n- **Skills Hub：** CoPaw 支持从社区 hub（如 ClawHub）导入 skills。如果你希望你的 skill 可以通过 hub 安装，请遵循相同的 `SKILL.md` + `references/`/`scripts/` 布局和 hub 的打包格式。\n\n仓库内基础 skills 的示例：**cron**、**file_reader**、**news**、**pdf**、**docx**、**pptx**、**xlsx**、**browser_visible**。贡献新的基础 skill 通常意味着：在 `agents/skills/` 下添加目录，在文档中添加简短条目（如 `website/public/docs/skills.*.md` 中的 Skills 表），并确保它正确同步到工作目录。\n\n---\n\n### 平台支持（Windows、Linux、macOS 等）\n\nCoPaw 旨在在 **Windows**、**Linux** 和 **macOS** 上运行。欢迎改进特定平台支持的贡献。\n\n- **兼容性修复：** 路径处理、行尾、shell 命令或在不同操作系统上行为不同的依赖项。例如：内存/向量栈的 Windows 兼容性，或在 Linux 和 macOS 上都能工作的安装脚本。\n- **安装和运行：** 一行安装（`install.sh`）、`pip` 安装，以及 `copaw init` / `copaw app` 应该在每个支持的平台上工作（或有清晰的文档说明）。对给定操作系统上的安装或启动的修复很有价值。\n- **平台特定功能：** 可选集成（如仅在支持时通知）是可以的，只要它们不会破坏其他平台。在适当的地方使用运行时检查或可选依赖项。\n- **文档：** 在文档或 README 中记录任何平台特定的步骤、已知限制或推荐设置（如 Windows 上的 WSL、Apple Silicon vs x86）。\n\n如果你添加或更改平台支持，请在受影响的操作系统上进行测试，并在 PR 描述中提及。对于较大或模糊的平台工作，建议先创建 issue。\n\n---\n\n### 其他贡献\n\n- **MCP（模型上下文协议）：** CoPaw 支持运行时 **MCP 工具**发现和热插拔。贡献新的 MCP 服务器或工具（或关于如何附加它们的文档）可以帮助用户扩展 agent 而无需更改核心代码。\n- **文档：** 对 [文档](https://copaw.agentscope.io/)（位于 `website/public/docs/` 下）和 README 的修复和改进始终受欢迎。\n- **Bug 修复和重构：** 小的修复、更清晰的错误消息以及保持行为相同的重构都很有价值。对于较大的重构，最好先创建 issue，以便我们可以就方法达成一致。\n- **示例和工作流程：** 教程或示例工作流程（如\"每日摘要到钉钉\"、\"本地模型 + cron\"）可以记录或从仓库/文档链接。\n- **任何其他有用的东西！**\n\n---\n\n## 应该做和不应该做\n\n### ✅ 应该做\n\n- 从小的、集中的更改开始。\n- 在 issue 中首先讨论大型或涉及敏感的更改。\n- 在适用的地方编写或更新测试。\n- 为面向用户的更改更新文档。\n- 使用常规提交消息和 PR 标题。\n- 保持尊重和建设性（我们遵循友好的行为准则）。\n\n### ❌ 不应该做\n\n- 不要在没有事先讨论的情况下打开非常大的 PR。\n- 不要忽略 CI 或 pre-commit 失败。\n- 不要在一个 PR 中混合不相关的更改。\n- 不要在没有充分理由和清晰迁移说明的情况下破坏现有 API。\n- 不要在没有在 issue 中讨论的情况下向核心安装添加重型或可选依赖项。\n\n---\n\n## 获取帮助\n\n- **讨论：** [GitHub Discussions](https://github.com/agentscope-ai/CoPaw/discussions)\n- **Bug 和功能：** [GitHub Issues](https://github.com/agentscope-ai/CoPaw/issues)\n- **社区：** 钉钉群（见 [README](README_zh.md)）和 [Discord](https://discord.gg/eYMpfnkG8h)\n\n感谢你为 CoPaw 贡献代码。你的工作帮助它成为每个人更好的助手。🐾\n" }, { "path": "LICENSE", "content": " Apache License\n Version 2.0, January 2004\n http://www.apache.org/licenses/\n\n TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION\n\n 1. Definitions.\n\n \"License\" shall mean the terms and conditions for use, reproduction,\n and distribution as defined by Sections 1 through 9 of this document.\n\n \"Licensor\" shall mean the copyright owner or entity authorized by\n the copyright owner that is granting the License.\n\n \"Legal Entity\" shall mean the union of the acting entity and all\n other entities that control, are controlled by, or are under common\n control with that entity. For the purposes of this definition,\n \"control\" means (i) the power, direct or indirect, to cause the\n direction or management of such entity, whether by contract or\n otherwise, or (ii) ownership of fifty percent (50%) or more of the\n outstanding shares, or (iii) beneficial ownership of such entity.\n\n \"You\" (or \"Your\") shall mean an individual or Legal Entity\n exercising permissions granted by this License.\n\n \"Source\" form shall mean the preferred form for making modifications,\n including but not limited to software source code, documentation\n source, and configuration files.\n\n \"Object\" form shall mean any form resulting from mechanical\n transformation or translation of a Source form, including but\n not limited to compiled object code, generated documentation,\n and conversions to other media types.\n\n \"Work\" shall mean the work of authorship, whether in Source or\n Object form, made available under the License, as indicated by a\n copyright notice that is included in or attached to the work\n (an example is provided in the Appendix below).\n\n \"Derivative Works\" shall mean any work, whether in Source or Object\n form, that is based on (or derived from) the Work and for which the\n editorial revisions, annotations, elaborations, or other modifications\n represent, as a whole, an original work of authorship. For the purposes\n of this License, Derivative Works shall not include works that remain\n separable from, or merely link (or bind by name) to the interfaces of,\n the Work and Derivative Works thereof.\n\n \"Contribution\" shall mean any work of authorship, including\n the original version of the Work and any modifications or additions\n to that Work or Derivative Works thereof, that is intentionally\n submitted to the Licensor for inclusion in the Work by the copyright owner\n or by an individual or Legal Entity authorized to submit on behalf of\n the copyright owner. For the purposes of this definition, \"submitted\"\n means any form of electronic, verbal, or written communication sent\n to the Licensor or its representatives, including but not limited to\n communication on electronic mailing lists, source code control systems,\n and issue tracking systems that are managed by, or on behalf of, the\n Licensor for the purpose of discussing and improving the Work, but\n excluding communication that is conspicuously marked or otherwise\n designated in writing by the copyright owner as \"Not a Contribution.\"\n\n \"Contributor\" shall mean Licensor and any individual or Legal Entity\n on behalf of whom a Contribution has been received by Licensor and\n subsequently incorporated within the Work.\n\n 2. Grant of Copyright License. Subject to the terms and conditions of\n this License, each Contributor hereby grants to You a perpetual,\n worldwide, non-exclusive, no-charge, royalty-free, irrevocable\n copyright license to reproduce, prepare Derivative Works of,\n publicly display, publicly perform, sublicense, and distribute the\n Work and such Derivative Works in Source or Object form.\n\n 3. Grant of Patent License. Subject to the terms and conditions of\n this License, each Contributor hereby grants to You a perpetual,\n worldwide, non-exclusive, no-charge, royalty-free, irrevocable\n (except as stated in this section) patent license to make, have made,\n use, offer to sell, sell, import, and otherwise transfer the Work,\n where such license applies only to those patent claims licensable\n by such Contributor that are necessarily infringed by their\n Contribution(s) alone or by combination of their Contribution(s)\n with the Work to which such Contribution(s) was submitted. If You\n institute patent litigation against any entity (including a\n cross-claim or counterclaim in a lawsuit) alleging that the Work\n or a Contribution incorporated within the Work constitutes direct\n or contributory patent infringement, then any patent licenses\n granted to You under this License for that Work shall terminate\n as of the date such litigation is filed.\n\n 4. Redistribution. You may reproduce and distribute copies of the\n Work or Derivative Works thereof in any medium, with or without\n modifications, and in Source or Object form, provided that You\n meet the following conditions:\n\n (a) You must give any other recipients of the Work or\n Derivative Works a copy of this License; and\n\n (b) You must cause any modified files to carry prominent notices\n stating that You changed the files; and\n\n (c) You must retain, in the Source form of any Derivative Works\n that You distribute, all copyright, patent, trademark, and\n attribution notices from the Source form of the Work,\n excluding those notices that do not pertain to any part of\n the Derivative Works; and\n\n (d) If the Work includes a \"NOTICE\" text file as part of its\n distribution, then any Derivative Works that You distribute must\n include a readable copy of the attribution notices contained\n within such NOTICE file, excluding those notices that do not\n pertain to any part of the Derivative Works, in at least one\n of the following places: within a NOTICE text file distributed\n as part of the Derivative Works; within the Source form or\n documentation, if provided along with the Derivative Works; or,\n within a display generated by the Derivative Works, if and\n wherever such third-party notices normally appear. The contents\n of the NOTICE file are for informational purposes only and\n do not modify the License. You may add Your own attribution\n notices within Derivative Works that You distribute, alongside\n or as an addendum to the NOTICE text from the Work, provided\n that such additional attribution notices cannot be construed\n as modifying the License.\n\n You may add Your own copyright statement to Your modifications and\n may provide additional or different license terms and conditions\n for use, reproduction, or distribution of Your modifications, or\n for any such Derivative Works as a whole, provided Your use,\n reproduction, and distribution of the Work otherwise complies with\n the conditions stated in this License.\n\n 5. Submission of Contributions. Unless You explicitly state otherwise,\n any Contribution intentionally submitted for inclusion in the Work\n by You to the Licensor shall be under the terms and conditions of\n this License, without any additional terms or conditions.\n Notwithstanding the above, nothing herein shall supersede or modify\n the terms of any separate license agreement you may have executed\n with Licensor regarding such Contributions.\n\n 6. Trademarks. This License does not grant permission to use the trade\n names, trademarks, service marks, or product names of the Licensor,\n except as required for reasonable and customary use in describing the\n origin of the Work and reproducing the content of the NOTICE file.\n\n 7. Disclaimer of Warranty. Unless required by applicable law or\n agreed to in writing, Licensor provides the Work (and each\n Contributor provides its Contributions) on an \"AS IS\" BASIS,\n WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or\n implied, including, without limitation, any warranties or conditions\n of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A\n PARTICULAR PURPOSE. You are solely responsible for determining the\n appropriateness of using or redistributing the Work and assume any\n risks associated with Your exercise of permissions under this License.\n\n 8. Limitation of Liability. In no event and under no legal theory,\n whether in tort (including negligence), contract, or otherwise,\n unless required by applicable law (such as deliberate and grossly\n negligent acts) or agreed to in writing, shall any Contributor be\n liable to You for damages, including any direct, indirect, special,\n incidental, or consequential damages of any character arising as a\n result of this License or out of the use or inability to use the\n Work (including but not limited to damages for loss of goodwill,\n work stoppage, computer failure or malfunction, or any and all\n other commercial damages or losses), even if such Contributor\n has been advised of the possibility of such damages.\n\n 9. Accepting Warranty or Additional Liability. While redistributing\n the Work or Derivative Works thereof, You may choose to offer,\n and charge a fee for, acceptance of support, warranty, indemnity,\n or other liability obligations and/or rights consistent with this\n License. However, in accepting such obligations, You may act only\n on Your own behalf and on Your sole responsibility, not on behalf\n of any other Contributor, and only if You agree to indemnify,\n defend, and hold each Contributor harmless for any liability\n incurred by, or claims asserted against, such Contributor by reason\n of your accepting any such warranty or additional liability.\n\n END OF TERMS AND CONDITIONS\n\n Copyright 2025 The CoPaw Authors\n\n Licensed under the Apache License, Version 2.0 (the \"License\");\n you may not use this file except in compliance with the License.\n You may obtain a copy of the License at\n\n http://www.apache.org/licenses/LICENSE-2.0\n\n Unless required by applicable law or agreed to in writing, software\n distributed under the License is distributed on an \"AS IS\" BASIS,\n WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n See the License for the specific language governing permissions and\n limitations under the License.\n" }, { "path": "README.md", "content": "
\n\n# CoPaw\n\n[![GitHub Repo](https://img.shields.io/badge/GitHub-Repo-black.svg?logo=github)](https://github.com/agentscope-ai/CoPaw)\n[![PyPI](https://img.shields.io/pypi/v/copaw?color=3775A9&label=PyPI&logo=pypi)](https://pypi.org/project/copaw/)\n[![Documentation](https://img.shields.io/badge/Docs-Website-green.svg?logo=readthedocs&label=Docs)](https://copaw.agentscope.io/)\n[![Python Version](https://img.shields.io/badge/python-3.10%20~%20%3C3.14-blue.svg?logo=python&label=Python)](https://www.python.org/downloads/)\n[![Last Commit](https://img.shields.io/github/last-commit/agentscope-ai/CoPaw)](https://github.com/agentscope-ai/CoPaw)\n[![License](https://img.shields.io/badge/license-Apache%202.0-red.svg?logo=apache&label=License)](LICENSE)\n[![Code Style](https://img.shields.io/badge/code%20style-black-black.svg?logo=python&label=CodeStyle)](https://github.com/psf/black)\n[![GitHub Stars](https://img.shields.io/github/stars/agentscope-ai/CoPaw?style=flat&logo=github&color=yellow&label=Stars)](https://github.com/agentscope-ai/CoPaw/stargazers)\n[![GitHub Forks](https://img.shields.io/github/forks/agentscope-ai/CoPaw?style=flat&logo=github&color=purple&label=Forks)](https://github.com/agentscope-ai/CoPaw/network)\n[![DeepWiki](https://img.shields.io/badge/DeepWiki-Ask_Devin-navy.svg?logo=data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAACwAAAAyCAYAAAAnWDnqAAAAAXNSR0IArs4c6QAAA05JREFUaEPtmUtyEzEQhtWTQyQLHNak2AB7ZnyXZMEjXMGeK/AIi+QuHrMnbChYY7MIh8g01fJoopFb0uhhEqqcbWTp06/uv1saEDv4O3n3dV60RfP947Mm9/SQc0ICFQgzfc4CYZoTPAswgSJCCUJUnAAoRHOAUOcATwbmVLWdGoH//PB8mnKqScAhsD0kYP3j/Yt5LPQe2KvcXmGvRHcDnpxfL2zOYJ1mFwrryWTz0advv1Ut4CJgf5uhDuDj5eUcAUoahrdY/56ebRWeraTjMt/00Sh3UDtjgHtQNHwcRGOC98BJEAEymycmYcWwOprTgcB6VZ5JK5TAJ+fXGLBm3FDAmn6oPPjR4rKCAoJCal2eAiQp2x0vxTPB3ALO2CRkwmDy5WohzBDwSEFKRwPbknEggCPB/imwrycgxX2NzoMCHhPkDwqYMr9tRcP5qNrMZHkVnOjRMWwLCcr8ohBVb1OMjxLwGCvjTikrsBOiA6fNyCrm8V1rP93iVPpwaE+gO0SsWmPiXB+jikdf6SizrT5qKasx5j8ABbHpFTx+vFXp9EnYQmLx02h1QTTrl6eDqxLnGjporxl3NL3agEvXdT0WmEost648sQOYAeJS9Q7bfUVoMGnjo4AZdUMQku50McDcMWcBPvr0SzbTAFDfvJqwLzgxwATnCgnp4wDl6Aa+Ax283gghmj+vj7feE2KBBRMW3FzOpLOADl0Isb5587h/U4gGvkt5v60Z1VLG8BhYjbzRwyQZemwAd6cCR5/XFWLYZRIMpX39AR0tjaGGiGzLVyhse5C9RKC6ai42ppWPKiBagOvaYk8lO7DajerabOZP46Lby5wKjw1HCRx7p9sVMOWGzb/vA1hwiWc6jm3MvQDTogQkiqIhJV0nBQBTU+3okKCFDy9WwferkHjtxib7t3xIUQtHxnIwtx4mpg26/HfwVNVDb4oI9RHmx5WGelRVlrtiw43zboCLaxv46AZeB3IlTkwouebTr1y2NjSpHz68WNFjHvupy3q8TFn3Hos2IAk4Ju5dCo8B3wP7VPr/FGaKiG+T+v+TQqIrOqMTL1VdWV1DdmcbO8KXBz6esmYWYKPwDL5b5FA1a0hwapHiom0r/cKaoqr+27/XcrS5UwSMbQAAAABJRU5ErkJggg==)](https://deepwiki.com/agentscope-ai/CoPaw)\n[![Discord](https://img.shields.io/badge/Discord-Join_Us-blueviolet.svg?logo=discord)](https://discord.gg/eYMpfnkG8h)\n[![X](https://img.shields.io/badge/X-Follow_Us-black.svg?logo=x)](https://x.com/agentscope_ai)\n[![DingTalk](https://img.shields.io/badge/DingTalk-Join_Us-orange.svg)](https://qr.dingtalk.com/action/joingroup?code=v1,k1,OmDlBXpjW+I2vWjKDsjvI9dhcXjGZi3bQiojOq3dlDw=&_dt_no_comment=1&origin=11)\n\n[[Documentation](https://copaw.agentscope.io/)] [[中文 README](README_zh.md)] [[日本語](README_ja.md)]\n\n

\n \"CoPaw\n

\n\n

Works for you, grows with you.

\n\n
\n\nYour Personal AI Assistant; easy to install, deploy on your own machine or on the cloud; supports multiple chat apps with easily extensible capabilities.\n\n> **Core capabilities:**\n>\n> **Every channel** — DingTalk, Feishu, QQ, Discord, iMessage, and more. One assistant, connect as you need.\n>\n> **Under your control** — Memory and personalization under your control. Deploy locally or in the cloud; scheduled reminders to any channel.\n>\n> **Skills** — Built-in cron; custom skills in your workspace, auto-loaded. No lock-in.\n>\n>
\n> What you can do\n>\n>
\n>\n> - **Social**: daily digest of hot posts (Xiaohongshu, Zhihu, Reddit), Bilibili/YouTube summaries.\n> - **Productivity**: newsletter digests to DingTalk/Feishu/QQ, contacts from email/calendar.\n> - **Creative**: describe your goal, run overnight, get a draft next day.\n> - **Research**: track tech/AI news, personal knowledge base.\n> - **Desktop**: organize files, read/summarize docs, request files in chat.\n> - **Explore**: combine Skills and cron into your own agentic app.\n>\n>
\n\n---\n\n## News\n\n[2026-03-18] We released v0.1.0! See the [v0.1.0 Release Notes](https://agentscope-ai.github.io/CoPaw/release-notes) for the full changelog.\n\n- **[v0.1.0] Added:** Multi-workspace architecture with agent selector; skill security scanner and destructive shell command detection; optional web authentication; WeCom and XiaoYi channels; DingTalk AI Card replies; Gemini, DeepSeek, MiniMax, and Kimi providers; console dark mode and multimodal chat; SSE-based chat streaming with reconnect; voice message transcription via Whisper; `view_image` tool for multimodal conversations; LobeHub, ModelScope, and zip archive skill import; `glob_search` and `grep_search` built-in tools; timezone selector; `copaw update` CLI.\n- **[v0.1.0] Improved:** Graceful lifecycle management with zero-downtime agent reload; dynamic per-agent token counting; config loading protection; console internationalization with localized chat prompts; Windows desktop startup speed via bytecode pre-compilation; QQ channel reply logic with DM support.\n- **[v0.1.0] Fixed:** Telegram thread replies, media handling, and auto-reconnect; Discord cross-channel message merging and debounce generalization; Feishu channel reload; Ollama/LM Studio context length and error messages; cron jobs in correct workspace; Windows cross-disk moves, AutoRun stderr, and GBK encoding.\n- **[v0.1.0] Contributors:** Thanks to new contributors: [@dipeshbabu](https://github.com/dipeshbabu), [@sljeff](https://github.com/sljeff), [@octo-patch](https://github.com/octo-patch), [@Alexxigang](https://github.com/Alexxigang), [@howyoungchen](https://github.com/howyoungchen), [@nphenix](https://github.com/nphenix), [@skyfaker](https://github.com/skyfaker), [@hh0592821](https://github.com/hh0592821), [@futuremeng](https://github.com/futuremeng), [@toby1123yjh](https://github.com/toby1123yjh), [@hiyuchang](https://github.com/hiyuchang), [@hanson-hex](https://github.com/hanson-hex), [@JackyMao1999](https://github.com/JackyMao1999), [@mvanhorn](https://github.com/mvanhorn), [@yuanxs21](https://github.com/yuanxs21), [@aissac](https://github.com/aissac), [@lcq225](https://github.com/lcq225), [@Justin-lu](https://github.com/Justin-lu), [@rowanchen-com](https://github.com/rowanchen-com), [@pzlav](https://github.com/pzlav), [@mautops](https://github.com/mautops), [@hikariming](https://github.com/hikariming), [@Vanlee0129](https://github.com/Vanlee0129), [@JiwaniZakir](https://github.com/JiwaniZakir), [@EuanTop](https://github.com/EuanTop).\n\n[2026-03-12] We released v0.0.7! See the [v0.0.7 Release Notes](https://agentscope-ai.github.io/CoPaw/release-notes) for the full changelog.\n\n[2026-03-09] We released v0.0.6! See the [v0.0.6 Release Notes](https://agentscope-ai.github.io/CoPaw/release-notes) for the full changelog.\n\n[2026-03-06] We released v0.0.5! See the [v0.0.5 Release Notes](https://agentscope-ai.github.io/CoPaw/release-notes) for the full changelog.\n\n[2026-03-02] We released v0.0.4! See the [v0.0.4 Release Notes](https://agentscope-ai.github.io/CoPaw/release-notes) for the full changelog.\n\n---\n\n## Table of Contents\n\n> **Recommended reading:**\n>\n> - **I want to run CoPaw in 3 commands**: [Quick Start](#quick-start) → open Console in browser.\n> - **I want to chat in DingTalk / Feishu / QQ**: Configure [channels](https://copaw.agentscope.io/docs/channels) in the Console.\n> - **I don’t want to install Python**: [Script install](#script-install) handles Python automatically, or use [ModelScope one-click](https://modelscope.cn/studios/fork?target=AgentScope/CoPaw) for cloud deployment.\n\n- [News](#news)\n- [Quick Start](#quick-start)\n- [API Key](#api-key)\n- [Local Models](#local-models)\n- [Documentation](#documentation)\n- [FAQ](#faq)\n- [Roadmap](#roadmap)\n- [Contributing](#get-involved)\n- [Install from source](#install-from-source)\n- [Why CoPaw?](#why-copaw)\n- [Built by](#built-by)\n- [License](#license)\n\n---\n\n## Quick Start\n\n### pip install\n\nIf you prefer managing Python yourself:\n\n```bash\npip install copaw\ncopaw init --defaults\ncopaw app\n```\n\nThen open **http://127.0.0.1:8088/** in your browser for the Console (chat with CoPaw, configure the agent). To talk in DingTalk, Feishu, QQ, etc., add a channel in the [docs](https://copaw.agentscope.io/docs/channels).\n\n![Console](https://img.alicdn.com/imgextra/i3/O1CN01VYsFVo23aAvIM3GXB_!!6000000007271-2-tps-3328-1860.png)\n\n### Script install\n\nNo Python setup required, one command installs everything. The script will automatically download uv (Python package manager), create a virtual environment, and install CoPaw with all dependencies (including Node.js and frontend assets). Note: May not work in restricted network environments or corporate firewalls.\n\n**macOS / Linux:**\n\n```bash\ncurl -fsSL https://copaw.agentscope.io/install.sh | bash\n```\n\nTo install with Ollama support:\n\n```bash\ncurl -fsSL https://copaw.agentscope.io/install.sh | bash -s -- --extras ollama\n```\n\nTo install with multiple extras (e.g., Ollama + llama.cpp):\n\n```bash\ncurl -fsSL https://copaw.agentscope.io/install.sh | bash -s -- --extras ollama,llamacpp\n```\n\n**Windows (CMD):**\n\n```CMD\ncurl -fsSL https://copaw.agentscope.io/install.bat -o install.bat && install.bat\n```\n\n**Windows (PowerShell):**\n\n```powershell\nirm https://copaw.agentscope.io/install.ps1 | iex\n```\n\n> **Note**: The installer will automatically check the status of uv. If it is not installed, it will attempt to download and configure it automatically. If the automatic installation fails, please follow the on-screen prompts or execute `python -m pip install -U uv`, then rerun the installer.\n\n> **⚠️ Special Notice for Windows Enterprise LTSC Users**\n>\n> If you are using Windows LTSC or an enterprise environment governed by strict security policies, PowerShell may run in **Constrained Language Mode**, potentially causing the following issue:\n> 1. **If using CMD (.bat): Script executes successfully but fails to write to `Path`**\n>\n> The script completes file installation. Due to **Constrained Language Mode**, it cannot automatically update environment variables. Manually configure as follows:\n> - **Locate the installation directory**:\n> - Check if `uv` is available: Enter `uv --version` in CMD. If a version number appears, **only configure the CoPaw path**. If you receive the prompt `'uv' is not recognized as an internal or external command, operable program or batch file,` configure both paths.\n> - uv path (choose one based on installation location; use if `uv` fails): Typically `%USERPROFILE%\\.local\\bin`, `%USERPROFILE%\\AppData\\Local\\uv`, or the `Scripts` folder within your Python installation directory\n> - CoPaw path: Typically located at `%USERPROFILE%\\.copaw\\bin`.\n> - **Manually add to the system's Path environment variable**:\n> - Press `Win + R`, type `sysdm.cpl` and press Enter to open System Properties.\n> - Click “Advanced” -> “Environment Variables”.\n> - Under “System variables”, locate and select `Path`, then click “Edit”.\n> - Click “New”, enter both directory paths sequentially, then click OK to save.\n> 2. **If using PowerShell (.ps1): Script execution interrupted**\n>\n> Due to **Constrained Language Mode**, the script may fail to automatically download `uv`.\n> - **Manually install uv**: Refer to the [GitHub Release](https://github.com/astral-sh/uv/releases) to download `uv.exe` and place it in `%USERPROFILE%\\.local\\bin` or `%USERPROFILE%\\AppData\\Local\\uv`; or ensure Python is installed and run `python -m pip install -U uv`.\n> - **Configure `uv` environment variables**: Add the `uv` directory and `%USERPROFILE%\\.copaw\\bin` to your system's `Path` variable.\n> - **Re-run the installation**: Open a new terminal and execute the installation script again to complete the `CoPaw` installation.\n> - **Configure the `CoPaw` environment variable**: Add `%USERPROFILE%\\.copaw\\bin` to your system's `Path` variable.\n\nOnce installed, open a new terminal and run:\n\n```bash\ncopaw init --defaults # or: copaw init (interactive)\ncopaw app\n```\n\n
\nInstall options\n\n**macOS / Linux:**\n\n```bash\n# Install a specific version\ncurl -fsSL ... | bash -s -- --version 0.0.2\n\n# Install from source (dev/testing)\ncurl -fsSL ... | bash -s -- --from-source\n\n# With local model support\nbash install.sh --extras llamacpp # llama.cpp (cross-platform)\nbash install.sh --extras mlx # MLX (Apple Silicon)\nbash install.sh --extras llamacpp,mlx\n\n# Upgrade — just re-run the installer\ncurl -fsSL ... | bash\n\n# Uninstall\ncopaw uninstall # keeps config and data\ncopaw uninstall --purge # removes everything\n```\n\n**Windows (PowerShell):**\n\n```powershell\n# Install a specific version\nirm ... | iex; .\\install.ps1 -Version 0.0.2\n\n# Install from source (dev/testing)\n.\\install.ps1 -FromSource\n\n# With local model support\n.\\install.ps1 -Extras llamacpp # llama.cpp (cross-platform)\n.\\install.ps1 -Extras mlx # MLX\n.\\install.ps1 -Extras llamacpp,mlx\n\n# Upgrade — just re-run the installer\nirm ... | iex\n\n# Uninstall\ncopaw uninstall # keeps config and data\ncopaw uninstall --purge # removes everything\n```\n\n
\n\n### Desktop Application (Beta)\n\n> **Beta Notice**: The desktop application is currently in Beta testing phase with the following known limitations:\n> - **Incomplete compatibility testing**: Not fully tested across all system versions and hardware configurations\n> - **Potential performance issues**: Startup time, memory usage, and other performance aspects may need further optimization\n> - **Features under development**: Some features may be unstable or missing\n\nIf you're not comfortable with command-line tools, you can download and use CoPaw's desktop application without manually configuring Python environments or running commands.\n\n#### Download\n\nDownload the desktop app from [GitHub Releases](https://github.com/agentscope-ai/CoPaw/releases):\n- **Windows**: `CoPaw-Setup-.exe`\n- **macOS**: `CoPaw--macOS.zip` (Apple Silicon recommended)\n\n#### Features\n\n- ✅ **Zero configuration**: Download and double-click to run, no need to install Python or configure environment variables\n- ✅ **Cross-platform**: Supports Windows 10+ and macOS 14+\n- ✅ **Visual interface**: Automatically opens browser interface, no need to manually enter addresses\n- ⚠️ **Beta stage**: Features are continuously being improved, feedback welcome\n\n#### First Launch\n\n**Important**: The first launch may take 10-60 seconds (depending on your system configuration). The application needs to initialize the Python environment and load dependencies. Please wait patiently for the browser window to open automatically.\n\n#### macOS: Bypass System Security Restrictions\n\nWhen you download the CoPaw macOS app from Releases, macOS may show: *\"Apple cannot verify that 'CoPaw' contains no malicious software\"*. This happens because the app is not notarized. You can still open it as follows:\n\n- **Right-click to open (recommended)**\n Right-click (or Control+click) the CoPaw app → **Open** → in the dialog click **Open** again. This tells Gatekeeper you trust the app; after that you can double-click to launch as usual.\n\n- **Allow in System Settings**\n If it is still blocked, go to **System Settings → Privacy & Security**, scroll to the message like *\"CoPaw was blocked because it is from an unidentified developer\"*, and click **Open Anyway** or **Allow**.\n\n- **Remove quarantine attribute (not recommended for most users)**\n In Terminal run:\n `xattr -cr /Applications/CoPaw.app`\n (or use the path to the `.app` after unzipping). This clears the \"downloaded from the internet\" quarantine flag so the warning usually does not appear, but is less safe and controllable than using **Right-click → Open**.\n\nFor detailed usage instructions, troubleshooting, and common issues, see the [Desktop Application Guide](https://copaw.agentscope.io/docs/desktop).\n\n### Using Docker\n\nImages are on **Docker Hub** (`agentscope/copaw`). Image tags: `latest` (stable); `pre` (PyPI pre-release).\n\n```bash\ndocker pull agentscope/copaw:latest\ndocker run -p 127.0.0.1:8088:8088 \\\n -v copaw-data:/app/working \\\n -v copaw-secrets:/app/working.secret \\\n agentscope/copaw:latest\n```\n\nAlso available on Alibaba Cloud Container Registry (ACR) for users in China: `agentscope-registry.ap-southeast-1.cr.aliyuncs.com/agentscope/copaw` (same tags).\n\nThen open **http://127.0.0.1:8088/** for the Console. Config, memory, and skills are stored in the `copaw-data` volume; model provider settings and API keys are in the `copaw-secrets` volume. To pass API keys (e.g. `DASHSCOPE_API_KEY`), add `-e VAR=value` or `--env-file .env` to `docker run`.\n\n> **Connecting to Ollama or other services on the host machine**\n>\n> Inside a Docker container, `localhost` refers to the container itself, not your host machine. If you run Ollama (or other model services) on the host and want CoPaw in Docker to reach them, use one of these approaches:\n>\n> **Option A** — Explicit host binding (all platforms):\n> ```bash\n> docker run -p 127.0.0.1:8088:8088 \\\n> --add-host=host.docker.internal:host-gateway \\\n> -v copaw-data:/app/working \\\n> -v copaw-secrets:/app/working.secret \\\n> agentscope/copaw:latest\n> ```\n> Then in CoPaw **Settings → Models**, change the Base URL to `http://host.docker.internal:` — for example, `http://host.docker.internal:11434` for Ollama, or `http://host.docker.internal:1234/v1` for LM Studio.\n>\n> **Option B** — Host networking (Linux only):\n> ```bash\n> docker run --network=host \\\n> -v copaw-data:/app/working \\\n> -v copaw-secrets:/app/working.secret \\\n> agentscope/copaw:latest\n> ```\n> No port mapping (`-p`) is needed; the container shares the host network directly. Note that all container ports are exposed on the host, which may cause conflicts if the port is already in use.\n>\n> **Note:** If you only mount `/app/working` without a separate volume for `/app/working.secret`, the entrypoint will automatically redirect secrets into `/app/working/.secret` so they persist on the same volume.\n\nThe image is built from scratch. To build the image yourself, please refer to the [Build Docker image](scripts/README.md#build-docker-image) section in `scripts/README.md`, and then push to your registry.\n\n### Using ModelScope\n\n**No local install?** [ModelScope Studio](https://modelscope.cn/studios/fork?target=AgentScope/CoPaw) one-click cloud setup. Set your Studio to **non-public** so others cannot control your CoPaw.\n\n### Deploy on Alibaba Cloud ECS\n\nTo run CoPaw on Alibaba Cloud (ECS), use the one-click deployment: open the [CoPaw on Alibaba Cloud (ECS) deployment link](https://computenest.console.aliyun.com/service/instance/create/cn-hangzhou?type=user&ServiceId=service-1ed84201799f40879884) and follow the prompts. For step-by-step instructions, see [Alibaba Cloud Developer: Deploy your AI assistant in 3 minutes](https://developer.aliyun.com/article/1713682).\n\n---\n\n## API Key\n\nIf you use a **cloud LLM** (e.g. DashScope, ModelScope), you must configure an API key before chatting. CoPaw will not work until a valid key is set. See the [official docs](https://copaw.agentscope.io/docs/models#configure-cloud-providers) for details.\n\n**How to configure:**\n\n1. **Console (recommended)** — After running `copaw app`, open **http://127.0.0.1:8088/** → **Settings** → **Models**. Choose a provider, enter the **API Key**, and enable that provider and model.\n2. **`copaw init`** — When you run `copaw init`, it will guide you through configuring the LLM provider and API key. Follow the prompts to choose a provider and enter your key.\n3. **Environment variable** — For DashScope you can set `DASHSCOPE_API_KEY` in your shell or in a `.env` file in the working directory.\n\nTools that need extra keys (e.g. `TAVILY_API_KEY` for web search) can be set in Console **Settings → Environment variables**, or see [Config](https://copaw.agentscope.io/docs/config) for details.\n\n> **Using local models only?** If you use [Local Models](#local-models) (llama.cpp or MLX), you do **not** need any API key.\n\n## Local Models\n\nCoPaw can run LLMs entirely on your machine — no API keys or cloud services required. See the [official docs](https://copaw.agentscope.io/docs/models#local-providers-llamacpp--mlx) for details.\n\n| Backend | Best for | Install |\n| ------------- | ---------------------------------------- | -------------------------------------------------------------------- |\n| **llama.cpp** | Cross-platform (macOS / Linux / Windows) | `pip install 'copaw[llamacpp]'` or `bash install.sh --extras llamacpp` |\n| **MLX** | Apple Silicon Macs (M1/M2/M3/M4) | `pip install 'copaw[mlx]'` or `bash install.sh --extras mlx` |\n| **Ollama** | Cross-platform (requires Ollama service) | `pip install 'copaw[ollama]'` or `bash install.sh --extras ollama` |\n\nAfter installing, you can download and manage local models in the **Console** UI. You can also use the command line:\n\n```bash\ncopaw models download Qwen/Qwen3-4B-GGUF\ncopaw models # select the downloaded model\ncopaw app # start the server\n```\n\n---\n\n## Documentation\n\n| Topic | Description |\n| --------------------------------------------------------------------- | ------------------------------------------------ |\n| [Introduction](https://copaw.agentscope.io/docs/intro) | What CoPaw is and how to use it |\n| [Quick start](https://copaw.agentscope.io/docs/quickstart) | Install and run (local or ModelScope Studio) |\n| [Console](https://copaw.agentscope.io/docs/console) | Web UI: chat and agent configuration |\n| [Models](https://copaw.agentscope.io/docs/models) | Configure cloud, local, and custom providers |\n| [Channels](https://copaw.agentscope.io/docs/channels) | DingTalk, Feishu, QQ, Discord, iMessage, and more |\n| [Skills](https://copaw.agentscope.io/docs/skills) | Extend and customize capabilities |\n| [MCP](https://copaw.agentscope.io/docs/mcp) | Manage MCP clients |\n| [Memory](https://copaw.agentscope.io/docs/memory) | Long-term memory |\n| [Context](https://copaw.agentscope.io/docs/context) | Context management mechanism |\n| [Magic commands](https://copaw.agentscope.io/docs/commands) | Control conversation state without waiting for the AI |\n| [Heartbeat](https://copaw.agentscope.io/docs/heartbeat) | Scheduled check-in and digest |\n| [Config & working dir](https://copaw.agentscope.io/docs/config) | Working directory and config file |\n| [CLI](https://copaw.agentscope.io/docs/cli) | Init, cron jobs, skills, clean |\n| [FAQ](https://copaw.agentscope.io/docs/faq) | Common questions and troubleshooting |\n\nFull docs in this repo: [website/public/docs/](website/public/docs/).\n\n---\n\n## FAQ\n\nFor common questions, troubleshooting tips, and known issues, please visit the **[FAQ page](https://copaw.agentscope.io/docs/faq)**.\n\n---\n\n## Roadmap\n\n| Area | Item | Status |\n| ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------- |\n| **Horizontal Expansion** | More channels, models, skills, MCPs — **community contributions welcome** | Seeking Contributors |\n| **Existing Feature Extension** | Display optimization, download hints, Windows path compatibility, etc. — **community contributions welcome** | Seeking Contributors |\n| **Console Web UI** | Expose more info/config in the Console | In Progress |\n| **Self-healing** | Magic commands and daemon capabilities (CLI, status, restart, logs) | In Progress |\n| | DaemonAgent: autonomous diagnostics, self-healing, and recovery | Planned |\n| **Multi-agent** | Background task support | In Progress |\n| | Multi-agent isolation | Planned |\n| | Inter-agent contention resolution | Planned |\n| | Multi-agent communication | Planned |\n| **Multimodal** | Voice/video calls and real-time interaction | In Progress |\n| **Small + Large Model Collaboration** | Train/fine-tune local small LLMs for CoPaw workflows and sensitive-data use cases | In Progress |\n| | Multi-model routing. Local LLMs for sensitive data; cloud LLMs for planning and coding; balance of privacy, performance, and capability | Planned |\n| **Memory System** | Experience distillation & skill extraction | In Progress |\n| | Multimodal memory fusion | Planned |\n| | Context-aware proactive delivery | Planned |\n| **Security** | Shell execution confirmation | Planned |\n| | Tool/skills security | Planned |\n| | Configurable security levels (user-configurable) | Planned |\n| **Release & Contributing** | Contributing guidance for vibe coding agents | Planned |\n| **Sandbox** | Deeper integration with AgentScope Runtime sandboxes | Long-term Planned |\n| **Cloud-native** | Deeper integration with AgentScope Runtime; leverage cloud compute, storage, and tooling | Long-term Planned |\n| **Skills Hub** | Enrich the [AgentScope Skills](https://github.com/agentscope-ai/agentscope-skills) repository and improve discoverability of high-quality skills | Long-term Planned |\n\n\n*Status:* *In Progress* — actively being worked on; *Planned* — queued or under design, also **welcome contributions**; *Seeking Contributors* — we **strongly encourage community contributions**; *Long-term Planned* — longer-horizon roadmap.\n\n### Get involved\n\nWe are building CoPaw in the open and welcome contributions of all kinds! Check the [Roadmap](#roadmap) above (especially items marked **Seeking Contributors**) to find areas that interest you, and read [CONTRIBUTING](https://github.com/agentscope-ai/CoPaw/blob/main/CONTRIBUTING.md) to get started. We particularly welcome:\n\n- **Horizontal expansion** — new channels, model providers, skills, MCPs.\n- **Existing feature extension** — display and UX improvements, download hints, Windows path compatibility, and the like.\n\nJoin the conversation on [GitHub Discussions](https://github.com/agentscope-ai/CoPaw/discussions) to suggest or pick up work.\n\n---\n\n## Install from source\n\n```bash\ngit clone https://github.com/agentscope-ai/CoPaw.git\ncd CoPaw\n\n# Build console frontend first (required for web UI)\ncd console && npm ci && npm run build\ncd ..\n\n# Copy console build output to package directory\nmkdir -p src/copaw/console\ncp -R console/dist/. src/copaw/console/\n\n# Install Python package\npip install -e .\n```\n\n- **Dev** (tests, formatting): `pip install -e \".[dev,full]\"`\n- **Then**: Run `copaw init --defaults`, then `copaw app`.\n\n---\n\n## Why CoPaw?\n\nCoPaw represents both a **Co Personal Agent Workstation** and a \"co-paw\"—a partner always by your side. More than just a cold tool, CoPaw is a warm \"little paw\" always ready to lend a hand (or a paw!). It is the ultimate teammate for your digital life.\n\n---\n\n## Built by\n\n[AgentScope team](https://github.com/agentscope-ai) · [AgentScope](https://github.com/agentscope-ai/agentscope) · [AgentScope Runtime](https://github.com/agentscope-ai/agentscope-runtime) · [ReMe](https://github.com/agentscope-ai/ReMe)\n\n---\n\n## Contact us\n\n| [Discord](https://discord.gg/eYMpfnkG8h) | [X (Twitter)](https://x.com/agentscope_ai) | [DingTalk](https://qr.dingtalk.com/action/joingroup?code=v1,k1,OmDlBXpjW+I2vWjKDsjvI9dhcXjGZi3bQiojOq3dlDw=&_dt_no_comment=1&origin=11) |\n| ------------------------------------------------------------ | ------------------------------------------------------------ | ------------------------------------------------------------ |\n| [\"Discord\"](https://discord.gg/eYMpfnkG8h) | [\"X\"](https://x.com/agentscope_ai) | [\"DingTalk\"](https://qr.dingtalk.com/action/joingroup?code=v1,k1,OmDlBXpjW+I2vWjKDsjvI9dhcXjGZi3bQiojOq3dlDw=&_dt_no_comment=1&origin=11) |\n\n---\n\n## Telemetry\n\nCoPaw collects **anonymous** usage data during `copaw init` to help us understand our user base and prioritize improvements. Data is sent **once per version** — when you upgrade CoPaw, telemetry is re-collected so we can track version adoption.\n\n**What we collect:**\n\n- CoPaw version (e.g., 0.0.7)\n- Install method (pip, Docker, or desktop app)\n- OS and version (e.g., macOS 14.0, Ubuntu 22.04)\n- Python version (e.g., 3.13)\n- CPU architecture (e.g., x86_64, arm64)\n- GPU availability (yes/no)\n\n**What we do NOT collect:** No personal data, no files, no credentials, no IP addresses, no identifiable information.\n\nWhen running `copaw init` interactively, you will be asked whether to opt in. If you choose `--defaults`, telemetry is accepted automatically. The prompt appears once per version and never affects CoPaw's functionality.\n\n---\n\n## License\n\nCoPaw is released under the [Apache License 2.0](LICENSE).\n\n---\n\n## Contributors\n\nAll thanks to our contributors:\n\n\n \"Contributors\"\n\n" }, { "path": "README_ja.md", "content": "
\n\n# CoPaw\n\n[![GitHub Repo](https://img.shields.io/badge/GitHub-Repo-black.svg?logo=github)](https://github.com/agentscope-ai/CoPaw)\n[![PyPI](https://img.shields.io/pypi/v/copaw?color=3775A9&label=PyPI&logo=pypi)](https://pypi.org/project/copaw/)\n[![Documentation](https://img.shields.io/badge/Docs-Website-green.svg?logo=readthedocs&label=Docs)](https://copaw.agentscope.io/)\n[![Python Version](https://img.shields.io/badge/python-3.10%20~%20%3C3.14-blue.svg?logo=python&label=Python)](https://www.python.org/downloads/)\n[![Last Commit](https://img.shields.io/github/last-commit/agentscope-ai/CoPaw)](https://github.com/agentscope-ai/CoPaw)\n[![License](https://img.shields.io/badge/license-Apache%202.0-red.svg?logo=apache&label=License)](LICENSE)\n[![Code Style](https://img.shields.io/badge/code%20style-black-black.svg?logo=python&label=CodeStyle)](https://github.com/psf/black)\n[![GitHub Stars](https://img.shields.io/github/stars/agentscope-ai/CoPaw?style=flat&logo=github&color=yellow&label=Stars)](https://github.com/agentscope-ai/CoPaw/stargazers)\n[![GitHub Forks](https://img.shields.io/github/forks/agentscope-ai/CoPaw?style=flat&logo=github&color=purple&label=Forks)](https://github.com/agentscope-ai/CoPaw/network)\n[![DeepWiki](https://img.shields.io/badge/DeepWiki-Ask_Devin-navy.svg?logo=data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAACwAAAAyCAYAAAAnWDnqAAAAAXNSR0IArs4c6QAAA05JREFUaEPtmUtyEzEQhtWTQyQLHNak2AB7ZnyXZMEjXMGeK/AIi+QuHrMnbChYY7MIh8g01fJoopFb0uhhEqqcbWTp06/uv1saEDv4O3n3dV60RfP947Mm9/SQc0ICFQgzfc4CYZoTPAswgSJCCUJUnAAoRHOAUOcATwbmVLWdGoH//PB8mnKqScAhsD0kYP3j/Yt5LPQe2KvcXmGvRHcDnpxfL2zOYJ1mFwrryWTz0advv1Ut4CJgf5uhDuDj5eUcAUoahrdY/56ebRWeraTjMt/00Sh3UDtjgHtQNHwcRGOC98BJEAEymycmYcWwOprTgcB6VZ5JK5TAJ+fXGLBm3FDAmn6oPPjR4rKCAoJCal2eAiQp2x0vxTPB3ALO2CRkwmDy5WohzBDwSEFKRwPbknEggCPB/imwrycgxX2NzoMCHhPkDwqYMr9tRcP5qNrMZHkVnOjRMWwLCcr8ohBVb1OMjxLwGCvjTikrsBOiA6fNyCrm8V1rP93iVPpwaE+gO0SsWmPiXB+jikdf6SizrT5qKasx5j8ABbHpFTx+vFXp9EnYQmLx02h1QTTrl6eDqxLnGjporxl3NL3agEvXdT0WmEost648sQOYAeJS9Q7bfUVoMGnjo4AZdUMQku50McDcMWcBPvr0SzbTAFDfvJqwLzgxwATnCgnp4wDl6Aa+Ax283gghmj+vj7feE2KBBRMW3FzOpLOADl0Isb5587h/U4gGvkt5v60Z1VLG8BhYjbzRwyQZemwAd6cCR5/XFWLYZRIMpX39AR0tjaGGiGzLVyhse5C9RKC6ai42ppWPKiBagOvaYk8lO7DajerabOZP46Lby5wKjw1HCRx7p9sVMOWGzb/vA1hwiWc6jm3MvQDTogQkiqIhJV0nBQBTU+3okKCFDy9WwferkHjtxib7t3xIUQtHxnIwtx4mpg26/HfwVNVDb4oI9RHmx5WGelRVlrtiw43zboCLaxv46AZeB3IlTkwouebTr1y2NjSpHz68WNFjHvupy3q8TFn3Hos2IAk4Ju5dCo8B3wP7VPr/FGaKiG+T+v+TQqIrOqMTL1VdWV1DdmcbO8KXBz6esmYWYKPwDL5b5FA1a0hwapHiom0r/cKaoqr+27/XcrS5UwSMbQAAAABJRU5ErkJggg==)](https://deepwiki.com/agentscope-ai/CoPaw)\n[![Discord](https://img.shields.io/badge/Discord-Join_Us-blueviolet.svg?logo=discord)](https://discord.gg/eYMpfnkG8h)\n[![X](https://img.shields.io/badge/X-Follow_Us-black.svg?logo=x)](https://x.com/agentscope_ai)\n[![DingTalk](https://img.shields.io/badge/DingTalk-Join_Us-orange.svg)](https://qr.dingtalk.com/action/joingroup?code=v1,k1,OmDlBXpjW+I2vWjKDsjvI9dhcXjGZi3bQiojOq3dlDw=&_dt_no_comment=1&origin=11)\n\n[[ドキュメント](https://copaw.agentscope.io/)] [[English README](README.md)] [[中文 README](README_zh.md)]\n\n

\n \"CoPaw\n

\n\n

あなたのために働き、あなたとともに成長する。

\n\n
\n\nあなた専用のAIアシスタント。簡単にインストールでき、ローカルマシンやクラウドにデプロイ可能。複数のチャットアプリに対応し、機能を簡単に拡張できます。\n\n> **主な機能:**\n>\n> **あらゆるチャネル** — DingTalk、Feishu、QQ、Discord、iMessageなど。1つのアシスタントで、必要に応じて接続。\n>\n> **あなたの管理下** — メモリとパーソナライズはあなたの管理下に。ローカルまたはクラウドにデプロイ。任意のチャネルへのスケジュールリマインダー。\n>\n> **スキル** — 組み込みのcron機能。ワークスペース内のカスタムスキルを自動読み込み。ロックインなし。\n>\n>
\n> こんなことができます\n>\n>
\n>\n> - **ソーシャル**: 人気投稿のデイリーダイジェスト（小紅書、知乎、Reddit）、Bilibili/YouTubeの要約。\n> - **生産性**: ニュースレターのダイジェストをDingTalk/Feishu/QQに配信、メール/カレンダーからの連絡先管理。\n> - **クリエイティブ**: 目標を伝えて一晩実行、翌日にはドラフトが完成。\n> - **リサーチ**: テック/AIニュースの追跡、パーソナルナレッジベース。\n> - **デスクトップ**: ファイル整理、ドキュメントの読み取り/要約、チャットでファイルをリクエスト。\n> - **探索**: スキルとcronを組み合わせて、独自のエージェントアプリを構築。\n>\n>
\n\n---\n\n## ニュース\n\n[2026-03-12] v0.0.7をリリースしました！詳細は[v0.0.7リリースノート](https://agentscope-ai.github.io/CoPaw/release-notes)でご確認ください。\n\n- **[v0.0.7] 追加:** Tool Guardセキュリティレイヤー（危険なツール呼び出しをユーザー承認まで遮断）; MattermostとMatrixチャネル統合; Discord/DingTalk/Feishu/Telegramの@メンションフィルタリング; Telegram Markdownレンダリング; Feishu絵文字リアクションとリッチテキストメディア; QQ画像送信; LLM呼び出し自動リトライ; LM Studioプロバイダー; トークン使用量ダッシュボード; プロバイダー`generate_kwargs`エディタ; ワークスペースファイルのドラッグ＆ドロップ; チャット中のモデル切替; エージェント言語セレクター; コンテキスト管理UI; ページ遷移時のチャット状態保持; AIスキル最適化とストリーミング出力; スキルカード説明表示; 中国ユーザー向け自動PyPIミラー選択。\n- **[v0.0.7] 改善:** プロバイダー接続テストメッセージ; ワークスペースzip・セッション読取の非同期化; プロバイダーID競合の自動解決; モデル検出のオンデマンド化; トークン記録の集約; 組み込みスキルドキュメントとシェルPATH処理; Himalayaメールスキル; メモリドキュメント再構成; 設定・セキュリティページのリファクタリング。\n- **[v0.0.7] 修正:** DingTalk認証失敗時のクリーンアップ; Discord 2000文字超メッセージ分割; Matrix/Mattermost/MQTTチャネル設定の型整合; Windowsシェルエンコーディングとプロセスツリークリーンアップ; デスクトップSSL証明書・IME入力・外部URLナビゲーション; インストールスクリプトの関数定義順序修正; マジックコマンドセッション状態保護; Ollamaモーダル再レンダリング; `get_token_usage`データアクセス; チャットリクエストの重複排除。\n- **[v0.0.7] 貢献者:** 新規貢献者の皆さんに感謝します: [@2catycm](https://github.com/2catycm), [@2niuhe](https://github.com/2niuhe), [@yingdachen](https://github.com/yingdachen), [@Atletico1999](https://github.com/Atletico1999), [@buecker](https://github.com/buecker), [@Cirilla-zmh](https://github.com/Cirilla-zmh), [@gnipping](https://github.com/gnipping), [@Nufe-muzi](https://github.com/Nufe-muzi), [@FuKunZ](https://github.com/FuKunZ), [@JasonBuildAI](https://github.com/JasonBuildAI), [@StarMoonCity](https://github.com/StarMoonCity), [@walker83](https://github.com/walker83), [@lllcy](https://github.com/lllcy)。\n\n[2026-03-09] v0.0.6をリリースしました！詳細は[v0.0.6リリースノート](https://agentscope-ai.github.io/CoPaw/release-notes)でご確認ください。\n\n[2026-03-06] v0.0.5をリリースしました！詳細は[v0.0.5リリースノート](https://agentscope-ai.github.io/CoPaw/release-notes)でご確認ください。\n\n[2026-03-02] v0.0.4をリリースしました！詳細は[v0.0.4リリースノート](https://agentscope-ai.github.io/CoPaw/release-notes)でご確認ください。\n\n---\n\n## 目次\n\n> **おすすめの読み方:**\n>\n> - **3つのコマンドで実行したい**: [クイックスタート](#クイックスタート) → ブラウザでコンソールを開く。\n> - **DingTalk / Feishu / QQ でチャットしたい**: コンソールで[チャネル](https://copaw.agentscope.io/docs/channels)を設定。\n> - **Pythonをインストールしたくない**: [ワンラインインストール](#ワンラインインストールベータ版継続的に改善中)がPythonを自動処理。または[ModelScopeワンクリック](https://modelscope.cn/studios/fork?target=AgentScope/CoPaw)でクラウドデプロイ。\n\n- [ニュース](#ニュース)\n- [クイックスタート](#クイックスタート)\n- [APIキー](#apiキー)\n- [ローカルモデル](#ローカルモデル)\n- [ドキュメント](#ドキュメント)\n- [FAQ](#faq)\n- [ロードマップ](#ロードマップ)\n- [参加方法](#参加方法)\n- [ソースからインストール](#ソースからインストール)\n- [なぜCoPaw？](#なぜcopaw)\n- [開発チーム](#開発チーム)\n- [ライセンス](#ライセンス)\n\n---\n\n## クイックスタート\n\n### pip install（推奨）\n\nPythonを自分で管理する場合:\n\n```bash\npip install copaw\ncopaw init --defaults\ncopaw app\n```\n\nブラウザで **http://127.0.0.1:8088/** を開くとコンソール（CoPawとのチャット、エージェントの設定）が利用できます。DingTalk、Feishu、QQなどで会話するには、[チャネルドキュメント](https://copaw.agentscope.io/docs/channels)でチャネルを接続してください。\n\n![Console](https://img.alicdn.com/imgextra/i3/O1CN01VYsFVo23aAvIM3GXB_!!6000000007271-2-tps-3328-1860.png)\n\n### ワンラインインストール（ベータ版、継続的に改善中）\n\nPythonは不要です — インストーラーがすべて自動で処理します:\n\n**macOS / Linux:**\n\n```bash\ncurl -fsSL https://copaw.agentscope.io/install.sh | bash\n```\n\nOllamaサポート付きでインストールする場合:\n\n```bash\ncurl -fsSL https://copaw.agentscope.io/install.sh | bash -s -- --extras ollama\n```\n\n複数のエクストラ（例: Ollama + llama.cpp）付きでインストールする場合:\n\n```bash\ncurl -fsSL https://copaw.agentscope.io/install.sh | bash -s -- --extras ollama,llamacpp\n```\n\n**Windows (CMD):**\n\n```CMD\ncurl -fsSL https://copaw.agentscope.io/install.bat -o install.bat && install.bat\n```\n\n**Windows (PowerShell):**\n\n```powershell\nirm https://copaw.agentscope.io/install.ps1 | iex\n```\n\n> **注意**: インストーラーは uv の状態を自動的に確認します。未インストールの場合はダウンロードと設定を試みます。自動インストールに失敗した場合は、画面の指示に従うか、`python -m pip install -U uv` を実行してからインストーラーを再実行してください。\n\n> **⚠️ Windows Enterprise LTSC ユーザーへの重要なお知らせ**\n>\n> Windows LTSC または厳格なセキュリティポリシーが適用された企業環境をご利用の場合、PowerShell は **制限付き言語モード** で実行される可能性があり、以下の問題が発生する可能性があります：\n> 1. **CMD（.bat）使用時：スクリプトは正常に実行されるが`Path`への書き込みができない**\n>\n> スクリプトはファイルインストールを完了しましたが、**制限付き言語モード**のため環境変数への自動書き込みができません。この場合、手動で設定してください：\n> - **インストールディレクトリを確認**：\n> - `uv` の利用可否を確認：CMD で `uv --version` と入力し、バージョン番号が表示された場合は**CoPaw パスのみ設定**。`『uv』 は内部コマンドでも外部コマンドでもなく、実行可能プログラムまたはバッチファイルでもありません。` と表示された場合は両方を設定する必要があります。\n> - uvパス（いずれか一つ、インストール場所に応じて選択。`uv`が利用不可の場合に記入）：通常`%USERPROFILE%\\.local\\bin`、`%USERPROFILE%\\AppData\\Local\\uv`、またはPythonインストールディレクトリの`Scripts`フォルダ\n> - CoPawパス：通常 `%USERPROFILE%\\.copaw\\bin` にあります。\n> - **システム環境変数Pathへの手動追加**：\n> - `Win + R` を押し、`sysdm.cpl` と入力して Enter キーを押し、「システムのプロパティ」を開く。\n> - 「詳細設定」→「環境変数」をクリック。\n> - 「システム変数」で `Path` を探して選択し、「編集」をクリック。\n> - 「新規」をクリックし、上記の2つのディレクトリパスを順に入力して「OK」をクリックし保存します。\n> 2. **PowerShell（.ps1）を使用している場合：スクリプト実行が中断する**\n>\n> **制限付き言語モード** のため、スクリプトが自動的に`uv`をダウンロードできない可能性があります。\n> - **uvを手動でインストール**： [GitHub Release](https://github.com/astral-sh/uv/releases) を参照し、`uv.exe` を `%USERPROFILE%\\.local\\bin` または `%USERPROFILE%\\AppData\\Local\\uv` に配置。または Python がインストールされていることを確認し、`python -m pip install -U uv` を実行。\n> - **`uv`環境変数の設定**：`uv`の配置ディレクトリと `%USERPROFILE%\\.copaw\\bin` をシステムの `Path` 変数に追加してください。\n> - **再実行**：新しいターミナルを開き、インストールスクリプトを再度実行して `CoPaw` のインストールを完了させてください。\n> - **`CoPaw`環境変数の設定**：`%USERPROFILE%\\.copaw\\bin` をシステムの `Path` 変数に追加します。\n\nインストール完了後、新しいターミナルを開き、以下を実行してください：\n\n```bash\ncopaw init --defaults # または: copaw init（対話式）\ncopaw app\n```\n\n
\nインストールオプション\n\n**macOS / Linux:**\n\n```bash\n# 特定のバージョンをインストール\ncurl -fsSL ... | bash -s -- --version 0.0.2\n\n# ソースからインストール（開発/テスト用）\ncurl -fsSL ... | bash -s -- --from-source\n\n# ローカルモデルサポート付き\nbash install.sh --extras llamacpp # llama.cpp（クロスプラットフォーム）\nbash install.sh --extras mlx # MLX（Apple Silicon）\nbash install.sh --extras llamacpp,mlx\n\n# アップグレード — インストーラーを再実行するだけ\ncurl -fsSL ... | bash\n\n# アンインストール\ncopaw uninstall # 設定とデータを保持\ncopaw uninstall --purge # すべて削除\n```\n\n**Windows (PowerShell):**\n\n```powershell\n# 特定のバージョンをインストール\nirm ... | iex; .\\install.ps1 -Version 0.0.2\n\n# ソースからインストール（開発/テスト用）\n.\\install.ps1 -FromSource\n\n# ローカルモデルサポート付き\n.\\install.ps1 -Extras llamacpp # llama.cpp（クロスプラットフォーム）\n.\\install.ps1 -Extras mlx # MLX\n.\\install.ps1 -Extras llamacpp,mlx\n\n# アップグレード — インストーラーを再実行するだけ\nirm ... | iex\n\n# アンインストール\ncopaw uninstall # 設定とデータを保持\ncopaw uninstall --purge # すべて削除\n```\n\n
\n\n### デスクトップアプリケーション（Beta）\n\n> **Beta版の注意事項**: デスクトップアプリケーションは現在Beta版テスト段階にあり、以下の既知の制限があります：\n> - **互換性テストが不完全**: すべてのシステムバージョンとハードウェア構成で十分にテストされていません\n> - **パフォーマンスの問題の可能性**: 起動時間、メモリ使用量などのパフォーマンス面でさらなる最適化が必要な場合があります\n> - **開発中の機能**: 一部の機能が不安定または欠落している可能性があります\n\nコマンドラインツールに慣れていない場合、CoPawのデスクトップアプリケーションをダウンロードして使用できます。Python環境の手動設定やコマンドの実行は不要です。\n\n#### ダウンロード\n\n[GitHub Releases](https://github.com/agentscope-ai/CoPaw/releases)からデスクトップアプリをダウンロード:\n- **Windows**: `CoPaw-Setup-.exe`\n- **macOS**: `CoPaw--macOS.zip` (Apple Silicon推奨)\n\n#### 特徴\n\n- ✅ **ゼロ設定**: ダウンロードしてダブルクリックするだけで実行可能、Pythonのインストールや環境変数の設定は不要\n- ✅ **クロスプラットフォーム**: Windows 10+ と macOS 14+ に対応\n- ✅ **ビジュアルインターフェース**: ブラウザインターフェースが自動的に開き、手動でアドレスを入力する必要はありません\n- ⚠️ **Beta段階**: 機能は継続的に改善中、フィードバックを歓迎します\n\n#### 初回起動\n\n**重要**: 初回起動には10〜60秒かかる場合があります（システム構成によります）。アプリケーションはPython環境の初期化と依存関係の読み込みが必要です。ブラウザウィンドウが自動的に開くまでお待ちください。\n\n#### macOS: システムセキュリティ制限の回避\n\nReleasesからCoPaw macOSアプリをダウンロードすると、macOSは次のように表示する場合があります: *「Appleは'CoPaw'に悪意のあるソフトウェアが含まれていないことを確認できません」*。これはアプリが公証されていないためです。以下の方法で開くことができます:\n\n- **右クリックして開く（推奨）**\n CoPawアプリを右クリック（またはControl+クリック）→ **「開く」** → ダイアログで再度 **「開く」** をクリック。これによりGatekeeperにアプリを信頼していることを伝えます。その後は通常通りダブルクリックで起動できます。\n\n- **システム設定で許可**\n それでもブロックされる場合、**システム設定 → プライバシーとセキュリティ** に移動し、*「'CoPaw'は未確認の開発元からのものであるためブロックされました」* のようなメッセージまでスクロールし、**「このまま開く」** または **「許可」** をクリックします。\n\n- **検疫属性の削除（ほとんどのユーザーには非推奨）**\n ターミナルで実行:\n `xattr -cr /Applications/CoPaw.app`\n （または解凍後の `.app` へのパスを使用）。これにより「インターネットからダウンロードされた」検疫フラグがクリアされ、通常は警告が表示されなくなりますが、**右クリック → 開く** を使用するよりも安全性と制御性が低くなります。\n\n詳細な使用方法、トラブルシューティング、よくある問題については、[デスクトップアプリケーションガイド](https://copaw.agentscope.io/docs/desktop)を参照してください。\n\n### Dockerを使用\n\nイメージは **Docker Hub**（`agentscope/copaw`）で公開しています。タグ: `latest`（安定版）; `pre`（PyPIプレリリース版）。\n\n```bash\ndocker pull agentscope/copaw:latest\ndocker run -p 127.0.0.1:8088:8088 \\\n -v copaw-data:/app/working \\\n -v copaw-secrets:/app/working.secret \\\n agentscope/copaw:latest\n```\n\n中国のユーザーは阿里雲コンテナレジストリ（ACR）も利用できます: `agentscope-registry.ap-southeast-1.cr.aliyuncs.com/agentscope/copaw`（タグは同じ）。\n\nブラウザで **http://127.0.0.1:8088/** を開くとコンソールが利用できます。設定、メモリ、スキルは `copaw-data` ボリュームに保存されます。モデル設定とAPIキーは `copaw-secrets` ボリュームに保存されます。APIキー（例: `DASHSCOPE_API_KEY`）を渡すには、`docker run` に `-e VAR=value` または `--env-file .env` を追加してください。\n\n> **ホストマシン上のOllamaや他のモデルサービスに接続する**\n>\n> Dockerコンテナ内の `localhost` はコンテナ自身を指し、ホストマシンではありません。Ollama（または他のモデルサービス）がホスト上で動作している場合、以下のいずれかの方法でCoPawコンテナからアクセスできます：\n>\n> **方法A** — ホストアドレスの明示的バインディング（全プラットフォーム対応）：\n> ```bash\n> docker run -p 127.0.0.1:8088:8088 \\\n> --add-host=host.docker.internal:host-gateway \\\n> -v copaw-data:/app/working \\\n> -v copaw-secrets:/app/working.secret \\\n> agentscope/copaw:latest\n> ```\n> その後、CoPawの **Settings → Models → Ollama** で、Base URLを `http://host.docker.internal:11434` または対応するポートに変更してください。\n>\n> **方法B** — ホストネットワーク（Linuxのみ）：\n> ```bash\n> docker run --network=host \\\n> -v copaw-data:/app/working \\\n> -v copaw-secrets:/app/working.secret \\\n> agentscope/copaw:latest\n> ```\n> ポートマッピング（`-p`）は不要で、コンテナはホストネットワークを直接共有します。ただし、コンテナの全ポートがホスト上に公開されるため、使用中のポートと競合する可能性があります。\n>\n> **ヒント：** `/app/working` のみをマウントし `/app/working.secret` を別途マウントしない場合、エントリポイントスクリプトが自動的にsecretsを `/app/working/.secret` にリダイレクトし、同じボリュームに永続化します。\n\nイメージはゼロからビルドされています。自分でイメージをビルドする場合は、`scripts/README.md` の [Build Docker image](scripts/README.md#build-docker-image) セクションを参照し、レジストリにプッシュしてください。\n\n### ModelScopeを使用\n\n**ローカルインストール不要？** [ModelScope Studio](https://modelscope.cn/studios/fork?target=AgentScope/CoPaw) でワンクリッククラウドセットアップ。他の人があなたのCoPawを操作できないよう、Studioを**非公開**に設定してください。\n\n### Alibaba Cloud ECSへのデプロイ\n\nCoPawをAlibaba Cloud（ECS）で実行するには、ワンクリックデプロイを使用します: [CoPaw on Alibaba Cloud (ECS) デプロイリンク](https://computenest.console.aliyun.com/service/instance/create/cn-hangzhou?type=user&ServiceId=service-1ed84201799f40879884)を開き、プロンプトに従ってください。ステップバイステップの手順については、[Alibaba Cloud Developer: 3分でAIアシスタントをデプロイ](https://developer.aliyun.com/article/1713682)を参照してください。\n\n---\n\n## APIキー\n\n**クラウドLLM**（例: DashScope、ModelScope）を使用する場合、チャットの前にAPIキーを設定する必要があります。有効なキーが設定されるまでCoPawは動作しません。詳細は[公式ドキュメント](https://copaw.agentscope.io/docs/models#configure-cloud-providers)をご覧ください。\n\n**設定方法:**\n\n1. **コンソール（推奨）** — `copaw app` 実行後、**http://127.0.0.1:8088/** を開き → **設定** → **モデル**。プロバイダーを選択し、**APIキー**を入力して、そのプロバイダーとモデルを有効にしてください。\n2. **`copaw init`** — `copaw init` を実行すると、LLMプロバイダーとAPIキーの設定が案内されます。プロンプトに従ってプロバイダーを選択し、キーを入力してください。\n3. **環境変数** — DashScopeの場合、シェルまたはワーキングディレクトリの `.env` ファイルで `DASHSCOPE_API_KEY` を設定できます。\n\nその他のキー（例: Web検索用 `TAVILY_API_KEY`）は、コンソールの **設定 → 環境変数** で設定するか、[Config](https://copaw.agentscope.io/docs/config) で詳細を確認してください。\n\n> **ローカルモデルのみ使用する場合:** [ローカルモデル](#ローカルモデル)（llama.cppまたはMLX）を使用する場合、APIキーは**不要**です。\n\n## ローカルモデル\n\nCoPawはLLMを完全にローカルマシン上で実行できます — APIキーやクラウドサービスは不要です。詳細は[公式ドキュメント](https://copaw.agentscope.io/docs/models#local-providers-llamacpp--mlx)をご覧ください。\n\n| バックエンド | 最適な用途 | インストール |\n| ------------- | ---------------------------------------- | -------------------------------------------------------------------- |\n| **llama.cpp** | クロスプラットフォーム（macOS / Linux / Windows） | `pip install 'copaw[llamacpp]'` または `bash install.sh --extras llamacpp` |\n| **MLX** | Apple Silicon（M1/M2/M3/M4） | `pip install 'copaw[mlx]'` または `bash install.sh --extras mlx` |\n| **Ollama** | クロスプラットフォーム（Ollamaサービスが必要） | `pip install 'copaw[ollama]'` または `bash install.sh --extras ollama` |\n\nインストール後、**コンソール**UIでローカルモデルのダウンロードと管理ができます。コマンドラインでも利用できます:\n\n```bash\ncopaw models download Qwen/Qwen3-4B-GGUF\ncopaw models # ダウンロードしたモデルを選択\ncopaw app # サーバーを起動\n```\n\n---\n\n## ドキュメント\n\n| トピック | 説明 |\n| ------------------------------------------------------------------------- | --------------------------------------------------- |\n| [はじめに](https://copaw.agentscope.io/docs/intro) | CoPawとは何か、使い方 |\n| [クイックスタート](https://copaw.agentscope.io/docs/quickstart) | インストールと実行（ローカルまたはModelScope Studio） |\n| [コンソール](https://copaw.agentscope.io/docs/console) | Web UI: チャットとエージェント設定 |\n| [モデル](https://copaw.agentscope.io/docs/models) | クラウド・ローカル・カスタムプロバイダーの設定 |\n| [チャネル](https://copaw.agentscope.io/docs/channels) | DingTalk、Feishu、QQ、Discord、iMessageなど |\n| [スキル](https://copaw.agentscope.io/docs/skills) | 機能の拡張とカスタマイズ |\n| [MCP](https://copaw.agentscope.io/docs/mcp) | MCPクライアントの管理 |\n| [メモリ](https://copaw.agentscope.io/docs/memory) | 長期記憶 |\n| [コンテキスト](https://copaw.agentscope.io/docs/context) | コンテキスト管理メカニズム |\n| [魔法コマンド](https://copaw.agentscope.io/docs/commands) | AIの応答を待たずに会話状態を制御 |\n| [ハートビート](https://copaw.agentscope.io/docs/heartbeat) | スケジュールされたチェックインとダイジェスト |\n| [設定とワーキングディレクトリ](https://copaw.agentscope.io/docs/config) | ワーキングディレクトリと設定ファイル |\n| [CLI](https://copaw.agentscope.io/docs/cli) | Init、cronジョブ、スキル、クリーン |\n| [FAQ](https://copaw.agentscope.io/docs/faq) | よくある質問とトラブルシューティング |\n\nリポジトリ内の完全なドキュメント: [website/public/docs/](website/public/docs/)\n\n---\n\n## FAQ\n\nよくある質問、トラブルシューティングのヒント、既知の問題については、**[FAQページ](https://copaw.agentscope.io/docs/faq)** をご覧ください。\n\n---\n\n## ロードマップ\n\n| 方向 | 項目 | 状態 |\n| --- | --- | --- |\n| **横展開** | より多くのチャネル、モデル、スキル、MCP など — **コミュニティの貢献歓迎** | 貢献者募集中 |\n| **既存機能の拡張・改善** | 表示の最適化、ダウンロードヒント、Windowsパス互換など — **コミュニティの貢献歓迎** | 貢献者募集中 |\n| **コンソール Web UI** | コンソールでより多くの情報と設定を公開 | 進行中 |\n| **自己修復** | マジックコマンドとデーモン機能（CLI、status、restart、logs） | 進行中 |\n| | DaemonAgent: 自律診断、自己修復、復旧 | 計画中 |\n| **マルチエージェント** | バックグラウンドタスクサポート | 進行中 |\n| | マルチエージェントの分離 | 計画中 |\n| | エージェント間の競合・衝突の解決 | 計画中 |\n| | マルチエージェント通信 | 計画中 |\n| **マルチモーダル** | 音声/ビデオ通話とリアルタイム対話 | 進行中 |\n| **大小モデル協調** | CoPaw ワークフローと機密データ向けのローカル小モデル学習・ファインチューニング | 進行中 |\n| | マルチモデルルーティング。ローカルモデルで機密データ処理、クラウドモデルで計画・コーディング；プライバシー・性能・能力の両立 | 計画中 |\n| **メモリシステム** | 経験の蓄積とスキル抽出 | 進行中 |\n| | マルチモーダルメモリの融合強化 | 計画中 |\n| | シーン認識による能動的プッシュ | 計画中 |\n| **セキュリティ** | シェル実行の確認 | 計画中 |\n| | ツール/スキルのセキュリティ | 計画中 |\n| | 設定可能なセキュリティレベル | 計画中 |\n| **バージョンリリース・貢献規範** | Vibe Coding 等のエージェント向け貢献ガイダンス | 計画中 |\n| **サンドボックス** | AgentScope Runtime サンドボックスとの深い統合 | 長期計画 |\n| **クラウドネイティブ** | AgentScope Runtime との深い統合、クラウド算力・ストレージ・ツールエコシステムの活用 | 長期計画 |\n| **スキルエコシステム** | [AgentScope Skills](https://github.com/agentscope-ai/agentscope-skills) リポジトリの充実、高品質スキルの発見・利用向上 | 長期計画 |\n\n*状態説明：進行中 — 推進中；計画中 — 予定または設計中、**貢献も歓迎**；**貢献者募集中** — **コミュニティの参加を歓迎**；長期計画 — 中長期ロードマップ。*\n\n### 参加方法\n\nCoPawはオープンに開発しており、あらゆる形の貢献を歓迎しています！上記の[ロードマップ](#ロードマップ)（特に**貢献者募集中**の項目）から興味のある領域を選び、[CONTRIBUTING](https://github.com/agentscope-ai/CoPaw/blob/main/CONTRIBUTING.md)を読んで始めてください。特に歓迎するのは：\n\n- **横展開** — 新規チャネル、モデルプロバイダー、スキル、MCP。\n- **既存機能の拡張・改善** — 表示とインタラクションの最適化、ダウンロードヒント、Windowsパス互換など。\n\n[GitHub Discussions](https://github.com/agentscope-ai/CoPaw/discussions)で議論に参加し、アイデアを提案したりタスクを担当したりしてください。\n\n---\n\n## ソースからインストール\n\n```bash\ngit clone https://github.com/agentscope-ai/CoPaw.git\ncd CoPaw\n\n# まずコンソールフロントエンドをビルド（Web UIに必須）\ncd console && npm ci && npm run build\ncd ..\n\n# コンソールのビルド出力をパッケージディレクトリにコピー\nmkdir -p src/copaw/console\ncp -R console/dist/. src/copaw/console/\n\n# Pythonパッケージのインストール\npip install -e .\n```\n\n- **開発**（テスト、フォーマット）: `pip install -e \".[dev,full]\"`\n- **その後**: `copaw init --defaults` を実行し、次に `copaw app` を実行。\n\n---\n\n## なぜCoPaw？\n\nCoPawは **Co Personal Agent Workstation**（共同パーソナルエージェントワークステーション）であると同時に、「co-paw」— いつもあなたのそばにいるパートナーを表しています。単なる冷たいツールではなく、CoPawはいつでも手（または肉球！）を貸してくれる温かい「小さな肉球」です。デジタルライフにおける究極のチームメイトです。\n\n---\n\n## 開発チーム\n\n[AgentScope team](https://github.com/agentscope-ai) · [AgentScope](https://github.com/agentscope-ai/agentscope) · [AgentScope Runtime](https://github.com/agentscope-ai/agentscope-runtime) · [ReMe](https://github.com/agentscope-ai/ReMe)\n\n---\n\n## お問い合わせ\n\n| [Discord](https://discord.gg/eYMpfnkG8h) | [X (Twitter)](https://x.com/agentscope_ai) | [DingTalk](https://qr.dingtalk.com/action/joingroup?code=v1,k1,OmDlBXpjW+I2vWjKDsjvI9dhcXjGZi3bQiojOq3dlDw=&_dt_no_comment=1&origin=11) |\n| ------------------------------------------------------------ | ------------------------------------------------------------ | ------------------------------------------------------------ |\n| [\"Discord\"](https://discord.gg/eYMpfnkG8h) | [\"X\"](https://x.com/agentscope_ai) | [\"DingTalk\"](https://qr.dingtalk.com/action/joingroup?code=v1,k1,OmDlBXpjW+I2vWjKDsjvI9dhcXjGZi3bQiojOq3dlDw=&_dt_no_comment=1&origin=11) |\n\n---\n\n## テレメトリ\n\nCoPawは `copaw init` 実行時に**匿名**の利用データを収集し、ユーザー環境の把握と製品改善に役立てています。データは**バージョンごとに1回**送信されます — CoPawをアップグレードすると、バージョン分布を把握するために再収集されます。\n\n**収集する情報：**\n\n- CoPawバージョン（例: 0.0.7）\n- インストール方法（pip、Docker、またはデスクトップアプリ）\n- OSとバージョン（例: macOS 14.0、Ubuntu 22.04）\n- Pythonバージョン（例: 3.13）\n- CPUアーキテクチャ（例: x86_64、arm64）\n- GPUの利用可否（はい/いいえ）\n\n**収集しないもの：** 個人データ、ファイル、認証情報、IPアドレス、個人を特定できる情報は一切収集しません。\n\n`copaw init` を対話モードで実行すると、同意するかどうか尋ねられます。`--defaults` モードでは自動的に同意されます。プロンプトはバージョンごとに1回のみ表示され、CoPawの機能には影響しません。\n\n---\n\n## ライセンス\n\nCoPawは[Apache License 2.0](LICENSE)の下でリリースされています。\n\n---\n\n## コントリビューター\n\nCoPawをより良くするために貢献してくださったすべての方々に感謝します：\n\n\n \"コントリビューター\"\n\n" }, { "path": "README_zh.md", "content": "
\n\n# CoPaw\n\n[![GitHub 仓库](https://img.shields.io/badge/GitHub-仓库-black.svg?logo=github)](https://github.com/agentscope-ai/CoPaw)\n[![PyPI](https://img.shields.io/pypi/v/copaw?color=3775A9&label=PyPI&logo=pypi)](https://pypi.org/project/copaw/)\n[![文档](https://img.shields.io/badge/文档-在线-green.svg?logo=readthedocs&label=Docs)](https://copaw.agentscope.io/)\n[![Python 版本](https://img.shields.io/badge/python-3.10%20~%20%3C3.14-blue.svg?logo=python&label=Python)](https://www.python.org/downloads/)\n[![最后提交](https://img.shields.io/github/last-commit/agentscope-ai/CoPaw)](https://github.com/agentscope-ai/CoPaw)\n[![许可证](https://img.shields.io/badge/license-Apache%202.0-red.svg?logo=apache&label=%E8%AE%B8%E5%8F%AF%E8%AF%81)](LICENSE)\n[![代码风格](https://img.shields.io/badge/code%20style-black-black.svg?logo=python&label=%E4%BB%A3%E7%A0%81%E9%A3%8E%E6%A0%BC)](https://github.com/psf/black)\n[![GitHub Star](https://img.shields.io/github/stars/agentscope-ai/CoPaw?style=flat&logo=github&color=yellow&label=Star)](https://github.com/agentscope-ai/CoPaw/stargazers)\n[![GitHub Fork](https://img.shields.io/github/forks/agentscope-ai/CoPaw?style=flat&logo=github&color=purple&label=Fork)](https://github.com/agentscope-ai/CoPaw/network)\n[![DeepWiki](https://img.shields.io/badge/DeepWiki-Ask_Devin-navy.svg?logo=data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAACwAAAAyCAYAAAAnWDnqAAAAAXNSR0IArs4c6QAAA05JREFUaEPtmUtyEzEQhtWTQyQLHNak2AB7ZnyXZMEjXMGeK/AIi+QuHrMnbChYY7MIh8g01fJoopFb0uhhEqqcbWTp06/uv1saEDv4O3n3dV60RfP947Mm9/SQc0ICFQgzfc4CYZoTPAswgSJCCUJUnAAoRHOAUOcATwbmVLWdGoH//PB8mnKqScAhsD0kYP3j/Yt5LPQe2KvcXmGvRHcDnpxfL2zOYJ1mFwrryWTz0advv1Ut4CJgf5uhDuDj5eUcAUoahrdY/56ebRWeraTjMt/00Sh3UDtjgHtQNHwcRGOC98BJEAEymycmYcWwOprTgcB6VZ5JK5TAJ+fXGLBm3FDAmn6oPPjR4rKCAoJCal2eAiQp2x0vxTPB3ALO2CRkwmDy5WohzBDwSEFKRwPbknEggCPB/imwrycgxX2NzoMCHhPkDwqYMr9tRcP5qNrMZHkVnOjRMWwLCcr8ohBVb1OMjxLwGCvjTikrsBOiA6fNyCrm8V1rP93iVPpwaE+gO0SsWmPiXB+jikdf6SizrT5qKasx5j8ABbHpFTx+vFXp9EnYQmLx02h1QTTrl6eDqxLnGjporxl3NL3agEvXdT0WmEost648sQOYAeJS9Q7bfUVoMGnjo4AZdUMQku50McDcMWcBPvr0SzbTAFDfvJqwLzgxwATnCgnp4wDl6Aa+Ax283gghmj+vj7feE2KBBRMW3FzOpLOADl0Isb5587h/U4gGvkt5v60Z1VLG8BhYjbzRwyQZemwAd6cCR5/XFWLYZRIMpX39AR0tjaGGiGzLVyhse5C9RKC6ai42ppWPKiBagOvaYk8lO7DajerabOZP46Lby5wKjw1HCRx7p9sVMOWGzb/vA1hwiWc6jm3MvQDTogQkiqIhJV0nBQBTU+3okKCFDy9WwferkHjtxib7t3xIUQtHxnIwtx4mpg26/HfwVNVDb4oI9RHmx5WGelRVlrtiw43zboCLaxv46AZeB3IlTkwouebTr1y2NjSpHz68WNFjHvupy3q8TFn3Hos2IAk4Ju5dCo8B3wP7VPr/FGaKiG+T+v+TQqIrOqMTL1VdWV1DdmcbO8KXBz6esmYWYKPwDL5b5FA1a0hwapHiom0r/cKaoqr+27/XcrS5UwSMbQAAAABJRU5ErkJggg==)](https://deepwiki.com/agentscope-ai/CoPaw)\n[![Discord](https://img.shields.io/badge/Discord-Join_Us-blueviolet.svg?logo=discord)](https://discord.gg/eYMpfnkG8h)\n[![X](https://img.shields.io/badge/X-Follow_Us-black.svg?logo=x)](https://x.com/agentscope_ai)\n[![钉钉群](https://img.shields.io/badge/DingTalk-Join_Us-orange.svg)](https://qr.dingtalk.com/action/joingroup?code=v1,k1,OmDlBXpjW+I2vWjKDsjvI9dhcXjGZi3bQiojOq3dlDw=&_dt_no_comment=1&origin=11)\n\n[[文档](https://copaw.agentscope.io/)] [[English](README.md)] [[日本語](README_ja.md)]\n\n

\n \"CoPaw\n

\n\n

懂你所需，伴你左右。

\n\n
\n\n你的AI个人助理；安装极简、本地与云上均可部署；支持多端接入、能力轻松扩展。\n\n> **核心能力：**\n>\n> **全域触达** — 钉钉、飞书、QQ、Discord、iMessage 等频道，一个 CoPaw 按需连接。\n>\n> **由你掌控** — 记忆与个性化由你掌控，本地或云端均可；定时与协作发往指定频道。\n>\n> **Skills 扩展** — 内置定时任务，自定义技能目录，CoPaw 自动加载，无绑定。\n>\n>
\n> 你可以用 CoPaw 做什么\n>\n>
\n>\n> - **社交媒体**：每日热帖摘要（小红书、知乎、Reddit），B 站/YouTube 新视频摘要。\n> - **生产力**：邮件与 Newsletter 精华推送到钉钉/飞书/QQ，邮件与日历整理联系人。\n> - **创意与构建**：睡前说明目标、自动执行，次日获得雏形；从选题到成片全流程。\n> - **研究与学习**：追踪科技与 AI 资讯，个人知识库检索复用。\n> - **桌面与文件**：整理与搜索本地文件、阅读与摘要文档，在会话中索要文件。\n> - **探索更多**：用 Skills 与定时任务组合成你自己的 agentic app。\n>\n>
\n\n---\n\n## 新闻\n\n[2026-03-18] 我们发布了 v0.1.0！完整更新说明见 [v0.1.0 发布说明](https://agentscope-ai.github.io/CoPaw/release-notes)。\n\n- **[v0.1.0] 新增：** 多工作区架构，支持 Agent 切换器；技能安全扫描和危险 Shell 命令检测；可选 Web 认证；企业微信和小艺通道；钉钉 AI 卡片回复；Gemini、DeepSeek、MiniMax、Kimi 模型供应商；控制台暗色模式和多模态聊天；基于 SSE 的流式对话（支持重连）；Whisper 语音转文字；`view_image` 多模态对话工具；LobeHub、魔搭和 Zip 压缩包技能导入；`glob_search` 和 `grep_search` 内置搜索工具；时区选择器；`copaw update` 自升级命令。\n- **[v0.1.0] 优化：** 优雅的生命周期管理（Agent 零停机重载）；动态 Agent 级 Token 计数；配置加载保护；控制台多语言改进（含聊天提示词本地化）；Windows 桌面端字节码预编译加速启动；QQ 频道回复逻辑优化和私聊支持。\n- **[v0.1.0] 修复：** Telegram 消息线程、媒体处理和自动重连；Discord 跨频道消息合并和防抖泛化；飞书通道重载；Ollama/LM Studio 上下文长度和错误提示；定时任务工作区修复；聊天会话导航持久化；Windows 跨磁盘文件移动、AutoRun stderr 和 GBK 编码。\n- **[v0.1.0] 贡献者：** 感谢新贡献者：[@dipeshbabu](https://github.com/dipeshbabu)、[@sljeff](https://github.com/sljeff)、[@octo-patch](https://github.com/octo-patch)、[@Alexxigang](https://github.com/Alexxigang)、[@howyoungchen](https://github.com/howyoungchen)、[@nphenix](https://github.com/nphenix)、[@skyfaker](https://github.com/skyfaker)、[@hh0592821](https://github.com/hh0592821)、[@futuremeng](https://github.com/futuremeng)、[@toby1123yjh](https://github.com/toby1123yjh)、[@hiyuchang](https://github.com/hiyuchang)、[@hanson-hex](https://github.com/hanson-hex)、[@JackyMao1999](https://github.com/JackyMao1999)、[@mvanhorn](https://github.com/mvanhorn)、[@yuanxs21](https://github.com/yuanxs21)、[@aissac](https://github.com/aissac)、[@lcq225](https://github.com/lcq225)、[@Justin-lu](https://github.com/Justin-lu)、[@rowanchen-com](https://github.com/rowanchen-com)、[@pzlav](https://github.com/pzlav)、[@mautops](https://github.com/mautops)、[@hikariming](https://github.com/hikariming)、[@Vanlee0129](https://github.com/Vanlee0129)、[@JiwaniZakir](https://github.com/JiwaniZakir)、[@EuanTop](https://github.com/EuanTop)。\n\n[2026-03-12] 我们发布了 v0.0.7！完整更新说明见 [v0.0.7 发布说明](https://agentscope-ai.github.io/CoPaw/release-notes)。\n\n[2026-03-09] 我们发布了 v0.0.6！完整更新说明见 [v0.0.6 发布说明](https://agentscope-ai.github.io/CoPaw/release-notes)。\n\n[2026-03-06] 我们发布了 v0.0.5！完整更新说明见 [v0.0.5 发布说明](https://agentscope-ai.github.io/CoPaw/release-notes)。\n\n[2026-03-02] 我们发布了 v0.0.4！完整更新说明见 [v0.0.4 发布说明](https://agentscope-ai.github.io/CoPaw/release-notes)。\n\n---\n\n## 目录\n\n> **推荐阅读：**\n>\n> - **我想三条命令跑起来**： [快速开始](#快速开始) → 浏览器打开控制台。\n> - **我想在钉钉 / 飞书 / QQ 里聊**：在控制台中进行 [频道配置](https://copaw.agentscope.io/docs/channels)。\n> - **我不想装 Python**：[脚本安装](#脚本安装) 自动管理 Python，或使用 [魔搭一键配置](https://modelscope.cn/studios/fork?target=AgentScope/CoPaw) 云端部署。\n\n- [新闻](#新闻)\n- [快速开始](#快速开始)\n- [API Key](#api-key)\n- [本地模型](#本地模型)\n- [文档](#文档)\n- [常见问题](#常见问题)\n- [路线图](#路线图)\n- [参与贡献](#参与贡献)\n- [从源码安装](#从源码安装)\n- [为什么叫 CoPaw？](#为什么叫-copaw)\n- [由谁构建](#由谁构建)\n- [许可证](#许可证)\n\n---\n\n## 快速开始\n\n### pip 安装\n\n如果你习惯自行管理 Python 环境：\n\n```bash\npip install copaw\ncopaw init --defaults\ncopaw app\n```\n\n在浏览器打开 **http://127.0.0.1:8088/** 即可使用控制台（与 CoPaw 对话、配置 Agent）。若要在钉钉、飞书、QQ 等 app 内对话，请参考 [文档](https://copaw.agentscope.io/docs/channels) 接入频道。\n\n![Console](https://img.alicdn.com/imgextra/i3/O1CN01N6TeJ41Y2y7O4gppz_!!6000000003002-2-tps-3328-1860.png)\n\n### 脚本安装\n\n无需手动配置 Python，一行命令自动完成安装。脚本会自动下载 uv（Python 包管理器）、创建虚拟环境、安装 CoPaw 及其依赖（含 Node.js 和前端资源）。注意：部分网络环境或企业权限管控下可能无法使用。\n\n**macOS / Linux：**\n\n```bash\ncurl -fsSL https://copaw.agentscope.io/install.sh | bash\n```\n\n如需安装 Ollama 支持：\n\n```bash\ncurl -fsSL https://copaw.agentscope.io/install.sh | bash -s -- --extras ollama\n```\n\n如需安装多个扩展（例如 Ollama + llama.cpp）：\n\n```bash\ncurl -fsSL https://copaw.agentscope.io/install.sh | bash -s -- --extras ollama,llamacpp\n```\n\n**Windows (CMD):**\n\n```CMD\ncurl -fsSL https://copaw.agentscope.io/install.bat -o install.bat && install.bat\n```\n\n**Windows（PowerShell）：**\n\n```powershell\nirm https://copaw.agentscope.io/install.ps1 | iex\n```\n\n> **注意**：安装程序将自动检查 uv 状态，若未安装则尝试自动下载配置。如遇自动安装失败，请遵循屏幕提示操作，或执行 `python -m pip install -U uv`，然后重新运行安装程序。\n\n> **⚠️ Windows 企业版 LTSC 用户特别提示**\n>\n> 如果您使用的是 Windows LTSC 或受严格安全策略管控的企业环境，PowerShell 可能运行在 **受限语言模式** 下，可能会遇到以下问题：\n> 1. **如果你使用的是 CMD（.bat）：脚本执行成功但无法写入`Path`**\n>\n> 脚本已完成文件安装，由于 **受限语言模式** ，脚本无法自动写入环境变量，此时只需手动配置：\n> - **找到安装目录**：\n> - 检查 `uv` 是否可用：在 CMD 中输入 `uv --version` ，如果显示版本号，则**只需配置 CoPaw 路径**；如果提示 `'uv' 不是内部或外部命令，也不是可运行的程序或批处理文件。`，则需同时配置两者。\n> - uv路径（任选其一，取决于安装位置，若`uv`不可用则填）：通常在`%USERPROFILE%\\.local\\bin`、`%USERPROFILE%\\AppData\\Local\\uv`或 Python 安装目录下的 `Scripts` 文件夹\n> - CoPaw路径：通常在 `%USERPROFILE%\\.copaw\\bin` 。\n> - **手动添加到系统的 Path 环境变量**：\n> - 按 `Win + R`，输入 `sysdm.cpl` 并回车，打开“系统属性”。\n> - 点击 “高级” -> “环境变量”。\n> - 在 “系统变量” 中找到并选中 `Path`，点击 “编辑”。\n> - 点击 “新建”，依次填入上述两个目录路径，点击确定保存。\n> 2. **如果你使用的是 PowerShell（.ps1）：脚本运行中断**\n>\n> 由于 **受限语言模式** ，脚本可能无法自动下载`uv`。\n> - **手动安装uv**：参考 [GitHub Release](https://github.com/astral-sh/uv/releases)下载并将`uv.exe`放至`%USERPROFILE%\\.local\\bin`或`%USERPROFILE%\\AppData\\Local\\uv`；或者确保已安装 Python ，然后运行`python -m pip install -U uv`\n> - **配置`uv`环境变量**：将`uv`所在目录和 `%USERPROFILE%\\.copaw\\bin` 添加到系统的 `Path` 变量中。\n> - **重新运行**：打开新终端，再次执行安装脚本以完成 `CoPaw` 安装。\n> - **配置`CoPaw`环境变量**：将 `%USERPROFILE%\\.copaw\\bin` 添加到系统的 `Path` 变量中。\n\n安装完成后，请打开新终端并运行：\n\n```bash\ncopaw init --defaults # 或：copaw init（交互式）\ncopaw app\n```\n\n
\n安装选项\n\n**macOS / Linux：**\n\n```bash\n# 安装指定版本\ncurl -fsSL ... | bash -s -- --version 0.0.2\n\n# 从源码安装（开发/测试用）\ncurl -fsSL ... | bash -s -- --from-source\n\n# 安装本地模型支持\nbash install.sh --extras llamacpp # llama.cpp（跨平台）\nbash install.sh --extras mlx # MLX（Apple Silicon）\nbash install.sh --extras llamacpp,mlx\n\n# 升级 — 重新运行安装命令即可\ncurl -fsSL ... | bash\n\n# 卸载\ncopaw uninstall # 保留配置和数据\ncopaw uninstall --purge # 删除所有内容\n```\n\n**Windows（PowerShell）：**\n\n```powershell\n# 安装指定版本\nirm ... | iex; .\\install.ps1 -Version 0.0.2\n\n# 从源码安装（开发/测试用）\n.\\install.ps1 -FromSource\n\n# 安装本地模型支持\n.\\install.ps1 -Extras llamacpp # llama.cpp（跨平台）\n.\\install.ps1 -Extras mlx # MLX\n.\\install.ps1 -Extras llamacpp,mlx\n\n# 升级 — 重新运行安装命令即可\nirm ... | iex\n\n# 卸载\ncopaw uninstall # 保留配置和数据\ncopaw uninstall --purge # 删除所有内容\n```\n\n
\n\n### 桌面应用（Beta）\n\n> **Beta 版本说明**：桌面应用目前处于 Beta 测试阶段，存在以下已知限制：\n> - **兼容性测试不完整**：未在所有系统版本和硬件配置上进行充分测试\n> - **性能可能存在缺陷**：启动速度、内存占用等方面可能需要进一步优化\n> - **功能持续完善中**：部分功能可能不稳定或缺失\n\n如果你不习惯使用命令行，可以下载并使用 CoPaw 的桌面应用版本，无需手动配置 Python 环境或执行命令。\n\n#### 下载\n\n从 [GitHub Releases](https://github.com/agentscope-ai/CoPaw/releases) 下载桌面应用：\n- **Windows**: `CoPaw-Setup-.exe`\n- **macOS**: `CoPaw--macOS.zip` (推荐 Apple Silicon)\n\n#### 特点\n\n- ✅ **零配置**：下载后双击即可运行，无需安装 Python 或配置环境变量\n- ✅ **跨平台**：支持 Windows 10+ 和 macOS 14+\n- ✅ **可视化**：自动打开浏览器界面，无需手动输入地址\n- ⚠️ **Beta 阶段**：功能持续完善中，欢迎反馈问题\n\n#### 首次启动\n\n**重要提示**：首次启动可能需要 10-60 秒（取决于您的系统配置）。应用需要初始化 Python 环境和加载依赖，请耐心等待浏览器窗口自动打开。\n\n#### macOS：绕过系统安全限制\n\n当你从 Releases 下载 CoPaw macOS 应用时，macOS 可能显示：*\"Apple 无法验证 'CoPaw' 不包含恶意软件\"*。这是因为应用未经过公证。你仍然可以通过以下方式打开：\n\n- **右键打开（推荐）**\n 右键点击（或 Control + 点击）CoPaw 应用 → **\"打开\"** → 在对话框中再次点击 **\"打开\"**。这会告诉 Gatekeeper 你信任该应用；之后可以像往常一样双击启动。\n\n- **在系统设置中允许**\n 如果仍被阻止，进入 **系统设置 → 隐私与安全性**，向下滚动找到类似 *\"已阻止 'CoPaw'，因为无法验证开发者\"* 的提示，点击 **\"仍要打开\"** 或 **\"允许\"**。\n\n- **移除隔离属性（不推荐大多数用户）**\n 在终端运行：\n `xattr -cr /Applications/CoPaw.app`\n （或使用解压后的 `.app` 路径）。这会清除\"从互联网下载\"的隔离标志，使警告通常不会出现，但不如使用 **右键 → 打开** 安全和可控。\n\n详细使用说明、故障排除和常见问题，请参见 [桌面应用指南](https://copaw.agentscope.io/docs/desktop)。\n\n---\n\n### 使用 Docker\n\n镜像在 **Docker Hub**（`agentscope/copaw`）。镜像 tag：`latest`（稳定版）；`pre`（PyPI 预发布版）。\n\n```bash\ndocker pull agentscope/copaw:latest\ndocker run -p 127.0.0.1:8088:8088 \\\n -v copaw-data:/app/working \\\n -v copaw-secrets:/app/working.secret \\\n agentscope/copaw:latest\n```\n\n国内用户也可选用阿里云容器镜像服务 (ACR)：`agentscope-registry.ap-southeast-1.cr.aliyuncs.com/agentscope/copaw`（tag 相同）。\n\n然后在浏览器打开 **http://127.0.0.1:8088/** 进入控制台。配置、记忆与 Skills 保存在 `copaw-data` 卷中；模型配置与 API Key 保存在 `copaw-secrets` 卷中。如需传入 API Key（如 `DASHSCOPE_API_KEY`），在 `docker run` 时添加 `-e VAR=value` 或 `--env-file .env`。\n\n> **从容器内连接宿主机上的 Ollama 或其他模型服务**\n>\n> Docker 容器内的 `localhost` 指向容器自身，而非宿主机。如果 Ollama（或其他模型服务）运行在宿主机上，可通过以下方式让容器内的 CoPaw 访问：\n>\n> **方式 A** — 显式绑定宿主机地址（全平台通用）：\n> ```bash\n> docker run -p 127.0.0.1:8088:8088 \\\n> --add-host=host.docker.internal:host-gateway \\\n> -v copaw-data:/app/working \\\n> -v copaw-secrets:/app/working.secret \\\n> agentscope/copaw:latest\n> ```\n> 然后在 CoPaw **设置 → 模型** 中，将 Base URL 改为 `http://host.docker.internal:<端口>` — 例如 Ollama 填 `http://host.docker.internal:11434`，LM Studio 填 `http://host.docker.internal:1234/v1`。\n>\n> **方式 B** — 使用宿主机网络（仅限 Linux）：\n> ```bash\n> docker run --network=host \\\n> -v copaw-data:/app/working \\\n> -v copaw-secrets:/app/working.secret \\\n> agentscope/copaw:latest\n> ```\n> 无需端口映射（`-p`），容器直接共享宿主机网络。注意这会将容器的所有端口暴露在宿主机上，可能与已占用的端口产生冲突。\n>\n> **提示：** 如果你只挂载了 `/app/working` 而没有单独挂载 `/app/working.secret`，入口脚本会自动将 secrets 重定向到 `/app/working/.secret`，使其也保存在同一个 volume 中。\n\n镜像从零构建。若需自行构建镜像，请参阅 [scripts/README.md](scripts/README.md#build-docker-image) 中的「Build Docker image」小节，构建后推送到你的镜像仓库。\n\n### 使用魔搭创空间\n\n**不想本地安装？** 使用 [魔搭创空间](https://modelscope.cn/studios/fork?target=AgentScope/CoPaw) 一键云端配置。请将创空间设为 **非公开**，否则他人可能操纵你的 CoPaw。\n\n### 部署到阿里云 ECS\n\n若希望将 CoPaw 部署在阿里云上，可使用阿里云 ECS 一键部署：打开 [CoPaw 阿里云 ECS 部署链接](https://computenest.console.aliyun.com/service/instance/create/cn-hangzhou?type=user&ServiceId=service-1ed84201799f40879884) 按页面提示操作即可。详细步骤见 [阿里云开发者社区：CoPaw 3 分钟部署你的 AI 助理](https://developer.aliyun.com/article/1713682)。\n\n---\n\n## API Key\n\n若使用**云端大模型**（如 DashScope、ModelScope），在开始对话前必须配置 API Key。未配置有效 Key 前，CoPaw 无法正常工作。详情请参考[官方文档](https://copaw.agentscope.io/docs/models#%E9%85%8D%E7%BD%AE%E4%BA%91%E6%8F%90%E4%BE%9B%E5%95%86)。\n\n**配置方式：**\n\n1. **控制台（推荐）** — 运行 `copaw app` 后，打开 **http://127.0.0.1:8088/** → **设置** → **模型**。选择提供商、填写 **API Key**，并启用该提供商与模型。\n2. **`copaw init`** — 运行 `copaw init` 时，会引导你配置 LLM 提供商与 API Key。按提示选择提供商并填写 Key 即可。\n3. **环境变量** — 使用 DashScope 时，可在终端或工作目录下的 `.env` 文件中设置 `DASHSCOPE_API_KEY`。\n\n其他工具所需密钥（如网页搜索的 `TAVILY_API_KEY`）可在控制台 **设置 → 环境变量** 中配置，详见 [配置](https://copaw.agentscope.io/docs/config)。\n\n> **仅用本地模型？** 若使用 [本地模型](#本地模型)（llama.cpp 或 MLX），则**无需**任何 API Key。\n\n---\n\n## 本地模型\n\nCoPaw 可在本机完全本地运行大模型，无需 API Key 或云端服务。详情请见[官方文档](https://copaw.agentscope.io/docs/models#%E6%9C%AC%E5%9C%B0%E6%8F%90%E4%BE%9B%E5%95%86llamacpp--MLX)\n\n| 后端 | 适用场景 | 安装 |\n| ------------- | --------------------------------- | -------------------------------------------------------------------- |\n| **llama.cpp** | 跨平台（macOS / Linux / Windows） | `pip install 'copaw[llamacpp]'` 或 `bash install.sh --extras llamacpp` |\n| **MLX** | Apple Silicon（M1/M2/M3/M4） | `pip install 'copaw[mlx]'` 或 `bash install.sh --extras mlx` |\n| **Ollama** | 跨平台（需要 Ollama 服务运行） | `pip install 'copaw[ollama]'` 或 `bash install.sh --extras ollama` |\n\n安装后可以在 **控制台** 界面中下载与管理本地模型。\n\n也可以用命令行管理模型：\n\n```bash\ncopaw models download Qwen/Qwen3-4B-GGUF\ncopaw models # 选择已下载的模型\ncopaw app # 启动服务\n```\n\n---\n\n## 文档\n\n| 主题 | 说明 |\n| --------------------------------------------------------- | ------------------------------------ |\n| [项目介绍](https://copaw.agentscope.io/docs/intro) | CoPaw 是什么、怎么用 |\n| [快速开始](https://copaw.agentscope.io/docs/quickstart) | 安装与运行（本地或魔搭创空间） |\n| [控制台](https://copaw.agentscope.io/docs/console) | Web 界面：对话与 Agent 配置 |\n| [模型](https://copaw.agentscope.io/docs/models) | 配置云/本地/自定义提供商 |\n| [频道配置](https://copaw.agentscope.io/docs/channels) | 钉钉、飞书、QQ、Discord、iMessage 等 |\n| [Skills](https://copaw.agentscope.io/docs/skills) | 扩展与自定义能力 |\n| [MCP](https://copaw.agentscope.io/docs/mcp) | 管理 MCP 客户端 |\n| [记忆](https://copaw.agentscope.io/docs/memory) | 长期记忆 |\n| [上下文](https://copaw.agentscope.io/docs/context) | 上下文管理机制 |\n| [魔法命令](https://copaw.agentscope.io/docs/commands) | 控制对话状态，无需等待AI理解 |\n| [心跳](https://copaw.agentscope.io/docs/heartbeat) | 定时自检与摘要 |\n| [配置与工作目录](https://copaw.agentscope.io/docs/config) | 工作目录与配置文件 |\n| [CLI](https://copaw.agentscope.io/docs/cli) | 初始化、定时任务、Skills、清理 |\n| [FAQ 常见问题](https://copaw.agentscope.io/docs/faq) | 常见问题与报错排查 |\n\n完整文档见本仓库 [website/public/docs/](website/public/docs/)。\n\n---\n\n## 常见问题\n\n常见问题、排错指南与已知问题，请访问 **[FAQ 页面](https://copaw.agentscope.io/docs/faq)**。\n\n---\n\n## 路线图\n\n| 方向 | 事项 | 状态 |\n| ---------------------- | ----------------------------------------------------------------------------------------------------------- | -------- |\n| **横向拓展** | 更多频道、模型、技能、MCP 等 — **欢迎社区贡献** | 征集中 |\n| **已有功能扩展与完善** | 展示优化、下载提示、Windows 路径兼容等 — **欢迎社区贡献** | 征集中 |\n| **控制台 Web UI** | 在控制台中透出更多信息与配置 | 进行中 |\n| **自愈** | 魔法命令与 Daemon 能力（CLI、status、restart、logs） | 进行中 |\n| | DaemonAgent：自诊断、自愈与恢复 | 计划中 |\n| **多智能体** | 后台任务支持 | 进行中 |\n| | 多智能体隔离 | 计划中 |\n| | 智能体间竞争与冲突的解决 | 计划中 |\n| | 多智能体通信 | 计划中 |\n| **多模态** | 语音/视频通话与实时交互 | 进行中 |\n| **大小模型协同** | 针对 CoPaw 工作流与敏感数据场景的本地小模型训练与微调 | 进行中 |\n| | 多模型路由。本地模型处理敏感数据，云端模型负责规划与编码；兼顾隐私、性能与能力 | 计划中 |\n| **记忆系统** | 经验沉淀技能提炼 | 进行中 |\n| | 多模态记忆融合增强 | 计划中 |\n| | 场景感知主动推送 | 计划中 |\n| **安全** | Shell 执行确认 | 计划中 |\n| | 工具/技能安全性 | 计划中 |\n| | 可配置安全等级 | 计划中 |\n| **版本发布与贡献规范** | Vibe Coding 等 Agent 的贡献引导 | 计划中 |\n| **沙箱** | 与 AgentScope Runtime 沙箱深度集成 | 长期规划 |\n| **云原生** | 与 AgentScope Runtime 深度集成，充分利用云端算力、存储与工具生态 | 长期规划 |\n| **技能生态** | 丰富 [AgentScope Skills](https://github.com/agentscope-ai/agentscope-skills) 仓库，提升优质技能的发现与使用 | 长期规划 |\n\n*状态说明：进行中 — 正在推进；计划中 — 已排期或设计中，也**欢迎贡献**；**征集中** — 我们**非常欢迎**社区参与；长期规划 — 中长期路线。*\n\n### 参与贡献\n\nCoPaw 在开放协作中持续演进，欢迎各种形式的参与！请参考上方 [路线图](#路线图)（尤其是标记为 **征集中** 的项）选择你感兴趣的方向，并阅读 [CONTRIBUTING](https://github.com/agentscope-ai/CoPaw/blob/main/CONTRIBUTING_zh.md) 了解如何开始。我们特别欢迎：\n\n- **横向拓展** — 新频道、模型提供商、Skills、MCP。\n- **已有功能扩展与完善** — 展示与交互优化、下载提示、Windows 路径兼容等。\n\n欢迎在 [GitHub Discussions](https://github.com/agentscope-ai/CoPaw/discussions) 参与讨论、提出想法或认领任务。\n\n---\n\n## 从源码安装\n\n```bash\ngit clone https://github.com/agentscope-ai/CoPaw.git\ncd CoPaw\n\n# 先构建前端控制台（Web 界面必需）\ncd console && npm ci && npm run build\ncd ..\n\n# 将控制台构建产物复制到包目录\nmkdir -p src/copaw/console\ncp -R console/dist/. src/copaw/console/\n\n# 安装 Python 包\npip install -e .\n```\n\n- **开发**（测试、格式化）：`pip install -e \".[dev,full]\"`\n- **然后**：运行 `copaw init --defaults`，再运行 `copaw app`。\n\n---\n\n## 为什么叫 CoPaw？\n\nCoPaw 既是「你的搭档小爪子」（co-paw），也寓意 **Co Personal Agent Workstation**（协同个人智能体工作台）。我们希望它不是冰冷的工具，而是一只随时准备帮忙的温暖「小爪子」，是你数字生活中最默契的伙伴。\n\n---\n\n## 由谁构建\n\n[AgentScope 团队](https://github.com/agentscope-ai) · [AgentScope](https://github.com/agentscope-ai/agentscope) · [AgentScope Runtime](https://github.com/agentscope-ai/agentscope-runtime) · [ReMe](https://github.com/agentscope-ai/ReMe)\n\n---\n\n## 联系我们\n\n| [Discord](https://discord.gg/eYMpfnkG8h) | [X (Twitter)](https://x.com/agentscope_ai) | [钉钉](https://qr.dingtalk.com/action/joingroup?code=v1,k1,OmDlBXpjW+I2vWjKDsjvI9dhcXjGZi3bQiojOq3dlDw=&_dt_no_comment=1&origin=11) |\n| ------------------------------------------------------------ | ------------------------------------------------------------ | ------------------------------------------------------------ |\n| [\"Discord\"](https://discord.gg/eYMpfnkG8h) | [\"X\"](https://x.com/agentscope_ai) | [\"钉钉\"](https://qr.dingtalk.com/action/joingroup?code=v1,k1,OmDlBXpjW+I2vWjKDsjvI9dhcXjGZi3bQiojOq3dlDw=&_dt_no_comment=1&origin=11) |\n\n---\n\n## 遥测数据\n\nCoPaw 在执行 `copaw init` 时会收集**匿名**使用数据，帮助我们了解用户环境并优化产品。数据**每个版本收集一次** — 当你升级 CoPaw 后，会重新收集以便我们了解版本分布。\n\n**收集的信息：**\n\n- CoPaw 版本（如 0.0.7）\n- 安装方式（pip、Docker 或桌面应用）\n- 操作系统及版本（如 macOS 14.0、Ubuntu 22.04）\n- Python 版本（如 3.13）\n- CPU 架构（如 x86_64、arm64）\n- GPU 是否可用（是/否）\n\n**不收集：** 不涉及任何个人数据、文件、密钥、IP 地址或可识别信息。\n\n交互式运行 `copaw init` 时，会询问你是否同意。使用 `--defaults` 模式则自动同意。提示每个版本仅出现一次，且不影响 CoPaw 的任何功能。\n\n---\n\n## 许可证\n\nCoPaw 采用 [Apache License 2.0](LICENSE) 开源协议。\n\n---\n\n## 贡献者\n\n感谢所有为 CoPaw 做出贡献的朋友们：\n\n\n \"贡献者\"\n\n" }, { "path": "SECURITY.md", "content": "# Security Policy\n\nIf you believe you've found a security issue in CoPaw, please report it privately.\n\n## Reporting\n\nReport vulnerabilities of the CoPaw repository:\n\nIf you discover a security issue in CoPaw, please report it to us through the [Alibaba Security Response Center (ASRC)](https://security.alibaba.com/).\n\n### Required in Reports\n\n1. **Title**\n2. **Severity assessment**\n3. **Impact**\n4. **Affected component** (e.g. channel adapter, skill, config loading)\n5. **Technical reproduction steps**\n6. **Demonstrated impact** (how it crosses a trust boundary, not just theoretical)\n7. **Environment** (Python version, OS, how CoPaw is run)\n8. **Remediation advice** (if you have suggestions)\n\nReports without reproduction steps, demonstrated impact, and remediation advice will be deprioritized. Given the volume of scanner or AI-generated findings, we need vetted reports from researchers who understand the issues.\n\n### Report Acceptance Gate\n\nFor fastest triage, include all of the following:\n\n- Exact vulnerable path (file, function, and line range) on a current revision.\n- Tested version details (CoPaw version and/or commit SHA).\n- Reproducible PoC against latest `main` or latest released version.\n- Demonstrated impact tied to CoPaw's documented trust boundaries (see below).\n- For exposed-secret reports: proof the credential is CoPaw-owned or grants access to CoPaw-operated infrastructure/services.\n- Scope check explaining why the report is **not** covered by the Out of Scope section below.\n\nReports that miss these requirements may be closed as `invalid` or `no-action`.\n\n### Common False-Positive Patterns\n\n- Prompt-injection-only chains without a boundary bypass (prompt injection is out of scope).\n- Operator-intended local features (e.g. skills or commands the operator explicitly enabled) presented as remote injection.\n- Authorized user–triggered actions presented as privilege escalation (e.g. an allowed sender triggering a skill that writes to an allowed path). In this trust model, authorized user actions are trusted unless you demonstrate an auth/sandbox/boundary bypass.\n- Reports that only show a malicious skill executing privileged actions after a trusted operator installs/enables it.\n- Reports that assume per-user multi-tenant authorization on a shared CoPaw instance/config.\n- ReDoS/DoS claims that require trusted operator configuration input without a trust-boundary bypass.\n- Scanner-only claims against stale or nonexistent paths, or claims without a working repro.\n\n### Duplicate Report Handling\n\n- Search existing advisories and issues before filing.\n- Include likely duplicate advisory IDs in your report when applicable.\n- Maintainers may close lower-quality or later duplicates in favor of the earliest high-quality canonical report.\n\n## Alignment with `copaw init`\n\nThe security model and recommended baseline in this document are **aligned with** what users see and accept during **`copaw init`**. The init flow shows a security notice that covers: single-operator boundary; shared delegated authority when multiple people message the same instance; restricting channels and users (allowlists); using separate config/credentials and OS users or hosts per trust boundary; least privilege and sandboxing; keeping secrets out of the working directory and skill-accessible paths; and reviewing config and skills regularly. When updating either this document or the `SECURITY_WARNING` in `src/copaw/cli/init_cmd.py`, keep the **concepts and recommendations** consistent so operators get the same message in both places.\n\n## Security & Trust\n\nSecurity handling is owned by the CoPaw maintainers. For sensitive reports, use the private advisory or a private channel as above.\n\n## Bug Bounties\n\nCoPaw is a community open-source project. There is no bug bounty program and no budget for paid reports. Please still disclose responsibly so we can fix issues quickly. The best way to help the project right now is by sending PRs or clear, reproducible reports.\n\n## Operator Trust Model\n\nCoPaw does **not** model one instance as a multi-tenant, adversarial user boundary.\n\n- Authenticated callers to the same CoPaw instance (same config, same channel workspace) are treated as **trusted operators** for that instance.\n- Session identifiers and labels are routing/context controls, not per-user authorization boundaries.\n- If one operator can see or trigger what another operator can on the same instance, that is expected in this trust model.\n- **Recommended mode**: one user per machine/host (or per OS user), one CoPaw config for that user, and one or more agents/skills inside that instance.\n- If multiple users need CoPaw, use one host/OS user (or VPS) per user, or strict isolation; sharing one instance by mutually untrusted users is not the recommended default.\n- Skills run with the same privileges as the CoPaw process; only install and enable skills you trust.\n\n\n## Trusted Skills Concept\n\nSkills/extensions are part of CoPaw's **trusted computing base** for an instance.\n\n- Installing or enabling a skill grants it the same trust level as local code running for that instance.\n- Skill behavior such as reading env/files or running host commands is expected inside this trust boundary.\n- Security reports must show a **boundary bypass** (e.g. unauthenticated skill load, allowlist/policy bypass, or path-safety bypass), not only malicious behavior from a trusted-installed skill.\n\n## Out of Scope\n\n- Public internet exposure of CoPaw when the docs recommend against it.\n- Using CoPaw in ways that the docs recommend not to.\n- Deployments where mutually untrusted/adversarial operators share one CoPaw instance and config (e.g. reports expecting per-operator isolation for sessions, history, or similar).\n- **Prompt-injection-only** attacks (without a policy/auth/sandbox boundary bypass).\n- Reports that require write access to trusted local state (working directory, config, memory files) to achieve impact.\n- Reports where the only demonstrated impact is an already-authorized user intentionally invoking a skill or command that writes to an allowed path, without bypassing auth, sandbox, or another documented boundary.\n- Reports where the only claim is that a trusted-installed/enabled skill can execute with process/host privileges (documented trust model behavior).\n- Any report whose only claim is that an operator-enabled “dangerous” or break-glass option weakens defaults (these are explicit tradeoffs by design).\n- Reports that depend on trusted operator–supplied configuration to trigger availability impact (e.g. custom regex or patterns). These may still be fixed as defense-in-depth but are not security-boundary bypasses.\n- Exposed secrets that are third-party or user-controlled credentials (not CoPaw-owned and not granting access to CoPaw-operated infrastructure) without demonstrated CoPaw impact.\n- Scanner-only claims against stale or nonexistent paths, or without a working repro.\n\n## Deployment Assumptions\n\nCoPaw security guidance assumes:\n\n- The host where CoPaw runs is within a trusted OS/admin boundary.\n- Anyone who can modify the CoPaw working directory and config (including `config.json`) is effectively a trusted operator.\n- A single instance shared by mutually untrusted people is **not** a recommended setup. Use separate configs and, at minimum, separate OS users or hosts per trust boundary.\n- Authenticated callers to the same instance are treated as trusted operators; session or context identifiers are routing controls, not per-user authorization boundaries.\n- Multiple instances can run on one machine, but the recommended model is clean per-user isolation (prefer one host/OS user per user).\n\n## One-User Trust Model\n\nCoPaw's security model is **“personal assistant”** (one trusted operator, potentially many agents/skills), not “shared multi-tenant bus.”\n\n- If multiple people can message the same tool-enabled CoPaw instance (e.g. a shared channel workspace), they can all steer that agent within its granted permissions.\n- Session or memory scoping reduces context bleed but does **not** create per-user host authorization boundaries.\n- For mixed-trust or adversarial users, isolate by OS user/host and use separate config and credentials per boundary.\n- A company-shared agent can be valid when users are in the same trust boundary and the agent is strictly business-only.\n- For company-shared setups, use a dedicated machine/VM/container and dedicated accounts; avoid mixing personal data on that runtime.\n- If that host or environment is logged into personal accounts (e.g. personal password manager, personal cloud), you have collapsed the boundary and increased personal-data exposure risk.\n\n## Agent and Model Assumptions\n\n- The model/agent is **not** a trusted principal. Assume prompt/content injection can manipulate behavior.\n- Security boundaries come from host/config trust, channel/user allowlists, tool policy, and what skills are enabled.\n- Prompt injection by itself is not a vulnerability report unless it crosses one of those boundaries.\n\n## Working Directory and Config Trust Boundary\n\nThe CoPaw working directory is treated as **trusted local operator state**.\n\n- If someone can edit working directory files or config, they have already crossed the trusted operator boundary.\n- Memory or context over those files is expected behavior, not a separate security boundary.\n- Example out-of-scope pattern: “attacker writes malicious content into workspace files, then the agent uses it.” If you need isolation between mutually untrusted users, split by OS user or host and run separate instances.\n- Keep secrets out of the working directory and skill-accessible paths; this is part of the baseline recommended in `copaw init`.\n\n## Skills Trust Boundary\n\nSkills are loaded and run **in-process** (or under the same trust boundary) as the CoPaw runtime and are treated as trusted code.\n\n- Skills can execute with the same OS privileges as the CoPaw process.\n- Runtime helpers used by skills are convenience APIs, not a sandbox boundary.\n- Only install skills you trust, and restrict which skills are enabled in config where possible.\n\n## Operational Guidance\n\n- **Channels and users**: Restrict which channels and users can trigger the agent; use allowlists where possible.\n- **Multi-user or shared inbox**: Use separate config/credentials and ideally separate OS users or hosts per trust boundary.\n- **Skills**: Run with least privilege; sandbox where you can; limit tool scope to what you need.\n- **Secrets**: Keep them out of the agent's working directory and skill-accessible paths.\n- **Model**: Use a capable model when the agent has tools or handles untrusted input.\n- **Review**: Review your config and skills regularly.\n\nFor more operational and hardening guidance, see the [documentation](https://copaw.agentscope.io/) and any security-related docs linked from the repo.\n\n## Runtime Requirements\n\n- **Python**: CoPaw requires a supported Python version (see [README](README.md)). Use a version with current security updates.\n- **Docker or restricted environments**: When running in containers, run as a non-root user when possible. Use read-only mounts where feasible and limit capabilities to what is needed.\n" }, { "path": "console/eslint.config.js", "content": "import js from \"@eslint/js\";\nimport globals from \"globals\";\nimport reactHooks from \"eslint-plugin-react-hooks\";\nimport reactRefresh from \"eslint-plugin-react-refresh\";\nimport tseslint from \"typescript-eslint\";\n\nexport default tseslint.config(\n { ignores: [\"dist\"] },\n {\n extends: [js.configs.recommended, ...tseslint.configs.recommended],\n files: [\"**/*.{ts,tsx}\"],\n languageOptions: {\n ecmaVersion: 2020,\n globals: globals.browser,\n },\n plugins: {\n \"react-hooks\": reactHooks,\n \"react-refresh\": reactRefresh,\n },\n rules: {\n ...reactHooks.configs.recommended.rules,\n \"react-refresh/only-export-components\": [\n \"warn\",\n { allowConstantExport: true },\n ],\n },\n },\n);\n" }, { "path": "console/index.html", "content": "\n\n \n \n \n \n CoPaw Console\n \n \n
\n \n \n\n" }, { "path": "console/package.json", "content": "{\n \"name\": \"copaw-console\",\n \"private\": true,\n \"version\": \"0.0.0\",\n \"type\": \"module\",\n \"scripts\": {\n \"dev\": \"vite --host\",\n \"build\": \"tsc -b && vite build\",\n \"build:prod\": \"tsc -b && vite build --mode production\",\n \"build:test\": \"tsc -b && vite build --mode test\",\n \"format\": \"prettier --write .\",\n \"format:check\": \"prettier --check .\",\n \"lint\": \"eslint .\",\n \"preview\": \"vite preview\",\n \"preview:prod\": \"vite preview --mode production\",\n \"preview:test\": \"vite preview --mode test\"\n },\n \"dependencies\": {\n \"@agentscope-ai/chat\": \"^1.1.51\",\n \"@agentscope-ai/design\": \"^1.0.14\",\n \"@agentscope-ai/icons\": \"^1.0.46\",\n \"@ant-design/x-markdown\": \"^2.2.2\",\n \"@dnd-kit/core\": \"^6.3.1\",\n \"@dnd-kit/sortable\": \"^10.0.0\",\n \"@dnd-kit/utilities\": \"^3.2.2\",\n \"ahooks\": \"^3.9.6\",\n \"antd\": \"^5.29.1\",\n \"antd-style\": \"^3.7.1\",\n \"i18next\": \"^25.8.4\",\n \"lucide-react\": \"^0.562.0\",\n \"react\": \"^18\",\n \"react-dom\": \"^18\",\n \"react-i18next\": \"^16.5.4\",\n \"react-markdown\": \"^10.1.0\",\n \"react-router-dom\": \"^7.13.0\",\n \"remark-gfm\": \"^4.0.1\"\n },\n \"devDependencies\": {\n \"@eslint/js\": \"^9.25.0\",\n \"@types/i18next\": \"^12.1.0\",\n \"@types/node\": \"^25.0.3\",\n \"@types/react\": \"^18\",\n \"@types/react-dom\": \"^18\",\n \"@vitejs/plugin-react\": \"^4.4.1\",\n \"eslint\": \"^9.25.0\",\n \"eslint-plugin-react-hooks\": \"^5.2.0\",\n \"eslint-plugin-react-refresh\": \"^0.4.19\",\n \"globals\": \"^16.0.0\",\n \"less\": \"^4.5.1\",\n \"prettier\": \"3.0.0\",\n \"typescript\": \"~5.8.3\",\n \"typescript-eslint\": \"^8.30.1\",\n \"vite\": \"^6.3.5\"\n },\n \"repository\": \"https://github.com/agentscope-ai/agentscope-runtime.git\"\n}\n" }, { "path": "console/src/App.tsx", "content": "import { createGlobalStyle } from \"antd-style\";\nimport { ConfigProvider, bailianTheme } from \"@agentscope-ai/design\";\nimport { BrowserRouter, Routes, Route, Navigate } from \"react-router-dom\";\nimport { useEffect, useState } from \"react\";\nimport { useTranslation } from \"react-i18next\";\nimport zhCN from \"antd/locale/zh_CN\";\nimport enUS from \"antd/locale/en_US\";\nimport jaJP from \"antd/locale/ja_JP\";\nimport ruRU from \"antd/locale/ru_RU\";\nimport type { Locale } from \"antd/es/locale\";\nimport { theme as antdTheme } from \"antd\";\nimport dayjs from \"dayjs\";\nimport \"dayjs/locale/zh-cn\";\nimport \"dayjs/locale/ja\";\nimport \"dayjs/locale/ru\";\nimport MainLayout from \"./layouts/MainLayout\";\nimport { ThemeProvider, useTheme } from \"./contexts/ThemeContext\";\nimport LoginPage from \"./pages/Login\";\nimport { authApi } from \"./api/modules/auth\";\nimport { getApiUrl, getApiToken, clearAuthToken } from \"./api/config\";\nimport \"./styles/layout.css\";\nimport \"./styles/form-override.css\";\n\nconst antdLocaleMap: Record = {\n zh: zhCN,\n en: enUS,\n ja: jaJP,\n ru: ruRU,\n};\n\nconst dayjsLocaleMap: Record = {\n zh: \"zh-cn\",\n en: \"en\",\n ja: \"ja\",\n ru: \"ru\",\n};\n\nconst GlobalStyle = createGlobalStyle`\n* {\n margin: 0;\n box-sizing: border-box;\n}\n`;\n\nfunction AuthGuard({ children }: { children: React.ReactNode }) {\n const [status, setStatus] = useState<\"loading\" | \"auth-required\" | \"ok\">(\n \"loading\",\n );\n\n useEffect(() => {\n let cancelled = false;\n (async () => {\n try {\n const res = await authApi.getStatus();\n if (cancelled) return;\n if (!res.enabled) {\n setStatus(\"ok\");\n return;\n }\n const token = getApiToken();\n if (!token) {\n setStatus(\"auth-required\");\n return;\n }\n try {\n const r = await fetch(getApiUrl(\"/auth/verify\"), {\n headers: { Authorization: `Bearer ${token}` },\n });\n if (cancelled) return;\n if (r.ok) {\n setStatus(\"ok\");\n } else {\n clearAuthToken();\n setStatus(\"auth-required\");\n }\n } catch {\n if (!cancelled) {\n clearAuthToken();\n setStatus(\"auth-required\");\n }\n }\n } catch {\n if (!cancelled) setStatus(\"ok\");\n }\n })();\n return () => {\n cancelled = true;\n };\n }, []);\n\n if (status === \"loading\") return null;\n if (status === \"auth-required\")\n return (\n \n );\n return <>{children};\n}\n\nfunction getRouterBasename(pathname: string): string | undefined {\n return /^\\/console(?:\\/|$)/.test(pathname) ? \"/console\" : undefined;\n}\n\nfunction AppInner() {\n const basename = getRouterBasename(window.location.pathname);\n const { i18n } = useTranslation();\n const { isDark } = useTheme();\n const lang = i18n.resolvedLanguage || i18n.language || \"en\";\n const [antdLocale, setAntdLocale] = useState(\n antdLocaleMap[lang] ?? enUS,\n );\n\n useEffect(() => {\n const handleLanguageChanged = (lng: string) => {\n const shortLng = lng.split(\"-\")[0];\n setAntdLocale(antdLocaleMap[shortLng] ?? enUS);\n dayjs.locale(dayjsLocaleMap[shortLng] ?? \"en\");\n };\n\n // Set initial dayjs locale\n dayjs.locale(dayjsLocaleMap[lang.split(\"-\")[0]] ?? \"en\");\n\n i18n.on(\"languageChanged\", handleLanguageChanged);\n return () => {\n i18n.off(\"languageChanged\", handleLanguageChanged);\n };\n }, [i18n]);\n\n return (\n \n \n \n \n } />\n \n \n \n }\n />\n \n \n \n );\n}\n\nfunction App() {\n return (\n \n \n \n );\n}\n\nexport default App;\n" }, { "path": "console/src/api/config.ts", "content": "declare const BASE_URL: string;\ndeclare const TOKEN: string;\n\nconst AUTH_TOKEN_KEY = \"copaw_auth_token\";\n\n/**\n * Get the full API URL with /api prefix\n * @param path - API path (e.g., \"/models\", \"/skills\")\n * @returns Full API URL (e.g., \"http://localhost:8088/api/models\" or \"/api/models\")\n */\nexport function getApiUrl(path: string): string {\n const base = BASE_URL || \"\";\n const apiPrefix = \"/api\";\n const normalizedPath = path.startsWith(\"/\") ? path : `/${path}`;\n return `${base}${apiPrefix}${normalizedPath}`;\n}\n\n/**\n * Get the API token - checks localStorage first (auth login),\n * then falls back to the build-time TOKEN constant.\n * @returns API token string or empty string\n */\nexport function getApiToken(): string {\n const stored = localStorage.getItem(AUTH_TOKEN_KEY);\n if (stored) return stored;\n return typeof TOKEN !== \"undefined\" ? TOKEN : \"\";\n}\n\n/**\n * Store the auth token in localStorage after login.\n */\nexport function setAuthToken(token: string): void {\n localStorage.setItem(AUTH_TOKEN_KEY, token);\n}\n\n/**\n * Remove the auth token from localStorage (logout / 401).\n */\nexport function clearAuthToken(): void {\n localStorage.removeItem(AUTH_TOKEN_KEY);\n}\n" }, { "path": "console/src/api/index.ts", "content": "export * from \"./types\";\n\nexport { request } from \"./request\";\n\nexport { getApiUrl, getApiToken } from \"./config\";\n\nimport { rootApi } from \"./modules/root\";\nimport { channelApi } from \"./modules/channel\";\nimport { heartbeatApi } from \"./modules/heartbeat\";\nimport { cronJobApi } from \"./modules/cronjob\";\nimport { chatApi, sessionApi } from \"./modules/chat\";\nimport { envApi } from \"./modules/env\";\nimport { providerApi } from \"./modules/provider\";\nimport { skillApi } from \"./modules/skill\";\nimport { agentApi } from \"./modules/agent\";\nimport { agentsApi } from \"./modules/agents\";\nimport { workspaceApi } from \"./modules/workspace\";\nimport { localModelApi } from \"./modules/localModel\";\nimport { ollamaModelApi } from \"./modules/ollamaModel\";\nimport { mcpApi } from \"./modules/mcp\";\nimport { tokenUsageApi } from \"./modules/tokenUsage\";\nimport { toolsApi } from \"./modules/tools\";\nimport { securityApi } from \"./modules/security\";\nimport { userTimezoneApi } from \"./modules/userTimezone\";\n\nexport const api = {\n // Root\n ...rootApi,\n\n // Channels\n ...channelApi,\n\n // Heartbeat\n ...heartbeatApi,\n\n // Cron Jobs\n ...cronJobApi,\n\n // Chats\n ...chatApi,\n\n // Sessions（Legacy aliases）\n ...sessionApi,\n\n // Environment Variables\n ...envApi,\n\n // Providers\n ...providerApi,\n\n // Agent\n ...agentApi,\n\n // Skills\n ...skillApi,\n\n // Workspace\n ...workspaceApi,\n\n // Local Models\n ...localModelApi,\n\n // Ollama Models\n ...ollamaModelApi,\n\n // MCP Clients\n ...mcpApi,\n\n // Token Usage\n ...tokenUsageApi,\n // Tools\n ...toolsApi,\n\n // Security\n ...securityApi,\n\n // User Timezone\n ...userTimezoneApi,\n};\n\nexport default api;\n\n// Export individual APIs for direct access\nexport { agentsApi };\n" }, { "path": "console/src/api/modules/agent.ts", "content": "import { request } from \"../request\";\nimport type { AgentRequest, AgentsRunningConfig } from \"../types\";\n\n// Agent API\nexport const agentApi = {\n agentRoot: () => request(\"/agent/\"),\n\n healthCheck: () => request(\"/agent/health\"),\n\n agentApi: (body: AgentRequest) =>\n request(\"/agent/process\", {\n method: \"POST\",\n body: JSON.stringify(body),\n }),\n\n getProcessStatus: () => request(\"/agent/admin/status\"),\n\n shutdownSimple: () =>\n request(\"/agent/shutdown\", {\n method: \"POST\",\n }),\n\n shutdown: () =>\n request(\"/agent/admin/shutdown\", {\n method: \"POST\",\n }),\n\n getAgentRunningConfig: () =>\n request(\"/agent/running-config\"),\n\n updateAgentRunningConfig: (config: AgentsRunningConfig) =>\n request(\"/agent/running-config\", {\n method: \"PUT\",\n body: JSON.stringify(config),\n }),\n\n getAgentLanguage: () => request<{ language: string }>(\"/agent/language\"),\n\n updateAgentLanguage: (language: string) =>\n request<{ language: string; copied_files: string[] }>(\"/agent/language\", {\n method: \"PUT\",\n body: JSON.stringify({ language }),\n }),\n\n getAudioMode: () => request<{ audio_mode: string }>(\"/agent/audio-mode\"),\n\n updateAudioMode: (audio_mode: string) =>\n request<{ audio_mode: string }>(\"/agent/audio-mode\", {\n method: \"PUT\",\n body: JSON.stringify({ audio_mode }),\n }),\n\n getTranscriptionProviders: () =>\n request<{\n providers: { id: string; name: string; available: boolean }[];\n configured_provider_id: string;\n }>(\"/agent/transcription-providers\"),\n\n updateTranscriptionProvider: (provider_id: string) =>\n request<{ provider_id: string }>(\"/agent/transcription-provider\", {\n method: \"PUT\",\n body: JSON.stringify({ provider_id }),\n }),\n\n getTranscriptionProviderType: () =>\n request<{ transcription_provider_type: string }>(\n \"/agent/transcription-provider-type\",\n ),\n\n updateTranscriptionProviderType: (transcription_provider_type: string) =>\n request<{ transcription_provider_type: string }>(\n \"/agent/transcription-provider-type\",\n {\n method: \"PUT\",\n body: JSON.stringify({ transcription_provider_type }),\n },\n ),\n\n getLocalWhisperStatus: () =>\n request<{\n available: boolean;\n ffmpeg_installed: boolean;\n whisper_installed: boolean;\n }>(\"/agent/local-whisper-status\"),\n};\n" }, { "path": "console/src/api/modules/agents.ts", "content": "import { request } from \"../request\";\nimport type {\n AgentListResponse,\n AgentProfileConfig,\n CreateAgentRequest,\n AgentProfileRef,\n} from \"../types/agents\";\nimport type { MdFileInfo, MdFileContent } from \"../types/workspace\";\n\n// Multi-agent management API\nexport const agentsApi = {\n // List all agents\n listAgents: () => request(\"/agents\"),\n\n // Get agent details\n getAgent: (agentId: string) =>\n request(`/agents/${agentId}`),\n\n // Create new agent\n createAgent: (agent: CreateAgentRequest) =>\n request(\"/agents\", {\n method: \"POST\",\n body: JSON.stringify(agent),\n }),\n\n // Update agent configuration\n updateAgent: (agentId: string, agent: AgentProfileConfig) =>\n request(`/agents/${agentId}`, {\n method: \"PUT\",\n body: JSON.stringify(agent),\n }),\n\n // Delete agent\n deleteAgent: (agentId: string) =>\n request<{ success: boolean; agent_id: string }>(`/agents/${agentId}`, {\n method: \"DELETE\",\n }),\n\n // Agent workspace files\n listAgentFiles: (agentId: string) =>\n request(`/agents/${agentId}/files`),\n\n readAgentFile: (agentId: string, filename: string) =>\n request(\n `/agents/${agentId}/files/${encodeURIComponent(filename)}`,\n ),\n\n writeAgentFile: (agentId: string, filename: string, content: string) =>\n request<{ written: boolean; filename: string }>(\n `/agents/${agentId}/files/${encodeURIComponent(filename)}`,\n {\n method: \"PUT\",\n body: JSON.stringify({ content }),\n },\n ),\n\n // Agent memory files\n listAgentMemory: (agentId: string) =>\n request(`/agents/${agentId}/memory`),\n};\n" }, { "path": "console/src/api/modules/auth.ts", "content": "import { getApiUrl } from \"../config\";\n\nexport interface LoginResponse {\n token: string;\n username: string;\n message?: string;\n}\n\nexport interface AuthStatusResponse {\n enabled: boolean;\n has_users: boolean;\n}\n\nexport const authApi = {\n login: async (username: string, password: string): Promise => {\n const res = await fetch(getApiUrl(\"/auth/login\"), {\n method: \"POST\",\n headers: { \"Content-Type\": \"application/json\" },\n body: JSON.stringify({ username, password }),\n });\n if (!res.ok) {\n const err = await res.json().catch(() => ({}));\n throw new Error(err.detail || \"Login failed\");\n }\n return res.json();\n },\n\n register: async (\n username: string,\n password: string,\n ): Promise => {\n const res = await fetch(getApiUrl(\"/auth/register\"), {\n method: \"POST\",\n headers: { \"Content-Type\": \"application/json\" },\n body: JSON.stringify({ username, password }),\n });\n if (!res.ok) {\n const err = await res.json().catch(() => ({}));\n throw new Error(err.detail || \"Registration failed\");\n }\n return res.json();\n },\n\n getStatus: async (): Promise => {\n const res = await fetch(getApiUrl(\"/auth/status\"));\n if (!res.ok) throw new Error(\"Failed to check auth status\");\n return res.json();\n },\n};\n" }, { "path": "console/src/api/modules/channel.ts", "content": "import { request } from \"../request\";\nimport type { ChannelConfig, SingleChannelConfig } from \"../types\";\n\nexport const channelApi = {\n listChannelTypes: () => request(\"/config/channels/types\"),\n\n listChannels: () => request(\"/config/channels\"),\n\n updateChannels: (body: ChannelConfig) =>\n request(\"/config/channels\", {\n method: \"PUT\",\n body: JSON.stringify(body),\n }),\n\n getChannelConfig: (channelName: string) =>\n request(\n `/config/channels/${encodeURIComponent(channelName)}`,\n ),\n\n updateChannelConfig: (channelName: string, body: SingleChannelConfig) =>\n request(\n `/config/channels/${encodeURIComponent(channelName)}`,\n {\n method: \"PUT\",\n body: JSON.stringify(body),\n },\n ),\n};\n" }, { "path": "console/src/api/modules/chat.ts", "content": "import { request } from \"../request\";\nimport { getApiUrl } from \"../config\";\nimport type {\n ChatSpec,\n ChatHistory,\n ChatDeleteResponse,\n Session,\n} from \"../types\";\n\n/** Response from POST /console/upload. url = filename only; agent_id from header. */\nexport interface ChatUploadResponse {\n url: string;\n file_name: string;\n stored_name?: string;\n}\n\nconst CONSOLE_FILES_PREFIX = \"/console/files\";\n\nfunction buildChatUploadHeaders(): HeadersInit {\n const headers: Record = {};\n const token = localStorage.getItem(\"copaw_auth_token\");\n if (token) headers.Authorization = `Bearer ${token}`;\n try {\n const agentStorage = localStorage.getItem(\"copaw-agent-storage\");\n if (agentStorage) {\n const parsed = JSON.parse(agentStorage);\n const selectedAgent = parsed?.state?.selectedAgent;\n if (selectedAgent) headers[\"X-Agent-Id\"] = selectedAgent;\n }\n } catch {\n // ignore\n }\n return headers;\n}\n\nfunction getSelectedAgentId(): string {\n try {\n const agentStorage = localStorage.getItem(\"copaw-agent-storage\");\n if (agentStorage) {\n const parsed = JSON.parse(agentStorage);\n const id = parsed?.state?.selectedAgent;\n if (id) return id;\n }\n } catch {\n // ignore\n }\n return \"\";\n}\n\nexport const chatApi = {\n /** Upload a file for chat attachment. Returns URL path for content. */\n uploadFile: async (file: File): Promise => {\n const formData = new FormData();\n formData.append(\"file\", file);\n const response = await fetch(getApiUrl(\"/console/upload\"), {\n method: \"POST\",\n headers: buildChatUploadHeaders(),\n body: formData,\n });\n if (!response.ok) {\n const text = await response.text().catch(() => \"\");\n throw new Error(\n `Upload failed: ${response.status} ${response.statusText}${\n text ? ` - ${text}` : \"\"\n }`,\n );\n }\n return response.json();\n },\n\n /** Build full API URL for a console file. Backend returns filename only; agent_id from header/context (selectedAgent). */\n fileUrl: (filename: string): string => {\n if (!filename) return \"\";\n if (filename.startsWith(\"http://\") || filename.startsWith(\"https://\"))\n return filename;\n const agentId = getSelectedAgentId() || \"default\";\n const path = `${CONSOLE_FILES_PREFIX}/${agentId}/${filename.replace(\n /^\\/+/,\n \"\",\n )}`;\n return getApiUrl(path);\n },\n listChats: (params?: { user_id?: string; channel?: string }) => {\n const searchParams = new URLSearchParams();\n if (params?.user_id) searchParams.append(\"user_id\", params.user_id);\n if (params?.channel) searchParams.append(\"channel\", params.channel);\n const query = searchParams.toString();\n return request(`/chats${query ? `?${query}` : \"\"}`);\n },\n\n createChat: (chat: Partial) =>\n request(\"/chats\", {\n method: \"POST\",\n body: JSON.stringify(chat),\n }),\n\n getChat: (chatId: string) =>\n request(`/chats/${encodeURIComponent(chatId)}`),\n\n updateChat: (chatId: string, chat: Partial) =>\n request(`/chats/${encodeURIComponent(chatId)}`, {\n method: \"PUT\",\n body: JSON.stringify(chat),\n }),\n\n deleteChat: (chatId: string) =>\n request(`/chats/${encodeURIComponent(chatId)}`, {\n method: \"DELETE\",\n }),\n\n batchDeleteChats: (chatIds: string[]) =>\n request<{ success: boolean; deleted_count: number }>(\n \"/chats/batch-delete\",\n {\n method: \"POST\",\n body: JSON.stringify(chatIds),\n },\n ),\n\n /** Stop a running console chat (only stop when user clicks stop). chat_id = ChatSpec.id */\n stopConsoleChat: (chatId: string) =>\n request<{ stopped: boolean }>(\n `/console/chat/stop?chat_id=${encodeURIComponent(chatId)}`,\n { method: \"POST\" },\n ),\n};\n\nexport const sessionApi = {\n listSessions: (params?: { user_id?: string; channel?: string }) => {\n const searchParams = new URLSearchParams();\n if (params?.user_id) searchParams.append(\"user_id\", params.user_id);\n if (params?.channel) searchParams.append(\"channel\", params.channel);\n const query = searchParams.toString();\n return request(`/chats${query ? `?${query}` : \"\"}`);\n },\n\n getSession: (sessionId: string) =>\n request(`/chats/${encodeURIComponent(sessionId)}`),\n\n deleteSession: (sessionId: string) =>\n request(`/chats/${encodeURIComponent(sessionId)}`, {\n method: \"DELETE\",\n }),\n\n createSession: (session: Partial) =>\n request(\"/chats\", {\n method: \"POST\",\n body: JSON.stringify(session),\n }),\n\n updateSession: (sessionId: string, session: Partial) =>\n request(`/chats/${encodeURIComponent(sessionId)}`, {\n method: \"PUT\",\n body: JSON.stringify(session),\n }),\n\n batchDeleteSessions: (sessionIds: string[]) =>\n request<{ success: boolean; deleted_count: number }>(\n \"/chats/batch-delete\",\n {\n method: \"POST\",\n body: JSON.stringify(sessionIds),\n },\n ),\n};\n" }, { "path": "console/src/api/modules/console.ts", "content": "import { request } from \"../request\";\n\nexport interface PushMessage {\n id: string;\n text: string;\n}\n\nexport const consoleApi = {\n getPushMessages: () =>\n request<{ messages: PushMessage[] }>(\"/console/push-messages\"),\n};\n" }, { "path": "console/src/api/modules/cronjob.ts", "content": "import { request } from \"../request\";\nimport type {\n CronJobSpecInput,\n CronJobSpecOutput,\n CronJobView,\n} from \"../types\";\n\nexport const cronJobApi = {\n listCronJobs: () => request(\"/cron/jobs\"),\n\n createCronJob: (spec: CronJobSpecInput) =>\n request(\"/cron/jobs\", {\n method: \"POST\",\n body: JSON.stringify(spec),\n }),\n\n getCronJob: (jobId: string) =>\n request(`/cron/jobs/${encodeURIComponent(jobId)}`),\n\n replaceCronJob: (jobId: string, spec: CronJobSpecInput) =>\n request(`/cron/jobs/${encodeURIComponent(jobId)}`, {\n method: \"PUT\",\n body: JSON.stringify(spec),\n }),\n\n deleteCronJob: (jobId: string) =>\n request(`/cron/jobs/${encodeURIComponent(jobId)}`, {\n method: \"DELETE\",\n }),\n\n pauseCronJob: (jobId: string) =>\n request(`/cron/jobs/${encodeURIComponent(jobId)}/pause`, {\n method: \"POST\",\n }),\n\n resumeCronJob: (jobId: string) =>\n request(`/cron/jobs/${encodeURIComponent(jobId)}/resume`, {\n method: \"POST\",\n }),\n\n runCronJob: (jobId: string) =>\n request(`/cron/jobs/${encodeURIComponent(jobId)}/run`, {\n method: \"POST\",\n }),\n\n triggerCronJob: (jobId: string) =>\n request(`/cron/jobs/${encodeURIComponent(jobId)}/run`, {\n method: \"POST\",\n }),\n\n getCronJobState: (jobId: string) =>\n request(`/cron/jobs/${encodeURIComponent(jobId)}/state`),\n};\n" }, { "path": "console/src/api/modules/env.ts", "content": "import { request } from \"../request\";\nimport type { EnvVar } from \"../types\";\n\nexport const envApi = {\n listEnvs: () => request(\"/envs\"),\n\n /** Batch save – full replacement of all env vars. */\n saveEnvs: (envs: Record) =>\n request(\"/envs\", {\n method: \"PUT\",\n body: JSON.stringify(envs),\n }),\n\n deleteEnv: (key: string) =>\n request(`/envs/${encodeURIComponent(key)}`, {\n method: \"DELETE\",\n }),\n};\n" }, { "path": "console/src/api/modules/heartbeat.ts", "content": "import { request } from \"../request\";\nimport type { HeartbeatConfig } from \"../types/heartbeat\";\n\nexport const heartbeatApi = {\n getHeartbeatConfig: () => request(\"/config/heartbeat\"),\n\n updateHeartbeatConfig: (body: HeartbeatConfig) =>\n request(\"/config/heartbeat\", {\n method: \"PUT\",\n body: JSON.stringify(body),\n }),\n};\n" }, { "path": "console/src/api/modules/localModel.ts", "content": "import { request } from \"../request\";\nimport type {\n LocalModelResponse,\n DownloadModelRequest,\n DownloadTaskResponse,\n} from \"../types\";\n\nexport const localModelApi = {\n listLocalModels: (backend?: string) => {\n const params = backend ? `?backend=${encodeURIComponent(backend)}` : \"\";\n return request(`/local-models${params}`);\n },\n\n downloadModel: (body: DownloadModelRequest) =>\n request(\"/local-models/download\", {\n method: \"POST\",\n body: JSON.stringify(body),\n }),\n\n getDownloadStatus: (backend?: string) => {\n const params = backend ? `?backend=${encodeURIComponent(backend)}` : \"\";\n return request(\n `/local-models/download-status${params}`,\n );\n },\n\n cancelDownload: (taskId: string) =>\n request<{ status: string; task_id: string }>(\n `/local-models/cancel-download/${encodeURIComponent(taskId)}`,\n { method: \"POST\" },\n ),\n\n deleteLocalModel: (modelId: string) =>\n request<{ status: string; model_id: string }>(\n `/local-models/${encodeURIComponent(modelId)}`,\n { method: \"DELETE\" },\n ),\n};\n" }, { "path": "console/src/api/modules/mcp.ts", "content": "import { request } from \"../request\";\nimport type {\n MCPClientInfo,\n MCPClientCreateRequest,\n MCPClientUpdateRequest,\n} from \"../types\";\n\nexport const mcpApi = {\n /**\n * List all MCP clients\n */\n listMCPClients: () => request(\"/mcp\"),\n\n /**\n * Get details of a specific MCP client\n */\n getMCPClient: (clientKey: string) =>\n request(`/mcp/${encodeURIComponent(clientKey)}`),\n\n /**\n * Create a new MCP client\n */\n createMCPClient: (body: MCPClientCreateRequest) =>\n request(\"/mcp\", {\n method: \"POST\",\n body: JSON.stringify(body),\n }),\n\n /**\n * Update an existing MCP client\n */\n updateMCPClient: (clientKey: string, body: MCPClientUpdateRequest) =>\n request(`/mcp/${encodeURIComponent(clientKey)}`, {\n method: \"PUT\",\n body: JSON.stringify(body),\n }),\n\n /**\n * Toggle MCP client enabled status\n */\n toggleMCPClient: (clientKey: string) =>\n request(`/mcp/${encodeURIComponent(clientKey)}/toggle`, {\n method: \"PATCH\",\n }),\n\n /**\n * Delete an MCP client\n */\n deleteMCPClient: (clientKey: string) =>\n request<{ message: string }>(`/mcp/${encodeURIComponent(clientKey)}`, {\n method: \"DELETE\",\n }),\n};\n" }, { "path": "console/src/api/modules/ollamaModel.ts", "content": "import { request } from \"../request\";\nimport type {\n OllamaModelResponse,\n OllamaDownloadRequest,\n OllamaDownloadTaskResponse,\n} from \"../types\";\n\nexport const ollamaModelApi = {\n listOllamaModels: () => request(\"/ollama-models\"),\n\n downloadOllamaModel: (body: OllamaDownloadRequest) =>\n request(\"/ollama-models/download\", {\n method: \"POST\",\n body: JSON.stringify(body),\n }),\n\n getOllamaDownloadStatus: () =>\n request(\"/ollama-models/download-status\"),\n\n cancelOllamaDownload: (taskId: string) =>\n request<{ status: string; task_id: string }>(\n `/ollama-models/download/${encodeURIComponent(taskId)}`,\n { method: \"DELETE\" },\n ),\n\n deleteOllamaModel: (name: string) =>\n request<{ status: string; name: string }>(\n `/ollama-models/${encodeURIComponent(name)}`,\n { method: \"DELETE\" },\n ),\n};\n" }, { "path": "console/src/api/modules/provider.ts", "content": "import { request } from \"../request\";\nimport type {\n ProviderInfo,\n ProviderConfigRequest,\n ActiveModelsInfo,\n ModelSlotRequest,\n CreateCustomProviderRequest,\n AddModelRequest,\n TestConnectionResponse,\n TestProviderRequest,\n TestModelRequest,\n DiscoverModelsResponse,\n} from \"../types\";\n\nexport const providerApi = {\n listProviders: () => request(\"/models\"),\n\n configureProvider: (providerId: string, body: ProviderConfigRequest) =>\n request(`/models/${encodeURIComponent(providerId)}/config`, {\n method: \"PUT\",\n body: JSON.stringify(body),\n }),\n\n getActiveModels: () => request(\"/models/active\"),\n\n setActiveLlm: (body: ModelSlotRequest) =>\n request(\"/models/active\", {\n method: \"PUT\",\n body: JSON.stringify(body),\n }),\n\n /* ---- Custom provider CRUD ---- */\n\n createCustomProvider: (body: CreateCustomProviderRequest) =>\n request(\"/models/custom-providers\", {\n method: \"POST\",\n body: JSON.stringify(body),\n }),\n\n deleteCustomProvider: (providerId: string) =>\n request(\n `/models/custom-providers/${encodeURIComponent(providerId)}`,\n { method: \"DELETE\" },\n ),\n\n /* ---- Model CRUD (works for both built-in and custom providers) ---- */\n\n addModel: (providerId: string, body: AddModelRequest) =>\n request(`/models/${encodeURIComponent(providerId)}/models`, {\n method: \"POST\",\n body: JSON.stringify(body),\n }),\n\n removeModel: (providerId: string, modelId: string) =>\n request(\n `/models/${encodeURIComponent(providerId)}/models/${encodeURIComponent(\n modelId,\n )}`,\n { method: \"DELETE\" },\n ),\n\n /* ---- Test Connection ---- */\n\n testProviderConnection: (providerId: string, body?: TestProviderRequest) =>\n request(\n `/models/${encodeURIComponent(providerId)}/test`,\n {\n method: \"POST\",\n body: body ? JSON.stringify(body) : undefined,\n },\n ),\n\n testModelConnection: (providerId: string, body: TestModelRequest) =>\n request(\n `/models/${encodeURIComponent(providerId)}/models/test`,\n {\n method: \"POST\",\n body: JSON.stringify(body),\n },\n ),\n\n discoverModels: (providerId: string, body?: TestProviderRequest) =>\n request(\n `/models/${encodeURIComponent(providerId)}/discover`,\n {\n method: \"POST\",\n body: body ? JSON.stringify(body) : undefined,\n },\n ),\n};\n" }, { "path": "console/src/api/modules/root.ts", "content": "import { request } from \"../request\";\n\n// Root API\nexport const rootApi = {\n readRoot: () => request(\"/\"),\n getVersion: () => request<{ version: string }>(\"/version\"),\n};\n" }, { "path": "console/src/api/modules/security.ts", "content": "import { request } from \"../request\";\n\nexport interface ToolGuardRule {\n id: string;\n tools: string[];\n params: string[];\n category: string;\n severity: string;\n patterns: string[];\n exclude_patterns: string[];\n description: string;\n remediation: string;\n}\n\nexport interface ToolGuardConfig {\n enabled: boolean;\n guarded_tools: string[] | null;\n denied_tools: string[];\n custom_rules: ToolGuardRule[];\n disabled_rules: string[];\n}\n\n// ── Skill Scanner types ────────────────────────────────────────────\n\nexport interface SkillScannerWhitelistEntry {\n skill_name: string;\n content_hash: string;\n added_at: string;\n}\n\nexport type SkillScannerMode = \"block\" | \"warn\" | \"off\";\n\nexport interface SkillScannerConfig {\n mode: SkillScannerMode;\n timeout: number;\n whitelist: SkillScannerWhitelistEntry[];\n}\n\nexport interface BlockedSkillFinding {\n severity: string;\n title: string;\n description: string;\n file_path: string;\n line_number: number | null;\n rule_id: string;\n}\n\nexport interface BlockedSkillRecord {\n skill_name: string;\n blocked_at: string;\n max_severity: string;\n findings: BlockedSkillFinding[];\n content_hash: string;\n action: \"blocked\" | \"warned\";\n}\n\nexport interface SecurityScanErrorResponse {\n type: \"security_scan_failed\";\n detail: string;\n skill_name: string;\n max_severity: string;\n findings: BlockedSkillFinding[];\n}\n\nexport const securityApi = {\n // ── Tool Guard ──────────────────────────────────────────────────\n\n getToolGuard: () => request(\"/config/security/tool-guard\"),\n\n updateToolGuard: (body: ToolGuardConfig) =>\n request(\"/config/security/tool-guard\", {\n method: \"PUT\",\n body: JSON.stringify(body),\n }),\n\n getBuiltinRules: () =>\n request(\"/config/security/tool-guard/builtin-rules\"),\n\n // ── Skill Scanner ───────────────────────────────────────────────\n\n getSkillScanner: () =>\n request(\"/config/security/skill-scanner\"),\n\n updateSkillScanner: (body: SkillScannerConfig) =>\n request(\"/config/security/skill-scanner\", {\n method: \"PUT\",\n body: JSON.stringify(body),\n }),\n\n getBlockedHistory: () =>\n request(\n \"/config/security/skill-scanner/blocked-history\",\n ),\n\n clearBlockedHistory: () =>\n request<{ cleared: boolean }>(\n \"/config/security/skill-scanner/blocked-history\",\n { method: \"DELETE\" },\n ),\n\n removeBlockedEntry: (index: number) =>\n request<{ removed: boolean }>(\n `/config/security/skill-scanner/blocked-history/${index}`,\n { method: \"DELETE\" },\n ),\n\n addToWhitelist: (skillName: string, contentHash: string = \"\") =>\n request<{ whitelisted: boolean; skill_name: string }>(\n \"/config/security/skill-scanner/whitelist\",\n {\n method: \"POST\",\n body: JSON.stringify({\n skill_name: skillName,\n content_hash: contentHash,\n }),\n },\n ),\n\n removeFromWhitelist: (skillName: string) =>\n request<{ removed: boolean; skill_name: string }>(\n `/config/security/skill-scanner/whitelist/${encodeURIComponent(\n skillName,\n )}`,\n { method: \"DELETE\" },\n ),\n};\n" }, { "path": "console/src/api/modules/skill.ts", "content": "import { request } from \"../request\";\nimport { getApiUrl, getApiToken } from \"../config\";\nimport type { HubSkillSpec, SkillSpec } from \"../types\";\n\n// Declare BASE_URL as global (injected by Vite)\ndeclare const BASE_URL: string;\n\n// Get the API base URL for streaming requests\nfunction getStreamApiUrl(): string {\n const base = typeof BASE_URL === \"string\" ? BASE_URL : \"\";\n return `${base}/api`;\n}\n\nfunction buildHeaders(): HeadersInit {\n const headers: Record = {};\n\n const token = getApiToken();\n if (token) {\n headers[\"Authorization\"] = `Bearer ${token}`;\n }\n\n try {\n const agentStorage = localStorage.getItem(\"copaw-agent-storage\");\n if (agentStorage) {\n const parsed = JSON.parse(agentStorage);\n const selectedAgent = parsed?.state?.selectedAgent;\n if (selectedAgent) {\n headers[\"X-Agent-Id\"] = selectedAgent;\n }\n }\n } catch (error) {\n console.warn(\"Failed to get selected agent from storage:\", error);\n }\n\n return headers;\n}\n\nexport const skillApi = {\n listSkills: () => request(\"/skills\"),\n\n createSkill: (skillName: string, content: string) =>\n request>(\"/skills\", {\n method: \"POST\",\n body: JSON.stringify({\n name: skillName,\n content: content,\n }),\n }),\n\n enableSkill: (skillName: string) =>\n request(`/skills/${encodeURIComponent(skillName)}/enable`, {\n method: \"POST\",\n }),\n\n disableSkill: (skillName: string) =>\n request(`/skills/${encodeURIComponent(skillName)}/disable`, {\n method: \"POST\",\n }),\n\n batchEnableSkills: (skillNames: string[]) =>\n request(\"/skills/batch-enable\", {\n method: \"POST\",\n body: JSON.stringify(skillNames),\n }),\n\n deleteSkill: (skillName: string) =>\n request<{ deleted: boolean }>(`/skills/${encodeURIComponent(skillName)}`, {\n method: \"DELETE\",\n }),\n\n searchHubSkills: (query: string, limit = 20) =>\n request(\n `/skills/hub/search?q=${encodeURIComponent(query)}&limit=${limit}`,\n ),\n\n installHubSkill: (\n payload: {\n bundle_url: string;\n version?: string;\n enable?: boolean;\n overwrite?: boolean;\n },\n options?: { signal?: AbortSignal },\n ) =>\n request<{\n installed: boolean;\n name: string;\n enabled: boolean;\n source_url: string;\n }>(\"/skills/hub/install\", {\n method: \"POST\",\n body: JSON.stringify(payload),\n signal: options?.signal,\n }),\n\n startHubSkillInstall: (payload: {\n bundle_url: string;\n version?: string;\n enable?: boolean;\n overwrite?: boolean;\n }) =>\n request<{\n task_id: string;\n bundle_url: string;\n version: string;\n enable: boolean;\n overwrite: boolean;\n status: \"pending\" | \"importing\" | \"completed\" | \"failed\" | \"cancelled\";\n error: string | null;\n result: {\n installed: boolean;\n name: string;\n enabled: boolean;\n source_url: string;\n } | null;\n created_at: number;\n updated_at: number;\n }>(\"/skills/hub/install/start\", {\n method: \"POST\",\n body: JSON.stringify(payload),\n }),\n\n getHubSkillInstallStatus: (taskId: string) =>\n request<{\n task_id: string;\n bundle_url: string;\n version: string;\n enable: boolean;\n overwrite: boolean;\n status: \"pending\" | \"importing\" | \"completed\" | \"failed\" | \"cancelled\";\n error: string | null;\n result: {\n installed: boolean;\n name: string;\n enabled: boolean;\n source_url: string;\n } | null;\n created_at: number;\n updated_at: number;\n }>(`/skills/hub/install/status/${encodeURIComponent(taskId)}`),\n\n cancelHubSkillInstall: (taskId: string) =>\n request<{ task_id: string; status: string }>(\n `/skills/hub/install/cancel/${encodeURIComponent(taskId)}`,\n {\n method: \"POST\",\n },\n ),\n\n // Stream optimize skill with SSE (supports abort via signal)\n streamOptimizeSkill: async function (\n content: string,\n onChunk: (text: string) => void,\n signal: AbortSignal,\n language: string = \"en\",\n ): Promise {\n const apiUrl = getStreamApiUrl();\n\n const response = await fetch(`${apiUrl}/skills/ai/optimize/stream`, {\n method: \"POST\",\n headers: {\n \"Content-Type\": \"application/json\",\n },\n body: JSON.stringify({ content, language }),\n signal,\n });\n\n if (!response.ok) {\n throw new Error(`HTTP error! status: ${response.status}`);\n }\n\n const reader = response.body?.getReader();\n if (!reader) {\n throw new Error(\"No reader available\");\n }\n\n const decoder = new TextDecoder();\n let buffer = \"\";\n\n try {\n while (true) {\n const { done, value } = await reader.read();\n if (done) break;\n\n buffer += decoder.decode(value, { stream: true });\n const lines = buffer.split(\"\\n\");\n\n for (let i = 0; i < lines.length - 1; i++) {\n const line = lines[i].trim();\n if (line.startsWith(\"data: \")) {\n const data = line.slice(6);\n try {\n const parsed = JSON.parse(data);\n if (parsed.text) {\n onChunk(parsed.text);\n } else if (parsed.error) {\n throw new Error(parsed.error);\n } else if (parsed.done) {\n return;\n }\n } catch {\n // Skip invalid JSON\n }\n }\n }\n\n buffer = lines[lines.length - 1];\n }\n } finally {\n reader.releaseLock();\n }\n },\n\n uploadSkill: async (\n file: File,\n options?: { enable?: boolean; overwrite?: boolean },\n ): Promise<{ imported: string[]; count: number; enabled: boolean }> => {\n const formData = new FormData();\n formData.append(\"file\", file);\n\n const params = new URLSearchParams();\n if (options?.enable !== undefined) {\n params.set(\"enable\", String(options.enable));\n }\n if (options?.overwrite !== undefined) {\n params.set(\"overwrite\", String(options.overwrite));\n }\n const qs = params.toString();\n const url = getApiUrl(`/skills/upload${qs ? `?${qs}` : \"\"}`);\n\n const headers = buildHeaders();\n\n const response = await fetch(url, {\n method: \"POST\",\n headers,\n body: formData,\n });\n\n if (!response.ok) {\n const errorText = await response.text();\n throw new Error(\n `Upload failed: ${response.status} ${response.statusText} - ${errorText}`,\n );\n }\n\n return await response.json();\n },\n};\n" }, { "path": "console/src/api/modules/tokenUsage.ts", "content": "import { request } from \"../request\";\nimport type { TokenUsageSummary } from \"../types/tokenUsage\";\n\nexport interface GetTokenUsageParams {\n start_date: string;\n end_date: string;\n}\n\nfunction buildQuery(params: GetTokenUsageParams): string {\n const search = new URLSearchParams({\n start_date: params.start_date,\n end_date: params.end_date,\n });\n return `?${search.toString()}`;\n}\n\nexport const tokenUsageApi = {\n getTokenUsage: (params: GetTokenUsageParams) =>\n request(`/token-usage${buildQuery(params)}`),\n};\n" }, { "path": "console/src/api/modules/tools.ts", "content": "import { request } from \"../request\";\n\nexport interface ToolInfo {\n name: string;\n enabled: boolean;\n description: string;\n}\n\nexport const toolsApi = {\n /**\n * List all built-in tools\n */\n listTools: () => request(\"/tools\"),\n\n /**\n * Toggle tool enabled status\n */\n toggleTool: (toolName: string) =>\n request(`/tools/${encodeURIComponent(toolName)}/toggle`, {\n method: \"PATCH\",\n }),\n};\n" }, { "path": "console/src/api/modules/userTimezone.ts", "content": "import { request } from \"../request\";\n\nexport interface UserTimezoneConfig {\n timezone: string;\n}\n\nexport const userTimezoneApi = {\n getUserTimezone: () => request(\"/config/user-timezone\"),\n\n updateUserTimezone: (timezone: string) =>\n request(\"/config/user-timezone\", {\n method: \"PUT\",\n body: JSON.stringify({ timezone }),\n }),\n};\n" }, { "path": "console/src/api/modules/workspace.ts", "content": "import { request } from \"../request\";\nimport { getApiUrl, getApiToken } from \"../config\";\nimport type { MdFileInfo, MdFileContent, DailyMemoryFile } from \"../types\";\n\nfunction buildHeaders(): HeadersInit {\n const headers: Record = {};\n\n const token = getApiToken();\n if (token) {\n headers[\"Authorization\"] = `Bearer ${token}`;\n }\n\n try {\n const agentStorage = localStorage.getItem(\"copaw-agent-storage\");\n if (agentStorage) {\n const parsed = JSON.parse(agentStorage);\n const selectedAgent = parsed?.state?.selectedAgent;\n if (selectedAgent) {\n headers[\"X-Agent-Id\"] = selectedAgent;\n }\n }\n } catch (error) {\n console.warn(\"Failed to get selected agent from storage:\", error);\n }\n\n return headers;\n}\n\nfunction getSelectedAgentId(): string {\n try {\n const agentStorage = localStorage.getItem(\"copaw-agent-storage\");\n if (agentStorage) {\n const parsed = JSON.parse(agentStorage);\n const selectedAgent = parsed?.state?.selectedAgent;\n if (selectedAgent) {\n return selectedAgent;\n }\n }\n } catch (error) {\n console.warn(\"Failed to get selected agent from storage:\", error);\n }\n return \"default\";\n}\n\nfunction generateFallbackFilename(): string {\n const agentId = getSelectedAgentId();\n const now = new Date();\n const timestamp = now\n .toISOString()\n .replace(/[-:]/g, \"\")\n .replace(/\\..+/, \"\")\n .replace(\"T\", \"_\")\n .slice(0, 15); // YYYYMMDD_HHMMSS\n return `copaw_workspace_${agentId}_${timestamp}.zip`;\n}\n\nexport interface WorkspaceDownloadResult {\n blob: Blob;\n filename: string;\n}\n\nexport const workspaceApi = {\n listFiles: () =>\n request(\"/agent/files\").then((files) =>\n files.map((file) => ({\n ...file,\n updated_at: new Date(file.modified_time).getTime(),\n })),\n ),\n\n loadFile: (fileName: string) =>\n request(`/agent/files/${encodeURIComponent(fileName)}`),\n\n saveFile: (fileName: string, content: string) =>\n request>(\n `/agent/files/${encodeURIComponent(fileName)}`,\n {\n method: \"PUT\",\n body: JSON.stringify({ content }),\n },\n ),\n\n // Workspace package download\n downloadWorkspace: async (): Promise => {\n const response = await fetch(getApiUrl(\"/workspace/download\"), {\n method: \"GET\",\n headers: buildHeaders(),\n });\n\n if (!response.ok) {\n throw new Error(\n `Workspace download failed: ${response.status} ${response.statusText}`,\n );\n }\n\n const blob = await response.blob();\n\n // Extract filename from Content-Disposition header\n const disposition = response.headers.get(\"Content-Disposition\");\n let filename: string;\n\n if (disposition) {\n const filenameMatch = disposition.match(/filename=\"(.+?)\"/);\n if (filenameMatch && filenameMatch[1]) {\n filename = filenameMatch[1];\n } else {\n filename = generateFallbackFilename();\n }\n } else {\n filename = generateFallbackFilename();\n }\n\n return { blob, filename };\n },\n\n // File upload functionality\n uploadFile: async (\n file: File,\n ): Promise<{ success: boolean; message: string }> => {\n const formData = new FormData();\n formData.append(\"file\", file);\n\n const response = await fetch(getApiUrl(\"/workspace/upload\"), {\n method: \"POST\",\n headers: buildHeaders(),\n body: formData,\n });\n\n if (!response.ok) {\n const errorText = await response.text();\n throw new Error(\n `Upload failed: ${response.status} ${response.statusText} - ${errorText}`,\n );\n }\n\n return await response.json();\n },\n\n listDailyMemory: () =>\n request(\"/agent/memory\").then((files) =>\n files.map((file) => {\n const date = file.filename.replace(\".md\", \"\");\n return {\n ...file,\n date,\n updated_at: new Date(file.modified_time).getTime(),\n } as DailyMemoryFile;\n }),\n ),\n\n loadDailyMemory: (date: string) =>\n request(`/agent/memory/${encodeURIComponent(date)}.md`),\n\n saveDailyMemory: (date: string, content: string) =>\n request>(\n `/agent/memory/${encodeURIComponent(date)}.md`,\n {\n method: \"PUT\",\n body: JSON.stringify({ content }),\n },\n ),\n\n // System prompt files management\n getSystemPromptFiles: () => request(\"/agent/system-prompt-files\"),\n\n setSystemPromptFiles: (files: string[]) =>\n request(\"/agent/system-prompt-files\", {\n method: \"PUT\",\n body: JSON.stringify(files),\n }),\n};\n" }, { "path": "console/src/api/request.ts", "content": "import { getApiUrl, getApiToken, clearAuthToken } from \"./config\";\n\nfunction buildHeaders(method?: string, extra?: HeadersInit): Headers {\n // Normalize extra to a Headers instance for consistent handling\n const headers = extra instanceof Headers ? extra : new Headers(extra);\n\n // Only add Content-Type for methods that typically have a body\n if (method && [\"POST\", \"PUT\", \"PATCH\"].includes(method.toUpperCase())) {\n // Don't override if caller explicitly set Content-Type\n if (!headers.has(\"Content-Type\")) {\n headers.set(\"Content-Type\", \"application/json\");\n }\n }\n\n // Add authorization token if available\n const token = getApiToken();\n if (token) {\n headers.set(\"Authorization\", `Bearer ${token}`);\n }\n\n // Add selected agent ID to all requests (for multi-agent support)\n try {\n const agentStorage = localStorage.getItem(\"copaw-agent-storage\");\n if (agentStorage) {\n const parsed = JSON.parse(agentStorage);\n const selectedAgent = parsed?.state?.selectedAgent;\n if (selectedAgent) {\n headers.set(\"X-Agent-Id\", selectedAgent);\n }\n }\n } catch (error) {\n // Ignore localStorage errors\n console.warn(\"Failed to get selected agent from storage:\", error);\n }\n\n return headers;\n}\n\nexport async function request(\n path: string,\n options: RequestInit = {},\n): Promise {\n const url = getApiUrl(path);\n const method = options.method || \"GET\";\n const headers = buildHeaders(method, options.headers);\n\n const response = await fetch(url, {\n ...options,\n headers,\n });\n\n if (!response.ok) {\n // Handle 401: clear token and redirect to login\n if (response.status === 401) {\n clearAuthToken();\n if (window.location.pathname !== \"/login\") {\n window.location.href = \"/login\";\n }\n throw new Error(\"Not authenticated\");\n }\n\n const text = await response.text().catch(() => \"\");\n throw new Error(\n `Request failed: ${response.status} ${response.statusText}${\n text ? ` - ${text}` : \"\"\n }`,\n );\n }\n\n if (response.status === 204) {\n return undefined as T;\n }\n\n const contentType = response.headers.get(\"content-type\") || \"\";\n if (!contentType.includes(\"application/json\")) {\n return (await response.text()) as unknown as T;\n }\n\n return (await response.json()) as T;\n}\n" }, { "path": "console/src/api/types/agent.ts", "content": "export interface AgentRequest {\n input: unknown;\n session_id?: string | null;\n user_id?: string | null;\n channel?: string | null;\n [key: string]: unknown;\n}\n\nexport interface AgentsRunningConfig {\n max_iters: number;\n max_input_length: number;\n memory_compact_ratio: number;\n memory_reserve_ratio: number;\n tool_result_compact_recent_n: number;\n tool_result_compact_old_threshold: number;\n tool_result_compact_recent_threshold: number;\n tool_result_compact_retention_days: number;\n}\n" }, { "path": "console/src/api/types/agents.ts", "content": "// Multi-agent management types\n\nexport interface AgentSummary {\n id: string;\n name: string;\n description: string;\n workspace_dir: string;\n}\n\nexport interface AgentListResponse {\n agents: AgentSummary[];\n}\n\nexport interface AgentProfileConfig {\n id: string;\n name: string;\n description?: string;\n workspace_dir?: string;\n channels?: unknown;\n mcp?: unknown;\n heartbeat?: unknown;\n running?: unknown;\n llm_routing?: unknown;\n system_prompt_files?: string[];\n tools?: unknown;\n security?: unknown;\n}\n\nexport interface CreateAgentRequest {\n name: string;\n description?: string;\n workspace_dir?: string;\n language?: string;\n}\n\nexport interface AgentProfileRef {\n id: string;\n workspace_dir: string;\n}\n" }, { "path": "console/src/api/types/channel.ts", "content": "export interface BaseChannelConfig {\n enabled: boolean;\n bot_prefix: string;\n filter_tool_messages?: boolean;\n filter_thinking?: boolean;\n dm_policy?: \"open\" | \"allowlist\";\n group_policy?: \"open\" | \"allowlist\";\n allow_from?: string[];\n require_mention?: boolean;\n}\n\nexport interface IMessageChannelConfig extends BaseChannelConfig {\n db_path: string;\n poll_sec: number;\n}\n\nexport interface DiscordConfig extends BaseChannelConfig {\n bot_token: string;\n http_proxy: string;\n http_proxy_auth: string;\n}\n\nexport interface DingTalkConfig extends BaseChannelConfig {\n client_id: string;\n client_secret: string;\n message_type: string;\n card_template_id: string;\n card_template_key: string;\n robot_code: string;\n}\n\nexport interface FeishuConfig extends BaseChannelConfig {\n app_id: string;\n app_secret: string;\n encrypt_key: string;\n verification_token: string;\n media_dir: string;\n}\n\nexport interface QQConfig extends BaseChannelConfig {\n app_id: string;\n client_secret: string;\n}\n\nexport interface TelegramConfig extends BaseChannelConfig {\n bot_token: string;\n http_proxy: string;\n http_proxy_auth: string;\n show_typing?: boolean;\n}\n\nexport interface MQTTConfig extends BaseChannelConfig {\n host: string;\n port: number;\n transport: string;\n clean_session: boolean;\n qos: number;\n username: string;\n password: string;\n subscribe_topic: string;\n publish_topic: string;\n tls_enabled?: boolean;\n tls_ca_certs?: string;\n tls_certfile?: string;\n tls_keyfile?: string;\n}\n\nexport interface MatrixConfig extends BaseChannelConfig {\n homeserver: string;\n user_id: string;\n access_token: string;\n}\n\nexport type ConsoleConfig = BaseChannelConfig;\n\nexport interface VoiceChannelConfig extends BaseChannelConfig {\n twilio_account_sid: string;\n twilio_auth_token: string;\n phone_number: string;\n phone_number_sid: string;\n tts_provider: string;\n tts_voice: string;\n stt_provider: string;\n language: string;\n welcome_greeting: string;\n}\n\nexport interface XiaoYiConfig extends BaseChannelConfig {\n ak: string;\n sk: string;\n agent_id: string;\n ws_url: string;\n task_timeout_ms?: number;\n}\n\nexport interface ChannelConfig {\n imessage: IMessageChannelConfig;\n discord: DiscordConfig;\n dingtalk: DingTalkConfig;\n feishu: FeishuConfig;\n qq: QQConfig;\n telegram: TelegramConfig;\n mqtt: MQTTConfig;\n matrix: MatrixConfig;\n console: ConsoleConfig;\n voice: VoiceChannelConfig;\n xiaoyi: XiaoYiConfig;\n}\n\nexport type SingleChannelConfig =\n | IMessageChannelConfig\n | DiscordConfig\n | DingTalkConfig\n | FeishuConfig\n | QQConfig\n | ConsoleConfig\n | TelegramConfig\n | MQTTConfig\n | MatrixConfig\n | VoiceChannelConfig\n | XiaoYiConfig;\n" }, { "path": "console/src/api/types/chat.ts", "content": "export type ChatStatus = \"idle\" | \"running\";\n\nexport interface ChatSpec {\n id: string; // Chat UUID identifier\n session_id: string; // Session identifier (channel:user_id format)\n user_id: string; // User identifier\n channel: string; // Channel name, default: \"default\"\n created_at: string | null; // Chat creation timestamp (ISO 8601)\n updated_at: string | null; // Chat last update timestamp (ISO 8601)\n meta?: Record; // Additional metadata\n status?: ChatStatus; // Conversation status: idle or running\n}\n\nexport interface Message {\n role: string;\n content: unknown;\n [key: string]: unknown;\n}\n\nexport interface ChatHistory {\n messages: Message[];\n status?: ChatStatus; // Conversation status: idle or running\n}\n\nexport interface ChatDeleteResponse {\n success: boolean;\n chat_id: string;\n}\n\n// Legacy Session type alias for backward compatibility\nexport type Session = ChatSpec;\n" }, { "path": "console/src/api/types/cronjob.ts", "content": "export interface CronJobSchedule {\n type: \"cron\";\n cron: string;\n timezone?: string;\n}\n\nexport interface CronJobTarget {\n user_id: string;\n session_id: string;\n}\n\nexport interface CronJobDispatch {\n type: \"channel\";\n channel?: string;\n target: CronJobTarget;\n mode?: \"stream\" | \"final\";\n meta?: Record;\n}\n\nexport interface CronJobRuntime {\n max_concurrency?: number;\n timeout_seconds?: number;\n misfire_grace_seconds?: number;\n}\n\nexport interface CronJobRequest {\n input: unknown;\n session_id?: string | null;\n user_id?: string | null;\n [key: string]: unknown;\n}\n\nexport interface CronJobSpecInput {\n id: string;\n name: string;\n enabled?: boolean;\n schedule: CronJobSchedule;\n task_type?: \"text\" | \"agent\";\n text?: string;\n request?: CronJobRequest;\n dispatch: CronJobDispatch;\n runtime?: CronJobRuntime;\n meta?: Record;\n}\n\nexport type CronJobSpecOutput = CronJobSpecInput;\n\nexport interface CronJobView extends CronJobSpecOutput {\n // Extended view with runtime state\n state?: unknown;\n next_run_time?: number;\n last_run_time?: number;\n}\n\nexport type CronJobSpecInputLegacy = Record;\nexport type CronJobSpecOutputLegacy = Record;\nexport type CronJobViewLegacy = Record;\n" }, { "path": "console/src/api/types/env.ts", "content": "export interface EnvVar {\n key: string;\n value: string;\n}\n" }, { "path": "console/src/api/types/heartbeat.ts", "content": "export interface ActiveHoursConfig {\n start: string;\n end: string;\n}\n\nexport interface HeartbeatConfig {\n enabled: boolean;\n every: string;\n target: string;\n activeHours?: ActiveHoursConfig | null;\n}\n" }, { "path": "console/src/api/types/index.ts", "content": "export * from \"./agent\";\nexport * from \"./agents\";\nexport * from \"./channel\";\nexport * from \"./heartbeat\";\nexport * from \"./chat\";\nexport * from \"./cronjob\";\nexport * from \"./env\";\nexport * from \"./mcp\";\nexport * from \"./provider\";\nexport * from \"./skill\";\nexport * from \"./workspace\";\nexport * from \"./tokenUsage\";\n" }, { "path": "console/src/api/types/mcp.ts", "content": "/**\n * MCP (Model Context Protocol) client types\n */\n\nexport interface MCPClientInfo {\n /** Unique client key identifier */\n key: string;\n /** Client display name */\n name: string;\n /** Client description */\n description: string;\n /** Whether the client is enabled */\n enabled: boolean;\n /** MCP transport type */\n transport: \"stdio\" | \"streamable_http\" | \"sse\";\n /** Remote MCP endpoint URL for HTTP/SSE transport */\n url: string;\n /** HTTP headers for remote transport */\n headers: Record;\n /** Command to launch the MCP server */\n command: string;\n /** Command-line arguments */\n args: string[];\n /** Environment variables */\n env: Record;\n /** Working directory for stdio command */\n cwd: string;\n}\n\nexport interface MCPClientCreateRequest {\n /** Unique client key identifier */\n client_key: string;\n /** Client configuration */\n client: {\n /** Client display name */\n name: string;\n /** Client description */\n description?: string;\n /** Whether to enable the client */\n enabled?: boolean;\n /** MCP transport type */\n transport?: \"stdio\" | \"streamable_http\" | \"sse\";\n /** Remote MCP endpoint URL for HTTP/SSE transport */\n url?: string;\n /** HTTP headers for remote transport */\n headers?: Record;\n /** Command to launch the MCP server */\n command?: string;\n /** Command-line arguments */\n args?: string[];\n /** Environment variables */\n env?: Record;\n /** Working directory for stdio command */\n cwd?: string;\n };\n}\n\nexport interface MCPClientUpdateRequest {\n /** Client display name */\n name?: string;\n /** Client description */\n description?: string;\n /** Whether to enable the client */\n enabled?: boolean;\n /** MCP transport type */\n transport?: \"stdio\" | \"streamable_http\" | \"sse\";\n /** Remote MCP endpoint URL for HTTP/SSE transport */\n url?: string;\n /** HTTP headers for remote transport */\n headers?: Record;\n /** Command to launch the MCP server */\n command?: string;\n /** Command-line arguments */\n args?: string[];\n /** Environment variables */\n env?: Record;\n /** Working directory for stdio command */\n cwd?: string;\n}\n" }, { "path": "console/src/api/types/provider.ts", "content": "export interface ModelInfo {\n id: string;\n name: string;\n}\n\nexport interface ProviderInfo {\n id: string;\n name: string;\n api_key_prefix: string;\n chat_model: string;\n /** Built-in models (for built-in providers) or all models (for custom). */\n models: ModelInfo[];\n /** User-added models (deletable). Only populated for built-in providers. */\n extra_models: ModelInfo[];\n is_custom: boolean;\n is_local: boolean;\n /** Whether this provider supports fetching available models from the provider's API. */\n support_model_discovery: boolean;\n /** Whether this provider supports checking connection to the API without model configuration. */\n support_connection_check: boolean;\n /** True when the base_url should be frozen (not editable). */\n freeze_url: boolean;\n /** True when an API key is required for this provider. */\n require_api_key: boolean;\n api_key: string;\n base_url: string;\n generate_kwargs: Record;\n}\n\nexport interface ProviderConfigRequest {\n api_key?: string;\n base_url?: string;\n chat_model?: string;\n generate_kwargs?: Record;\n}\n\nexport interface ModelSlotConfig {\n provider_id: string;\n model: string;\n}\n\nexport interface ActiveModelsInfo {\n active_llm?: ModelSlotConfig;\n}\n\nexport interface ModelSlotRequest {\n provider_id: string;\n model: string;\n}\n\n/* ---- Custom provider CRUD ---- */\n\nexport interface CreateCustomProviderRequest {\n id: string;\n name: string;\n default_base_url?: string;\n api_key_prefix?: string;\n chat_model?: string;\n models?: ModelInfo[];\n}\n\nexport interface AddModelRequest {\n id: string;\n name: string;\n}\n\n/* ---- Local models ---- */\n\nexport interface LocalModelResponse {\n id: string;\n repo_id: string;\n filename: string;\n backend: string;\n source: string;\n file_size: number;\n local_path: string;\n display_name: string;\n}\n\nexport interface DownloadModelRequest {\n repo_id: string;\n filename?: string;\n backend: string;\n source: string;\n}\n\nexport interface DownloadTaskResponse {\n task_id: string;\n status: \"pending\" | \"downloading\" | \"completed\" | \"failed\" | \"cancelled\";\n repo_id: string;\n filename: string | null;\n backend: string;\n source: string;\n error: string | null;\n result: LocalModelResponse | null;\n}\n\n/* ---- Ollama models ---- */\n\nexport interface OllamaModelResponse {\n name: string;\n size: number;\n digest?: string | null;\n modified_at?: string | null;\n}\n\nexport interface OllamaDownloadRequest {\n name: string;\n}\n\nexport interface OllamaDownloadTaskResponse {\n task_id: string;\n status: \"pending\" | \"downloading\" | \"completed\" | \"failed\" | \"cancelled\";\n name: string;\n error: string | null;\n result: OllamaModelResponse | null;\n}\n\n/* ---- Test Connection ---- */\n\nexport interface TestConnectionResponse {\n success: boolean;\n message: string;\n}\n\nexport interface TestProviderRequest {\n api_key?: string;\n base_url?: string;\n chat_model?: string;\n generate_kwargs?: Record;\n}\n\nexport interface TestModelRequest {\n model_id: string;\n}\n\nexport interface DiscoverModelsResponse {\n success: boolean;\n message: string;\n models: ModelInfo[];\n added_count: number;\n}\n" }, { "path": "console/src/api/types/skill.ts", "content": "export interface SkillSpec {\n name: string;\n description?: string;\n content: string;\n source: string;\n path: string;\n enabled?: boolean;\n}\n\nexport interface HubSkillSpec {\n slug: string;\n name: string;\n description: string;\n version: string;\n source_url: string;\n}\n\n// Legacy Skill interface for backward compatibility\nexport interface Skill {\n id: string;\n name: string;\n description: string;\n function_name: string;\n enabled: boolean;\n version: string;\n tags: string[];\n created_at: number;\n updated_at: number;\n}\n" }, { "path": "console/src/api/types/tokenUsage.ts", "content": "/** Per-model (has provider_id, model) or per-date (no provider_id, model) stats. */\nexport interface TokenUsageStats {\n provider_id?: string;\n model?: string;\n prompt_tokens: number;\n completion_tokens: number;\n call_count: number;\n}\n\nexport interface TokenUsageSummary {\n total_prompt_tokens: number;\n total_completion_tokens: number;\n total_calls: number;\n by_model: Record;\n by_date: Record;\n}\n" }, { "path": "console/src/api/types/workspace.ts", "content": "export interface MdFileInfo {\n filename: string;\n path: string;\n size: number;\n created_time: string;\n modified_time: string;\n}\n\nexport interface MdFileContent {\n content: string;\n}\n\nexport interface MarkdownFile extends MdFileInfo {\n updated_at: number;\n enabled?: boolean;\n}\n\nexport interface DailyMemoryFile extends MdFileInfo {\n date: string;\n updated_at: number;\n}\n" }, { "path": "console/src/components/AgentSelector/index.module.less", "content": "// ─── Wrapper ──────────────────────────────────────────────────────────────────\n.agentSelectorWrapper {\n display: flex;\n align-items: center;\n gap: 8px;\n padding: 0;\n background: transparent;\n border: none;\n transition: all 0.2s ease;\n}\n\n// ─── Label ────────────────────────────────────────────────────────────────────\n.agentSelectorLabel {\n display: flex;\n align-items: center;\n gap: 6px;\n font-size: 12px;\n font-weight: 500;\n color: rgba(0, 0, 0, 0.4);\n white-space: nowrap;\n user-select: none;\n\n svg {\n opacity: 0.5;\n }\n}\n\n// ─── Select Component ─────────────────────────────────────────────────────────\n.agentSelector {\n min-width: 180px;\n\n :global {\n .ant-select-selector {\n border: 1px solid rgba(97, 92, 237, 0.25) !important;\n background: rgba(97, 92, 237, 0.04) !important;\n box-shadow: none !important;\n padding: 4px 8px !important;\n height: 32px !important;\n font-size: 13px;\n font-weight: 500;\n border-radius: 8px !important;\n transition: all 0.2s ease;\n\n &:hover {\n border-color: rgba(97, 92, 237, 0.45) !important;\n background: rgba(97, 92, 237, 0.07) !important;\n }\n\n &:focus {\n border-color: #615ced !important;\n background: #ffffff !important;\n box-shadow: 0 0 0 2px rgba(97, 92, 237, 0.12) !important;\n }\n }\n\n .ant-select-selection-item {\n padding: 0 !important;\n line-height: 22px;\n }\n\n .ant-select-arrow {\n color: rgba(97, 92, 237, 0.5);\n right: 8px;\n\n .ant-select-suffix {\n display: flex;\n align-items: center;\n }\n }\n\n .ant-select-focused {\n .ant-select-selector {\n border-color: #615ced !important;\n background: #ffffff !important;\n box-shadow: 0 0 0 2px rgba(97, 92, 237, 0.12) !important;\n }\n }\n }\n}\n\n// ─── Selected Agent Label ─────────────────────────────────────────────────────\n.selectedAgentLabel {\n display: flex;\n align-items: center;\n gap: 6px;\n color: rgba(0, 0, 0, 0.85);\n\n svg {\n flex-shrink: 0;\n color: #615ced;\n opacity: 0.85;\n }\n\n span {\n font-weight: 600;\n font-size: 13px;\n }\n}\n\n// ─── Agent Badge ──────────────────────────────────────────────────────────────\n.agentSelectorSuffix {\n display: flex;\n align-items: center;\n gap: 6px;\n margin-right: 0;\n\n .agentBadge {\n :global {\n .ant-badge-count {\n background: linear-gradient(135deg, #615ced, #8b87f0);\n color: #ffffff;\n font-size: 10px;\n font-weight: 700;\n min-width: 18px;\n height: 18px;\n line-height: 18px;\n border-radius: 9px;\n box-shadow: 0 2px 6px rgba(97, 92, 237, 0.35);\n }\n }\n }\n}\n\n// ─── Dropdown ─────────────────────────────────────────────────────────────────\n.agentSelectorDropdown {\n border-radius: 12px !important;\n overflow: hidden;\n min-width: 280px !important;\n box-shadow:\n 0 8px 32px rgba(0, 0, 0, 0.12),\n 0 2px 8px rgba(0, 0, 0, 0.06) !important;\n :global {\n .copaw-select-item {\n padding: 0 !important;\n border-radius: 8px;\n margin: 3px 6px;\n transition: all 0.15s cubic-bezier(0.4, 0, 0.2, 1);\n\n &:hover {\n background: rgba(97, 92, 237, 0.08) !important;\n }\n\n &.copaw-select-item-option-selected {\n background: rgba(97, 92, 237, 0.05) !important;\n\n .agentOptionIcon {\n background: linear-gradient(135deg, #615ced 0%, #8b87f0 100%);\n border-color: transparent;\n color: #ffffff;\n box-shadow: 0 2px 8px rgba(97, 92, 237, 0.4);\n }\n }\n }\n\n .ant-select-item {\n padding: 0 !important;\n border-radius: 8px;\n margin: 3px 6px;\n transition: all 0.15s cubic-bezier(0.4, 0, 0.2, 1);\n\n &:hover {\n background: rgba(97, 92, 237, 0.08) !important;\n }\n\n &.ant-select-item-option-selected {\n background: rgba(97, 92, 237, 0.05) !important;\n\n .agentOptionIcon {\n background: linear-gradient(135deg, #615ced 0%, #8b87f0 100%);\n border-color: transparent;\n color: #ffffff;\n box-shadow: 0 2px 8px rgba(97, 92, 237, 0.4);\n }\n }\n }\n\n .rc-virtual-list {\n padding: 6px 0;\n }\n }\n}\n\n// ─── Agent Option ─────────────────────────────────────────────────────────────\n.agentOption {\n padding: 10px 14px;\n display: flex;\n flex-direction: column;\n gap: 6px;\n}\n\n.agentOptionHeader {\n display: flex;\n align-items: center;\n gap: 10px;\n}\n\n.agentOptionIcon {\n flex-shrink: 0;\n width: 30px;\n height: 30px;\n display: flex;\n align-items: center;\n justify-content: center;\n background: linear-gradient(135deg, #f5f5ff 0%, #efefff 100%);\n border: 1px solid rgba(97, 92, 237, 0.15);\n border-radius: 8px;\n color: #615ced;\n transition: all 0.2s ease;\n\n .agentOption:hover & {\n background: linear-gradient(135deg, #ebe9ff 0%, #f0efff 100%);\n border-color: rgba(97, 92, 237, 0.3);\n color: #615ced;\n box-shadow: 0 2px 6px rgba(97, 92, 237, 0.15);\n }\n}\n\n.agentOptionContent {\n flex: 1;\n min-width: 0;\n display: flex;\n flex-direction: column;\n gap: 2px;\n}\n\n.agentOptionName {\n display: flex;\n align-items: center;\n gap: 6px;\n font-size: 13px;\n font-weight: 600;\n color: #1a1a2e;\n line-height: 1.4;\n\n span {\n flex: 1;\n overflow: hidden;\n text-overflow: ellipsis;\n white-space: nowrap;\n }\n}\n\n.activeIndicator {\n flex-shrink: 0;\n color: #52c41a;\n animation: fadeIn 0.3s ease;\n}\n\n@keyframes fadeIn {\n from {\n opacity: 0;\n transform: scale(0.8);\n }\n to {\n opacity: 1;\n transform: scale(1);\n }\n}\n\n.agentOptionDescription {\n font-size: 11px;\n color: #8c8c8c;\n line-height: 1.4;\n overflow: hidden;\n text-overflow: ellipsis;\n white-space: nowrap;\n}\n\n.agentOptionId {\n font-size: 10px;\n font-family: \"SF Mono\", \"Consolas\", \"Monaco\", monospace;\n color: rgba(97, 92, 237, 0.4);\n letter-spacing: 0.3px;\n padding-top: 4px;\n border-top: 1px solid rgba(97, 92, 237, 0.06);\n}\n\n// ─── Dark mode overrides ───────────────────────────────────────────────────────\n:global(.dark-mode) {\n .agentSelectorLabel {\n color: rgba(255, 255, 255, 0.55);\n\n svg {\n opacity: 0.7;\n }\n }\n\n .agentSelector {\n :global {\n .ant-select-selector {\n border-color: rgba(139, 135, 240, 0.3) !important;\n background: rgba(97, 92, 237, 0.1) !important;\n\n &:hover {\n border-color: rgba(139, 135, 240, 0.5) !important;\n background: rgba(97, 92, 237, 0.15) !important;\n }\n\n &:focus {\n border-color: #8b87f0 !important;\n background: rgba(97, 92, 237, 0.15) !important;\n box-shadow: 0 0 0 2px rgba(97, 92, 237, 0.25) !important;\n }\n }\n\n .ant-select-arrow {\n color: rgba(139, 135, 240, 0.6);\n }\n\n .ant-select-focused .ant-select-selector {\n border-color: #8b87f0 !important;\n background: rgba(97, 92, 237, 0.15) !important;\n box-shadow: 0 0 0 2px rgba(97, 92, 237, 0.25) !important;\n }\n }\n }\n\n .selectedAgentLabel {\n color: rgba(255, 255, 255, 0.9);\n\n svg {\n color: #b8b5f5;\n opacity: 0.9;\n }\n }\n\n .agentSelectorSuffix {\n .agentBadge {\n :global {\n .ant-badge-count {\n background: linear-gradient(135deg, #615ced, #8b87f0);\n color: #ffffff;\n box-shadow: 0 2px 6px rgba(97, 92, 237, 0.4);\n }\n }\n }\n }\n\n .agentSelectorDropdown {\n box-shadow:\n 0 8px 32px rgba(0, 0, 0, 0.4),\n 0 2px 8px rgba(0, 0, 0, 0.2) !important;\n\n :global {\n .ant-select-item {\n &:hover {\n background: rgba(255, 255, 255, 0.1) !important;\n }\n\n &.ant-select-item-option-selected {\n background: rgba(255, 255, 255, 0.06) !important;\n\n .agentOptionIcon {\n background: linear-gradient(135deg, #615ced 0%, #8b87f0 100%);\n border-color: transparent;\n color: #ffffff;\n box-shadow: 0 2px 8px rgba(97, 92, 237, 0.5);\n }\n }\n }\n }\n }\n\n .agentOptionIcon {\n background: linear-gradient(\n 135deg,\n rgba(97, 92, 237, 0.15) 0%,\n rgba(97, 92, 237, 0.08) 100%\n );\n border-color: rgba(139, 135, 240, 0.2);\n color: #b8b5f5;\n\n .agentOption:hover & {\n background: linear-gradient(\n 135deg,\n rgba(97, 92, 237, 0.3) 0%,\n rgba(97, 92, 237, 0.15) 100%\n );\n border-color: rgba(139, 135, 240, 0.4);\n color: #c5c3f8;\n box-shadow: 0 2px 8px rgba(97, 92, 237, 0.3);\n }\n }\n\n .agentOptionName {\n color: rgba(255, 255, 255, 0.88);\n }\n\n .agentOptionDescription {\n color: rgba(255, 255, 255, 0.4);\n }\n\n .agentOptionId {\n color: rgba(139, 135, 240, 0.45);\n border-top-color: rgba(139, 135, 240, 0.1);\n }\n}\n" }, { "path": "console/src/components/AgentSelector/index.tsx", "content": "import { Select, message, Badge } from \"antd\";\nimport { useEffect, useState } from \"react\";\nimport { Bot, Layers, CheckCircle } from \"lucide-react\";\nimport { useAgentStore } from \"../../stores/agentStore\";\nimport { agentsApi } from \"../../api/modules/agents\";\nimport { useTranslation } from \"react-i18next\";\nimport styles from \"./index.module.less\";\n\nexport default function AgentSelector() {\n const { t } = useTranslation();\n const { selectedAgent, agents, setSelectedAgent, setAgents } =\n useAgentStore();\n const [loading, setLoading] = useState(false);\n\n useEffect(() => {\n loadAgents();\n }, []);\n\n const loadAgents = async () => {\n try {\n setLoading(true);\n const data = await agentsApi.listAgents();\n setAgents(data.agents);\n } catch (error) {\n console.error(\"Failed to load agents:\", error);\n message.error(t(\"agent.loadFailed\"));\n } finally {\n setLoading(false);\n }\n };\n\n const handleChange = (value: string) => {\n setSelectedAgent(value);\n message.success(t(\"agent.switchSuccess\"));\n };\n\n const agentCount = agents.length;\n\n return (\n
\n
\n \n {t(\"agent.currentWorkspace\")}\n
\n \n \n
\n }\n >\n {agents.map((agent) => (\n \n \n {agent.name}\n \n }\n >\n
\n
\n
\n \n
\n
\n
\n {agent.name}\n {agent.id === selectedAgent && (\n \n )}\n
\n {agent.description && (\n
\n {agent.description}\n
\n )}\n
\n
\n
ID: {agent.id}
\n
\n \n ))}\n \n \n );\n}\n" }, { "path": "console/src/components/ConsoleCronBubble/index.module.less", "content": ".wrap {\n position: fixed;\n top: 24px;\n right: 24px;\n z-index: 1000;\n display: flex;\n flex-direction: column;\n gap: 12px;\n max-width: min(400px, calc(100vw - 48px));\n pointer-events: none;\n\n & > * {\n pointer-events: auto;\n }\n}\n\n.bubble {\n display: flex;\n align-items: flex-start;\n gap: 12px;\n padding: 14px 16px;\n background: var(--colorBgElevated, #fff);\n border-radius: 12px;\n box-shadow: 0 4px 16px rgba(0, 0, 0, 0.08);\n border: 1px solid var(--colorBorderSecondary, #f0f0f0);\n}\n\n.icon {\n flex-shrink: 0;\n color: var(--colorPrimary, #1677ff);\n margin-top: 2px;\n}\n\n.text {\n flex: 1;\n margin: 0;\n font-size: 14px;\n line-height: 1.5;\n color: var(--colorText, #333);\n word-break: break-word;\n white-space: pre-wrap;\n max-height: 6em;\n overflow: hidden;\n display: -webkit-box;\n -webkit-box-orient: vertical;\n -webkit-line-clamp: 4;\n line-clamp: 4;\n}\n\n.close {\n flex-shrink: 0;\n padding: 4px;\n border: none;\n background: transparent;\n color: var(--colorTextSecondary, #999);\n cursor: pointer;\n border-radius: 6px;\n display: flex;\n align-items: center;\n justify-content: center;\n\n &:hover {\n color: var(--colorText, #333);\n background: var(--colorFillTertiary, #f5f5f5);\n }\n}\n" }, { "path": "console/src/components/ConsoleCronBubble/index.tsx", "content": "import { useEffect, useRef, useState } from \"react\";\nimport { MessageCircle, X } from \"lucide-react\";\nimport { consoleApi, type PushMessage } from \"../../api/modules/console\";\nimport styles from \"./index.module.less\";\n\nconst POLL_INTERVAL_MS = 2500;\nconst AUTO_DISMISS_MS = 8000;\nconst MAX_SEEN_IDS = 500;\nconst MAX_VISIBLE_BUBBLES = 4;\nconst MAX_NEW_PER_POLL = 2;\nconst TITLE_BLINK_PREFIX = \"\\u2022 \";\n\ninterface BubbleItem extends PushMessage {\n dismissAt: number;\n}\n\nexport default function ConsoleCronBubble() {\n const [items, setItems] = useState([]);\n const pollRef = useRef | null>(null);\n const seenIdsRef = useRef>(new Set());\n const originalTitleRef = useRef(document.title);\n const blinkRef = useRef | null>(null);\n\n const dismiss = (id: string) => {\n setItems((prev) => prev.filter((i) => i.id !== id));\n };\n\n useEffect(() => {\n originalTitleRef.current = document.title;\n }, []);\n\n useEffect(() => {\n const tick = () => {\n consoleApi\n .getPushMessages()\n .then((res) => {\n if (!res?.messages?.length) return;\n const seen = seenIdsRef.current;\n if (seen.size > MAX_SEEN_IDS) seen.clear();\n const newItems: BubbleItem[] = [];\n const now = Date.now();\n for (const m of res.messages) {\n if (seen.has(m.id)) continue;\n seen.add(m.id);\n newItems.push({ ...m, dismissAt: now + AUTO_DISMISS_MS });\n }\n if (newItems.length === 0) return;\n const toAdd = newItems.slice(-MAX_NEW_PER_POLL);\n setItems((prev) => {\n const merged = [...prev, ...toAdd];\n return merged.slice(-MAX_VISIBLE_BUBBLES);\n });\n })\n .catch(() => {});\n };\n\n tick();\n pollRef.current = setInterval(tick, POLL_INTERVAL_MS);\n return () => {\n if (pollRef.current) clearInterval(pollRef.current);\n };\n }, []);\n\n useEffect(() => {\n if (items.length === 0) return;\n const t = setInterval(() => {\n const now = Date.now();\n setItems((prev) => {\n const next = prev.filter((i) => i.dismissAt > now);\n return next.length === prev.length ? prev : next;\n });\n }, 500);\n return () => clearInterval(t);\n }, [items.length]);\n\n useEffect(() => {\n if (items.length === 0 || !document.hidden || blinkRef.current) return;\n const original = originalTitleRef.current;\n let showPrefix = true;\n blinkRef.current = setInterval(() => {\n document.title = showPrefix\n ? `${TITLE_BLINK_PREFIX}${original}`\n : original;\n showPrefix = !showPrefix;\n }, 800);\n return () => {\n if (blinkRef.current) {\n clearInterval(blinkRef.current);\n blinkRef.current = null;\n }\n document.title = original;\n };\n }, [items.length]);\n\n useEffect(() => {\n const onVisibility = () => {\n if (document.visibilityState === \"visible\") {\n if (blinkRef.current) {\n clearInterval(blinkRef.current);\n blinkRef.current = null;\n }\n document.title = originalTitleRef.current;\n }\n };\n document.addEventListener(\"visibilitychange\", onVisibility);\n return () => document.removeEventListener(\"visibilitychange\", onVisibility);\n }, []);\n\n if (items.length === 0) return null;\n\n return (\n
\n {items.map((item) => (\n
\n \n

\n {item.text}\n

\n dismiss(item.id)}\n aria-label=\"Close\"\n >\n \n \n
\n ))}\n
\n );\n}\n" }, { "path": "console/src/components/LanguageSwitcher.tsx", "content": "import { Dropdown, Button } from \"@agentscope-ai/design\";\nimport { GlobalOutlined } from \"@ant-design/icons\";\nimport { useTranslation } from \"react-i18next\";\nimport type { MenuProps } from \"antd\";\n\nexport default function LanguageSwitcher() {\n const { i18n } = useTranslation();\n\n const currentLanguage = i18n.resolvedLanguage || i18n.language;\n\n const changeLanguage = (lang: string) => {\n i18n.changeLanguage(lang);\n localStorage.setItem(\"language\", lang);\n };\n\n const items: MenuProps[\"items\"] = [\n {\n key: \"en\",\n label: \"English\",\n onClick: () => changeLanguage(\"en\"),\n },\n {\n key: \"ru\",\n label: \"Русский\",\n onClick: () => changeLanguage(\"ru\"),\n },\n {\n key: \"zh\",\n label: \"简体中文\",\n onClick: () => changeLanguage(\"zh\"),\n },\n {\n key: \"ja\",\n label: \"日本語\",\n onClick: () => changeLanguage(\"ja\"),\n },\n ];\n\n const languageLabels: Record = {\n en: \"English\",\n ru: \"Русский\",\n zh: \"简体中文\",\n ja: \"日本語\",\n };\n\n const currentLabel = languageLabels[currentLanguage] ?? \"English\";\n\n return (\n \n \n \n );\n}\n" }, { "path": "console/src/components/MarkdownCopy/MarkdownCopy.tsx", "content": "import { useState, useEffect, useMemo } from \"react\";\nimport { Button, message, Switch, Input } from \"@agentscope-ai/design\";\nimport { CopyOutlined } from \"@ant-design/icons\";\nimport { XMarkdown } from \"@ant-design/x-markdown\";\nimport { useTranslation } from \"react-i18next\";\nimport type { CSSProperties } from \"react\";\nimport { stripFrontmatter } from \"../../utils/markdown\";\nimport styles from \"./index.module.less\";\n\ninterface MarkdownCopyProps {\n content: string;\n showMarkdown?: boolean;\n onShowMarkdownChange?: (show: boolean) => void;\n copyButtonProps?: {\n type?:\n | \"text\"\n | \"link\"\n | \"default\"\n | \"primary\"\n | \"dashed\"\n | \"primaryLess\"\n | \"textCompact\"\n | undefined;\n size?: \"small\" | \"middle\" | \"large\" | undefined;\n style?: CSSProperties;\n };\n markdownViewerProps?: {\n style?: CSSProperties;\n className?: string;\n };\n textareaProps?: {\n rows?: number;\n placeholder?: string;\n disabled?: boolean;\n style?: CSSProperties;\n className?: string;\n };\n showControls?: boolean;\n editable?: boolean;\n onContentChange?: (content: string) => void;\n}\n\nexport function MarkdownCopy({\n content,\n showMarkdown = true,\n onShowMarkdownChange,\n copyButtonProps = {},\n markdownViewerProps = {},\n textareaProps = {},\n showControls = true,\n editable = false,\n onContentChange,\n}: MarkdownCopyProps) {\n const { t } = useTranslation();\n const [isCopying, setIsCopying] = useState(false);\n const [editContent, setEditContent] = useState(content);\n const [localShowMarkdown, setLocalShowMarkdown] = useState(showMarkdown);\n const markdownContent = useMemo(\n () => stripFrontmatter(content || \"\"),\n [content],\n );\n\n useEffect(() => {\n setEditContent(content);\n }, [content]);\n\n useEffect(() => {\n if (editable && !textareaProps.disabled) {\n setLocalShowMarkdown(false);\n } else {\n setLocalShowMarkdown(showMarkdown);\n }\n }, [editable, textareaProps.disabled, showMarkdown]);\n\n const copyToClipboard = async () => {\n const contentToCopy =\n localShowMarkdown && !(editable && !textareaProps.disabled)\n ? content\n : editable\n ? editContent\n : content;\n\n if (!contentToCopy) return;\n\n setIsCopying(true);\n try {\n if (navigator.clipboard && window.isSecureContext) {\n await navigator.clipboard.writeText(contentToCopy);\n message.success(t(\"common.copied\"));\n } else {\n const textArea = document.createElement(\"textarea\");\n textArea.value = contentToCopy;\n textArea.style.position = \"fixed\";\n textArea.style.left = \"-999999px\";\n textArea.style.top = \"-999999px\";\n document.body.appendChild(textArea);\n textArea.focus();\n textArea.select();\n document.execCommand(\"copy\");\n textArea.remove();\n message.success(t(\"common.copied\"));\n }\n } catch (err) {\n console.error(\"Failed to copy text: \", err);\n message.error(t(\"common.copyFailed\"));\n } finally {\n setIsCopying(false);\n }\n };\n\n const handleContentChange = (e: React.ChangeEvent) => {\n const newContent = e.target.value;\n setEditContent(newContent);\n if (onContentChange) {\n onContentChange(newContent);\n }\n };\n\n const handleShowMarkdownChange = (show: boolean) => {\n setLocalShowMarkdown(show);\n if (onShowMarkdownChange) {\n onShowMarkdownChange(show);\n }\n };\n\n const defaultCopyButtonProps = {\n type: \"text\" as const,\n size: \"small\" as const,\n ...copyButtonProps,\n };\n\n const defaultMarkdownViewerProps = {\n style: {\n padding: 16,\n height: \"100%\",\n overflow: \"auto\",\n backgroundColor: \"#fff\",\n borderRadius: 6,\n ...markdownViewerProps.style,\n },\n ...markdownViewerProps,\n };\n\n const defaultTextareaProps = {\n rows: 12,\n placeholder: t(\"common.contentPlaceholder\"),\n ...textareaProps,\n };\n\n return (\n
\n {showControls && (\n
\n
{t(\"common.content\")}
\n
\n
\n {t(\"common.preview\")}\n \n
\n }\n {...defaultCopyButtonProps}\n onClick={copyToClipboard}\n loading={isCopying}\n />\n
\n
\n )}\n\n {localShowMarkdown ? (\n
\n \n
\n ) : (\n
\n \n
\n )}\n
\n );\n}\n" }, { "path": "console/src/components/MarkdownCopy/index.module.less", "content": ".markdownCopy {\n display: flex;\n flex-direction: column;\n height: 100%;\n}\n\n.controls {\n display: flex;\n justify-content: space-between;\n align-items: center;\n margin-bottom: 8px;\n font-size: 12px;\n font-weight: 600;\n height: 20px;\n}\n\n.controlGroup {\n display: flex;\n align-items: center;\n gap: 8px;\n}\n\n.previewToggle {\n display: flex;\n align-items: center;\n gap: 8px;\n}\n\n.previewLabel {\n font-size: 12px;\n color: #666;\n white-space: nowrap;\n}\n\n.markdownViewer {\n flex: 1;\n min-height: 300px;\n max-height: 300px;\n overflow: auto;\n border: 1px solid #d9d9d9;\n border-radius: 6px;\n background-color: #fff;\n}\n\n.textareaContainer {\n flex: 1;\n display: flex;\n flex-direction: column;\n}\n\n.textarea {\n font-family: monospace;\n font-size: 13px;\n resize: vertical;\n height: min(100%, clamp(280px, 50vh, 640px));\n min-height: min(240px, 100%);\n max-height: 100%;\n padding: 12px;\n border: 1px solid #d9d9d9;\n border-radius: 6px;\n}\n" }, { "path": "console/src/components/PageHeader/index.tsx", "content": "" }, { "path": "console/src/components/ThemeToggleButton/index.module.less", "content": "/* ---- Theme toggle button ---- */\n.toggleBtn {\n display: inline-flex;\n align-items: center;\n justify-content: center;\n height: 32px;\n border: none;\n border-radius: 8px;\n background: transparent;\n cursor: pointer;\n transition:\n background 0.15s ease,\n color 0.15s ease;\n color: #555;\n padding: 0;\n flex-shrink: 0;\n\n &:hover {\n background: rgba(97, 92, 237, 0.08);\n color: #615ced;\n }\n}\n\n.icon {\n font-size: 16px;\n}\n\n/* Dark mode overrides */\n:global(.dark-mode) .toggleBtn {\n color: #ccc;\n\n &:hover {\n background: rgba(255, 255, 255, 0.1);\n color: #fff;\n }\n}\n" }, { "path": "console/src/components/ThemeToggleButton/index.tsx", "content": "import { Tooltip, Button } from \"antd\";\nimport { SunOutlined, MoonOutlined } from \"@ant-design/icons\";\nimport { useTheme } from \"../../contexts/ThemeContext\";\nimport { useTranslation } from \"react-i18next\";\nimport styles from \"./index.module.less\";\n\n/**\n * ThemeToggleButton - toggles between light and dark theme.\n * Displays a sun icon in dark mode and a moon icon in light mode.\n */\nexport default function ThemeToggleButton() {\n const { isDark, toggleTheme } = useTheme();\n const { t } = useTranslation();\n\n return (\n \n : }\n >\n {t(isDark ? \"theme.light\" : \"theme.dark\")}\n \n \n );\n}\n" }, { "path": "console/src/constants/timezone.ts", "content": "export const TIMEZONE_OPTIONS = [\n { value: \"America/Los_Angeles\", label: \"America/Los_Angeles (UTC-8)\" },\n { value: \"America/Denver\", label: \"America/Denver (UTC-7)\" },\n { value: \"America/Chicago\", label: \"America/Chicago (UTC-6)\" },\n { value: \"America/New_York\", label: \"America/New_York (UTC-5)\" },\n { value: \"America/Toronto\", label: \"America/Toronto (UTC-5)\" },\n { value: \"UTC\", label: \"UTC\" },\n { value: \"Europe/London\", label: \"Europe/London (UTC+0)\" },\n { value: \"Europe/Paris\", label: \"Europe/Paris (UTC+1)\" },\n { value: \"Europe/Berlin\", label: \"Europe/Berlin (UTC+1)\" },\n { value: \"Europe/Moscow\", label: \"Europe/Moscow (UTC+3)\" },\n { value: \"Asia/Dubai\", label: \"Asia/Dubai (UTC+4)\" },\n { value: \"Asia/Shanghai\", label: \"Asia/Shanghai (UTC+8)\" },\n { value: \"Asia/Hong_Kong\", label: \"Asia/Hong_Kong (UTC+8)\" },\n { value: \"Asia/Singapore\", label: \"Asia/Singapore (UTC+8)\" },\n { value: \"Asia/Tokyo\", label: \"Asia/Tokyo (UTC+9)\" },\n { value: \"Asia/Seoul\", label: \"Asia/Seoul (UTC+9)\" },\n { value: \"Australia/Sydney\", label: \"Australia/Sydney (UTC+10)\" },\n { value: \"Australia/Melbourne\", label: \"Australia/Melbourne (UTC+10)\" },\n { value: \"Pacific/Auckland\", label: \"Pacific/Auckland (UTC+12)\" },\n];\n" }, { "path": "console/src/contexts/ThemeContext.tsx", "content": "import {\n createContext,\n useContext,\n useEffect,\n useState,\n useCallback,\n type ReactNode,\n} from \"react\";\n\nexport type ThemeMode = \"light\" | \"dark\" | \"system\";\nexport type ResolvedTheme = \"light\" | \"dark\";\n\nconst STORAGE_KEY = \"copaw-theme\";\n\ninterface ThemeContextValue {\n /** User selected preference: light / dark / system */\n themeMode: ThemeMode;\n /** Resolved final theme after applying system preference */\n isDark: boolean;\n setThemeMode: (mode: ThemeMode) => void;\n /** Convenience toggle: light ↔ dark (skips system) */\n toggleTheme: () => void;\n}\n\nconst ThemeContext = createContext({\n themeMode: \"light\",\n isDark: false,\n setThemeMode: () => {},\n toggleTheme: () => {},\n});\n\nfunction getInitialMode(): ThemeMode {\n try {\n const stored = localStorage.getItem(STORAGE_KEY);\n if (stored === \"light\" || stored === \"dark\" || stored === \"system\") {\n return stored;\n }\n } catch {\n // ignore storage errors\n }\n return \"system\";\n}\n\nfunction resolveIsDark(mode: ThemeMode): boolean {\n if (mode === \"dark\") return true;\n if (mode === \"light\") return false;\n // system\n return window.matchMedia?.(\"(prefers-color-scheme: dark)\").matches ?? false;\n}\n\nexport function ThemeProvider({ children }: { children: ReactNode }) {\n const [themeMode, setThemeModeState] = useState(getInitialMode);\n const [isDark, setIsDark] = useState(() =>\n resolveIsDark(getInitialMode()),\n );\n\n // Apply dark/light class to element for global CSS variable overrides\n useEffect(() => {\n const html = document.documentElement;\n if (isDark) {\n html.classList.add(\"dark-mode\");\n } else {\n html.classList.remove(\"dark-mode\");\n }\n }, [isDark]);\n\n // Listen to system theme changes when mode is \"system\"\n useEffect(() => {\n if (themeMode !== \"system\") return;\n\n const mq = window.matchMedia(\"(prefers-color-scheme: dark)\");\n const handler = (e: MediaQueryListEvent) => {\n setIsDark(e.matches);\n };\n mq.addEventListener(\"change\", handler);\n return () => mq.removeEventListener(\"change\", handler);\n }, [themeMode]);\n\n const setThemeMode = useCallback((mode: ThemeMode) => {\n setThemeModeState(mode);\n setIsDark(resolveIsDark(mode));\n try {\n localStorage.setItem(STORAGE_KEY, mode);\n } catch {\n // ignore\n }\n }, []);\n\n const toggleTheme = useCallback(() => {\n setThemeMode(isDark ? \"light\" : \"dark\");\n }, [isDark, setThemeMode]);\n\n return (\n \n {children}\n \n );\n}\n\nexport function useTheme(): ThemeContextValue {\n return useContext(ThemeContext);\n}\n" }, { "path": "console/src/i18n.ts", "content": "import i18n from \"i18next\";\nimport { initReactI18next } from \"react-i18next\";\nimport en from \"./locales/en.json\";\nimport ru from \"./locales/ru.json\";\nimport zh from \"./locales/zh.json\";\nimport ja from \"./locales/ja.json\";\nconst resources = {\n en: {\n translation: en,\n },\n ru: {\n translation: ru,\n },\n zh: {\n translation: zh,\n },\n ja: {\n translation: ja,\n },\n};\n\ni18n.use(initReactI18next).init({\n resources,\n lng: localStorage.getItem(\"language\") || \"en\",\n fallbackLng: \"en\",\n interpolation: {\n escapeValue: false,\n },\n});\n\nexport default i18n;\n" }, { "path": "console/src/layouts/Header.tsx", "content": "import { Layout, Space } from \"antd\";\nimport LanguageSwitcher from \"../components/LanguageSwitcher\";\nimport ThemeToggleButton from \"../components/ThemeToggleButton\";\nimport AgentSelector from \"../components/AgentSelector\";\nimport { useTranslation } from \"react-i18next\";\nimport {\n FileTextOutlined,\n BookOutlined,\n QuestionCircleOutlined,\n GithubOutlined,\n} from \"@ant-design/icons\";\nimport { Button, Tooltip } from \"@agentscope-ai/design\";\nimport styles from \"./index.module.less\";\nimport {\n GITHUB_URL,\n KEY_TO_LABEL,\n getDocsUrl,\n getFaqUrl,\n getReleaseNotesUrl,\n} from \"./constants\";\n\nconst { Header: AntHeader } = Layout;\n\ninterface HeaderProps {\n selectedKey: string;\n}\n\nexport default function Header({ selectedKey }: HeaderProps) {\n const { t, i18n } = useTranslation();\n\n const handleNavClick = (url: string) => {\n if (url) {\n const pywebview = (window as any).pywebview;\n if (pywebview?.api) {\n pywebview.api.open_external_link(url);\n } else {\n window.open(url, \"_blank\");\n }\n }\n };\n\n return (\n \n \n {t(KEY_TO_LABEL[selectedKey] || \"nav.chat\")}\n \n \n \n \n }\n type=\"text\"\n onClick={() => handleNavClick(getReleaseNotesUrl(i18n.language))}\n >\n {t(\"header.changelog\")}\n \n \n \n }\n type=\"text\"\n onClick={() => handleNavClick(getDocsUrl(i18n.language))}\n >\n {t(\"header.docs\")}\n \n \n \n }\n type=\"text\"\n onClick={() => handleNavClick(getFaqUrl(i18n.language))}\n >\n {t(\"header.faq\")}\n \n \n \n }\n type=\"text\"\n onClick={() => handleNavClick(GITHUB_URL)}\n >\n {t(\"header.github\")}\n \n \n \n \n \n \n );\n}\n" }, { "path": "console/src/layouts/MainLayout/index.tsx", "content": "import { Layout } from \"antd\";\nimport { Routes, Route, useLocation, Navigate } from \"react-router-dom\";\nimport Sidebar from \"../Sidebar\";\nimport Header from \"../Header\";\nimport ConsoleCronBubble from \"../../components/ConsoleCronBubble\";\nimport styles from \"../index.module.less\";\nimport Chat from \"../../pages/Chat\";\nimport ChannelsPage from \"../../pages/Control/Channels\";\nimport SessionsPage from \"../../pages/Control/Sessions\";\nimport CronJobsPage from \"../../pages/Control/CronJobs\";\nimport HeartbeatPage from \"../../pages/Control/Heartbeat\";\nimport AgentConfigPage from \"../../pages/Agent/Config\";\nimport SkillsPage from \"../../pages/Agent/Skills\";\nimport ToolsPage from \"../../pages/Agent/Tools\";\nimport WorkspacePage from \"../../pages/Agent/Workspace\";\nimport MCPPage from \"../../pages/Agent/MCP\";\nimport ModelsPage from \"../../pages/Settings/Models\";\nimport EnvironmentsPage from \"../../pages/Settings/Environments\";\nimport SecurityPage from \"../../pages/Settings/Security\";\nimport TokenUsagePage from \"../../pages/Settings/TokenUsage\";\nimport VoiceTranscriptionPage from \"../../pages/Settings/VoiceTranscription\";\nimport AgentsPage from \"../../pages/Settings/Agents\";\n\nconst { Content } = Layout;\n\nconst pathToKey: Record = {\n \"/chat\": \"chat\",\n \"/channels\": \"channels\",\n \"/sessions\": \"sessions\",\n \"/cron-jobs\": \"cron-jobs\",\n \"/heartbeat\": \"heartbeat\",\n \"/skills\": \"skills\",\n \"/tools\": \"tools\",\n \"/mcp\": \"mcp\",\n \"/workspace\": \"workspace\",\n \"/agents\": \"agents\",\n \"/models\": \"models\",\n \"/environments\": \"environments\",\n \"/agent-config\": \"agent-config\",\n \"/security\": \"security\",\n \"/token-usage\": \"token-usage\",\n \"/voice-transcription\": \"voice-transcription\",\n};\n\nexport default function MainLayout() {\n const location = useLocation();\n const currentPath = location.pathname;\n const selectedKey = pathToKey[currentPath] || \"chat\";\n\n return (\n \n \n \n
\n \n \n
\n \n } />\n } />\n } />\n } />\n } />\n } />\n } />\n } />\n } />\n } />\n } />\n } />\n } />\n } />\n } />\n } />\n }\n />\n \n
\n \n \n \n );\n}\n" }, { "path": "console/src/layouts/Sidebar.tsx", "content": "import {\n Layout,\n Menu,\n Button,\n Badge,\n Modal,\n Spin,\n Tooltip,\n type MenuProps,\n} from \"antd\";\nimport { useState, useEffect, useCallback } from \"react\";\nimport { useNavigate } from \"react-router-dom\";\nimport { useTranslation } from \"react-i18next\";\nimport ReactMarkdown from \"react-markdown\";\nimport remarkGfm from \"remark-gfm\";\nimport {\n MessageSquare,\n Radio,\n Zap,\n MessageCircle,\n Wifi,\n UsersRound,\n CalendarClock,\n Activity,\n Sparkles,\n Briefcase,\n Cpu,\n Box,\n Globe,\n Settings,\n Shield,\n Plug,\n Wrench,\n PanelLeftClose,\n PanelLeftOpen,\n Copy,\n Check,\n BarChart3,\n Mic,\n Bot,\n LogOut,\n} from \"lucide-react\";\nimport api from \"../api\";\nimport { clearAuthToken } from \"../api/config\";\nimport { authApi } from \"../api/modules/auth\";\nimport styles from \"./index.module.less\";\nimport { useTheme } from \"../contexts/ThemeContext\";\nimport {\n PYPI_URL,\n ONE_HOUR_MS,\n DEFAULT_OPEN_KEYS,\n KEY_TO_PATH,\n UPDATE_MD,\n isStableVersion,\n compareVersions,\n} from \"./constants\";\n\n// ── Layout ────────────────────────────────────────────────────────────────\n\nconst { Sider } = Layout;\n\n// ── Types ─────────────────────────────────────────────────────────────────\n\ninterface SidebarProps {\n selectedKey: string;\n}\n\n// ── CopyButton ────────────────────────────────────────────────────────────\n\nfunction CopyButton({ text }: { text: string }) {\n const [copied, setCopied] = useState(false);\n const { t } = useTranslation();\n\n const handleCopy = useCallback(() => {\n navigator.clipboard.writeText(text).then(() => {\n setCopied(true);\n setTimeout(() => setCopied(false), 2000);\n });\n }, [text]);\n\n return (\n \n : }\n onClick={handleCopy}\n className={`${styles.copyBtn} ${\n copied ? styles.copyBtnCopied : styles.copyBtnDefault\n }`}\n />\n \n );\n}\n\n// ── Sidebar ───────────────────────────────────────────────────────────────\n\nexport default function Sidebar({ selectedKey }: SidebarProps) {\n const navigate = useNavigate();\n const { t, i18n } = useTranslation();\n const { isDark } = useTheme();\n const [collapsed, setCollapsed] = useState(false);\n const [openKeys, setOpenKeys] = useState(DEFAULT_OPEN_KEYS);\n const [version, setVersion] = useState(\"\");\n const [latestVersion, setLatestVersion] = useState(\"\");\n const [updateModalOpen, setUpdateModalOpen] = useState(false);\n const [updateMarkdown, setUpdateMarkdown] = useState(\"\");\n const [authEnabled, setAuthEnabled] = useState(false);\n\n // ── Effects ──────────────────────────────────────────────────────────────\n\n useEffect(() => {\n authApi\n .getStatus()\n .then((res) => setAuthEnabled(res.enabled))\n .catch(() => {});\n }, []);\n\n useEffect(() => {\n if (!collapsed) setOpenKeys(DEFAULT_OPEN_KEYS);\n }, [collapsed]);\n\n useEffect(() => {\n api\n .getVersion()\n .then((res) => setVersion(res?.version ?? \"\"))\n .catch(() => {});\n }, []);\n\n useEffect(() => {\n fetch(PYPI_URL)\n .then((res) => res.json())\n .then((data) => {\n const releases = data?.releases ?? {};\n\n // Build stable/post versions list with their latest upload time.\n const versionsWithTime = Object.entries(releases)\n .filter(([v]) => isStableVersion(v))\n .map(([v, files]) => {\n const fileList = files as Array<{ upload_time_iso_8601?: string }>;\n const latestUpload = fileList\n .map((f) => f.upload_time_iso_8601)\n .filter(Boolean)\n .sort()\n .pop();\n return { version: v, uploadTime: latestUpload || \"\" };\n });\n\n // Sort by upload time (newest first); break ties by semantic version.\n versionsWithTime.sort((a, b) => {\n const timeDiff =\n new Date(b.uploadTime).getTime() - new Date(a.uploadTime).getTime();\n return timeDiff !== 0\n ? timeDiff\n : compareVersions(b.version, a.version);\n });\n\n const versions = versionsWithTime.map((v) => v.version);\n // latest = most recently uploaded stable/post release\n const latest = versions[0] ?? data?.info?.version ?? \"\";\n\n // Only notify once the latest version is older than 1 hour,\n // giving Docker images time to build and become available.\n const releaseTime = versionsWithTime.find((v) => v.version === latest)\n ?.uploadTime;\n const isOldEnough =\n !!releaseTime &&\n new Date(releaseTime) <= new Date(Date.now() - ONE_HOUR_MS);\n\n if (isOldEnough) {\n setLatestVersion(latest);\n } else {\n setLatestVersion(\"\");\n }\n })\n .catch(() => {});\n }, []);\n\n // ── Derived state ─────────────────────────────────────────────────────────\n\n // Show update notification only when latestVersion is strictly newer than current version.\n const hasUpdate =\n !!version && !!latestVersion && compareVersions(latestVersion, version) > 0;\n\n // ── Handlers ──────────────────────────────────────────────────────────────\n\n const handleOpenUpdateModal = () => {\n setUpdateMarkdown(\"\");\n setUpdateModalOpen(true);\n const lang = i18n.language?.startsWith(\"zh\")\n ? \"zh\"\n : i18n.language?.startsWith(\"ru\")\n ? \"ru\"\n : \"en\";\n const faqLang = lang === \"zh\" ? \"zh\" : \"en\";\n const url = `https://copaw.agentscope.io/docs/faq.${faqLang}.md`;\n fetch(url, { cache: \"no-cache\" })\n .then((res) => (res.ok ? res.text() : Promise.reject()))\n .then((text) => {\n const zhPattern = /###\\s*CoPaw如何更新[\\s\\S]*?(?=\\n###|$)/;\n const enPattern = /###\\s*How to update CoPaw[\\s\\S]*?(?=\\n###|$)/;\n const match = text.match(faqLang === \"zh\" ? zhPattern : enPattern);\n setUpdateMarkdown(\n match && lang !== \"ru\"\n ? match[0].trim()\n : UPDATE_MD[lang] ?? UPDATE_MD.en,\n );\n })\n .catch(() => {\n setUpdateMarkdown(UPDATE_MD[lang] ?? UPDATE_MD.en);\n });\n };\n\n // ── Menu items ────────────────────────────────────────────────────────────\n\n const menuItems: MenuProps[\"items\"] = [\n {\n key: \"chat-group\",\n label: t(\"nav.chat\"),\n icon: ,\n children: [\n {\n key: \"chat\",\n label: t(\"nav.chat\"),\n icon: ,\n },\n ],\n },\n {\n key: \"control-group\",\n label: t(\"nav.control\"),\n icon: ,\n children: [\n { key: \"channels\", label: t(\"nav.channels\"), icon: },\n {\n key: \"sessions\",\n label: t(\"nav.sessions\"),\n icon: ,\n },\n {\n key: \"cron-jobs\",\n label: t(\"nav.cronJobs\"),\n icon: ,\n },\n {\n key: \"heartbeat\",\n label: t(\"nav.heartbeat\"),\n icon: ,\n },\n ],\n },\n {\n key: \"agent-group\",\n label: t(\"nav.agent\"),\n icon: ,\n children: [\n {\n key: \"workspace\",\n label: t(\"nav.workspace\"),\n icon: ,\n },\n { key: \"skills\", label: t(\"nav.skills\"), icon: },\n { key: \"tools\", label: t(\"nav.tools\"), icon: },\n { key: \"mcp\", label: t(\"nav.mcp\"), icon: },\n {\n key: \"agent-config\",\n label: t(\"nav.agentConfig\"),\n icon: ,\n },\n ],\n },\n {\n key: \"settings-group\",\n label: t(\"nav.settings\"),\n icon: ,\n children: [\n { key: \"agents\", label: t(\"nav.agents\"), icon: },\n { key: \"models\", label: t(\"nav.models\"), icon: },\n {\n key: \"environments\",\n label: t(\"nav.environments\"),\n icon: ,\n },\n {\n key: \"security\",\n label: t(\"nav.security\"),\n icon: ,\n },\n {\n key: \"token-usage\",\n label: t(\"nav.tokenUsage\"),\n icon: ,\n },\n {\n key: \"voice-transcription\",\n label: t(\"nav.voiceTranscription\"),\n icon: ,\n },\n ],\n },\n ];\n\n // ── Render ────────────────────────────────────────────────────────────────\n\n return (\n \n
\n {!collapsed && (\n
\n \n {version && (\n \n hasUpdate && handleOpenUpdateModal()}\n >\n v{version}\n \n \n )}\n
\n )}\n \n ) : (\n \n )\n }\n onClick={() => setCollapsed(!collapsed)}\n className={styles.collapseBtn}\n />\n
\n\n setOpenKeys(keys as string[])}\n onClick={({ key }) => {\n const path = KEY_TO_PATH[String(key)];\n if (path) navigate(path);\n }}\n items={menuItems}\n theme={isDark ? \"dark\" : \"light\"}\n />\n\n {authEnabled && (\n
\n }\n onClick={() => {\n clearAuthToken();\n window.location.href = \"/login\";\n }}\n block\n style={{\n display: \"flex\",\n alignItems: \"center\",\n gap: 8,\n justifyContent: collapsed ? \"center\" : \"flex-start\",\n }}\n >\n {!collapsed && t(\"login.logout\")}\n \n
\n )}\n\n setUpdateModalOpen(false)}\n title={\n

\n {t(\"sidebar.updateModal.title\", { version: latestVersion })}\n

\n }\n width={680}\n footer={[\n {\n const websiteLang = i18n.language?.startsWith(\"zh\") ? \"zh\" : \"en\";\n window.open(\n `https://copaw.agentscope.io/release-notes?lang=${websiteLang}`,\n \"_blank\",\n );\n }}\n className={styles.updateModalPrimaryBtn}\n >\n {t(\"sidebar.updateModal.viewReleases\")}\n ,\n ,\n ]}\n >\n
\n {!updateMarkdown ? (\n
\n \n
\n ) : (\n \n \n \n {children}\n \n \n );\n }\n return (\n \n {children}\n \n );\n },\n }}\n >\n {updateMarkdown}\n \n )}\n
\n \n \n );\n}\n" }, { "path": "console/src/layouts/constants.ts", "content": "// ── URLs ──────────────────────────────────────────────────────────────────\n\nexport const PYPI_URL = \"https://pypi.org/pypi/copaw/json\";\n\nexport const GITHUB_URL = \"https://github.com/agentscope-ai/CoPaw\" as const;\n\n// ── Timing ────────────────────────────────────────────────────────────────\n\nexport const ONE_HOUR_MS = 60 * 60 * 1000;\n\n// ── Navigation ────────────────────────────────────────────────────────────\n\nexport const DEFAULT_OPEN_KEYS = [\n \"chat-group\",\n \"control-group\",\n \"agent-group\",\n \"settings-group\",\n];\n\nexport const KEY_TO_PATH: Record = {\n chat: \"/chat\",\n channels: \"/channels\",\n sessions: \"/sessions\",\n \"cron-jobs\": \"/cron-jobs\",\n heartbeat: \"/heartbeat\",\n skills: \"/skills\",\n tools: \"/tools\",\n mcp: \"/mcp\",\n workspace: \"/workspace\",\n agents: \"/agents\",\n models: \"/models\",\n environments: \"/environments\",\n \"agent-config\": \"/agent-config\",\n security: \"/security\",\n \"token-usage\": \"/token-usage\",\n \"voice-transcription\": \"/voice-transcription\",\n};\n\nexport const KEY_TO_LABEL: Record = {\n chat: \"nav.chat\",\n channels: \"nav.channels\",\n sessions: \"nav.sessions\",\n \"cron-jobs\": \"nav.cronJobs\",\n heartbeat: \"nav.heartbeat\",\n skills: \"nav.skills\",\n tools: \"nav.tools\",\n mcp: \"nav.mcp\",\n \"agent-config\": \"nav.agentConfig\",\n workspace: \"nav.workspace\",\n models: \"nav.models\",\n environments: \"nav.environments\",\n security: \"nav.security\",\n \"token-usage\": \"nav.tokenUsage\",\n agents: \"nav.agents\",\n};\n\n// ── URL helpers ───────────────────────────────────────────────────────────\n\nexport const getWebsiteLang = (lang: string): string =>\n lang.startsWith(\"zh\") ? \"zh\" : \"en\";\n\nexport const getDocsUrl = (lang: string): string =>\n `https://copaw.agentscope.io/docs/intro?lang=${getWebsiteLang(lang)}`;\n\nexport const getFaqUrl = (lang: string): string =>\n `https://copaw.agentscope.io/docs/faq?lang=${getWebsiteLang(lang)}`;\n\nexport const getReleaseNotesUrl = (lang: string): string =>\n `https://copaw.agentscope.io/release-notes?lang=${getWebsiteLang(lang)}`;\n\n// ── Version helpers ────────────────────────────────────────────────────────\n\n// Filter out pre-release versions; post-releases are treated as stable.\n// PEP 440 pre-release suffixes: aN / bN / rcN (or cN) / devN.\nexport const isStableVersion = (v: string): boolean =>\n !/(\\d)(a|alpha|b|beta|rc|c|dev)\\d*/i.test(v);\n\n// Compare two PEP 440 version strings. Returns >0 if a>b, <0 if a 1.0.0).\nexport const compareVersions = (a: string, b: string): number => {\n const normalise = (v: string) =>\n v\n .replace(/\\.post(\\d+)/i, \".$1\")\n .split(/[.\\-]/)\n .map((seg) => (isNaN(Number(seg)) ? 0 : Number(seg)));\n const aN = normalise(a);\n const bN = normalise(b);\n const len = Math.max(aN.length, bN.length);\n for (let i = 0; i < len; i++) {\n const diff = (aN[i] ?? 0) - (bN[i] ?? 0);\n if (diff !== 0) return diff;\n }\n return 0;\n};\n\n// ── Update markdown ───────────────────────────────────────────────────────\n\nexport const UPDATE_MD: Record = {\n zh: `### CoPaw如何更新\n\n要更新 CoPaw 到最新版本，可根据你的安装方式选择对应方法：\n\n1. 如果你使用的是一键安装脚本，直接重新运行安装命令即可自动升级。\n\n2. 如果你是通过 pip 安装，在终端中执行以下命令升级：\n\n\\`\\`\\`\npip install --upgrade copaw\n\\`\\`\\`\n\n3. 如果你是从源码安装，进入项目目录并拉取最新代码后重新安装：\n\n\\`\\`\\`\ncd CoPaw\ngit pull origin main\npip install -e .\n\\`\\`\\`\n\n4. 如果你使用的是 Docker，拉取最新镜像并重启容器：\n\n\\`\\`\\`\ndocker pull agentscope/copaw:latest\ndocker run -p 127.0.0.1:8088:8088 -v copaw-data:/app/working agentscope/copaw:latest\n\\`\\`\\`\n\n升级后重启服务 copaw app。`,\n\n ru: `### Как обновить CoPaw\n\nЧтобы обновить CoPaw, выберите способ в зависимости от типа установки:\n\n1. Если вы устанавливали через однострочный скрипт, повторно запустите установщик для обновления.\n\n2. Если устанавливали через pip, выполните:\n\n\\`\\`\\`\npip install --upgrade copaw\n\\`\\`\\`\n\n3. Если устанавливали из исходников, получите последние изменения и переустановите:\n\n\\`\\`\\`\ncd CoPaw\ngit pull origin main\npip install -e .\n\\`\\`\\`\n\n4. Если используете Docker, загрузите новый образ и перезапустите контейнер:\n\n\\`\\`\\`\ndocker pull agentscope/copaw:latest\ndocker run -p 127.0.0.1:8088:8088 -v copaw-data:/app/working agentscope/copaw:latest\n\\`\\`\\`\n\nПосле обновления перезапустите сервис с помощью \\`copaw app\\`.`,\n\n en: `### How to update CoPaw\n\nTo update CoPaw, use the method matching your installation type:\n\n1. If installed via one-line script, re-run the installer to upgrade.\n\n2. If installed via pip, run:\n\n\\`\\`\\`\npip install --upgrade copaw\n\\`\\`\\`\n\n3. If installed from source, pull the latest code and reinstall:\n\n\\`\\`\\`\ncd CoPaw\ngit pull origin main\npip install -e .\n\\`\\`\\`\n\n4. If using Docker, pull the latest image and restart the container:\n\n\\`\\`\\`\ndocker pull agentscope/copaw:latest\ndocker run -p 127.0.0.1:8088:8088 -v copaw-data:/app/working agentscope/copaw:latest\n\\`\\`\\`\n\nAfter upgrading, restart the service with \\`copaw app\\`.`,\n};\n" }, { "path": "console/src/layouts/index.module.less", "content": "// ─── MainLayout ───────────────────────────────────────────────────────────────\n.mainLayout {\n height: 100vh;\n}\n\n.pageContainer {\n // inherits from .page-container global class; add local overrides here if needed\n}\n\n// ─── Header ───────────────────────────────────────────────────────────────────\n.header {\n height: 64px;\n padding: 0 24px;\n display: flex;\n align-items: center;\n justify-content: space-between;\n background: #fff;\n border-bottom: 1px solid #f0f0f0;\n}\n\n.headerTitle {\n font-size: 18px;\n font-weight: 500;\n}\n\n// ─── Sidebar ──────────────────────────────────────────────────────────────────\n.sider {\n background: #fff !important;\n border-right: 1px solid #f0f0f0;\n overflow: auto;\n height: 100vh;\n\n :global {\n .copaw-menu {\n border-inline-end: 0 !important;\n }\n }\n}\n\n.siderDark {\n background: #1a1a1a !important;\n border-right-color: rgba(255, 255, 255, 0.08) !important;\n\n :global {\n .copaw-menu {\n background: #1a1a1a !important;\n border-inline-end: 0 !important;\n }\n /* Group title (sub-menu label) */\n .copaw-menu-submenu-title {\n color: rgba(255, 255, 255, 0.45) !important;\n }\n /* Regular menu item */\n .copaw-menu-item {\n color: rgba(255, 255, 255, 0.75) !important;\n }\n /* Hover state */\n .copaw-menu-item:hover,\n .copaw-menu-submenu-title:hover {\n background: rgba(255, 255, 255, 0.06) !important;\n color: rgba(255, 255, 255, 0.9) !important;\n }\n /* Selected item */\n .copaw-menu-item-selected {\n background: rgba(97, 92, 237, 0.2) !important;\n color: #8b87f0 !important;\n }\n }\n}\n\n.siderTop {\n height: 64px;\n display: flex;\n align-items: center;\n padding: 0 16px;\n gap: 12px;\n}\n\n.logoWrapper {\n display: flex;\n align-items: center;\n}\n\n.logoImg {\n height: 32px;\n width: auto;\n}\n\n.versionBadge {\n font-size: 10px;\n color: #615ced;\n font-weight: 600;\n line-height: 1;\n position: relative;\n top: 10px;\n}\n\n.versionBadgeClickable {\n cursor: pointer;\n}\n\n.versionBadgeDefault {\n cursor: default;\n}\n\n.collapseBtn {\n margin: auto;\n color: #615ced;\n}\n\n// ─── Update Modal ─────────────────────────────────────────────────────────────\n.updateModalTitle {\n color: #615ced;\n}\n\n.updateModalBody {\n max-height: 480px;\n overflow-y: auto;\n padding: 8px 4px;\n min-height: 120px;\n}\n\n.updateModalSpinWrapper {\n display: flex;\n justify-content: center;\n align-items: center;\n height: 120px;\n}\n\n.updateModalPrimaryBtn {\n background: #615ced;\n border-color: #615ced;\n}\n\n// ─── Code block inside update modal ──────────────────────────────────────────\n.codeBlock {\n position: relative;\n background: #f5f5f5;\n border: 1px solid #e8e8e8;\n border-radius: 6px;\n padding: 12px 40px 12px 16px;\n overflow-x: auto;\n margin: 8px 0;\n}\n\n.codeBlockInner {\n font-family: monospace;\n font-size: 13px;\n}\n\n.codeInline {\n background: #f5f5f5;\n border-radius: 3px;\n padding: 1px 5px;\n font-family: monospace;\n font-size: 13px;\n}\n\n// ─── CopyButton ───────────────────────────────────────────────────────────────\n.copyBtn {\n position: absolute;\n top: 8px;\n right: 8px;\n transition: color 0.2s;\n}\n\n.copyBtnCopied {\n color: #52c41a;\n}\n\n.copyBtnDefault {\n color: #999;\n}\n\n/* ─── Dark mode overrides ─────────────────────────────────────────────────── */\n:global(.dark-mode) {\n .header {\n background: #1f1f1f !important;\n border-bottom-color: rgba(255, 255, 255, 0.08) !important;\n color: rgba(255, 255, 255, 0.85);\n\n /* Text buttons (Docs / FAQ / GitHub / Changelog) */\n :global(.copaw-btn-text),\n :global(.ant-btn-text) {\n color: rgba(255, 255, 255, 0.75) !important;\n\n &:hover {\n color: #fff !important;\n background: rgba(255, 255, 255, 0.08) !important;\n }\n\n .anticon,\n svg {\n color: inherit !important;\n }\n }\n\n /* Fallback: any icon or text directly inside header */\n :global(.anticon) {\n color: rgba(255, 255, 255, 0.75);\n }\n }\n\n .headerTitle {\n color: rgba(255, 255, 255, 0.85);\n }\n\n .sider {\n background: #1a1a1a !important;\n border-right-color: rgba(255, 255, 255, 0.08) !important;\n }\n\n .siderTop {\n border-bottom: 1px solid rgba(255, 255, 255, 0.06);\n }\n\n .versionBadge {\n color: #8b87f0;\n }\n\n .collapseBtn {\n color: #8b87f0;\n }\n\n .codeBlock {\n background: #2a2a2a;\n border-color: rgba(255, 255, 255, 0.1);\n }\n\n .codeInline {\n background: #2a2a2a;\n color: rgba(255, 255, 255, 0.85);\n }\n\n .copyBtnDefault {\n color: rgba(255, 255, 255, 0.3);\n }\n}\n" }, { "path": "console/src/locales/en.json", "content": "{\n \"common\": {\n \"save\": \"Save\",\n \"reset\": \"Reset\",\n \"cancel\": \"Cancel\",\n \"confirm\": \"Confirm\",\n \"delete\": \"Delete\",\n \"edit\": \"Edit\",\n \"create\": \"Create\",\n \"upload\": \"Upload\",\n \"download\": \"Download\",\n \"refresh\": \"Refresh\",\n \"enable\": \"Enable\",\n \"disable\": \"Disable\",\n \"enabled\": \"Enabled\",\n \"disabled\": \"Disabled\",\n \"preview\": \"Preview\",\n \"content\": \"Content\",\n \"loading\": \"Loading...\",\n \"copy\": \"Copy\",\n \"copied\": \"Copied to clipboard\",\n \"copyFailed\": \"Failed to copy to clipboard\",\n \"contentPlaceholder\": \"Enter content...\",\n \"help\": \"Help\",\n \"close\": \"Close\",\n \"actions\": \"Actions\",\n \"total\": \"Total {{count}}\"\n },\n \"nav\": {\n \"chat\": \"Chat\",\n \"control\": \"Control\",\n \"channels\": \"Channels\",\n \"sessions\": \"Sessions\",\n \"cronJobs\": \"Cron Jobs\",\n \"heartbeat\": \"Heartbeat\",\n \"agent\": \"Agent\",\n \"workspace\": \"Workspace\",\n \"skills\": \"Skills\",\n \"tools\": \"Tools\",\n \"mcp\": \"MCP\",\n \"agentConfig\": \"Configuration\",\n \"agents\": \"Agent Management\",\n \"settings\": \"Settings\",\n \"models\": \"Models\",\n \"environments\": \"Environments\",\n \"security\": \"Security\",\n \"tokenUsage\": \"Token Usage\",\n \"voiceTranscription\": \"Voice Transcription\"\n },\n \"voiceTranscription\": {\n \"title\": \"Voice Transcription\",\n \"description\": \"Configure how incoming audio and voice messages are handled.\",\n \"loadFailed\": \"Failed to load audio mode settings\",\n \"saveSuccess\": \"Audio mode saved\",\n \"saveFailed\": \"Failed to save audio mode\",\n \"audioModeLabel\": \"Audio Mode\",\n \"audioModeDescription\": \"Choose how voice messages from channels (Discord, Telegram, etc.) are processed before being sent to the model.\",\n \"modeAuto\": \"Auto (Recommended)\",\n \"modeAutoDesc\": \"Transcribe audio to text using the selected transcription provider, then send the text to the model. If transcription is unavailable or disabled, a file-uploaded placeholder is shown instead. Audio is never sent directly to the model in this mode. Works with all models.\",\n \"modeNative\": \"Native Audio\",\n \"modeNativeDesc\": \"Send the audio file directly to the model without transcription. This is the only mode that sends audio to the model. Only works with specific audio-capable models (e.g. gpt-4o-audio). Most models do not support this and will reject the message.\",\n \"ffmpegReady\": \"ffmpeg is installed. Audio conversion is available for native mode.\",\n \"ffmpegMissing\": \"ffmpeg is not installed.\",\n \"ffmpegMissingDesc\": \"Native audio mode requires ffmpeg to convert audio formats (e.g. .ogg to .wav). Install ffmpeg as a system package to enable this mode.\",\n \"providerTypeLabel\": \"Transcription Provider\",\n \"providerTypeDescription\": \"Choose the transcription backend. Select Disabled if you do not need voice transcription.\",\n \"providerTypeDisabled\": \"Disabled\",\n \"providerTypeDisabledDesc\": \"No transcription. Voice messages will show a file-uploaded placeholder.\",\n \"providerTypeWhisperApi\": \"Whisper API\",\n \"providerTypeWhisperApiDesc\": \"Use an OpenAI-compatible Whisper API endpoint from a configured provider (e.g. OpenAI, Ollama).\",\n \"providerTypeLocalWhisper\": \"Local Whisper\",\n \"providerTypeLocalWhisperDesc\": \"Run transcription locally using the openai-whisper Python library. Requires both ffmpeg and openai-whisper to be installed.\",\n \"localWhisperReady\": \"Local Whisper is ready. Both ffmpeg and openai-whisper are installed.\",\n \"localWhisperMissing\": \"Local Whisper is not ready. Missing dependencies must be installed.\",\n \"localWhisperMissingDesc\": \"ffmpeg: {{ffmpeg}} | openai-whisper: {{whisper}}. Install missing dependencies: ffmpeg (system package) and openai-whisper (uv pip install openai-whisper, or install CoPaw with the [whisper] extra).\",\n \"providerLabel\": \"Whisper API Provider\",\n \"providerDescription\": \"Select which provider to use for audio transcription via the Whisper API. Only providers with a Whisper-compatible endpoint are shown.\",\n \"providerPlaceholder\": \"Select a provider...\",\n \"noProvidersWarning\": \"No transcription-capable providers found. Configure an OpenAI provider to enable voice transcription.\",\n \"transcriptionInfoTitle\": \"How transcription works\",\n \"transcriptionInfoDesc\": \"Whisper API transcription uses an OpenAI-compatible /v1/audio/transcriptions endpoint. This requires a configured provider with a Whisper-compatible endpoint — for example, an OpenAI provider. Select a specific provider above to enable transcription.\",\n \"transcriptionInfoDescLocal\": \"Local Whisper transcription runs the openai-whisper library directly on your machine. It requires both ffmpeg (for audio decoding) and the openai-whisper Python package to be installed. No API key or network connection is needed. Install with: uv pip install 'copaw[whisper]'.\"\n },\n \"workspace\": {\n \"title\": \"WorkSpace\",\n \"workspacePath\": \"Workspace:\",\n \"noFiles\": \"No files\",\n \"coreFiles\": \"Core Files\",\n \"coreFilesDesc\": \"Bootstrap persona, identity, and tool guidance.\",\n \"uploadTooltip\": \"Bootstrap persona, identity, and tool guidance. (ZIP files only, max 100MB)\",\n \"selectFile\": \"Select a file to edit\",\n \"fileContent\": \"File content...\",\n \"uploadSuccess\": \"File uploaded successfully\",\n \"uploadFailed\": \"File upload failed\",\n \"downloadSuccess\": \"Workspace downloaded successfully\",\n \"downloadFailed\": \"Workspace download failed\",\n \"zipOnly\": \"Only .zip files are supported for upload\",\n \"fileSizeLimit\": \"File size exceeds 100MB limit. Current file: {{size}}MB\",\n \"systemPromptToggleTooltip\": \"Enable/disable this file in system prompt\",\n \"memoryFileWarning\": \"MEMORY.md is typically queried on-demand by the agent using tools. Loading it into the system prompt may cause the context to become too long.\",\n \"configUpdated\": \"System prompt configuration updated\",\n \"configUpdateFailed\": \"Failed to update system prompt configuration\",\n \"attribution\": \"Workspace design partly inspired by the OpenClaw project — thank you! 🐾\",\n \"saveSuccess\": \"Saved successfully\",\n \"saveFailed\": \"Save failed\"\n },\n \"agent\": {\n \"management\": \"Agent Management\",\n \"pageDescription\": \"Create, configure, and manage multiple AI agents with custom workspaces and identities.\",\n \"name\": \"Name\",\n \"id\": \"ID\",\n \"description\": \"Description\",\n \"workspace\": \"Workspace Path\",\n \"create\": \"Create Agent\",\n \"createTitle\": \"Create New Agent\",\n \"createSuccess\": \"Agent created successfully\",\n \"createFailed\": \"Failed to create agent\",\n \"edit\": \"Edit\",\n \"editTitle\": \"Edit Agent - {{name}}\",\n \"updateSuccess\": \"Agent updated successfully\",\n \"updateFailed\": \"Failed to update agent\",\n \"delete\": \"Delete\",\n \"deleteConfirm\": \"Confirm Delete Agent\",\n \"deleteConfirmDesc\": \"Agent will be unavailable after deletion, but workspace files will be kept\",\n \"deleteSuccess\": \"Agent deleted successfully\",\n \"deleteFailed\": \"Failed to delete agent\",\n \"selectAgent\": \"Select Agent\",\n \"currentWorkspace\": \"Current Agent\",\n \"switchSuccess\": \"Agent switched successfully\",\n \"switchFailed\": \"Failed to switch agent\",\n \"loadFailed\": \"Failed to load agent list\",\n \"loadConfigFailed\": \"Failed to load agent config\",\n \"saveFailed\": \"Failed to save agent\",\n \"idRequired\": \"Please enter agent ID\",\n \"idPattern\": \"ID can only contain lowercase letters, numbers, underscores and hyphens\",\n \"idPlaceholder\": \"e.g.: my-agent\",\n \"nameRequired\": \"Please enter agent name\",\n \"namePlaceholder\": \"e.g.: My Agent\",\n \"descriptionPlaceholder\": \"Briefly describe this agent's purpose...\",\n \"workspaceHelp\": \"Leave empty to auto-generate in ~/.copaw/workspaces/\",\n \"defaultNotEditable\": \"Default agent cannot be edited\",\n \"defaultNotDeletable\": \"Default agent cannot be deleted\"\n },\n \"skills\": {\n \"title\": \"Skills\",\n \"description\": \"Manage agent skills and capabilities.\",\n \"importSkills\": \"Import Skill\",\n \"enterSkillUrl\": \"Enter Skill URL\",\n \"supportedSkillUrlSources\": \"Currently supported skill URL sources:\",\n \"urlExamples\": \"URL examples:\",\n \"invalidSkillUrlSource\": \"Skill URL currently needs to start with https://skills.sh/, https://clawhub.ai/, https://skillsmp.com/, https://lobehub.com/, https://market.lobehub.com/, https://github.com/, or https://modelscope.cn/skills/\",\n \"source\": \"Source\",\n \"path\": \"Path\",\n \"skillDescription\": \"Description\",\n \"createSkill\": \"Create Skill\",\n \"viewSkill\": \"View Skill\",\n \"editSkill\": \"Edit Skill\",\n \"skillName\": \"Skill Name\",\n \"skillContent\": \"Skill Content\",\n \"pleaseInputName\": \"Please input skill name\",\n \"pleaseInputContent\": \"Please input skill content\",\n \"skillNamePlaceholder\": \"e.g., weather_query\",\n \"contentPlaceholder\": \"[Format]\\n---\\nname: skill_name (required, lowercase with underscores)\\ndescription: Brief description (required)\\n---\\n\\nSkill implementation (Markdown format)\\n\\n[Example]\\n---\\nname: weather_query\\ndescription: Query weather info for a city\\n---\\n\\n## Features\\nQuery real-time weather data.\\n\\n## Usage\\nUser inputs city name, returns weather info.\",\n \"createSuccess\": \"Skill created successfully\",\n \"createFailed\": \"Failed to create skill\",\n \"deleteConfirm\": \"Are you sure you want to delete this skill?\",\n \"deleteSuccess\": \"Skill deleted successfully\",\n \"deleteFailed\": \"Failed to delete skill\",\n \"updateSuccess\": \"Skill updated successfully\",\n \"updateFailed\": \"Failed to update skill\",\n \"frontmatterRequired\": \"Skills must start and end with ---\",\n \"frontmatterNameRequired\": \"Skills missing required field : name\",\n \"frontmatterDescriptionRequired\": \"Skills missing required field : description\",\n \"editNotSupported\": \"Edit operation is not supported by backend API\",\n \"editNote\": \"Note: Backend API does not support editing skills. You can only view or toggle enable/disable status.\",\n \"create\": \"Create\",\n \"optimizeWithAI\": \"AI Optimize\",\n \"stopOptimize\": \"Stop\",\n \"optimizeSuccess\": \"Skill optimized successfully\",\n \"optimizeFailed\": \"Failed to optimize skill\",\n \"noContentToOptimize\": \"No content to optimize\",\n \"cancelImport\": \"Cancel Import\",\n \"importCancelled\": \"Skill import cancelled\",\n \"importTimeout\": \"Skill import timed out. Please retry or check your network.\",\n \"uploadSkill\": \"Upload Skill\",\n \"uploadSuccess\": \"Skill uploaded successfully\",\n \"uploadFailed\": \"Skill upload failed\",\n \"uploadNoChange\": \"No new skills were imported. They may already exist.\",\n \"zipOnly\": \"Only .zip files are supported for upload\",\n \"fileSizeExceeded\": \"File size exceeds 100MB limit. Current file: {{size}}MB\"\n },\n \"mcp\": {\n \"title\": \"MCP Clients\",\n \"description\": \"Manage Model Context Protocol (MCP) clients for extending agent capabilities.\",\n \"create\": \"Create Client\",\n \"formatSupport\": \"Supported formats\",\n \"emptyState\": \"No MCP clients configured yet\",\n \"loadError\": \"Failed to load MCP clients\",\n \"createSuccess\": \"MCP client created successfully\",\n \"createError\": \"Failed to create MCP client\",\n \"updateSuccess\": \"MCP client updated successfully\",\n \"updateError\": \"Failed to update MCP client\",\n \"enableSuccess\": \"MCP client enabled successfully\",\n \"disableSuccess\": \"MCP client disabled successfully\",\n \"toggleError\": \"Failed to toggle MCP client status\",\n \"deleteConfirm\": \"Are you sure you want to delete this MCP client?\",\n \"deleteSuccess\": \"MCP client deleted successfully\",\n \"deleteError\": \"Failed to delete MCP client\"\n },\n \"heartbeat\": {\n \"title\": \"Heartbeat\",\n \"description\": \"Run HEARTBEAT.md at a fixed interval for self-checks. By default runs silently without affecting current conversations, or optionally send replies to the last chat channel.\",\n \"enabled\": \"Enable heartbeat\",\n \"every\": \"Interval\",\n \"everyRequired\": \"Required\",\n \"everyMin\": \"Must be at least 1\",\n \"unitMinutes\": \"Minutes\",\n \"unitHours\": \"Hours\",\n \"target\": \"Reply target\",\n \"targetMain\": \"Silent mode (default, no channel output)\",\n \"targetLast\": \"Send to last chat channel\",\n \"activeHours\": \"Active hours (optional)\",\n \"activeStart\": \"Start time\",\n \"activeEnd\": \"End time\",\n \"loadFailed\": \"Failed to load heartbeat config\",\n \"saveSuccess\": \"Saved successfully; heartbeat hot-reloaded\",\n \"saveFailed\": \"Failed to save heartbeat config\"\n },\n \"cronJobs\": {\n \"title\": \"Cron Jobs\",\n \"description\": \"Create and manage scheduled tasks that automatically execute at specified times. \",\n \"createJob\": \"Create Job\",\n \"editJob\": \"Edit Job\",\n \"confirmDelete\": \"Confirm Delete\",\n \"deleteConfirm\": \"Are you sure you want to delete this Cron Job?\",\n \"okText\": \"OK\",\n \"cancelText\": \"Cancel\",\n \"deleteText\": \"Delete\",\n \"id\": \"Job ID\",\n \"name\": \"Job Name\",\n \"enabled\": \"Status\",\n \"scheduleType\": \"Schedule Type\",\n \"scheduleCron\": \"Schedule (Cron)\",\n \"scheduleCronLabel\": \"Schedule (Cron)\",\n \"scheduleTimezone\": \"Timezone\",\n \"cronType\": \"Frequency\",\n \"cronTypeHourly\": \"Hourly\",\n \"cronTypeDaily\": \"Daily\",\n \"cronTypeWeekly\": \"Weekly\",\n \"cronTypeCustom\": \"Custom\",\n \"cronTime\": \"Time\",\n \"cronDaysOfWeek\": \"Days of Week\",\n \"cronDayMon\": \"Monday\",\n \"cronDayTue\": \"Tuesday\",\n \"cronDayWed\": \"Wednesday\",\n \"cronDayThu\": \"Thursday\",\n \"cronDayFri\": \"Friday\",\n \"cronDaySat\": \"Saturday\",\n \"cronDaySun\": \"Sunday\",\n \"cronCustomExpression\": \"Cron Expression\",\n \"taskText\": \"Description\",\n \"action\": \"Action\",\n \"disable\": \"Disable\",\n \"executeNow\": \"Execute Now\",\n \"edit\": \"Edit\",\n \"delete\": \"Delete\",\n \"totalItems\": \"Total {{count}} items\",\n \"perPage\": \"/ page\",\n \"pleaseInputId\": \"Please input job ID\",\n \"pleaseInputName\": \"Please input job name\",\n \"pleaseInputCron\": \"Please input cron expression\",\n \"pleaseSelectTaskType\": \"Please select task type\",\n \"pleaseInputRequest\": \"Please input request content\",\n \"pleaseInputChannel\": \"Please input target channel\",\n \"pleaseInputUserId\": \"Please input target user ID\",\n \"pleaseInputSessionId\": \"Please input target session ID\",\n \"jobIdPlaceholder\": \"e.g., daily-report-job\",\n \"jobNamePlaceholder\": \"e.g., Daily Morning Report\",\n \"selectTimezone\": \"Select timezone\",\n \"taskDescriptionPlaceholder\": \"Brief description of what this job does...\",\n \"invalidJsonFormat\": \"Invalid JSON format\",\n \"jsonFormatRequired\": \"JSON format required\",\n \"taskType\": \"Task Type\",\n \"text\": \"Description\",\n \"requestInput\": \"Request Content\",\n \"requestSessionId\": \"Request Session ID\",\n \"requestUserId\": \"Request User ID\",\n \"dispatchChannel\": \"Target Channel\",\n \"dispatchTargetUserId\": \"Target User ID\",\n \"dispatchTargetSessionId\": \"Target Session ID\",\n \"dispatchMode\": \"Delivery Mode\",\n \"runtimeMaxConcurrency\": \"Max Concurrency\",\n \"runtimeTimeoutSeconds\": \"Timeout (seconds)\",\n \"runtimeMisfireGraceSeconds\": \"Misfire Grace (seconds)\",\n \"idTooltip\": \"Unique identifier for this job. Use lowercase letters, numbers, hyphens, and underscores.\",\n \"nameTooltip\": \"A friendly name to help you identify this job.\",\n \"cronTooltip\": \"Define when the task should run\",\n \"cronExample\": \"Common examples: '0 9 * * *' = 9 AM daily | '*/30 * * * *' = every 30 min | '0 */2 * * *' = every 2 hours | '0 0 * * 0' = Sunday midnight\",\n \"cronHelper\": \"New to Cron expressions?\",\n \"cronHelperLink\": \"Use online generator\",\n \"timezoneTooltip\": \"Timezone for the cron schedule. Default: UTC\",\n \"taskTypeTooltip\": \"Choose 'text' for simple message tasks, or 'agent' for complex agent workflows.\",\n \"textTooltip\": \"Optional description of what this task does. Helpful for documentation.\",\n \"requestInputTooltip\": \"Message content in JSON format. This is what the agent will receive and process.\",\n \"requestInputExample\": \"Format: [{\\\"role\\\":\\\"user\\\",\\\"content\\\":[{\\\"type\\\":\\\"text\\\",\\\"text\\\":\\\"Your message here\\\"}]}]\",\n \"requestSessionIdTooltip\": \"Session ID for the request context. Use 'default' if unsure.\",\n \"requestUserIdTooltip\": \"User ID that initiates the request. Use 'system' for automated tasks.\",\n \"dispatchChannelTooltip\": \"Target channel where the response will be sent (e.g., 'console', 'discord', 'imessage').\",\n \"dispatchTargetUserIdTooltip\": \"User ID who will receive the response in the target channel.\",\n \"dispatchTargetSessionIdTooltip\": \"Session ID where the response will be delivered in the target channel.\",\n \"dispatchModeTooltip\": \"Choose 'stream' for real-time responses or 'final' for complete responses only.\",\n \"maxConcurrencyTooltip\": \"Maximum number of this job that can run simultaneously. Default: 1\",\n \"timeoutSecondsTooltip\": \"Maximum execution time in seconds. Job will be terminated if exceeded.\",\n \"misfireGraceSecondsTooltip\": \"Grace period for missed executions. If a job misses its scheduled time by more than this, it won't run.\",\n \"executeNowTitle\": \"Execute Task Now\",\n \"executeNowContent\": \"Are you sure you want to execute \\\"{{name}}\\\" now?\",\n \"executeNowConfirm\": \"Execute Now\"\n },\n \"channels\": {\n \"title\": \"Channels\",\n \"description\": \"Manage and configure message channels\",\n \"loading\": \"Loading channels...\",\n \"configSaved\": \"Configuration saved successfully\",\n \"configFailed\": \"Failed to save configuration\",\n \"channelType\": \"Channel Type\",\n \"status\": \"Status\",\n \"totalItems\": \"Total {{count}} items\",\n \"botPrefix\": \"Bot Prefix\",\n \"filterToolMessages\": \"Show Tool Messages\",\n \"filterToolMessagesTooltip\": \"Show tool call and output messages to users (turn off to hide)\",\n \"filterThinking\": \"Show Thinking\",\n \"filterThinkingTooltip\": \"Show model thinking/reasoning content to users (turn off to hide)\",\n \"notSet\": \"Not set\",\n \"clickCardToEdit\": \"Click card to edit\",\n \"settings\": \"Settings\",\n \"channelSettings\": \"Channel Settings\",\n \"pleaseInputDbPath\": \"Please input DB path\",\n \"pleaseInputPollInterval\": \"Please input poll interval\",\n \"discordBotToken\": \"Discord bot token\",\n \"httpProxyPlaceholder\": \"http://127.0.0.1:18118\",\n \"httpProxyAuthPlaceholder\": \"user:password\",\n \"dbPathPlaceholder\": \"~/Library/Messages/chat.db\",\n \"botPrefixPlaceholder\": \"@bot\",\n \"dmPolicy\": \"DM Policy\",\n \"dmPolicyTooltip\": \"Control who can interact with the bot via direct message. Open: everyone; Allowlist: authorized users only\",\n \"groupPolicy\": \"Group Policy\",\n \"groupPolicyTooltip\": \"Control who can interact with the bot in group chats. Open: everyone; Allowlist: authorized users only\",\n \"requireMention\": \"Require @Mention\",\n \"requireMentionTooltip\": \"When enabled, bot only responds in group chats when explicitly @mentioned\",\n \"policyOpen\": \"Open\",\n \"policyAllowlist\": \"Allowlist\",\n \"allowFrom\": \"Allowlist Users\",\n \"allowFromTooltip\": \"List of user IDs allowed to interact with the bot. Enable allowlist first, then DM the bot to see your ID in the deny message\",\n \"allowFromPlaceholder\": \"Enter user ID and press Enter to add\",\n \"denyMessage\": \"Access Denied Message\",\n \"denyMessageTooltip\": \"Custom message shown to users when access is denied\",\n \"twilioAccountSid\": \"Twilio Account SID\",\n \"twilioAuthToken\": \"Twilio Auth Token\",\n \"phoneNumber\": \"Phone Number\",\n \"phoneNumberSid\": \"Phone Number SID\",\n \"phoneNumberSidHelp\": \"Found under Phone Numbers → Active Numbers in the Twilio Console.\",\n \"ttsProvider\": \"TTS Provider\",\n \"ttsVoice\": \"TTS Voice\",\n \"sttProvider\": \"STT Provider\",\n \"language\": \"Language\",\n \"welcomeGreeting\": \"Welcome Greeting\",\n \"welcomeText\": \"Welcome Message\",\n \"welcomeTextTooltip\": \"Message automatically sent when a user enters a single chat session with the bot for the first time that day\",\n \"welcomeTextPlaceholder\": \"e.g. Hello! I'm CoPaw. How can I help you?\",\n \"loginWeCom\": \"Authorize WeCom Bot via QR Code\",\n \"wecomAuthHint\": \"Click the button to open the WeCom QR code window. After scanning and confirming, Bot ID and Secret will be filled in automatically.\",\n \"wecomAuthSuccess\": \"WeCom bot authorized successfully\",\n \"wecomWindowBlocked\": \"Popup blocked. Please allow popups and try again.\",\n \"wecomCancelled\": \"Authorization cancelled\",\n \"wecomAuthFailed\": \"Authorization failed: {{msg}}\",\n \"wecomSdkLoadFailed\": \"Failed to load WeCom SDK\",\n \"voiceSetupGuide\": \"Set up a Twilio account, purchase a phone number, then enter your credentials below. Find your Account SID and Auth Token on the Twilio Console dashboard. The Phone Number SID is listed under Phone Numbers → Active Numbers.\",\n \"voiceSetupLink\": \"Open Twilio Console\",\n \"xiaoyiSetupGuide\": \"Please create an agent on Huawei Developer Platform and get AK/SK and Agent ID. AK/SK can be found in the credential management page.\",\n \"filterAll\": \"All\",\n \"builtin\": \"Built-in\",\n \"custom\": \"Custom\"\n },\n \"sessions\": {\n \"title\": \"Sessions\",\n \"description\": \"View and manage active chat sessions\",\n \"loading\": \"Loading sessions...\",\n \"confirmDelete\": \"Confirm Delete\",\n \"deleteConfirm\": \"Are you sure you want to delete this session?\",\n \"batchDeleteConfirm\": \"Are you sure you want to delete selected {{count}} sessions?\",\n \"deleteSuccess\": \"Session deleted successfully\",\n \"deleteFailed\": \"Failed to delete session\",\n \"batchDeleteButton\": \"Batch Delete\",\n \"filterUserId\": \"Filter by User ID\",\n \"filterChannel\": \"Filter by Channel\",\n \"allChannels\": \"All Channels\",\n \"totalItems\": \"Total {{count}} items\",\n \"selectedItems\": \"Selected {{count}} items\",\n \"editSession\": \"Edit Session\",\n \"pleaseInputName\": \"Please input session name\",\n \"sessionNamePlaceholder\": \"Session name\"\n },\n \"environments\": {\n \"title\": \"Environment Variables\",\n \"description\": \"Configure key-value environment variables for agents and skills.\",\n \"key\": \"Key\",\n \"value\": \"Value\",\n \"variableNamePlaceholder\": \"VARIABLE_NAME\",\n \"valuePlaceholder\": \"value\",\n \"insertRowBelow\": \"Insert row below\",\n \"deleteRow\": \"Delete row\",\n \"deleteVariable\": \"Delete Variable\",\n \"deleteConfirm\": \"Delete \\\"{{name}}\\\"?\",\n \"deleteSelected\": \"Delete Selected\",\n \"deleteSelectedConfirm\": \"Delete {{label}}?\",\n \"keyRequired\": \"Key is required\",\n \"invalidKeyFormat\": \"Invalid key format\",\n \"duplicateKey\": \"Duplicate key\",\n \"saveSuccess\": \"Environment variables saved\",\n \"saveFailed\": \"Failed to save\",\n \"deleteSuccess\": \"\\\"{{name}}\\\" deleted\",\n \"deleteFailed\": \"Failed to delete\",\n \"noVariables\": \"No environment variables configured yet.\",\n \"addVariable\": \"Add Variable\",\n \"loading\": \"Loading…\",\n \"retry\": \"Retry\",\n \"of\": \"of\",\n \"selected\": \"selected\",\n \"variable\": \"variable\",\n \"variables\": \"variables\",\n \"showValue\": \"Show value\",\n \"hideValue\": \"Hide value\"\n },\n \"modelSelector\": {\n \"selectModel\": \"Select model\",\n \"noConfiguredModels\": \"No configured models\",\n \"switchFailed\": \"Failed to switch model\"\n },\n \"tokenUsage\": {\n \"title\": \"Token Usage\",\n \"description\": \"View LLM token consumption over time, by date and model.\",\n \"totalTokens\": \"Total Tokens\",\n \"totalCalls\": \"Total Calls\",\n \"promptTokens\": \"Prompt Tokens\",\n \"completionTokens\": \"Completion Tokens\",\n \"byModel\": \"By Model\",\n \"byDate\": \"By Date\",\n \"provider\": \"Provider\",\n \"model\": \"Model\",\n \"date\": \"Date\",\n \"refresh\": \"Refresh\",\n \"loadFailed\": \"Failed to load token usage\",\n \"noData\": \"No token usage data in the selected period\"\n },\n \"models\": {\n \"llmConfiguration\": \"LLM Configuration\",\n \"providersTitle\": \"Providers\",\n \"providersDescription\": \"Configure API keys and endpoints for each provider.\",\n \"llmTitle\": \"LLM\",\n \"llmDescription\": \"Choose the active LLM model from an authorized provider.\",\n \"configureProvider\": \"Configure {{name}}\",\n \"baseURL\": \"Base URL\",\n \"apiKey\": \"API Key\",\n \"advancedConfig\": \"Advanced Configuration\",\n \"generateConfig\": \"Generation Parameters\",\n \"generateConfigHint\": \"Generation parameters expressed as a JSON object. They will be expanded and passed into the generation request (`openai.chat.completions` or `anthropic.messages`).\",\n \"generateConfigInvalidJson\": \"Please enter valid JSON\",\n \"generateConfigMustBeObject\": \"Generation parameters must be a JSON object\",\n \"protocol\": \"Protocol\",\n \"protocolHint\": \"Choose the provider API protocol for this configuration.\",\n \"selectProtocol\": \"Please select a protocol\",\n \"protocolOpenAI\": \"OpenAI-compatible (Chat Completions)\",\n \"protocolAnthropic\": \"Anthropic (Messages API)\",\n \"currentKey\": \"Current: {{key}}\",\n \"startsWith\": \"Starts with \\\"{{prefix}}\\\"\",\n \"optionalSelfHosted\": \"Optional for self-hosted services\",\n \"leaveBlankKeep\": \"Leave blank to keep current key\",\n \"enterApiKey\": \"Enter API key ({{prefix}}...)\",\n \"enterApiKeyOptional\": \"Enter API key (optional)\",\n \"openAIEndpoint\": \"OpenAI endpoint, e.g. https://api.openai.com/v1\",\n \"openAICompatibleEndpoint\": \"OpenAI-compatible endpoint, e.g. https://api.example.com (append /v1 only if your provider requires it)\",\n \"azureEndpointHint\": \"Azure OpenAI endpoint, e.g. https://.openai.azure.com/openai/v1\",\n \"anthropicEndpointHint\": \"Anthropic endpoint, e.g. https://api.anthropic.com\",\n \"ollamaEndpointHint\": \"Ollama endpoint, e.g. http://localhost:11434\",\n \"lmstudioEndpointHint\": \"LM Studio endpoint, e.g. http://localhost:1234/v1\",\n \"apiEndpointHint\": \"API endpoint, e.g. https://api.example.com\",\n \"pleaseEnterBaseURL\": \"Please enter the API base URL\",\n \"pleaseEnterValidURL\": \"Please enter a valid URL\",\n \"apiKeyShouldStart\": \"API Key should start with \\\"{{prefix}}\\\"\",\n \"configurationSaved\": \"{{name}} configuration saved\",\n \"failedToSaveConfig\": \"Failed to save configuration\",\n \"revokeAuthorization\": \"Revoke Authorization\",\n \"revokeConfirmContent\": \"Are you sure you want to remove the API key for {{name}}? The current LLM model configuration will also be cleared.\",\n \"revokeConfirmSimple\": \"Are you sure you want to remove the API key for {{name}}?\",\n \"authorizationRevoked\": \"{{name}} authorization revoked, LLM model cleared\",\n \"authorizationRevokedSimple\": \"{{name}} authorization revoked\",\n \"failedToRevoke\": \"Failed to revoke authorization\",\n \"active\": \"Active: {{provider}} / {{model}}\",\n \"provider\": \"Provider\",\n \"model\": \"Model\",\n \"selectProvider\": \"Select provider (must be authorized)\",\n \"selectModel\": \"Select a model\",\n \"llmModelUpdated\": \"LLM Model updated\",\n \"failedToSave\": \"Failed to save\",\n \"saved\": \"Saved\",\n \"save\": \"Save\",\n \"cancel\": \"Cancel\",\n \"loading\": \"Loading...\",\n \"retry\": \"Retry\",\n \"notSet\": \"Not set\",\n \"available\": \"Available\",\n \"unavailable\": \"Unavailable\",\n \"providerAvailable\": \"Ready (with models)\",\n \"providerNoModels\": \"Not Ready (no models)\",\n \"providerNotConfigured\": \"Not Ready (not configured)\",\n \"settings\": \"Settings\",\n \"actions\": \"Actions\",\n \"custom\": \"Custom\",\n \"builtin\": \"Built-in\",\n \"addProvider\": \"Add Provider\",\n \"addProviderTitle\": \"Add Custom Provider\",\n \"providerIdLabel\": \"Provider ID\",\n \"providerIdPlaceholder\": \"e.g. openai, google, anthropic\",\n \"providerIdHint\": \"Lowercase letters, digits, hyphens, underscores. Cannot be changed later.\",\n \"providerNameLabel\": \"Display Name\",\n \"providerNamePlaceholder\": \"e.g. OpenAI, Google Gemini\",\n \"defaultBaseUrlLabel\": \"Default Base URL\",\n \"defaultBaseUrlPlaceholder\": \"e.g. https://api.example.com\",\n \"apiKeyPrefixLabel\": \"API Key Prefix (optional)\",\n \"apiKeyPrefixPlaceholder\": \"e.g. sk-\",\n \"providerCreated\": \"Provider \\\"{{name}}\\\" created\",\n \"providerCreateFailed\": \"Failed to create provider\",\n \"deleteProvider\": \"Delete Provider\",\n \"deleteProviderConfirm\": \"Delete custom provider \\\"{{name}}\\\" and all its models? This cannot be undone.\",\n \"providerDeleted\": \"Provider \\\"{{name}}\\\" deleted\",\n \"providerDeleteFailed\": \"Failed to delete provider\",\n \"manageModels\": \"Models\",\n \"manageModelsTitle\": \"{{provider}} — Model Management\",\n \"userAdded\": \"User-added\",\n \"addModel\": \"Add Model\",\n \"addModelTitle\": \"Add Model to {{provider}}\",\n \"modelIdLabel\": \"Model ID\",\n \"modelIdPlaceholder\": \"e.g. gpt-4o, gemini-2.0-flash\",\n \"modelNameLabel\": \"Model Name\",\n \"modelNameRequired\": \"Please enter model name\",\n \"modelNamePlaceholder\": \"e.g. GPT-4o, Gemini 2.0 Flash\",\n \"modelAdded\": \"Model \\\"{{name}}\\\" added\",\n \"modelAddFailed\": \"Failed to add model\",\n \"removeModel\": \"Remove\",\n \"removeModelConfirm\": \"Remove model \\\"{{name}}\\\" from {{provider}}?\",\n \"modelRemoved\": \"Model \\\"{{name}}\\\" removed\",\n \"modelRemoveFailed\": \"Failed to remove model\",\n \"modelsCount\": \"{{count}} models\",\n \"noModels\": \"No models\",\n \"addModelFirst\": \"Please add a model first\",\n \"local\": \"Local\",\n \"localType\": \"Type\",\n \"localEmbedded\": \"Embedded (in-process)\",\n \"localDownloadFirst\": \"Download a model first\",\n \"localDownloadModel\": \"Download Model\",\n \"localModelsTitle\": \"{{provider}} — Local Models\",\n \"localNoModels\": \"No downloaded models yet\",\n \"localRepoId\": \"Repository ID\",\n \"localRepoIdRequired\": \"Please enter a repository ID\",\n \"localRepoIdPlaceholder\": \"e.g. TheBloke/Mistral-7B-GGUF\",\n \"localFilename\": \"Filename (optional)\",\n \"localFilenamePlaceholder\": \"e.g. mistral-7b.Q4_K_M.gguf\",\n \"localFilenameHint\": \"Leave empty to auto-select the best quantization\",\n \"localSource\": \"Source\",\n \"localDownloadSuccess\": \"Model downloaded successfully\",\n \"localDownloadFailed\": \"Failed to download model\",\n \"localDeleteModel\": \"Delete Model\",\n \"localDeleteConfirm\": \"Delete local model \\\"{{name}}\\\"? The model file will be removed from disk.\",\n \"localModelDeleted\": \"Model \\\"{{name}}\\\" deleted\",\n \"localDeleteFailed\": \"Failed to delete model\",\n \"localDownloadPending\": \"Preparing to download...\",\n \"localDownloading\": \"Downloading {{repo}}... This may take a few minutes.\",\n \"localDownloadNavigateHint\": \"You can navigate away — the download will continue in the background.\",\n \"localDownloadInProgress\": \"A download is already in progress\",\n \"localCancelDownload\": \"Cancel Download\",\n \"localCancelDownloadConfirm\": \"Cancel download of \\\"{{repo}}\\\"?\",\n \"localDownloadCancelled\": \"Download cancelled\",\n \"localCancelDownloadFailed\": \"Failed to cancel download\",\n \"ollamaModelNamePlaceholder\": \"e.g. mistral:7b, qwen3:8b\",\n \"testConnection\": \"Test Connection\",\n \"testConnectionSuccess\": \"Connection test successful\",\n \"testConnectionFailed\": \"Connection test failed\",\n \"testConnectionError\": \"An error occurred while testing connection\",\n \"discoverModels\": \"Discover Models\",\n \"discoverModelsFailed\": \"Failed to discover models\",\n \"ollamaFetchModelsFailed\": \"Failed to fetch Ollama models. Please check the error details.\",\n \"modelTestFailed\": \"Model validation failed, please check if the model ID is correct\",\n \"modelTestFailedConfirm\": \"Model connection test failed: {{message}}. Do you still want to add this model?\",\n \"autoDiscoveredAndAdded\": \"Auto-discovered {{count}} models and added {{added}} new model(s)\",\n \"autoDiscoveredNoNew\": \"Auto-discovered {{count}} models; model list is already up to date\",\n \"autoDiscoverFailed\": \"Automatic model discovery failed; you can add models manually\"\n },\n \"agentConfig\": {\n \"title\": \"Configuration\",\n \"description\": \"Configure agent runtime parameters\",\n \"reactAgentTitle\": \"ReAct Agent\",\n \"contextManagementTitle\": \"Context Management\",\n \"maxIters\": \"Max Iterations\",\n \"maxItersTooltip\": \"Maximum number of reasoning-acting iterations for ReAct agent\",\n \"maxItersPlaceholder\": \"Enter max iterations\",\n \"maxItersRequired\": \"Max iterations is required\",\n \"maxItersMin\": \"Max iterations must be at least 1\",\n \"maxInputLength\": \"Max Input Length\",\n \"maxInputLengthTooltip\": \"Maximum input length (tokens) for the model context window\",\n \"maxInputLengthPlaceholder\": \"Enter max input length\",\n \"maxInputLengthRequired\": \"Max input length is required\",\n \"maxInputLengthMin\": \"Max input length must be at least 1000\",\n \"contextCompactRatio\": \"Context Compact Ratio\",\n \"contextCompactRatioTooltip\": \"Ratio of context to compact when context is full\",\n \"contextCompactRatioRequired\": \"Context compact ratio is required\",\n \"contextCompactThreshold\": \"Context Compact Threshold\",\n \"contextCompactThresholdTooltip\": \"Context compact threshold (tokens), auto-calculated from max input length and compact ratio\",\n \"contextCompactThresholdPlaceholder\": \"Auto-calculated\",\n \"contextCompactReserveRatio\": \"Context Reserve Ratio\",\n \"contextCompactReserveRatioTooltip\": \"Ratio of context to reserve when compacting\",\n \"contextCompactReserveRatioRequired\": \"Context reserve ratio is required\",\n \"contextCompactReserveThreshold\": \"Context Reserve Threshold\",\n \"contextCompactReserveThresholdTooltip\": \"Context reserve threshold (tokens), auto-calculated from max input length and reserve ratio\",\n \"contextCompactReserveThresholdPlaceholder\": \"Auto-calculated\",\n \"toolResultCompactRecentN\": \"Tool Result recent_n\",\n \"toolResultCompactRecentNTooltip\": \"Number of tool results to use recent threshold for\",\n \"toolResultCompactRecentNRequired\": \"Tool result recent_n is required\",\n \"toolResultCompactOldThreshold\": \"Max Characters for Tool Results Beyond recent_n\",\n \"toolResultCompactOldThresholdTooltip\": \"Tool results beyond recent_n exceeding this character limit will be compacted\",\n \"toolResultCompactOldThresholdPlaceholder\": \"Enter character threshold\",\n \"toolResultCompactOldThresholdRequired\": \"Max characters for tool results beyond recent_n is required\",\n \"toolResultCompactRecentThreshold\": \"Max Characters for Tool Results Within recent_n\",\n \"toolResultCompactRecentThresholdTooltip\": \"Tool results within recent_n exceeding this character limit will be compacted\",\n \"toolResultCompactRecentThresholdPlaceholder\": \"Enter character threshold\",\n \"toolResultCompactRecentThresholdRequired\": \"Max characters for tool results within recent_n is required\",\n \"toolResultCompactRetentionDays\": \"Tool Result File Retention Days\",\n \"toolResultCompactRetentionDaysTooltip\": \"Number of days to retain compacted tool result files, expired files are auto-cleaned\",\n \"toolResultCompactRetentionDaysRequired\": \"Tool result file retention days is required\",\n \"language\": \"Agent Language\",\n \"languageTooltip\": \"Language for agent persona files (SOUL.md, AGENTS.md, etc.). Changing this will re-copy MD files in the selected language.\",\n \"languageConfirmTitle\": \"Change Agent Language\",\n \"languageConfirmContent\": \"Changing the language will overwrite the following files with the new language version:\\n\\n SOUL.md, AGENTS.md, PROFILE.md, MEMORY.md, BOOTSTRAP.md, HEARTBEAT.md\\n\\nIf you have customized any of these files, please back them up first. Your other files will not be affected.\",\n \"languageConfirmOk\": \"Change Language\",\n \"languageSaveSuccess\": \"Language updated successfully\",\n \"languageSaveSuccessWithFiles\": \"Language updated, {{count}} MD file(s) copied\",\n \"languageSaveFailed\": \"Failed to update language\",\n \"saveSuccess\": \"Configuration saved successfully\",\n \"saveFailed\": \"Failed to save configuration\",\n \"timezone\": \"User Timezone\",\n \"timezoneTooltip\": \"Used for scheduled tasks, time display, and agent context. Defaults to your system timezone.\",\n \"timezoneRequired\": \"Please select a timezone\",\n \"selectTimezone\": \"Select timezone\",\n \"timezoneSaveSuccess\": \"Timezone updated successfully\",\n \"timezoneSaveFailed\": \"Failed to update timezone\",\n \"loadFailed\": \"Failed to load configuration\"\n },\n \"tools\": {\n \"title\": \"Built-in Tools\",\n \"description\": \"Manage built-in tools and their enabled status. Disabled tools will not be available to the agent.\",\n \"emptyState\": \"No tools configured\",\n \"loadError\": \"Failed to load tools\",\n \"enableSuccess\": \"Tool enabled successfully\",\n \"disableSuccess\": \"Tool disabled successfully\",\n \"toggleError\": \"Failed to toggle tool status\",\n \"enableAll\": \"Enable All\",\n \"disableAll\": \"Disable All\",\n \"enableAllSuccess\": \"All tools enabled\",\n \"disableAllSuccess\": \"All tools disabled\",\n \"allEnabled\": \"All tools are already enabled\",\n \"allDisabled\": \"All tools are already disabled\"\n },\n \"modelConfig\": {\n \"promptTitle\": \"LLM Model Required — Select in Chat After Configuration\",\n \"promptMessage\": \"Chat requires an LLM model to function. Please configure a model first, then select it from the model selector at the top of the Chat page.\",\n \"configureButton\": \"Configure Model\",\n \"skipButton\": \"Skip\",\n \"chatDisabledTitle\": \"Chat Disabled\",\n \"chatDisabledMessage\": \"Chat functionality is disabled because no model is configured. Please configure a model to enable chat.\",\n \"configureNow\": \"Configure Model\",\n \"modelNotConfigured\": \"Please configure a model in Settings before using chat\"\n },\n \"header\": {\n \"changelog\": \"Changelog\",\n \"docs\": \"Doc\",\n \"tutorial\": \"Tutorial\",\n \"faq\": \"FAQ\",\n \"github\": \"GitHub\"\n },\n \"theme\": {\n \"dark\": \"Dark\",\n \"light\": \"Light\",\n \"darkMode\": \"Dark mode\",\n \"lightMode\": \"Light mode\",\n \"switchToDark\": \"Switch to dark mode\",\n \"switchToLight\": \"Switch to light mode\"\n },\n \"sidebar\": {\n \"newVersion\": \"New version available: v{{version}}, click to upgrade\",\n \"updateModal\": {\n \"title\": \"New version available: v{{version}}\",\n \"viewReleases\": \"View Releases\",\n \"close\": \"Close\"\n }\n },\n \"chat\": {\n \"disclaimer\": \"Works for you, grows with you\",\n \"greeting\": \"Hello, how can I help you today?\",\n \"description\": \"I am a helpful assistant that can help you with your questions.\",\n \"prompt1\": \"Let's start a new journey!\",\n \"prompt2\": \"Can you tell me what skills you have?\",\n \"attachments\": {\n \"tooltip\": \"Supports documents, images, videos, audio and more formats, single file up to 10MB\",\n \"fileSizeLimit\": \"Single file cannot exceed 10MB\"\n }\n },\n \"security\": {\n \"title\": \"Security\",\n \"description\": \"Manage security features for tools and skills.\",\n \"toolGuardTitle\": \"Tool Guard\",\n \"toolGuardDescription\": \"Configure security scanning for tool calls. Dangerous operations will require your explicit approval before execution.\",\n \"enabled\": \"Enable Tool Guard\",\n \"enabledTooltip\": \"When enabled, tool calls are scanned for dangerous patterns before execution\",\n \"guardedTools\": \"Guarded Tools\",\n \"guardedToolsTooltip\": \"Tools that require approval when dangerous patterns are detected. Leave empty to use the built-in default set.\",\n \"guardedToolsPlaceholder\": \"Select tools or type custom tool names\",\n \"deniedTools\": \"Denied Tools\",\n \"deniedToolsTooltip\": \"Tools that are always rejected without asking for approval\",\n \"deniedToolsPlaceholder\": \"Select tools to always deny\",\n \"saveSuccess\": \"Tool guard settings saved\",\n \"saveFailed\": \"Failed to save tool guard settings\",\n \"loadFailed\": \"Failed to load tool guard settings\",\n \"rules\": {\n \"title\": \"Detection Rules\",\n \"description\": \"Rules define regex patterns that trigger security alerts. Built-in rules can be disabled; custom rules can be added, edited, or deleted.\",\n \"id\": \"Rule ID\",\n \"severity\": \"Severity\",\n \"descriptionCol\": \"Description\",\n \"source\": \"Source\",\n \"actions\": \"Actions\",\n \"builtin\": \"Built-in\",\n \"custom\": \"Custom\",\n \"enable\": \"Enable\",\n \"disable\": \"Disable\",\n \"edit\": \"Edit\",\n \"delete\": \"Delete\",\n \"add\": \"Add Rule\",\n \"addTitle\": \"Add Custom Rule\",\n \"editTitle\": \"Edit Custom Rule\",\n \"ruleId\": \"Rule ID\",\n \"ruleIdRequired\": \"Rule ID is required\",\n \"duplicateId\": \"A rule with this ID already exists\",\n \"tools\": \"Target Tools\",\n \"toolsPlaceholder\": \"Leave empty to match all tools\",\n \"params\": \"Target Parameters\",\n \"paramsPlaceholder\": \"Leave empty to match all parameters\",\n \"severityLabel\": \"Severity\",\n \"categoryLabel\": \"Category\",\n \"patterns\": \"Regex Patterns\",\n \"patternsRequired\": \"At least one pattern is required\",\n \"patternsTooltip\": \"One regex per line. Matched against tool parameter values (case-insensitive).\",\n \"excludePatterns\": \"Exclude Patterns\",\n \"excludePatternsTooltip\": \"One regex per line. If any matches, the rule is skipped for that value.\",\n \"descriptionLabel\": \"Description\",\n \"descriptionPlaceholder\": \"What does this rule detect?\",\n \"remediationLabel\": \"Remediation\",\n \"remediationPlaceholder\": \"Suggested action when this rule triggers\",\n \"preview\": \"Preview\",\n \"previewTitle\": \"Rule Details\",\n \"actionLabel\": \"Action\",\n \"actionApproval\": \"Require Approval\",\n \"allTools\": \"All tools\",\n \"allParams\": \"All parameters\",\n \"descriptions\": {\n \"TOOL_CMD_DANGEROUS_RM\": \"Detects 'rm' command that may cause data loss\",\n \"TOOL_CMD_DANGEROUS_MV\": \"Detects 'mv' command that may move or overwrite files unexpectedly\",\n \"TOOL_CMD_FS_DESTRUCTION\": \"Detects low-level disk formatting or wiping commands\",\n \"TOOL_CMD_DOS_FORK_BOMB\": \"Detects classic Bash fork bombs and mass process termination\",\n \"TOOL_CMD_PIPE_TO_SHELL\": \"Detects 'curl | bash' patterns used to download and immediately execute remote payloads\",\n \"TOOL_CMD_REVERSE_SHELL\": \"Detects attempts to establish reverse shells or unauthorized network tunnels\",\n \"TOOL_CMD_SYSTEM_TAMPERING\": \"Detects access to cron jobs, SSH keys, or sudo permissions (including reads and modifications)\",\n \"TOOL_CMD_UNSAFE_PERMISSIONS\": \"Detects global permission downgrades (chmod 777) or setting immutable flags\",\n \"TOOL_CMD_OBFUSCATED_EXEC\": \"Detects execution of base64 encoded strings passed directly to a shell interpreter\"\n }\n },\n \"skillScanner\": {\n \"title\": \"Skill Scanner\",\n \"description\": \"Automatically scan skills for security threats before enabling or installing. Unsafe skills can be blocked or whitelisted.\",\n \"mode\": \"Scanner Mode\",\n \"modeTooltip\": \"Controls how the scanner handles unsafe skills: block, warn only, or disabled\",\n \"modeBlock\": \"Block\",\n \"modeWarn\": \"Warn Only\",\n \"modeOff\": \"Off\",\n \"timeout\": \"Scan Timeout (seconds)\",\n \"timeoutTooltip\": \"Maximum time to wait for a scan to complete (5-300 seconds)\",\n \"saveSuccess\": \"Skill scanner settings saved\",\n \"saveFailed\": \"Failed to save skill scanner settings\",\n \"scanAlerts\": {\n \"title\": \"Scan Alerts\",\n \"empty\": \"No security alerts\",\n \"clearAll\": \"Clear All\",\n \"clearConfirm\": \"Clear all scan alerts?\",\n \"skillName\": \"Skill\",\n \"action\": \"Action\",\n \"actionBlocked\": \"Blocked\",\n \"actionWarned\": \"Warned\",\n \"time\": \"Time\",\n \"actions\": \"Actions\",\n \"allowSkill\": \"Add to Whitelist\",\n \"remove\": \"Remove\",\n \"viewFindings\": \"View Details\"\n },\n \"whitelist\": {\n \"title\": \"Whitelist\",\n \"empty\": \"No skills are whitelisted\",\n \"skillName\": \"Skill\",\n \"addedAt\": \"Added At\",\n \"contentHash\": \"Content Hash\",\n \"actions\": \"Actions\",\n \"remove\": \"Remove\",\n \"removeConfirm\": \"Remove this skill from the whitelist?\",\n \"addSuccess\": \"Skill added to whitelist\",\n \"removeSuccess\": \"Skill removed from whitelist\",\n \"addFailed\": \"Failed to add skill to whitelist\",\n \"removeFailed\": \"Failed to remove skill from whitelist\",\n \"removeWillDisable\": \"The skill will also be disabled after removal.\",\n \"removeAndDisabled\": \"Skill removed from whitelist and disabled\"\n },\n \"scanError\": {\n \"title\": \"Security Issues Detected\",\n \"description\": \"The following security issues were found:\",\n \"warnDescription\": \"Security issues were found but the skill was still enabled (warn mode):\",\n \"goToWhitelist\": \"Go to Whitelist\"\n }\n }\n },\n \"login\": {\n \"title\": \"Login to CoPaw\",\n \"registerTitle\": \"Create Account\",\n \"firstUserHint\": \"Create your admin account to get started\",\n \"usernamePlaceholder\": \"Username\",\n \"passwordPlaceholder\": \"Password\",\n \"usernameRequired\": \"Please enter your username\",\n \"passwordRequired\": \"Please enter your password\",\n \"submit\": \"Login\",\n \"register\": \"Register\",\n \"failed\": \"Login failed, please check your credentials\",\n \"registerSuccess\": \"Registration successful\",\n \"registerFailed\": \"Registration failed\",\n \"authNotEnabled\": \"Authentication is not enabled\",\n \"logout\": \"Logout\",\n \"logoutSuccess\": \"Logged out successfully\",\n \"sessionExpired\": \"Session expired, please login again\",\n \"unauthorized\": \"Unauthorized, please login\"\n }\n}\n" }, { "path": "console/src/locales/ja.json", "content": "{\n \"common\": {\n \"save\": \"保存\",\n \"reset\": \"リセット\",\n \"cancel\": \"キャンセル\",\n \"confirm\": \"確認\",\n \"delete\": \"削除\",\n \"edit\": \"編集\",\n \"create\": \"作成\",\n \"upload\": \"アップロード\",\n \"download\": \"ダウンロード\",\n \"refresh\": \"更新\",\n \"enable\": \"有効化\",\n \"disable\": \"無効化\",\n \"enabled\": \"有効\",\n \"disabled\": \"無効\",\n \"preview\": \"プレビュー\",\n \"content\": \"内容\",\n \"loading\": \"読み込み中...\",\n \"copy\": \"コピー\",\n \"copied\": \"クリップボードにコピーしました\",\n \"copyFailed\": \"クリップボードへのコピーに失敗しました\",\n \"contentPlaceholder\": \"内容を入力してください...\",\n \"close\": \"閉じる\"\n },\n \"nav\": {\n \"chat\": \"チャット\",\n \"control\": \"コントロール\",\n \"channels\": \"チャンネル\",\n \"sessions\": \"セッション\",\n \"cronJobs\": \"定期実行\",\n \"heartbeat\": \"ハートビート\",\n \"agent\": \"エージェント\",\n \"workspace\": \"ワークスペース\",\n \"skills\": \"スキル\",\n \"mcp\": \"MCP\",\n \"agentConfig\": \"設定\",\n \"settings\": \"設定\",\n \"models\": \"モデル\",\n \"environments\": \"環境変数\",\n \"security\": \"セキュリティ\",\n \"tokenUsage\": \"トークン使用量\",\n \"tools\": \"ツール\",\n \"voiceTranscription\": \"音声文字起こし\",\n \"agents\": \"エージェント管理\"\n },\n \"agent\": {\n \"management\": \"エージェント管理\",\n \"pageDescription\": \"カスタムワークスペースとアイデンティティを持つ複数の AI エージェントを作成、設定、管理します。\",\n \"name\": \"名前\",\n \"id\": \"ID\",\n \"description\": \"説明\",\n \"workspace\": \"ワークスペースパス\",\n \"create\": \"エージェントを作成\",\n \"createTitle\": \"新しいエージェントを作成\",\n \"createSuccess\": \"エージェントが正常に作成されました\",\n \"createFailed\": \"エージェントの作成に失敗しました\",\n \"edit\": \"編集\",\n \"editTitle\": \"エージェントを編集 - {{name}}\",\n \"updateSuccess\": \"エージェントが正常に更新されました\",\n \"updateFailed\": \"エージェントの更新に失敗しました\",\n \"delete\": \"削除\",\n \"deleteConfirm\": \"エージェントの削除を確認\",\n \"deleteConfirmDesc\": \"削除後、エージェントは利用できなくなりますが、ワークスペースファイルは保持されます\",\n \"deleteSuccess\": \"エージェントが正常に削除されました\",\n \"deleteFailed\": \"エージェントの削除に失敗しました\",\n \"selectAgent\": \"エージェントを選択\",\n \"currentWorkspace\": \"現在のエージェント\",\n \"switchSuccess\": \"エージェントが正常に切り替えられました\",\n \"switchFailed\": \"エージェントの切り替えに失敗しました\",\n \"loadFailed\": \"エージェントリストの読み込みに失敗しました\",\n \"loadConfigFailed\": \"エージェント設定の読み込みに失敗しました\",\n \"saveFailed\": \"エージェントの保存に失敗しました\",\n \"idRequired\": \"エージェント ID を入力してください\",\n \"idPattern\": \"ID は小文字、数字、アンダースコア、ハイフンのみ使用できます\",\n \"idPlaceholder\": \"例：my-agent\",\n \"nameRequired\": \"エージェント名を入力してください\",\n \"namePlaceholder\": \"例：マイエージェント\",\n \"descriptionPlaceholder\": \"このエージェントの目的を簡単に説明してください...\",\n \"workspaceHelp\": \"空欄のままにすると、~/.copaw/workspaces/ に自動生成されます\",\n \"defaultNotEditable\": \"デフォルトのエージェントは編集できません\",\n \"defaultNotDeletable\": \"デフォルトのエージェントは削除できません\"\n },\n \"workspace\": {\n \"title\": \"ワークスペース\",\n \"workspacePath\": \"ワークスペース:\",\n \"noFiles\": \"ファイルなし\",\n \"coreFiles\": \"コアファイル\",\n \"coreFilesDesc\": \"ペルソナ・アイデンティティ・ツールガイダンスを設定します。\",\n \"uploadTooltip\": \"ペルソナ・アイデンティティ・ツールガイダンスを設定します。（ZIPファイルのみ、最大100MB）\",\n \"selectFile\": \"編集するファイルを選択\",\n \"fileContent\": \"ファイルの内容...\",\n \"uploadSuccess\": \"ファイルのアップロードに成功しました\",\n \"uploadFailed\": \"ファイルのアップロードに失敗しました\",\n \"downloadSuccess\": \"ワークスペースのダウンロードに成功しました\",\n \"downloadFailed\": \"ワークスペースのダウンロードに失敗しました\",\n \"zipOnly\": \"アップロードできるのは .zip ファイルのみです\",\n \"fileSizeExceeded\": \"ファイルサイズが100MBの制限を超えています。現在のファイル: {{size}}MB\",\n \"systemPromptToggleTooltip\": \"システムプロンプトへのファイル読み込みを有効/無効にする\",\n \"memoryFileWarning\": \"MEMORY.md は通常、エージェントがツールを使用してオンデマンドで照会および読み込みます。システムプロンプトに読み込むと、コンテキストが長くなりすぎる可能性があります。\",\n \"configUpdated\": \"システムプロンプト設定が更新されました\",\n \"configUpdateFailed\": \"システムプロンプト設定の更新に失敗しました\",\n \"attribution\": \"ワークスペースの設計はOpenClawプロジェクトの一部を参考にしています — ありがとう！🐾\"\n },\n \"skills\": {\n \"title\": \"スキル\",\n \"description\": \"エージェントのスキルと機能を管理します。\",\n \"importSkills\": \"スキルをインポート\",\n \"enterSkillUrl\": \"スキルのURLを入力\",\n \"supportedSkillUrlSources\": \"現在サポートされているスキルURLのソース:\",\n \"urlExamples\": \"URLの例:\",\n \"invalidSkillUrlSource\": \"スキルURLは https://skills.sh/、https://clawhub.ai/、https://skillsmp.com/、https://lobehub.com/、https://market.lobehub.com/、https://github.com/、または https://modelscope.cn/skills/ で始まる必要があります\",\n \"source\": \"ソース\",\n \"path\": \"パス\",\n \"skillDescription\": \"説明\",\n \"createSkill\": \"スキルを作成\",\n \"viewSkill\": \"スキルを表示\",\n \"editSkill\": \"スキルを編集\",\n \"skillName\": \"スキル名\",\n \"skillContent\": \"スキルの内容\",\n \"pleaseInputName\": \"スキル名を入力してください\",\n \"pleaseInputContent\": \"スキルの内容を入力してください\",\n \"skillNamePlaceholder\": \"例: weather_query\",\n \"contentPlaceholder\": \"---\\nname: <スキル名> (必須)\\ndescription: <スキルの説明> (必須)\\nmetadata: { \\\"copaw\\\": { \\\"emoji\\\": \\\"🔧\\\" } }\\n---\\n\\nスキルの実装内容...\\n\\n# 例:\\n# ---\\n# name: cron\\n# description: copawコマンド経由でcronジョブを管理 - タスクの作成・照会・一時停止・再開・削除\\n# metadata: { \\\"copaw\\\": { \\\"emoji\\\": \\\"⏰\\\" } }\\n# ---\",\n \"createSuccess\": \"スキルを作成しました\",\n \"createFailed\": \"スキルの作成に失敗しました\",\n \"deleteConfirm\": \"このスキルを削除してもよろしいですか？\",\n \"deleteSuccess\": \"スキルを削除しました\",\n \"deleteFailed\": \"スキルの削除に失敗しました\",\n \"updateSuccess\": \"スキルを更新しました\",\n \"updateFailed\": \" スキルの更新に失敗しました\",\n \"frontmatterRequired\": \"スキルは --- で始まり --- で終わる必要があります\",\n \"frontmatterNameRequired\": \"スキルに必須フィールド「name」がありません\",\n \"frontmatterDescriptionRequired\": \"スキルに必須フィールド「description」がありません\",\n \"editNotSupported\": \"編集操作はバックエンドAPIでサポートされていません\",\n \"editNote\": \"注意: バックエンドAPIはスキルの編集をサポートしていません。表示または有効/無効の切り替えのみ可能です。\",\n \"create\": \"作成\",\n \"cancelImport\": \"インポートを中止\",\n \"importCancelled\": \"スキルのインポートを中止しました\",\n \"importTimeout\": \"スキルのインポートがタイムアウトしました。再試行するかネットワークを確認してください。\",\n \"uploadSkill\": \"スキルをアップロード\",\n \"uploadSuccess\": \"スキルのアップロードに成功しました\",\n \"uploadFailed\": \"スキルのアップロードに失敗しました\",\n \"uploadNoChange\": \"新しいスキルはインポートされませんでした。既に存在する可能性があります\",\n \"zipOnly\": \"アップロードは .zip ファイルのみ対応しています\",\n \"fileSizeExceeded\": \"ファイルサイズが100MBの制限を超えています。現在のファイル: {{size}}MB\"\n },\n \"mcp\": {\n \"title\": \"MCPクライアント\",\n \"description\": \"エージェントの機能を拡張するためのMCP（Model Context Protocol）クライアントを管理します。\",\n \"create\": \"クライアントを作成\",\n \"formatSupport\": \"サポートされているフォーマット\",\n \"emptyState\": \"MCPクライアントがまだ設定されていません\",\n \"loadError\": \"MCPクライアントの読み込みに失敗しました\",\n \"createSuccess\": \"MCPクライアントを作成しました\",\n \"createError\": \"MCPクライアントの作成に失敗しました\",\n \"updateSuccess\": \"MCPクライアントを更新しました\",\n \"updateError\": \"MCPクライアントの更新に失敗しました\",\n \"enableSuccess\": \"MCPクライアントを有効化しました\",\n \"disableSuccess\": \"MCPクライアントを無効化しました\",\n \"toggleError\": \"MCPクライアントのステータス変更に失敗しました\",\n \"deleteConfirm\": \"このMCPクライアントを削除してもよろしいですか？\",\n \"deleteSuccess\": \"MCPクライアントを削除しました\",\n \"deleteError\": \"MCPクライアントの削除に失敗しました\"\n },\n \"heartbeat\": {\n \"title\": \"ハートビート\",\n \"description\": \"一定間隔でHEARTBEAT.mdを実行してセルフチェックを行います。デフォルトでは現在の会話に影響を与えずサイレントに動作しますが、オプションで最後のチャットチャンネルに返信を送ることもできます。\",\n \"enabled\": \"ハートビートを有効化\",\n \"every\": \"間隔\",\n \"everyRequired\": \"必須\",\n \"everyMin\": \"1以上の値が必要です\",\n \"unitMinutes\": \"分\",\n \"unitHours\": \"時間\",\n \"target\": \"返信先\",\n \"targetMain\": \"サイレントモード（デフォルト、チャンネル出力なし）\",\n \"targetLast\": \"最後のチャットチャンネルに送信\",\n \"activeHours\": \"稼働時間（任意）\",\n \"activeStart\": \"開始時刻\",\n \"activeEnd\": \"終了時刻\",\n \"loadFailed\": \"ハートビート設定の読み込みに失敗しました\",\n \"saveSuccess\": \"保存しました。ハートビートをホットリロードしました\",\n \"saveFailed\": \"ハートビート設定の保存に失敗しました\"\n },\n \"cronJobs\": {\n \"title\": \"定期実行\",\n \"description\": \"指定した時刻に自動実行されるスケジュールタスクを作成・管理します。\",\n \"createJob\": \"ジョブを作成\",\n \"editJob\": \"ジョブを編集\",\n \"confirmDelete\": \"削除の確認\",\n \"deleteConfirm\": \"この定期実行ジョブを削除してもよろしいですか？\",\n \"okText\": \"OK\",\n \"cancelText\": \"キャンセル\",\n \"deleteText\": \"削除\",\n \"id\": \"ジョブID\",\n \"name\": \"ジョブ名\",\n \"enabled\": \"ステータス\",\n \"scheduleType\": \"スケジュールタイプ\",\n \"scheduleCron\": \"スケジュール（Cron）\",\n \"scheduleCronLabel\": \"スケジュール（Cron）\",\n \"scheduleTimezone\": \"タイムゾーン\",\n \"cronType\": \"頻度\",\n \"cronTypeHourly\": \"毎時\",\n \"cronTypeDaily\": \"毎日\",\n \"cronTypeWeekly\": \"毎週\",\n \"cronTypeCustom\": \"カスタム\",\n \"cronTime\": \"時刻\",\n \"cronDaysOfWeek\": \"曜日\",\n \"cronDayMon\": \"月曜日\",\n \"cronDayTue\": \"火曜日\",\n \"cronDayWed\": \"水曜日\",\n \"cronDayThu\": \"木曜日\",\n \"cronDayFri\": \"金曜日\",\n \"cronDaySat\": \"土曜日\",\n \"cronDaySun\": \"日曜日\",\n \"cronCustomExpression\": \"Cron式\",\n \"taskText\": \"説明\",\n \"action\": \"操作\",\n \"disable\": \"無効化\",\n \"executeNow\": \"今すぐ実行\",\n \"edit\": \"編集\",\n \"delete\": \"削除\",\n \"totalItems\": \"合計 {{count}} 件\",\n \"perPage\": \"件/ページ\",\n \"pleaseInputId\": \"ジョブIDを入力してください\",\n \"pleaseInputName\": \"ジョブ名を入力してください\",\n \"pleaseInputCron\": \"Cron式を入力してください\",\n \"pleaseSelectTaskType\": \"タスクタイプを選択してください\",\n \"pleaseInputRequest\": \"リクエスト内容を入力してください\",\n \"pleaseInputChannel\": \"対象チャンネルを入力してください\",\n \"pleaseInputUserId\": \"対象ユーザーIDを入力してください\",\n \"pleaseInputSessionId\": \"対象セッションIDを入力してください\",\n \"jobIdPlaceholder\": \"例: daily-report-job\",\n \"jobNamePlaceholder\": \"例: 毎朝の日報\",\n \"selectTimezone\": \"タイムゾーンを選択\",\n \"taskDescriptionPlaceholder\": \"このジョブの内容を簡単に説明...\",\n \"invalidJsonFormat\": \"JSONフォーマットが不正です\",\n \"jsonFormatRequired\": \"JSONフォーマットが必要です\",\n \"taskType\": \"タスクタイプ\",\n \"text\": \"説明\",\n \"requestInput\": \"リクエスト内容\",\n \"requestSessionId\": \"リクエストセッションID\",\n \"requestUserId\": \"リクエストユーザーID\",\n \"dispatchChannel\": \"対象チャンネル\",\n \"dispatchTargetUserId\": \"対象ユーザーID\",\n \"dispatchTargetSessionId\": \"対象セッションID\",\n \"dispatchMode\": \"配信モード\",\n \"runtimeMaxConcurrency\": \"最大同時実行数\",\n \"runtimeTimeoutSeconds\": \"タイムアウト（秒）\",\n \"runtimeMisfireGraceSeconds\": \"遅延許容時間（秒）\",\n \"idTooltip\": \"このジョブの一意識別子。小文字・数字・ハイフン・アンダースコアが使用できます。\",\n \"nameTooltip\": \"このジョブを識別するためのわかりやすい名前。\",\n \"cronTooltip\": \"タスクの実行タイミングを定義します\",\n \"cronExample\": \"よく使う例: '0 9 * * *' = 毎日9時 | '*/30 * * * *' = 30分ごと | '0 */2 * * *' = 2時間ごと | '0 0 * * 0' = 日曜0時\",\n \"cronHelper\": \"Cron式に慣れていませんか？\",\n \"cronHelperLink\": \"オンラインジェネレーターを使う\",\n \"timezoneTooltip\": \"Cronスケジュールのタイムゾーン。デフォルト: UTC\",\n \"taskTypeTooltip\": \"シンプルなメッセージタスクには「テキスト」を、複雑なエージェントワークフローには「エージェント」を選択してください。\",\n \"textTooltip\": \"このタスクの内容の説明（任意）。ドキュメント用に便利です。\",\n \"requestInputTooltip\": \"JSON形式のメッセージ内容。エージェントが受け取って処理する内容です。\",\n \"requestInputExample\": \"フォーマット: [{\\\"role\\\":\\\"user\\\",\\\"content\\\":[{\\\"type\\\":\\\"text\\\",\\\"text\\\":\\\"ここにメッセージを入力\\\"}]}]\",\n \"requestSessionIdTooltip\": \"リクエストコンテキストのセッションID。不明な場合は「default」を使用してください。\",\n \"requestUserIdTooltip\": \"リクエストを開始するユーザーID。自動タスクには「system」を使用してください。\",\n \"dispatchChannelTooltip\": \"レスポンスを送信する対象チャンネル（例: 'console', 'discord', 'imessage'）。\",\n \"dispatchTargetUserIdTooltip\": \"対象チャンネルでレスポンスを受け取るユーザーID。\",\n \"dispatchTargetSessionIdTooltip\": \"対象チャンネルでレスポンスを届けるセッションID。\",\n \"dispatchModeTooltip\": \"リアルタイム応答には「ストリーム」を、完了後の応答には「ファイナル」を選択してください。\",\n \"maxConcurrencyTooltip\": \"このジョブの最大同時実行数。デフォルト: 1\",\n \"timeoutSecondsTooltip\": \"最大実行時間（秒）。超過するとジョブが終了します。\",\n \"misfireGraceSecondsTooltip\": \"実行漏れの許容時間。スケジュール時刻をこの時間以上過ぎた場合は実行されません。\",\n \"executeNowTitle\": \"タスクを今すぐ実行\",\n \"executeNowContent\": \"\\\"{{name}}\\\" を今すぐ実行してもよろしいですか？\",\n \"executeNowConfirm\": \"今すぐ実行\"\n },\n \"channels\": {\n \"title\": \"チャンネル\",\n \"description\": \"メッセージチャンネルの管理と設定\",\n \"loading\": \"チャンネルを読み込み中...\",\n \"configSaved\": \"設定を保存しました\",\n \"configFailed\": \"設定の保存に失敗しました\",\n \"channelType\": \"チャンネルタイプ\",\n \"status\": \"ステータス\",\n \"totalItems\": \"合計 {{count}} 件\",\n \"botPrefix\": \"Botプレフィックス\",\n \"filterToolMessages\": \"ツールメッセージを表示\",\n \"filterToolMessagesTooltip\": \"ツール呼び出しと出力メッセージをユーザーに表示します（オフにすると非表示）\",\n \"filterThinking\": \"思考過程を表示\",\n \"filterThinkingTooltip\": \"モデルの思考・推論内容をユーザーに表示します（オフにすると非表示）\",\n \"notSet\": \"未設定\",\n \"clickCardToEdit\": \"カードをクリックして編集\",\n \"settings\": \"設定\",\n \"channelSettings\": \"チャンネル設定\",\n \"pleaseInputDbPath\": \"DBパスを入力してください\",\n \"pleaseInputPollInterval\": \"ポーリング間隔を入力してください\",\n \"discordBotToken\": \"Discord Botトークン\",\n \"httpProxyPlaceholder\": \"http://127.0.0.1:18118\",\n \"httpProxyAuthPlaceholder\": \"ユーザー:パスワード\",\n \"dbPathPlaceholder\": \"~/Library/Messages/chat.db\",\n \"botPrefixPlaceholder\": \"@bot\",\n \"dmPolicy\": \"DMポリシー\",\n \"dmPolicyTooltip\": \"ダイレクトメッセージでBotと対話できるユーザーを制御します。オープン: 全員、許可リスト: 認証済みユーザーのみ\",\n \"groupPolicy\": \"グループポリシー\",\n \"groupPolicyTooltip\": \"グループチャットでBotと対話できるユーザーを制御します。オープン: 全員、許可リスト: 認証済みユーザーのみ\",\n \"requireMention\": \"@メンション必須\",\n \"requireMentionTooltip\": \"有効にすると、グループチャットでは明示的に@メンションされた場合のみ応答します\",\n \"policyOpen\": \"オープン\",\n \"policyAllowlist\": \"許可リスト\",\n \"allowFrom\": \"許可ユーザー\",\n \"allowFromTooltip\": \"Botと対話できるユーザーIDのリスト（フォーマット: ニックネーム#末尾4桁、例: John#1234）\",\n \"allowFromPlaceholder\": \"ユーザーIDを入力してEnterで追加\",\n \"denyMessage\": \"アクセス拒否メッセージ\",\n \"denyMessageTooltip\": \"アクセスが拒否されたユーザーに表示されるカスタムメッセージ\",\n \"twilioAccountSid\": \"Twilio アカウント SID\",\n \"twilioAuthToken\": \"Twilio 認証トークン\",\n \"phoneNumber\": \"電話番号\",\n \"phoneNumberSid\": \"電話番号 SID\",\n \"phoneNumberSidHelp\": \"TwilioコンソールのPhone Numbers → Active Numbersで確認できます。\",\n \"ttsProvider\": \"TTSプロバイダー\",\n \"ttsVoice\": \"TTSボイス\",\n \"sttProvider\": \"STTプロバイダー\",\n \"language\": \"言語\",\n \"welcomeGreeting\": \"ウェルカムメッセージ\",\n \"voiceSetupGuide\": \"Twilioアカウントを作成して電話番号を取得し、以下に認証情報を入力してください。アカウント SIDと認証トークンはTwilioコンソールのダッシュボードで確認できます。電話番号 SIDはPhone Numbers → Active Numbersに記載されています。\",\n \"voiceSetupLink\": \"Twilioコンソールを開く\",\n \"loginWeCom\": \"QRコードでWeComボットを認証\",\n \"wecomAuthHint\": \"ボタンをクリックするとWeComのQRコードウィンドウが開きます。スキャンして確認後、Bot IDとSecretが自動入力されます。\",\n \"wecomAuthSuccess\": \"WeComボットの認証に成功しました\",\n \"wecomWindowBlocked\": \"ポップアップがブロックされました。ポップアップを許可してから再試行してください。\",\n \"wecomCancelled\": \"認証がキャンセルされました\",\n \"wecomAuthFailed\": \"認証に失敗しました: {{msg}}\",\n \"wecomSdkLoadFailed\": \"WeCom SDKの読み込みに失敗しました\",\n \"filterAll\": \"すべて\",\n \"builtin\": \"組み込み\",\n \"custom\": \"カスタム\"\n },\n \"sessions\": {\n \"title\": \"セッション\",\n \"description\": \"アクティブなチャットセッションの表示と管理\",\n \"loading\": \"セッションを読み込み中...\",\n \"confirmDelete\": \"削除の確認\",\n \"deleteConfirm\": \"このセッションを削除してもよろしいですか？\",\n \"batchDeleteConfirm\": \"選択した {{count}} 件のセッションを削除してもよろしいですか？\",\n \"deleteSuccess\": \"セッションを削除しました\",\n \"deleteFailed\": \"セッションの削除に失敗しました\",\n \"batchDeleteButton\": \"一括削除\",\n \"filterUserId\": \"ユーザーIDで絞り込み\",\n \"filterChannel\": \"チャンネルで絞り込み\",\n \"allChannels\": \"すべてのチャンネル\",\n \"totalItems\": \"合計 {{count}} 件\",\n \"selectedItems\": \"{{count}} 件選択中\",\n \"editSession\": \"セッションを編集\",\n \"pleaseInputName\": \"セッション名を入力してください\",\n \"sessionNamePlaceholder\": \"セッション名\"\n },\n \"environments\": {\n \"title\": \"環境変数\",\n \"description\": \"エージェントとスキルのキー・バリュー形式の環境変数を設定します。\",\n \"key\": \"キー\",\n \"value\": \"値\",\n \"variableNamePlaceholder\": \"VARIABLE_NAME\",\n \"valuePlaceholder\": \"値\",\n \"insertRowBelow\": \"下に行を挿入\",\n \"deleteRow\": \"行を削除\",\n \"deleteVariable\": \"変数を削除\",\n \"deleteConfirm\": \"\\\"{{name}}\\\" を削除しますか？\",\n \"deleteSelected\": \"選択を削除\",\n \"deleteSelectedConfirm\": \"{{label}} を削除しますか？\",\n \"keyRequired\": \"キーは必須です\",\n \"invalidKeyFormat\": \"キーのフォーマットが不正です\",\n \"duplicateKey\": \"キーが重複しています\",\n \"saveSuccess\": \"環境変数を保存しました\",\n \"saveFailed\": \"保存に失敗しました\",\n \"deleteSuccess\": \"\\\"{{name}}\\\" を削除しました\",\n \"deleteFailed\": \"削除に失敗しました\",\n \"noVariables\": \"環境変数がまだ設定されていません。\",\n \"addVariable\": \"変数を追加\",\n \"loading\": \"読み込み中...\",\n \"retry\": \"再試行\",\n \"of\": \"/\",\n \"selected\": \"選択中\",\n \"variable\": \"変数\",\n \"variables\": \"変数\",\n \"showValue\": \"値を表示\",\n \"hideValue\": \"値を非表示\"\n },\n \"tokenUsage\": {\n \"title\": \"Token 使用量\",\n \"description\": \"日付・モデル別の LLM Token 使用量を確認します。\",\n \"totalTokens\": \"合計 Token 数\",\n \"totalCalls\": \"総呼び出し回数\",\n \"promptTokens\": \"入力 Token\",\n \"completionTokens\": \"出力 Token\",\n \"byModel\": \"モデル別\",\n \"byDate\": \"日付別\",\n \"provider\": \"プロバイダー\",\n \"model\": \"モデル\",\n \"date\": \"日付\",\n \"refresh\": \"更新\",\n \"loadFailed\": \"Token 使用量の読み込みに失敗しました\",\n \"noData\": \"選択期間に Token 使用データがありません\"\n },\n \"modelSelector\": {\n \"selectModel\": \"モデルを選択\",\n \"noConfiguredModels\": \"設定済みモデルがありません\",\n \"switchFailed\": \"モデルの切り替えに失敗しました\"\n },\n \"models\": {\n \"llmConfiguration\": \"LLM設定\",\n \"providersTitle\": \"プロバイダー\",\n \"providersDescription\": \"各プロバイダーのAPIキーとエンドポイントを設定します。\",\n \"llmTitle\": \"LLM\",\n \"llmDescription\": \"認証済みプロバイダーからアクティブなLLMモデルを選択します。\",\n \"configureProvider\": \"{{name}} を設定\",\n \"baseURL\": \"ベースURL\",\n \"apiKey\": \"APIキー\",\n \"advancedConfig\": \"詳細設定\",\n \"generateConfig\": \"生成パラメータ設定\",\n \"generateConfigHint\": \"JSON 形式で指定した生成パラメータ設定です。展開されたうえで生成リクエスト（`openai.chat.completions` または `anthropic.messages`）に渡されます。\",\n \"generateConfigInvalidJson\": \"有効な JSON を入力してください\",\n \"generateConfigMustBeObject\": \"生成パラメータ設定は JSON オブジェクトである必要があります\",\n \"protocol\": \"プロトコル\",\n \"protocolHint\": \"この設定のプロバイダーAPIプロトコルを選択してください。\",\n \"selectProtocol\": \"プロトコルを選択してください\",\n \"protocolOpenAI\": \"OpenAI互換（Chat Completions）\",\n \"protocolAnthropic\": \"Anthropic（Messages API）\",\n \"currentKey\": \"現在: {{key}}\",\n \"startsWith\": \"\\\"{{prefix}}\\\" で始まる\",\n \"optionalSelfHosted\": \"セルフホストサービスの場合は任意\",\n \"leaveBlankKeep\": \"空欄のままにすると現在のキーを維持します\",\n \"enterApiKey\": \"APIキーを入力（{{prefix}}...）\",\n \"enterApiKeyOptional\": \"APIキーを入力（任意）\",\n \"openAIEndpoint\": \"OpenAIエンドポイント、例: https://api.openai.com/v1\",\n \"openAICompatibleEndpoint\": \"OpenAI互換エンドポイント、例: https://api.example.com（プロバイダーが必要とする場合のみ /v1 を追加）\",\n \"azureEndpointHint\": \"Azure OpenAIエンドポイント、例: https://.openai.azure.com/openai/v1\",\n \"anthropicEndpointHint\": \"Anthropicエンドポイント、例: https://api.anthropic.com\",\n \"ollamaEndpointHint\": \"Ollamaエンドポイント、例: http://localhost:11434\",\n \"lmstudioEndpointHint\": \"LM Studioエンドポイント、例: http://localhost:1234/v1\",\n \"apiEndpointHint\": \"APIエンドポイント、例: https://api.example.com\",\n \"pleaseEnterBaseURL\": \"APIベースURLを入力してください\",\n \"pleaseEnterValidURL\": \"有効なURLを入力してください\",\n \"apiKeyShouldStart\": \"APIキーは \\\"{{prefix}}\\\" で始まる必要があります\",\n \"configurationSaved\": \"{{name}} の設定を保存しました\",\n \"failedToSaveConfig\": \"設定の保存に失敗しました\",\n \"revokeAuthorization\": \"認証を取り消す\",\n \"revokeConfirmContent\": \"{{name}} のAPIキーを削除してもよろしいですか？現在のLLMモデル設定もクリアされます。\",\n \"revokeConfirmSimple\": \"{{name}} のAPIキーを削除してもよろしいですか？\",\n \"authorizationRevoked\": \"{{name}} の認証を取り消し、LLMモデルをクリアしました\",\n \"authorizationRevokedSimple\": \"{{name}} の認証を取り消しました\",\n \"failedToRevoke\": \"認証の取り消しに失敗しました\",\n \"active\": \"アクティブ: {{provider}} / {{model}}\",\n \"provider\": \"プロバイダー\",\n \"model\": \"モデル\",\n \"selectProvider\": \"プロバイダーを選択（認証済みである必要があります）\",\n \"selectModel\": \"モデルを選択\",\n \"llmModelUpdated\": \"LLMモデルを更新しました\",\n \"failedToSave\": \"保存に失敗しました\",\n \"saved\": \"保存しました\",\n \"save\": \"保存\",\n \"cancel\": \"キャンセル\",\n \"loading\": \"読み込み中...\",\n \"retry\": \"再試行\",\n \"notSet\": \"未設定\",\n \"available\": \"利用可能\",\n \"unavailable\": \"利用不可\",\n \"providerAvailable\": \"準備完了（モデルあり）\",\n \"providerNoModels\": \"未準備（モデルなし）\",\n \"providerNotConfigured\": \"未準備（未設定）\",\n \"settings\": \"設定\",\n \"actions\": \"操作\",\n \"custom\": \"カスタム\",\n \"builtin\": \"組み込み\",\n \"addProvider\": \"プロバイダーを追加\",\n \"addProviderTitle\": \"カスタムプロバイダーを追加\",\n \"providerIdLabel\": \"プロバイダーID\",\n \"providerIdPlaceholder\": \"例: openai, google, anthropic\",\n \"providerIdHint\": \"小文字・数字・ハイフン・アンダースコアが使用できます。後から変更できません。\",\n \"providerNameLabel\": \"表示名\",\n \"providerNamePlaceholder\": \"例: OpenAI, Google Gemini\",\n \"defaultBaseUrlLabel\": \"デフォルトベースURL\",\n \"defaultBaseUrlPlaceholder\": \"例: https://api.example.com\",\n \"apiKeyPrefixLabel\": \"APIキープレフィックス（任意）\",\n \"apiKeyPrefixPlaceholder\": \"例: sk-\",\n \"providerCreated\": \"プロバイダー \\\"{{name}}\\\" を作成しました\",\n \"providerCreateFailed\": \"プロバイダーの作成に失敗しました\",\n \"deleteProvider\": \"プロバイダーを削除\",\n \"deleteProviderConfirm\": \"カスタムプロバイダー \\\"{{name}}\\\" とすべてのモデルを削除しますか？この操作は取り消せません。\",\n \"providerDeleted\": \"プロバイダー \\\"{{name}}\\\" を削除しました\",\n \"providerDeleteFailed\": \"プロバイダーの削除に失敗しました\",\n \"manageModels\": \"モデル\",\n \"manageModelsTitle\": \"{{provider}} — モデル管理\",\n \"userAdded\": \"ユーザー追加\",\n \"addModel\": \"モデルを追加\",\n \"addModelTitle\": \"{{provider}} にモデルを追加\",\n \"modelIdLabel\": \"モデルID\",\n \"modelIdPlaceholder\": \"例: gpt-4o, gemini-2.0-flash\",\n \"modelNameLabel\": \"モデル名\",\n \"modelNameRequired\": \"モデル名を入力してください\",\n \"modelNamePlaceholder\": \"例: GPT-4o, Gemini 2.0 Flash\",\n \"modelAdded\": \"モデル \\\"{{name}}\\\" を追加しました\",\n \"modelAddFailed\": \"モデルの追加に失敗しました\",\n \"removeModel\": \"削除\",\n \"removeModelConfirm\": \"{{provider}} からモデル \\\"{{name}}\\\" を削除しますか？\",\n \"modelRemoved\": \"モデル \\\"{{name}}\\\" を削除しました\",\n \"modelRemoveFailed\": \"モデルの削除に失敗しました\",\n \"modelsCount\": \"{{count}} モデル\",\n \"noModels\": \"モデルなし\",\n \"addModelFirst\": \"先にモデルを追加してください\",\n \"local\": \"ローカル\",\n \"localType\": \"タイプ\",\n \"localEmbedded\": \"組み込み（インプロセス）\",\n \"localDownloadFirst\": \"先にモデルをダウンロードしてください\",\n \"localDownloadModel\": \"モデルをダウンロード\",\n \"localModelsTitle\": \"{{provider}} — ローカルモデル\",\n \"localNoModels\": \"まだダウンロード済みモデルがありません\",\n \"localRepoId\": \"リポジトリID\",\n \"localRepoIdRequired\": \"リポジトリIDを入力してください\",\n \"localRepoIdPlaceholder\": \"例: TheBloke/Mistral-7B-GGUF\",\n \"localFilename\": \"ファイル名（任意）\",\n \"localFilenamePlaceholder\": \"例: mistral-7b.Q4_K_M.gguf\",\n \"localFilenameHint\": \"空欄にすると最適な量子化が自動選択されます\",\n \"localSource\": \"ソース\",\n \"localDownloadSuccess\": \"モデルのダウンロードに成功しました\",\n \"localDownloadFailed\": \"モデルのダウンロードに失敗しました\",\n \"localDeleteModel\": \"モデルを削除\",\n \"localDeleteConfirm\": \"ローカルモデル \\\"{{name}}\\\" を削除しますか？モデルファイルはディスクから削除されます。\",\n \"localModelDeleted\": \"モデル \\\"{{name}}\\\" を削除しました\",\n \"localDeleteFailed\": \"モデルの削除に失敗しました\",\n \"localDownloadPending\": \"ダウンロードの準備中...\",\n \"localDownloading\": \"{{repo}} をダウンロード中... 数分かかる場合があります。\",\n \"localDownloadNavigateHint\": \"他のページに移動しても構いません。ダウンロードはバックグラウンドで継続されます。\",\n \"localDownloadInProgress\": \"すでにダウンロードが進行中です\",\n \"localCancelDownload\": \"ダウンロードをキャンセル\",\n \"localCancelDownloadConfirm\": \"\\\"{{repo}}\\\" のダウンロードをキャンセルしますか？\",\n \"localDownloadCancelled\": \"ダウンロードをキャンセルしました\",\n \"localCancelDownloadFailed\": \"ダウンロードのキャンセルに失敗しました\",\n \"ollamaModelNamePlaceholder\": \"例: mistral:7b, qwen3:8b\",\n \"testConnection\": \"接続テスト\",\n \"testConnectionSuccess\": \"接続テストに成功しました\",\n \"testConnectionFailed\": \"接続テストに失敗しました\",\n \"testConnectionError\": \"接続テスト中にエラーが発生しました\",\n \"discoverModels\": \"モデルを検出\",\n \"discoverModelsFailed\": \"モデルの検出に失敗しました\",\n \"ollamaFetchModelsFailed\": \"Ollamaモデルの取得に失敗しました。エラーの詳細を確認してください。\",\n \"modelTestFailed\": \"モデルの検証に失敗しました。モデルIDが正しいか確認してください\",\n \"modelTestFailedConfirm\": \"モデルの接続テストに失敗しました: {{message}}。このモデルを追加しますか？\",\n \"autoDiscoveredAndAdded\": \"{{count}} 件のモデルを自動検出し、{{added}} 件の新規モデルを追加しました\",\n \"autoDiscoveredNoNew\": \"{{count}} 件のモデルを自動検出しました。モデルリストはすでに最新です\",\n \"autoDiscoverFailed\": \"モデルの自動検出に失敗しました。手動でモデルを追加できます\"\n },\n \"agentConfig\": {\n \"title\": \"設定\",\n \"description\": \"エージェントのランタイムパラメーターを設定します\",\n \"reactAgentTitle\": \"ReActエージェント\",\n \"contextManagementTitle\": \"コンテキスト管理\",\n \"maxIters\": \"最大反復回数\",\n \"maxItersTooltip\": \"ReActエージェントの推論・行動サイクルの最大反復回数\",\n \"maxItersPlaceholder\": \"最大反復回数を入力\",\n \"maxItersRequired\": \"最大反復回数は必須です\",\n \"maxItersMin\": \"最大反復回数は1以上である必要があります\",\n \"maxInputLength\": \"最大入力長\",\n \"maxInputLengthTooltip\": \"モデルのコンテキストウィンドウの最大入力長（トークン数）\",\n \"maxInputLengthPlaceholder\": \"最大入力長を入力\",\n \"maxInputLengthRequired\": \"最大入力長は必須です\",\n \"maxInputLengthMin\": \"最大入力長は1000以上である必要があります\",\n \"contextCompactRatio\": \"コンテキスト圧縮比率\",\n \"contextCompactRatioTooltip\": \"コンテキストがいっぱいの時に圧縮するコンテキストの比率\",\n \"contextCompactRatioRequired\": \"コンテキスト圧縮比率は必須です\",\n \"contextCompactThreshold\": \"コンテキスト圧縮閾値\",\n \"contextCompactThresholdTooltip\": \"コンテキスト圧縮閾値（トークン数）、最大入力長と圧縮比率から自動計算\",\n \"contextCompactThresholdPlaceholder\": \"自動計算\",\n \"contextCompactReserveRatio\": \"コンテキスト予約比率\",\n \"contextCompactReserveRatioTooltip\": \"コンテキスト圧縮時に予約する比率\",\n \"contextCompactReserveRatioRequired\": \"コンテキスト予約比率は必須です\",\n \"contextCompactReserveThreshold\": \"コンテキスト予約閾値\",\n \"contextCompactReserveThresholdTooltip\": \"コンテキスト予約閾値（トークン数）、最大入力長と予約比率から自動計算\",\n \"contextCompactReserveThresholdPlaceholder\": \"自動計算\",\n \"toolResultCompactRecentN\": \"ツール呼び出し結果のrecent_n\",\n \"toolResultCompactRecentNTooltip\": \"最近のしきい値を使用するツール呼び出し結果の数\",\n \"toolResultCompactRecentNRequired\": \"ツール呼び出し結果のrecent_nは必須です\",\n \"toolResultCompactOldThreshold\": \"recent_nを超えるツール呼び出し結果の最大文字数\",\n \"toolResultCompactOldThresholdTooltip\": \"recent_n範囲外のツール呼び出し結果で、この文字数を超えると圧縮されます\",\n \"toolResultCompactOldThresholdPlaceholder\": \"文字数しきい値を入力\",\n \"toolResultCompactOldThresholdRequired\": \"recent_nを超えるツール呼び出し結果の最大文字数は必須です\",\n \"toolResultCompactRecentThreshold\": \"recent_n内のツール呼び出し結果の最大文字数\",\n \"toolResultCompactRecentThresholdTooltip\": \"recent_n範囲内のツール呼び出し結果で、この文字数を超えると圧縮されます\",\n \"toolResultCompactRecentThresholdPlaceholder\": \"文字数しきい値を入力\",\n \"toolResultCompactRecentThresholdRequired\": \"recent_n内のツール呼び出し結果の最大文字数は必須です\",\n \"toolResultCompactRetentionDays\": \"ツール呼び出しファイルの保持日数\",\n \"toolResultCompactRetentionDaysTooltip\": \"圧縮されたツール結果ファイルの保持日数、期限切れは自動削除されます\",\n \"toolResultCompactRetentionDaysRequired\": \"ツール呼び出しファイルの保持日数は必須です\",\n \"language\": \"エージェント言語\",\n \"languageTooltip\": \"エージェントのペルソナファイル（SOUL.md、AGENTS.md など）の言語。変更すると選択した言語のMDファイルが再コピーされます。\",\n \"languageConfirmTitle\": \"エージェント言語の変更\",\n \"languageConfirmContent\": \"言語を変更すると、以下のファイルが新しい言語のデフォルト版で上書きされます：\\n\\n SOUL.md、AGENTS.md、PROFILE.md、MEMORY.md、BOOTSTRAP.md、HEARTBEAT.md\\n\\nカスタマイズ済みのファイルがある場合は、事前にバックアップしてください。その他のファイルは影響を受けません。\",\n \"languageConfirmOk\": \"言語を変更\",\n \"languageSaveSuccess\": \"言語を更新しました\",\n \"languageSaveSuccessWithFiles\": \"言語を更新し、{{count}} 個のMDファイルをコピーしました\",\n \"languageSaveFailed\": \"言語の更新に失敗しました\",\n \"timezone\": \"ユーザータイムゾーン\",\n \"timezoneTooltip\": \"スケジュールタスク、時刻表示、エージェントコンテキストに使用されます。デフォルトはシステムのタイムゾーンです。\",\n \"timezoneRequired\": \"タイムゾーンを選択してください\",\n \"selectTimezone\": \"タイムゾーンを選択\",\n \"timezoneSaveSuccess\": \"タイムゾーンを更新しました\",\n \"timezoneSaveFailed\": \"タイムゾーンの更新に失敗しました\",\n \"saveSuccess\": \"設定を保存しました\",\n \"saveFailed\": \"設定の保存に失敗しました\",\n \"loadFailed\": \"設定の読み込みに失敗しました\"\n },\n \"tools\": {\n \"title\": \"ビルトインツール\",\n \"description\": \"ビルトインツールとその有効状態を管理します。無効なツールはエージェントで使用できません。\",\n \"emptyState\": \"ツールが設定されていません\",\n \"loadError\": \"ツールの読み込みに失敗しました\",\n \"enableSuccess\": \"ツールを有効化しました\",\n \"disableSuccess\": \"ツールを無効化しました\",\n \"toggleError\": \"ツール状態の切り替えに失敗しました\",\n \"enableAll\": \"すべて有効化\",\n \"disableAll\": \"すべて無効化\",\n \"enableAllSuccess\": \"すべてのツールを有効化しました\",\n \"disableAllSuccess\": \"すべてのツールを無効化しました\",\n \"allEnabled\": \"すべてのツールは既に有効です\",\n \"allDisabled\": \"すべてのツールは既に無効です\"\n },\n \"modelConfig\": {\n \"promptTitle\": \"LLMモデルが必要です — 設定後にChatページで選択\",\n \"promptMessage\": \"チャット機能にはLLMモデルが必要です。まずモデルを設定し、設定完了後にChatページ上部のモデルセレクターで選択してください。\",\n \"configureButton\": \"モデルを設定\",\n \"skipButton\": \"スキップ\",\n \"chatDisabledTitle\": \"チャット無効\",\n \"chatDisabledMessage\": \"モデルが設定されていないためチャット機能が無効です。チャットを有効にするにはモデルを設定してください。\",\n \"configureNow\": \"モデルを設定\",\n \"modelNotConfigured\": \"チャットを使用する前に設定でモデルを設定してください\"\n },\n \"header\": {\n \"changelog\": \"変更履歴\",\n \"docs\": \"ドキュメント\",\n \"tutorial\": \"チュートリアル\",\n \"faq\": \"よくある質問\",\n \"github\": \"GitHub\"\n },\n \"theme\": {\n \"dark\": \"ダーク\",\n \"light\": \"ライト\",\n \"darkMode\": \"ダークモード\",\n \"lightMode\": \"ライトモード\",\n \"switchToDark\": \"ダークモードに切り替え\",\n \"switchToLight\": \"ライトモードに切り替え\"\n },\n \"sidebar\": {\n \"newVersion\": \"新しいバージョンが利用可能です: v{{version}}、クリックしてアップグレード\",\n \"updateModal\": {\n \"title\": \"新しいバージョンが利用可能です: v{{version}}\",\n \"viewReleases\": \"リリースを見る\",\n \"close\": \"閉じる\"\n }\n },\n \"chat\": {\n \"disclaimer\": \"あなたのために働き、あなたと共に成長します\",\n \"greeting\": \"こんにちは、今日はどんなお手伝いができますか？\",\n \"description\": \"私はあなたの質問をサポートするAIアシスタントです。\",\n \"prompt1\": \"新しい旅を始めましょう！\",\n \"prompt2\": \"あなたのスキルを教えてください。\",\n \"attachments\": {\n \"tooltip\": \"ドキュメント、画像、動画、音声など、様々な形式に対応。1ファイルあたり最大10MB\",\n \"fileSizeLimit\": \"1ファイルあたり最大10MB\"\n }\n },\n \"security\": {\n \"title\": \"セキュリティ\",\n \"description\": \"ツールとスキルのセキュリティ機能を管理します。\",\n \"toolGuardTitle\": \"ツールガード\",\n \"toolGuardDescription\": \"ツール呼び出しのセキュリティスキャンを設定します。危険な操作は実行前に明示的な承認が必要になります。\",\n \"enabled\": \"ツールガードを有効にする\",\n \"enabledTooltip\": \"有効にすると、ツール呼び出しが実行前に危険なパターンをスキャンされます\",\n \"guardedTools\": \"保護対象ツール\",\n \"guardedToolsTooltip\": \"危険なパターンが検出された場合に承認が必要なツール。空の場合はデフォルトセットが使用されます。\",\n \"guardedToolsPlaceholder\": \"ツールを選択またはカスタムツール名を入力\",\n \"deniedTools\": \"拒否ツール\",\n \"deniedToolsTooltip\": \"承認なしで常に拒否されるツール\",\n \"deniedToolsPlaceholder\": \"常に拒否するツールを選択\",\n \"saveSuccess\": \"ツールガード設定を保存しました\",\n \"saveFailed\": \"ツールガード設定の保存に失敗しました\",\n \"loadFailed\": \"ツールガード設定の読み込みに失敗しました\",\n \"rules\": {\n \"title\": \"検出ルール\",\n \"description\": \"ルールはセキュリティアラートをトリガーする正規表現パターンを定義します。組み込みルールは無効化でき、カスタムルールは追加・編集・削除できます。\",\n \"id\": \"ルール ID\",\n \"severity\": \"重要度\",\n \"descriptionCol\": \"説明\",\n \"source\": \"ソース\",\n \"actions\": \"操作\",\n \"builtin\": \"組み込み\",\n \"custom\": \"カスタム\",\n \"enable\": \"有効化\",\n \"disable\": \"無効化\",\n \"edit\": \"編集\",\n \"delete\": \"削除\",\n \"add\": \"ルール追加\",\n \"addTitle\": \"カスタムルールを追加\",\n \"editTitle\": \"カスタムルールを編集\",\n \"ruleId\": \"ルール ID\",\n \"ruleIdRequired\": \"ルール ID は必須です\",\n \"duplicateId\": \"このIDのルールは既に存在します\",\n \"tools\": \"対象ツール\",\n \"toolsPlaceholder\": \"空白の場合はすべてのツールに一致\",\n \"params\": \"対象パラメータ\",\n \"paramsPlaceholder\": \"空白の場合はすべてのパラメータに一致\",\n \"severityLabel\": \"重要度\",\n \"categoryLabel\": \"カテゴリ\",\n \"patterns\": \"正規表現パターン\",\n \"patternsRequired\": \"パターンが少なくとも1つ必要です\",\n \"patternsTooltip\": \"1行に1つの正規表現。ツールパラメータ値に対してマッチング（大文字小文字区別なし）。\",\n \"excludePatterns\": \"除外パターン\",\n \"excludePatternsTooltip\": \"1行に1つの正規表現。マッチした場合、そのルールはスキップされます。\",\n \"descriptionLabel\": \"説明\",\n \"descriptionPlaceholder\": \"このルールは何を検出しますか？\",\n \"remediationLabel\": \"修正提案\",\n \"remediationPlaceholder\": \"ルールがトリガーされた場合の推奨アクション\",\n \"preview\": \"プレビュー\",\n \"previewTitle\": \"ルール詳細\",\n \"actionLabel\": \"アクション\",\n \"actionApproval\": \"承認待ち\",\n \"allTools\": \"すべてのツール\",\n \"allParams\": \"すべてのパラメータ\",\n \"descriptions\": {\n \"TOOL_CMD_DANGEROUS_RM\": \"データ損失を引き起こす可能性のある rm コマンドを検出\",\n \"TOOL_CMD_DANGEROUS_MV\": \"ファイルを意図せず移動・上書きする可能性のある mv コマンドを検出\",\n \"TOOL_CMD_FS_DESTRUCTION\": \"低レベルのディスクフォーマットまたはワイプコマンドを検出\",\n \"TOOL_CMD_DOS_FORK_BOMB\": \"Bash フォーク爆弾および大量プロセス終了を検出\",\n \"TOOL_CMD_PIPE_TO_SHELL\": \"リモートペイロードをダウンロードして即座に実行する 'curl | bash' パターンを検出\",\n \"TOOL_CMD_REVERSE_SHELL\": \"リバースシェルまたは不正なネットワークトンネルの確立を検出\",\n \"TOOL_CMD_SYSTEM_TAMPERING\": \"cron ジョブ、SSH キー、sudo 権限へのアクセス（読み取り・変更を含む）を検出\",\n \"TOOL_CMD_UNSAFE_PERMISSIONS\": \"グローバル権限の引き下げ（chmod 777）や不変フラグの設定を検出\",\n \"TOOL_CMD_OBFUSCATED_EXEC\": \"base64 エンコード文字列をシェルインタプリタに直接渡して実行する操作を検出\"\n }\n },\n \"skillScanner\": {\n \"title\": \"スキルスキャナー\",\n \"description\": \"スキルを有効化・インストールする前にセキュリティ脅威を自動スキャンします。\",\n \"mode\": \"スキャンモード\",\n \"modeTooltip\": \"スキャナーが安全でないスキルをどう処理するかを制御: ブロック、警告のみ、オフ\",\n \"modeBlock\": \"ブロック\",\n \"modeWarn\": \"警告のみ\",\n \"modeOff\": \"オフ\",\n \"timeout\": \"スキャンタイムアウト（秒）\",\n \"timeoutTooltip\": \"スキャン完了を待つ最大時間（5-300秒）\",\n \"saveSuccess\": \"スキルスキャナー設定を保存しました\",\n \"saveFailed\": \"スキルスキャナー設定の保存に失敗しました\",\n \"scanAlerts\": {\n \"title\": \"スキャンアラート\",\n \"empty\": \"セキュリティアラートはありません\",\n \"clearAll\": \"すべてクリア\",\n \"clearConfirm\": \"すべてのスキャンアラートをクリアしますか？\",\n \"skillName\": \"スキル\",\n \"action\": \"アクション\",\n \"actionBlocked\": \"ブロック済み\",\n \"actionWarned\": \"警告済み\",\n \"time\": \"日時\",\n \"actions\": \"操作\",\n \"allowSkill\": \"ホワイトリストに追加\",\n \"remove\": \"削除\",\n \"viewFindings\": \"詳細を表示\"\n },\n \"whitelist\": {\n \"title\": \"ホワイトリスト\",\n \"empty\": \"ホワイトリストにスキルがありません\",\n \"skillName\": \"スキル\",\n \"addedAt\": \"追加日時\",\n \"contentHash\": \"コンテンツハッシュ\",\n \"actions\": \"操作\",\n \"remove\": \"削除\",\n \"removeConfirm\": \"このスキルをホワイトリストから削除しますか？\",\n \"addSuccess\": \"スキルをホワイトリストに追加しました\",\n \"removeSuccess\": \"スキルをホワイトリストから削除しました\",\n \"addFailed\": \"ホワイトリストへの追加に失敗しました\",\n \"removeFailed\": \"ホワイトリストからの削除に失敗しました\",\n \"removeWillDisable\": \"削除後、このスキルも無効化されます。\",\n \"removeAndDisabled\": \"スキルをホワイトリストから削除し、無効化しました\"\n },\n \"scanError\": {\n \"title\": \"セキュリティ問題が検出されました\",\n \"description\": \"以下のセキュリティ問題が見つかりました：\",\n \"warnDescription\": \"セキュリティ問題が見つかりましたが、スキルは引き続き有効です（警告モード）：\",\n \"goToWhitelist\": \"ホワイトリストへ\"\n }\n }\n },\n \"login\": {\n \"title\": \"CoPaw にログイン\",\n \"registerTitle\": \"アカウント作成\",\n \"firstUserHint\": \"管理者アカウントを作成して始めましょう\",\n \"usernamePlaceholder\": \"ユーザー名\",\n \"passwordPlaceholder\": \"パスワード\",\n \"usernameRequired\": \"ユーザー名を入力してください\",\n \"passwordRequired\": \"パスワードを入力してください\",\n \"submit\": \"ログイン\",\n \"register\": \"登録\",\n \"failed\": \"ログインに失敗しました。認証情報を確認してください\",\n \"registerSuccess\": \"登録が完了しました\",\n \"registerFailed\": \"登録に失敗しました\",\n \"authNotEnabled\": \"認証は有効になっていません\",\n \"logout\": \"ログアウト\",\n \"logoutSuccess\": \"正常にログアウトしました\",\n \"sessionExpired\": \"セッションが期限切れです。再度ログインしてください\",\n \"unauthorized\": \"未認証です。ログインしてください\"\n },\n \"voiceTranscription\": {\n \"title\": \"音声文字起こし\",\n \"description\": \"受信した音声メッセージの処理方法を設定します。\",\n \"loadFailed\": \"音声モード設定の読み込みに失敗しました\",\n \"saveSuccess\": \"音声モードを保存しました\",\n \"saveFailed\": \"音声モードの保存に失敗しました\",\n \"audioModeLabel\": \"音声モード\",\n \"audioModeDescription\": \"チャンネル（Discord、Telegram など）からの音声メッセージをモデルに送信する前にどのように処理するかを選択します。\",\n \"modeAuto\": \"自動（推奨）\",\n \"modeAutoDesc\": \"選択した文字起こしプロバイダーで音声をテキストに変換してからモデルに送信します。文字起こしが無効または利用できない場合、ファイルアップロードのプレースホルダーが表示されます。このモードでは音声はモデルに直接送信されません。すべてのモデルで動作します。\",\n \"modeNative\": \"ネイティブ音声\",\n \"modeNativeDesc\": \"文字起こしせずに音声ファイルをモデルに直接送信します。音声をモデルに送信する唯一のモードです。音声対応モデル（例: gpt-4o-audio）でのみ動作します。ほとんどのモデルはこのモードをサポートしていません。\",\n \"ffmpegReady\": \"ffmpegがインストールされています。ネイティブモードの音声変換が利用可能です。\",\n \"ffmpegMissing\": \"ffmpegがインストールされていません。\",\n \"ffmpegMissingDesc\": \"ネイティブ音声モードでは、音声形式の変換（.oggから.wavなど）にffmpegが必要です。このモードを有効にするには、ffmpegをシステムパッケージとしてインストールしてください。\",\n \"providerTypeLabel\": \"文字起こしプロバイダー\",\n \"providerTypeDescription\": \"文字起こしバックエンドを選択します。音声文字起こしが不要な場合は「無効」を選択してください。\",\n \"providerTypeDisabled\": \"無効\",\n \"providerTypeDisabledDesc\": \"文字起こしなし。音声メッセージはファイルアップロードのプレースホルダーとして表示されます。\",\n \"providerTypeWhisperApi\": \"Whisper API\",\n \"providerTypeWhisperApiDesc\": \"設定済みプロバイダー（OpenAI、Ollama など）の OpenAI 互換 Whisper API エンドポイントを使用します。\",\n \"providerTypeLocalWhisper\": \"ローカル Whisper\",\n \"providerTypeLocalWhisperDesc\": \"ローカルにインストールされた openai-whisper Python ライブラリで文字起こしを実行します。ffmpeg と openai-whisper の両方のインストールが必要です。\",\n \"localWhisperReady\": \"ローカル Whisper は準備完了です。ffmpeg と openai-whisper がインストールされています。\",\n \"localWhisperMissing\": \"ローカル Whisper は準備ができていません。不足している依存関係をインストールしてください。\",\n \"localWhisperMissingDesc\": \"ffmpeg: {{ffmpeg}} | openai-whisper: {{whisper}}。不足している依存関係をインストールしてください：ffmpeg（システムパッケージ）と openai-whisper（uv pip install openai-whisper、または CoPaw を [whisper] エクストラ付きでインストール）。\",\n \"providerLabel\": \"Whisper API プロバイダー\",\n \"providerDescription\": \"Whisper API による音声文字起こしに使用するプロバイダーを選択します。Whisper 対応エンドポイントを持つプロバイダーのみ表示されます。\",\n \"providerPlaceholder\": \"プロバイダーを選択...\",\n \"noProvidersWarning\": \"文字起こし対応のプロバイダーが見つかりません。音声文字起こしを有効にするには、OpenAI プロバイダーを設定してください。\",\n \"transcriptionInfoTitle\": \"文字起こしの仕組み\",\n \"transcriptionInfoDesc\": \"Whisper API 文字起こしは OpenAI 互換の /v1/audio/transcriptions エンドポイントを使用します。Whisper 対応エンドポイントを持つプロバイダー（例: OpenAI）の設定が必要です。上記で具体的なプロバイダーを選択して文字起こしを有効にしてください。\",\n \"transcriptionInfoDescLocal\": \"ローカル Whisper 文字起こしは、お使いのマシン上で直接 openai-whisper ライブラリを実行します。ffmpeg（音声デコード用）と openai-whisper Python パッケージの両方のインストールが必要です。API キーやネットワーク接続は不要です。インストール：uv pip install 'copaw[whisper]'。\"\n }\n}\n" }, { "path": "console/src/locales/ru.json", "content": "{\n \"common\": {\n \"save\": \"Сохранить\",\n \"reset\": \"Сбросить\",\n \"cancel\": \"Отмена\",\n \"confirm\": \"Подтвердить\",\n \"delete\": \"Удалить\",\n \"edit\": \"Редактировать\",\n \"create\": \"Создать\",\n \"upload\": \"Загрузить\",\n \"download\": \"Скачать\",\n \"refresh\": \"Обновить\",\n \"enable\": \"Включить\",\n \"disable\": \"Отключить\",\n \"enabled\": \"Включено\",\n \"disabled\": \"Отключено\",\n \"preview\": \"Предпросмотр\",\n \"content\": \"Содержимое\",\n \"loading\": \"Загрузка...\",\n \"copy\": \"Копировать\",\n \"copied\": \"Скопировано в буфер обмена\",\n \"copyFailed\": \"Не удалось скопировать в буфер обмена\",\n \"contentPlaceholder\": \"Введите содержимое...\",\n \"close\": \"Закрыть\"\n },\n \"nav\": {\n \"chat\": \"Чат\",\n \"control\": \"Управление\",\n \"channels\": \"Каналы\",\n \"sessions\": \"Сессии\",\n \"cronJobs\": \"Cron-задачи\",\n \"heartbeat\": \"Пульс\",\n \"agent\": \"Агент\",\n \"workspace\": \"Рабочее пространство\",\n \"skills\": \"Навыки\",\n \"tools\": \"Инструменты\",\n \"mcp\": \"MCP\",\n \"agentConfig\": \"Конфигурация\",\n \"settings\": \"Настройки\",\n \"models\": \"Модели\",\n \"environments\": \"Окружения\",\n \"security\": \"Безопасность\",\n \"tokenUsage\": \"Использование токенов\",\n \"voiceTranscription\": \"Транскрипция голоса\",\n \"agents\": \"Управление агентами\"\n },\n \"agent\": {\n \"management\": \"Управление агентами\",\n \"pageDescription\": \"Создавайте, настраивайте и управляйте несколькими AI-агентами с пользовательскими рабочими пространствами и идентичностями.\",\n \"name\": \"Название\",\n \"id\": \"ID\",\n \"description\": \"Описание\",\n \"workspace\": \"Путь к рабочему пространству\",\n \"create\": \"Создать агента\",\n \"createTitle\": \"Создать нового агента\",\n \"createSuccess\": \"Агент успешно создан\",\n \"createFailed\": \"Не удалось создать агента\",\n \"edit\": \"Редактировать\",\n \"editTitle\": \"Редактировать агента - {{name}}\",\n \"updateSuccess\": \"Агент успешно обновлён\",\n \"updateFailed\": \"Не удалось обновить агента\",\n \"delete\": \"Удалить\",\n \"deleteConfirm\": \"Подтвердить удаление агента\",\n \"deleteConfirmDesc\": \"После удаления агент станет недоступен, но файлы рабочего пространства будут сохранены\",\n \"deleteSuccess\": \"Агент успешно удалён\",\n \"deleteFailed\": \"Не удалось удалить агента\",\n \"selectAgent\": \"Выбрать агента\",\n \"currentWorkspace\": \"Текущий агент\",\n \"switchSuccess\": \"Агент успешно переключён\",\n \"switchFailed\": \"Не удалось переключить агента\",\n \"loadFailed\": \"Не удалось загрузить список агентов\",\n \"loadConfigFailed\": \"Не удалось загрузить конфигурацию агента\",\n \"saveFailed\": \"Не удалось сохранить агента\",\n \"idRequired\": \"Пожалуйста, введите ID агента\",\n \"idPattern\": \"ID может содержать только строчные буквы, цифры, подчёркивания и дефисы\",\n \"idPlaceholder\": \"например: my-agent\",\n \"nameRequired\": \"Пожалуйста, введите название агента\",\n \"namePlaceholder\": \"например: Мой агент\",\n \"descriptionPlaceholder\": \"Кратко опишите назначение этого агента...\",\n \"workspaceHelp\": \"Оставьте пустым для автоматического создания в ~/.copaw/workspaces/\",\n \"defaultNotEditable\": \"Агент по умолчанию не может быть отредактирован\",\n \"defaultNotDeletable\": \"Агент по умолчанию не может быть удалён\"\n },\n \"workspace\": {\n \"title\": \"Рабочее пространство\",\n \"workspacePath\": \"Рабочее пространство:\",\n \"noFiles\": \"Нет файлов\",\n \"coreFiles\": \"Основные файлы\",\n \"coreFilesDesc\": \"Базовые файлы с описанием персоны, идентичности и инструкций по инструментам.\",\n \"uploadTooltip\": \"Базовые файлы с описанием персоны, идентичности и инструкций по инструментам. (Только ZIP-файлы, максимум 100 МБ)\",\n \"selectFile\": \"Выберите файл для редактирования\",\n \"fileContent\": \"Содержимое файла...\",\n \"uploadSuccess\": \"Файл успешно загружен\",\n \"uploadFailed\": \"Не удалось загрузить файл\",\n \"downloadSuccess\": \"Рабочее пространство успешно скачано\",\n \"downloadFailed\": \"Не удалось скачать рабочее пространство\",\n \"zipOnly\": \"Для загрузки поддерживаются только файлы .zip\",\n \"fileSizeExceeded\": \"Размер файла превышает лимит 100 МБ. Текущий файл: {{size}} МБ\",\n \"systemPromptToggleTooltip\": \"Включить/выключить загрузку этого файла в системный промпт\",\n \"memoryFileWarning\": \"MEMORY.md обычно запрашивается агентом по требованию с помощью инструментов. Загрузка его в системный промпт может привести к слишком длинному контексту.\",\n \"configUpdated\": \"Конфигурация системного промпта обновлена\",\n \"configUpdateFailed\": \"Не удалось обновить конфигурацию системного промпта\",\n \"attribution\": \"Дизайн рабочего пространства частично вдохновлён проектом OpenClaw — спасибо! 🐾\"\n },\n \"skills\": {\n \"title\": \"Навыки\",\n \"description\": \"Управляйте навыками и возможностями агента.\",\n \"importSkills\": \"Импорт навыка\",\n \"enterSkillUrl\": \"Введите URL навыка\",\n \"supportedSkillUrlSources\": \"Сейчас поддерживаются следующие источники URL навыков:\",\n \"urlExamples\": \"Примеры URL:\",\n \"invalidSkillUrlSource\": \"URL навыка должен начинаться с https://skills.sh/, https://clawhub.ai/, https://skillsmp.com/, https://lobehub.com/, https://market.lobehub.com/, https://github.com/ или https://modelscope.cn/skills/\",\n \"source\": \"Источник\",\n \"path\": \"Путь\",\n \"skillDescription\": \"Описание\",\n \"createSkill\": \"Создать навык\",\n \"viewSkill\": \"Просмотреть навык\",\n \"editSkill\": \"Редактировать навык\",\n \"skillName\": \"Название навыка\",\n \"skillContent\": \"Содержимое навыка\",\n \"pleaseInputName\": \"Пожалуйста, введите название навыка\",\n \"pleaseInputContent\": \"Пожалуйста, введите содержимое навыка\",\n \"skillNamePlaceholder\": \"например, weather_query\",\n \"contentPlaceholder\": \"[Формат]\\n---\\nname: skill_name (обязательно, строчные буквы с подчёркиванием)\\ndescription: Краткое описание (обязательно)\\n---\\n\\nРеализация навыка (формат Markdown)\\n\\n[Пример]\\n---\\nname: weather_query\\ndescription: Запрос информации о погоде для города\\n---\\n\\n## Функции\\nЗапрос данных о погоде в реальном времени.\\n\\n## Использование\\nПользователь вводит название города, возвращается информация о погоде.\",\n \"createSuccess\": \"Навык успешно создан\",\n \"createFailed\": \"Не удалось создать навык\",\n \"deleteConfirm\": \"Вы уверены, что хотите удалить этот навык?\",\n \"deleteSuccess\": \"Навык успешно удалён\",\n \"deleteFailed\": \"Не удалось удалить навык\",\n \"updateSuccess\": \"Навык успешно обновлён\",\n \"updateFailed\": \"Не удалось обновить навык\",\n \"frontmatterRequired\": \"Навык должен начинаться и заканчиваться ---\",\n \"frontmatterNameRequired\": \"В навыке отсутствует обязательное поле: name\",\n \"frontmatterDescriptionRequired\": \"В навыке отсутствует обязательное поле: description\",\n \"editNotSupported\": \"Операция редактирования не поддерживается API бэкенда\",\n \"editNote\": \"Примечание: API бэкенда не поддерживает редактирование навыков. Можно только просматривать и переключать статус включения/отключения.\",\n \"create\": \"Создать\",\n \"optimizeWithAI\": \"AI Оптимизация\",\n \"stopOptimize\": \"Стоп\",\n \"optimizeSuccess\": \"Навык успешно оптимизирован\",\n \"optimizeFailed\": \"Не удалось оптимизировать навык\",\n \"noContentToOptimize\": \"Нет содержимого для оптимизации\",\n \"cancelImport\": \"Отменить импорт\",\n \"importCancelled\": \"Импорт навыка отменён\",\n \"importTimeout\": \"Время ожидания импорта навыка истекло. Повторите попытку или проверьте сеть.\",\n \"uploadSkill\": \"Загрузить навык\",\n \"uploadSuccess\": \"Навык успешно загружен\",\n \"uploadFailed\": \"Не удалось загрузить навык\",\n \"uploadNoChange\": \"Новые навыки не были импортированы. Возможно, они уже существуют\",\n \"zipOnly\": \"Поддерживается загрузка только .zip файлов\",\n \"fileSizeExceeded\": \"Размер файла превышает лимит 100МБ. Текущий файл: {{size}}МБ\"\n },\n \"mcp\": {\n \"title\": \"MCP-клиенты\",\n \"description\": \"Управляйте клиентами Model Context Protocol (MCP) для расширения возможностей агента.\",\n \"create\": \"Создать клиент\",\n \"formatSupport\": \"Поддерживаемые форматы\",\n \"emptyState\": \"MCP-клиенты пока не настроены\",\n \"loadError\": \"Не удалось загрузить MCP-клиентов\",\n \"createSuccess\": \"MCP-клиент успешно создан\",\n \"createError\": \"Не удалось создать MCP-клиент\",\n \"updateSuccess\": \"MCP-клиент успешно обновлён\",\n \"updateError\": \"Не удалось обновить MCP-клиент\",\n \"enableSuccess\": \"MCP-клиент успешно включён\",\n \"disableSuccess\": \"MCP-клиент успешно отключён\",\n \"toggleError\": \"Не удалось переключить статус MCP-клиента\",\n \"deleteConfirm\": \"Вы уверены, что хотите удалить этот MCP-клиент?\",\n \"deleteSuccess\": \"MCP-клиент успешно удалён\",\n \"deleteError\": \"Не удалось удалить MCP-клиент\"\n },\n \"heartbeat\": {\n \"title\": \"Пульс\",\n \"description\": \"Запускайте HEARTBEAT.md с фиксированным интервалом для самопроверок. По умолчанию выполняется тихо и не влияет на текущие диалоги, либо может отправлять ответы в последний канал чата.\",\n \"enabled\": \"Включить пульс\",\n \"every\": \"Интервал\",\n \"everyRequired\": \"Обязательно\",\n \"everyMin\": \"Должно быть не меньше 1\",\n \"unitMinutes\": \"Минуты\",\n \"unitHours\": \"Часы\",\n \"target\": \"Цель ответа\",\n \"targetMain\": \"Тихий режим (по умолчанию, без вывода в канал)\",\n \"targetLast\": \"Отправлять в последний канал чата\",\n \"activeHours\": \"Активные часы (необязательно)\",\n \"activeStart\": \"Время начала\",\n \"activeEnd\": \"Время окончания\",\n \"loadFailed\": \"Не удалось загрузить конфигурацию пульса\",\n \"saveSuccess\": \"Успешно сохранено; пульс перезагружен на лету\",\n \"saveFailed\": \"Не удалось сохранить конфигурацию пульса\"\n },\n \"cronJobs\": {\n \"title\": \"Cron-задачи\",\n \"description\": \"Создавайте и управляйте задачами по расписанию, которые автоматически выполняются в указанное время.\",\n \"createJob\": \"Создать задачу\",\n \"editJob\": \"Редактировать задачу\",\n \"confirmDelete\": \"Подтвердить удаление\",\n \"deleteConfirm\": \"Вы уверены, что хотите удалить эту cron-задачу?\",\n \"okText\": \"OK\",\n \"cancelText\": \"Отмена\",\n \"deleteText\": \"Удалить\",\n \"id\": \"ID задачи\",\n \"name\": \"Название задачи\",\n \"enabled\": \"Статус\",\n \"scheduleType\": \"Тип расписания\",\n \"scheduleCron\": \"Расписание (Cron)\",\n \"scheduleCronLabel\": \"Расписание (Cron)\",\n \"scheduleTimezone\": \"Часовой пояс\",\n \"cronType\": \"Частота\",\n \"cronTypeHourly\": \"Каждый час\",\n \"cronTypeDaily\": \"Ежедневно\",\n \"cronTypeWeekly\": \"Еженедельно\",\n \"cronTypeCustom\": \"Пользовательский\",\n \"cronTime\": \"Время\",\n \"cronDaysOfWeek\": \"Дни недели\",\n \"cronDayMon\": \"Понедельник\",\n \"cronDayTue\": \"Вторник\",\n \"cronDayWed\": \"Среда\",\n \"cronDayThu\": \"Четверг\",\n \"cronDayFri\": \"Пятница\",\n \"cronDaySat\": \"Суббота\",\n \"cronDaySun\": \"Воскресенье\",\n \"cronCustomExpression\": \"Cron-выражение\",\n \"taskText\": \"Описание\",\n \"action\": \"Действие\",\n \"disable\": \"Отключить\",\n \"executeNow\": \"Выполнить сейчас\",\n \"edit\": \"Редактировать\",\n \"delete\": \"Удалить\",\n \"totalItems\": \"Всего {{count}} элементов\",\n \"perPage\": \"/ стр.\",\n \"pleaseInputId\": \"Пожалуйста, введите ID задачи\",\n \"pleaseInputName\": \"Пожалуйста, введите название задачи\",\n \"pleaseInputCron\": \"Пожалуйста, введите cron-выражение\",\n \"pleaseSelectTaskType\": \"Пожалуйста, выберите тип задачи\",\n \"pleaseInputRequest\": \"Пожалуйста, введите содержимое запроса\",\n \"pleaseInputChannel\": \"Пожалуйста, введите целевой канал\",\n \"pleaseInputUserId\": \"Пожалуйста, введите ID целевого пользователя\",\n \"pleaseInputSessionId\": \"Пожалуйста, введите ID целевой сессии\",\n \"jobIdPlaceholder\": \"например, daily-report-job\",\n \"jobNamePlaceholder\": \"например, Ежедневный утренний отчёт\",\n \"selectTimezone\": \"Выберите часовой пояс\",\n \"taskDescriptionPlaceholder\": \"Кратко опишите, что делает эта задача...\",\n \"invalidJsonFormat\": \"Неверный формат JSON\",\n \"jsonFormatRequired\": \"Требуется формат JSON\",\n \"taskType\": \"Тип задачи\",\n \"text\": \"Описание\",\n \"requestInput\": \"Содержимое запроса\",\n \"requestSessionId\": \"ID сессии запроса\",\n \"requestUserId\": \"ID пользователя запроса\",\n \"dispatchChannel\": \"Целевой канал\",\n \"dispatchTargetUserId\": \"ID целевого пользователя\",\n \"dispatchTargetSessionId\": \"ID целевой сессии\",\n \"dispatchMode\": \"Режим доставки\",\n \"runtimeMaxConcurrency\": \"Макс. параллельность\",\n \"runtimeTimeoutSeconds\": \"Таймаут (секунды)\",\n \"runtimeMisfireGraceSeconds\": \"Льготный период пропуска (секунды)\",\n \"idTooltip\": \"Уникальный идентификатор этой задачи. Используйте строчные буквы, цифры, дефисы и подчёркивания.\",\n \"nameTooltip\": \"Понятное имя, чтобы вам было проще найти эту задачу.\",\n \"cronTooltip\": \"Определите, когда задача должна запускаться\",\n \"cronExample\": \"Популярные примеры: '0 9 * * *' = ежедневно в 09:00 | '*/30 * * * *' = каждые 30 мин | '0 */2 * * *' = каждые 2 часа | '0 0 * * 0' = воскресенье, полночь\",\n \"cronHelper\": \"Впервые работаете с cron-выражениями?\",\n \"cronHelperLink\": \"Использовать онлайн-генератор\",\n \"timezoneTooltip\": \"Часовой пояс для cron-расписания. По умолчанию: UTC\",\n \"taskTypeTooltip\": \"Выберите 'text' для простых текстовых задач или 'agent' для сложных сценариев с агентом.\",\n \"textTooltip\": \"Необязательное описание того, что делает задача. Полезно для документации.\",\n \"requestInputTooltip\": \"Содержимое сообщения в формате JSON. Именно это агент получит и обработает.\",\n \"requestInputExample\": \"Формат: [{\\\"role\\\":\\\"user\\\",\\\"content\\\":[{\\\"type\\\":\\\"text\\\",\\\"text\\\":\\\"Ваше сообщение\\\"}]}]\",\n \"requestSessionIdTooltip\": \"ID сессии для контекста запроса. Если не уверены, используйте 'default'.\",\n \"requestUserIdTooltip\": \"ID пользователя, который инициирует запрос. Для автоматических задач используйте 'system'.\",\n \"dispatchChannelTooltip\": \"Целевой канал, куда будет отправлен ответ (например, 'console', 'discord', 'imessage').\",\n \"dispatchTargetUserIdTooltip\": \"ID пользователя, который получит ответ в целевом канале.\",\n \"dispatchTargetSessionIdTooltip\": \"ID сессии, куда будет доставлен ответ в целевом канале.\",\n \"dispatchModeTooltip\": \"Выберите 'stream' для ответов в реальном времени или 'final' только для итоговых ответов.\",\n \"maxConcurrencyTooltip\": \"Максимальное количество одновременно выполняемых экземпляров этой задачи. По умолчанию: 1\",\n \"timeoutSecondsTooltip\": \"Максимальное время выполнения в секундах. При превышении задача будет остановлена.\",\n \"misfireGraceSecondsTooltip\": \"Льготный период для пропущенных запусков. Если задача пропустила время запуска больше чем на это значение, она не будет выполнена.\",\n \"executeNowTitle\": \"Выполнить задачу сейчас\",\n \"executeNowContent\": \"Вы уверены, что хотите выполнить «{{name}}» прямо сейчас?\",\n \"executeNowConfirm\": \"Выполнить сейчас\"\n },\n \"channels\": {\n \"title\": \"Каналы\",\n \"description\": \"Управление и настройка каналов сообщений\",\n \"loading\": \"Загрузка каналов...\",\n \"configSaved\": \"Конфигурация успешно сохранена\",\n \"configFailed\": \"Не удалось сохранить конфигурацию\",\n \"channelType\": \"Тип канала\",\n \"status\": \"Статус\",\n \"totalItems\": \"Всего {{count}} элементов\",\n \"botPrefix\": \"Префикс бота\",\n \"filterToolMessages\": \"Показывать сообщения инструментов\",\n \"filterToolMessagesTooltip\": \"Показывать пользователям вызовы инструментов и их вывод (выключите, чтобы скрыть)\",\n \"filterThinking\": \"Показывать рассуждения\",\n \"filterThinkingTooltip\": \"Показывать пользователям рассуждения модели (выключите, чтобы скрыть)\",\n \"notSet\": \"Не задано\",\n \"clickCardToEdit\": \"Нажмите на карточку для редактирования\",\n \"settings\": \"Настройки\",\n \"channelSettings\": \"Настройки канала\",\n \"pleaseInputDbPath\": \"Пожалуйста, введите путь к БД\",\n \"pleaseInputPollInterval\": \"Пожалуйста, введите интервал опроса\",\n \"discordBotToken\": \"Токен Discord-бота\",\n \"httpProxyPlaceholder\": \"http://127.0.0.1:18118\",\n \"httpProxyAuthPlaceholder\": \"user:password\",\n \"dbPathPlaceholder\": \"~/Library/Messages/chat.db\",\n \"botPrefixPlaceholder\": \"@bot\",\n \"dmPolicy\": \"Политика личных сообщений\",\n \"dmPolicyTooltip\": \"Кто может взаимодействовать с ботом в личных сообщениях. Open: все; Allowlist: только авторизованные пользователи\",\n \"groupPolicy\": \"Политика групп\",\n \"groupPolicyTooltip\": \"Кто может взаимодействовать с ботом в групповых чатах. Open: все; Allowlist: только авторизованные пользователи\",\n \"requireMention\": \"Требовать @упоминание\",\n \"requireMentionTooltip\": \"Бот отвечает в групповых чатах только при явном @упоминании\",\n \"policyOpen\": \"Open\",\n \"policyAllowlist\": \"Allowlist\",\n \"allowFrom\": \"Пользователи allowlist\",\n \"allowFromTooltip\": \"Список ID пользователей, которым разрешено взаимодействовать с ботом. Включите белый список, затем напишите боту в ЛС — ваш ID будет в сообщении об отказе\",\n \"allowFromPlaceholder\": \"Введите ID пользователя и нажмите Enter, чтобы добавить\",\n \"denyMessage\": \"Сообщение об отказе\",\n \"denyMessageTooltip\": \"Пользовательское сообщение для пользователей, которым отказан доступ\",\n \"twilioAccountSid\": \"Twilio Account SID\",\n \"twilioAuthToken\": \"Twilio Auth Token\",\n \"phoneNumber\": \"Номер телефона\",\n \"phoneNumberSid\": \"Phone Number SID\",\n \"phoneNumberSidHelp\": \"Можно найти в разделе Phone Numbers → Active Numbers в Twilio Console.\",\n \"ttsProvider\": \"TTS-провайдер\",\n \"ttsVoice\": \"TTS-голос\",\n \"sttProvider\": \"STT-провайдер\",\n \"language\": \"Язык\",\n \"welcomeGreeting\": \"Приветственное сообщение\",\n \"voiceSetupGuide\": \"Создайте аккаунт Twilio, купите номер телефона и затем введите данные ниже. Account SID и Auth Token находятся на панели Twilio Console. Phone Number SID указан в разделе Phone Numbers → Active Numbers.\",\n \"voiceSetupLink\": \"Открыть Twilio Console\",\n \"loginWeCom\": \"Авторизовать бота WeCom по QR-коду\",\n \"wecomAuthHint\": \"Нажмите кнопку — откроется окно с QR-кодом WeCom. После сканирования Bot ID и Secret будут заполнены автоматически.\",\n \"wecomAuthSuccess\": \"Бот WeCom успешно авторизован\",\n \"wecomWindowBlocked\": \"Всплывающее окно заблокировано. Разрешите всплывающие окна и попробуйте снова.\",\n \"wecomCancelled\": \"Авторизация отменена\",\n \"wecomAuthFailed\": \"Ошибка авторизации: {{msg}}\",\n \"wecomSdkLoadFailed\": \"Не удалось загрузить WeCom SDK\",\n \"filterAll\": \"Все\",\n \"builtin\": \"Встроенные\",\n \"custom\": \"Пользовательские\"\n },\n \"sessions\": {\n \"title\": \"Сессии\",\n \"description\": \"Просмотр и управление активными чат-сессиями\",\n \"loading\": \"Загрузка сессий...\",\n \"confirmDelete\": \"Подтвердить удаление\",\n \"deleteConfirm\": \"Вы уверены, что хотите удалить эту сессию?\",\n \"batchDeleteConfirm\": \"Вы уверены, что хотите удалить выбранные сессии ({{count}})?\",\n \"deleteSuccess\": \"Сессия успешно удалена\",\n \"deleteFailed\": \"Не удалось удалить сессию\",\n \"batchDeleteButton\": \"Массовое удаление\",\n \"filterUserId\": \"Фильтр по ID пользователя\",\n \"filterChannel\": \"Фильтр по каналу\",\n \"allChannels\": \"Все каналы\",\n \"totalItems\": \"Всего {{count}} элементов\",\n \"selectedItems\": \"Выбрано {{count}} элементов\",\n \"editSession\": \"Редактировать сессию\",\n \"pleaseInputName\": \"Пожалуйста, введите название сессии\",\n \"sessionNamePlaceholder\": \"Название сессии\"\n },\n \"environments\": {\n \"title\": \"Переменные окружения\",\n \"description\": \"Настройка переменных окружения (ключ-значение) для агентов и навыков.\",\n \"key\": \"Ключ\",\n \"value\": \"Значение\",\n \"variableNamePlaceholder\": \"VARIABLE_NAME\",\n \"valuePlaceholder\": \"value\",\n \"insertRowBelow\": \"Вставить строку ниже\",\n \"deleteRow\": \"Удалить строку\",\n \"deleteVariable\": \"Удалить переменную\",\n \"deleteConfirm\": \"Удалить «{{name}}»?\",\n \"deleteSelected\": \"Удалить выбранные\",\n \"deleteSelectedConfirm\": \"Удалить {{label}}?\",\n \"keyRequired\": \"Ключ обязателен\",\n \"invalidKeyFormat\": \"Неверный формат ключа\",\n \"duplicateKey\": \"Дубликат ключа\",\n \"saveSuccess\": \"Переменные окружения сохранены\",\n \"saveFailed\": \"Не удалось сохранить\",\n \"deleteSuccess\": \"«{{name}}» удалено\",\n \"deleteFailed\": \"Не удалось удалить\",\n \"noVariables\": \"Переменные окружения пока не настроены.\",\n \"addVariable\": \"Добавить переменную\",\n \"loading\": \"Загрузка…\",\n \"retry\": \"Повторить\",\n \"of\": \"из\",\n \"selected\": \"выбрано\",\n \"variable\": \"переменная\",\n \"variables\": \"переменных\",\n \"showValue\": \"Показать значение\",\n \"hideValue\": \"Скрыть значение\"\n },\n \"tokenUsage\": {\n \"title\": \"Использование токенов\",\n \"description\": \"Просмотр расхода LLM-токенов по датам и моделям.\",\n \"totalTokens\": \"Всего токенов\",\n \"totalCalls\": \"Всего вызовов\",\n \"promptTokens\": \"Входные токены\",\n \"completionTokens\": \"Выходные токены\",\n \"byModel\": \"По модели\",\n \"byDate\": \"По дате\",\n \"provider\": \"Провайдер\",\n \"model\": \"Модель\",\n \"date\": \"Дата\",\n \"refresh\": \"Обновить\",\n \"loadFailed\": \"Не удалось загрузить данные об использовании токенов\",\n \"noData\": \"Нет данных об использовании токенов за выбранный период\"\n },\n \"modelSelector\": {\n \"selectModel\": \"Выбрать модель\",\n \"noConfiguredModels\": \"Нет настроенных моделей\",\n \"switchFailed\": \"Не удалось переключить модель\"\n },\n \"models\": {\n \"llmConfiguration\": \"Конфигурация LLM\",\n \"providersTitle\": \"Провайдеры\",\n \"providersDescription\": \"Настройте API-ключи и endpoints для каждого провайдера.\",\n \"llmTitle\": \"LLM\",\n \"llmDescription\": \"Выберите активную LLM-модель от авторизованного провайдера.\",\n \"configureProvider\": \"Настроить {{name}}\",\n \"baseURL\": \"Базовый URL\",\n \"apiKey\": \"API-ключ\",\n \"advancedConfig\": \"Расширенная конфигурация\",\n \"generateConfig\": \"Параметры генерации\",\n \"generateConfigHint\": \"Параметры генерации в формате JSON будут развёрнуты и переданы в запрос на генерацию (`openai.chat.completions` или `anthropic.messages`).\",\n \"generateConfigInvalidJson\": \"Пожалуйста, введите корректный JSON\",\n \"generateConfigMustBeObject\": \"Параметры генерации должны быть JSON-объектом\",\n \"protocol\": \"Протокол\",\n \"protocolHint\": \"Выберите протокол API провайдера для этой конфигурации.\",\n \"selectProtocol\": \"Пожалуйста, выберите протокол\",\n \"protocolOpenAI\": \"OpenAI-совместимый (Chat Completions)\",\n \"protocolAnthropic\": \"Anthropic (Messages API)\",\n \"currentKey\": \"Текущий: {{key}}\",\n \"startsWith\": \"Начинается с «{{prefix}}»\",\n \"optionalSelfHosted\": \"Необязательно для self-hosted сервисов\",\n \"leaveBlankKeep\": \"Оставьте пустым, чтобы сохранить текущий ключ\",\n \"enterApiKey\": \"Введите API-ключ ({{prefix}}...)\",\n \"enterApiKeyOptional\": \"Введите API-ключ (необязательно)\",\n \"openAIEndpoint\": \"OpenAI endpoint, например https://api.openai.com/v1\",\n \"openAICompatibleEndpoint\": \"OpenAI-совместимый endpoint, например https://api.example.com (добавляйте /v1 только если ваш провайдер этого требует)\",\n \"azureEndpointHint\": \"Azure OpenAI endpoint, например https://.openai.azure.com/openai/v1\",\n \"anthropicEndpointHint\": \"Anthropic endpoint, например https://api.anthropic.com\",\n \"ollamaEndpointHint\": \"Ollama endpoint, например http://localhost:11434\",\n \"lmstudioEndpointHint\": \"LM Studio endpoint, например http://localhost:1234/v1\",\n \"apiEndpointHint\": \"API endpoint, например https://api.example.com\",\n \"pleaseEnterBaseURL\": \"Пожалуйста, введите базовый URL API\",\n \"pleaseEnterValidURL\": \"Пожалуйста, введите корректный URL\",\n \"apiKeyShouldStart\": \"API-ключ должен начинаться с «{{prefix}}»\",\n \"configurationSaved\": \"Конфигурация {{name}} сохранена\",\n \"failedToSaveConfig\": \"Не удалось сохранить конфигурацию\",\n \"revokeAuthorization\": \"Отозвать авторизацию\",\n \"revokeConfirmContent\": \"Вы уверены, что хотите удалить API-ключ для {{name}}? Текущая конфигурация LLM-модели также будет очищена.\",\n \"revokeConfirmSimple\": \"Вы уверены, что хотите удалить API-ключ для {{name}}?\",\n \"authorizationRevoked\": \"Авторизация {{name}} отозвана, LLM-модель очищена\",\n \"authorizationRevokedSimple\": \"Авторизация {{name}} отозвана\",\n \"failedToRevoke\": \"Не удалось отозвать авторизацию\",\n \"active\": \"Активно: {{provider}} / {{model}}\",\n \"provider\": \"Провайдер\",\n \"model\": \"Модель\",\n \"selectProvider\": \"Выберите провайдера (должен быть авторизован)\",\n \"selectModel\": \"Выберите модель\",\n \"llmModelUpdated\": \"LLM-модель обновлена\",\n \"failedToSave\": \"Не удалось сохранить\",\n \"saved\": \"Сохранено\",\n \"save\": \"Сохранить\",\n \"cancel\": \"Отмена\",\n \"loading\": \"Загрузка...\",\n \"retry\": \"Повторить\",\n \"notSet\": \"Не задано\",\n \"available\": \"Доступно\",\n \"unavailable\": \"Недоступно\",\n \"providerAvailable\": \"Готово (есть модели)\",\n \"providerNoModels\": \"Не готово (нет моделей)\",\n \"providerNotConfigured\": \"Не готово (не настроено)\",\n \"settings\": \"Настройки\",\n \"actions\": \"Действия\",\n \"custom\": \"Пользовательский\",\n \"builtin\": \"Встроенный\",\n \"addProvider\": \"Добавить провайдера\",\n \"addProviderTitle\": \"Добавить пользовательского провайдера\",\n \"providerIdLabel\": \"ID провайдера\",\n \"providerIdPlaceholder\": \"например: openai, google, anthropic\",\n \"providerIdHint\": \"Строчные буквы, цифры, дефисы и подчёркивания. Нельзя изменить позже.\",\n \"providerNameLabel\": \"Отображаемое имя\",\n \"providerNamePlaceholder\": \"например: OpenAI, Google Gemini\",\n \"defaultBaseUrlLabel\": \"Базовый URL по умолчанию\",\n \"defaultBaseUrlPlaceholder\": \"например: https://api.example.com\",\n \"apiKeyPrefixLabel\": \"Префикс API-ключа (необязательно)\",\n \"apiKeyPrefixPlaceholder\": \"например: sk-\",\n \"providerCreated\": \"Провайдер «{{name}}» создан\",\n \"providerCreateFailed\": \"Не удалось создать провайдера\",\n \"deleteProvider\": \"Удалить провайдера\",\n \"deleteProviderConfirm\": \"Удалить пользовательского провайдера «{{name}}» и все его модели? Это действие нельзя отменить.\",\n \"providerDeleted\": \"Провайдер «{{name}}» удалён\",\n \"providerDeleteFailed\": \"Не удалось удалить провайдера\",\n \"manageModels\": \"Модели\",\n \"manageModelsTitle\": \"{{provider}} — Управление моделями\",\n \"userAdded\": \"Добавлено пользователем\",\n \"addModel\": \"Добавить модель\",\n \"addModelTitle\": \"Добавить модель в {{provider}}\",\n \"modelIdLabel\": \"ID модели\",\n \"modelIdPlaceholder\": \"например: gpt-4o, gemini-2.0-flash\",\n \"modelNameLabel\": \"Название модели\",\n \"modelNameRequired\": \"Пожалуйста, введите название модели\",\n \"modelNamePlaceholder\": \"например: GPT-4o, Gemini 2.0 Flash\",\n \"modelAdded\": \"Модель «{{name}}» добавлена\",\n \"modelAddFailed\": \"Не удалось добавить модель\",\n \"removeModel\": \"Удалить\",\n \"removeModelConfirm\": \"Удалить модель «{{name}}» из {{provider}}?\",\n \"modelRemoved\": \"Модель «{{name}}» удалена\",\n \"modelRemoveFailed\": \"Не удалось удалить модель\",\n \"modelsCount\": \"{{count}} моделей\",\n \"noModels\": \"Нет моделей\",\n \"addModelFirst\": \"Сначала добавьте модель\",\n \"local\": \"Локальные\",\n \"localType\": \"Тип\",\n \"localEmbedded\": \"Встроенная (в процессе)\",\n \"localDownloadFirst\": \"Сначала скачайте модель\",\n \"localDownloadModel\": \"Скачать модель\",\n \"localModelsTitle\": \"{{provider}} — Локальные модели\",\n \"localNoModels\": \"Пока нет скачанных моделей\",\n \"localRepoId\": \"ID репозитория\",\n \"localRepoIdRequired\": \"Пожалуйста, введите ID репозитория\",\n \"localRepoIdPlaceholder\": \"например: TheBloke/Mistral-7B-GGUF\",\n \"localFilename\": \"Имя файла (необязательно)\",\n \"localFilenamePlaceholder\": \"например: mistral-7b.Q4_K_M.gguf\",\n \"localFilenameHint\": \"Оставьте пустым для автоматического выбора лучшей квантизации\",\n \"localSource\": \"Источник\",\n \"localDownloadSuccess\": \"Модель успешно скачана\",\n \"localDownloadFailed\": \"Не удалось скачать модель\",\n \"localDeleteModel\": \"Удалить модель\",\n \"localDeleteConfirm\": \"Удалить локальную модель «{{name}}»? Файл модели будет удалён с диска.\",\n \"localModelDeleted\": \"Модель «{{name}}» удалена\",\n \"localDeleteFailed\": \"Не удалось удалить модель\",\n \"localDownloadPending\": \"Подготовка к загрузке...\",\n \"localDownloading\": \"Загрузка {{repo}}... Это может занять несколько минут.\",\n \"localDownloadNavigateHint\": \"Вы можете перейти на другую страницу — загрузка продолжится в фоне.\",\n \"localDownloadInProgress\": \"Загрузка уже выполняется\",\n \"localCancelDownload\": \"Отменить загрузку\",\n \"localCancelDownloadConfirm\": \"Отменить загрузку «{{repo}}»?\",\n \"localDownloadCancelled\": \"Загрузка отменена\",\n \"localCancelDownloadFailed\": \"Не удалось отменить загрузку\",\n \"ollamaModelNamePlaceholder\": \"например: mistral:7b, qwen3:8b\",\n \"testConnection\": \"Проверить подключение\",\n \"testConnectionSuccess\": \"Проверка подключения прошла успешно\",\n \"testConnectionFailed\": \"Проверка подключения не удалась\",\n \"testConnectionError\": \"Произошла ошибка при проверке подключения\",\n \"discoverModels\": \"Обнаружить модели\",\n \"discoverModelsFailed\": \"Не удалось обнаружить модели\",\n \"ollamaFetchModelsFailed\": \"Не удалось получить список моделей Ollama. Проверьте подробности ошибки.\",\n \"modelTestFailed\": \"Проверка модели не пройдена, проверьте корректность ID модели\",\n \"modelTestFailedConfirm\": \"Тест подключения модели не пройден: {{message}}. Всё равно добавить эту модель?\",\n \"autoDiscoveredAndAdded\": \"Автоматически обнаружено {{count}} моделей и добавлено {{added}} новых\",\n \"autoDiscoveredNoNew\": \"Автоматически обнаружено {{count}} моделей; список моделей уже актуален\",\n \"autoDiscoverFailed\": \"Автоматическое обнаружение моделей не удалось; вы можете добавить модели вручную\"\n },\n \"agentConfig\": {\n \"title\": \"Конфигурация\",\n \"description\": \"Настройка параметров выполнения агента\",\n \"reactAgentTitle\": \"Агент ReAct\",\n \"contextManagementTitle\": \"Управление контекстом\",\n \"maxIters\": \"Макс. итераций\",\n \"maxItersTooltip\": \"Максимальное число итераций рассуждение-действие для агента ReAct\",\n \"maxItersPlaceholder\": \"Введите макс. число итераций\",\n \"maxItersRequired\": \"Требуется указать макс. число итераций\",\n \"maxItersMin\": \"Макс. число итераций должно быть не меньше 1\",\n \"maxInputLength\": \"Макс. длина входа\",\n \"maxInputLengthTooltip\": \"Максимальная длина входа (токены) для окна контекста модели\",\n \"maxInputLengthPlaceholder\": \"Введите макс. длину входа\",\n \"maxInputLengthRequired\": \"Требуется указать макс. длину входа\",\n \"maxInputLengthMin\": \"Макс. длина входа должна быть не меньше 1000\",\n \"contextCompactRatio\": \"Коэффициент сжатия контекста\",\n \"contextCompactRatioTooltip\": \"Доля контекста для сжатия при заполнении\",\n \"contextCompactRatioRequired\": \"Требуется указать коэффициент сжатия контекста\",\n \"contextCompactThreshold\": \"Порог сжатия контекста\",\n \"contextCompactThresholdTooltip\": \"Порог сжатия контекста (токены), автоматически вычисляется из макс. длины входа и коэффициента сжатия\",\n \"contextCompactThresholdPlaceholder\": \"Автоматически\",\n \"contextCompactReserveRatio\": \"Коэффициент резерва контекста\",\n \"contextCompactReserveRatioTooltip\": \"Доля контекста для резерва при сжатии\",\n \"contextCompactReserveRatioRequired\": \"Требуется указать коэффициент резерва контекста\",\n \"contextCompactReserveThreshold\": \"Порог резерва контекста\",\n \"contextCompactReserveThresholdTooltip\": \"Порог резерва контекста (токены), автоматически вычисляется из макс. длины входа и коэффициента резерва\",\n \"contextCompactReserveThresholdPlaceholder\": \"Автоматически\",\n \"toolResultCompactRecentN\": \"recent_n результатов инструментов\",\n \"toolResultCompactRecentNTooltip\": \"Количество результатов инструментов для использования порога недавних сообщений\",\n \"toolResultCompactRecentNRequired\": \"recent_n результатов инструментов обязательно\",\n \"toolResultCompactOldThreshold\": \"Макс. символов для результатов инструментов за пределами recent_n\",\n \"toolResultCompactOldThresholdTooltip\": \"Результаты инструментов за пределами recent_n, превышающие этот лимит, будут сжаты\",\n \"toolResultCompactOldThresholdPlaceholder\": \"Введите порог символов\",\n \"toolResultCompactOldThresholdRequired\": \"Макс. символов для результатов за пределами recent_n обязательно\",\n \"toolResultCompactRecentThreshold\": \"Макс. символов для результатов инструментов в пределах recent_n\",\n \"toolResultCompactRecentThresholdTooltip\": \"Результаты инструментов в пределах recent_n, превышающие этот лимит, будут сжаты\",\n \"toolResultCompactRecentThresholdPlaceholder\": \"Введите порог символов\",\n \"toolResultCompactRecentThresholdRequired\": \"Макс. символов для результатов в пределах recent_n обязательно\",\n \"toolResultCompactRetentionDays\": \"Дни хранения файлов результатов инструментов\",\n \"toolResultCompactRetentionDaysTooltip\": \"Количество дней хранения сжатых файлов, просроченные файлы удаляются автоматически\",\n \"toolResultCompactRetentionDaysRequired\": \"Дни хранения файлов результатов инструментов обязательны\",\n \"language\": \"Язык агента\",\n \"languageTooltip\": \"Язык файлов персонажа агента (SOUL.md, AGENTS.md и др.). При смене языка MD-файлы будут скопированы на выбранном языке.\",\n \"languageConfirmTitle\": \"Смена языка агента\",\n \"languageConfirmContent\": \"При смене языка следующие файлы будут перезаписаны версией на новом языке:\\n\\n SOUL.md, AGENTS.md, PROFILE.md, MEMORY.md, BOOTSTRAP.md, HEARTBEAT.md\\n\\nЕсли вы вносили изменения в эти файлы, сначала сделайте резервную копию. Остальные файлы не будут затронуты.\",\n \"languageConfirmOk\": \"Сменить язык\",\n \"languageSaveSuccess\": \"Язык успешно обновлён\",\n \"languageSaveSuccessWithFiles\": \"Язык обновлён, скопировано файлов: {{count}}\",\n \"languageSaveFailed\": \"Не удалось обновить язык\",\n \"timezone\": \"Часовой пояс пользователя\",\n \"timezoneTooltip\": \"Используется для запланированных задач, отображения времени и контекста агента. По умолчанию — системный часовой пояс.\",\n \"timezoneRequired\": \"Пожалуйста, выберите часовой пояс\",\n \"selectTimezone\": \"Выберите часовой пояс\",\n \"timezoneSaveSuccess\": \"Часовой пояс обновлён\",\n \"timezoneSaveFailed\": \"Не удалось обновить часовой пояс\",\n \"saveSuccess\": \"Конфигурация успешно сохранена\",\n \"saveFailed\": \"Не удалось сохранить конфигурацию\",\n \"loadFailed\": \"Не удалось загрузить конфигурацию\"\n },\n \"tools\": {\n \"title\": \"Встроенные инструменты\",\n \"description\": \"Управляйте встроенными инструментами и их статусом. Отключённые инструменты не будут доступны агенту.\",\n \"emptyState\": \"Нет настроенных инструментов\",\n \"loadError\": \"Не удалось загрузить инструменты\",\n \"enableSuccess\": \"Инструмент успешно включён\",\n \"disableSuccess\": \"Инструмент успешно отключён\",\n \"toggleError\": \"Не удалось изменить статус инструмента\",\n \"enableAll\": \"Включить все\",\n \"disableAll\": \"Отключить все\",\n \"enableAllSuccess\": \"Все инструменты включены\",\n \"disableAllSuccess\": \"Все инструменты отключены\",\n \"allEnabled\": \"Все инструменты уже включены\",\n \"allDisabled\": \"Все инструменты уже отключены\"\n },\n \"modelConfig\": {\n \"promptTitle\": \"Требуется LLM-модель — выберите в Chat после настройки\",\n \"promptMessage\": \"Для работы чата нужна LLM-модель. Сначала настройте модель, затем выберите её в селекторе моделей вверху страницы Chat.\",\n \"configureButton\": \"Настроить модель\",\n \"skipButton\": \"Пропустить\",\n \"chatDisabledTitle\": \"Чат отключён\",\n \"chatDisabledMessage\": \"Функции чата отключены, потому что не настроена модель. Настройте модель, чтобы включить чат.\",\n \"configureNow\": \"Настроить модель\",\n \"modelNotConfigured\": \"Перед использованием чата настройте модель в разделе «Настройки»\"\n },\n \"header\": {\n \"changelog\": \"Список изменений\",\n \"docs\": \"Документация\",\n \"tutorial\": \"Руководство\",\n \"faq\": \"FAQ\",\n \"github\": \"GitHub\"\n },\n \"theme\": {\n \"dark\": \"Тёмная\",\n \"light\": \"Светлая\",\n \"darkMode\": \"Тёмный режим\",\n \"lightMode\": \"Светлый режим\",\n \"switchToDark\": \"Переключить на тёмный режим\",\n \"switchToLight\": \"Переключить на светлый режим\"\n },\n \"sidebar\": {\n \"newVersion\": \"Доступна новая версия: v{{version}}, нажмите для обновления\",\n \"updateModal\": {\n \"title\": \"Доступна новая версия: v{{version}}\",\n \"viewReleases\": \"Открыть релизы\",\n \"close\": \"Закрыть\"\n }\n },\n \"chat\": {\n \"disclaimer\": \"Работает для вас, растёт вместе с вами\",\n \"greeting\": \"Привет, чем я могу помочь вам сегодня?\",\n \"description\": \"Я полезный ассистент, который поможет вам с вашими вопросами.\",\n \"prompt1\": \"Давайте начнём новое путешествие!\",\n \"prompt2\": \"Расскажи мне, какими навыками ты обладаешь?\",\n \"attachments\": {\n \"tooltip\": \"Поддерживаются документы, изображения, видео, аудио и другие форматы. Максимум 10 МБ на файл\",\n \"fileSizeLimit\": \"Размер одного файла не может превышать 10 МБ\"\n }\n },\n \"security\": {\n \"title\": \"Безопасность\",\n \"description\": \"Управление функциями безопасности инструментов и навыков.\",\n \"toolGuardTitle\": \"Защита инструментов\",\n \"toolGuardDescription\": \"Настройте сканирование безопасности для вызовов инструментов. Опасные операции потребуют вашего явного подтверждения перед выполнением.\",\n \"enabled\": \"Включить защиту инструментов\",\n \"enabledTooltip\": \"При включении вызовы инструментов сканируются на наличие опасных шаблонов перед выполнением\",\n \"guardedTools\": \"Защищённые инструменты\",\n \"guardedToolsTooltip\": \"Инструменты, требующие подтверждения при обнаружении опасных шаблонов. Оставьте пустым для использования набора по умолчанию.\",\n \"guardedToolsPlaceholder\": \"Выберите инструменты или введите пользовательские имена\",\n \"deniedTools\": \"Запрещённые инструменты\",\n \"deniedToolsTooltip\": \"Инструменты, которые всегда отклоняются без запроса подтверждения\",\n \"deniedToolsPlaceholder\": \"Выберите инструменты для запрета\",\n \"saveSuccess\": \"Настройки защиты инструментов сохранены\",\n \"saveFailed\": \"Не удалось сохранить настройки защиты инструментов\",\n \"loadFailed\": \"Не удалось загрузить настройки защиты инструментов\",\n \"rules\": {\n \"title\": \"Правила обнаружения\",\n \"description\": \"Правила определяют шаблоны регулярных выражений, которые вызывают оповещения безопасности. Встроенные правила можно отключить; пользовательские правила можно добавлять, редактировать или удалять.\",\n \"id\": \"ID правила\",\n \"severity\": \"Серьёзность\",\n \"descriptionCol\": \"Описание\",\n \"source\": \"Источник\",\n \"actions\": \"Действия\",\n \"builtin\": \"Встроенное\",\n \"custom\": \"Пользовательское\",\n \"enable\": \"Включить\",\n \"disable\": \"Отключить\",\n \"edit\": \"Редактировать\",\n \"delete\": \"Удалить\",\n \"add\": \"Добавить правило\",\n \"addTitle\": \"Добавить пользовательское правило\",\n \"editTitle\": \"Редактировать пользовательское правило\",\n \"ruleId\": \"ID правила\",\n \"ruleIdRequired\": \"ID правила обязателен\",\n \"duplicateId\": \"Правило с таким ID уже существует\",\n \"tools\": \"Целевые инструменты\",\n \"toolsPlaceholder\": \"Оставьте пустым для совпадения со всеми инструментами\",\n \"params\": \"Целевые параметры\",\n \"paramsPlaceholder\": \"Оставьте пустым для совпадения со всеми параметрами\",\n \"severityLabel\": \"Серьёзность\",\n \"categoryLabel\": \"Категория\",\n \"patterns\": \"Шаблоны регулярных выражений\",\n \"patternsRequired\": \"Требуется хотя бы один шаблон\",\n \"patternsTooltip\": \"По одному регулярному выражению в строке. Сопоставляется со значениями параметров инструмента (без учёта регистра).\",\n \"excludePatterns\": \"Шаблоны исключения\",\n \"excludePatternsTooltip\": \"По одному регулярному выражению в строке. Если совпадает, правило пропускается.\",\n \"descriptionLabel\": \"Описание\",\n \"descriptionPlaceholder\": \"Что обнаруживает это правило?\",\n \"remediationLabel\": \"Рекомендация\",\n \"remediationPlaceholder\": \"Рекомендуемое действие при срабатывании правила\",\n \"preview\": \"Просмотр\",\n \"previewTitle\": \"Детали правила\",\n \"actionLabel\": \"Действие\",\n \"actionApproval\": \"Требуется одобрение\",\n \"allTools\": \"Все инструменты\",\n \"allParams\": \"Все параметры\",\n \"descriptions\": {\n \"TOOL_CMD_DANGEROUS_RM\": \"Обнаруживает команду rm, которая может привести к потере данных\",\n \"TOOL_CMD_DANGEROUS_MV\": \"Обнаруживает команду mv, которая может неожиданно переместить или перезаписать файлы\",\n \"TOOL_CMD_FS_DESTRUCTION\": \"Обнаруживает команды низкоуровневого форматирования или очистки дисков\",\n \"TOOL_CMD_DOS_FORK_BOMB\": \"Обнаруживает классические Bash fork-бомбы и массовое завершение процессов\",\n \"TOOL_CMD_PIPE_TO_SHELL\": \"Обнаруживает паттерны 'curl | bash' для загрузки и немедленного выполнения удалённых скриптов\",\n \"TOOL_CMD_REVERSE_SHELL\": \"Обнаруживает попытки создания обратных оболочек или несанкционированных сетевых туннелей\",\n \"TOOL_CMD_SYSTEM_TAMPERING\": \"Обнаруживает доступ к заданиям cron, SSH-ключам или правам sudo (включая чтение и изменение)\",\n \"TOOL_CMD_UNSAFE_PERMISSIONS\": \"Обнаруживает глобальное понижение прав доступа (chmod 777) или установку неизменяемых флагов\",\n \"TOOL_CMD_OBFUSCATED_EXEC\": \"Обнаруживает выполнение строк в кодировке base64, передаваемых напрямую в интерпретатор оболочки\"\n }\n },\n \"skillScanner\": {\n \"title\": \"Сканер навыков\",\n \"description\": \"Автоматическое сканирование навыков на наличие угроз безопасности перед активацией или установкой.\",\n \"mode\": \"Режим сканирования\",\n \"modeTooltip\": \"Управление поведением сканера: блокировка, только предупреждение или отключение\",\n \"modeBlock\": \"Блокировать\",\n \"modeWarn\": \"Только предупреждение\",\n \"modeOff\": \"Выключен\",\n \"timeout\": \"Таймаут сканирования (секунды)\",\n \"timeoutTooltip\": \"Максимальное время ожидания завершения сканирования (5-300 секунд)\",\n \"saveSuccess\": \"Настройки сканера навыков сохранены\",\n \"saveFailed\": \"Не удалось сохранить настройки сканера навыков\",\n \"scanAlerts\": {\n \"title\": \"Оповещения сканирования\",\n \"empty\": \"Нет оповещений безопасности\",\n \"clearAll\": \"Очистить все\",\n \"clearConfirm\": \"Очистить все оповещения сканирования?\",\n \"skillName\": \"Навык\",\n \"action\": \"Действие\",\n \"actionBlocked\": \"Заблокировано\",\n \"actionWarned\": \"Предупреждение\",\n \"time\": \"Время\",\n \"actions\": \"Действия\",\n \"allowSkill\": \"Добавить в белый список\",\n \"remove\": \"Удалить\",\n \"viewFindings\": \"Подробности\"\n },\n \"whitelist\": {\n \"title\": \"Белый список\",\n \"empty\": \"Белый список пуст\",\n \"skillName\": \"Навык\",\n \"addedAt\": \"Добавлено\",\n \"contentHash\": \"Хеш содержимого\",\n \"actions\": \"Действия\",\n \"remove\": \"Удалить\",\n \"removeConfirm\": \"Удалить этот навык из белого списка?\",\n \"addSuccess\": \"Навык добавлен в белый список\",\n \"removeSuccess\": \"Навык удалён из белого списка\",\n \"addFailed\": \"Не удалось добавить навык в белый список\",\n \"removeFailed\": \"Не удалось удалить навык из белого списка\",\n \"removeWillDisable\": \"После удаления навык также будет отключён.\",\n \"removeAndDisabled\": \"Навык удалён из белого списка и отключён\"\n },\n \"scanError\": {\n \"title\": \"Обнаружены проблемы безопасности\",\n \"description\": \"Обнаружены следующие проблемы безопасности:\",\n \"warnDescription\": \"Обнаружены проблемы безопасности, но навык был включён (режим предупреждения):\",\n \"goToWhitelist\": \"Перейти к белому списку\"\n }\n }\n },\n \"login\": {\n \"title\": \"Вход в CoPaw\",\n \"registerTitle\": \"Создание аккаунта\",\n \"firstUserHint\": \"Создайте учётную запись администратора для начала работы\",\n \"usernamePlaceholder\": \"Имя пользователя\",\n \"passwordPlaceholder\": \"Пароль\",\n \"usernameRequired\": \"Пожалуйста, введите имя пользователя\",\n \"passwordRequired\": \"Пожалуйста, введите пароль\",\n \"submit\": \"Войти\",\n \"register\": \"Зарегистрироваться\",\n \"failed\": \"Ошибка входа, проверьте учётные данные\",\n \"registerSuccess\": \"Регистрация прошла успешно\",\n \"registerFailed\": \"Ошибка регистрации\",\n \"authNotEnabled\": \"Аутентификация не включена\",\n \"logout\": \"Выйти\",\n \"logoutSuccess\": \"Вы успешно вышли\",\n \"sessionExpired\": \"Сессия истекла, пожалуйста, войдите снова\",\n \"unauthorized\": \"Не авторизован, пожалуйста, войдите\"\n },\n \"voiceTranscription\": {\n \"title\": \"Транскрипция голоса\",\n \"description\": \"Настройте обработку входящих аудио- и голосовых сообщений.\",\n \"loadFailed\": \"Не удалось загрузить настройки аудиорежима\",\n \"saveSuccess\": \"Аудиорежим сохранён\",\n \"saveFailed\": \"Не удалось сохранить аудиорежим\",\n \"audioModeLabel\": \"Аудиорежим\",\n \"audioModeDescription\": \"Выберите, как голосовые сообщения из каналов (Discord, Telegram и др.) обрабатываются перед отправкой модели.\",\n \"modeAuto\": \"Авто (рекомендуется)\",\n \"modeAutoDesc\": \"Транскрибировать аудио в текст через выбранный провайдер, затем отправить текст модели. Если транскрипция отключена или недоступна, отображается заглушка «файл загружен». В этом режиме аудио не отправляется модели напрямую. Работает со всеми моделями.\",\n \"modeNative\": \"Нативное аудио\",\n \"modeNativeDesc\": \"Отправлять аудиофайл модели напрямую без транскрипции. Это единственный режим, передающий аудио модели. Работает только с моделями, поддерживающими аудио (например, gpt-4o-audio). Большинство моделей не поддерживают этот режим.\",\n \"ffmpegReady\": \"ffmpeg установлен. Конвертация аудио для нативного режима доступна.\",\n \"ffmpegMissing\": \"ffmpeg не установлен.\",\n \"ffmpegMissingDesc\": \"Нативный аудиорежим требует ffmpeg для конвертации аудиоформатов (например, .ogg в .wav). Установите ffmpeg как системный пакет для включения этого режима.\",\n \"providerTypeLabel\": \"Провайдер транскрипции\",\n \"providerTypeDescription\": \"Выберите бэкенд транскрипции. Если голосовая транскрипция не нужна, выберите «Отключено».\",\n \"providerTypeDisabled\": \"Отключено\",\n \"providerTypeDisabledDesc\": \"Без транскрипции. Голосовые сообщения будут отображаться как заглушка «файл загружен».\",\n \"providerTypeWhisperApi\": \"Whisper API\",\n \"providerTypeWhisperApiDesc\": \"Использовать OpenAI-совместимый Whisper API от настроенного провайдера (например, OpenAI, Ollama).\",\n \"providerTypeLocalWhisper\": \"Локальный Whisper\",\n \"providerTypeLocalWhisperDesc\": \"Запускать транскрипцию локально с помощью библиотеки openai-whisper. Требуются ffmpeg и openai-whisper.\",\n \"localWhisperReady\": \"Локальный Whisper готов к работе. ffmpeg и openai-whisper установлены.\",\n \"localWhisperMissing\": \"Локальный Whisper не готов. Необходимо установить недостающие зависимости.\",\n \"localWhisperMissingDesc\": \"ffmpeg: {{ffmpeg}} | openai-whisper: {{whisper}}. Установите недостающие зависимости: ffmpeg (системный пакет) и openai-whisper (uv pip install openai-whisper или установите CoPaw с опцией [whisper]).\",\n \"providerLabel\": \"Провайдер Whisper API\",\n \"providerDescription\": \"Выберите провайдера для транскрипции аудио через Whisper API. Отображаются только провайдеры с совместимым эндпоинтом.\",\n \"providerPlaceholder\": \"Выберите провайдера...\",\n \"noProvidersWarning\": \"Не найдено провайдеров для транскрипции. Настройте провайдер OpenAI для включения голосовой транскрипции.\",\n \"transcriptionInfoTitle\": \"Как работает транскрипция\",\n \"transcriptionInfoDesc\": \"Whisper API транскрипция использует OpenAI-совместимый эндпоинт /v1/audio/transcriptions. Необходим провайдер с поддержкой Whisper (например, OpenAI). Выберите конкретного провайдера выше для включения транскрипции.\",\n \"transcriptionInfoDescLocal\": \"Локальная Whisper транскрипция запускает библиотеку openai-whisper непосредственно на вашем устройстве. Требуются ffmpeg (для декодирования аудио) и пакет openai-whisper. API-ключ и подключение к интернету не нужны. Установка: uv pip install 'copaw[whisper]'.\"\n }\n}\n" }, { "path": "console/src/locales/zh.json", "content": "{\n \"common\": {\n \"save\": \"保存\",\n \"reset\": \"重置\",\n \"cancel\": \"取消\",\n \"confirm\": \"确认\",\n \"delete\": \"删除\",\n \"edit\": \"编辑\",\n \"create\": \"创建\",\n \"upload\": \"上传\",\n \"download\": \"下载\",\n \"refresh\": \"刷新\",\n \"enable\": \"启用\",\n \"disable\": \"禁用\",\n \"enabled\": \"已启用\",\n \"disabled\": \"已禁用\",\n \"preview\": \"预览\",\n \"content\": \"内容\",\n \"loading\": \"加载中...\",\n \"copy\": \"复制\",\n \"copied\": \"已复制到剪贴板\",\n \"copyFailed\": \"复制到剪贴板失败\",\n \"contentPlaceholder\": \"输入内容...\",\n \"help\": \"帮助\",\n \"close\": \"关闭\",\n \"actions\": \"操作\",\n \"total\": \"共 {{count}} 条\"\n },\n \"nav\": {\n \"chat\": \"聊天\",\n \"control\": \"控制\",\n \"channels\": \"频道\",\n \"sessions\": \"会话\",\n \"cronJobs\": \"定时任务\",\n \"heartbeat\": \"心跳\",\n \"agent\": \"智能体\",\n \"workspace\": \"工作区\",\n \"skills\": \"技能\",\n \"tools\": \"工具\",\n \"mcp\": \"MCP\",\n \"agentConfig\": \"运行配置\",\n \"agents\": \"智能体管理\",\n \"settings\": \"设置\",\n \"models\": \"模型\",\n \"environments\": \"环境变量\",\n \"security\": \"安全\",\n \"tokenUsage\": \"Token 消耗\",\n \"voiceTranscription\": \"语音转写\"\n },\n \"workspace\": {\n \"title\": \"工作区\",\n \"workspacePath\": \"工作区路径：\",\n \"noFiles\": \"没有文件\",\n \"coreFiles\": \"核心文件\",\n \"coreFilesDesc\": \"引导角色、身份和工具指南。\",\n \"uploadTooltip\": \"引导角色、身份和工具指南。（仅支持 ZIP 文件，最大 100MB）\",\n \"selectFile\": \"选择文件进行编辑\",\n \"fileContent\": \"文件内容...\",\n \"uploadSuccess\": \"文件上传成功\",\n \"uploadFailed\": \"文件上传失败\",\n \"downloadSuccess\": \"工作区下载成功\",\n \"downloadFailed\": \"工作区下载失败\",\n \"zipOnly\": \"仅支持上传 .zip 文件\",\n \"fileSizeExceeded\": \"文件大小超过 100MB 限制。当前文件：{{size}}MB\",\n \"systemPromptToggleTooltip\": \"启用/禁用此文件加载到系统提示词\",\n \"memoryFileWarning\": \"MEMORY.md 一般是由 agent 主动调用工具按需查询和加载，放到 system prompt 里面可能会导致上下文过长\",\n \"configUpdated\": \"系统提示词配置已更新\",\n \"configUpdateFailed\": \"更新系统提示词配置失败\",\n \"attribution\": \"工作区设计部分灵感源自 OpenClaw 项目，在此表示感谢 🐾\",\n \"saveSuccess\": \"保存成功\",\n \"saveFailed\": \"保存失败\"\n },\n \"agent\": {\n \"management\": \"智能体管理\",\n \"pageDescription\": \"创建、配置和管理多个 AI 智能体，支持自定义工作空间和身份。\",\n \"name\": \"名称\",\n \"id\": \"ID\",\n \"description\": \"描述\",\n \"workspace\": \"工作区路径\",\n \"create\": \"创建智能体\",\n \"createTitle\": \"创建新智能体\",\n \"createSuccess\": \"智能体创建成功\",\n \"createFailed\": \"智能体创建失败\",\n \"edit\": \"编辑\",\n \"editTitle\": \"编辑智能体 - {{name}}\",\n \"updateSuccess\": \"智能体更新成功\",\n \"updateFailed\": \"智能体更新失败\",\n \"delete\": \"删除\",\n \"deleteConfirm\": \"确认删除智能体\",\n \"deleteConfirmDesc\": \"删除后智能体将不可用，但工作区文件会保留\",\n \"deleteSuccess\": \"智能体删除成功\",\n \"deleteFailed\": \"智能体删除失败\",\n \"selectAgent\": \"选择智能体\",\n \"currentWorkspace\": \"当前智能体\",\n \"switchSuccess\": \"智能体切换成功\",\n \"switchFailed\": \"智能体切换失败\",\n \"loadFailed\": \"加载智能体列表失败\",\n \"loadConfigFailed\": \"加载智能体配置失败\",\n \"saveFailed\": \"保存智能体失败\",\n \"idRequired\": \"请输入智能体ID\",\n \"idPattern\": \"ID只能包含小写字母、数字、下划线和连字符\",\n \"idPlaceholder\": \"例如：my-agent\",\n \"nameRequired\": \"请输入智能体名称\",\n \"namePlaceholder\": \"例如：我的智能体\",\n \"descriptionPlaceholder\": \"简要描述这个智能体的用途...\",\n \"workspaceHelp\": \"留空将自动生成在 ~/.copaw/workspaces/ 目录\",\n \"defaultNotEditable\": \"默认智能体不允许编辑\",\n \"defaultNotDeletable\": \"默认智能体不允许删除\"\n },\n \"skills\": {\n \"title\": \"技能\",\n \"description\": \"管理智能体技能和能力。\",\n \"importSkills\": \"导入技能\",\n \"enterSkillUrl\": \"输入技能URL\",\n \"supportedSkillUrlSources\": \"当前支持的技能 URL 来源：\",\n \"urlExamples\": \"URL 示例：\",\n \"invalidSkillUrlSource\": \"技能 URL 当前需要以 https://skills.sh/、https://clawhub.ai/、https://skillsmp.com/、https://lobehub.com/、https://market.lobehub.com/、https://github.com/ 或 https://modelscope.cn/skills/ 开头\",\n \"source\": \"来源\",\n \"path\": \"路径\",\n \"skillDescription\": \"描述\",\n \"createSkill\": \"创建技能\",\n \"viewSkill\": \"查看技能\",\n \"editSkill\": \"编辑技能\",\n \"skillName\": \"技能名称\",\n \"skillContent\": \"技能内容\",\n \"pleaseInputName\": \"请输入技能名称\",\n \"pleaseInputContent\": \"请输入技能内容\",\n \"skillNamePlaceholder\": \"例如：weather_query\",\n \"contentPlaceholder\": \"【格式要求】\\n---\\nname: 技能名称（必填，英文小写下划线）\\ndescription: 功能描述（必填，简洁清晰）\\n---\\n\\n技能实现内容（Markdown格式）\\n\\n【示例】\\n---\\nname: weather_query\\ndescription: 查询指定城市的天气信息\\n---\\n\\n## 功能\\n查询实时天气数据。\\n\\n## 使用\\n用户输入城市名，返回天气信息。\",\n \"createSuccess\": \"技能创建成功\",\n \"createFailed\": \"技能创建失败\",\n \"deleteConfirm\": \"确定要删除此技能吗？\",\n \"deleteSuccess\": \"技能删除成功\",\n \"deleteFailed\": \"技能删除失败\",\n \"updateSuccess\": \"技能更新成功\",\n \"updateFailed\": \"技能更新失败\",\n \"frontmatterRequired\": \"Skills内容必须以 --- 开头和结尾\",\n \"frontmatterNameRequired\": \"Skills 中缺少必填字段：name\",\n \"frontmatterDescriptionRequired\": \"Skills 中缺少必填字段：description\",\n \"editNotSupported\": \"后端API不支持编辑操作\",\n \"editNote\": \"注意：后端API不支持编辑技能。您只能查看或切换启用/禁用状态。\",\n \"create\": \"创建\",\n \"optimizeWithAI\": \"AI优化\",\n \"stopOptimize\": \"停止\",\n \"optimizeSuccess\": \"技能优化成功\",\n \"optimizeFailed\": \"技能优化失败\",\n \"noContentToOptimize\": \"没有可优化的内容\",\n \"cancelImport\": \"取消导入\",\n \"importCancelled\": \"已取消技能导入\",\n \"importTimeout\": \"技能导入超时，请重试或检查网络。\",\n \"uploadSkill\": \"上传技能\",\n \"uploadSuccess\": \"技能上传成功\",\n \"uploadFailed\": \"技能上传失败\",\n \"uploadNoChange\": \"没有导入新技能，可能已存在相同技能\",\n \"zipOnly\": \"仅支持上传 .zip 文件\",\n \"fileSizeExceeded\": \"文件大小超过 100MB 限制。当前文件：{{size}}MB\"\n },\n \"mcp\": {\n \"title\": \"MCP 客户端\",\n \"description\": \"管理模型上下文协议（MCP）客户端以扩展智能体能力。\",\n \"create\": \"创建客户端\",\n \"formatSupport\": \"支持的格式\",\n \"emptyState\": \"暂无配置的 MCP 客户端\",\n \"loadError\": \"加载 MCP 客户端失败\",\n \"createSuccess\": \"MCP 客户端创建成功\",\n \"createError\": \"MCP 客户端创建失败\",\n \"updateSuccess\": \"MCP 客户端更新成功\",\n \"updateError\": \"MCP 客户端更新失败\",\n \"enableSuccess\": \"MCP 客户端启用成功\",\n \"disableSuccess\": \"MCP 客户端禁用成功\",\n \"toggleError\": \"切换 MCP 客户端状态失败\",\n \"deleteConfirm\": \"确定要删除此 MCP 客户端吗？\",\n \"deleteSuccess\": \"MCP 客户端删除成功\",\n \"deleteError\": \"MCP 客户端删除失败\"\n },\n \"heartbeat\": {\n \"title\": \"心跳\",\n \"description\": \"按固定间隔用 HEARTBEAT.md 内容执行自检。默认静默运行不影响当前对话，也可选择将回复发到上次对话频道。\",\n \"enabled\": \"开启心跳\",\n \"every\": \"执行间隔\",\n \"everyRequired\": \"请填写间隔\",\n \"everyMin\": \"间隔至少为 1\",\n \"unitMinutes\": \"分钟\",\n \"unitHours\": \"小时\",\n \"target\": \"回复目标\",\n \"targetMain\": \"静默运行（默认，不发送到频道）\",\n \"targetLast\": \"发到上次对话频道\",\n \"activeHours\": \"活跃时段（可选）\",\n \"activeStart\": \"开始时间\",\n \"activeEnd\": \"结束时间\",\n \"loadFailed\": \"加载心跳配置失败\",\n \"saveSuccess\": \"保存成功，心跳已热重载\",\n \"saveFailed\": \"保存心跳配置失败\"\n },\n \"cronJobs\": {\n \"title\": \"定时任务\",\n \"description\": \"创建和管理在指定时间自动执行的定时任务。\",\n \"createJob\": \"创建任务\",\n \"editJob\": \"编辑任务\",\n \"confirmDelete\": \"确认删除\",\n \"deleteConfirm\": \"确定要删除此定时任务吗？\",\n \"okText\": \"确定\",\n \"cancelText\": \"取消\",\n \"deleteText\": \"删除\",\n \"id\": \"任务ID\",\n \"name\": \"任务名称\",\n \"enabled\": \"启用状态\",\n \"scheduleType\": \"调度类型\",\n \"scheduleCron\": \"执行时间（Cron）\",\n \"scheduleCronLabel\": \"执行时间（Cron）\",\n \"scheduleTimezone\": \"时区\",\n \"cronType\": \"频率类型\",\n \"cronTypeHourly\": \"每小时\",\n \"cronTypeDaily\": \"每天\",\n \"cronTypeWeekly\": \"每周\",\n \"cronTypeCustom\": \"自定义\",\n \"cronTime\": \"执行时间\",\n \"cronDaysOfWeek\": \"星期\",\n \"cronDayMon\": \"周一\",\n \"cronDayTue\": \"周二\",\n \"cronDayWed\": \"周三\",\n \"cronDayThu\": \"周四\",\n \"cronDayFri\": \"周五\",\n \"cronDaySat\": \"周六\",\n \"cronDaySun\": \"周日\",\n \"cronCustomExpression\": \"Cron 表达式\",\n \"taskText\": \"任务描述\",\n \"action\": \"操作\",\n \"disable\": \"禁用\",\n \"executeNow\": \"立即执行\",\n \"edit\": \"编辑\",\n \"delete\": \"删除\",\n \"totalItems\": \"共 {{count}} 项\",\n \"perPage\": \"/ 页\",\n \"pleaseInputId\": \"请输入任务ID\",\n \"pleaseInputName\": \"请输入任务名称\",\n \"pleaseInputCron\": \"请输入Cron表达式\",\n \"pleaseSelectTaskType\": \"请选择任务类型\",\n \"pleaseInputRequest\": \"请输入请求内容\",\n \"pleaseInputChannel\": \"请输入目标频道\",\n \"pleaseInputUserId\": \"请输入目标用户ID\",\n \"pleaseInputSessionId\": \"请输入目标会话ID\",\n \"jobIdPlaceholder\": \"例如：daily-report-job\",\n \"jobNamePlaceholder\": \"例如：每日早报\",\n \"selectTimezone\": \"选择时区\",\n \"taskDescriptionPlaceholder\": \"简要描述这个任务的作用...\",\n \"invalidJsonFormat\": \"JSON格式无效\",\n \"jsonFormatRequired\": \"需要JSON格式\",\n \"taskType\": \"任务类型\",\n \"text\": \"任务描述\",\n \"requestInput\": \"请求内容\",\n \"requestSessionId\": \"请求会话ID\",\n \"requestUserId\": \"请求用户ID\",\n \"dispatchChannel\": \"目标频道\",\n \"dispatchTargetUserId\": \"目标用户ID\",\n \"dispatchTargetSessionId\": \"目标会话ID\",\n \"dispatchMode\": \"分发模式\",\n \"runtimeMaxConcurrency\": \"最大并发数\",\n \"runtimeTimeoutSeconds\": \"超时时间（秒）\",\n \"runtimeMisfireGraceSeconds\": \"错过执行宽限期（秒）\",\n \"idTooltip\": \"任务的唯一标识符。建议使用小写字母、数字、连字符和下划线。\",\n \"nameTooltip\": \"任务的友好名称，便于识别。\",\n \"cronTooltip\": \"定义任务执行时间\",\n \"cronExample\": \"常用示例：'0 9 * * *' = 每天9点 | '*/30 * * * *' = 每30分钟 | '0 */2 * * *' = 每2小时 | '0 0 * * 0' = 每周日0点\",\n \"cronHelper\": \"不熟悉 Cron 表达式？\",\n \"cronHelperLink\": \"使用在线工具生成\",\n \"timezoneTooltip\": \"Cron 计划使用的时区。默认：UTC\",\n \"taskTypeTooltip\": \"选择 'text' 用于简单消息任务，选择 'agent' 用于复杂的智能体工作流。\",\n \"textTooltip\": \"可选：描述这个任务的作用，便于文档记录。\",\n \"requestInputTooltip\": \"JSON 格式的消息内容。这是智能体将接收和处理的内容。\",\n \"requestInputExample\": \"格式：[{\\\"role\\\":\\\"user\\\",\\\"content\\\":[{\\\"type\\\":\\\"text\\\",\\\"text\\\":\\\"您的消息内容\\\"}]}]\",\n \"requestSessionIdTooltip\": \"请求上下文的会话ID。不确定时使用 'default'。\",\n \"requestUserIdTooltip\": \"发起请求的用户ID。自动化任务使用 'system'。\",\n \"dispatchChannelTooltip\": \"响应将发送到的目标频道（例如：'console'、'discord'、'imessage'）。\",\n \"dispatchTargetUserIdTooltip\": \"在目标频道中接收响应的用户ID。\",\n \"dispatchTargetSessionIdTooltip\": \"在目标频道中传递响应的会话ID。\",\n \"dispatchModeTooltip\": \"选择 'stream' 获取实时响应，或选择 'final' 仅获取完整响应。\",\n \"maxConcurrencyTooltip\": \"此任务可以同时运行的最大数量。默认：1\",\n \"timeoutSecondsTooltip\": \"最大执行时间（秒）。超时将终止任务。\",\n \"misfireGraceSecondsTooltip\": \"错过执行的宽限期。如果任务错过计划时间超过此时长，将不会执行。\",\n \"executeNowTitle\": \"立即执行任务\",\n \"executeNowContent\": \"确定要立即执行任务 \\\"{{name}}\\\" 吗？\",\n \"executeNowConfirm\": \"立即执行\"\n },\n \"channels\": {\n \"title\": \"频道\",\n \"description\": \"管理和配置消息频道\",\n \"loading\": \"正在加载频道...\",\n \"configSaved\": \"配置保存成功\",\n \"configFailed\": \"配置保存失败\",\n \"channelType\": \"频道类型\",\n \"status\": \"状态\",\n \"totalItems\": \"共 {{count}} 项\",\n \"botPrefix\": \"机器人前缀\",\n \"filterToolMessages\": \"显示工具消息\",\n \"filterToolMessagesTooltip\": \"向用户显示工具调用和输出消息（关闭则隐藏）\",\n \"filterThinking\": \"显示思考过程\",\n \"filterThinkingTooltip\": \"向用户显示模型的思考/推理内容（关闭则隐藏）\",\n \"notSet\": \"未设置\",\n \"clickCardToEdit\": \"点击卡片进行编辑\",\n \"settings\": \"设置\",\n \"channelSettings\": \"频道设置\",\n \"pleaseInputDbPath\": \"请输入数据库路径\",\n \"pleaseInputPollInterval\": \"请输入轮询间隔\",\n \"discordBotToken\": \"Discord机器人令牌\",\n \"httpProxyPlaceholder\": \"http://127.0.0.1:18118\",\n \"httpProxyAuthPlaceholder\": \"用户名:密码\",\n \"dbPathPlaceholder\": \"~/Library/Messages/chat.db\",\n \"botPrefixPlaceholder\": \"@bot\",\n \"dmPolicy\": \"私聊策略\",\n \"dmPolicyTooltip\": \"控制谁可以通过私聊与机器人交互。开放：所有人；白名单：仅限授权用户\",\n \"groupPolicy\": \"群聊策略\",\n \"groupPolicyTooltip\": \"控制谁可以在群聊中与机器人交互。开放：所有人；白名单：仅限授权用户\",\n \"requireMention\": \"需要 @提及\",\n \"requireMentionTooltip\": \"开启后，群聊中仅在被 @提及 时才会回复\",\n \"policyOpen\": \"开放\",\n \"policyAllowlist\": \"白名单\",\n \"allowFrom\": \"白名单用户\",\n \"allowFromTooltip\": \"允许与机器人交互的用户 ID 列表。启用白名单后，用户私聊机器人即可在拒绝消息中看到自己的 ID\",\n \"allowFromPlaceholder\": \"输入用户ID后按回车添加\",\n \"denyMessage\": \"拒绝访问消息\",\n \"denyMessageTooltip\": \"自定义消息，当用户被拒绝访问时显示\",\n \"twilioAccountSid\": \"Twilio 账户 SID\",\n \"twilioAuthToken\": \"Twilio 认证令牌\",\n \"phoneNumber\": \"电话号码\",\n \"phoneNumberSid\": \"电话号码 SID\",\n \"phoneNumberSidHelp\": \"可在 Twilio 控制台的 Phone Numbers → Active Numbers 中找到。\",\n \"ttsProvider\": \"TTS 提供商\",\n \"ttsVoice\": \"TTS 语音\",\n \"sttProvider\": \"STT 提供商\",\n \"language\": \"语言\",\n \"welcomeGreeting\": \"欢迎语\",\n \"welcomeText\": \"欢迎消息\",\n \"welcomeTextTooltip\": \"用户当天首次进入机器人单聊会话时机器人自动发送的消息\",\n \"welcomeTextPlaceholder\": \"例如：你好！我是 CoPaw，有什么可以帮你的？\",\n \"loginWeCom\": \"扫码授权企业微信机器人\",\n \"wecomAuthHint\": \"点击按钮后会弹出企业微信二维码窗口，扫码确认后 Bot ID 与 Secret 将自动填入。\",\n \"wecomAuthSuccess\": \"企业微信机器人授权成功\",\n \"wecomWindowBlocked\": \"弹窗被浏览器拦截，请允许弹窗后重试。\",\n \"wecomCancelled\": \"授权已取消\",\n \"wecomAuthFailed\": \"授权失败：{{msg}}\",\n \"wecomSdkLoadFailed\": \"WeCom SDK 加载失败\",\n \"voiceSetupGuide\": \"请先注册 Twilio 账户并购买电话号码，然后在下方填写凭据。Account SID 和 Auth Token 可在 Twilio 控制台首页找到。Phone Number SID 在 Phone Numbers → Active Numbers 中查看。\",\n \"voiceSetupLink\": \"打开 Twilio 控制台\",\n \"xiaoyiSetupGuide\": \"请在华为开发者平台创建智能体并获取 AK/SK 和 Agent ID。AK/SK 可在凭证管理页面找到。\",\n \"filterAll\": \"全部\",\n \"builtin\": \"内置\",\n \"custom\": \"自定义\"\n },\n \"sessions\": {\n \"title\": \"会话\",\n \"description\": \"查看和管理活动聊天会话\",\n \"loading\": \"正在加载会话...\",\n \"confirmDelete\": \"确认删除\",\n \"deleteConfirm\": \"确定要删除此会话吗？\",\n \"batchDeleteConfirm\": \"确定要删除选中的 {{count}} 个会话吗？\",\n \"deleteSuccess\": \"会话删除成功\",\n \"deleteFailed\": \"会话删除失败\",\n \"batchDeleteButton\": \"批量删除\",\n \"filterUserId\": \"按用户ID筛选\",\n \"filterChannel\": \"按频道筛选\",\n \"allChannels\": \"全部频道\",\n \"totalItems\": \"共 {{count}} 项\",\n \"selectedItems\": \"已选 {{count}} 项\",\n \"editSession\": \"编辑会话\",\n \"pleaseInputName\": \"请输入会话名称\",\n \"sessionNamePlaceholder\": \"会话名称\"\n },\n \"environments\": {\n \"title\": \"环境变量\",\n \"description\": \"为智能体和技能配置键值环境变量。\",\n \"key\": \"键\",\n \"value\": \"值\",\n \"variableNamePlaceholder\": \"VARIABLE_NAME\",\n \"valuePlaceholder\": \"值\",\n \"insertRowBelow\": \"在下方插入行\",\n \"deleteRow\": \"删除行\",\n \"deleteVariable\": \"删除变量\",\n \"deleteConfirm\": \"删除 \\\"{{name}}\\\"?\",\n \"deleteSelected\": \"删除选中项\",\n \"deleteSelectedConfirm\": \"删除 {{label}}?\",\n \"keyRequired\": \"键为必填项\",\n \"invalidKeyFormat\": \"键格式无效\",\n \"duplicateKey\": \"键重复\",\n \"saveSuccess\": \"环境变量已保存\",\n \"saveFailed\": \"保存失败\",\n \"deleteSuccess\": \"\\\"{{name}}\\\" 已删除\",\n \"deleteFailed\": \"删除失败\",\n \"noVariables\": \"尚未配置环境变量。\",\n \"addVariable\": \"添加变量\",\n \"loading\": \"加载中…\",\n \"retry\": \"重试\",\n \"of\": \"共\",\n \"selected\": \"已选\",\n \"variable\": \"变量\",\n \"variables\": \"变量\",\n \"showValue\": \"显示值\",\n \"hideValue\": \"隐藏值\"\n },\n \"tokenUsage\": {\n \"title\": \"Token 消耗\",\n \"description\": \"查看一段时间内的 LLM Token 消耗，按日期和模型统计。\",\n \"totalTokens\": \"总 Token 数\",\n \"totalCalls\": \"总调用次数\",\n \"promptTokens\": \"输入 Token\",\n \"completionTokens\": \"输出 Token\",\n \"byModel\": \"按模型\",\n \"byDate\": \"按日期\",\n \"provider\": \"提供商\",\n \"model\": \"模型\",\n \"date\": \"日期\",\n \"refresh\": \"刷新\",\n \"loadFailed\": \"加载 Token 消耗数据失败\",\n \"noData\": \"所选时间段内暂无 Token 消耗数据\"\n },\n \"modelSelector\": {\n \"selectModel\": \"选择模型\",\n \"noConfiguredModels\": \"暂无已配置模型\",\n \"switchFailed\": \"切换模型失败\"\n },\n \"models\": {\n \"llmConfiguration\": \"LLM 配置\",\n \"providersTitle\": \"提供商\",\n \"providersDescription\": \"为每个提供商配置 API 密钥和端点。\",\n \"llmTitle\": \"LLM\",\n \"llmDescription\": \"从已授权的提供商中选择活动的 LLM 模型。\",\n \"configureProvider\": \"配置 {{name}}\",\n \"baseURL\": \"基础 URL\",\n \"apiKey\": \"API 密钥\",\n \"advancedConfig\": \"进阶配置\",\n \"generateConfig\": \"生成参数配置\",\n \"generateConfigHint\": \"使用 JSON 格式表示的生成参数配置项，会被展开传入到生成请求（`openai.chat.completions` 或 `anthropic.messages`）中。\",\n \"generateConfigInvalidJson\": \"请输入有效的 JSON\",\n \"generateConfigMustBeObject\": \"生成参数配置必须是 JSON 对象\",\n \"protocol\": \"协议\",\n \"protocolHint\": \"为当前配置选择提供商 API 协议。\",\n \"selectProtocol\": \"请选择协议\",\n \"protocolOpenAI\": \"OpenAI 兼容（Chat Completions）\",\n \"protocolAnthropic\": \"Anthropic（Messages API）\",\n \"currentKey\": \"当前密钥：{{key}}\",\n \"startsWith\": \"以 \\\"{{prefix}}\\\" 开头\",\n \"optionalSelfHosted\": \"自托管服务可选\",\n \"leaveBlankKeep\": \"留空以保持当前密钥\",\n \"enterApiKey\": \"输入 API 密钥 ({{prefix}}...)\",\n \"enterApiKeyOptional\": \"输入 API 密钥（可选）\",\n \"openAIEndpoint\": \"OpenAI 端点，例如 https://api.openai.com/v1\",\n \"openAICompatibleEndpoint\": \"OpenAI 兼容端点，例如 https://api.example.com（仅在你的服务要求时再追加 /v1）\",\n \"azureEndpointHint\": \"Azure OpenAI 端点，例如 https://.openai.azure.com/openai/v1\",\n \"anthropicEndpointHint\": \"Anthropic 端点，例如 https://api.anthropic.com\",\n \"ollamaEndpointHint\": \"Ollama 端点，例如 http://localhost:11434\",\n \"lmstudioEndpointHint\": \"LM Studio 端点，例如 http://localhost:1234/v1\",\n \"apiEndpointHint\": \"API 端点，例如 https://api.example.com\",\n \"pleaseEnterBaseURL\": \"请输入 API 基础 URL\",\n \"pleaseEnterValidURL\": \"请输入有效的 URL\",\n \"apiKeyShouldStart\": \"API 密钥应以 \\\"{{prefix}}\\\" 开头\",\n \"configurationSaved\": \"{{name}} 配置已保存\",\n \"failedToSaveConfig\": \"保存配置失败\",\n \"revokeAuthorization\": \"撤销授权\",\n \"revokeConfirmContent\": \"确定要移除 {{name}} 的 API 密钥吗？当前 LLM 模型配置也将被清除。\",\n \"revokeConfirmSimple\": \"确定要移除 {{name}} 的 API 密钥吗？\",\n \"authorizationRevoked\": \"{{name}} 授权已撤销，LLM 模型已清除\",\n \"authorizationRevokedSimple\": \"{{name}} 授权已撤销\",\n \"failedToRevoke\": \"撤销授权失败\",\n \"active\": \"活动：{{provider}} / {{model}}\",\n \"provider\": \"提供商\",\n \"model\": \"模型\",\n \"selectProvider\": \"选择提供商（必须已授权）\",\n \"selectModel\": \"选择模型\",\n \"llmModelUpdated\": \"LLM 模型已更新\",\n \"failedToSave\": \"保存失败\",\n \"saved\": \"已保存\",\n \"save\": \"保存\",\n \"cancel\": \"取消\",\n \"loading\": \"加载中...\",\n \"retry\": \"重试\",\n \"notSet\": \"未设置\",\n \"available\": \"可用\",\n \"unavailable\": \"不可用\",\n \"providerAvailable\": \"可用（有模型）\",\n \"providerNoModels\": \"未就绪（无模型）\",\n \"providerNotConfigured\": \"未就绪（未配置）\",\n \"settings\": \"设置\",\n \"actions\": \"操作\",\n \"custom\": \"自定义\",\n \"builtin\": \"内置\",\n \"addProvider\": \"添加提供商\",\n \"addProviderTitle\": \"添加自定义提供商\",\n \"providerIdLabel\": \"提供商 ID\",\n \"providerIdPlaceholder\": \"例如 openai, google, anthropic\",\n \"providerIdHint\": \"小写字母、数字、连字符、下划线，创建后不可更改。\",\n \"providerNameLabel\": \"显示名称\",\n \"providerNamePlaceholder\": \"例如 OpenAI, Google Gemini\",\n \"defaultBaseUrlLabel\": \"默认 Base URL\",\n \"defaultBaseUrlPlaceholder\": \"例如 https://api.example.com\",\n \"apiKeyPrefixLabel\": \"API Key 前缀（可选）\",\n \"apiKeyPrefixPlaceholder\": \"例如 sk-\",\n \"providerCreated\": \"提供商 \\\"{{name}}\\\" 已创建\",\n \"providerCreateFailed\": \"创建提供商失败\",\n \"deleteProvider\": \"删除提供商\",\n \"deleteProviderConfirm\": \"确定删除自定义提供商 \\\"{{name}}\\\" 及其所有模型？此操作不可撤销。\",\n \"providerDeleted\": \"提供商 \\\"{{name}}\\\" 已删除\",\n \"providerDeleteFailed\": \"删除提供商失败\",\n \"manageModels\": \"模型\",\n \"manageModelsTitle\": \"{{provider}} — 模型管理\",\n \"userAdded\": \"用户添加\",\n \"addModel\": \"添加模型\",\n \"addModelTitle\": \"为 {{provider}} 添加模型\",\n \"modelIdLabel\": \"模型 ID\",\n \"modelIdPlaceholder\": \"例如 gpt-4o, gemini-2.0-flash\",\n \"modelNameLabel\": \"模型名称\",\n \"modelNameRequired\": \"请输入模型名称\",\n \"modelNamePlaceholder\": \"例如 GPT-4o, Gemini 2.0 Flash\",\n \"modelAdded\": \"模型 \\\"{{name}}\\\" 已添加\",\n \"modelAddFailed\": \"添加模型失败\",\n \"removeModel\": \"移除\",\n \"removeModelConfirm\": \"确定从 {{provider}} 中移除模型 \\\"{{name}}\\\"？\",\n \"modelRemoved\": \"模型 \\\"{{name}}\\\" 已移除\",\n \"modelRemoveFailed\": \"移除模型失败\",\n \"modelsCount\": \"{{count}} 个模型\",\n \"noModels\": \"暂无模型\",\n \"addModelFirst\": \"请先添加模型\",\n \"local\": \"本地\",\n \"localType\": \"类型\",\n \"localEmbedded\": \"嵌入式（进程内）\",\n \"localDownloadFirst\": \"请先下载模型\",\n \"localDownloadModel\": \"下载模型\",\n \"localModelsTitle\": \"{{provider}} — 本地模型\",\n \"localNoModels\": \"暂无已下载的模型\",\n \"localRepoId\": \"仓库 ID\",\n \"localRepoIdRequired\": \"请输入仓库 ID\",\n \"localRepoIdPlaceholder\": \"例如 TheBloke/Mistral-7B-GGUF\",\n \"localFilename\": \"文件名（可选）\",\n \"localFilenamePlaceholder\": \"例如 mistral-7b.Q4_K_M.gguf\",\n \"localFilenameHint\": \"留空将自动选择最佳量化版本\",\n \"localSource\": \"来源\",\n \"localDownloadSuccess\": \"模型下载成功\",\n \"localDownloadFailed\": \"模型下载失败\",\n \"localDeleteModel\": \"删除模型\",\n \"localDeleteConfirm\": \"确定删除本地模型 \\\"{{name}}\\\"？模型文件将从磁盘中删除。\",\n \"localModelDeleted\": \"模型 \\\"{{name}}\\\" 已删除\",\n \"localDeleteFailed\": \"删除模型失败\",\n \"localDownloadPending\": \"准备下载...\",\n \"localDownloading\": \"正在下载 {{repo}}... 可能需要几分钟。\",\n \"localDownloadNavigateHint\": \"您可以离开此页面，下载将在后台继续进行。\",\n \"localDownloadInProgress\": \"已有下载任务正在进行\",\n \"localCancelDownload\": \"取消下载\",\n \"localCancelDownloadConfirm\": \"确定取消下载 \\\"{{repo}}\\\"？\",\n \"localDownloadCancelled\": \"下载已取消\",\n \"localCancelDownloadFailed\": \"取消下载失败\",\n \"ollamaModelNamePlaceholder\": \"例如 mistral:7b, qwen3:8b\",\n \"testConnection\": \"测试连接\",\n \"testConnectionSuccess\": \"连接测试成功\",\n \"testConnectionFailed\": \"连接测试失败\",\n \"testConnectionError\": \"测试连接时发生错误\",\n \"discoverModels\": \"自动获取模型\",\n \"discoverModelsFailed\": \"自动获取模型失败\",\n \"ollamaFetchModelsFailed\": \"获取 Ollama 模型列表失败，请查看错误详情。\",\n \"modelTestFailed\": \"模型验证失败，请检查模型ID是否正确\",\n \"modelTestFailedConfirm\": \"模型连接测试失败：{{message}}。是否仍要添加此模型？\",\n \"autoDiscoveredAndAdded\": \"已自动获取 {{count}} 个模型，并新增 {{added}} 个到可选列表\",\n \"autoDiscoveredNoNew\": \"已自动获取 {{count}} 个模型，当前列表已是最新\",\n \"autoDiscoverFailed\": \"自动获取模型失败，可在模型管理中手动添加\"\n },\n \"agentConfig\": {\n \"title\": \"运行配置\",\n \"description\": \"配置智能体运行参数\",\n \"reactAgentTitle\": \"ReAct 智能体\",\n \"contextManagementTitle\": \"上下文管理\",\n \"maxIters\": \"最大迭代次数\",\n \"maxItersTooltip\": \"ReAct 智能体的最大推理-行动迭代次数\",\n \"maxItersPlaceholder\": \"请输入最大迭代次数\",\n \"maxItersRequired\": \"最大迭代次数为必填项\",\n \"maxItersMin\": \"最大迭代次数必须大于等于 1\",\n \"maxInputLength\": \"最大输入长度\",\n \"maxInputLengthTooltip\": \"模型上下文窗口的最大输入长度（token 数）\",\n \"maxInputLengthPlaceholder\": \"请输入最大输入长度\",\n \"maxInputLengthRequired\": \"最大输入长度为必填项\",\n \"maxInputLengthMin\": \"最大输入长度必须大于等于 1000\",\n \"contextCompactRatio\": \"上下文压缩比例\",\n \"contextCompactRatioTooltip\": \"当上下文满时，压缩上下文的比例\",\n \"contextCompactRatioRequired\": \"上下文压缩比例为必填项\",\n \"contextCompactThreshold\": \"上下文压缩阈值\",\n \"contextCompactThresholdTooltip\": \"上下文压缩阈值（token 数），根据最大输入长度和上下文压缩比例自动计算\",\n \"contextCompactThresholdPlaceholder\": \"自动计算\",\n \"contextCompactReserveRatio\": \"上下文保留比例\",\n \"contextCompactReserveRatioTooltip\": \"压缩上下文时保留的比例\",\n \"contextCompactReserveRatioRequired\": \"上下文保留比例为必填项\",\n \"contextCompactReserveThreshold\": \"上下文保留阈值\",\n \"contextCompactReserveThresholdTooltip\": \"上下文保留阈值（token 数），根据最大输入长度和上下文保留比例自动计算\",\n \"contextCompactReserveThresholdPlaceholder\": \"自动计算\",\n \"toolResultCompactRecentN\": \"工具调用结果recent_n\",\n \"toolResultCompactRecentNTooltip\": \"使用最近消息阈值的工具调用结果数量\",\n \"toolResultCompactRecentNRequired\": \"工具调用结果recent_n为必填项\",\n \"toolResultCompactOldThreshold\": \"超出recent_n的工具调用结果的最大字符数\",\n \"toolResultCompactOldThresholdTooltip\": \"超出recent_n范围的工具调用结果，超过此字符数将被压缩\",\n \"toolResultCompactOldThresholdPlaceholder\": \"请输入字符阈值\",\n \"toolResultCompactOldThresholdRequired\": \"超出recent_n的工具调用结果最大字符数为必填项\",\n \"toolResultCompactRecentThreshold\": \"recent_n内的工具调用结果的最大字符数\",\n \"toolResultCompactRecentThresholdTooltip\": \"recent_n范围内的工具调用结果，超过此字符数将被压缩\",\n \"toolResultCompactRecentThresholdPlaceholder\": \"请输入字符阈值\",\n \"toolResultCompactRecentThresholdRequired\": \"recent_n内的工具调用结果最大字符数为必填项\",\n \"toolResultCompactRetentionDays\": \"工具调用的文件保留天数\",\n \"toolResultCompactRetentionDaysTooltip\": \"压缩后的工具结果文件保留天数，过期自动清理\",\n \"toolResultCompactRetentionDaysRequired\": \"工具调用的文件保留天数为必填项\",\n \"language\": \"智能体语言\",\n \"languageTooltip\": \"智能体人设文件（SOUL.md、AGENTS.md 等）使用的语言。切换语言后将自动重新复制对应语言的 MD 文件。\",\n \"languageConfirmTitle\": \"切换智能体语言\",\n \"languageConfirmContent\": \"切换语言将会覆盖以下文件为新语言的默认版本：\\n\\n SOUL.md、AGENTS.md、PROFILE.md、MEMORY.md、BOOTSTRAP.md、HEARTBEAT.md\\n\\n如果您已对这些文件进行过自定义修改，请提前备份。您自行添加的其他文件不受影响。\",\n \"languageConfirmOk\": \"切换语言\",\n \"languageSaveSuccess\": \"语言更新成功\",\n \"languageSaveSuccessWithFiles\": \"语言已更新，已复制 {{count}} 个 MD 文件\",\n \"languageSaveFailed\": \"语言更新失败\",\n \"timezone\": \"用户时区\",\n \"timezoneTooltip\": \"用于定时任务、时间显示和 Agent 上下文，默认使用系统时区。\",\n \"timezoneRequired\": \"请选择时区\",\n \"selectTimezone\": \"选择时区\",\n \"timezoneSaveSuccess\": \"时区更新成功\",\n \"timezoneSaveFailed\": \"时区更新失败\",\n \"saveSuccess\": \"配置保存成功\",\n \"saveFailed\": \"配置保存失败\",\n \"loadFailed\": \"配置加载失败\"\n },\n \"tools\": {\n \"title\": \"内置工具\",\n \"description\": \"管理内置工具及其启用状态。禁用的工具将不会提供给智能体使用。\",\n \"emptyState\": \"暂无工具配置\",\n \"loadError\": \"加载工具失败\",\n \"enableSuccess\": \"工具启用成功\",\n \"disableSuccess\": \"工具禁用成功\",\n \"toggleError\": \"切换工具状态失败\",\n \"enableAll\": \"全部启用\",\n \"disableAll\": \"全部禁用\",\n \"enableAllSuccess\": \"全部工具已启用\",\n \"disableAllSuccess\": \"全部工具已禁用\",\n \"allEnabled\": \"所有工具已处于启用状态\",\n \"allDisabled\": \"所有工具已处于禁用状态\"\n },\n \"modelConfig\": {\n \"promptTitle\": \"需要配置 LLM 模型，配置模型后在 Chat 页面选择\",\n \"promptMessage\": \"聊天功能需要 LLM 模型才能运行。请先配置模型，配置完成后在 Chat 页面顶部的模型选择器中选择即可使用。\",\n \"configureButton\": \"配置模型\",\n \"skipButton\": \"跳过\",\n \"chatDisabledTitle\": \"聊天已禁用\",\n \"chatDisabledMessage\": \"聊天功能已禁用，因为未配置模型。请配置模型以启用聊天功能。\",\n \"configureNow\": \"配置模型\",\n \"modelNotConfigured\": \"请先在设置中配置模型后再使用聊天功能\"\n },\n \"header\": {\n \"changelog\": \"更新日志\",\n \"docs\": \"文档\",\n \"tutorial\": \"教程\",\n \"faq\": \"常见问题\",\n \"github\": \"GitHub\"\n },\n \"theme\": {\n \"dark\": \"深色\",\n \"light\": \"浅色\",\n \"darkMode\": \"深色模式\",\n \"lightMode\": \"浅色模式\",\n \"switchToDark\": \"切换到深色模式\",\n \"switchToLight\": \"切换到浅色模式\"\n },\n \"sidebar\": {\n \"newVersion\": \"发现新版本 v{{version}}，点击前往升级\",\n \"updateModal\": {\n \"title\": \"发现新版本 v{{version}}\",\n \"viewReleases\": \"查看 Releases\",\n \"close\": \"关闭\"\n }\n },\n \"chat\": {\n \"disclaimer\": \"懂你所需，伴你左右\",\n \"greeting\": \"你好，我今天能帮你做什么？\",\n \"description\": \"我是一个智能助手，可以帮助你解答问题。\",\n \"prompt1\": \"让我们开启一段新的旅程吧！\",\n \"prompt2\": \"能告诉我你有哪些技能吗？\",\n \"attachments\": {\n \"tooltip\": \"支持文档、图片、视频、音频等多种格式，单文件不超过10MB\",\n \"fileSizeLimit\": \"单文件不超过10MB\"\n }\n },\n \"security\": {\n \"title\": \"安全\",\n \"description\": \"管理工具和技能的安全功能。\",\n \"toolGuardTitle\": \"工具防护\",\n \"toolGuardDescription\": \"配置工具调用的安全扫描。危险操作将在执行前需要你的明确批准。\",\n \"enabled\": \"启用工具防护\",\n \"enabledTooltip\": \"启用后，工具调用在执行前会被扫描是否包含危险模式\",\n \"guardedTools\": \"受保护的工具\",\n \"guardedToolsTooltip\": \"检测到危险模式时需要审批的工具。留空则使用内置默认集合。\",\n \"guardedToolsPlaceholder\": \"选择工具或输入自定义工具名\",\n \"deniedTools\": \"禁止的工具\",\n \"deniedToolsTooltip\": \"始终被拒绝的工具，无需审批直接拦截\",\n \"deniedToolsPlaceholder\": \"选择要始终禁止的工具\",\n \"saveSuccess\": \"工具防护设置已保存\",\n \"saveFailed\": \"保存工具防护设置失败\",\n \"loadFailed\": \"加载工具防护设置失败\",\n \"rules\": {\n \"title\": \"检测规则\",\n \"description\": \"规则定义了触发安全警告的正则表达式模式。内置规则可以禁用；自定义规则可以添加、编辑或删除。\",\n \"id\": \"规则 ID\",\n \"severity\": \"严重程度\",\n \"descriptionCol\": \"描述\",\n \"source\": \"来源\",\n \"actions\": \"操作\",\n \"builtin\": \"内置\",\n \"custom\": \"自定义\",\n \"enable\": \"启用\",\n \"disable\": \"禁用\",\n \"edit\": \"编辑\",\n \"delete\": \"删除\",\n \"add\": \"添加规则\",\n \"addTitle\": \"添加自定义规则\",\n \"editTitle\": \"编辑自定义规则\",\n \"ruleId\": \"规则 ID\",\n \"ruleIdRequired\": \"规则 ID 不能为空\",\n \"duplicateId\": \"已存在相同 ID 的规则\",\n \"tools\": \"目标工具\",\n \"toolsPlaceholder\": \"留空匹配所有工具\",\n \"params\": \"目标参数\",\n \"paramsPlaceholder\": \"留空匹配所有参数\",\n \"severityLabel\": \"严重程度\",\n \"categoryLabel\": \"分类\",\n \"patterns\": \"正则模式\",\n \"patternsRequired\": \"至少需要一个正则模式\",\n \"patternsTooltip\": \"每行一个正则表达式，匹配工具参数值（不区分大小写）。\",\n \"excludePatterns\": \"排除模式\",\n \"excludePatternsTooltip\": \"每行一个正则表达式。如果匹配，则跳过该规则。\",\n \"descriptionLabel\": \"描述\",\n \"descriptionPlaceholder\": \"该规则检测什么？\",\n \"remediationLabel\": \"修复建议\",\n \"remediationPlaceholder\": \"触发规则时建议的操作\",\n \"preview\": \"预览\",\n \"previewTitle\": \"规则详情\",\n \"actionLabel\": \"触发行为\",\n \"actionApproval\": \"等待审批\",\n \"allTools\": \"所有工具\",\n \"allParams\": \"所有参数\",\n \"descriptions\": {\n \"TOOL_CMD_DANGEROUS_RM\": \"检测可能导致数据丢失的 rm 命令\",\n \"TOOL_CMD_DANGEROUS_MV\": \"检测可能意外移动或覆盖文件的 mv 命令\",\n \"TOOL_CMD_FS_DESTRUCTION\": \"检测低级别磁盘格式化或擦除命令\",\n \"TOOL_CMD_DOS_FORK_BOMB\": \"检测经典 Bash Fork 炸弹和批量进程终止\",\n \"TOOL_CMD_PIPE_TO_SHELL\": \"检测通过 'curl | bash' 模式下载并立即执行远程载荷的行为\",\n \"TOOL_CMD_REVERSE_SHELL\": \"检测建立反向 Shell 或未授权网络隧道的行为\",\n \"TOOL_CMD_SYSTEM_TAMPERING\": \"检测对定时任务、SSH 密钥或 sudo 权限的访问（包括读取和修改）\",\n \"TOOL_CMD_UNSAFE_PERMISSIONS\": \"检测全局权限降级（chmod 777）或设置不可变标志的操作\",\n \"TOOL_CMD_OBFUSCATED_EXEC\": \"检测将 base64 编码字符串直接传递给 Shell 解释器执行的行为\"\n }\n },\n \"skillScanner\": {\n \"title\": \"技能扫描器\",\n \"description\": \"在启用或安装技能前，自动扫描安全威胁。不安全的技能可以被拦截或加入白名单。\",\n \"mode\": \"扫描模式\",\n \"modeTooltip\": \"控制扫描器如何处理不安全的技能：拦截、仅提醒或关闭\",\n \"modeBlock\": \"拦截\",\n \"modeWarn\": \"仅提醒\",\n \"modeOff\": \"关闭\",\n \"timeout\": \"扫描超时（秒）\",\n \"timeoutTooltip\": \"等待扫描完成的最长时间（5-300秒）\",\n \"saveSuccess\": \"技能扫描器设置已保存\",\n \"saveFailed\": \"保存技能扫描器设置失败\",\n \"scanAlerts\": {\n \"title\": \"扫描告警\",\n \"empty\": \"暂无安全告警\",\n \"clearAll\": \"清除全部\",\n \"clearConfirm\": \"确定清除所有扫描告警吗？\",\n \"skillName\": \"技能\",\n \"action\": \"动作\",\n \"actionBlocked\": \"已拦截\",\n \"actionWarned\": \"已提醒\",\n \"time\": \"时间\",\n \"actions\": \"操作\",\n \"allowSkill\": \"加入白名单\",\n \"remove\": \"删除\",\n \"viewFindings\": \"查看详情\"\n },\n \"whitelist\": {\n \"title\": \"白名单\",\n \"empty\": \"暂无白名单技能\",\n \"skillName\": \"技能\",\n \"addedAt\": \"添加时间\",\n \"contentHash\": \"内容哈希\",\n \"actions\": \"操作\",\n \"remove\": \"移除\",\n \"removeConfirm\": \"确定将此技能从白名单中移除？\",\n \"addSuccess\": \"技能已加入白名单\",\n \"removeSuccess\": \"技能已从白名单移除\",\n \"addFailed\": \"加入白名单失败\",\n \"removeFailed\": \"从白名单移除失败\",\n \"removeWillDisable\": \"移除后该技能将同时被禁用。\",\n \"removeAndDisabled\": \"技能已从白名单移除并已禁用\"\n },\n \"scanError\": {\n \"title\": \"检测到安全问题\",\n \"description\": \"发现以下安全问题：\",\n \"warnDescription\": \"发现安全问题，但技能仍已启用（仅提醒模式）：\",\n \"goToWhitelist\": \"前往白名单\"\n }\n }\n },\n \"login\": {\n \"title\": \"登录 CoPaw\",\n \"registerTitle\": \"创建账户\",\n \"firstUserHint\": \"创建管理员账户以开始使用\",\n \"usernamePlaceholder\": \"用户名\",\n \"passwordPlaceholder\": \"密码\",\n \"usernameRequired\": \"请输入用户名\",\n \"passwordRequired\": \"请输入密码\",\n \"submit\": \"登录\",\n \"register\": \"注册\",\n \"failed\": \"登录失败，请检查您的凭据\",\n \"registerSuccess\": \"注册成功\",\n \"registerFailed\": \"注册失败\",\n \"authNotEnabled\": \"认证未启用\",\n \"logout\": \"退出登录\",\n \"logoutSuccess\": \"已成功退出\",\n \"sessionExpired\": \"会话已过期，请重新登录\",\n \"unauthorized\": \"未授权，请登录\"\n },\n \"voiceTranscription\": {\n \"title\": \"语音转写\",\n \"description\": \"配置如何处理收到的音频和语音消息。\",\n \"loadFailed\": \"加载音频模式设置失败\",\n \"saveSuccess\": \"音频模式已保存\",\n \"saveFailed\": \"保存音频模式失败\",\n \"audioModeLabel\": \"音频模式\",\n \"audioModeDescription\": \"选择来自频道（Discord、Telegram 等）的语音消息在发送给模型之前如何处理。\",\n \"modeAuto\": \"自动（推荐）\",\n \"modeAutoDesc\": \"使用所选转写提供商将音频转写为文字后发送给模型。如果转写未启用或不可用，则显示文件上传占位消息。此模式下音频不会直接发送给模型。适用于所有模型。\",\n \"modeNative\": \"原生音频\",\n \"modeNativeDesc\": \"直接将音频文件发送给模型，不进行转写。这是唯一会将音频发送给模型的模式。仅适用于特定的音频模型（如 gpt-4o-audio），大多数模型不支持此模式。\",\n \"ffmpegReady\": \"ffmpeg 已安装。原生模式音频格式转换可用。\",\n \"ffmpegMissing\": \"ffmpeg 未安装。\",\n \"ffmpegMissingDesc\": \"原生音频模式需要 ffmpeg 来转换音频格式（如 .ogg 转 .wav）。请安装 ffmpeg 系统包以启用此模式。\",\n \"providerTypeLabel\": \"转写提供商\",\n \"providerTypeDescription\": \"选择转写后端。如果不需要语音转写，请选择「已禁用」。\",\n \"providerTypeDisabled\": \"已禁用\",\n \"providerTypeDisabledDesc\": \"不进行转写。语音消息将显示为文件上传占位消息。\",\n \"providerTypeWhisperApi\": \"Whisper API\",\n \"providerTypeWhisperApiDesc\": \"使用已配置提供商（如 OpenAI、Ollama）的 OpenAI 兼容 Whisper API 端点。\",\n \"providerTypeLocalWhisper\": \"本地 Whisper\",\n \"providerTypeLocalWhisperDesc\": \"使用本地安装的 openai-whisper Python 库进行转写。需要同时安装 ffmpeg 和 openai-whisper。\",\n \"localWhisperReady\": \"本地 Whisper 已就绪。ffmpeg 和 openai-whisper 均已安装。\",\n \"localWhisperMissing\": \"本地 Whisper 未就绪，缺少必要依赖。\",\n \"localWhisperMissingDesc\": \"ffmpeg: {{ffmpeg}} | openai-whisper: {{whisper}}。请安装缺少的依赖：ffmpeg（系统包）和 openai-whisper（uv pip install openai-whisper，或使用 [whisper] 额外依赖安装 CoPaw）。\",\n \"providerLabel\": \"Whisper API 提供商\",\n \"providerDescription\": \"选择用于 Whisper API 音频转写的提供商。仅显示支持 Whisper 端点的提供商。\",\n \"providerPlaceholder\": \"选择提供商...\",\n \"noProvidersWarning\": \"未找到支持转写的提供商。请配置一个 OpenAI 提供商以启用语音转写。\",\n \"transcriptionInfoTitle\": \"转写工作原理\",\n \"transcriptionInfoDesc\": \"Whisper API 转写使用 OpenAI 兼容的 /v1/audio/transcriptions 端点。需要配置一个支持 Whisper 端点的提供商（如 OpenAI）。请在上方选择具体的提供商以启用转写。\",\n \"transcriptionInfoDescLocal\": \"本地 Whisper 转写直接在您的设备上运行 openai-whisper 库。需要同时安装 ffmpeg（用于音频解码）和 openai-whisper Python 包。无需 API Key 或网络连接。安装命令：uv pip install 'copaw[whisper]'。\"\n }\n}\n" }, { "path": "console/src/main.tsx", "content": "import { createRoot } from \"react-dom/client\";\nimport App from \"./App.tsx\";\nimport \"./i18n\";\n\nif (typeof window !== \"undefined\") {\n const originalError = console.error;\n const originalWarn = console.warn;\n\n console.error = function (...args: any[]) {\n const msg = args[0]?.toString() || \"\";\n if (msg.includes(\":first-child\") || msg.includes(\"pseudo class\")) {\n return;\n }\n originalError.apply(console, args);\n };\n\n console.warn = function (...args: any[]) {\n const msg = args[0]?.toString() || \"\";\n if (\n msg.includes(\":first-child\") ||\n msg.includes(\"pseudo class\") ||\n msg.includes(\"potentially unsafe\")\n ) {\n return;\n }\n originalWarn.apply(console, args);\n };\n}\n\ncreateRoot(document.getElementById(\"root\")!).render();\n" }, { "path": "console/src/pages/Agent/Config/components/ContextManagementCard.tsx", "content": "import { Form, InputNumber, Input, Card } from \"@agentscope-ai/design\";\nimport { useTranslation } from \"react-i18next\";\nimport { SliderWithValue } from \"./SliderWithValue\";\nimport styles from \"../index.module.less\";\n\ninterface ContextManagementCardProps {\n contextCompactThreshold: number;\n contextCompactReserveThreshold: number;\n}\n\nexport function ContextManagementCard({\n contextCompactThreshold,\n contextCompactReserveThreshold,\n}: ContextManagementCardProps) {\n const { t } = useTranslation();\n return (\n \n \n \n \n\n \n \n \n\n \n 0\n ? contextCompactThreshold.toLocaleString()\n : \"\"\n }\n placeholder={t(\"agentConfig.contextCompactThresholdPlaceholder\")}\n />\n \n\n \n \n \n\n \n 0\n ? contextCompactReserveThreshold.toLocaleString()\n : \"\"\n }\n placeholder={t(\n \"agentConfig.contextCompactReserveThresholdPlaceholder\",\n )}\n />\n \n\n \n \n \n\n \n \n \n\n \n \n \n\n \n \n \n \n );\n}\n" }, { "path": "console/src/pages/Agent/Config/components/PageHeader.tsx", "content": "import { useTranslation } from \"react-i18next\";\nimport styles from \"../index.module.less\";\n\nexport function PageHeader() {\n const { t } = useTranslation();\n return (\n
\n
\n

{t(\"agentConfig.title\")}

\n

{t(\"agentConfig.description\")}

\n
\n
\n );\n}\n" }, { "path": "console/src/pages/Agent/Config/components/ReactAgentCard.tsx", "content": "import { Form, InputNumber, Select, Card } from \"@agentscope-ai/design\";\nimport { useTranslation } from \"react-i18next\";\nimport { TIMEZONE_OPTIONS } from \"../../../../constants/timezone\";\nimport styles from \"../index.module.less\";\n\nconst LANGUAGE_OPTIONS = [\n { value: \"zh\", label: \"中文\" },\n { value: \"en\", label: \"English\" },\n { value: \"ru\", label: \"Русский\" },\n];\n\ninterface ReactAgentCardProps {\n language: string;\n savingLang: boolean;\n onLanguageChange: (value: string) => void;\n timezone: string;\n savingTimezone: boolean;\n onTimezoneChange: (value: string) => void;\n}\n\nexport function ReactAgentCard({\n language,\n savingLang,\n onLanguageChange,\n timezone,\n savingTimezone,\n onTimezoneChange,\n}: ReactAgentCardProps) {\n const { t } = useTranslation();\n return (\n \n \n \n \n\n \n \n (option?.label?.toString() || \"\")\n .toLowerCase()\n .includes(input.toLowerCase())\n }\n options={TIMEZONE_OPTIONS}\n onChange={onTimezoneChange}\n loading={savingTimezone}\n disabled={savingTimezone}\n style={{ width: \"100%\" }}\n />\n \n\n \n \n \n \n );\n}\n" }, { "path": "console/src/pages/Agent/Config/components/SliderWithValue.tsx", "content": "import { Slider } from \"@agentscope-ai/design\";\n\ninterface SliderWithValueProps {\n value?: number;\n min?: number;\n max?: number;\n step?: number;\n marks?: Record;\n onChange?: (value: number) => void;\n}\n\nexport function SliderWithValue({\n value,\n min,\n max,\n step,\n marks,\n onChange,\n}: SliderWithValueProps) {\n const formatValue = (v: number) => {\n if (v >= 1) return v.toString();\n return v.toFixed(2);\n };\n\n return (\n
\n
\n \n
\n
\n \n {value !== undefined ? formatValue(value) : \"-\"}\n \n
\n
\n );\n}\n" }, { "path": "console/src/pages/Agent/Config/components/index.ts", "content": "export { SliderWithValue } from \"./SliderWithValue\";\nexport { PageHeader } from \"./PageHeader\";\nexport { ReactAgentCard } from \"./ReactAgentCard\";\nexport { ContextManagementCard } from \"./ContextManagementCard\";\n" }, { "path": "console/src/pages/Agent/Config/index.module.less", "content": ".configPage {\n padding: 24px;\n height: 100%;\n overflow-y: auto;\n width: 100%;\n}\n\n.header {\n display: flex;\n justify-content: space-between;\n align-items: center;\n margin-bottom: 24px;\n}\n\n.headerActions {\n display: flex;\n gap: 8px;\n flex-shrink: 0;\n margin-top: 34px;\n}\n\n.title {\n font-size: 24px;\n font-weight: 600;\n margin: 0 0 8px 0;\n color: #000;\n}\n\n.description {\n font-size: 14px;\n color: #666;\n margin: 0;\n}\n\n.formCard {\n width: 100%;\n\n &:hover {\n border: 1px solid #615ced;\n box-shadow: 0 12px 32px rgba(0, 0, 0, 0.08);\n }\n}\n\n.form {\n :global {\n .ant-form-item-label > label {\n font-weight: 500;\n }\n }\n}\n\n.buttonGroup {\n display: flex;\n gap: 12px;\n justify-content: flex-end;\n margin-top: 32px;\n margin-bottom: 0;\n}\n\n.centerState {\n display: flex;\n flex-direction: column;\n align-items: center;\n justify-content: center;\n height: 400px;\n gap: 16px;\n}\n\n.stateText {\n font-size: 14px;\n color: #666;\n}\n\n.stateTextError {\n font-size: 14px;\n color: #ff4d4f;\n}\n\n.footerActions {\n display: flex;\n justify-content: flex-end;\n align-items: center;\n padding: 16px 24px;\n}\n" }, { "path": "console/src/pages/Agent/Config/index.tsx", "content": "import { useState } from \"react\";\nimport { Button, Form } from \"@agentscope-ai/design\";\nimport { useTranslation } from \"react-i18next\";\nimport { useAgentConfig } from \"./useAgentConfig.tsx\";\nimport {\n PageHeader,\n ReactAgentCard,\n ContextManagementCard,\n} from \"./components\";\nimport styles from \"./index.module.less\";\n\nfunction AgentConfigPage() {\n const { t } = useTranslation();\n const {\n form,\n loading,\n saving,\n error,\n language,\n savingLang,\n timezone,\n savingTimezone,\n fetchConfig,\n handleSave,\n handleLanguageChange,\n handleTimezoneChange,\n } = useAgentConfig();\n\n // Force re-render when form values change to refresh derived threshold values\n const [, forceUpdate] = useState({});\n const handleValuesChange = () => forceUpdate({});\n\n const getCalculatedValues = () => {\n const values = form.getFieldsValue([\n \"max_input_length\",\n \"memory_compact_ratio\",\n \"memory_reserve_ratio\",\n ]);\n const maxInputLength = values.max_input_length ?? 0;\n const memoryCompactRatio = values.memory_compact_ratio ?? 0;\n const memoryReserveRatio = values.memory_reserve_ratio ?? 0;\n return {\n contextCompactThreshold: Math.floor(maxInputLength * memoryCompactRatio),\n contextCompactReserveThreshold: Math.floor(\n maxInputLength * memoryReserveRatio,\n ),\n };\n };\n\n const { contextCompactThreshold, contextCompactReserveThreshold } =\n getCalculatedValues();\n\n if (loading) {\n return (\n
\n
\n {t(\"common.loading\")}\n
\n
\n );\n }\n\n if (error) {\n return (\n
\n
\n {error}\n \n
\n
\n );\n }\n\n return (\n
\n \n\n \n \n\n \n \n\n
\n \n {t(\"common.reset\")}\n \n \n
\n
\n );\n}\n\nexport default AgentConfigPage;\n" }, { "path": "console/src/pages/Agent/Config/useAgentConfig.tsx", "content": "import { useState, useEffect, useCallback } from \"react\";\nimport { Form, Modal, message } from \"@agentscope-ai/design\";\nimport { useTranslation } from \"react-i18next\";\nimport api from \"../../../api\";\nimport type { AgentsRunningConfig } from \"../../../api/types\";\n\nexport function useAgentConfig() {\n const { t } = useTranslation();\n const [form] = Form.useForm();\n const [loading, setLoading] = useState(true);\n const [saving, setSaving] = useState(false);\n const [error, setError] = useState(null);\n const [language, setLanguage] = useState(\"zh\");\n const [savingLang, setSavingLang] = useState(false);\n const [timezone, setTimezone] = useState(\"UTC\");\n const [savingTimezone, setSavingTimezone] = useState(false);\n\n const fetchConfig = useCallback(async () => {\n setLoading(true);\n setError(null);\n try {\n const [config, langResp, tzResp] = await Promise.all([\n api.getAgentRunningConfig(),\n api.getAgentLanguage(),\n api.getUserTimezone(),\n ]);\n form.setFieldsValue(config);\n setLanguage(langResp.language);\n setTimezone(tzResp.timezone || \"UTC\");\n } catch (err) {\n const errMsg =\n err instanceof Error ? err.message : t(\"agentConfig.loadFailed\");\n setError(errMsg);\n } finally {\n setLoading(false);\n }\n }, [form, t]);\n\n useEffect(() => {\n fetchConfig();\n }, [fetchConfig]);\n\n const handleSave = useCallback(async () => {\n try {\n const values = await form.validateFields();\n setSaving(true);\n await api.updateAgentRunningConfig(values as AgentsRunningConfig);\n message.success(t(\"agentConfig.saveSuccess\"));\n } catch (err) {\n if (err instanceof Error && \"errorFields\" in err) return;\n const errMsg =\n err instanceof Error ? err.message : t(\"agentConfig.saveFailed\");\n message.error(errMsg);\n } finally {\n setSaving(false);\n }\n }, [form, t]);\n\n const handleLanguageChange = useCallback(\n (value: string): void => {\n if (value === language) return;\n Modal.confirm({\n title: t(\"agentConfig.languageConfirmTitle\"),\n content: (\n \n {t(\"agentConfig.languageConfirmContent\")}\n \n ),\n okText: t(\"agentConfig.languageConfirmOk\"),\n cancelText: t(\"common.cancel\"),\n onOk: async () => {\n setSavingLang(true);\n try {\n const resp = await api.updateAgentLanguage(value);\n setLanguage(resp.language);\n if (resp.copied_files && resp.copied_files.length > 0) {\n message.success(\n t(\"agentConfig.languageSaveSuccessWithFiles\", {\n count: resp.copied_files.length,\n }),\n );\n } else {\n message.success(t(\"agentConfig.languageSaveSuccess\"));\n }\n } catch (err) {\n const errMsg =\n err instanceof Error\n ? err.message\n : t(\"agentConfig.languageSaveFailed\");\n message.error(errMsg);\n } finally {\n setSavingLang(false);\n }\n },\n });\n },\n [language, t],\n );\n\n const handleTimezoneChange = useCallback(\n async (value: string) => {\n if (value === timezone) return;\n setSavingTimezone(true);\n try {\n await api.updateUserTimezone(value);\n setTimezone(value);\n message.success(t(\"agentConfig.timezoneSaveSuccess\"));\n } catch (err) {\n const errMsg =\n err instanceof Error\n ? err.message\n : t(\"agentConfig.timezoneSaveFailed\");\n message.error(errMsg);\n } finally {\n setSavingTimezone(false);\n }\n },\n [timezone, t],\n );\n\n return {\n form,\n loading,\n saving,\n error,\n language,\n savingLang,\n timezone,\n savingTimezone,\n fetchConfig,\n handleSave,\n handleLanguageChange,\n handleTimezoneChange,\n };\n}\n" }, { "path": "console/src/pages/Agent/MCP/components/MCPClientCard.tsx", "content": "import { Card, Button, Modal, Tooltip, Input } from \"@agentscope-ai/design\";\nimport { DeleteOutlined } from \"@ant-design/icons\";\nimport { Server } from \"lucide-react\";\nimport type { MCPClientInfo } from \"../../../../api/types\";\nimport { useTranslation } from \"react-i18next\";\nimport { useState } from \"react\";\nimport { useTheme } from \"../../../../contexts/ThemeContext\";\nimport styles from \"../index.module.less\";\n\ninterface MCPClientCardProps {\n client: MCPClientInfo;\n onToggle: (client: MCPClientInfo, e: React.MouseEvent) => void;\n onDelete: (client: MCPClientInfo, e: React.MouseEvent) => void;\n onUpdate: (key: string, updates: any) => Promise;\n isHovered: boolean;\n onMouseEnter: () => void;\n onMouseLeave: () => void;\n}\n\nexport function MCPClientCard({\n client,\n onToggle,\n onDelete,\n onUpdate,\n isHovered,\n onMouseEnter,\n onMouseLeave,\n}: MCPClientCardProps) {\n const { t } = useTranslation();\n const { isDark } = useTheme();\n const [jsonModalOpen, setJsonModalOpen] = useState(false);\n const [deleteModalOpen, setDeleteModalOpen] = useState(false);\n const [editedJson, setEditedJson] = useState(\"\");\n const [isEditing, setIsEditing] = useState(false);\n\n // Determine if MCP client is remote or local based on command\n const isRemote =\n client.transport === \"streamable_http\" || client.transport === \"sse\";\n const clientType = isRemote ? \"Remote\" : \"Local\";\n\n const handleToggleClick = (e: React.MouseEvent) => {\n e.stopPropagation();\n onToggle(client, e);\n };\n\n const handleDeleteClick = (e: React.MouseEvent) => {\n e.stopPropagation();\n setDeleteModalOpen(true);\n };\n\n const confirmDelete = () => {\n setDeleteModalOpen(false);\n onDelete(client, null as any);\n };\n\n const handleCardClick = () => {\n const jsonStr = JSON.stringify(client, null, 2);\n setEditedJson(jsonStr);\n setIsEditing(false);\n setJsonModalOpen(true);\n };\n\n const handleSaveJson = async () => {\n try {\n const parsed = JSON.parse(editedJson);\n const { key, ...updates } = parsed;\n\n // Send all updates directly to backend, let backend handle env masking check\n const success = await onUpdate(client.key, updates);\n if (success) {\n setJsonModalOpen(false);\n setIsEditing(false);\n }\n } catch (error) {\n alert(\"Invalid JSON format\");\n }\n };\n\n const clientJson = JSON.stringify(client, null, 2);\n\n return (\n <>\n \n
\n
\n \n \n \n \n

{client.name}

\n \n \n {clientType}\n \n
\n
\n \n \n {client.enabled ? t(\"common.enabled\") : t(\"common.disabled\")}\n \n
\n
\n\n
\n {client.description || \"\\u00A0\"}\n
\n\n
\n \n {client.enabled ? t(\"common.disable\") : t(\"common.enable\")}\n \n\n }\n className={styles.deleteButton}\n onClick={handleDeleteClick}\n disabled={client.enabled}\n />\n
\n \n\n setDeleteModalOpen(false)}\n okText={t(\"common.confirm\")}\n cancelText={t(\"common.cancel\")}\n okButtonProps={{ danger: true }}\n >\n

{t(\"mcp.deleteConfirm\")}

\n \n\n setJsonModalOpen(false)}\n footer={\n
\n setJsonModalOpen(false)}\n style={{ marginRight: 8 }}\n >\n {t(\"common.cancel\")}\n \n {isEditing ? (\n \n ) : (\n \n )}\n
\n }\n width={700}\n >\n {isEditing ? (\n setEditedJson(e.target.value)}\n autoSize={{ minRows: 15, maxRows: 25 }}\n style={{\n fontFamily: \"Monaco, Courier New, monospace\",\n fontSize: 13,\n }}\n />\n ) : (\n \n {clientJson}\n \n )}\n \n \n );\n}\n" }, { "path": "console/src/pages/Agent/MCP/components/MCPClientDrawer.tsx", "content": "import { Drawer, Form, Input, Switch, Button } from \"@agentscope-ai/design\";\nimport type { MCPClientInfo } from \"../../../../api/types\";\nimport { useTranslation } from \"react-i18next\";\nimport { useState } from \"react\";\n\ninterface MCPClientDrawerProps {\n open: boolean;\n client: MCPClientInfo | null;\n onClose: () => void;\n onSubmit: (\n key: string,\n values: {\n name: string;\n command?: string;\n enabled?: boolean;\n transport?: \"stdio\" | \"streamable_http\" | \"sse\";\n url?: string;\n headers?: Record;\n args?: string[];\n env?: Record;\n cwd?: string;\n },\n ) => Promise;\n form: any;\n}\n\nexport function MCPClientDrawer({\n open,\n client,\n onClose,\n onSubmit,\n form,\n}: MCPClientDrawerProps) {\n const { t } = useTranslation();\n const [submitting, setSubmitting] = useState(false);\n const isEditing = !!client;\n\n const handleSubmit = async () => {\n try {\n const values = await form.validateFields();\n setSubmitting(true);\n\n const clientData = {\n name: values.name,\n command: values.command,\n enabled: values.enabled ?? true,\n args: values.args ? values.args.split(\" \").filter(Boolean) : [],\n env: values.env ? JSON.parse(values.env) : {},\n };\n\n const key = isEditing ? client.key : values.key;\n const success = await onSubmit(key, clientData);\n\n if (success) {\n onClose();\n }\n } catch (error) {\n console.error(\"Form validation failed:\", error);\n } finally {\n setSubmitting(false);\n }\n };\n\n return (\n \n \n \n \n }\n >\n
\n {!isEditing && (\n \n \n \n )}\n\n \n \n \n\n \n \n \n\n \n \n \n\n \n \n \n\n \n \n \n\n \n \n \n \n \n );\n}\n" }, { "path": "console/src/pages/Agent/MCP/components/index.ts", "content": "export { MCPClientCard } from \"./MCPClientCard\";\nexport { MCPClientDrawer } from \"./MCPClientDrawer\";\n" }, { "path": "console/src/pages/Agent/MCP/index.module.less", "content": ".mcpCard {\n border-radius: 12px;\n transition: all 0.2s ease-in-out;\n cursor: pointer;\n padding: 16px;\n\n &.enabledCard {\n border: 2px solid #615ced !important;\n box-shadow: rgba(97, 92, 237, 0.2) 0px 4px 12px !important;\n }\n\n &.hover {\n border: 1px solid #615ced;\n box-shadow: 0 8px 20px rgba(0, 0, 0, 0.08);\n }\n\n &.normal {\n border: 1px solid rgba(0, 0, 0, 0.04);\n box-shadow: 0 2px 8px rgba(0, 0, 0, 0.04);\n }\n}\n\n.cardHeader {\n display: flex;\n justify-content: space-between;\n align-items: center;\n margin-bottom: 12px;\n}\n\n.mcpTitle {\n margin: 0;\n font-size: 17px;\n font-weight: 600;\n color: #1a1a1a;\n max-width: 180px;\n overflow: hidden;\n text-overflow: ellipsis;\n white-space: nowrap;\n}\n\n.typeBadge {\n font-size: 10px;\n padding: 2px 6px;\n border-radius: 3px;\n font-weight: 500;\n\n &.local {\n background-color: #e6f7ff;\n color: #1890ff;\n border: 1px solid #91d5ff;\n }\n\n &.remote {\n background-color: #fff7e6;\n color: #fa8c16;\n border: 1px solid #ffd591;\n }\n}\n\n.fileIcon {\n font-size: 20px;\n display: flex;\n align-items: center;\n}\n\n.description {\n font-size: 14px;\n color: #666;\n line-height: 1.6;\n margin-bottom: 32px;\n min-height: 64px;\n overflow: hidden;\n text-overflow: ellipsis;\n display: -webkit-box;\n -webkit-line-clamp: 2;\n -webkit-box-orient: vertical;\n}\n\n.cardFooter {\n display: flex;\n justify-content: flex-end;\n align-items: center;\n gap: 8px;\n padding-top: 16px;\n margin-top: auto;\n border-top: 1px solid #f0f0f0;\n}\n\n.actionButton {\n padding: 0;\n font-size: 12px;\n}\n\n.deleteButton {\n padding: 4px;\n display: flex;\n align-items: center;\n justify-content: center;\n\n &:hover {\n background-color: #ff4d4f;\n color: #fff;\n border-color: #ff4d4f;\n }\n}\n\n.statusContainer {\n display: flex;\n align-items: center;\n gap: 6px;\n}\n\n.statusDot {\n width: 6px;\n height: 6px;\n border-radius: 50%;\n\n &.enabled {\n background-color: #52c41a;\n }\n\n &.disabled {\n background-color: #d9d9d9;\n }\n}\n\n.statusText {\n font-size: 12px;\n\n &.enabled {\n color: #52c41a;\n }\n\n &.disabled {\n color: #999;\n }\n}\n\n.editJsonTextArea {\n width: 100%;\n min-height: 500px;\n font-family:\n Monaco,\n Courier New,\n monospace;\n font-size: 13px;\n padding: 16px;\n border: 1px solid var(--ant-color-border);\n border-radius: 4px;\n resize: vertical;\n background-color: var(--ant-color-bg-container);\n color: var(--ant-color-text);\n}\n\n.preformattedText {\n background-color: var(--ant-color-bg-container-disabled, #f5f5f5);\n color: var(--ant-color-text);\n padding: 16px;\n border-radius: 8px;\n max-height: 500px;\n overflow: auto;\n}\n" }, { "path": "console/src/pages/Agent/MCP/index.tsx", "content": "import { useState } from \"react\";\nimport { Button, Empty, Modal, Input } from \"@agentscope-ai/design\";\nimport type { MCPClientInfo } from \"../../../api/types\";\nimport { MCPClientCard } from \"./components\";\nimport { useMCP } from \"./useMCP\";\nimport { useTranslation } from \"react-i18next\";\n\ntype MCPTransport = \"stdio\" | \"streamable_http\" | \"sse\";\n\nfunction normalizeTransport(raw?: unknown): MCPTransport | undefined {\n if (typeof raw !== \"string\") return undefined;\n const value = raw.trim().toLowerCase();\n switch (value) {\n case \"stdio\":\n return \"stdio\";\n case \"sse\":\n return \"sse\";\n case \"streamablehttp\":\n case \"streamable_http\":\n case \"streamable-http\":\n case \"http\":\n return \"streamable_http\";\n default:\n return undefined;\n }\n}\n\nfunction normalizeClientData(key: string, rawData: any) {\n const transport =\n normalizeTransport(rawData.transport ?? rawData.type) ??\n (rawData.url || rawData.baseUrl || !rawData.command\n ? \"streamable_http\"\n : \"stdio\");\n\n const command =\n transport === \"stdio\" ? (rawData.command ?? \"\").toString() : \"\";\n\n return {\n name: rawData.name || key,\n description: rawData.description || \"\",\n enabled: rawData.enabled ?? rawData.isActive ?? true,\n transport,\n url: (rawData.url || rawData.baseUrl || \"\").toString(),\n headers: rawData.headers || {},\n command,\n args: Array.isArray(rawData.args) ? rawData.args : [],\n env: rawData.env || {},\n cwd: (rawData.cwd || \"\").toString(),\n };\n}\n\nfunction MCPPage() {\n const { t } = useTranslation();\n const {\n clients,\n loading,\n toggleEnabled,\n deleteClient,\n createClient,\n updateClient,\n } = useMCP();\n const [hoverKey, setHoverKey] = useState(null);\n const [createModalOpen, setCreateModalOpen] = useState(false);\n const [newClientJson, setNewClientJson] = useState(`{\n \"mcpServers\": {\n \"example-client\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@example/mcp-server\"],\n \"env\": {\n \"API_KEY\": \"\"\n }\n }\n }\n}`);\n\n const handleToggleEnabled = async (\n client: MCPClientInfo,\n e?: React.MouseEvent,\n ) => {\n e?.stopPropagation();\n await toggleEnabled(client);\n };\n\n const handleDelete = async (client: MCPClientInfo, e?: React.MouseEvent) => {\n e?.stopPropagation();\n await deleteClient(client);\n };\n\n const handleCreateClient = async () => {\n try {\n const parsed = JSON.parse(newClientJson);\n\n // Support two formats:\n // Format 1: { \"mcpServers\": { \"key\": { \"command\": \"...\", ... } } }\n // Format 2: { \"key\": { \"command\": \"...\", ... } }\n // Format 3: { \"key\": \"...\", \"name\": \"...\", \"command\": \"...\", ... } (direct)\n\n const clientsToCreate: Array<{ key: string; data: any }> = [];\n\n if (parsed.mcpServers) {\n // Format 1: nested mcpServers\n Object.entries(parsed.mcpServers).forEach(\n ([key, data]: [string, any]) => {\n clientsToCreate.push({\n key,\n data: normalizeClientData(key, data),\n });\n },\n );\n } else if (\n parsed.key &&\n (parsed.command || parsed.url || parsed.baseUrl)\n ) {\n // Format 3: direct format with key field\n const { key, ...clientData } = parsed;\n clientsToCreate.push({\n key,\n data: normalizeClientData(key, clientData),\n });\n } else {\n // Format 2: direct client objects with keys\n Object.entries(parsed).forEach(([key, data]: [string, any]) => {\n if (\n typeof data === \"object\" &&\n (data.command || data.url || data.baseUrl)\n ) {\n clientsToCreate.push({\n key,\n data: normalizeClientData(key, data),\n });\n }\n });\n }\n\n // Create all clients\n let allSuccess = true;\n for (const { key, data } of clientsToCreate) {\n const success = await createClient(key, data);\n if (!success) allSuccess = false;\n }\n\n if (allSuccess) {\n setCreateModalOpen(false);\n setNewClientJson(`{\n \"mcpServers\": {\n \"example-client\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@example/mcp-server\"],\n \"env\": {\n \"API_KEY\": \"\"\n }\n }\n }\n}`);\n }\n } catch (error) {\n alert(\"Invalid JSON format\");\n }\n };\n\n return (\n
\n \n
\n

\n {t(\"mcp.title\")}\n

\n

\n {t(\"mcp.description\")}\n

\n
\n \n
\n\n {loading ? (\n
\n

{t(\"common.loading\")}

\n
\n ) : clients.length === 0 ? (\n \n ) : (\n \n {clients.map((client) => (\n setHoverKey(client.key)}\n onMouseLeave={() => setHoverKey(null)}\n />\n ))}\n \n )}\n\n setCreateModalOpen(false)}\n footer={\n
\n setCreateModalOpen(false)}\n style={{ marginRight: 8 }}\n >\n {t(\"common.cancel\")}\n \n \n
\n }\n width={800}\n >\n
\n

\n {t(\"mcp.formatSupport\")}:\n

\n \n
  • \n Standard format:{\" \"}\n {`{ \"mcpServers\": { \"key\": {...} } }`}\n
    • \n
  • \n Direct format: {`{ \"key\": {...} }`}\n
    • \n
  • \n Single format:{\" \"}\n {`{ \"key\": \"...\", \"name\": \"...\", \"command\": \"...\" }`}\n
    • \n \n
    \n setNewClientJson(e.target.value)}\n autoSize={{ minRows: 15, maxRows: 25 }}\n style={{\n fontFamily: \"Monaco, Courier New, monospace\",\n fontSize: 13,\n }}\n />\n \n \n );\n}\n\nexport default MCPPage;\n" }, { "path": "console/src/pages/Agent/MCP/useMCP.ts", "content": "import { useCallback, useEffect, useState } from \"react\";\nimport { message } from \"@agentscope-ai/design\";\nimport api from \"../../../api\";\nimport type { MCPClientInfo } from \"../../../api/types\";\nimport { useTranslation } from \"react-i18next\";\nimport { useAgentStore } from \"../../../stores/agentStore\";\n\nexport function useMCP() {\n const { t } = useTranslation();\n const { selectedAgent } = useAgentStore();\n const [clients, setClients] = useState([]);\n const [loading, setLoading] = useState(false);\n\n const loadClients = useCallback(async () => {\n setLoading(true);\n try {\n const data = await api.listMCPClients();\n setClients(data);\n } catch (error) {\n console.error(\"Failed to load MCP clients:\", error);\n message.error(t(\"mcp.loadError\"));\n } finally {\n setLoading(false);\n }\n }, [t]);\n\n useEffect(() => {\n loadClients();\n }, [loadClients, selectedAgent]);\n\n const createClient = useCallback(\n async (\n key: string,\n clientData: {\n name: string;\n description?: string;\n command: string;\n enabled?: boolean;\n transport?: \"stdio\" | \"streamable_http\" | \"sse\";\n url?: string;\n headers?: Record;\n args?: string[];\n env?: Record;\n cwd?: string;\n },\n ) => {\n try {\n await api.createMCPClient({\n client_key: key,\n client: clientData,\n });\n message.success(t(\"mcp.createSuccess\"));\n await loadClients();\n return true;\n } catch (error: any) {\n const errorMsg = error?.message || t(\"mcp.createError\");\n message.error(errorMsg);\n return false;\n }\n },\n [t, loadClients],\n );\n\n const updateClient = useCallback(\n async (\n key: string,\n updates: {\n name?: string;\n description?: string;\n command?: string;\n enabled?: boolean;\n transport?: \"stdio\" | \"streamable_http\" | \"sse\";\n url?: string;\n headers?: Record;\n args?: string[];\n env?: Record;\n cwd?: string;\n },\n ) => {\n try {\n await api.updateMCPClient(key, updates);\n message.success(t(\"mcp.updateSuccess\"));\n await loadClients();\n return true;\n } catch (error: any) {\n const errorMsg = error?.message || t(\"mcp.updateError\");\n message.error(errorMsg);\n return false;\n }\n },\n [t, loadClients],\n );\n\n const toggleEnabled = useCallback(\n async (client: MCPClientInfo) => {\n try {\n await api.toggleMCPClient(client.key);\n message.success(\n client.enabled ? t(\"mcp.disableSuccess\") : t(\"mcp.enableSuccess\"),\n );\n await loadClients();\n } catch (error) {\n message.error(t(\"mcp.toggleError\"));\n }\n },\n [t, loadClients],\n );\n\n const deleteClient = useCallback(\n async (client: MCPClientInfo) => {\n try {\n await api.deleteMCPClient(client.key);\n message.success(t(\"mcp.deleteSuccess\"));\n await loadClients();\n } catch (error) {\n message.error(t(\"mcp.deleteError\"));\n }\n },\n [t, loadClients],\n );\n\n return {\n clients,\n loading,\n createClient,\n updateClient,\n toggleEnabled,\n deleteClient,\n };\n}\n" }, { "path": "console/src/pages/Agent/Skills/components/SkillCard.tsx", "content": "import { Card, Button, Tooltip } from \"@agentscope-ai/design\";\nimport {\n DeleteOutlined,\n FileTextFilled,\n FileZipFilled,\n FilePdfFilled,\n FileWordFilled,\n FileExcelFilled,\n FilePptFilled,\n FileImageFilled,\n CodeFilled,\n} from \"@ant-design/icons\";\nimport type { SkillSpec } from \"../../../../api/types\";\nimport { useTranslation } from \"react-i18next\";\nimport styles from \"../index.module.less\";\n\ninterface SkillCardProps {\n skill: SkillSpec;\n isHover: boolean;\n onClick: () => void;\n onMouseEnter: () => void;\n onMouseLeave: () => void;\n onToggleEnabled: (e: React.MouseEvent) => void;\n onDelete?: (e?: React.MouseEvent) => void;\n}\n\nconst getFileIcon = (filePath: string) => {\n const extension = filePath.split(\".\").pop()?.toLowerCase() || \"\";\n\n switch (extension) {\n case \"txt\":\n case \"md\":\n case \"markdown\":\n return ;\n case \"zip\":\n case \"rar\":\n case \"7z\":\n case \"tar\":\n case \"gz\":\n return ;\n case \"pdf\":\n return ;\n case \"doc\":\n case \"docx\":\n return ;\n case \"xls\":\n case \"xlsx\":\n return ;\n case \"ppt\":\n case \"pptx\":\n return ;\n case \"jpg\":\n case \"jpeg\":\n case \"png\":\n case \"gif\":\n case \"svg\":\n case \"webp\":\n return ;\n case \"py\":\n case \"js\":\n case \"ts\":\n case \"jsx\":\n case \"tsx\":\n case \"java\":\n case \"cpp\":\n case \"c\":\n case \"go\":\n case \"rs\":\n case \"rb\":\n case \"php\":\n return ;\n default:\n return ;\n }\n};\n\nexport function SkillCard({\n skill,\n isHover,\n onClick,\n onMouseEnter,\n onMouseLeave,\n onToggleEnabled,\n onDelete,\n}: SkillCardProps) {\n const { t } = useTranslation();\n const isCustomized = skill.source === \"customized\";\n\n const handleDeleteClick = (e: React.MouseEvent) => {\n e.stopPropagation();\n if (!skill.enabled && onDelete) {\n onDelete(e);\n }\n };\n\n return (\n \n
    \n
    \n
    \n {getFileIcon(skill.name)}\n

    {skill.name}

    \n
    \n
    \n \n \n {skill.enabled ? t(\"common.enabled\") : t(\"common.disabled\")}\n \n
    \n
    \n\n
    \n
    {t(\"skills.skillDescription\")}
    \n \n
    \n {skill.description || \"-\"}\n
    \n \n
    \n\n
    \n
    \n
    {t(\"skills.source\")}
    \n
    \n \n {skill.source}\n \n
    \n
    \n\n
    \n
    {t(\"skills.path\")}
    \n \n {skill.path}\n
    \n
    \n
    \n \n\n
    \n \n {skill.enabled ? t(\"common.disable\") : t(\"common.enable\")}\n \n\n {isCustomized && onDelete && (\n }\n className={styles.deleteButton}\n onClick={handleDeleteClick}\n disabled={skill.enabled}\n />\n )}\n
    \n \n );\n}\n" }, { "path": "console/src/pages/Agent/Skills/components/SkillDrawer.tsx", "content": "import { useState, useEffect, useCallback, useRef } from \"react\";\nimport { Drawer, Form, Input, Button, message } from \"@agentscope-ai/design\";\nimport { useTranslation } from \"react-i18next\";\nimport { ThunderboltOutlined, StopOutlined } from \"@ant-design/icons\";\nimport type { FormInstance } from \"antd\";\nimport type { SkillSpec } from \"../../../../api/types\";\nimport { MarkdownCopy } from \"../../../../components/MarkdownCopy/MarkdownCopy\";\nimport { api } from \"../../../../api\";\n\n/**\n * Parse frontmatter from content string.\n * Returns an object with parsed key-value pairs, or null if no valid frontmatter found.\n */\nfunction parseFrontmatter(content: string): Record | null {\n const trimmed = content.trim();\n if (!trimmed.startsWith(\"---\")) return null;\n\n const endIndex = trimmed.indexOf(\"---\", 3);\n if (endIndex === -1) return null;\n\n const frontmatterBlock = trimmed.slice(3, endIndex).trim();\n if (!frontmatterBlock) return null;\n\n const result: Record = {};\n for (const line of frontmatterBlock.split(\"\\n\")) {\n const colonIndex = line.indexOf(\":\");\n if (colonIndex > 0) {\n const key = line.slice(0, colonIndex).trim();\n const value = line.slice(colonIndex + 1).trim();\n result[key] = value;\n }\n }\n return result;\n}\n\ninterface SkillDrawerProps {\n open: boolean;\n editingSkill: SkillSpec | null;\n form: FormInstance;\n onClose: () => void;\n onSubmit: (values: SkillSpec) => void;\n onContentChange?: (content: string) => void;\n}\n\nexport function SkillDrawer({\n open,\n editingSkill,\n form,\n onClose,\n onSubmit,\n onContentChange,\n}: SkillDrawerProps) {\n const { t, i18n } = useTranslation();\n const [showMarkdown, setShowMarkdown] = useState(true);\n const [contentValue, setContentValue] = useState(\"\");\n const [optimizing, setOptimizing] = useState(false);\n const abortControllerRef = useRef(null);\n\n const validateFrontmatter = useCallback(\n (_: unknown, value: string) => {\n const content = contentValue || value;\n if (!content || !content.trim()) {\n return Promise.reject(new Error(t(\"skills.pleaseInputContent\")));\n }\n const fm = parseFrontmatter(content);\n if (!fm) {\n return Promise.reject(new Error(t(\"skills.frontmatterRequired\")));\n }\n if (!fm.name) {\n return Promise.reject(new Error(t(\"skills.frontmatterNameRequired\")));\n }\n if (!fm.description) {\n return Promise.reject(\n new Error(t(\"skills.frontmatterDescriptionRequired\")),\n );\n }\n return Promise.resolve();\n },\n [contentValue, t],\n );\n\n useEffect(() => {\n if (editingSkill) {\n setContentValue(editingSkill.content);\n form.setFieldsValue({\n name: editingSkill.name,\n content: editingSkill.content,\n });\n } else {\n setContentValue(\"\");\n form.resetFields();\n }\n }, [editingSkill, form]);\n\n const handleSubmit = (values: { name: string; content: string }) => {\n if (editingSkill) {\n message.warning(t(\"skills.editNotSupported\"));\n onClose();\n } else {\n onSubmit({\n ...values,\n content: contentValue || values.content,\n source: \"\",\n path: \"\",\n });\n }\n };\n\n const handleContentChange = (content: string) => {\n setContentValue(content);\n form.setFieldsValue({ content });\n form.validateFields([\"content\"]).catch(() => {});\n if (onContentChange) {\n onContentChange(content);\n }\n };\n\n const handleOptimize = async () => {\n if (!contentValue.trim()) {\n message.warning(t(\"skills.noContentToOptimize\"));\n return;\n }\n\n setOptimizing(true);\n abortControllerRef.current = new AbortController();\n const originalContent = contentValue;\n setContentValue(\"\"); // Clear content for streaming output\n\n try {\n await api.streamOptimizeSkill(\n originalContent,\n (textChunk) => {\n setContentValue((prev) => {\n const newContent = prev + textChunk;\n form.setFieldsValue({ content: newContent });\n return newContent;\n });\n },\n abortControllerRef.current.signal,\n i18n.language, // Pass current language to API\n );\n message.success(t(\"skills.optimizeSuccess\"));\n } catch (error: any) {\n if (error.name !== \"AbortError\") {\n message.error(error.message || t(\"skills.optimizeFailed\"));\n }\n } finally {\n setOptimizing(false);\n abortControllerRef.current = null;\n }\n };\n\n const handleStopOptimize = () => {\n if (abortControllerRef.current) {\n abortControllerRef.current.abort();\n setOptimizing(false);\n abortControllerRef.current = null;\n }\n };\n\n const drawerFooter = !editingSkill ? (\n \n
    \n {!optimizing ? (\n }\n onClick={handleOptimize}\n disabled={!contentValue.trim()}\n >\n {t(\"skills.optimizeWithAI\")}\n \n ) : (\n }\n onClick={handleStopOptimize}\n >\n {t(\"skills.stopOptimize\")}\n \n )}\n
    \n
    \n \n \n
    \n \n ) : (\n
    \n \n
    \n );\n\n return (\n \n
    \n {!editingSkill && (\n <>\n \n \n \n\n \n \n \n \n )}\n\n {editingSkill && (\n <>\n \n \n \n\n \n \n \n\n \n \n \n\n \n \n \n\n \n

    \n {t(\"skills.editNote\")}\n

    \n \n \n )}\n \n \n );\n}\n" }, { "path": "console/src/pages/Agent/Skills/components/index.ts", "content": "export { SkillCard } from \"./SkillCard\";\nexport { SkillDrawer } from \"./SkillDrawer\";\n" }, { "path": "console/src/pages/Agent/Skills/index.module.less", "content": ".skillsPage {\n padding: 24px;\n}\n\n.header {\n display: flex;\n justify-content: space-between;\n align-items: center;\n margin-bottom: 16px;\n}\n\n.headerInfo {\n display: flex;\n flex-direction: column;\n}\n\n.title {\n margin-bottom: 4px;\n font-size: 24px;\n font-weight: 600;\n}\n\n.description {\n margin: 0;\n color: #999;\n font-size: 14px;\n}\n\n.loading {\n text-align: center;\n padding: 60px;\n}\n\n.loadingText {\n color: #999;\n}\n\n.importHintBlock {\n margin-bottom: 12px;\n}\n\n.importHintTitle {\n margin: 0;\n font-size: 13px;\n color: #666;\n}\n\n.importHintList {\n margin: 8px 0;\n padding: 0 0 0 20px;\n font-size: 12px;\n color: #999;\n}\n\n.importUrlInput {\n width: 100%;\n height: 40px;\n padding: 0 12px;\n border: 1px solid #d9d9d9;\n border-radius: 8px;\n outline: none;\n font-size: 14px;\n\n &:focus {\n border-color: #615ced;\n }\n}\n\n.importUrlError {\n margin-top: 8px;\n color: #ff4d4f;\n font-size: 13px;\n}\n\n.importLoadingText {\n margin-top: 8px;\n font-size: 13px;\n color: #666;\n}\n\n.skillsGrid {\n display: grid;\n grid-template-columns: repeat(auto-fill, minmax(320px, 1fr));\n gap: 24px;\n}\n\n.skillCard {\n border-radius: 16px;\n transition: all 0.2s ease-in-out;\n cursor: pointer;\n overflow: hidden;\n\n :global(.ant-card-body) {\n padding: 16px 16px 12px;\n }\n\n &.enabledCard {\n border: 2px solid #615ced !important;\n box-shadow: rgba(97, 92, 237, 0.2) 0px 8px 24px !important;\n\n .statusDot.enabled {\n background-color: #52c41a;\n }\n\n .statusText.enabled {\n color: #52c41a;\n }\n }\n\n &.hover {\n border: 1px solid #615ced;\n box-shadow: 0 12px 32px rgba(0, 0, 0, 0.08);\n }\n\n &.normal {\n border: 1px solid rgba(0, 0, 0, 0.04);\n box-shadow: 0 4px 12px rgba(0, 0, 0, 0.04);\n }\n}\n\n.cardBody {\n display: flex;\n flex-direction: column;\n gap: 12px;\n}\n\n.cardHeader {\n display: flex;\n justify-content: space-between;\n align-items: flex-start;\n margin-bottom: 8px;\n}\n\n.skillTitle {\n margin: 0;\n font-size: 17px;\n font-weight: 600;\n color: #1a1a1a;\n line-height: 1.3;\n}\n\n.fileIcon {\n font-size: 22px;\n display: flex;\n align-items: center;\n}\n\n.statusContainer {\n display: flex;\n align-items: center;\n gap: 6px;\n}\n\n.statusDot {\n width: 6px;\n height: 6px;\n border-radius: 50%;\n\n &.enabled {\n background-color: #52c41a;\n }\n\n &.disabled {\n background-color: #d9d9d9;\n }\n}\n\n.statusText {\n font-size: 12px;\n\n &.enabled {\n color: #52c41a;\n }\n\n &.disabled {\n color: #999;\n }\n}\n\n.infoSection {\n display: flex;\n flex-direction: column;\n gap: 6px;\n min-width: 0;\n}\n\n.descriptionSection {\n display: flex;\n flex-direction: column;\n gap: 6px;\n}\n\n.infoBlock {\n font-size: 12px;\n color: #525866;\n background-color: #f5f6fa;\n border: 1px solid #eceff6;\n border-radius: 8px;\n padding: 8px 10px;\n}\n\n.descriptionContent {\n line-height: 1.45;\n word-break: break-word;\n display: -webkit-box;\n -webkit-box-orient: vertical;\n -webkit-line-clamp: 3;\n overflow: hidden;\n min-height: 64px;\n max-height: 64px;\n}\n\n.metaStack {\n display: flex;\n flex-direction: column;\n gap: 10px;\n}\n\n.infoLabel {\n font-size: 12px;\n color: #999;\n margin-bottom: 4px;\n}\n\n.singleLineValue {\n white-space: nowrap;\n overflow: hidden;\n text-overflow: ellipsis;\n}\n\n.builtinTag {\n font-size: 12px;\n color: #615ced;\n background: rgba(97, 92, 237, 0.1);\n border-radius: 4px;\n padding: 1px 6px;\n white-space: nowrap;\n}\n\n.customizedTag {\n font-size: 12px;\n color: #fa8c16;\n background: rgba(250, 140, 22, 0.1);\n border-radius: 4px;\n padding: 1px 6px;\n white-space: nowrap;\n}\n\n.pathValue {\n max-width: 100%;\n}\n\n.cardFooter {\n display: flex;\n justify-content: flex-end;\n align-items: center;\n gap: 8px;\n padding-top: 10px;\n margin-top: 2px;\n border-top: 1px solid #f1f2f6;\n}\n\n.actionButton {\n padding: 0;\n}\n\n.deleteButton {\n padding: 4px;\n display: flex;\n align-items: center;\n justify-content: center;\n\n &:hover {\n background-color: #ff4d4f;\n color: #fff;\n border-color: #ff4d4f;\n }\n}\n\n.contentLabel {\n font-size: 12px;\n font-weight: 600;\n display: flex;\n justify-content: space-between;\n align-items: center;\n height: 20px;\n width: 100%;\n\n label {\n width: 100%;\n }\n}\n\n.buttonGroup {\n display: flex;\n align-items: center;\n}\n\n.markdownToggle {\n display: flex;\n align-items: center;\n gap: 8px;\n}\n\n.toggleLabel {\n font-size: 12px;\n color: #666;\n white-space: nowrap;\n}\n\n.markdownViewer {\n min-height: 200px;\n max-height: 300px;\n overflow: auto;\n border: 1px solid #d9d9d9;\n border-radius: 6px;\n background-color: #fff;\n}\n\n.copyButton {\n border-radius: 4px;\n}\n\n@media (max-width: 768px) {\n .descriptionContent {\n min-height: 50px;\n }\n}\n\n/* ─── Dark mode ─────────────────────────────────────────────────────────────── */\n:global(.dark-mode) {\n .description {\n color: rgba(255, 255, 255, 0.35);\n }\n\n .loadingText {\n color: rgba(255, 255, 255, 0.35);\n }\n\n /* Import modal hints */\n .importHintTitle {\n color: rgba(255, 255, 255, 0.55);\n }\n\n .importHintList {\n color: rgba(255, 255, 255, 0.35);\n }\n\n .importUrlInput {\n background: #2a2a2a;\n border-color: rgba(255, 255, 255, 0.15);\n color: rgba(255, 255, 255, 0.85);\n\n &::placeholder {\n color: rgba(255, 255, 255, 0.25);\n }\n\n &:focus {\n border-color: #615ced;\n }\n }\n\n .importLoadingText {\n color: rgba(255, 255, 255, 0.45);\n }\n\n /* Skill card */\n .skillCard {\n &.normal {\n border-color: rgba(255, 255, 255, 0.08) !important;\n box-shadow: 0 4px 12px rgba(0, 0, 0, 0.3) !important;\n }\n\n &.hover {\n border-color: #615ced !important;\n box-shadow: 0 12px 32px rgba(0, 0, 0, 0.4) !important;\n }\n }\n\n .skillTitle {\n color: rgba(255, 255, 255, 0.85);\n }\n\n .statusDot.disabled {\n background-color: rgba(255, 255, 255, 0.2);\n }\n\n .statusText.disabled {\n color: rgba(255, 255, 255, 0.3);\n }\n\n /* Description info block */\n .infoBlock {\n color: rgba(255, 255, 255, 0.65);\n background-color: rgba(255, 255, 255, 0.05);\n border-color: rgba(255, 255, 255, 0.08);\n }\n\n /* Source / Path labels */\n .infoLabel {\n color: rgba(255, 255, 255, 0.3);\n }\n\n /* Card footer divider */\n .cardFooter {\n border-top-color: rgba(255, 255, 255, 0.08);\n }\n\n /* Toggle label */\n .toggleLabel {\n color: rgba(255, 255, 255, 0.45);\n }\n\n /* Markdown viewer */\n .markdownViewer {\n border-color: rgba(255, 255, 255, 0.1);\n background-color: #1f1f1f;\n color: rgba(255, 255, 255, 0.85);\n }\n}\n" }, { "path": "console/src/pages/Agent/Skills/index.tsx", "content": "import { useState, useRef } from \"react\";\nimport { Button, Form, Modal, message } from \"@agentscope-ai/design\";\nimport {\n DownloadOutlined,\n PlusOutlined,\n UploadOutlined,\n} from \"@ant-design/icons\";\nimport type { SkillSpec } from \"../../../api/types\";\nimport { SkillCard, SkillDrawer } from \"./components\";\nimport { useSkills } from \"./useSkills\";\nimport { useTranslation } from \"react-i18next\";\nimport styles from \"./index.module.less\";\n\nfunction SkillsPage() {\n const { t } = useTranslation();\n const {\n skills,\n loading,\n uploading,\n importing,\n cancelImport,\n createSkill,\n uploadSkill,\n importFromHub,\n toggleEnabled,\n deleteSkill,\n } = useSkills();\n const [drawerOpen, setDrawerOpen] = useState(false);\n const [importModalOpen, setImportModalOpen] = useState(false);\n const [importUrl, setImportUrl] = useState(\"\");\n const [importUrlError, setImportUrlError] = useState(\"\");\n const [editingSkill, setEditingSkill] = useState(null);\n const [hoverKey, setHoverKey] = useState(null);\n const [form] = Form.useForm();\n const fileInputRef = useRef(null);\n\n const MAX_UPLOAD_SIZE_MB = 100;\n\n const handleUploadClick = () => {\n fileInputRef.current?.click();\n };\n\n const handleFileChange = async (e: React.ChangeEvent) => {\n const file = e.target.files?.[0];\n if (!file) return;\n\n // Reset input so the same file can be re-selected\n e.target.value = \"\";\n\n if (!file.name.toLowerCase().endsWith(\".zip\")) {\n message.warning(t(\"skills.zipOnly\"));\n return;\n }\n\n const sizeMB = file.size / (1024 * 1024);\n if (sizeMB > MAX_UPLOAD_SIZE_MB) {\n message.warning(\n t(\"skills.fileSizeExceeded\", { size: sizeMB.toFixed(1) }),\n );\n return;\n }\n\n await uploadSkill(file);\n };\n\n const supportedSkillUrlPrefixes = [\n \"https://skills.sh/\",\n \"https://clawhub.ai/\",\n \"https://skillsmp.com/\",\n \"https://lobehub.com/\",\n \"https://market.lobehub.com/\",\n \"https://github.com/\",\n \"https://modelscope.cn/skills/\",\n ];\n\n const isSupportedSkillUrl = (url: string) => {\n return supportedSkillUrlPrefixes.some((prefix) => url.startsWith(prefix));\n };\n\n const handleCreate = () => {\n setEditingSkill(null);\n form.resetFields();\n form.setFieldsValue({\n enabled: false,\n });\n setDrawerOpen(true);\n };\n\n const closeImportModal = () => {\n if (importing) {\n return;\n }\n setImportModalOpen(false);\n setImportUrl(\"\");\n setImportUrlError(\"\");\n };\n\n const handleImportFromHub = () => {\n setImportModalOpen(true);\n };\n\n const handleImportUrlChange = (value: string) => {\n setImportUrl(value);\n const trimmed = value.trim();\n if (trimmed && !isSupportedSkillUrl(trimmed)) {\n setImportUrlError(t(\"skills.invalidSkillUrlSource\"));\n return;\n }\n setImportUrlError(\"\");\n };\n\n const handleConfirmImport = async () => {\n if (importing) return;\n const trimmed = importUrl.trim();\n if (!trimmed) return;\n if (!isSupportedSkillUrl(trimmed)) {\n setImportUrlError(t(\"skills.invalidSkillUrlSource\"));\n return;\n }\n const success = await importFromHub(trimmed);\n if (success) {\n closeImportModal();\n }\n };\n\n const handleEdit = (skill: SkillSpec) => {\n setEditingSkill(skill);\n form.setFieldsValue(skill);\n setDrawerOpen(true);\n };\n\n const handleToggleEnabled = async (skill: SkillSpec, e: React.MouseEvent) => {\n e.stopPropagation();\n await toggleEnabled(skill);\n };\n\n const handleDelete = async (skill: SkillSpec, e?: React.MouseEvent) => {\n e?.stopPropagation();\n await deleteSkill(skill);\n };\n\n const handleDrawerClose = () => {\n setDrawerOpen(false);\n setEditingSkill(null);\n };\n\n const handleSubmit = async (values: { name: string; content: string }) => {\n try {\n const success = await createSkill(values.name, values.content);\n if (success) {\n setDrawerOpen(false);\n }\n } catch (error) {\n console.error(\"Submit failed\", error);\n }\n };\n\n return (\n
    \n
    \n
    \n

    {t(\"skills.title\")}

    \n

    {t(\"skills.description\")}

    \n
    \n
    \n \n }\n loading={uploading}\n disabled={uploading}\n >\n {t(\"skills.uploadSkill\")}\n \n }\n >\n {t(\"skills.importSkills\")}\n \n \n
    \n
    \n\n \n \n {t(importing ? \"skills.cancelImport\" : \"common.cancel\")}\n \n \n {t(\"skills.importSkills\")}\n \n
    \n }\n width={760}\n >\n
    \n

    \n {t(\"skills.supportedSkillUrlSources\")}\n

    \n
      \n
    • https://skills.sh/
      • \n
    • https://clawhub.ai/
      • \n
    • https://skillsmp.com/
      • \n
    • https://lobehub.com/
      • \n
    • https://market.lobehub.com/
      • \n
    • https://github.com/
      • \n
    • https://modelscope.cn/skills/
      • \n
    \n

    {t(\"skills.urlExamples\")}

    \n
      \n
    • https://skills.sh/vercel-labs/skills/find-skills
      • \n
    • https://lobehub.com/zh/skills/openclaw-skills-cli-developer
      • \n
    • \n https://market.lobehub.com/api/v1/skills/openclaw-skills-cli-developer/download\n
      • \n
    • \n https://github.com/anthropics/skills/tree/main/skills/skill-creator\n
      • \n
    • https://modelscope.cn/skills/@anthropics/skill-creator
      • \n
    \n
    \n\n handleImportUrlChange(e.target.value)}\n placeholder={t(\"skills.enterSkillUrl\")}\n disabled={importing}\n />\n {importUrlError ? (\n
    {importUrlError}
    \n ) : null}\n {importing ? (\n
    {t(\"common.loading\")}
    \n ) : null}\n \n\n {loading ? (\n
    \n {t(\"common.loading\")}\n
    \n ) : (\n
    \n {skills\n .slice()\n .sort((a, b) => {\n if (a.enabled && !b.enabled) return -1;\n if (!a.enabled && b.enabled) return 1;\n return a.name.localeCompare(b.name);\n })\n .map((skill) => (\n handleEdit(skill)}\n onMouseEnter={() => setHoverKey(skill.name)}\n onMouseLeave={() => setHoverKey(null)}\n onToggleEnabled={(e) => handleToggleEnabled(skill, e)}\n onDelete={(e) => handleDelete(skill, e)}\n />\n ))}\n
    \n )}\n\n \n \n );\n}\n\nexport default SkillsPage;\n" }, { "path": "console/src/pages/Agent/Skills/useSkills.ts", "content": "import { useState, useEffect, useCallback, useRef } from \"react\";\nimport { message, Modal } from \"@agentscope-ai/design\";\nimport React from \"react\";\nimport api from \"../../../api\";\nimport type { SkillSpec } from \"../../../api/types\";\nimport type { SecurityScanErrorResponse } from \"../../../api/modules/security\";\nimport { useTranslation } from \"react-i18next\";\nimport { useAgentStore } from \"../../../stores/agentStore\";\n\nfunction tryParseScanError(error: unknown): SecurityScanErrorResponse | null {\n if (!(error instanceof Error)) return null;\n const msg = error.message || \"\";\n const jsonStart = msg.indexOf(\"{\");\n if (jsonStart === -1) return null;\n try {\n const parsed = JSON.parse(msg.substring(jsonStart));\n if (parsed?.type === \"security_scan_failed\") {\n return parsed as SecurityScanErrorResponse;\n }\n } catch {\n // not JSON\n }\n return null;\n}\n\nexport function useSkills() {\n const { t } = useTranslation();\n const { selectedAgent } = useAgentStore();\n const [skills, setSkills] = useState([]);\n const [loading, setLoading] = useState(false);\n const [uploading, setUploading] = useState(false);\n const [importing, setImporting] = useState(false);\n const importTaskIdRef = useRef(null);\n const importCancelReasonRef = useRef<\"manual\" | \"timeout\" | null>(null);\n\n const showScanErrorModal = useCallback(\n (scanError: SecurityScanErrorResponse) => {\n const findings = scanError.findings || [];\n Modal.error({\n title: t(\"security.skillScanner.scanError.title\"),\n width: 640,\n content: React.createElement(\n \"div\",\n null,\n React.createElement(\n \"p\",\n null,\n t(\"security.skillScanner.scanError.description\"),\n ),\n React.createElement(\n \"div\",\n {\n style: {\n maxHeight: 300,\n overflow: \"auto\",\n marginTop: 8,\n },\n },\n findings.map((f, i) =>\n React.createElement(\n \"div\",\n {\n key: i,\n style: {\n padding: \"8px 12px\",\n marginBottom: 4,\n background: \"#fafafa\",\n borderRadius: 6,\n border: \"1px solid #f0f0f0\",\n },\n },\n React.createElement(\n \"strong\",\n { style: { marginBottom: 4, display: \"block\" } },\n f.title,\n ),\n React.createElement(\n \"div\",\n { style: { fontSize: 12, color: \"#666\" } },\n f.file_path + (f.line_number ? `:${f.line_number}` : \"\"),\n ),\n f.description &&\n React.createElement(\n \"div\",\n {\n style: {\n fontSize: 12,\n color: \"#999\",\n marginTop: 2,\n },\n },\n f.description,\n ),\n ),\n ),\n ),\n ),\n });\n },\n [t],\n );\n\n const handleError = useCallback(\n (error: unknown, defaultMsg: string): boolean => {\n const scanError = tryParseScanError(error);\n if (scanError) {\n showScanErrorModal(scanError);\n return true;\n }\n const msg =\n error instanceof Error && error.message ? error.message : defaultMsg;\n console.error(defaultMsg, error);\n message.error(msg);\n return false;\n },\n [showScanErrorModal],\n );\n\n const checkScanWarnings = useCallback(\n async (skillName: string) => {\n try {\n const [alerts, scannerCfg] = await Promise.all([\n api.getBlockedHistory(),\n api.getSkillScanner(),\n ]);\n if (!alerts.length) return;\n if (\n scannerCfg?.whitelist?.some(\n (w: { skill_name: string }) => w.skill_name === skillName,\n )\n )\n return;\n const latestForSkill = alerts\n .filter((a) => a.skill_name === skillName && a.action === \"warned\")\n .pop();\n if (!latestForSkill) return;\n const findings = latestForSkill.findings || [];\n Modal.warning({\n title: t(\"security.skillScanner.scanError.title\"),\n width: 640,\n content: React.createElement(\n \"div\",\n null,\n React.createElement(\n \"p\",\n null,\n t(\"security.skillScanner.scanError.warnDescription\"),\n ),\n React.createElement(\n \"div\",\n { style: { maxHeight: 300, overflow: \"auto\", marginTop: 8 } },\n findings.map((f, i) =>\n React.createElement(\n \"div\",\n {\n key: i,\n style: {\n padding: \"8px 12px\",\n marginBottom: 4,\n background: \"#fafafa\",\n borderRadius: 6,\n border: \"1px solid #f0f0f0\",\n },\n },\n React.createElement(\n \"strong\",\n { style: { marginBottom: 4, display: \"block\" } },\n f.title,\n ),\n React.createElement(\n \"div\",\n { style: { fontSize: 12, color: \"#666\" } },\n f.file_path + (f.line_number ? `:${f.line_number}` : \"\"),\n ),\n f.description &&\n React.createElement(\n \"div\",\n { style: { fontSize: 12, color: \"#999\", marginTop: 2 } },\n f.description,\n ),\n ),\n ),\n ),\n ),\n });\n } catch {\n // non-critical\n }\n },\n [t],\n );\n\n const fetchSkills = async () => {\n setLoading(true);\n try {\n const data = await api.listSkills();\n if (data) {\n setSkills(data);\n }\n } catch (error) {\n console.error(\"Failed to load skills\", error);\n message.error(\"Failed to load skills\");\n } finally {\n setLoading(false);\n }\n };\n\n useEffect(() => {\n let mounted = true;\n\n const loadSkills = async () => {\n await fetchSkills();\n };\n\n if (mounted) {\n loadSkills();\n }\n\n return () => {\n mounted = false;\n };\n }, [selectedAgent]);\n\n const createSkill = async (name: string, content: string) => {\n try {\n await api.createSkill(name, content);\n message.success(\"Created successfully\");\n await fetchSkills();\n await checkScanWarnings(name);\n return true;\n } catch (error) {\n handleError(error, \"Failed to save\");\n return false;\n }\n };\n\n const uploadSkill = async (file: File) => {\n try {\n setUploading(true);\n const result = await api.uploadSkill(file, {\n enable: false,\n overwrite: false,\n });\n if (result?.count > 0) {\n message.success(\n t(\"skills.uploadSuccess\") + `: ${result.imported.join(\", \")}`,\n );\n await fetchSkills();\n for (const name of result.imported) {\n await checkScanWarnings(name);\n }\n return true;\n }\n message.warning(t(\"skills.uploadNoChange\"));\n await fetchSkills();\n return true;\n } catch (error) {\n handleError(error, t(\"skills.uploadFailed\"));\n return false;\n } finally {\n setUploading(false);\n }\n };\n\n const importFromHub = async (input: string) => {\n const text = (input || \"\").trim();\n if (!text) {\n message.warning(\"Please provide a hub skill URL\");\n return false;\n }\n if (!text.startsWith(\"http://\") && !text.startsWith(\"https://\")) {\n message.warning(\n \"Please enter a valid URL starting with http:// or https://\",\n );\n return false;\n }\n const timeoutMs = 90_000;\n const pollMs = 1_000;\n const startedAt = Date.now();\n try {\n setImporting(true);\n importCancelReasonRef.current = null;\n const payload = { bundle_url: text, enable: true, overwrite: false };\n const task = await api.startHubSkillInstall(payload);\n importTaskIdRef.current = task.task_id;\n\n while (importTaskIdRef.current) {\n const status = await api.getHubSkillInstallStatus(task.task_id);\n\n if (status.status === \"completed\" && status.result?.installed) {\n message.success(`Imported skill: ${status.result.name}`);\n await fetchSkills();\n if (status.result.name) await checkScanWarnings(status.result.name);\n return true;\n }\n\n if (status.status === \"failed\") {\n throw new Error(status.error || \"Import failed\");\n }\n\n if (status.status === \"cancelled\") {\n message.warning(\n t(\n importCancelReasonRef.current === \"timeout\"\n ? \"skills.importTimeout\"\n : \"skills.importCancelled\",\n ),\n );\n return false;\n }\n\n if (Date.now() - startedAt >= timeoutMs) {\n importCancelReasonRef.current = \"timeout\";\n await api.cancelHubSkillInstall(task.task_id);\n }\n\n await new Promise((resolve) => window.setTimeout(resolve, pollMs));\n }\n\n return false;\n } catch (error) {\n handleError(error, \"Import failed\");\n return false;\n } finally {\n importTaskIdRef.current = null;\n importCancelReasonRef.current = null;\n setImporting(false);\n }\n };\n\n const cancelImport = useCallback(() => {\n if (!importing) return;\n importCancelReasonRef.current = \"manual\";\n const taskId = importTaskIdRef.current;\n if (!taskId) return;\n void api.cancelHubSkillInstall(taskId);\n }, [importing]);\n\n const toggleEnabled = async (skill: SkillSpec) => {\n try {\n if (skill.enabled) {\n await api.disableSkill(skill.name);\n setSkills((prev) =>\n prev.map((s) =>\n s.name === skill.name ? { ...s, enabled: false } : s,\n ),\n );\n message.success(\"Disabled successfully\");\n } else {\n await api.enableSkill(skill.name);\n setSkills((prev) =>\n prev.map((s) =>\n s.name === skill.name ? { ...s, enabled: true } : s,\n ),\n );\n message.success(\"Enabled successfully\");\n await checkScanWarnings(skill.name);\n }\n return true;\n } catch (error) {\n handleError(error, \"Operation failed\");\n return false;\n }\n };\n\n const deleteSkill = async (skill: SkillSpec) => {\n const confirmed = await new Promise((resolve) => {\n Modal.confirm({\n title: \"Confirm Delete\",\n content: `Are you sure you want to delete skill \"${skill.name}\"? This action cannot be undone.`,\n okText: \"Delete\",\n okType: \"danger\",\n cancelText: \"Cancel\",\n onOk: () => resolve(true),\n onCancel: () => resolve(false),\n });\n });\n\n if (!confirmed) return false;\n\n try {\n const result = await api.deleteSkill(skill.name);\n if (result.deleted) {\n message.success(\"Deleted successfully\");\n await fetchSkills();\n return true;\n } else {\n message.error(\"Failed to delete skill\");\n return false;\n }\n } catch (error) {\n console.error(\"Failed to delete skill\", error);\n message.error(\"Failed to delete skill\");\n return false;\n }\n };\n\n return {\n skills,\n loading,\n uploading,\n importing,\n cancelImport,\n createSkill,\n uploadSkill,\n importFromHub,\n toggleEnabled,\n deleteSkill,\n };\n}\n" }, { "path": "console/src/pages/Agent/Tools/index.module.less", "content": ".toolsPage {\n padding: 24px;\n}\n\n.header {\n display: flex;\n justify-content: space-between;\n align-items: flex-start;\n margin-bottom: 24px;\n}\n\n.headerInfo {\n display: flex;\n flex-direction: column;\n}\n\n.actionTabs {\n display: flex;\n gap: 4px;\n padding: 4px;\n background: rgba(0, 0, 0, 0.04);\n border-radius: 10px;\n align-self: center;\n}\n\n.actionTab {\n padding: 5px 14px;\n border-radius: 7px;\n border: none;\n font-size: 13px;\n color: #999;\n background: transparent;\n cursor: pointer;\n transition: all 0.18s ease;\n\n &:hover {\n color: #666;\n background: rgba(0, 0, 0, 0.04);\n }\n}\n\n.disabledTab {\n color: #615ced !important;\n background: #fff !important;\n cursor: not-allowed;\n box-shadow: 0 1px 4px rgba(0, 0, 0, 0.1);\n\n &:hover {\n color: #615ced !important;\n background: #fff !important;\n }\n}\n\n.title {\n margin-bottom: 4px;\n font-size: 24px;\n font-weight: 600;\n}\n\n.description {\n margin: 0;\n color: #999;\n font-size: 14px;\n}\n\n.loading {\n text-align: center;\n padding: 60px;\n color: #999;\n}\n\n.toolsGrid {\n display: grid;\n grid-template-columns: repeat(auto-fill, minmax(320px, 1fr));\n gap: 24px;\n}\n\n.toolCard {\n border-radius: 16px;\n transition: all 0.2s ease-in-out;\n cursor: default;\n\n &.enabledCard {\n border: 2px solid #615ced !important;\n box-shadow: rgba(97, 92, 237, 0.2) 0px 8px 24px !important;\n\n .statusDot {\n background-color: #52c41a;\n }\n\n .statusText {\n color: #52c41a;\n }\n }\n\n &.hoverCard {\n border: 1px solid #615ced;\n box-shadow: 0 12px 32px rgba(0, 0, 0, 0.08);\n }\n\n &.normalCard {\n border: 1px solid rgba(0, 0, 0, 0.04);\n box-shadow: 0 4px 12px rgba(0, 0, 0, 0.04);\n }\n}\n\n.cardHeader {\n display: flex;\n justify-content: space-between;\n align-items: flex-start;\n margin-bottom: 8px;\n}\n\n.toolName {\n margin: 0;\n font-size: 16px;\n font-weight: 600;\n color: #1a1a1a;\n font-family: Monaco, \"Courier New\", monospace;\n}\n\n.statusContainer {\n display: flex;\n align-items: center;\n gap: 6px;\n flex-shrink: 0;\n}\n\n.statusDot {\n width: 6px;\n height: 6px;\n border-radius: 50%;\n background-color: #d9d9d9;\n}\n\n.statusText {\n font-size: 12px;\n color: #999;\n}\n\n.toolDescription {\n margin: 0 0 16px 0;\n color: #666;\n font-size: 13px;\n line-height: 1.6;\n min-height: 40px;\n overflow: hidden;\n text-overflow: ellipsis;\n display: -webkit-box;\n -webkit-line-clamp: 2;\n -webkit-box-orient: vertical;\n}\n\n.cardFooter {\n display: flex;\n justify-content: flex-end;\n align-items: center;\n padding-top: 12px;\n border-top: 1px solid #f0f0f0;\n}\n" }, { "path": "console/src/pages/Agent/Tools/index.tsx", "content": "import { useState, useMemo } from \"react\";\nimport { Card, Switch, Empty, Button } from \"@agentscope-ai/design\";\nimport { useTools } from \"./useTools\";\nimport { useTranslation } from \"react-i18next\";\nimport type { ToolInfo } from \"../../../api/modules/tools\";\nimport styles from \"./index.module.less\";\n\nexport default function ToolsPage() {\n const { t } = useTranslation();\n const { tools, loading, batchLoading, toggleEnabled, enableAll, disableAll } =\n useTools();\n const [hoverKey, setHoverKey] = useState(null);\n\n const handleToggle = (tool: ToolInfo) => {\n toggleEnabled(tool);\n };\n\n const hasDisabledTools = useMemo(\n () => tools.some((tool) => !tool.enabled),\n [tools],\n );\n const hasEnabledTools = useMemo(\n () => tools.some((tool) => tool.enabled),\n [tools],\n );\n\n return (\n
    \n
    \n
    \n

    {t(\"tools.title\")}

    \n

    {t(\"tools.description\")}

    \n
    \n
    \n \n {t(\"tools.enableAll\")}\n \n \n {t(\"tools.disableAll\")}\n \n
    \n
    \n\n {loading ? (\n
    \n

    {t(\"common.loading\")}

    \n
    \n ) : tools.length === 0 ? (\n \n ) : (\n
    \n {tools.map((tool) => (\n setHoverKey(tool.name)}\n onMouseLeave={() => setHoverKey(null)}\n >\n
    \n

    {tool.name}

    \n
    \n \n \n {tool.enabled ? t(\"common.enabled\") : t(\"common.disabled\")}\n \n
    \n
    \n\n

    {tool.description}

    \n\n
    \n handleToggle(tool)}\n />\n
    \n \n ))}\n
    \n )}\n
    \n );\n}\n" }, { "path": "console/src/pages/Agent/Tools/useTools.ts", "content": "import { useCallback, useEffect, useState } from \"react\";\nimport { message } from \"@agentscope-ai/design\";\nimport api from \"../../../api\";\nimport type { ToolInfo } from \"../../../api/modules/tools\";\nimport { useTranslation } from \"react-i18next\";\nimport { useAgentStore } from \"../../../stores/agentStore\";\n\nexport function useTools() {\n const { t } = useTranslation();\n const { selectedAgent } = useAgentStore();\n const [tools, setTools] = useState([]);\n const [loading, setLoading] = useState(false);\n const [batchLoading, setBatchLoading] = useState(false);\n\n const loadTools = useCallback(async () => {\n setLoading(true);\n try {\n const data = await api.listTools();\n setTools(data);\n } catch (error) {\n console.error(\"Failed to load tools:\", error);\n message.error(t(\"tools.loadError\"));\n } finally {\n setLoading(false);\n }\n }, [t]);\n\n useEffect(() => {\n loadTools();\n }, [loadTools, selectedAgent]);\n\n const toggleEnabled = useCallback(\n async (tool: ToolInfo) => {\n // Optimistic update\n setTools((prev) =>\n prev.map((t) =>\n t.name === tool.name ? { ...t, enabled: !t.enabled } : t,\n ),\n );\n\n try {\n const result = await api.toggleTool(tool.name);\n message.success(\n tool.enabled ? t(\"tools.disableSuccess\") : t(\"tools.enableSuccess\"),\n );\n // Update with server response (no full reload)\n setTools((prev) =>\n prev.map((t) => (t.name === result.name ? result : t)),\n );\n } catch (error) {\n // Revert optimistic update on error\n setTools((prev) =>\n prev.map((t) =>\n t.name === tool.name ? { ...t, enabled: tool.enabled } : t,\n ),\n );\n message.error(t(\"tools.toggleError\"));\n }\n },\n [t],\n );\n\n const enableAll = useCallback(async () => {\n const disabledTools = tools.filter((tool) => !tool.enabled);\n if (disabledTools.length === 0) {\n message.info(t(\"tools.allEnabled\"));\n return;\n }\n\n // Optimistic update\n setTools((prev) => prev.map((t) => ({ ...t, enabled: true })));\n\n setBatchLoading(true);\n try {\n const results = await Promise.all(\n disabledTools.map((tool) => api.toggleTool(tool.name)),\n );\n message.success(t(\"tools.enableAllSuccess\"));\n // Update with server responses\n setTools((prev) =>\n prev.map((t) => {\n const result = results.find((r) => r.name === t.name);\n return result || t;\n }),\n );\n } catch (error) {\n message.error(t(\"tools.toggleError\"));\n // Reload on error to sync with server\n await loadTools();\n } finally {\n setBatchLoading(false);\n }\n }, [tools, t, loadTools]);\n\n const disableAll = useCallback(async () => {\n const enabledTools = tools.filter((tool) => tool.enabled);\n if (enabledTools.length === 0) {\n message.info(t(\"tools.allDisabled\"));\n return;\n }\n\n // Optimistic update\n setTools((prev) => prev.map((t) => ({ ...t, enabled: false })));\n\n setBatchLoading(true);\n try {\n const results = await Promise.all(\n enabledTools.map((tool) => api.toggleTool(tool.name)),\n );\n message.success(t(\"tools.disableAllSuccess\"));\n // Update with server responses\n setTools((prev) =>\n prev.map((t) => {\n const result = results.find((r) => r.name === t.name);\n return result || t;\n }),\n );\n } catch (error) {\n message.error(t(\"tools.toggleError\"));\n // Reload on error to sync with server\n await loadTools();\n } finally {\n setBatchLoading(false);\n }\n }, [tools, t, loadTools]);\n\n return {\n tools,\n loading,\n batchLoading,\n toggleEnabled,\n enableAll,\n disableAll,\n };\n}\n" }, { "path": "console/src/pages/Agent/Workspace/components/FileEditor.tsx", "content": "import React, { useState, useMemo } from \"react\";\nimport { Button, Card, Input, Switch, message } from \"@agentscope-ai/design\";\nimport { CopyOutlined, UndoOutlined, SaveOutlined } from \"@ant-design/icons\";\nimport type { MarkdownFile } from \"../../../../api/types\";\nimport { XMarkdown } from \"@ant-design/x-markdown\";\nimport { useTranslation } from \"react-i18next\";\nimport { stripFrontmatter } from \"../../../../utils/markdown\";\nimport styles from \"../index.module.less\";\n\ninterface FileEditorProps {\n selectedFile: MarkdownFile | null;\n fileContent: string;\n loading: boolean;\n hasChanges: boolean;\n onContentChange: (content: string) => void;\n onSave: () => void;\n onReset: () => void;\n}\n\nexport const FileEditor: React.FC = ({\n selectedFile,\n fileContent,\n loading,\n hasChanges,\n onContentChange,\n onSave,\n onReset,\n}) => {\n const { t } = useTranslation();\n const [showMarkdown, setShowMarkdown] = useState(true);\n\n const isMarkdownFile = selectedFile?.filename.endsWith(\".md\") || false;\n const markdownContent = useMemo(\n () => stripFrontmatter(fileContent || \"\"),\n [fileContent],\n );\n\n const copyToClipboard = async () => {\n try {\n if (navigator.clipboard && window.isSecureContext) {\n await navigator.clipboard.writeText(fileContent);\n message.success(t(\"common.copied\"));\n } else {\n const textArea = document.createElement(\"textarea\");\n textArea.value = fileContent;\n textArea.style.position = \"fixed\";\n textArea.style.left = \"-999999px\";\n textArea.style.top = \"-999999px\";\n document.body.appendChild(textArea);\n textArea.focus();\n textArea.select();\n document.execCommand(\"copy\");\n textArea.remove();\n message.success(t(\"common.copied\"));\n }\n } catch (err) {\n console.error(\"Failed to copy text: \", err);\n message.error(t(\"common.copyFailed\"));\n }\n };\n\n return (\n
    \n \n {selectedFile ? (\n <>\n
    \n
    \n
    {selectedFile.filename}
    \n
    {selectedFile.path}
    \n
    \n
    \n }\n >\n {t(\"common.reset\")}\n \n }\n >\n {t(\"common.save\")}\n \n
    \n
    \n\n
    \n
    \n
    {t(\"common.content\")}
    \n {isMarkdownFile && (\n
    \n
    \n \n {t(\"common.preview\")}\n \n \n
    \n }\n type=\"text\"\n onClick={copyToClipboard}\n className={styles.copyButton}\n />\n
    \n )}\n
    \n {showMarkdown && isMarkdownFile ? (\n \n ) : (\n onContentChange(e.target.value)}\n className={styles.textarea}\n placeholder={t(\"workspace.fileContent\")}\n />\n )}\n
    \n \n ) : (\n
    {t(\"workspace.selectFile\")}
    \n )}\n     \n
    \n );\n};\n" }, { "path": "console/src/pages/Agent/Workspace/components/FileItem.tsx", "content": "import React from \"react\";\nimport { Switch, Tooltip } from \"@agentscope-ai/design\";\nimport {\n CaretDownOutlined,\n CaretRightOutlined,\n HolderOutlined,\n} from \"@ant-design/icons\";\nimport { useSortable } from \"@dnd-kit/sortable\";\nimport { CSS } from \"@dnd-kit/utilities\";\nimport type { MarkdownFile, DailyMemoryFile } from \"../../../../api/types\";\nimport { formatFileSize, formatTimeAgo } from \"./utils\";\nimport { useTranslation } from \"react-i18next\";\nimport styles from \"../index.module.less\";\n\ninterface FileItemProps {\n file: MarkdownFile;\n selectedFile: MarkdownFile | null;\n expandedMemory: boolean;\n dailyMemories: DailyMemoryFile[];\n enabled?: boolean;\n onFileClick: (file: MarkdownFile) => void;\n onDailyMemoryClick: (daily: DailyMemoryFile) => void;\n onToggleEnabled: (filename: string) => void;\n}\n\nexport const FileItem: React.FC = ({\n file,\n selectedFile,\n expandedMemory,\n dailyMemories,\n enabled = false,\n onFileClick,\n onDailyMemoryClick,\n onToggleEnabled,\n}) => {\n const { t } = useTranslation();\n const isSelected = selectedFile?.filename === file.filename;\n const isMemoryFile = file.filename === \"MEMORY.md\";\n\n const {\n attributes,\n listeners,\n setNodeRef,\n transform,\n transition,\n isDragging,\n } = useSortable({\n id: file.filename,\n disabled: !enabled,\n });\n\n const style: React.CSSProperties = {\n transform: CSS.Transform.toString(transform),\n transition,\n opacity: isDragging ? 0.5 : 1,\n position: \"relative\",\n zIndex: isDragging ? 1 : undefined,\n };\n\n const handleToggleClick = (\n _checked: boolean,\n event:\n | React.MouseEvent\n | React.KeyboardEvent,\n ) => {\n event.stopPropagation();\n onToggleEnabled(file.filename);\n };\n\n return (\n
    \n onFileClick(file)}\n className={`${styles.fileItem} ${isSelected ? styles.selected : \"\"} ${\n isDragging ? styles.dragging : \"\"\n }`}\n >\n
    \n {enabled && (\n e.stopPropagation()}\n >\n \n
    \n )}\n
    \n
    \n {enabled && ●}\n {file.filename}\n
    \n
    \n {formatFileSize(file.size)} · {formatTimeAgo(file.updated_at)}\n
    \n
    \n
    \n \n \n \n {isMemoryFile && (\n \n {expandedMemory ? (\n \n ) : (\n \n )}\n \n )}\n
    \n
    \n \n\n {isMemoryFile && expandedMemory && (\n
    \n {dailyMemories.map((daily) => {\n const isDailySelected =\n selectedFile?.filename === `${daily.date}.md`;\n return (\n onDailyMemoryClick(daily)}\n className={`${styles.dailyMemoryItem} ${\n isDailySelected ? styles.selected : \"\"\n }`}\n >\n
    {daily.date}.md
    \n
    \n {formatFileSize(daily.size)} ·{\" \"}\n {formatTimeAgo(daily.updated_at)}\n
    \n
    \n );\n })}\n \n )}\n \n );\n};\n" }, { "path": "console/src/pages/Agent/Workspace/components/FileListPanel.tsx", "content": "import React from \"react\";\nimport { Button, Card } from \"@agentscope-ai/design\";\nimport { ReloadOutlined } from \"@ant-design/icons\";\nimport {\n DndContext,\n closestCenter,\n PointerSensor,\n useSensor,\n useSensors,\n DragEndEvent,\n} from \"@dnd-kit/core\";\nimport {\n SortableContext,\n verticalListSortingStrategy,\n arrayMove,\n} from \"@dnd-kit/sortable\";\nimport type { MarkdownFile, DailyMemoryFile } from \"../../../../api/types\";\nimport { FileItem } from \"./FileItem\";\nimport { useTranslation } from \"react-i18next\";\nimport styles from \"../index.module.less\";\n\ninterface FileListPanelProps {\n files: MarkdownFile[];\n selectedFile: MarkdownFile | null;\n dailyMemories: DailyMemoryFile[];\n expandedMemory: boolean;\n workspacePath: string | null;\n enabledFiles: string[];\n onRefresh: () => void;\n onFileClick: (file: MarkdownFile) => void;\n onDailyMemoryClick: (daily: DailyMemoryFile) => void;\n onToggleEnabled: (filename: string) => void;\n onReorder: (newOrder: string[]) => void;\n}\n\nexport const FileListPanel: React.FC = ({\n files,\n selectedFile,\n dailyMemories,\n expandedMemory,\n enabledFiles,\n onRefresh,\n onFileClick,\n onDailyMemoryClick,\n onToggleEnabled,\n onReorder,\n}) => {\n const { t } = useTranslation();\n\n const sensors = useSensors(\n useSensor(PointerSensor, {\n activationConstraint: {\n distance: 5,\n },\n }),\n );\n\n const handleDragEnd = (event: DragEndEvent) => {\n const { active, over } = event;\n if (!over || active.id === over.id) return;\n\n const oldIndex = enabledFiles.indexOf(active.id as string);\n const newIndex = enabledFiles.indexOf(over.id as string);\n if (oldIndex === -1 || newIndex === -1) return;\n\n const newOrder = arrayMove(enabledFiles, oldIndex, newIndex);\n onReorder(newOrder);\n };\n\n return (\n
    \n \n
    \n

    {t(\"workspace.coreFiles\")}

    \n \n
    \n\n

    {t(\"workspace.coreFilesDesc\")}

    \n
    \n\n
    \n {files.length > 0 ? (\n \n \n {files.map((file) => {\n const isEnabled = enabledFiles.includes(file.filename);\n return (\n \n );\n })}\n \n \n ) : (\n
    {t(\"workspace.noFiles\")}
    \n )}\n
    \n \n
    \n );\n};\n" }, { "path": "console/src/pages/Agent/Workspace/components/index.ts", "content": "export { FileListPanel } from \"./FileListPanel\";\nexport { FileEditor } from \"./FileEditor\";\nexport { FileItem } from \"./FileItem\";\nexport { useAgentsData } from \"./useAgentsData\";\nexport * from \"./utils\";\n" }, { "path": "console/src/pages/Agent/Workspace/components/useAgentsData.ts", "content": "import { useState, useEffect } from \"react\";\nimport { message } from \"@agentscope-ai/design\";\nimport { useTranslation } from \"react-i18next\";\nimport api from \"../../../../api\";\nimport type { MarkdownFile, DailyMemoryFile } from \"../../../../api/types\";\nimport { workspaceApi } from \"../../../../api/modules/workspace\";\nimport { agentsApi } from \"../../../../api/modules/agents\";\nimport { useAgentStore } from \"../../../../stores/agentStore\";\n\n// Returns the parent directory of a file path, supporting both '/' and '\\' separators.\nconst getParentDir = (filePath: string): string => {\n const match = filePath.match(/^(.*)[/\\\\]/);\n return match ? match[1] : filePath;\n};\n\nexport const useAgentsData = () => {\n const { t } = useTranslation();\n const { selectedAgent } = useAgentStore();\n const [files, setFiles] = useState([]);\n const [selectedFile, setSelectedFile] = useState(null);\n const [dailyMemories, setDailyMemories] = useState([]);\n const [expandedMemory, setExpandedMemory] = useState(false);\n const [fileContent, setFileContent] = useState(\"\");\n const [originalContent, setOriginalContent] = useState(\"\");\n const [loading, setLoading] = useState(false);\n const [workspacePath, setWorkspacePath] = useState(null);\n const [enabledFiles, setEnabledFiles] = useState([]);\n\n useEffect(() => {\n const initializeData = async () => {\n // Remember currently selected file name\n const previouslySelectedFilename = selectedFile?.filename;\n\n // Clear content first\n setFileContent(\"\");\n setOriginalContent(\"\");\n setExpandedMemory(false);\n\n const enabled = await fetchEnabledFiles();\n const fileList = await agentsApi.listAgentFiles(selectedAgent);\n const sortedFiles = sortFilesByEnabled(\n fileList as unknown as MarkdownFile[],\n enabled,\n );\n setFiles(sortedFiles);\n\n // Set workspace path (handle both Unix '/' and Windows '\\' separators)\n if (fileList.length > 0) {\n setWorkspacePath(getParentDir(fileList[0].path));\n } else {\n setWorkspacePath(\"\");\n }\n\n // Try to re-select the same file in new workspace\n if (previouslySelectedFilename) {\n const sameFile = sortedFiles.find(\n (f) => f.filename === previouslySelectedFilename,\n );\n if (sameFile) {\n // Auto-load the same file from new workspace\n await handleFileClick(sameFile);\n } else {\n // File doesn't exist in new workspace, clear selection\n setSelectedFile(null);\n }\n } else {\n setSelectedFile(null);\n }\n };\n initializeData();\n // eslint-disable-next-line react-hooks/exhaustive-deps\n }, [selectedAgent]);\n\n // Re-sort when enabledFiles changes (for toggle/reorder operations)\n useEffect(() => {\n if (files.length > 0 && enabledFiles.length >= 0) {\n const sortedFiles = sortFilesByEnabled(files, enabledFiles);\n\n // Only update if order actually changed to avoid infinite loop\n const orderChanged = sortedFiles.some(\n (file, index) => file.filename !== files[index]?.filename,\n );\n if (orderChanged) {\n setFiles(sortedFiles);\n }\n }\n // eslint-disable-next-line react-hooks/exhaustive-deps\n }, [enabledFiles]);\n\n const fetchEnabledFiles = async () => {\n try {\n const result = await workspaceApi.getSystemPromptFiles();\n const enabled = Array.isArray(result) ? result : [];\n setEnabledFiles(enabled);\n return enabled;\n } catch (error) {\n console.error(\"Failed to fetch enabled files\", error);\n return [];\n }\n };\n\n const sortFilesByEnabled = (\n fileList: MarkdownFile[],\n currentEnabledFiles: string[],\n ) => {\n const safeEnabled = Array.isArray(currentEnabledFiles)\n ? currentEnabledFiles\n : [];\n return [...fileList].sort((a, b) => {\n const aIndex = safeEnabled.indexOf(a.filename);\n const bIndex = safeEnabled.indexOf(b.filename);\n const aEnabled = aIndex !== -1;\n const bEnabled = bIndex !== -1;\n\n if (aEnabled && bEnabled) {\n return aIndex - bIndex;\n }\n if (aEnabled) return -1;\n if (bEnabled) return 1;\n return a.filename.localeCompare(b.filename);\n });\n };\n\n const fetchFiles = async (latestEnabledFiles?: string[]) => {\n try {\n // Validate with Array.isArray: onClick handlers may pass a MouseEvent as the first argument\n const enabled = Array.isArray(latestEnabledFiles)\n ? latestEnabledFiles\n : await fetchEnabledFiles();\n // Use agent-specific API\n const fileList = await agentsApi.listAgentFiles(selectedAgent);\n const sortedFiles = sortFilesByEnabled(\n fileList as unknown as MarkdownFile[],\n enabled,\n );\n setFiles(sortedFiles);\n // Set workspace path (handle both Unix '/' and Windows '\\' separators)\n if (fileList.length > 0) {\n setWorkspacePath(getParentDir(fileList[0].path));\n } else {\n setWorkspacePath(\"\");\n }\n } catch (error) {\n console.error(\"Failed to fetch files\", error);\n message.error(\"Failed to load file list\");\n }\n };\n\n const fetchDailyMemories = async () => {\n try {\n const memoryList = await api.listDailyMemory();\n setDailyMemories(memoryList);\n } catch (error) {\n console.error(\"Failed to fetch daily memories\", error);\n message.error(\"Failed to load memory list\");\n }\n };\n\n const handleFileClick = async (file: MarkdownFile) => {\n if (file.filename === \"MEMORY.md\") {\n if (expandedMemory && selectedFile?.filename === \"MEMORY.md\") {\n setExpandedMemory(false);\n return;\n } else {\n setExpandedMemory(true);\n fetchDailyMemories();\n }\n }\n\n setSelectedFile(file);\n setLoading(true);\n try {\n // Use agent-specific API\n const data = await agentsApi.readAgentFile(selectedAgent, file.filename);\n setFileContent(data.content);\n setOriginalContent(data.content);\n } catch (error) {\n console.error(\"Failed to load file\", error);\n message.error(\"Failed to load file\");\n } finally {\n setLoading(false);\n }\n };\n\n const handleDailyMemoryClick = async (daily: DailyMemoryFile) => {\n setSelectedFile({\n filename: `${daily.date}.md`,\n path: daily.path,\n size: daily.size,\n created_time: daily.created_time,\n modified_time: daily.modified_time,\n updated_at: daily.updated_at,\n });\n setLoading(true);\n try {\n const data = await api.loadDailyMemory(daily.date);\n setFileContent(data.content);\n setOriginalContent(data.content);\n } catch (error) {\n console.error(\"Failed to load daily memory\", error);\n message.error(\"Failed to load daily memory\");\n } finally {\n setLoading(false);\n }\n };\n\n const handleSave = async () => {\n if (!selectedFile) return;\n setLoading(true);\n try {\n if (selectedFile.filename.match(/^\\d{4}-\\d{2}-\\d{2}\\.md$/)) {\n const date = selectedFile.filename.replace(\".md\", \"\");\n await api.saveDailyMemory(date, fileContent);\n } else {\n await api.saveFile(selectedFile.filename, fileContent);\n }\n setOriginalContent(fileContent);\n message.success(\"Saved successfully\");\n if (selectedFile.filename.match(/^\\d{4}-\\d{2}-\\d{2}\\.md$/)) {\n fetchDailyMemories();\n } else {\n fetchFiles();\n }\n } catch (error) {\n console.error(\"Failed to save file\", error);\n message.error(\"Failed to save\");\n } finally {\n setLoading(false);\n }\n };\n\n const handleReset = () => {\n setFileContent(originalContent);\n };\n\n const handleToggleFileEnabled = async (filename: string) => {\n const isEnabling = !enabledFiles.includes(filename);\n\n // Show warning for MEMORY.md\n if (isEnabling && filename === \"MEMORY.md\") {\n message.warning({\n content: t(\"workspace.memoryFileWarning\"),\n duration: 5,\n });\n }\n\n const newEnabledFiles = enabledFiles.includes(filename)\n ? enabledFiles.filter((f) => f !== filename)\n : [...enabledFiles, filename];\n\n try {\n await workspaceApi.setSystemPromptFiles(newEnabledFiles);\n setEnabledFiles(newEnabledFiles);\n message.success(\n t(\"workspace.configUpdated\") || \"System prompt configuration updated\",\n );\n } catch (error) {\n console.error(\"Failed to update system prompt files\", error);\n message.error(\n t(\"workspace.configUpdateFailed\") ||\n \"Failed to update system prompt configuration\",\n );\n }\n };\n\n const handleReorderFiles = async (newOrder: string[]) => {\n try {\n await workspaceApi.setSystemPromptFiles(newOrder);\n setEnabledFiles(newOrder);\n } catch (error) {\n console.error(\"Failed to reorder files\", error);\n message.error(\"Failed to update file order\");\n }\n };\n\n const hasChanges = fileContent !== originalContent;\n\n return {\n files,\n selectedFile,\n dailyMemories,\n expandedMemory,\n fileContent,\n loading,\n workspacePath,\n hasChanges,\n enabledFiles,\n setFileContent,\n fetchFiles,\n fetchDailyMemories,\n handleFileClick,\n handleDailyMemoryClick,\n handleSave,\n handleReset,\n handleToggleFileEnabled,\n handleReorderFiles,\n };\n};\n" }, { "path": "console/src/pages/Agent/Workspace/components/utils.ts", "content": "export const formatFileSize = (bytes: number): string => {\n if (bytes === 0) return \"0 B\";\n if (bytes < 1024) return `${bytes} B`;\n if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;\n return `${(bytes / 1024 / 1024).toFixed(1)} MB`;\n};\n\nexport const formatTimeAgo = (timestamp: number): string => {\n const seconds = Math.floor((Date.now() - timestamp) / 1000);\n if (seconds < 60) return \"just now\";\n if (seconds < 3600) return `${Math.floor(seconds / 60)}m ago`;\n if (seconds < 86400) return `${Math.floor(seconds / 3600)}h ago`;\n return `${Math.floor(seconds / 86400)}d ago`;\n};\n\nexport const isDailyMemoryFile = (filename: string): boolean => {\n return /^\\d{4}-\\d{2}-\\d{2}\\.md$/.test(filename);\n};\n" }, { "path": "console/src/pages/Agent/Workspace/index.module.less", "content": ".agentsPage {\n padding: 24px;\n height: calc(100vh - 96px);\n display: flex;\n flex-direction: column;\n overflow: hidden;\n}\n\n.header {\n flex-shrink: 0;\n}\n\n.title {\n margin-bottom: 4px;\n}\n\n.description {\n margin: 0;\n color: #999;\n font-size: 14px;\n}\n\n.content {\n display: flex;\n gap: 16px;\n flex: 1;\n min-height: 0;\n overflow: auto;\n padding-bottom: 12px;\n}\n\n.fileListPanel {\n width: 400px;\n flex-shrink: 0;\n display: flex;\n flex-direction: column;\n min-height: 0;\n overflow: hidden;\n}\n\n.cardBody {\n padding: 16px;\n display: flex;\n flex-direction: column;\n height: 100%;\n overflow: auto;\n}\n\n.cardContainer {\n flex: 1;\n min-height: 0;\n}\n\n.workspaceInfo {\n display: flex;\n align-items: center;\n justify-content: space-between;\n height: 30px;\n}\n\n.headerRow {\n display: flex;\n justify-content: space-between;\n align-items: center;\n margin-bottom: 12px;\n flex-shrink: 0;\n}\n\n.actionButtons {\n display: flex;\n gap: 8px;\n align-items: center;\n margin-bottom: 12px;\n}\n\n.sectionTitle {\n margin: 0;\n font-size: 14px;\n font-weight: 600;\n}\n\n.infoText {\n margin: 0;\n margin-bottom: 12px;\n font-size: 12px;\n color: #999;\n flex-shrink: 0;\n}\n\n.workspacePath {\n margin: 0;\n margin-bottom: 12px;\n font-size: 12px;\n color: #666;\n font-family: monospace;\n flex-shrink: 0;\n overflow: hidden;\n text-overflow: ellipsis;\n white-space: nowrap;\n}\n\n.divider {\n height: 1px;\n background-color: #e8e8e8;\n margin-bottom: 16px;\n flex-shrink: 0;\n}\n\n.scrollContainer {\n flex: 1;\n min-height: 0;\n overflow: auto;\n\n &::-webkit-scrollbar {\n display: none;\n }\n\n scrollbar-width: none;\n -ms-overflow-style: none;\n -webkit-overflow-scrolling: touch;\n}\n\n.fileEditor {\n flex: 1;\n display: flex;\n flex-direction: column;\n min-height: 0;\n height: 100%;\n width: 100%;\n}\n\n.editorCard {\n height: 100% !important;\n\n :global {\n .copaw-card-body {\n height: 100%;\n\n .copaw-spark-card-wrapper {\n height: 100%;\n }\n\n .copaw-spark-content {\n height: 100%;\n }\n\n .agentscope-runtime-webui-spark-card-wrapper {\n height: 100%;\n\n .agentscope-runtime-webui-spark-content {\n height: 100%;\n }\n }\n\n .spark-card-wrapper {\n height: 100%;\n\n .spark-content {\n height: 100%;\n overflow: hidden;\n }\n }\n }\n }\n}\n\n.editorHeader {\n padding: 16px;\n border-bottom: 1px solid #f0f0f0;\n display: flex;\n justify-content: space-between;\n align-items: center;\n flex-shrink: 0;\n}\n\n.fileName {\n font-size: 16px;\n font-weight: 600;\n margin-bottom: 4px;\n}\n\n.filePath {\n font-size: 12px;\n color: #999;\n font-family: monospace;\n}\n\n.buttonGroup {\n display: flex;\n gap: 8px;\n align-items: center;\n}\n\n.editorContent {\n padding: 16px;\n height: calc(100% - 96px);\n\n textarea {\n font-family: monospace;\n font-size: 13px;\n resize: vertical;\n height: 100%;\n }\n}\n\n.contentLabel {\n margin-bottom: 8px;\n font-size: 12px;\n font-weight: 600;\n flex-shrink: 0;\n display: flex;\n justify-content: space-between;\n align-items: center;\n height: 20px;\n}\n\n.markdownViewer {\n flex: 1;\n display: flex;\n flex-direction: column;\n height: 100%;\n overflow: auto;\n border: 1px solid #e8e8e8;\n padding: 16px;\n border-radius: 8px;\n}\n\n.textarea {\n font-family: monospace;\n font-size: 13px;\n resize: vertical;\n height: min(100%, clamp(280px, 50vh, 640px));\n min-height: min(240px, 100%);\n max-height: 100%;\n}\n\n.markdownToggle {\n display: flex;\n align-items: center;\n gap: 8px;\n}\n\n.toggleLabel {\n font-size: 12px;\n color: #666;\n white-space: nowrap;\n}\n\n.emptyState {\n flex: 1;\n display: flex;\n align-items: center;\n justify-content: center;\n color: #999;\n}\n\n.buttonGroup {\n display: flex;\n align-items: center;\n}\n\n.copyButton {\n border-radius: 4px;\n}\n\n.fileItem {\n padding: 12px;\n border: 1px solid #e8e8e8;\n border-radius: 8px;\n margin-bottom: 8px;\n cursor: pointer;\n background-color: #fff;\n transition: all 0.2s;\n\n &:hover:not(.selected) {\n border-color: #d9d9d9;\n background-color: #fafafa;\n }\n\n &.selected {\n border: 2px solid #615ced;\n background-color: #f6f5ff;\n }\n}\n\n.fileItemHeader {\n display: flex;\n align-items: center;\n justify-content: space-between;\n}\n\n.fileInfo {\n flex: 1;\n min-width: 0;\n}\n\n.fileItemActions {\n display: flex;\n align-items: center;\n gap: 8px;\n flex-shrink: 0;\n margin-left: 12px;\n}\n\n.dragHandle {\n display: flex;\n align-items: center;\n justify-content: center;\n width: 20px;\n flex-shrink: 0;\n margin-right: 8px;\n color: #bbb;\n cursor: grab;\n font-size: 14px;\n transition: color 0.2s;\n\n &:active {\n cursor: grabbing;\n }\n\n &:hover {\n color: #615ced;\n }\n}\n\n.dragging {\n box-shadow: 0 4px 12px rgba(0, 0, 0, 0.12);\n border-color: #615ced !important;\n background-color: #f6f5ff !important;\n}\n\n.enabledBadge {\n color: #52c41a;\n font-size: 8px;\n margin-right: 6px;\n vertical-align: middle;\n}\n\n.fileActions {\n display: flex;\n align-items: center;\n gap: 8px;\n}\n\n.fileItemName {\n font-size: 14px;\n font-weight: 600;\n margin-bottom: 4px;\n}\n\n.fileItemMeta {\n font-size: 12px;\n color: #999;\n}\n\n.expandIcon {\n font-size: 12px;\n color: #999;\n margin-left: 8px;\n}\n\n.dailyMemoryList {\n margin-left: 16px;\n margin-top: -4px;\n margin-bottom: 8px;\n}\n\n.dailyMemoryItem {\n padding: 10px;\n border: 1px solid #e8e8e8;\n border-radius: 6px;\n margin-bottom: 6px;\n cursor: pointer;\n background-color: #fff;\n transition: all 0.2s;\n\n &:hover:not(.selected) {\n border-color: #d9d9d9;\n background-color: #fafafa;\n }\n\n &.selected {\n border: 2px solid #615ced;\n background-color: #f6f5ff;\n }\n}\n\n.dailyMemoryName {\n font-size: 13px;\n font-weight: 500;\n margin-bottom: 2px;\n}\n\n.dailyMemoryMeta {\n font-size: 11px;\n color: #999;\n}\n\n.attribution {\n margin: 0;\n padding: 4px 0 0;\n font-size: 11px;\n color: #bbb;\n text-align: right;\n flex-shrink: 0;\n}\n\n/* ─── Dark mode ─────────────────────────────────────────────────────────────── */\n:global(.dark-mode) {\n .description {\n color: rgba(255, 255, 255, 0.35);\n }\n\n .workspacePath {\n color: rgba(255, 255, 255, 0.3);\n }\n\n .infoText {\n color: rgba(255, 255, 255, 0.3);\n }\n\n .divider {\n background-color: rgba(255, 255, 255, 0.08);\n }\n\n /* File list items */\n .fileItem {\n background-color: #2a2a2a;\n border-color: rgba(255, 255, 255, 0.1);\n\n &:hover:not(.selected) {\n border-color: rgba(255, 255, 255, 0.2);\n background-color: #333;\n }\n\n &.selected {\n border-color: #615ced;\n background-color: rgba(97, 92, 237, 0.15);\n }\n }\n\n .fileItemName {\n color: rgba(255, 255, 255, 0.85);\n }\n\n .fileItemMeta {\n color: rgba(255, 255, 255, 0.35);\n }\n\n .expandIcon {\n color: rgba(255, 255, 255, 0.3);\n }\n\n .dragHandle {\n color: rgba(255, 255, 255, 0.2);\n\n &:hover {\n color: #8b87f0;\n }\n }\n\n .dragging {\n box-shadow: 0 4px 12px rgba(0, 0, 0, 0.4);\n border-color: #615ced !important;\n background-color: rgba(97, 92, 237, 0.15) !important;\n }\n\n /* Daily memory items */\n .dailyMemoryItem {\n background-color: #2a2a2a;\n border-color: rgba(255, 255, 255, 0.1);\n\n &:hover:not(.selected) {\n border-color: rgba(255, 255, 255, 0.2);\n background-color: #333;\n }\n\n &.selected {\n border-color: #615ced;\n background-color: rgba(97, 92, 237, 0.15);\n }\n }\n\n .dailyMemoryName {\n color: rgba(255, 255, 255, 0.85);\n }\n\n .dailyMemoryMeta {\n color: rgba(255, 255, 255, 0.35);\n }\n\n /* Editor area */\n .editorHeader {\n border-bottom-color: rgba(255, 255, 255, 0.08);\n }\n\n .fileName {\n color: rgba(255, 255, 255, 0.85);\n }\n\n .filePath {\n color: rgba(255, 255, 255, 0.35);\n }\n\n .markdownViewer {\n border-color: rgba(255, 255, 255, 0.1);\n color: rgba(255, 255, 255, 0.85);\n background: #1f1f1f;\n }\n\n .toggleLabel {\n color: rgba(255, 255, 255, 0.45);\n }\n\n .emptyState {\n color: rgba(255, 255, 255, 0.3);\n }\n\n .sectionTitle {\n color: rgba(255, 255, 255, 0.85);\n }\n\n .attribution {\n color: rgba(255, 255, 255, 0.2);\n }\n\n /* Textarea inside editor */\n .textarea,\n .editorContent textarea {\n background: #2a2a2a !important;\n color: rgba(255, 255, 255, 0.85) !important;\n border-color: rgba(255, 255, 255, 0.1) !important;\n }\n}\n" }, { "path": "console/src/pages/Agent/Workspace/index.tsx", "content": "import { useAgentsData, FileListPanel, FileEditor } from \"./components\";\nimport styles from \"./index.module.less\";\nimport { UploadOutlined, DownloadOutlined } from \"@ant-design/icons\";\nimport { Button, Tooltip, message } from \"@agentscope-ai/design\";\nimport { workspaceApi } from \"../../../api/modules/workspace\";\nimport { useRef } from \"react\";\nimport { useTranslation } from \"react-i18next\";\n\nexport default function WorkspacePage() {\n const { t } = useTranslation();\n const {\n files,\n selectedFile,\n dailyMemories,\n expandedMemory,\n fileContent,\n loading,\n workspacePath,\n hasChanges,\n enabledFiles,\n setFileContent,\n fetchFiles,\n handleFileClick,\n handleDailyMemoryClick,\n handleSave,\n handleReset,\n handleToggleFileEnabled,\n handleReorderFiles,\n } = useAgentsData();\n\n const fileInputRef = useRef(null);\n\n const handleDownload = async () => {\n try {\n const { blob, filename } = await workspaceApi.downloadWorkspace();\n const url = window.URL.createObjectURL(blob);\n const a = document.createElement(\"a\");\n a.href = url;\n a.download = filename;\n document.body.appendChild(a);\n a.click();\n window.URL.revokeObjectURL(url);\n document.body.removeChild(a);\n message.success(t(\"workspace.downloadSuccess\"));\n } catch (error) {\n console.error(\"Download failed:\", error);\n message.error(\n t(\"workspace.downloadFailed\") + \": \" + (error as Error).message,\n );\n }\n };\n\n const handleFileUpload = async (\n event: React.ChangeEvent,\n ) => {\n const file = event.target.files?.[0];\n if (!file) return;\n\n // Check if file is zip format\n if (!file.name.toLowerCase().endsWith(\".zip\")) {\n message.error(t(\"workspace.zipOnly\"));\n if (fileInputRef.current) {\n fileInputRef.current.value = \"\";\n }\n return;\n }\n\n const maxSize = 100 * 1024 * 1024;\n if (file.size > maxSize) {\n message.error(\n t(\"workspace.fileSizeExceeded\", {\n size: (file.size / (1024 * 1024)).toFixed(2),\n }),\n );\n if (fileInputRef.current) {\n fileInputRef.current.value = \"\";\n }\n return;\n }\n\n try {\n const result = await workspaceApi.uploadFile(file);\n if (result.success) {\n message.success(t(\"workspace.uploadSuccess\"));\n } else {\n message.error(t(\"workspace.uploadFailed\") + \": \" + result.message);\n }\n } catch (error) {\n console.error(\"Upload failed:\", error);\n message.error(\n t(\"workspace.uploadFailed\") + \": \" + (error as Error).message,\n );\n } finally {\n // Clear input value to allow re-uploading the same file\n if (fileInputRef.current) {\n fileInputRef.current.value = \"\";\n }\n }\n };\n\n const handleUploadClick = () => {\n fileInputRef.current?.click();\n };\n\n return (\n
    \n
    \n

    {t(\"workspace.title\")}

    \n
    \n

    \n {t(\"workspace.workspacePath\")}{\" \"}\n {workspacePath === null\n ? t(\"common.loading\")\n : workspacePath || t(\"workspace.noFiles\")}\n

    \n
    \n \n }\n >\n {t(\"common.upload\")}\n \n \n }\n >\n {t(\"common.download\")}\n \n
    \n
    \n
    \n\n
    \n \n\n \n
    \n\n

    {t(\"workspace.attribution\")}

    \n\n {/* Hidden file input - only accepts .zip files up to 100MB */}\n \n
    \n );\n}\n" }, { "path": "console/src/pages/Chat/ModelSelector/index.module.less", "content": "/* ---- Trigger button ---- */\n.trigger {\n display: inline-flex;\n align-items: center;\n gap: 5px;\n padding: 4px 10px;\n border-radius: 8px;\n cursor: pointer;\n font-size: 16px;\n font-weight: 600;\n color: #333;\n // border: 1px solid rgba(0, 0, 0, 0.08);\n // background: #fff;\n transition: all 0.15s ease;\n user-select: none;\n max-width: 260px;\n\n &:hover,\n &.triggerActive {\n border-color: #615ced;\n color: #615ced;\n box-shadow: 0 2px 8px rgba(97, 92, 237, 0.12);\n }\n}\n\n.triggerName {\n overflow: hidden;\n text-overflow: ellipsis;\n white-space: nowrap;\n max-width: 180px;\n}\n\n.triggerArrow {\n flex-shrink: 0;\n font-size: 16px;\n color: #999;\n transition:\n transform 0.2s,\n color 0.15s;\n\n &.triggerArrowOpen {\n transform: rotate(180deg);\n color: #615ced;\n }\n}\n\n/* ---- Level-1 panel ---- */\n.panel {\n min-width: 180px;\n border-radius: 12px;\n background: #fff;\n border: 1px solid rgba(0, 0, 0, 0.06);\n box-shadow: 0 8px 24px rgba(0, 0, 0, 0.1);\n padding: 4px 0;\n overflow: visible;\n}\n\n.providerItem {\n position: relative;\n display: flex;\n align-items: center;\n justify-content: space-between;\n padding: 7px 12px;\n cursor: pointer;\n font-size: 16px;\n color: #333;\n transition: background 0.12s;\n gap: 8px;\n\n &:hover {\n background: rgba(97, 92, 237, 0.06);\n color: #615ced;\n }\n\n &:hover :global(.modelSubmenu) {\n display: block;\n }\n\n &:first-child {\n border-radius: 8px 8px 0 0;\n }\n\n &:last-child {\n border-radius: 0 0 8px 8px;\n }\n\n &.providerItemActive {\n font-weight: 600;\n }\n}\n\n.providerName {\n flex: 1;\n overflow: hidden;\n text-overflow: ellipsis;\n white-space: nowrap;\n}\n\n.providerArrow {\n flex-shrink: 0;\n font-size: 16px;\n color: #bbb;\n}\n\n/* ---- Level-2 submenu ---- */\n.submenu {\n display: none;\n position: absolute;\n top: -4px;\n left: 100%;\n margin-left: 2px;\n min-width: 200px;\n max-height: 360px;\n overflow-y: auto;\n border-radius: 12px;\n background: #fff;\n border: 1px solid rgba(0, 0, 0, 0.06);\n box-shadow: 0 8px 24px rgba(0, 0, 0, 0.1);\n padding: 4px 0;\n z-index: 1100;\n}\n\n.modelItem {\n display: flex;\n align-items: center;\n justify-content: space-between;\n padding: 7px 12px;\n cursor: pointer;\n font-size: 16px;\n color: #333;\n transition: background 0.12s;\n gap: 8px;\n white-space: nowrap;\n\n &:hover {\n background: rgba(97, 92, 237, 0.06);\n color: #615ced;\n }\n\n &:first-child {\n border-radius: 8px 8px 0 0;\n }\n\n &:last-child {\n border-radius: 0 0 8px 8px;\n }\n\n &.modelItemActive {\n background: rgba(97, 92, 237, 0.08);\n color: #615ced;\n font-weight: 500;\n }\n}\n\n.modelName {\n overflow: hidden;\n text-overflow: ellipsis;\n flex: 1;\n}\n\n.checkIcon {\n flex-shrink: 0;\n font-size: 16px;\n color: #615ced;\n}\n\n.emptyTip {\n padding: 10px 14px;\n font-size: 16px;\n color: #bbb;\n}\n\n.spinWrapper {\n padding: 14px 16px;\n text-align: center;\n}\n\n/* ─── Dark mode overrides ─────────────────────────────────────────────────── */\n:global(.dark-mode) {\n .trigger {\n color: rgba(255, 255, 255, 0.85);\n\n &:hover,\n &.triggerActive {\n color: #8b87f0;\n box-shadow: 0 2px 8px rgba(97, 92, 237, 0.2);\n }\n }\n\n .triggerArrow {\n color: rgba(255, 255, 255, 0.3);\n\n &.triggerArrowOpen {\n color: #8b87f0;\n }\n }\n\n .panel {\n background: #1f1f1f;\n border-color: rgba(255, 255, 255, 0.08);\n box-shadow: 0 8px 24px rgba(0, 0, 0, 0.4);\n }\n\n .providerItem {\n color: rgba(255, 255, 255, 0.85);\n\n &:hover {\n background: rgba(97, 92, 237, 0.15);\n color: #8b87f0;\n }\n }\n\n .providerArrow {\n color: rgba(255, 255, 255, 0.2);\n }\n\n .submenu {\n background: #1f1f1f;\n border-color: rgba(255, 255, 255, 0.08);\n box-shadow: 0 8px 24px rgba(0, 0, 0, 0.4);\n }\n\n .modelItem {\n color: rgba(255, 255, 255, 0.85);\n\n &:hover {\n background: rgba(97, 92, 237, 0.15);\n color: #8b87f0;\n }\n\n &.modelItemActive {\n background: rgba(97, 92, 237, 0.18);\n color: #8b87f0;\n }\n }\n\n .checkIcon {\n color: #8b87f0;\n }\n\n .emptyTip {\n color: rgba(255, 255, 255, 0.25);\n }\n}\n" }, { "path": "console/src/pages/Chat/ModelSelector/index.tsx", "content": "import { useState, useEffect, useCallback, useRef } from \"react\";\nimport { Dropdown, message, Spin } from \"antd\";\nimport {\n DownOutlined,\n CheckOutlined,\n LoadingOutlined,\n RightOutlined,\n} from \"@ant-design/icons\";\nimport { useLocation } from \"react-router-dom\";\nimport { useTranslation } from \"react-i18next\";\nimport { providerApi } from \"../../../api/modules/provider\";\nimport type { ProviderInfo, ActiveModelsInfo } from \"../../../api/types\";\nimport styles from \"./index.module.less\";\n\ninterface EligibleProvider {\n id: string;\n name: string;\n models: Array<{ id: string; name: string }>;\n}\n\nexport default function ModelSelector() {\n const { t } = useTranslation();\n const [providers, setProviders] = useState([]);\n const [activeModels, setActiveModels] = useState(\n null,\n );\n const [loading, setLoading] = useState(false);\n const [saving, setSaving] = useState(false);\n const [open, setOpen] = useState(false);\n const savingRef = useRef(false);\n const location = useLocation();\n\n const fetchData = useCallback(async () => {\n setLoading(true);\n try {\n const [provData, activeData] = await Promise.all([\n providerApi.listProviders(),\n providerApi.getActiveModels(),\n ]);\n if (Array.isArray(provData)) setProviders(provData);\n if (activeData) setActiveModels(activeData);\n } catch (err) {\n console.error(\"ModelSelector: failed to load data\", err);\n } finally {\n setLoading(false);\n }\n }, []);\n\n useEffect(() => {\n fetchData();\n }, [fetchData]);\n\n // Re-sync active model whenever the route switches back to /chat\n const prevPathRef = useRef(location.pathname);\n useEffect(() => {\n const prev = prevPathRef.current;\n const curr = location.pathname;\n prevPathRef.current = curr;\n const comingToChat = curr.startsWith(\"/chat\") && !prev.startsWith(\"/chat\");\n if (comingToChat) {\n providerApi\n .getActiveModels()\n .then((activeData) => {\n if (activeData) setActiveModels(activeData);\n })\n .catch(() => {});\n }\n }, [location.pathname]);\n\n // Eligible providers: configured + has models\n const eligibleProviders: EligibleProvider[] = providers\n .filter((p) => {\n const hasModels =\n (p.models?.length ?? 0) + (p.extra_models?.length ?? 0) > 0;\n if (!hasModels) return false;\n if (p.is_local) return true;\n if (p.require_api_key === false) return !!p.base_url;\n if (p.is_custom) return !!p.base_url;\n if (p.require_api_key ?? true) return !!p.api_key;\n return true;\n })\n .map((p) => ({\n id: p.id,\n name: p.name,\n models: [...(p.models ?? []), ...(p.extra_models ?? [])],\n }));\n\n const activeProviderId = activeModels?.active_llm?.provider_id;\n const activeModelId = activeModels?.active_llm?.model;\n\n // Display label for trigger button\n const activeModelName = (() => {\n if (!activeProviderId || !activeModelId)\n return t(\"modelSelector.selectModel\");\n for (const p of eligibleProviders) {\n if (p.id === activeProviderId) {\n const m = p.models.find((m) => m.id === activeModelId);\n if (m) return m.name || m.id;\n }\n }\n return activeModelId;\n })();\n\n const handleOpenChange = useCallback(async (next: boolean) => {\n setOpen(next);\n if (next) {\n // Re-fetch active model every time the dropdown opens\n try {\n const activeData = await providerApi.getActiveModels();\n if (activeData) setActiveModels(activeData);\n } catch {\n // ignore\n }\n }\n }, []);\n\n const handleSelect = async (providerId: string, modelId: string) => {\n if (savingRef.current) return;\n if (providerId === activeProviderId && modelId === activeModelId) {\n setOpen(false);\n return;\n }\n savingRef.current = true;\n setSaving(true);\n setOpen(false);\n try {\n await providerApi.setActiveLlm({\n provider_id: providerId,\n model: modelId,\n });\n setActiveModels({\n active_llm: { provider_id: providerId, model: modelId },\n });\n } catch (err) {\n const msg =\n err instanceof Error ? err.message : t(\"modelSelector.switchFailed\");\n message.error(msg);\n } finally {\n setSaving(false);\n savingRef.current = false;\n }\n };\n\n const dropdownContent = (\n
    \n {loading ? (\n
    \n \n
    \n ) : eligibleProviders.length === 0 ? (\n
    \n {t(\"modelSelector.noConfiguredModels\")}\n
    \n ) : (\n eligibleProviders.map((provider) => {\n const isProviderActive = provider.id === activeProviderId;\n return (\n \n {provider.name}\n \n\n {/* Level-2 submenu — shown on parent hover via CSS */}\n
    \n {provider.models.map((model) => {\n const isActive =\n isProviderActive && model.id === activeModelId;\n return (\n {\n e.stopPropagation();\n handleSelect(provider.id, model.id);\n }}\n >\n \n {model.name || model.id}\n \n {isActive && (\n \n )}\n
    \n );\n })}\n
    \n
    \n );\n })\n )}\n \n );\n\n return (\n dropdownContent}\n trigger={[\"click\"]}\n placement=\"bottomLeft\"\n >\n \n {saving && (\n \n )}\n {activeModelName}\n \n \n \n );\n}\n" }, { "path": "console/src/pages/Chat/OptionsPanel/FormItem.tsx", "content": "import { Form } from \"antd\";\nimport { createStyles } from \"antd-style\";\n\ninterface FormItemProps {\n name: string | string[];\n label: string;\n isList?: boolean;\n children: any;\n normalize?: (value: any) => any;\n}\n\nconst useStyles = createStyles(({ token }) => ({\n label: {\n marginBottom: 6,\n fontSize: 12,\n color: token.colorTextSecondary,\n },\n}));\n\nexport default function FormItem(props: FormItemProps) {\n const { styles } = useStyles();\n\n const node = props.isList ? (\n {props.children}\n ) : (\n \n {props.children}\n \n );\n\n return (\n
    \n {props.label &&
    {props.label}
    }\n {node}\n
    \n );\n}\n" }, { "path": "console/src/pages/Chat/OptionsPanel/OptionsEditor.tsx", "content": "import React from \"react\";\nimport { Form, Input, ColorPicker, Flex, Divider, InputNumber } from \"antd\";\nimport { createStyles } from \"antd-style\";\nimport { Button, IconButton, Switch } from \"@agentscope-ai/design\";\nimport { SparkDeleteLine, SparkPlusLine } from \"@agentscope-ai/icons\";\nimport FormItem from \"./FormItem\";\nimport defaultConfig from \"./defaultConfig\";\n\nconst useStyles = createStyles(({ token }) => ({\n container: {\n height: \"100%\",\n display: \"flex\",\n flexDirection: \"column\",\n },\n\n form: {\n height: 0,\n flex: 1,\n padding: \"8px 16px 16px 16px\",\n overflow: \"auto\",\n },\n actions: {\n padding: 16,\n display: \"flex\",\n borderTop: `1px solid ${token.colorBorderSecondary}`,\n justifyContent: \"flex-end\",\n gap: 16,\n },\n}));\n\ninterface OptionsEditorProps {\n value?: Record;\n onChange?: (value: Record) => void;\n}\n\nconst OptionsEditor: React.FC = ({ value, onChange }) => {\n const { styles } = useStyles();\n const [form] = Form.useForm();\n\n const handleSave = () => {\n form\n .validateFields()\n .then((values) => {\n onChange?.(values);\n })\n .catch((error) => {\n console.error(\"Validation failed:\", error);\n });\n };\n\n const handleReset = () => {\n form.setFieldsValue(defaultConfig);\n };\n\n return (\n
    \n \n Theme\n\n value.toHexString()}\n >\n \n \n\n value.toHexString()}\n >\n \n \n\n value.toHexString()}\n >\n \n \n\n \n \n \n\n \n \n \n\n \n \n \n\n Sender\n\n \n \n \n\n \n \n \n\n Welcome\n\n \n \n \n\n \n \n \n\n \n \n \n\n \n {(\n fields: { key: string; name: string }[],\n {\n add,\n remove,\n }: { add: (item: any) => void; remove: (name: string) => void },\n ) => {\n return (\n
    \n {fields.map((field) => {\n return (\n \n \n \n \n }\n onClick={() => add({})}\n >\n }\n onClick={() => remove(field.name)}\n >\n \n );\n })}\n
    \n );\n }}\n     \n\n API\n\n \n \n \n\n \n \n \n \n\n
    \n \n \n
    \n
    \n );\n};\n\nexport default OptionsEditor;\n" }, { "path": "console/src/pages/Chat/OptionsPanel/defaultConfig.ts", "content": "import type { TFunction } from \"i18next\";\n\nconst defaultConfig = {\n theme: {\n colorPrimary: \"#615CED\",\n darkMode: false,\n prefix: \"copaw\",\n leftHeader: {\n logo: \"\",\n title: \"Work with CoPaw\",\n },\n },\n sender: {\n attachments: true,\n maxLength: 10000,\n disclaimer: \"Works for you, grows with you\",\n },\n welcome: {\n greeting: \"Hello, how can I help you today?\",\n description:\n \"I am a helpful assistant that can help you with your questions.\",\n avatar: `${import.meta.env.BASE_URL}copaw-symbol.svg`,\n prompts: [\n {\n value: \"Let's start a new journey!\",\n },\n {\n value: \"Can you tell me what skills you have?\",\n },\n ],\n },\n api: {\n baseURL: \"\",\n token: \"\",\n },\n} as const;\n\nexport function getDefaultConfig(t: TFunction) {\n return {\n ...defaultConfig,\n sender: {\n ...defaultConfig.sender,\n disclaimer: t(\"chat.disclaimer\"),\n },\n welcome: {\n ...defaultConfig.welcome,\n greeting: t(\"chat.greeting\"),\n description: t(\"chat.description\"),\n prompts: [{ value: t(\"chat.prompt1\") }, { value: t(\"chat.prompt2\") }],\n },\n };\n}\n\nexport default defaultConfig;\n\nexport type DefaultConfig = typeof defaultConfig;\n" }, { "path": "console/src/pages/Chat/OptionsPanel/index.tsx", "content": "import { SparkSettingLine } from \"@agentscope-ai/icons\";\nimport { IconButton, Drawer } from \"@agentscope-ai/design\";\nimport { useState } from \"react\";\nimport OptionsEditor from \"./OptionsEditor\";\n\ninterface OptionsPanelProps {\n value?: Record;\n onChange?: (value: Record) => void;\n}\n\nexport default function OptionsPanel(props: OptionsPanelProps) {\n const [open, setOpen] = useState(false);\n\n return (\n <>\n setOpen(true)}\n icon={}\n bordered={false}\n />\n setOpen(false)}\n styles={{ body: { padding: 0 }, header: { padding: 8 } }}\n >\n {\n setOpen(false);\n props.onChange?.(v);\n }}\n />\n \n \n );\n}\n" }, { "path": "console/src/pages/Chat/index.module.less", "content": "/* Disabled input overlay */\n.chatDisabledOverlay {\n position: relative;\n height: 100%;\n width: 100%;\n}\n\n.chatDisabledOverlay :global([class*=\"chat-anywhere-input\"]),\n.chatDisabledOverlay :global([class*=\"chat-input\"]),\n.chatDisabledOverlay :global(textarea),\n.chatDisabledOverlay :global(input[type=\"text\"]) {\n pointer-events: none !important;\n opacity: 0.5 !important;\n background-color: #f5f5f5 !important;\n cursor: not-allowed !important;\n}\n\n.chatDisabledOverlay :global(button[class*=\"send\"]),\n.chatDisabledOverlay :global(button[class*=\"submit\"]) {\n pointer-events: none !important;\n opacity: 0.3 !important;\n cursor: not-allowed !important;\n}\n" }, { "path": "console/src/pages/Chat/index.tsx", "content": "import {\n AgentScopeRuntimeWebUI,\n IAgentScopeRuntimeWebUIOptions,\n type IAgentScopeRuntimeWebUIMessage,\n type IAgentScopeRuntimeWebUIRef,\n Stream,\n} from \"@agentscope-ai/chat\";\nimport { useCallback, useEffect, useMemo, useRef, useState } from \"react\";\nimport { Button, Modal, Result, message } from \"antd\";\nimport { ExclamationCircleOutlined, SettingOutlined } from \"@ant-design/icons\";\nimport { SparkCopyLine } from \"@agentscope-ai/icons\";\nimport { useTranslation } from \"react-i18next\";\nimport { useLocation, useNavigate } from \"react-router-dom\";\nimport sessionApi from \"./sessionApi\";\nimport defaultConfig, { getDefaultConfig } from \"./OptionsPanel/defaultConfig\";\nimport { chatApi } from \"../../api/modules/chat\";\nimport { getApiToken, getApiUrl } from \"../../api/config\";\nimport { providerApi } from \"../../api/modules/provider\";\nimport api from \"../../api\";\nimport ModelSelector from \"./ModelSelector\";\nimport { useTheme } from \"../../contexts/ThemeContext\";\nimport { useAgentStore } from \"../../stores/agentStore\";\nimport AgentScopeRuntimeResponseBuilder from \"@agentscope-ai/chat/lib/AgentScopeRuntimeWebUI/core/AgentScopeRuntime/Response/Builder.js\";\nimport { AgentScopeRuntimeRunStatus } from \"@agentscope-ai/chat/lib/AgentScopeRuntimeWebUI/core/AgentScopeRuntime/types.js\";\nimport { useChatAnywhereInput } from \"@agentscope-ai/chat/lib/AgentScopeRuntimeWebUI/core/Context/ChatAnywhereInputContext.js\";\nimport \"./index.module.less\";\nimport { Tooltip } from \"antd\";\nimport { IconButton } from \"@agentscope-ai/design\";\nimport { SparkAttachmentLine } from \"@agentscope-ai/icons\";\n\ntype CopyableContent = {\n type?: string;\n text?: string;\n refusal?: string;\n};\n\ntype CopyableMessage = {\n role?: string;\n content?: string | CopyableContent[];\n};\n\ntype CopyableResponse = {\n output?: CopyableMessage[];\n};\n\ntype RuntimeUiMessage = IAgentScopeRuntimeWebUIMessage & {\n msgStatus?: string;\n role?: string;\n cards?: Array<{\n code: string;\n data: unknown;\n }>;\n history?: boolean;\n};\n\ntype StreamResponseData = {\n status?: string;\n output?: Array<{\n content?: unknown[];\n }>;\n};\n\ntype RuntimeLoadingBridgeApi = {\n getLoading?: () => boolean | string;\n setLoading?: (loading: boolean | string) => void;\n};\n\ninterface CustomWindow extends Window {\n currentSessionId?: string;\n currentUserId?: string;\n currentChannel?: string;\n}\n\ndeclare const window: CustomWindow;\n\nfunction extractCopyableText(response: CopyableResponse): string {\n const collectText = (assistantOnly: boolean) => {\n const chunks = (response.output || []).flatMap((item: CopyableMessage) => {\n if (assistantOnly && item.role !== \"assistant\") return [];\n\n if (typeof item.content === \"string\") {\n return [item.content];\n }\n\n if (!Array.isArray(item.content)) {\n return [];\n }\n\n return item.content.flatMap((content: CopyableContent) => {\n if (content.type === \"text\" && typeof content.text === \"string\") {\n return [content.text];\n }\n\n if (content.type === \"refusal\" && typeof content.refusal === \"string\") {\n return [content.refusal];\n }\n\n return [];\n });\n });\n\n return chunks.filter(Boolean).join(\"\\n\\n\").trim();\n };\n\n return collectText(true) || JSON.stringify(response);\n}\n\nasync function copyText(text: string) {\n if (navigator.clipboard && window.isSecureContext) {\n await navigator.clipboard.writeText(text);\n return;\n }\n\n const textarea = document.createElement(\"textarea\");\n textarea.value = text;\n textarea.setAttribute(\"readonly\", \"\");\n textarea.style.position = \"absolute\";\n textarea.style.left = \"-9999px\";\n document.body.appendChild(textarea);\n\n let copied = false;\n try {\n textarea.focus();\n textarea.select();\n copied = document.execCommand(\"copy\");\n } finally {\n document.body.removeChild(textarea);\n }\n\n if (!copied) {\n throw new Error(\"Failed to copy text\");\n }\n}\n\nfunction buildModelError(): Response {\n return new Response(\n JSON.stringify({\n error: \"Model not configured\",\n message: \"Please configure a model first\",\n }),\n { status: 400, headers: { \"Content-Type\": \"application/json\" } },\n );\n}\n\nfunction cloneRuntimeMessages(\n messages: RuntimeUiMessage[],\n): RuntimeUiMessage[] {\n return JSON.parse(JSON.stringify(messages)) as RuntimeUiMessage[];\n}\n\nfunction cloneValue(value: T): T {\n return JSON.parse(JSON.stringify(value)) as T;\n}\n\nfunction isFinalResponseStatus(status?: string): boolean {\n return (\n status === AgentScopeRuntimeRunStatus.Completed ||\n status === AgentScopeRuntimeRunStatus.Failed ||\n status === AgentScopeRuntimeRunStatus.Canceled\n );\n}\n\nfunction hasRenderableOutput(response: StreamResponseData): boolean {\n if (response.status === AgentScopeRuntimeRunStatus.Failed) {\n return true;\n }\n\n return (\n response.output?.some((message) => (message.content?.length ?? 0) > 0) ??\n false\n );\n}\n\nfunction getResponseCardData(\n message?: RuntimeUiMessage,\n): StreamResponseData | null {\n const responseCard = message?.cards?.find(\n (card) => card.code === \"AgentScopeRuntimeResponseCard\",\n );\n\n if (!responseCard?.data) {\n return null;\n }\n\n return cloneValue(responseCard.data as StreamResponseData);\n}\n\nfunction getStreamingAssistantMessageId(\n messages: RuntimeUiMessage[],\n): string | null {\n return (\n [...messages]\n .reverse()\n .find(\n (message) =>\n message.role === \"assistant\" &&\n (message.msgStatus === \"generating\" ||\n (message.cards?.length ?? 0) === 0),\n )?.id ||\n [...messages].reverse().find((message) => message.role === \"assistant\")\n ?.id ||\n null\n );\n}\n\nfunction RuntimeLoadingBridge({\n bridgeRef,\n}: {\n bridgeRef: { current: RuntimeLoadingBridgeApi | null };\n}) {\n const { setLoading, getLoading } = useChatAnywhereInput(\n (value) =>\n ({\n setLoading: value.setLoading,\n getLoading: value.getLoading,\n }) as RuntimeLoadingBridgeApi,\n );\n\n useEffect(() => {\n if (!setLoading || !getLoading) {\n bridgeRef.current = null;\n return;\n }\n\n bridgeRef.current = {\n setLoading,\n getLoading,\n };\n\n return () => {\n if (bridgeRef.current?.setLoading === setLoading) {\n bridgeRef.current = null;\n }\n };\n }, [getLoading, setLoading, bridgeRef]);\n\n return null;\n}\n\nexport default function ChatPage() {\n const { t } = useTranslation();\n const navigate = useNavigate();\n const location = useLocation();\n const { isDark } = useTheme();\n const chatId = useMemo(() => {\n const match = location.pathname.match(/^\\/chat\\/(.+)$/);\n return match?.[1];\n }, [location.pathname]);\n const [showModelPrompt, setShowModelPrompt] = useState(false);\n const { selectedAgent } = useAgentStore();\n const [refreshKey, setRefreshKey] = useState(0);\n const [chatStatus, setChatStatus] = useState<\"idle\" | \"running\">(\"idle\");\n const [, setReconnectStreaming] = useState(false);\n const reconnectTriggeredForRef = useRef(null);\n const prevChatIdRef = useRef(undefined);\n const runtimeLoadingBridgeRef = useRef(null);\n\n const isComposingRef = useRef(false);\n const isChatActiveRef = useRef(false);\n isChatActiveRef.current =\n location.pathname === \"/\" || location.pathname.startsWith(\"/chat\");\n\n const lastSessionIdRef = useRef(null);\n const chatIdRef = useRef(chatId);\n const navigateRef = useRef(navigate);\n const chatRef = useRef(null);\n chatIdRef.current = chatId;\n navigateRef.current = navigate;\n\n useEffect(() => {\n sessionApi.setChatRef(chatRef);\n return () => sessionApi.setChatRef(null);\n }, []);\n\n useEffect(() => {\n const handleCompositionStart = () => {\n if (!isChatActiveRef.current) return;\n isComposingRef.current = true;\n };\n\n const handleCompositionEnd = () => {\n if (!isChatActiveRef.current) return;\n setTimeout(() => {\n isComposingRef.current = false;\n }, 150);\n };\n\n const handleKeyPress = (e: KeyboardEvent) => {\n if (!isChatActiveRef.current) return;\n const target = e.target as HTMLElement;\n if (target?.tagName === \"TEXTAREA\" && e.key === \"Enter\" && !e.shiftKey) {\n if (isComposingRef.current || (e as any).isComposing) {\n e.stopPropagation();\n e.stopImmediatePropagation();\n return false;\n }\n }\n };\n\n document.addEventListener(\"compositionstart\", handleCompositionStart, true);\n document.addEventListener(\"compositionend\", handleCompositionEnd, true);\n document.addEventListener(\"keypress\", handleKeyPress, true);\n\n return () => {\n document.removeEventListener(\n \"compositionstart\",\n handleCompositionStart,\n true,\n );\n document.removeEventListener(\n \"compositionend\",\n handleCompositionEnd,\n true,\n );\n document.removeEventListener(\"keypress\", handleKeyPress, true);\n };\n }, []);\n\n useEffect(() => {\n sessionApi.onSessionIdResolved = (tempId, realId) => {\n if (!isChatActiveRef.current) return;\n if (chatIdRef.current === tempId) {\n lastSessionIdRef.current = realId;\n navigateRef.current(`/chat/${realId}`, { replace: true });\n }\n };\n\n sessionApi.onSessionRemoved = (removedId) => {\n if (!isChatActiveRef.current) return;\n if (chatIdRef.current === removedId) {\n lastSessionIdRef.current = null;\n navigateRef.current(\"/chat\", { replace: true });\n }\n };\n\n return () => {\n sessionApi.onSessionIdResolved = null;\n sessionApi.onSessionRemoved = null;\n };\n }, []);\n\n // Fetch chat status when viewing a chat (for running indicator and reconnect)\n useEffect(() => {\n if (!chatId || chatId === \"undefined\" || chatId === \"null\") {\n setChatStatus(\"idle\");\n return;\n }\n const realId = sessionApi.getRealIdForSession(chatId) ?? chatId;\n api.getChat(realId).then(\n (res) => setChatStatus((res.status as \"idle\" | \"running\") ?? \"idle\"),\n () => setChatStatus(\"idle\"),\n );\n }, [chatId]);\n\n // Trigger reconnect when session status becomes \"running\" so the library\n // consumes the SSE stream. Done here (not in sessionApi.getSession) so we\n // run after React has updated and the chat input ref is ready, avoiding\n // a fixed timeout and race conditions.\n useEffect(() => {\n if (prevChatIdRef.current !== chatId) {\n prevChatIdRef.current = chatId;\n reconnectTriggeredForRef.current = null;\n }\n if (!chatId || chatStatus !== \"running\") return;\n if (reconnectTriggeredForRef.current === chatId) return;\n reconnectTriggeredForRef.current = chatId;\n sessionApi.triggerReconnectSubmit();\n }, [chatId, chatStatus]);\n\n // Refresh chat when selectedAgent changes\n const prevSelectedAgentRef = useRef(selectedAgent);\n useEffect(() => {\n // Only refresh if selectedAgent actually changed (not initial mount)\n if (\n prevSelectedAgentRef.current !== selectedAgent &&\n prevSelectedAgentRef.current !== undefined\n ) {\n // Force re-render by updating refresh key\n setRefreshKey((prev) => prev + 1);\n }\n prevSelectedAgentRef.current = selectedAgent;\n }, [selectedAgent]);\n\n const getSessionListWrapped = useCallback(async () => {\n const sessions = await sessionApi.getSessionList();\n const currentChatId = chatIdRef.current;\n\n if (currentChatId) {\n const idx = sessions.findIndex((s) => s.id === currentChatId);\n if (idx > 0) {\n return [\n sessions[idx],\n ...sessions.slice(0, idx),\n ...sessions.slice(idx + 1),\n ];\n }\n }\n\n return sessions;\n }, []);\n\n const getSessionWrapped = useCallback(async (sessionId: string) => {\n const currentChatId = chatIdRef.current;\n\n if (\n isChatActiveRef.current &&\n sessionId &&\n sessionId !== lastSessionIdRef.current &&\n sessionId !== currentChatId\n ) {\n const urlId = sessionApi.getRealIdForSession(sessionId) ?? sessionId;\n lastSessionIdRef.current = urlId;\n navigateRef.current(`/chat/${urlId}`, { replace: true });\n }\n\n return sessionApi.getSession(sessionId);\n }, []);\n\n const createSessionWrapped = useCallback(async (session: any) => {\n const result = await sessionApi.createSession(session);\n const newSessionId = session?.id || result[0]?.id;\n if (isChatActiveRef.current && newSessionId) {\n lastSessionIdRef.current = newSessionId;\n navigateRef.current(`/chat/${newSessionId}`, { replace: true });\n }\n return result;\n }, []);\n\n const wrappedSessionApi = useMemo(\n () => ({\n getSessionList: getSessionListWrapped,\n getSession: getSessionWrapped,\n createSession: createSessionWrapped,\n updateSession: sessionApi.updateSession.bind(sessionApi),\n removeSession: sessionApi.removeSession.bind(sessionApi),\n }),\n [],\n );\n\n const copyResponse = useCallback(\n async (response: CopyableResponse) => {\n try {\n await copyText(extractCopyableText(response));\n message.success(t(\"common.copied\"));\n } catch {\n message.error(t(\"common.copyFailed\"));\n }\n },\n [t],\n );\n\n const persistSessionMessages = useCallback(\n async (sessionId: string, messages: RuntimeUiMessage[]) => {\n if (!sessionId) return;\n await sessionApi.updateSession({\n id: sessionId,\n messages: cloneRuntimeMessages(messages),\n });\n },\n [],\n );\n\n const releaseStaleLoadingState = useCallback((sessionId: string) => {\n const activeChatId = chatIdRef.current;\n const realSessionId = sessionApi.getRealIdForSession(sessionId);\n const isBackgroundSession =\n activeChatId !== sessionId && activeChatId !== realSessionId;\n\n if (!isBackgroundSession) {\n return;\n }\n\n if (sessionApi.hasLiveMessagesForSession(activeChatId)) {\n return;\n }\n\n runtimeLoadingBridgeRef.current?.setLoading?.(false);\n }, []);\n\n const persistStreamSession = useCallback(\n (sessionId: string, readableStream: ReadableStream) => {\n const initialMessages = cloneRuntimeMessages(\n (chatRef.current?.messages.getMessages() as RuntimeUiMessage[]) || [],\n );\n const assistantMessageId =\n getStreamingAssistantMessageId(initialMessages) ||\n `stream-${sessionId}`;\n const responseBuilder = new AgentScopeRuntimeResponseBuilder({\n id: \"\",\n status: AgentScopeRuntimeRunStatus.Created,\n created_at: 0,\n });\n\n void (async () => {\n let cachedMessages = initialMessages;\n let hasStreamActivity = false;\n let didReleaseLoading = false;\n\n try {\n for await (const chunk of Stream({ readableStream })) {\n let chunkData: unknown;\n try {\n chunkData = JSON.parse(chunk.data);\n } catch {\n continue;\n }\n\n hasStreamActivity = true;\n const responseData = responseBuilder.handle(\n chunkData as never,\n ) as StreamResponseData;\n const isFinalChunk = isFinalResponseStatus(responseData.status);\n const existingAssistantMessage = cachedMessages.find(\n (message) => message.id === assistantMessageId,\n );\n const previousResponseData = getResponseCardData(\n existingAssistantMessage,\n );\n\n let nextResponseData: StreamResponseData | null = null;\n if (hasRenderableOutput(responseData)) {\n nextResponseData = cloneValue(responseData);\n } else if (isFinalChunk && previousResponseData) {\n nextResponseData = {\n ...previousResponseData,\n status: responseData.status ?? previousResponseData.status,\n };\n }\n\n if (nextResponseData) {\n const assistantMessage: RuntimeUiMessage = {\n ...(existingAssistantMessage || {\n id: assistantMessageId,\n role: \"assistant\",\n }),\n id: assistantMessageId,\n role: \"assistant\",\n cards: [\n {\n code: \"AgentScopeRuntimeResponseCard\",\n data: nextResponseData,\n },\n ],\n msgStatus: isFinalChunk ? \"finished\" : \"generating\",\n };\n\n const assistantIndex = cachedMessages.findIndex(\n (message) => message.id === assistantMessageId,\n );\n cachedMessages =\n assistantIndex >= 0\n ? [\n ...cachedMessages.slice(0, assistantIndex),\n assistantMessage,\n ...cachedMessages.slice(assistantIndex + 1),\n ]\n : [...cachedMessages, assistantMessage];\n\n await persistSessionMessages(sessionId, cachedMessages);\n }\n\n if (!isFinalChunk) {\n continue;\n }\n\n releaseStaleLoadingState(sessionId);\n didReleaseLoading = true;\n }\n } catch (error) {\n console.error(\"Failed to persist background chat stream:\", error);\n } finally {\n if (!hasStreamActivity || didReleaseLoading) {\n return;\n }\n\n releaseStaleLoadingState(sessionId);\n }\n })();\n },\n [persistSessionMessages, releaseStaleLoadingState],\n );\n\n const customFetch = useCallback(\n async (data: {\n input?: any[];\n biz_params?: any;\n signal?: AbortSignal;\n reconnect?: boolean;\n session_id?: string;\n user_id?: string;\n channel?: string;\n }): Promise => {\n const headers: Record = {\n \"Content-Type\": \"application/json\",\n };\n const token = getApiToken();\n if (token) headers.Authorization = `Bearer ${token}`;\n try {\n const agentStorage = localStorage.getItem(\"copaw-agent-storage\");\n if (agentStorage) {\n const parsed = JSON.parse(agentStorage);\n const selectedAgent = parsed?.state?.selectedAgent;\n if (selectedAgent) {\n headers[\"X-Agent-Id\"] = selectedAgent;\n }\n }\n } catch (error) {\n console.warn(\"Failed to get selected agent from storage:\", error);\n }\n\n const shouldReconnect =\n data.reconnect || data.biz_params?.reconnect === true;\n const reconnectSessionId =\n data.session_id ?? window.currentSessionId ?? \"\";\n if (shouldReconnect && reconnectSessionId) {\n const res = await fetch(getApiUrl(\"/console/chat\"), {\n method: \"POST\",\n headers,\n body: JSON.stringify({\n reconnect: true,\n session_id: reconnectSessionId,\n user_id: data.user_id ?? window.currentUserId ?? \"default\",\n channel: data.channel ?? window.currentChannel ?? \"console\",\n }),\n });\n if (!res.ok || !res.body) return res;\n const onStreamEnd = () => {\n setChatStatus(\"idle\");\n setReconnectStreaming(false);\n };\n const stream = res.body;\n const transformed = new ReadableStream({\n start(controller) {\n const reader = stream.getReader();\n function pump() {\n reader.read().then(({ done, value }) => {\n if (done) {\n controller.close();\n onStreamEnd();\n return;\n }\n controller.enqueue(value);\n return pump();\n });\n }\n pump();\n },\n });\n return new Response(transformed, {\n headers: res.headers,\n status: res.status,\n });\n }\n\n try {\n const activeModels = await providerApi.getActiveModels();\n if (\n !activeModels?.active_llm?.provider_id ||\n !activeModels?.active_llm?.model\n ) {\n setShowModelPrompt(true);\n return buildModelError();\n }\n } catch {\n setShowModelPrompt(true);\n return buildModelError();\n }\n\n const { input = [], biz_params } = data;\n const session = input[input.length - 1]?.session || {};\n const lastInput = input.slice(-1);\n const lastMsg = lastInput[0];\n const rewrittenInput =\n lastMsg?.content && Array.isArray(lastMsg.content)\n ? [\n {\n ...lastMsg,\n content: lastMsg.content.map((part: any) => {\n const p = { ...part };\n const toStoredName = (v: string) => {\n const m1 = v.match(/\\/console\\/files\\/[^/]+\\/(.+)$/);\n if (m1) return m1[1];\n const m2 = v.match(/^[^/]+\\/(.+)$/);\n if (m2) return m2[1];\n return v;\n };\n if (p.type === \"image\" && typeof p.image_url === \"string\")\n p.image_url = toStoredName(p.image_url);\n if (p.type === \"file\" && typeof p.file_url === \"string\")\n p.file_url = toStoredName(p.file_url);\n if (p.type === \"audio\" && typeof p.audio_url === \"string\")\n p[\"data\"] = toStoredName(p.audio_url);\n if (p.type === \"video\" && typeof p.video_url === \"string\")\n p.video_url = toStoredName(p.video_url);\n\n return p;\n }),\n },\n ]\n : lastInput;\n\n const requestBody = {\n input: rewrittenInput,\n session_id: window.currentSessionId || session?.session_id || \"\",\n user_id: window.currentUserId || session?.user_id || \"default\",\n channel: window.currentChannel || session?.channel || \"console\",\n stream: true,\n ...biz_params,\n };\n\n const response = await fetch(getApiUrl(\"/console/chat\"), {\n method: \"POST\",\n headers,\n body: JSON.stringify(requestBody),\n signal: data.signal,\n });\n\n if (!response.ok || !response.body || !requestBody.session_id) {\n return response;\n }\n\n const [uiStream, cacheStream] = response.body.tee();\n persistStreamSession(requestBody.session_id, cacheStream);\n\n return new Response(uiStream, {\n status: response.status,\n statusText: response.statusText,\n headers: response.headers,\n });\n },\n [persistStreamSession, setChatStatus, setReconnectStreaming],\n );\n\n const options = useMemo(() => {\n const i18nConfig = getDefaultConfig(t);\n\n const handleBeforeSubmit = async () => {\n if (isComposingRef.current) return false;\n return true;\n };\n\n return {\n ...i18nConfig,\n theme: {\n ...defaultConfig.theme,\n darkMode: isDark,\n leftHeader: {\n ...defaultConfig.theme.leftHeader,\n },\n rightHeader: (\n <>\n \n \n \n ),\n },\n welcome: {\n ...i18nConfig.welcome,\n avatar: isDark\n ? `${import.meta.env.BASE_URL}copaw-dark.png`\n : `${import.meta.env.BASE_URL}copaw-symbol.svg`,\n },\n sender: {\n ...(i18nConfig as any)?.sender,\n beforeSubmit: handleBeforeSubmit,\n attachments: {\n trigger: function (props: any) {\n return (\n \n }\n bordered={false}\n />\n \n );\n },\n accept: \"*/*\",\n customRequest: async (options: {\n file: File;\n onSuccess: (body: { url?: string; thumbUrl?: string }) => void;\n onError?: (e: Error) => void;\n onProgress?: (e: { percent?: number }) => void;\n }) => {\n try {\n console.log(\"options.file\", options.file);\n\n // Check file size limit (10MB)\n const file = options.file as File;\n const isLt10M = file.size / 1024 / 1024 < 10;\n if (!isLt10M) {\n message.error(t(\"chat.attachments.fileSizeLimit\"));\n return options.onError?.(new Error(\"File size exceeds 10MB\"));\n }\n\n options.onProgress?.({ percent: 0 });\n const res = await chatApi.uploadFile(options.file);\n options.onProgress?.({ percent: 100 });\n options.onSuccess({ url: chatApi.fileUrl(res.url) });\n } catch (e) {\n options.onError?.(e instanceof Error ? e : new Error(String(e)));\n }\n },\n },\n },\n session: { multiple: true, api: wrappedSessionApi },\n api: {\n ...defaultConfig.api,\n fetch: customFetch,\n cancel(data: { session_id: string }) {\n const chatIdForStop = data?.session_id\n ? sessionApi.getRealIdForSession(data.session_id) ?? data.session_id\n : \"\";\n if (chatIdForStop) {\n chatApi.stopConsoleChat(chatIdForStop).then(\n () => setChatStatus(\"idle\"),\n (err) => {\n console.error(\"stopConsoleChat failed:\", err);\n },\n );\n }\n },\n },\n actions: {\n list: [\n {\n icon: (\n \n \n \n ),\n onClick: ({ data }: { data: CopyableResponse }) => {\n void copyResponse(data);\n },\n },\n ],\n replace: true,\n },\n } as unknown as IAgentScopeRuntimeWebUIOptions;\n }, [wrappedSessionApi, customFetch, copyResponse, t, isDark]);\n\n return (\n \n
    \n \n
    \n\n \n }\n title={\n \n {t(\"modelConfig.promptTitle\")}\n \n }\n subTitle={\n \n {t(\"modelConfig.promptMessage\")}\n \n }\n extra={[\n ,\n }\n onClick={() => {\n setShowModelPrompt(false);\n navigate(\"/models\");\n }}\n >\n {t(\"modelConfig.configureButton\")}\n ,\n ]}\n />\n \n \n );\n}\n" }, { "path": "console/src/pages/Chat/sessionApi/index.ts", "content": "import type { RefObject } from \"react\";\nimport {\n IAgentScopeRuntimeWebUISession,\n IAgentScopeRuntimeWebUISessionAPI,\n IAgentScopeRuntimeWebUIMessage,\n IAgentScopeRuntimeWebUIRef,\n IAgentScopeRuntimeWebUIInputData,\n} from \"@agentscope-ai/chat\";\nimport api, { type ChatSpec, type Message } from \"../../../api\";\nimport { chatApi } from \"../../../api/modules/chat\";\n\n// ---------------------------------------------------------------------------\n// Constants\n// ---------------------------------------------------------------------------\n\nconst DEFAULT_USER_ID = \"default\";\nconst DEFAULT_CHANNEL = \"console\";\nconst DEFAULT_SESSION_NAME = \"New Chat\";\nconst ROLE_TOOL = \"tool\";\nconst ROLE_USER = \"user\";\nconst ROLE_ASSISTANT = \"assistant\";\nconst TYPE_PLUGIN_CALL_OUTPUT = \"plugin_call_output\";\n// const CARD_REQUEST = \"AgentScopeRuntimeRequestCard\";\nconst CARD_RESPONSE = \"AgentScopeRuntimeResponseCard\";\n\n// ---------------------------------------------------------------------------\n// Window globals\n// ---------------------------------------------------------------------------\n\ninterface CustomWindow extends Window {\n currentSessionId?: string;\n currentUserId?: string;\n currentChannel?: string;\n}\n\ndeclare const window: CustomWindow;\n\n// ---------------------------------------------------------------------------\n// Local helper types\n// ---------------------------------------------------------------------------\n\n/** A single item inside a message's content array. */\ninterface ContentItem {\n type: string;\n text?: string;\n [key: string]: unknown;\n}\n\n/** A backend message after role-normalisation (output of toOutputMessage). */\ninterface OutputMessage extends Omit {\n role: string;\n metadata: null;\n sequence_number?: number;\n}\n\n/**\n * Extended session carrying extra fields that the library type does not define\n * but our backend / window globals require.\n */\ninterface ExtendedSession extends IAgentScopeRuntimeWebUISession {\n sessionId: string;\n userId: string;\n channel: string;\n meta: Record;\n /** Real backend UUID, used when id is overridden with a local timestamp. */\n realId?: string;\n /** Conversation status: idle or running (for reconnect). */\n status?: \"idle\" | \"running\";\n}\n\ninterface RuntimeResponseCard {\n data?: {\n status?: string;\n };\n}\n\nconst LIVE_MESSAGE_STATUSES = new Set([\"generating\", \"created\", \"in_progress\"]);\n\nconst hasLiveMessages = (\n messages?: IAgentScopeRuntimeWebUIMessage[],\n): boolean => {\n if (!messages?.length) return false;\n\n return messages.some((message) => {\n const msgStatus =\n typeof (message as { msgStatus?: unknown }).msgStatus === \"string\"\n ? ((message as { msgStatus: string }).msgStatus as string)\n : undefined;\n\n if (msgStatus && LIVE_MESSAGE_STATUSES.has(msgStatus)) {\n return true;\n }\n\n const cards = (message as { cards?: RuntimeResponseCard[] }).cards;\n return (\n cards?.some((card) => {\n const status = card.data?.status;\n return !!status && LIVE_MESSAGE_STATUSES.has(status);\n }) ?? false\n );\n });\n};\n\nconst hasMessages = (messages?: IAgentScopeRuntimeWebUIMessage[]): boolean =>\n (messages?.length ?? 0) > 0;\n\nconst shouldPreferLocalMessages = (\n localMessages?: IAgentScopeRuntimeWebUIMessage[],\n remoteMessages?: IAgentScopeRuntimeWebUIMessage[],\n): boolean => {\n if (!hasMessages(localMessages)) {\n return false;\n }\n\n if (!hasMessages(remoteMessages)) {\n return true;\n }\n\n return (remoteMessages?.length ?? 0) < (localMessages?.length ?? 0);\n};\n\n// ---------------------------------------------------------------------------\n// Message conversion helpers: backend flat messages → card-based UI format\n// ---------------------------------------------------------------------------\n\nfunction generateId(): string {\n return `${Date.now()}-${Math.random().toString(36).substr(2, 9)}`;\n}\n\n/** Turn a backend content URL (path or full URL) into a full URL for display. */\nfunction toDisplayUrl(url: string | undefined): string {\n if (!url) return \"\";\n if (url.startsWith(\"http://\") || url.startsWith(\"https://\")) return url;\n return chatApi.fileUrl(url.startsWith(\"/\") ? url : `/${url}`);\n}\n\n/** Map backend message content to request card content (text + image + file). */\nfunction contentToRequestParts(\n content: unknown,\n): Array> {\n if (typeof content === \"string\") {\n return [{ type: \"text\", text: content, status: \"created\" }];\n }\n if (!Array.isArray(content)) {\n return [{ type: \"text\", text: String(content || \"\"), status: \"created\" }];\n }\n const parts: Array> = [];\n for (const c of content as ContentItem[]) {\n if (c.type === \"text\") {\n if (c.text) parts.push({ type: \"text\", text: c.text, status: \"created\" });\n } else if (c.type === \"image\" && c.image_url) {\n parts.push({\n type: \"image\",\n image_url: toDisplayUrl(c.image_url as string),\n status: \"created\",\n });\n } else if (c.type === \"file\" && (c.file_url || c.file_id)) {\n parts.push({\n type: \"file\",\n file_url: toDisplayUrl((c.file_url as string) || (c.file_id as string)),\n file_name: (c.filename as string) || (c.file_name as string) || \"file\",\n status: \"created\",\n });\n }\n }\n if (parts.length === 0) {\n parts.push({ type: \"text\", text: \"\", status: \"created\" });\n }\n return parts;\n}\n\n/**\n * Convert a backend message to a response output message.\n * Maps system + plugin_call_output → role \"tool\" and strips metadata.\n */\nconst toOutputMessage = (msg: Message): OutputMessage => ({\n ...msg,\n role:\n msg.type === TYPE_PLUGIN_CALL_OUTPUT && msg.role === \"system\"\n ? ROLE_TOOL\n : msg.role,\n metadata: null,\n});\n\n/** Build a user card (AgentScopeRuntimeRequestCard) from a user message. */\nfunction buildUserCard(msg: Message): IAgentScopeRuntimeWebUIMessage {\n const contentParts = contentToRequestParts(msg.content);\n return {\n id: (msg.id as string) || generateId(),\n role: \"user\",\n cards: [\n {\n code: \"AgentScopeRuntimeRequestCard\",\n data: {\n input: [\n {\n role: \"user\",\n type: \"message\",\n content: contentParts,\n },\n ],\n },\n },\n ],\n };\n}\n\n/**\n * Build an assistant response card (AgentScopeRuntimeResponseCard)\n * wrapping a group of consecutive non-user output messages.\n */\nconst buildResponseCard = (\n outputMessages: OutputMessage[],\n): IAgentScopeRuntimeWebUIMessage => {\n const now = Math.floor(Date.now() / 1000);\n const maxSeq = outputMessages.reduce(\n (max, m) => Math.max(max, m.sequence_number || 0),\n 0,\n );\n return {\n id: generateId(),\n role: ROLE_ASSISTANT,\n cards: [\n {\n code: CARD_RESPONSE,\n data: {\n id: `response_${generateId()}`,\n output: outputMessages,\n object: \"response\",\n status: \"completed\",\n created_at: now,\n sequence_number: maxSeq + 1,\n error: null,\n completed_at: now,\n usage: null,\n },\n },\n ],\n msgStatus: \"finished\",\n };\n};\n\n/**\n * Convert flat backend messages into the card-based format expected by\n * the @agentscope-ai/chat component.\n *\n * - User messages → AgentScopeRuntimeRequestCard\n * - Consecutive non-user messages (assistant / system / tool) → grouped\n * into a single AgentScopeRuntimeResponseCard with all output messages.\n */\nconst convertMessages = (\n messages: Message[],\n): IAgentScopeRuntimeWebUIMessage[] => {\n const result: IAgentScopeRuntimeWebUIMessage[] = [];\n let i = 0;\n\n while (i < messages.length) {\n if (messages[i].role === ROLE_USER) {\n result.push(buildUserCard(messages[i++]));\n } else {\n const outputMsgs: OutputMessage[] = [];\n while (i < messages.length && messages[i].role !== ROLE_USER) {\n outputMsgs.push(toOutputMessage(messages[i++]));\n }\n if (outputMsgs.length) result.push(buildResponseCard(outputMsgs));\n }\n }\n\n return result;\n};\n\nconst chatSpecToSession = (chat: ChatSpec): ExtendedSession =>\n ({\n id: chat.id,\n name: (chat as ChatSpec & { name?: string }).name || DEFAULT_SESSION_NAME,\n sessionId: chat.session_id,\n userId: chat.user_id,\n channel: chat.channel,\n messages: [],\n meta: chat.meta || {},\n status: chat.status ?? \"idle\",\n }) as ExtendedSession;\n\n/** Returns true when id is a pure numeric local timestamp (not a backend UUID). */\nconst isLocalTimestamp = (id: string): boolean => /^\\d+$/.test(id);\n\n/**\n * Resolve and persist the real backend UUID for a local timestamp session.\n * Stores the real UUID as realId while keeping the timestamp as id, so the\n * library's internal currentSessionId (timestamp) remains valid.\n * Returns the resolved real UUID, or null if not found.\n */\nconst resolveRealId = (\n sessionList: IAgentScopeRuntimeWebUISession[],\n tempSessionId: string,\n): { list: IAgentScopeRuntimeWebUISession[]; realId: string | null } => {\n const realSession = sessionList.find(\n (s) => (s as ExtendedSession).sessionId === tempSessionId,\n );\n if (!realSession) return { list: sessionList, realId: null };\n\n const realUUID = realSession.id;\n // Keep the timestamp as id (so the library's currentSessionId still matches),\n // and store the real UUID in realId for backend requests.\n (realSession as ExtendedSession).realId = realUUID;\n realSession.id = tempSessionId;\n return {\n list: [realSession, ...sessionList.filter((s) => s !== realSession)],\n realId: realUUID,\n };\n};\n\n// ---------------------------------------------------------------------------\n// SessionApi\n// ---------------------------------------------------------------------------\n\nclass SessionApi implements IAgentScopeRuntimeWebUISessionAPI {\n private sessionList: IAgentScopeRuntimeWebUISession[] = [];\n private resolvingSessionIds: Set = new Set();\n\n private findSessionIndexByAnyId(sessionId?: string | null): number {\n if (!sessionId) {\n return -1;\n }\n\n return this.sessionList.findIndex((session) => {\n const extended = session as ExtendedSession;\n return (\n extended.id === sessionId ||\n extended.realId === sessionId ||\n extended.sessionId === sessionId\n );\n });\n }\n\n private findSessionByAnyId(\n sessionId?: string | null,\n ): ExtendedSession | null {\n const index = this.findSessionIndexByAnyId(sessionId);\n return index >= 0 ? (this.sessionList[index] as ExtendedSession) : null;\n }\n\n private cacheSession(session: ExtendedSession): void {\n const index = this.findSessionIndexByAnyId(session.id);\n if (index >= 0) {\n const existing = this.sessionList[index] as ExtendedSession;\n this.sessionList[index] = {\n ...existing,\n ...session,\n id: existing.id,\n realId: session.realId ?? existing.realId,\n } as ExtendedSession;\n return;\n }\n\n this.sessionList.unshift(session);\n }\n\n /**\n * Deduplicates concurrent getSessionList calls so that two parallel\n * invocations share one network request and write sessionList only once,\n * preserving any realId mappings that were already resolved.\n */\n private sessionListRequest: Promise | null =\n null;\n\n /**\n * Deduplicates concurrent getSession calls for the same sessionId.\n * Key: sessionId, Value: in-flight promise for getSession.\n */\n private sessionRequests: Map<\n string,\n Promise\n > = new Map();\n\n /**\n * Called when a temporary timestamp session id is resolved to a real backend\n * UUID. Consumers (e.g. Chat/index.tsx) can register here to update the URL.\n */\n onSessionIdResolved: ((tempId: string, realId: string) => void) | null = null;\n\n /**\n * Called after a session is removed. Consumers can register here to clear\n * the session id from the URL.\n */\n onSessionRemoved: ((removedId: string) => void) | null = null;\n\n /**\n * Ref to the chat component so we can trigger submit with reconnect flag\n * (library will call customFetch with biz_params.reconnect and consume the SSE stream).\n */\n private chatRef: RefObject | null = null;\n\n setChatRef(ref: RefObject | null): void {\n this.chatRef = ref;\n }\n\n /**\n * Programmatically trigger the library's submit with biz_params.reconnect so\n * customFetch does POST /console/chat with reconnect:true and the library\n * consumes the SSE stream (replay + live tail).\n */\n triggerReconnectSubmit(): void {\n const ref = this.chatRef?.current;\n if (!ref?.input?.submit) {\n console.warn(\"triggerReconnectSubmit: chatRef not available\");\n return;\n }\n ref.input.submit({\n query: \"\",\n biz_params: {\n reconnect: true,\n } as IAgentScopeRuntimeWebUIInputData[\"biz_params\"],\n });\n }\n\n private resolveRealIdInBackground(tempId: string): void {\n if (this.resolvingSessionIds.has(tempId)) {\n return;\n }\n\n this.resolvingSessionIds.add(tempId);\n void this.getSessionList()\n .then(() => {\n const { list, realId } = resolveRealId(this.sessionList, tempId);\n this.sessionList = list;\n if (realId) {\n this.onSessionIdResolved?.(tempId, realId);\n }\n })\n .finally(() => {\n this.resolvingSessionIds.delete(tempId);\n });\n }\n\n private createEmptySession(sessionId: string): ExtendedSession {\n window.currentSessionId = sessionId;\n window.currentUserId = DEFAULT_USER_ID;\n window.currentChannel = DEFAULT_CHANNEL;\n return {\n id: sessionId,\n name: DEFAULT_SESSION_NAME,\n sessionId,\n userId: DEFAULT_USER_ID,\n channel: DEFAULT_CHANNEL,\n messages: [],\n meta: {},\n } as ExtendedSession;\n }\n\n private updateWindowVariables(session: ExtendedSession): void {\n window.currentSessionId = session.sessionId || \"\";\n window.currentUserId = session.userId || DEFAULT_USER_ID;\n window.currentChannel = session.channel || DEFAULT_CHANNEL;\n }\n\n private getLocalSession(sessionId: string): IAgentScopeRuntimeWebUISession {\n const local = this.sessionList.find((s) => s.id === sessionId);\n if (local) {\n this.updateWindowVariables(local as ExtendedSession);\n return local;\n }\n return this.createEmptySession(sessionId);\n }\n\n /**\n * Returns the real backend UUID for a session identified by id (which may be\n * a local timestamp). Returns null when not yet resolved or not found.\n */\n getRealIdForSession(sessionId: string): string | null {\n const s = this.findSessionByAnyId(sessionId);\n return s?.realId ?? null;\n }\n\n hasLiveMessagesForSession(sessionId?: string | null): boolean {\n return hasLiveMessages(this.findSessionByAnyId(sessionId)?.messages);\n }\n\n async getSessionList() {\n // Deduplicate: reuse the in-flight request if one is already running so\n // concurrent calls don't overwrite sessionList and lose realId mappings.\n if (this.sessionListRequest) return this.sessionListRequest;\n\n this.sessionListRequest = (async () => {\n try {\n const previousSessions = [...this.sessionList] as ExtendedSession[];\n const chats = await api.listChats();\n const newList = chats\n .filter((c) => c.id && c.id !== \"undefined\" && c.id !== \"null\")\n .map(chatSpecToSession)\n .reverse();\n\n // Merge: preserve realId mappings (timestamp → UUID) stored in memory\n const mergedSessions = newList.map((s) => {\n const existing = previousSessions.find(\n (e) =>\n (e as ExtendedSession).sessionId ===\n (s as ExtendedSession).sessionId,\n ) as ExtendedSession | undefined;\n\n if (!existing) {\n return s;\n }\n\n return {\n ...s,\n id: existing.realId ? existing.id : s.id,\n name:\n existing.name && existing.name !== DEFAULT_SESSION_NAME\n ? existing.name\n : s.name,\n messages: hasMessages(existing.messages)\n ? existing.messages\n : s.messages,\n meta:\n Object.keys(existing.meta || {}).length > 0\n ? existing.meta\n : s.meta,\n realId: existing.realId,\n } as ExtendedSession;\n });\n\n const preservedLocalSessions = previousSessions.filter((session) => {\n if (!isLocalTimestamp(session.id) || session.realId) {\n return false;\n }\n\n return !mergedSessions.some(\n (merged) =>\n (merged as ExtendedSession).sessionId === session.sessionId,\n );\n });\n\n this.sessionList = [...preservedLocalSessions, ...mergedSessions];\n\n return [...this.sessionList];\n } finally {\n this.sessionListRequest = null;\n }\n })();\n\n return this.sessionListRequest;\n }\n\n async getSession(sessionId: string) {\n // Deduplicate: reuse the in-flight request if one is already running\n // for the same sessionId so concurrent calls share one network request.\n const existingRequest = this.sessionRequests.get(sessionId);\n if (existingRequest) return existingRequest;\n\n const requestPromise = this._doGetSession(sessionId);\n this.sessionRequests.set(sessionId, requestPromise);\n\n try {\n const result = await requestPromise;\n // Reconnect for running sessions is triggered by ChatPage when session\n // status becomes \"running\" (useEffect on chatStatus), avoiding a fixed\n // timeout and race conditions with the chat input ref.\n return result;\n } finally {\n this.sessionRequests.delete(sessionId);\n }\n }\n\n private async _doGetSession(\n sessionId: string,\n ): Promise {\n // --- Local timestamp ID (New Chat before first reply) ---\n if (isLocalTimestamp(sessionId)) {\n const fromList = this.sessionList.find((s) => s.id === sessionId) as\n | ExtendedSession\n | undefined;\n\n if (fromList && hasMessages(fromList.messages)) {\n this.updateWindowVariables(fromList);\n return fromList;\n }\n\n // If realId is already resolved, use it directly to fetch history.\n if (fromList?.realId) {\n const chatHistory = await api.getChat(fromList.realId);\n const remoteMessages = convertMessages(chatHistory.messages || []);\n\n if (shouldPreferLocalMessages(fromList.messages, remoteMessages)) {\n this.updateWindowVariables(fromList);\n return fromList;\n }\n\n const session: ExtendedSession = {\n id: sessionId,\n name: fromList.name || DEFAULT_SESSION_NAME,\n sessionId: fromList.sessionId || sessionId,\n userId: fromList.userId || DEFAULT_USER_ID,\n channel: fromList.channel || DEFAULT_CHANNEL,\n messages: remoteMessages,\n meta: fromList.meta || {},\n realId: fromList.realId,\n status: chatHistory.status ?? \"idle\",\n };\n this.cacheSession(session);\n this.updateWindowVariables(session);\n return session;\n }\n\n return this.getLocalSession(sessionId);\n }\n\n // --- No session selected (e.g. after delete) ---\n // Return a transient empty session; it is NOT added to sessionList so it\n // never appears as a list item. The component will call createSession on\n // the next submit via ensureSession.\n if (!sessionId || sessionId === \"undefined\" || sessionId === \"null\") {\n return this.createEmptySession(Date.now().toString());\n }\n\n // --- Regular backend UUID ---\n const fromList = this.sessionList.find((s) => s.id === sessionId) as\n | ExtendedSession\n | undefined;\n\n if (fromList && hasMessages(fromList.messages)) {\n this.updateWindowVariables(fromList);\n return fromList;\n }\n\n const chatHistory = await api.getChat(sessionId);\n const remoteMessages = convertMessages(chatHistory.messages || []);\n\n if (\n fromList &&\n shouldPreferLocalMessages(fromList.messages, remoteMessages)\n ) {\n this.updateWindowVariables(fromList);\n return fromList;\n }\n\n const session: ExtendedSession = {\n id: sessionId,\n name: fromList?.name || sessionId,\n sessionId: fromList?.sessionId || sessionId,\n userId: fromList?.userId || DEFAULT_USER_ID,\n channel: fromList?.channel || DEFAULT_CHANNEL,\n messages: remoteMessages,\n meta: fromList?.meta || {},\n status: chatHistory.status ?? \"idle\",\n };\n\n this.cacheSession(session);\n this.updateWindowVariables(session);\n return session;\n }\n\n async updateSession(session: Partial) {\n if (!session.id) {\n return [...this.sessionList];\n }\n\n const index = this.findSessionIndexByAnyId(session.id);\n\n if (index > -1) {\n const existing = this.sessionList[index] as ExtendedSession;\n this.sessionList[index] = {\n ...existing,\n ...session,\n id: existing.id,\n sessionId: existing.sessionId || session.id,\n userId: existing.userId || window.currentUserId || DEFAULT_USER_ID,\n channel: existing.channel || window.currentChannel || DEFAULT_CHANNEL,\n messages: session.messages ?? existing.messages,\n meta: existing.meta || {},\n } as ExtendedSession;\n\n // Timestamp session without realId yet — resolve in the background\n if (isLocalTimestamp(existing.id) && !existing.realId) {\n this.resolveRealIdInBackground(existing.id);\n }\n } else {\n const nextSession: ExtendedSession = {\n id: session.id,\n name: session.name ?? DEFAULT_SESSION_NAME,\n sessionId: session.id,\n userId: window.currentUserId || DEFAULT_USER_ID,\n channel: window.currentChannel || DEFAULT_CHANNEL,\n messages: session.messages ?? [],\n meta: {},\n };\n\n this.sessionList.unshift(nextSession);\n\n if (isLocalTimestamp(session.id)) {\n this.resolveRealIdInBackground(session.id);\n }\n }\n\n return [...this.sessionList];\n }\n\n async createSession(session: Partial) {\n session.id = Date.now().toString();\n\n const extended: ExtendedSession = {\n ...session,\n name: session.name || DEFAULT_SESSION_NAME,\n messages: session.messages ?? [],\n sessionId: session.id,\n userId: DEFAULT_USER_ID,\n channel: DEFAULT_CHANNEL,\n } as ExtendedSession;\n\n this.updateWindowVariables(extended);\n return [...this.sessionList];\n }\n\n async removeSession(session: Partial) {\n if (!session.id) return [...this.sessionList];\n\n const { id: sessionId } = session;\n\n const existing = this.sessionList.find((s) => s.id === sessionId) as\n | ExtendedSession\n | undefined;\n\n // Use realId (UUID) when available; skip backend call for pure local sessions\n const deleteId =\n existing?.realId ?? (isLocalTimestamp(sessionId) ? null : sessionId);\n\n if (deleteId) await api.deleteChat(deleteId);\n\n this.sessionList = this.sessionList.filter((s) => s.id !== sessionId);\n\n // Notify consumers (e.g. to clear the URL) with both the list id and the\n // real backend UUID so callers can match either form.\n const resolvedId = existing?.realId ?? sessionId;\n this.onSessionRemoved?.(resolvedId);\n\n return [...this.sessionList];\n }\n}\n\nexport default new SessionApi();\n" }, { "path": "console/src/pages/Control/Channels/components/ChannelCard.tsx", "content": "import { Card, Tooltip } from \"@agentscope-ai/design\";\nimport { useTranslation } from \"react-i18next\";\nimport { getChannelLabel, type ChannelKey } from \"./constants\";\nimport styles from \"../index.module.less\";\n\ninterface ChannelCardProps {\n channelKey: ChannelKey;\n config: Record;\n isHover: boolean;\n onClick: () => void;\n onMouseEnter: () => void;\n onMouseLeave: () => void;\n}\n\nexport function ChannelCard({\n channelKey,\n config,\n isHover,\n onClick,\n onMouseEnter,\n onMouseLeave,\n}: ChannelCardProps) {\n const { t } = useTranslation();\n const enabled = Boolean(config.enabled);\n const isBuiltin = Boolean(config.isBuiltin);\n const label = getChannelLabel(channelKey);\n const getConfigString = (key: string) =>\n typeof config[key] === \"string\" ? config[key] : \"\";\n const phoneNumber = getConfigString(\"phone_number\");\n const botPrefix = getConfigString(\"bot_prefix\");\n\n const getCardClassNames = () => {\n if (isHover) return `${styles.channelCard} ${styles.hover}`;\n if (enabled) return `${styles.channelCard} ${styles.enabled}`;\n return `${styles.channelCard} ${styles.normal}`;\n };\n\n return (\n \n
    \n \n
    \n
    {label}
    \n {isBuiltin ? (\n {t(\"channels.builtin\")}\n ) : (\n {t(\"channels.custom\")}\n )}\n
    \n     \n\n
    \n \n
    {enabled ? t(\"common.enabled\") : t(\"common.disabled\")}
    \n
    \n
    \n\n
    \n {channelKey === \"voice\" ? (\n <>\n {t(\"channels.phoneNumber\")}: {phoneNumber || t(\"channels.notSet\")}\n \n ) : (\n <>\n {t(\"channels.botPrefix\")}: {botPrefix || t(\"channels.notSet\")}\n \n )}\n
    \n\n
    \n {t(\"channels.clickCardToEdit\")}\n
    \n \n );\n}\n" }, { "path": "console/src/pages/Control/Channels/components/ChannelDrawer.tsx", "content": "import {\n Drawer,\n Form,\n Input,\n InputNumber,\n Switch,\n Button,\n Select,\n message,\n} from \"@agentscope-ai/design\";\nimport { Alert, ConfigProvider } from \"antd\";\nimport { LinkOutlined } from \"@ant-design/icons\";\nimport { useTranslation } from \"react-i18next\";\nimport type { FormInstance } from \"antd\";\nimport { useCallback, useRef } from \"react\";\nimport { getChannelLabel, type ChannelKey } from \"./constants\";\nimport styles from \"../index.module.less\";\nimport { useTheme } from \"../../../../contexts/ThemeContext\";\n\nconst WECOM_SDK_URL =\n \"https://wwcdn.weixin.qq.com/node/wework/js/wecom-aibot-sdk@0.1.0.min.js\";\n\nconst WECOM_SOURCE = \"copaw\";\n\ninterface WecomBotInfo {\n botid: string;\n secret: string;\n}\n\ninterface WecomAuthError {\n code: string;\n message: string;\n details?: unknown;\n}\n\ndeclare global {\n interface Window {\n WecomAIBotSDK?: {\n openBotInfoAuthWindow: (options: {\n source: string;\n onCreated?: (bot: WecomBotInfo) => void;\n onError?: (error: WecomAuthError) => void;\n }) => Promise | void;\n };\n }\n}\n\nconst CHANNELS_WITH_ACCESS_CONTROL: ChannelKey[] = [\n \"telegram\",\n \"dingtalk\",\n \"discord\",\n \"feishu\",\n \"wecom\",\n \"mattermost\",\n \"matrix\",\n];\n\n// Doc EN URLs per channel (anchors on https://copaw.agentscope.io/docs/channels)\nconst CHANNEL_DOC_EN_URLS: Partial> = {\n dingtalk:\n \"https://copaw.agentscope.io/docs/channels/?lang=en#DingTalk-recommended\",\n feishu: \"https://copaw.agentscope.io/docs/channels/?lang=en#Feishu-Lark\",\n imessage:\n \"https://copaw.agentscope.io/docs/channels/?lang=en#iMessage-macOS-only\",\n discord: \"https://copaw.agentscope.io/docs/channels/?lang=en#Discord\",\n qq: \"https://copaw.agentscope.io/docs/channels/?lang=en#QQ\",\n telegram: \"https://copaw.agentscope.io/docs/channels/?lang=en#Telegram\",\n mqtt: \"https://copaw.agentscope.io/docs/channels/?lang=en#MQTT\",\n mattermost: \"https://copaw.agentscope.io/docs/channels/?lang=en#Mattermost\",\n matrix: \"https://copaw.agentscope.io/docs/channels/?lang=en#Matrix\",\n wecom: \"https://copaw.agentscope.io/docs/channels/?lang=en#WeCom-WeChat-Work\",\n xiaoyi:\n \"https://developer.huawei.com/consumer/cn/doc/service/openclaw-0000002518410344\",\n};\n\n// Doc ZH URLs per channel (anchors on https://copaw.agentscope.io/docs/channels)\nconst CHANNEL_DOC_ZH_URLS: Partial> = {\n dingtalk: \"https://copaw.agentscope.io/docs/channels/?lang=zh#钉钉推荐\",\n feishu: \"https://copaw.agentscope.io/docs/channels/?lang=zh#飞书\",\n imessage:\n \"https://copaw.agentscope.io/docs/channels/?lang=zh#iMessage仅-macOS\",\n discord: \"https://copaw.agentscope.io/docs/channels/?lang=zh#Discord\",\n qq: \"https://copaw.agentscope.io/docs/channels/?lang=zh#QQ\",\n telegram: \"https://copaw.agentscope.io/docs/channels/?lang=zh#Telegram\",\n mqtt: \"https://copaw.agentscope.io/docs/channels/?lang=zh#MQTT\",\n mattermost: \"https://copaw.agentscope.io/docs/channels/?lang=zh#Mattermost\",\n matrix: \"https://copaw.agentscope.io/docs/channels/?lang=zh#Matrix\",\n wecom: \"https://copaw.agentscope.io/docs/channels/?lang=zh#企业微信\",\n xiaoyi:\n \"https://developer.huawei.com/consumer/cn/doc/service/openclaw-0000002518410344\",\n};\n\nconst TWILIO_CONSOLE_URL = \"https://console.twilio.com\";\n\nconst BASE_FIELDS = [\n \"enabled\",\n \"bot_prefix\",\n \"filter_tool_messages\",\n \"filter_thinking\",\n \"isBuiltin\",\n];\n\ninterface ChannelDrawerProps {\n open: boolean;\n activeKey: ChannelKey | null;\n activeLabel: string;\n form: FormInstance>;\n saving: boolean;\n initialValues: Record | undefined;\n isBuiltin: boolean;\n onClose: () => void;\n onSubmit: (values: Record) => void;\n}\n\nexport function ChannelDrawer({\n open,\n activeKey,\n activeLabel,\n form,\n saving,\n initialValues,\n isBuiltin,\n onClose,\n onSubmit,\n}: ChannelDrawerProps) {\n const { t, i18n } = useTranslation();\n const { isDark } = useTheme();\n const currentLang = i18n.language?.startsWith(\"zh\") ? \"zh\" : \"en\";\n const label = activeKey ? getChannelLabel(activeKey) : activeLabel;\n const sdkLoadedRef = useRef(false);\n\n // Dynamically load the WeCom SDK script\n const loadWecomSDK = useCallback((): Promise => {\n return new Promise((resolve, reject) => {\n if (window.WecomAIBotSDK || sdkLoadedRef.current) {\n resolve();\n return;\n }\n const script = document.createElement(\"script\");\n script.src = WECOM_SDK_URL;\n script.async = true;\n script.onload = () => {\n sdkLoadedRef.current = true;\n resolve();\n };\n script.onerror = () => reject(new Error(\"Failed to load WeCom SDK\"));\n document.body.appendChild(script);\n });\n }, []);\n\n // Handle WeCom scan-to-authorize button click; source is fixed to WECOM_SOURCE\n const handleWecomAuth = useCallback(async () => {\n try {\n await loadWecomSDK();\n } catch {\n message.error(t(\"channels.wecomSdkLoadFailed\"));\n return;\n }\n if (!window.WecomAIBotSDK) {\n message.error(t(\"channels.wecomSdkLoadFailed\"));\n return;\n }\n const result = window.WecomAIBotSDK.openBotInfoAuthWindow({\n source: WECOM_SOURCE,\n });\n if (result && typeof result.then === \"function\") {\n result.then(\n (bot) => {\n if (bot?.botid) {\n form.setFieldsValue({ bot_id: bot.botid, secret: bot.secret });\n message.success(t(\"channels.wecomAuthSuccess\"));\n }\n },\n (error: WecomAuthError) => {\n if (error?.code === \"WINDOW_BLOCKED\") {\n message.error(t(\"channels.wecomWindowBlocked\"));\n } else if (error?.code === \"CANCELLED\") {\n message.info(t(\"channels.wecomCancelled\"));\n } else {\n message.error(\n t(\"channels.wecomAuthFailed\", {\n msg: error?.message || error?.code || \"Unknown error\",\n }),\n );\n }\n },\n );\n }\n }, [loadWecomSDK, form, t]);\n\n // ── Access control fields (shared across multiple channels) ──────────────\n\n const renderAccessControlFields = () => (\n <>\n \n \n \n \n \n \n \n \n \n \n \n \n \n );\n\n // ── Builtin channel-specific fields ─────────────────────────────────────\n\n const renderBuiltinExtraFields = (key: ChannelKey) => {\n switch (key) {\n case \"matrix\":\n return (\n <>\n \n \n \n \n \n \n \n \n \n \n );\n\n case \"imessage\":\n return (\n <>\n \n \n \n \n \n \n \n );\n\n case \"discord\":\n return (\n <>\n \n \n \n \n \n \n \n \n \n \n );\n\n case \"dingtalk\":\n return (\n <>\n \n \n \n \n \n \n \n \n \n \n prev.message_type !== cur.message_type\n }\n >\n {({ getFieldValue }) => {\n if (getFieldValue(\"message_type\") !== \"card\") return null;\n return (\n <>\n \n \n \n \n \n \n \n \n \n \n );\n }}\n \n \n );\n\n case \"feishu\":\n return (\n <>\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n );\n\n case \"qq\":\n return (\n <>\n \n \n \n \n \n \n \n );\n\n case \"telegram\":\n return (\n <>\n \n \n \n \n \n \n \n \n \n \n \n \n \n );\n\n case \"mqtt\":\n return (\n <>\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n );\n\n case \"mattermost\":\n return (\n <>\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n );\n\n case \"voice\":\n return (\n <>\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n );\n\n case \"wecom\":\n return (\n <>\n \n \n {t(\"channels.wecomAuthHint\")}\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n );\n\n case \"xiaoyi\":\n return (\n <>\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n );\n\n default:\n return null;\n }\n };\n\n // ── Custom channel fields (key-value editor) ─────────────────────────────\n\n const renderCustomExtraFields = (\n values: Record | undefined,\n ) => {\n if (!values) return null;\n const extraKeys = Object.keys(values).filter(\n (k) => !BASE_FIELDS.includes(k),\n );\n if (extraKeys.length === 0) return null;\n\n return (\n <>\n
    Custom Fields
    \n {extraKeys.map((fieldKey) => {\n const value = values[fieldKey];\n return (\n \n {typeof value === \"boolean\" ? (\n \n ) : typeof value === \"number\" ? (\n \n ) : (\n \n )}\n \n );\n })}\n \n );\n };\n\n // ── Drawer title ─────────────────────────────────────────────────────────\n\n const drawerTitle = (\n
    \n \n {label\n ? `${label} ${t(\"channels.settings\")}`\n : t(\"channels.channelSettings\")}\n \n {activeKey &&\n CHANNEL_DOC_EN_URLS[activeKey] &&\n CHANNEL_DOC_ZH_URLS[activeKey] && (\n }\n onClick={() => {\n const url =\n CHANNEL_DOC_EN_URLS[activeKey]! ||\n CHANNEL_DOC_ZH_URLS[activeKey]!;\n const isCopawDoc = url.includes(\n \"copaw.agentscope.io/docs/channels/\",\n );\n const finalUrl =\n isCopawDoc && currentLang === \"zh\"\n ? CHANNEL_DOC_ZH_URLS[activeKey]!\n : CHANNEL_DOC_EN_URLS[activeKey]!;\n window.open(finalUrl, \"_blank\");\n }}\n className={styles.dingtalkDocBtn}\n >\n {label} Doc\n \n )}\n {activeKey === \"voice\" && (\n }\n onClick={() =>\n window.open(TWILIO_CONSOLE_URL, \"_blank\", \"noopener,noreferrer\")\n }\n className={styles.dingtalkDocBtn}\n >\n {t(\"channels.voiceSetupLink\")}\n \n )}\n
    \n );\n\n // ── Render ───────────────────────────────────────────────────────────────\n\n const drawerFooter = (\n
    \n \n \n
    \n );\n\n return (\n \n {activeKey && (\n \n \n \n \n\n {activeKey !== \"voice\" && (\n \n \n \n )}\n\n {activeKey !== \"console\" && (\n <>\n \n \n \n \n \n \n \n )}\n\n {isBuiltin\n ? renderBuiltinExtraFields(activeKey)\n : renderCustomExtraFields(initialValues)}\n\n {CHANNELS_WITH_ACCESS_CONTROL.includes(activeKey) &&\n renderAccessControlFields()}\n \n )}\n \n );\n}\n" }, { "path": "console/src/pages/Control/Channels/components/constants.ts", "content": "// Channel key type - now accepts any string for custom channels\nexport type ChannelKey = string;\n\n// Built-in channel labels\nexport const CHANNEL_LABELS: Record = {\n imessage: \"iMessage\",\n discord: \"Discord\",\n dingtalk: \"DingTalk\",\n feishu: \"Feishu\",\n qq: \"QQ\",\n telegram: \"Telegram\",\n mqtt: \"MQTT\",\n mattermost: \"Mattermost\",\n matrix: \"Matrix\",\n console: \"Console\",\n voice: \"Twilio\",\n wecom: \"WeCom\",\n xiaoyi: \"XiaoYi\",\n};\n\n// Get channel label - returns built-in label or formatted custom name\nexport function getChannelLabel(key: string): string {\n if (CHANNEL_LABELS[key]) {\n return CHANNEL_LABELS[key];\n }\n // Format custom channel name: my_channel -> My Channel\n return key\n .split(/[_-]/)\n .map((word) => word.charAt(0).toUpperCase() + word.slice(1))\n .join(\" \");\n}\n" }, { "path": "console/src/pages/Control/Channels/components/index.ts", "content": "export { ChannelCard } from \"./ChannelCard\";\nexport { ChannelDrawer } from \"./ChannelDrawer\";\nexport { useChannels } from \"../useChannels\";\nexport { CHANNEL_LABELS, getChannelLabel, type ChannelKey } from \"./constants\";\n" }, { "path": "console/src/pages/Control/Channels/index.module.less", "content": ".channelsPage {\n padding: 24px;\n}\n\n.pageHeader {\n display: flex;\n justify-content: space-between;\n align-items: flex-start;\n margin-bottom: 24px;\n}\n\n.title {\n margin-bottom: 4px;\n font-size: 24px;\n font-weight: 600;\n}\n\n.description {\n color: #999;\n font-size: 14px;\n margin: 0;\n}\n\n.filterTabs {\n display: flex;\n gap: 4px;\n padding: 4px;\n background: rgba(0, 0, 0, 0.04);\n border-radius: 10px;\n align-self: center;\n}\n\n.filterTab {\n padding: 5px 14px;\n border-radius: 7px;\n border: none;\n background: transparent;\n font-size: 13px;\n color: #666;\n cursor: pointer;\n transition: all 0.18s ease;\n\n &:hover {\n color: #333;\n background: rgba(0, 0, 0, 0.04);\n }\n}\n\n.filterTabActive {\n background: #fff;\n color: #615ced;\n font-weight: 500;\n box-shadow: 0 1px 4px rgba(0, 0, 0, 0.1);\n}\n\n.loading {\n text-align: center;\n padding: 60px;\n}\n\n.loadingText {\n color: #999;\n}\n\n.channelsGrid {\n display: grid;\n grid-template-columns: repeat(auto-fill, minmax(300px, 1fr));\n gap: 24px;\n}\n\n/* ---- Channel Card Styles ---- */\n\n.channelCard {\n border-radius: 16px;\n cursor: pointer;\n transition: all 0.2s ease-in-out;\n\n &.hover {\n border: 2px solid #615ced;\n box-shadow: 0 12px 32px rgba(97, 92, 237, 0.3);\n }\n\n &.enabled {\n border: 2px solid #615ced;\n box-shadow: 0 8px 24px rgba(97, 92, 237, 0.2);\n transform: scale(1.02);\n }\n\n &.normal {\n border: 1px solid rgba(0, 0, 0, 0.04);\n box-shadow: 0 4px 12px rgba(0, 0, 0, 0.04);\n transform: scale(1);\n }\n}\n\n.cardHeader {\n display: flex;\n justify-content: space-between;\n align-items: center;\n margin-bottom: 12px;\n}\n\n.cardHeaderRight {\n display: flex;\n align-items: center;\n gap: 8px;\n}\n\n.cardTitleRow {\n display: flex;\n align-items: center;\n gap: 6px;\n}\n\n.builtinTag {\n font-size: 10px;\n color: #615ced;\n background: rgba(97, 92, 237, 0.1);\n border-radius: 4px;\n padding: 1px 6px;\n white-space: nowrap;\n flex-shrink: 0;\n}\n\n.customTag {\n font-size: 10px;\n color: #fa8c16;\n background: rgba(250, 140, 22, 0.1);\n border: none;\n border-radius: 4px;\n padding: 1px 6px;\n margin: 0;\n white-space: nowrap;\n flex-shrink: 0;\n}\n\n.statusContainer {\n display: flex;\n align-items: center;\n justify-content: center;\n gap: 8px;\n font-size: 12px;\n color: #999;\n}\n\n.statusDot {\n width: 8px;\n height: 8px;\n border-radius: 50%;\n\n &.enabled {\n background-color: #52c41a;\n box-shadow: 0 0 0 2px rgba(82, 196, 26, 0.2);\n }\n\n &.disabled {\n background-color: #d9d9d9;\n box-shadow: none;\n }\n}\n\n.channelTag {\n font-size: 12px;\n color: #b37feb;\n padding: 2px 8px;\n border-radius: 999px;\n background: rgba(97, 92, 237, 0.08);\n}\n\n.cardTitle {\n max-width: 150px;\n font-size: 16px;\n font-weight: 600;\n overflow: hidden;\n text-overflow: ellipsis;\n white-space: nowrap;\n flex-shrink: 1;\n min-width: 0;\n}\n\n.cardDescription {\n font-size: 12px;\n color: #999;\n margin-bottom: 12px;\n}\n\n.cardFooter {\n display: flex;\n align-items: center;\n justify-content: space-between;\n margin-top: 4px;\n}\n\n.actionButton {\n padding: 0;\n height: auto;\n font-size: 12px;\n}\n\n.cardHint {\n font-size: 12px;\n color: #bbb;\n}\n\n/* ---- Channel Drawer Styles ---- */\n\n.drawerTitle {\n display: flex;\n align-items: center;\n gap: 8px;\n}\n\n.dingtalkDocBtn {\n font-size: 12px;\n padding: 0 8px;\n}\n\n.formActions {\n display: flex;\n justify-content: flex-end;\n gap: 8px;\n}\n\n.formTopActions {\n display: flex;\n justify-content: flex-end;\n gap: 8px;\n margin-bottom: 16px;\n}\n\n.drawerHeaderActions {\n display: flex;\n gap: 8px;\n align-items: center;\n}\n\n/* ─── Dark mode ─────────────────────────────────────────────────────────────── */\n:global(.dark-mode) {\n .title {\n color: rgba(255, 255, 255, 0.85);\n }\n\n .description {\n color: rgba(255, 255, 255, 0.35);\n }\n\n .filterTabs {\n background: rgba(255, 255, 255, 0.06);\n }\n\n .filterTab {\n color: rgba(255, 255, 255, 0.45);\n\n &:hover {\n color: rgba(255, 255, 255, 0.75);\n background: rgba(255, 255, 255, 0.06);\n }\n }\n\n .filterTabActive {\n background: #2a2a2a;\n color: #8b87f0;\n box-shadow: 0 1px 4px rgba(0, 0, 0, 0.4);\n }\n\n .loadingText {\n color: rgba(255, 255, 255, 0.35);\n }\n\n /* Card background and text */\n .channelCard {\n &.normal {\n border-color: rgba(255, 255, 255, 0.08);\n box-shadow: 0 4px 12px rgba(0, 0, 0, 0.3);\n }\n }\n\n .cardTitle {\n color: rgba(255, 255, 255, 0.85);\n }\n\n .statusContainer {\n color: rgba(255, 255, 255, 0.35);\n }\n\n .statusDot.disabled {\n background-color: rgba(255, 255, 255, 0.2);\n }\n\n .cardDescription {\n color: rgba(255, 255, 255, 0.35);\n }\n\n .cardHint {\n color: rgba(255, 255, 255, 0.2);\n }\n\n .drawerHeaderActions {\n .cancelBtn {\n color: rgba(255, 255, 255, 0.65);\n }\n }\n}\n" }, { "path": "console/src/pages/Control/Channels/index.tsx", "content": "import { useMemo, useState } from \"react\";\nimport { Form, message } from \"@agentscope-ai/design\";\nimport { useTranslation } from \"react-i18next\";\n\nimport api from \"../../../api\";\nimport {\n ChannelCard,\n ChannelDrawer,\n useChannels,\n getChannelLabel,\n type ChannelKey,\n} from \"./components\";\nimport styles from \"./index.module.less\";\n\ntype FilterType = \"all\" | \"builtin\" | \"custom\";\n\nfunction ChannelsPage() {\n const { t } = useTranslation();\n const { channels, orderedKeys, isBuiltin, loading, fetchChannels } =\n useChannels();\n const [filter, setFilter] = useState(\"all\");\n const [saving, setSaving] = useState(false);\n const [hoverKey, setHoverKey] = useState(null);\n const [activeKey, setActiveKey] = useState(null);\n const [drawerOpen, setDrawerOpen] = useState(false);\n // eslint-disable-next-line @typescript-eslint/no-explicit-any\n const [form] = Form.useForm();\n\n // Sort cards: enabled first, then disabled (preserve orderedKeys order within each group)\n const cards = useMemo(() => {\n const enabledCards: { key: ChannelKey; config: Record }[] =\n [];\n const disabledCards: {\n key: ChannelKey;\n config: Record;\n }[] = [];\n\n orderedKeys.forEach((key) => {\n const config = channels[key] || { enabled: false, bot_prefix: \"\" };\n const builtin = isBuiltin(key);\n if (filter === \"builtin\" && !builtin) return;\n if (filter === \"custom\" && builtin) return;\n if (config.enabled) {\n enabledCards.push({ key, config });\n } else {\n disabledCards.push({ key, config });\n }\n });\n\n return [...enabledCards, ...disabledCards];\n }, [channels, orderedKeys, filter, isBuiltin]);\n\n const handleCardClick = (key: ChannelKey) => {\n setActiveKey(key);\n setDrawerOpen(true);\n const channelConfig = channels[key] || { enabled: false, bot_prefix: \"\" };\n form.setFieldsValue({\n ...channelConfig,\n filter_tool_messages: !channelConfig.filter_tool_messages,\n filter_thinking: !channelConfig.filter_thinking,\n });\n };\n\n const handleDrawerClose = () => {\n setDrawerOpen(false);\n setActiveKey(null);\n };\n\n const handleSubmit = async (values: Record) => {\n if (!activeKey) return;\n\n // eslint-disable-next-line @typescript-eslint/no-unused-vars\n const { isBuiltin: _isBuiltin, ...savedConfig } = channels[activeKey] || {};\n const updatedChannel: Record = {\n ...savedConfig,\n ...values,\n filter_tool_messages: !values.filter_tool_messages,\n filter_thinking: !values.filter_thinking,\n };\n\n setSaving(true);\n try {\n await api.updateChannelConfig(\n activeKey,\n updatedChannel as unknown as Parameters<\n typeof api.updateChannelConfig\n >[1],\n );\n await fetchChannels();\n\n setDrawerOpen(false);\n message.success(t(\"channels.configSaved\"));\n } catch (error) {\n console.error(\"❌ Failed to update channel config:\", error);\n message.error(t(\"channels.configFailed\"));\n } finally {\n setSaving(false);\n }\n };\n\n const activeLabel = activeKey ? getChannelLabel(activeKey) : \"\";\n\n const FILTER_TABS: { key: FilterType; label: string }[] = [\n { key: \"all\", label: t(\"channels.filterAll\") },\n { key: \"builtin\", label: t(\"channels.builtin\") },\n { key: \"custom\", label: t(\"channels.custom\") },\n ];\n\n return (\n
    \n
    \n
    \n

    {t(\"channels.title\")}

    \n

    {t(\"channels.description\")}

    \n
    \n
    \n {FILTER_TABS.map(({ key, label }) => (\n setFilter(key)}\n >\n {label}\n \n ))}\n
    \n
    \n\n {loading ? (\n
    \n {t(\"channels.loading\")}\n
    \n ) : (\n
    \n {cards.map(({ key, config }) => (\n handleCardClick(key)}\n onMouseEnter={() => setHoverKey(key)}\n onMouseLeave={() => setHoverKey(null)}\n />\n ))}\n
    \n )}\n\n \n
    \n );\n}\n\nexport default ChannelsPage;\n" }, { "path": "console/src/pages/Control/Channels/useChannels.ts", "content": "import { useState, useEffect, useCallback, useMemo } from \"react\";\nimport api from \"../../../api\";\nimport { useAgentStore } from \"../../../stores/agentStore\";\n\nexport function useChannels() {\n const { selectedAgent } = useAgentStore();\n const [channels, setChannels] = useState<\n Record>\n >({});\n const [channelTypes, setChannelTypes] = useState([]);\n const [loading, setLoading] = useState(true);\n\n const fetchChannels = useCallback(async () => {\n setLoading(true);\n try {\n const [data, types] = await Promise.all([\n api.listChannels(),\n api.listChannelTypes(),\n ]);\n if (data)\n setChannels(data as unknown as Record>);\n if (types) setChannelTypes(types);\n } catch (error) {\n console.error(\"❌ Failed to load channels:\", error);\n } finally {\n setLoading(false);\n }\n }, []);\n\n useEffect(() => {\n fetchChannels();\n }, [fetchChannels, selectedAgent]);\n\n // Built-in channels come first (in a fixed order), then custom channels\n const builtinOrder = useMemo(\n () => [\n \"console\",\n \"dingtalk\",\n \"feishu\",\n \"imessage\",\n \"discord\",\n \"telegram\",\n \"qq\",\n \"matrix\",\n \"xiaoyi\",\n ],\n [],\n );\n\n const orderedKeys = useMemo(\n () => [\n ...builtinOrder.filter((k) => channelTypes.includes(k)),\n ...channelTypes.filter((k) => !builtinOrder.includes(k)),\n ],\n [builtinOrder, channelTypes],\n );\n\n // Read isBuiltin from API response\n const isBuiltin = useCallback(\n (key: string) => Boolean(channels[key]?.isBuiltin),\n [channels],\n );\n\n return {\n channels,\n channelTypes,\n orderedKeys,\n isBuiltin,\n loading,\n fetchChannels,\n };\n}\n" }, { "path": "console/src/pages/Control/CronJobs/components/JobDrawer.tsx", "content": "import {\n Drawer,\n Form,\n Input,\n InputNumber,\n Select,\n Switch,\n Button,\n Checkbox,\n} from \"@agentscope-ai/design\";\nimport { TimePicker } from \"antd\";\nimport { useTranslation } from \"react-i18next\";\nimport type { FormInstance } from \"antd\";\nimport type { CronJobSpecOutput } from \"../../../../api/types\";\nimport { TIMEZONE_OPTIONS, DEFAULT_FORM_VALUES } from \"./constants\";\nimport styles from \"../../CronJobs/index.module.less\";\n\ntype CronJob = CronJobSpecOutput;\n\ninterface JobDrawerProps {\n open: boolean;\n editingJob: CronJob | null;\n form: FormInstance;\n saving: boolean;\n onClose: () => void;\n onSubmit: (values: CronJob) => void;\n}\n\nexport function JobDrawer({\n open,\n editingJob,\n form,\n saving,\n onClose,\n onSubmit,\n}: JobDrawerProps) {\n const { t } = useTranslation();\n\n return (\n \n \n \n \n }\n >\n \n \n \n \n\n \n \n \n\n \n \n \n\n \n\n \n \n \n \n \n\n prev.cronType !== cur.cronType}\n >\n {({ getFieldValue }) => {\n const cronType = getFieldValue(\"cronType\");\n\n if (cronType === \"daily\" || cronType === \"weekly\") {\n return (\n \n \n \n );\n }\n return null;\n }}\n \n\n prev.cronType !== cur.cronType}\n >\n {({ getFieldValue }) => {\n const cronType = getFieldValue(\"cronType\");\n\n if (cronType === \"weekly\") {\n return (\n \n \n \n );\n }\n return null;\n }}\n \n\n prev.cronType !== cur.cronType}\n >\n {({ getFieldValue }) => {\n const cronType = getFieldValue(\"cronType\");\n\n if (cronType === \"custom\") {\n return (\n \n
    \n {t(\"cronJobs.cronExample\")}\n
    \n
    \n {t(\"cronJobs.cronHelper\")}{\" \"}\n \n {t(\"cronJobs.cronHelperLink\")} →\n \n
    \n \n }\n >\n \n \n );\n }\n return null;\n }}\n \n\n \n\n \n \n (option?.label?.toString() || \"\")\n .toLowerCase()\n .includes(input.toLowerCase())\n }\n options={TIMEZONE_OPTIONS}\n />\n \n\n \n \n \n\n \n \n \n\n {\n if (!value) return Promise.resolve();\n try {\n JSON.parse(value);\n return Promise.resolve();\n } catch {\n return Promise.reject(\n new Error(t(\"cronJobs.invalidJsonFormat\")),\n );\n }\n },\n },\n ]}\n tooltip={t(\"cronJobs.requestInputTooltip\")}\n extra={\n \n {t(\"cronJobs.requestInputExample\")}\n \n }\n >\n \n \n\n \n \n \n\n \n \n \n\n \n\n \n \n \n\n \n \n \n\n \n \n \n\n \n \n \n\n \n \n \n\n \n \n \n\n \n \n \n \n \n );\n}\n" }, { "path": "console/src/pages/Control/CronJobs/components/columns.tsx", "content": "import { Button, Tooltip, Dropdown } from \"@agentscope-ai/design\";\nimport type { ColumnsType } from \"antd/es/table\";\nimport type { MenuProps } from \"antd\";\nimport type { CronJobSpecOutput } from \"../../../../api/types\";\nimport { CopyOutlined, MoreOutlined } from \"@ant-design/icons\";\nimport { message } from \"antd\";\nimport { TFunction } from \"i18next\";\nimport { parseCron } from \"./parseCron\";\n\ntype CronJob = CronJobSpecOutput;\n\ninterface ColumnHandlers {\n onToggleEnabled: (job: CronJob) => void;\n onExecuteNow: (job: CronJob) => void;\n onEdit: (job: CronJob) => void;\n onDelete: (jobId: string) => void;\n t: TFunction;\n}\n\nconst createCopyToClipboard = (t: TFunction) => async (text: string) => {\n try {\n if (navigator.clipboard && window.isSecureContext) {\n await navigator.clipboard.writeText(text);\n message.success(t(\"common.copied\"));\n } else {\n const textArea = document.createElement(\"textarea\");\n textArea.value = text;\n textArea.style.position = \"fixed\";\n textArea.style.left = \"-999999px\";\n textArea.style.top = \"-999999px\";\n document.body.appendChild(textArea);\n textArea.focus();\n textArea.select();\n document.execCommand(\"copy\");\n textArea.remove();\n message.success(t(\"common.copied\"));\n }\n } catch (err) {\n console.error(\"Failed to copy text: \", err);\n message.error(t(\"common.copyFailed\"));\n }\n};\n\nexport const createColumns = (\n handlers: ColumnHandlers,\n): ColumnsType => {\n const copyToClipboard = createCopyToClipboard(handlers.t);\n\n return [\n {\n title: handlers.t(\"cronJobs.id\"),\n dataIndex: \"id\",\n key: \"id\",\n width: 250,\n fixed: \"left\",\n },\n {\n title: handlers.t(\"cronJobs.name\"),\n dataIndex: \"name\",\n key: \"name\",\n width: 250,\n },\n {\n title: handlers.t(\"cronJobs.enabled\"),\n dataIndex: \"enabled\",\n key: \"enabled\",\n width: 100,\n render: (enabled: boolean) => (\n \n \n {enabled\n ? handlers.t(\"common.enabled\")\n : handlers.t(\"common.disabled\")}\n \n ),\n },\n {\n title: handlers.t(\"cronJobs.scheduleType\"),\n dataIndex: [\"schedule\", \"type\"],\n key: \"schedule_type\",\n width: 140,\n render: () => \"cron\",\n },\n {\n title: handlers.t(\"cronJobs.scheduleCron\"),\n dataIndex: [\"schedule\", \"cron\"],\n key: \"cron\",\n width: 180,\n render: (cron: string) => {\n // Parse cron to friendly text\n const cronParts = parseCron(cron || \"0 9 * * *\");\n let displayText = \"\";\n\n switch (cronParts.type) {\n case \"hourly\":\n displayText = handlers.t(\"cronJobs.cronTypeHourly\");\n break;\n case \"daily\":\n displayText = `${handlers.t(\"cronJobs.cronTypeDaily\")} ${String(\n cronParts.hour,\n ).padStart(2, \"0\")}:${String(cronParts.minute).padStart(2, \"0\")}`;\n break;\n case \"weekly\": {\n const dayNames = (cronParts.daysOfWeek || [])\n .map((d) => {\n const dayMap: Record = {\n mon: handlers.t(\"cronJobs.cronDayMon\"),\n tue: handlers.t(\"cronJobs.cronDayTue\"),\n wed: handlers.t(\"cronJobs.cronDayWed\"),\n thu: handlers.t(\"cronJobs.cronDayThu\"),\n fri: handlers.t(\"cronJobs.cronDayFri\"),\n sat: handlers.t(\"cronJobs.cronDaySat\"),\n sun: handlers.t(\"cronJobs.cronDaySun\"),\n };\n return dayMap[d] || d;\n })\n .join(\",\");\n displayText = `${handlers.t(\n \"cronJobs.cronTypeWeekly\",\n )} ${dayNames} ${String(cronParts.hour).padStart(2, \"0\")}:${String(\n cronParts.minute,\n ).padStart(2, \"0\")}`;\n break;\n }\n case \"custom\":\n displayText = cron;\n break;\n }\n\n return (\n \n
    Cron 表达式: {cron}
    \n
    \n 格式: 分钟 小时 日 月 星期\n
    \n \n }\n >\n {displayText}\n \n );\n },\n },\n {\n title: handlers.t(\"cronJobs.scheduleTimezone\"),\n dataIndex: [\"schedule\", \"timezone\"],\n key: \"timezone\",\n width: 170,\n },\n {\n title: \"TaskType\",\n dataIndex: \"task_type\",\n key: \"task_type\",\n width: 140,\n },\n {\n title: handlers.t(\"cronJobs.taskText\"),\n dataIndex: \"text\",\n key: \"text\",\n width: 200,\n ellipsis: {\n showTitle: true,\n },\n render: (text: string) => {\n if (!text) return \"-\";\n return (\n \n {text}\n \n );\n },\n },\n {\n title: \"RequestInput\",\n dataIndex: [\"request\", \"input\"],\n key: \"request_input\",\n width: 350,\n ellipsis: true,\n render: (input: unknown) => {\n if (!input) return \"-\";\n\n let displayText: string;\n let fullText: string;\n\n try {\n fullText = JSON.stringify(input, null, 2);\n displayText = JSON.stringify(input);\n } catch {\n fullText = String(input);\n displayText = fullText;\n }\n\n if (displayText.length <= 50) {\n return {displayText};\n }\n\n const truncatedText =\n displayText.length > 50\n ? displayText.substring(0, 50) + \"...\"\n : displayText;\n\n return (\n \n \n {fullText}\n \n }\n size=\"small\"\n onClick={(e) => {\n e.stopPropagation();\n copyToClipboard(fullText);\n }}\n style={{\n position: \"absolute\",\n top: 0,\n right: 0,\n color: \"#1890ff\",\n zIndex: 10,\n }}\n />\n \n }\n placement=\"topLeft\"\n overlayInnerStyle={{ maxWidth: 400 }}\n >\n \n {truncatedText}\n \n \n );\n },\n },\n {\n title: \"RequestSessionID\",\n dataIndex: [\"request\", \"session_id\"],\n key: \"session_id\",\n width: 160,\n },\n {\n title: \"RequestUserID\",\n dataIndex: [\"request\", \"user_id\"],\n key: \"user_id\",\n width: 140,\n },\n {\n title: \"DispatchType\",\n dataIndex: [\"dispatch\", \"type\"],\n key: \"dispatch_type\",\n width: 140,\n },\n {\n title: \"DispatchChannel\",\n dataIndex: [\"dispatch\", \"channel\"],\n key: \"channel\",\n width: 150,\n },\n {\n title: \"DispatchTargetUserID\",\n dataIndex: [\"dispatch\", \"target\", \"user_id\"],\n key: \"target_user_id\",\n width: 190,\n },\n {\n title: \"DispatchTargetSessionID\",\n dataIndex: [\"dispatch\", \"target\", \"session_id\"],\n key: \"target_session_id\",\n width: 210,\n },\n {\n title: \"DispatchMode\",\n dataIndex: [\"dispatch\", \"mode\"],\n key: \"mode\",\n width: 140,\n },\n {\n title: \"RuntimeMaxConcurrency\",\n dataIndex: [\"runtime\", \"max_concurrency\"],\n key: \"max_concurrency\",\n width: 210,\n },\n {\n title: \"RuntimeTimeoutSeconds\",\n dataIndex: [\"runtime\", \"timeout_seconds\"],\n key: \"timeout_seconds\",\n width: 210,\n },\n {\n title: \"RuntimeMisfireGraceSeconds\",\n dataIndex: [\"runtime\", \"misfire_grace_seconds\"],\n key: \"misfire_grace_seconds\",\n width: 240,\n },\n {\n title: handlers.t(\"cronJobs.action\"),\n key: \"action\",\n width: 240,\n fixed: \"right\",\n render: (_: unknown, record: CronJob) => {\n const menuItems: MenuProps[\"items\"] = [\n {\n key: \"edit\",\n label: handlers.t(\"cronJobs.edit\"),\n disabled: record.enabled,\n onClick: () => handlers.onEdit(record),\n },\n {\n key: \"delete\",\n label: handlers.t(\"cronJobs.delete\"),\n disabled: record.enabled,\n danger: true,\n onClick: () => handlers.onDelete(record.id),\n },\n ];\n\n return (\n
    \n handlers.onToggleEnabled(record)}\n >\n {record.enabled\n ? handlers.t(\"cronJobs.disable\")\n : handlers.t(\"common.enable\")}\n \n handlers.onExecuteNow(record)}\n >\n {handlers.t(\"cronJobs.executeNow\")}\n \n \n
    \n );\n },\n },\n ];\n};\n" }, { "path": "console/src/pages/Control/CronJobs/components/constants.ts", "content": "import dayjs from \"dayjs\";\n\nexport { TIMEZONE_OPTIONS } from \"../../../../constants/timezone\";\n\nexport const DEFAULT_FORM_VALUES = {\n enabled: false,\n schedule: {\n type: \"cron\" as const,\n cron: \"0 9 * * *\",\n timezone: \"UTC\",\n },\n cronType: \"daily\",\n cronTime: dayjs().hour(9).minute(0),\n task_type: \"agent\" as const,\n dispatch: {\n type: \"channel\" as const,\n channel: \"console\",\n target: {\n user_id: \"\",\n session_id: \"\",\n },\n mode: \"final\" as const,\n },\n runtime: {\n max_concurrency: 1,\n timeout_seconds: 120,\n misfire_grace_seconds: 60,\n },\n};\n" }, { "path": "console/src/pages/Control/CronJobs/components/index.ts", "content": "export { createColumns } from \"./columns\";\nexport { JobDrawer } from \"./JobDrawer\";\nexport { useCronJobs } from \"../useCronJobs\";\nexport { TIMEZONE_OPTIONS, DEFAULT_FORM_VALUES } from \"./constants\";\n" }, { "path": "console/src/pages/Control/CronJobs/components/parseCron.ts", "content": "/**\n * Parse cron expression to form-friendly format and vice versa.\n * Supports: hourly, daily, weekly, custom\n *\n * Day-of-week values use three-letter English abbreviations\n * (mon, tue, wed, thu, fri, sat, sun) to avoid the numbering\n * mismatch between crontab (0=Sun) and APScheduler v3 (0=Mon).\n */\n\nexport type CronType = \"hourly\" | \"daily\" | \"weekly\" | \"custom\";\n\nexport interface CronParts {\n type: CronType;\n hour?: number;\n minute?: number;\n daysOfWeek?: string[]; // \"mon\", \"tue\", …, \"sun\"\n rawCron?: string;\n}\n\nconst CRON_RE = /^(\\S+)\\s+(\\S+)\\s+(\\S+)\\s+(\\S+)\\s+(\\S+)$/;\nconst INTEGER_RE = /^\\d+$/;\n\n/**\n * Mapping from crontab numeric day to three-letter abbreviation.\n * Supports both crontab (0=Sun) and the common 7=Sun alias.\n */\nconst ORDERED_DAYS = [\"mon\", \"tue\", \"wed\", \"thu\", \"fri\", \"sat\", \"sun\"] as const;\ntype DayName = (typeof ORDERED_DAYS)[number];\n\nconst NUM_TO_NAME: Record = {\n \"0\": \"sun\",\n \"1\": \"mon\",\n \"2\": \"tue\",\n \"3\": \"wed\",\n \"4\": \"thu\",\n \"5\": \"fri\",\n \"6\": \"sat\",\n \"7\": \"sun\",\n};\n\nconst VALID_NAMES = new Set(ORDERED_DAYS);\n\nfunction isDayName(value: string): value is DayName {\n return VALID_NAMES.has(value as DayName);\n}\n\n/**\n * Parse cron expression to CronParts\n * Examples:\n * \"0 * * * *\" -> hourly\n * \"0 9 * * *\" -> daily at 09:00\n * \"0 9 * * mon,wed,fri\" -> weekly on Mon/Wed/Fri at 09:00\n * \"* /15 * * * *\" -> custom (every 15 minutes)\n */\nexport function parseCron(cron: string): CronParts {\n const trimmed = (cron || \"\").trim();\n if (!trimmed) {\n return { type: \"daily\", hour: 9, minute: 0 };\n }\n\n const match = trimmed.match(CRON_RE);\n if (!match) {\n return { type: \"custom\", rawCron: trimmed };\n }\n\n const [, minute, hour, dayOfMonth, month, dayOfWeek] = match;\n\n // Hourly: \"0 * * * *\"\n if (\n hour === \"*\" &&\n dayOfMonth === \"*\" &&\n month === \"*\" &&\n dayOfWeek === \"*\" &&\n minute === \"0\"\n ) {\n return { type: \"hourly\", minute: 0 };\n }\n\n // Daily: \"M H * * *\"\n if (dayOfMonth === \"*\" && month === \"*\" && dayOfWeek === \"*\") {\n const h = parsePlainCronNumber(hour, 0, 23);\n const m = parsePlainCronNumber(minute, 0, 59);\n if (h !== null && m !== null) {\n return { type: \"daily\", hour: h, minute: m };\n }\n }\n\n // Weekly: \"M H * * D\" where D is days\n if (dayOfMonth === \"*\" && month === \"*\" && dayOfWeek !== \"*\") {\n const h = parsePlainCronNumber(hour, 0, 23);\n const m = parsePlainCronNumber(minute, 0, 59);\n if (h !== null && m !== null) {\n const days = parseDaysOfWeek(dayOfWeek);\n if (days.length > 0) {\n return { type: \"weekly\", hour: h, minute: m, daysOfWeek: days };\n }\n }\n }\n\n // Everything else is custom\n return { type: \"custom\", rawCron: trimmed };\n}\n\nfunction parsePlainCronNumber(\n value: string,\n min: number,\n max: number,\n): number | null {\n if (!INTEGER_RE.test(value)) {\n return null;\n }\n\n const parsed = Number(value);\n if (parsed < min || parsed > max) {\n return null;\n }\n\n return parsed;\n}\n\n/**\n * Serialize CronParts back to cron expression\n */\nexport function serializeCron(parts: CronParts): string {\n switch (parts.type) {\n case \"hourly\":\n return \"0 * * * *\";\n\n case \"daily\": {\n const h = parts.hour ?? 9;\n const m = parts.minute ?? 0;\n return `${m} ${h} * * *`;\n }\n\n case \"weekly\": {\n const h = parts.hour ?? 9;\n const m = parts.minute ?? 0;\n const days = serializeDaysOfWeek(parts.daysOfWeek);\n return `${m} ${h} * * ${days}`;\n }\n\n case \"custom\":\n return parts.rawCron || \"0 9 * * *\";\n\n default:\n return \"0 9 * * *\";\n }\n}\n\n/**\n * Parse day of week field to string abbreviations.\n *\n * Accepts both numeric (crontab convention: 0=Sun … 6=Sat) and\n * named values (mon, tue, …). Always returns abbreviation strings.\n * Invalid or lossy tokens return an empty array so callers can\n * fall back to `custom`.\n */\nfunction parseDaysOfWeek(dayOfWeek: string): string[] {\n const days: DayName[] = [];\n const parts = dayOfWeek.split(\",\");\n\n for (const part of parts) {\n const trimmed = part.trim().toLowerCase();\n\n if (!trimmed) {\n return [];\n }\n\n if (isDayName(trimmed)) {\n if (!days.includes(trimmed)) {\n days.push(trimmed);\n }\n continue;\n }\n\n if (trimmed.includes(\"-\")) {\n const rangeParts = trimmed.split(\"-\");\n if (\n rangeParts.length !== 2 ||\n rangeParts[0] === \"\" ||\n rangeParts[1] === \"\"\n ) {\n return [];\n }\n\n const [startStr, endStr] = rangeParts;\n const startName = NUM_TO_NAME[startStr] || startStr;\n const endName = NUM_TO_NAME[endStr] || endStr;\n\n if (!isDayName(startName) || !isDayName(endName)) {\n return [];\n }\n\n const si = ORDERED_DAYS.indexOf(startName);\n const ei = ORDERED_DAYS.indexOf(endName);\n if (si === -1 || ei === -1 || si > ei) {\n return [];\n }\n\n for (let i = si; i <= ei; i++) {\n if (!days.includes(ORDERED_DAYS[i])) {\n days.push(ORDERED_DAYS[i]);\n }\n }\n continue;\n }\n\n const name = NUM_TO_NAME[trimmed];\n if (!name) {\n return [];\n }\n\n if (!days.includes(name)) {\n days.push(name);\n }\n }\n\n return days;\n}\n\nfunction serializeDaysOfWeek(daysOfWeek?: string[]): string {\n if (!daysOfWeek || daysOfWeek.length === 0) {\n return \"mon\";\n }\n\n const selectedDays = ORDERED_DAYS.filter((day) => daysOfWeek.includes(day));\n if (selectedDays.length === 0) {\n return \"mon\";\n }\n\n const segments: string[] = [];\n let rangeStart = selectedDays[0];\n let previousDay = selectedDays[0];\n\n for (let i = 1; i <= selectedDays.length; i++) {\n const currentDay = selectedDays[i];\n const isContiguous =\n currentDay !== undefined &&\n ORDERED_DAYS.indexOf(currentDay) ===\n ORDERED_DAYS.indexOf(previousDay) + 1;\n\n if (isContiguous) {\n previousDay = currentDay;\n continue;\n }\n\n if (rangeStart === previousDay) {\n segments.push(rangeStart);\n } else {\n segments.push(`${rangeStart}-${previousDay}`);\n }\n\n rangeStart = currentDay;\n previousDay = currentDay ?? previousDay;\n }\n\n return segments.join(\",\");\n}\n" }, { "path": "console/src/pages/Control/CronJobs/index.module.less", "content": ".cronJobsPage {\n padding: 24px;\n}\n\n.header {\n display: flex;\n justify-content: space-between;\n align-items: center;\n margin-bottom: 16px;\n}\n\n.headerInfo {\n display: flex;\n flex-direction: column;\n}\n\n.title {\n margin-bottom: 4px;\n font-size: 24px;\n font-weight: 600;\n}\n\n.description {\n margin: 0;\n color: #999;\n font-size: 14px;\n}\n\n.tableCard {\n :global(.ant-card-body) {\n padding: 0;\n }\n}\n\n.formActions {\n display: flex;\n justify-content: flex-end;\n gap: 8px;\n}\n\n/* ─── Dark mode ─────────────────────────────────────────────────────────────── */\n:global(.dark-mode) {\n .title {\n color: rgba(255, 255, 255, 0.85);\n }\n\n .description {\n color: rgba(255, 255, 255, 0.35);\n }\n}\n" }, { "path": "console/src/pages/Control/CronJobs/index.tsx", "content": "import { useState, useEffect, useRef } from \"react\";\nimport { Button, Card, Form, Modal, Table } from \"@agentscope-ai/design\";\nimport dayjs from \"dayjs\";\nimport type { CronJobSpecOutput } from \"../../../api/types\";\nimport { useTranslation } from \"react-i18next\";\nimport api from \"../../../api\";\nimport {\n createColumns,\n JobDrawer,\n useCronJobs,\n DEFAULT_FORM_VALUES,\n} from \"./components\";\nimport { parseCron, serializeCron } from \"./components/parseCron\";\nimport styles from \"./index.module.less\";\n\ntype CronJob = CronJobSpecOutput;\n\nfunction CronJobsPage() {\n const { t } = useTranslation();\n const {\n jobs,\n loading,\n createJob,\n updateJob,\n deleteJob,\n toggleEnabled,\n executeNow,\n } = useCronJobs();\n const [drawerOpen, setDrawerOpen] = useState(false);\n const [editingJob, setEditingJob] = useState(null);\n const [saving, setSaving] = useState(false);\n const [form] = Form.useForm();\n const userTimezoneRef = useRef(\"UTC\");\n\n useEffect(() => {\n api\n .getUserTimezone()\n .then((res) => {\n if (res.timezone) userTimezoneRef.current = res.timezone;\n })\n .catch((err) => console.error(\"Failed to fetch user timezone:\", err));\n }, []);\n\n const handleCreate = () => {\n setEditingJob(null);\n form.resetFields();\n form.setFieldsValue({\n ...DEFAULT_FORM_VALUES,\n schedule: {\n ...DEFAULT_FORM_VALUES.schedule,\n timezone: userTimezoneRef.current,\n },\n });\n setDrawerOpen(true);\n };\n\n const handleEdit = (job: CronJob) => {\n setEditingJob(job);\n\n // Parse cron expression to form fields\n const cronParts = parseCron(job.schedule?.cron || \"0 9 * * *\");\n\n const formValues: any = {\n ...job,\n request: {\n ...job.request,\n input: job.request?.input\n ? JSON.stringify(job.request.input, null, 2)\n : \"\",\n },\n cronType: cronParts.type,\n };\n\n // Set time picker value\n if (cronParts.type === \"daily\" || cronParts.type === \"weekly\") {\n const h = cronParts.hour ?? 9;\n const m = cronParts.minute ?? 0;\n formValues.cronTime = dayjs().hour(h).minute(m);\n }\n\n // Set days of week\n if (cronParts.type === \"weekly\" && cronParts.daysOfWeek) {\n formValues.cronDaysOfWeek = cronParts.daysOfWeek;\n }\n\n // Set custom cron\n if (cronParts.type === \"custom\" && cronParts.rawCron) {\n formValues.cronCustom = cronParts.rawCron;\n }\n\n form.setFieldsValue(formValues);\n setDrawerOpen(true);\n };\n\n const handleDelete = (jobId: string) => {\n Modal.confirm({\n title: t(\"cronJobs.confirmDelete\"),\n content: t(\"cronJobs.deleteConfirm\"),\n okText: t(\"cronJobs.deleteText\"),\n okType: \"primary\",\n cancelText: t(\"cronJobs.cancelText\"),\n onOk: async () => {\n await deleteJob(jobId);\n },\n });\n };\n\n const handleToggleEnabled = async (job: CronJob) => {\n await toggleEnabled(job);\n };\n\n const handleExecuteNow = async (job: CronJob) => {\n Modal.confirm({\n title: t(\"cronJobs.executeNowTitle\"),\n content: t(\"cronJobs.executeNowContent\", { name: job.name }),\n okText: t(\"cronJobs.executeNowConfirm\"),\n okType: \"primary\",\n cancelText: t(\"cronJobs.cancelText\"),\n onOk: async () => {\n await executeNow(job.id);\n },\n });\n };\n\n const handleDrawerClose = () => {\n setDrawerOpen(false);\n setEditingJob(null);\n };\n\n const handleSubmit = async (values: any) => {\n // Serialize cron from form fields\n const cronParts: any = {\n type: values.cronType || \"daily\",\n };\n\n if (values.cronType === \"daily\" || values.cronType === \"weekly\") {\n if (values.cronTime) {\n cronParts.hour = values.cronTime.hour();\n cronParts.minute = values.cronTime.minute();\n }\n }\n\n if (values.cronType === \"weekly\" && values.cronDaysOfWeek) {\n cronParts.daysOfWeek = values.cronDaysOfWeek;\n }\n\n if (values.cronType === \"custom\" && values.cronCustom) {\n cronParts.rawCron = values.cronCustom;\n }\n\n const cronExpression = serializeCron(cronParts);\n\n let processedValues = {\n ...values,\n schedule: {\n ...values.schedule,\n cron: cronExpression,\n },\n };\n\n // Parse request input JSON\n if (values.request?.input && typeof values.request.input === \"string\") {\n try {\n processedValues = {\n ...processedValues,\n request: {\n ...values.request,\n input: JSON.parse(values.request.input as any),\n },\n };\n } catch (error) {\n console.error(\"❌ Failed to parse request.input JSON:\", error);\n }\n }\n\n let success = false;\n setSaving(true);\n try {\n if (editingJob) {\n success = await updateJob(editingJob.id, processedValues);\n } else {\n success = await createJob(processedValues);\n }\n } finally {\n setSaving(false);\n }\n if (success) {\n setDrawerOpen(false);\n }\n };\n\n const columns = createColumns({\n onToggleEnabled: handleToggleEnabled,\n onExecuteNow: handleExecuteNow,\n onEdit: handleEdit,\n onDelete: handleDelete,\n t,\n });\n\n return (\n
    \n
    \n
    \n

    {t(\"cronJobs.title\")}

    \n

    {t(\"cronJobs.description\")}

    \n
    \n \n
    \n\n \n t(\"cronJobs.totalItems\", { count: total }),\n }}\n />\n \n\n \n
    \n );\n}\n\nexport default CronJobsPage;\n" }, { "path": "console/src/pages/Control/CronJobs/useCronJobs.ts", "content": "import { useState, useEffect } from \"react\";\nimport { message } from \"@agentscope-ai/design\";\nimport api from \"../../../api\";\nimport type { CronJobSpecOutput } from \"../../../api/types\";\nimport { useAgentStore } from \"../../../stores/agentStore\";\n\ntype CronJob = CronJobSpecOutput;\n\nexport function useCronJobs() {\n const { selectedAgent } = useAgentStore();\n const [jobs, setJobs] = useState([]);\n const [loading, setLoading] = useState(false);\n\n const fetchJobs = async () => {\n setLoading(true);\n try {\n const data = await api.listCronJobs();\n if (data) {\n setJobs(data as CronJob[]);\n }\n } catch (error) {\n console.error(\"Failed to load cron jobs\", error);\n message.error(\"Failed to load Cron Jobs\");\n } finally {\n setLoading(false);\n }\n };\n\n useEffect(() => {\n let mounted = true;\n\n const loadJobs = async () => {\n await fetchJobs();\n };\n\n if (mounted) {\n loadJobs();\n }\n\n return () => {\n mounted = false;\n };\n }, [selectedAgent]);\n\n const createJob = async (values: CronJob) => {\n try {\n const created = await api.createCronJob(values);\n setJobs((prev) => [created as CronJob, ...prev]);\n message.success(\"Created successfully\");\n return true;\n } catch (error) {\n console.error(\"Failed to create cron job\", error);\n message.error(\"Failed to save\");\n return false;\n }\n };\n\n const updateJob = async (jobId: string, values: CronJob) => {\n const original = jobs.find((j) => j.id === jobId);\n const optimisticUpdate = { ...original, ...values };\n setJobs((prev) => prev.map((j) => (j.id === jobId ? optimisticUpdate : j)));\n\n try {\n const updated = await api.replaceCronJob(jobId, values);\n setJobs((prev) =>\n prev.map((j) => (j.id === jobId ? (updated as CronJob) : j)),\n );\n message.success(\"Updated successfully\");\n return true;\n } catch (error) {\n console.error(\"Failed to update cron job\", error);\n if (original) {\n setJobs((prev) => prev.map((j) => (j.id === jobId ? original : j)));\n }\n message.error(\"Failed to save\");\n return false;\n }\n };\n\n const deleteJob = async (jobId: string) => {\n const original = jobs.find((j) => j.id === jobId);\n setJobs((prev) => prev.filter((j) => j.id !== jobId));\n\n try {\n await api.deleteCronJob(jobId);\n message.success(\"Deleted successfully\");\n return true;\n } catch (error) {\n console.error(\"Failed to delete cron job\", error);\n if (original) {\n setJobs((prev) => [...prev, original]);\n }\n message.error(\"Failed to delete\");\n return false;\n }\n };\n\n const toggleEnabled = async (job: CronJob) => {\n const updated = { ...job, enabled: !job.enabled };\n setJobs((prev) => prev.map((j) => (j.id === job.id ? updated : j)));\n\n try {\n const returned = await api.replaceCronJob(job.id, updated);\n setJobs((prev) =>\n prev.map((j) => (j.id === job.id ? (returned as CronJob) : j)),\n );\n message.success(`${updated.enabled ? \"Enabled\" : \"Disabled\"}`);\n return true;\n } catch (error) {\n console.error(\"Failed to toggle cron job\", error);\n setJobs((prev) => prev.map((j) => (j.id === job.id ? job : j)));\n message.error(\"Operation failed\");\n return false;\n }\n };\n\n const executeNow = async (jobId: string) => {\n try {\n await api.triggerCronJob(jobId);\n message.success(\"Task triggered successfully\");\n return true;\n } catch (error) {\n console.error(\"Failed to execute cron job\", error);\n message.error(\"Failed to execute\");\n return false;\n }\n };\n\n return {\n jobs,\n loading,\n createJob,\n updateJob,\n deleteJob,\n toggleEnabled,\n executeNow,\n };\n}\n" }, { "path": "console/src/pages/Control/Heartbeat/index.module.less", "content": ".heartbeatPage {\n padding: 24px;\n}\n\n.title {\n margin-bottom: 4px;\n font-size: 24px;\n font-weight: 600;\n}\n\n.description {\n margin: 0 0 24px;\n color: #999;\n font-size: 14px;\n}\n\n.card {\n max-width: 560px;\n}\n\n.everyField {\n :global(.ant-form-item-control-input-content) {\n display: block;\n }\n}\n\n.everyRow {\n display: flex;\n gap: 12px;\n align-items: center;\n}\n\n.everyNumber {\n width: 120px;\n}\n\n.everyUnit {\n min-width: 100px;\n}\n\n.formActions {\n display: flex;\n justify-content: flex-end;\n gap: 8px;\n margin-top: 16px;\n}\n\n.activeHoursRow {\n display: flex;\n gap: 16px;\n align-items: flex-start;\n}\n\n.activeHoursRow :global(.ant-form-item) {\n flex: 1;\n margin-bottom: 0;\n}\n\n/* ─── Dark mode ─────────────────────────────────────────────────────────────── */\n:global(.dark-mode) {\n .title {\n color: rgba(255, 255, 255, 0.85);\n }\n\n .description {\n color: rgba(255, 255, 255, 0.35);\n }\n}\n" }, { "path": "console/src/pages/Control/Heartbeat/index.tsx", "content": "import { useEffect, useState } from \"react\";\nimport {\n Button,\n Card,\n Form,\n InputNumber,\n message,\n Select,\n Switch,\n} from \"@agentscope-ai/design\";\nimport { TimePicker } from \"antd\";\nimport dayjs from \"dayjs\";\nimport customParseFormat from \"dayjs/plugin/customParseFormat\";\nimport { useTranslation } from \"react-i18next\";\nimport api from \"../../../api\";\nimport { useAgentStore } from \"../../../stores/agentStore\";\nimport type { HeartbeatConfig } from \"../../../api/types/heartbeat\";\nimport { parseEvery, serializeEvery, type EveryUnit } from \"./parseEvery\";\nimport styles from \"./index.module.less\";\n\ndayjs.extend(customParseFormat);\n\nconst TIME_FORMAT = \"HH:mm\";\n\n/** TimePicker that uses \"HH:mm\" string as value for Form. */\nfunction TimePickerHHmm({\n value,\n onChange,\n}: {\n value?: string | null;\n onChange?: (s: string) => void;\n}) {\n const strVal =\n typeof value === \"string\" ? value : Array.isArray(value) ? value[0] : null;\n return (\n {\n const s = typeof str === \"string\" ? str : str?.[0];\n if (s) onChange?.(s);\n }}\n minuteStep={15}\n needConfirm={false}\n style={{ width: \"100%\" }}\n />\n );\n}\n\n/** Form values: API shape plus flattened fields for interval and time. */\ntype HeartbeatFormValues = Omit & {\n every?: string;\n everyNumber?: number;\n everyUnit?: EveryUnit;\n useActiveHours?: boolean;\n activeHoursStart?: string;\n activeHoursEnd?: string;\n};\n\nconst TARGET_OPTIONS = [\n { value: \"main\", labelKey: \"heartbeat.targetMain\" },\n { value: \"last\", labelKey: \"heartbeat.targetLast\" },\n];\n\nconst EVERY_UNIT_OPTIONS: { value: EveryUnit; labelKey: string }[] = [\n { value: \"m\", labelKey: \"heartbeat.unitMinutes\" },\n { value: \"h\", labelKey: \"heartbeat.unitHours\" },\n];\n\nfunction HeartbeatPage() {\n const { t } = useTranslation();\n const { selectedAgent } = useAgentStore();\n const [loading, setLoading] = useState(true);\n const [saving, setSaving] = useState(false);\n const [form] = Form.useForm();\n\n const fetchConfig = async () => {\n setLoading(true);\n try {\n const data = await api.getHeartbeatConfig();\n const everyParts = parseEvery(data.every ?? \"6h\");\n form.setFieldsValue({\n enabled: data.enabled ?? false,\n everyNumber: everyParts.number,\n everyUnit: everyParts.unit,\n target: data.target ?? \"main\",\n useActiveHours: !!data.activeHours,\n activeHoursStart: data.activeHours?.start ?? \"08:00\",\n activeHoursEnd: data.activeHours?.end ?? \"22:00\",\n });\n } catch (e) {\n console.error(\"Failed to load heartbeat config:\", e);\n message.error(t(\"heartbeat.loadFailed\"));\n } finally {\n setLoading(false);\n }\n };\n\n useEffect(() => {\n fetchConfig();\n // eslint-disable-next-line react-hooks/exhaustive-deps\n }, [selectedAgent]);\n\n const onFinish = async (values: HeartbeatFormValues) => {\n const every =\n values.everyNumber != null && values.everyUnit\n ? serializeEvery({\n number: values.everyNumber,\n unit: values.everyUnit,\n })\n : \"6h\";\n const body: HeartbeatConfig = {\n enabled: values.enabled ?? false,\n every,\n target: values.target ?? \"main\",\n activeHours:\n values.useActiveHours &&\n values.activeHoursStart &&\n values.activeHoursEnd\n ? {\n start: values.activeHoursStart,\n end: values.activeHoursEnd,\n }\n : undefined,\n };\n setSaving(true);\n try {\n await api.updateHeartbeatConfig(body);\n message.success(t(\"heartbeat.saveSuccess\"));\n } catch (e) {\n console.error(\"Failed to save heartbeat config:\", e);\n message.error(t(\"heartbeat.saveFailed\"));\n } finally {\n setSaving(false);\n }\n };\n\n if (loading) {\n return (\n
    \n

    {t(\"heartbeat.title\")}

    \n

    {t(\"heartbeat.description\")}

    \n {t(\"common.loading\")}\n
    \n );\n }\n\n return (\n
    \n

    {t(\"heartbeat.title\")}

    \n

    {t(\"heartbeat.description\")}

    \n\n \n \n \n \n \n\n \n
    \n \n \n \n \n ({\n value: opt.value,\n label: t(opt.labelKey),\n }))}\n className={styles.everyUnit}\n />\n \n
    \n \n\n \n ({\n value: opt.value,\n label: t(opt.labelKey),\n }))}\n />\n \n\n \n \n \n\n \n prev.useActiveHours !== cur.useActiveHours\n }\n >\n {({ getFieldValue }) =>\n getFieldValue(\"useActiveHours\") ? (\n
    \n \n \n \n \n \n \n
    \n ) : null\n }\n \n\n \n \n \n \n     \n
    \n );\n}\n\nexport default HeartbeatPage;\n" }, { "path": "console/src/pages/Control/Heartbeat/parseEvery.ts", "content": "/**\n * Parse backend \"every\" string (e.g. \"6h\", \"30m\", \"2h30m\") to number + unit\n * for form display. Serialize back to string for API.\n */\n\nconst EVERY_RE =\n /^(?:(?\\d+)h)?(?:(?\\d+)m)?(?:(?\\d+)s)?$/i;\n\nexport type EveryUnit = \"m\" | \"h\";\n\nexport interface EveryParts {\n number: number;\n unit: EveryUnit;\n}\n\nexport function parseEvery(every: string): EveryParts {\n const s = (every || \"\").trim();\n if (!s) {\n return { number: 6, unit: \"h\" };\n }\n const m = s.match(EVERY_RE);\n if (!m || !m.groups) {\n return { number: 6, unit: \"h\" };\n }\n const hours = parseInt(m.groups.hours ?? \"0\", 10);\n const minutes = parseInt(m.groups.minutes ?? \"0\", 10);\n const seconds = parseInt(m.groups.seconds ?? \"0\", 10);\n const totalMinutes = hours * 60 + minutes + Math.round(seconds / 60);\n if (totalMinutes <= 0) {\n return { number: 6, unit: \"h\" };\n }\n if (totalMinutes >= 60 && totalMinutes % 60 === 0) {\n return { number: totalMinutes / 60, unit: \"h\" };\n }\n return { number: totalMinutes, unit: \"m\" };\n}\n\nexport function serializeEvery(parts: EveryParts): string {\n if (parts.unit === \"h\") {\n return `${parts.number}h`;\n }\n return `${parts.number}m`;\n}\n" }, { "path": "console/src/pages/Control/Sessions/components/FilterBar.tsx", "content": "import { Input, Select } from \"@agentscope-ai/design\";\nimport { useTranslation } from \"react-i18next\";\nimport styles from \"../index.module.less\";\n\ninterface FilterBarProps {\n filterUserId: string;\n filterChannel: string;\n uniqueChannels: string[];\n onUserIdChange: (value: string) => void;\n onChannelChange: (value: string) => void;\n}\n\nexport function FilterBar({\n filterUserId,\n filterChannel,\n uniqueChannels,\n onUserIdChange,\n onChannelChange,\n}: FilterBarProps) {\n const { t } = useTranslation();\n\n return (\n
    \n onUserIdChange(e.target.value)}\n allowClear\n className=\"sessions-filter-input\"\n style={{ width: 200 }}\n />\n onChannelChange(value || \"\")}\n allowClear\n className=\"sessions-filter-select\"\n style={{ width: 180 }}\n >\n {uniqueChannels.map((channel) => (\n \n {channel}\n \n ))}\n \n
    \n );\n}\n" }, { "path": "console/src/pages/Control/Sessions/components/SessionDrawer.tsx", "content": "import { Drawer, Form, Input, Button } from \"@agentscope-ai/design\";\nimport { useTranslation } from \"react-i18next\";\nimport type { FormInstance } from \"antd\";\nimport type { Session } from \"./constants\";\nimport styles from \"../index.module.less\";\n\ninterface SessionDrawerProps {\n open: boolean;\n editingSession: Session | null;\n form: FormInstance;\n saving: boolean;\n onClose: () => void;\n onSubmit: (values: Session) => void;\n}\n\nexport function SessionDrawer({\n open,\n editingSession,\n form,\n saving,\n onClose,\n onSubmit,\n}: SessionDrawerProps) {\n const { t } = useTranslation();\n\n const drawerFooter = (\n
    \n \n \n
    \n );\n\n return (\n \n
    \n \n \n \n\n {editingSession && (\n <>\n \n \n \n\n \n \n \n\n \n \n \n\n \n \n \n \n )}\n \n \n );\n}\n" }, { "path": "console/src/pages/Control/Sessions/components/columns.tsx", "content": "import { Button, Tag } from \"@agentscope-ai/design\";\nimport { useTranslation } from \"react-i18next\";\nimport type { TFunction } from \"i18next\";\nimport type { ColumnsType } from \"antd/es/table\";\nimport { CHANNEL_COLORS, formatTime, type Session } from \"./constants\";\n\ninterface ColumnHandlers {\n onEdit: (session: Session) => void;\n onDelete: (sessionId: string) => void;\n t: TFunction;\n}\n\n/** Normalize ISO string to UTC for consistent sorting across mixed timezone formats. */\nconst toUTCTime = (ts: string | null | undefined): number => {\n if (!ts) return 0;\n const normalized =\n /[Z+\\-]\\d{2}:?\\d{2}$/.test(ts) || ts.endsWith(\"Z\") ? ts : ts + \"Z\";\n return new Date(normalized).getTime();\n};\n\nexport const createColumns = (\n handlers: ColumnHandlers,\n): ColumnsType => {\n const { t } = useTranslation();\n\n return [\n {\n title: \"ID\",\n dataIndex: \"id\",\n key: \"id\",\n width: 250,\n },\n {\n title: \"Name\",\n dataIndex: \"name\",\n key: \"name\",\n width: 200,\n },\n {\n title: \"SessionID\",\n dataIndex: \"session_id\",\n key: \"session_id\",\n width: 180,\n },\n {\n title: \"UserID\",\n dataIndex: \"user_id\",\n key: \"user_id\",\n width: 150,\n },\n {\n title: \"Channel\",\n dataIndex: \"channel\",\n key: \"channel\",\n width: 120,\n render: (channel: string) => (\n {channel}\n ),\n },\n {\n title: \"CreatedAt\",\n dataIndex: \"created_at\",\n key: \"created_at\",\n width: 180,\n render: (timestamp: string | number | null) => formatTime(timestamp),\n sorter: (a: Session, b: Session) =>\n toUTCTime(a.created_at) - toUTCTime(b.created_at),\n },\n {\n title: \"UpdatedAt\",\n dataIndex: \"updated_at\",\n key: \"updated_at\",\n width: 180,\n render: (timestamp: string | number | null) => formatTime(timestamp),\n sorter: (a: Session, b: Session) =>\n toUTCTime(a.updated_at) - toUTCTime(b.updated_at),\n defaultSortOrder: \"descend\",\n },\n {\n title: \"Action\",\n key: \"action\",\n width: 180,\n fixed: \"right\",\n render: (_: unknown, record: Session) => (\n
    \n handlers.onEdit(record)}\n >\n {t(\"common.edit\")}\n \n handlers.onDelete(record.id)}\n >\n {t(\"common.delete\")}\n \n
    \n ),\n },\n ];\n};\n" }, { "path": "console/src/pages/Control/Sessions/components/constants.ts", "content": "import type { ChatSpec } from \"../../../../api/types\";\n\nexport interface Session extends ChatSpec {\n name?: string;\n}\n\nexport const CHANNEL_COLORS: Record = {\n imessage: \"blue\",\n discord: \"purple\",\n dingtalk: \"cyan\",\n feishu: \"magenta\",\n qq: \"orange\",\n telegram: \"geekblue\",\n mqtt: \"gold\",\n console: \"green\",\n} as const;\n\n/**\n * Normalize ISO timestamp to ensure UTC timezone is always recognized.\n * Timestamps without timezone suffix (e.g. from datetime.utcnow()) are\n * treated as local time by browsers, causing incorrect display. Appending\n * 'Z' forces UTC interpretation, consistent with timezone-aware timestamps.\n */\nconst normalizeTimestamp = (timestamp: string): string => {\n if (/[Z+\\-]\\d{2}:?\\d{2}$/.test(timestamp) || timestamp.endsWith(\"Z\")) {\n return timestamp;\n }\n return timestamp + \"Z\";\n};\n\nexport const formatTime = (timestamp: string | number | null): string => {\n if (timestamp === null || timestamp === undefined) return \"N/A\";\n const normalized =\n typeof timestamp === \"string\" ? normalizeTimestamp(timestamp) : timestamp;\n const date = new Date(normalized);\n return date.toLocaleString(\"zh-CN\", {\n year: \"numeric\",\n month: \"2-digit\",\n day: \"2-digit\",\n hour: \"2-digit\",\n minute: \"2-digit\",\n });\n};\n" }, { "path": "console/src/pages/Control/Sessions/components/index.ts", "content": "export { createColumns } from \"./columns\";\nexport { FilterBar } from \"./FilterBar\";\nexport { SessionDrawer } from \"./SessionDrawer\";\nexport { CHANNEL_COLORS, formatTime, type Session } from \"./constants\";\n" }, { "path": "console/src/pages/Control/Sessions/index.module.less", "content": ".sessionsPage {\n padding: 24px;\n height: calc(100vh - 128px);\n}\n\n.selectedRow > td {\n background-color: #e6f7ff !important;\n}\n\n.selectedRow:hover > td {\n background-color: #bae7ff !important;\n}\n\n.header {\n display: flex;\n justify-content: space-between;\n align-items: center;\n margin-bottom: 16px;\n}\n\n.headerInfo {\n display: flex;\n flex-direction: column;\n}\n\n.title {\n margin-bottom: 4px;\n font-size: 24px;\n font-weight: 600;\n}\n\n.description {\n margin: 0;\n color: #999;\n font-size: 14px;\n}\n\n.filterBar {\n margin-bottom: 16px;\n display: flex;\n gap: 12px;\n align-items: center;\n}\n\n/* Input and Select styling */\n:global(.sessions-filter-input) {\n .ant-input {\n border-radius: 8px !important;\n border: 1px solid #d9d9d9 !important;\n transition: all 0.2s ease-in-out !important;\n\n &:hover {\n border-color: #615ced !important;\n }\n\n &:focus {\n border-color: #615ced !important;\n box-shadow: 0 0 0 2px rgba(97, 92, 237, 0.2) !important;\n }\n }\n}\n\n:global(.sessions-filter-select) {\n .ant-select-selector {\n border-radius: 8px !important;\n border: 1px solid #d9d9d9 !important;\n transition: all 0.2s ease-in-out !important;\n\n &:hover {\n border-color: #615ced !important;\n }\n\n &:focus,\n &:focus-within {\n border-color: #615ced !important;\n box-shadow: 0 0 0 2px rgba(97, 92, 237, 0.2) !important;\n }\n }\n}\n\n.tableCard {\n :global(.ant-card-body) {\n padding: 0;\n }\n}\n\n.formActions {\n display: flex;\n justify-content: flex-end;\n gap: 8px;\n}\n\n/* ─── Dark mode ─────────────────────────────────────────────────────────────── */\n:global(.dark-mode) {\n .selectedRow > td {\n background-color: rgba(97, 92, 237, 0.12) !important;\n }\n\n .selectedRow:hover > td {\n background-color: rgba(97, 92, 237, 0.2) !important;\n }\n\n .title {\n color: rgba(255, 255, 255, 0.85);\n }\n\n .description {\n color: rgba(255, 255, 255, 0.35);\n }\n\n /* Filter input and select */\n :global(.sessions-filter-input) {\n :global(.copaw-input),\n :global(.ant-input) {\n background: #2a2a2a !important;\n border-color: rgba(255, 255, 255, 0.15) !important;\n color: rgba(255, 255, 255, 0.85) !important;\n\n &::placeholder {\n color: rgba(255, 255, 255, 0.25) !important;\n }\n }\n }\n\n :global(.sessions-filter-select) {\n :global(.copaw-select-selector),\n :global(.ant-select-selector) {\n background: #2a2a2a !important;\n border-color: rgba(255, 255, 255, 0.15) !important;\n color: rgba(255, 255, 255, 0.85) !important;\n }\n\n :global(.copaw-select-selection-placeholder),\n :global(.ant-select-selection-placeholder) {\n color: rgba(255, 255, 255, 0.25) !important;\n }\n\n :global(.copaw-select-arrow),\n :global(.ant-select-arrow) {\n color: rgba(255, 255, 255, 0.3) !important;\n }\n }\n}\n" }, { "path": "console/src/pages/Control/Sessions/index.tsx", "content": "import { useEffect, useState } from \"react\";\nimport {\n Card,\n Form,\n Modal,\n Table,\n message,\n Button,\n} from \"@agentscope-ai/design\";\nimport { useTranslation } from \"react-i18next\";\nimport {\n createColumns,\n FilterBar,\n SessionDrawer,\n type Session,\n} from \"./components\";\nimport { useSessions } from \"./useSessions\";\nimport api from \"../../../api\";\nimport styles from \"./index.module.less\";\n\nfunction SessionsPage() {\n const { t } = useTranslation();\n const {\n sessions,\n loading,\n updateSession,\n deleteSession,\n batchDeleteSessions,\n } = useSessions();\n const [filteredSessions, setFilteredSessions] = useState([]);\n const [drawerOpen, setDrawerOpen] = useState(false);\n const [editingSession, setEditingSession] = useState(null);\n const [saving, setSaving] = useState(false);\n const [form] = Form.useForm();\n\n const [selectedRowKeys, setSelectedRowKeys] = useState([]);\n\n // Filter states\n const [filterUserId, setFilterUserId] = useState(\"\");\n const [filterChannel, setFilterChannel] = useState(\"\");\n const [availableChannels, setAvailableChannels] = useState([]);\n\n useEffect(() => {\n const fetchChannelTypes = async () => {\n try {\n const types = await api.listChannelTypes();\n setAvailableChannels(types);\n } catch (error) {\n console.error(\"❌ Failed to load channel types:\", error);\n }\n };\n fetchChannelTypes();\n }, []);\n\n // Filter effect\n useEffect(() => {\n let filtered: Session[] = sessions;\n\n if (filterUserId) {\n filtered = filtered.filter(\n (session: Session) =>\n session.user_id?.toLowerCase().includes(filterUserId.toLowerCase()),\n );\n }\n\n if (filterChannel) {\n filtered = filtered.filter(\n (session: Session) => session.channel === filterChannel,\n );\n }\n\n setFilteredSessions(filtered);\n }, [sessions, filterUserId, filterChannel]);\n\n const handleEdit = (session: Session) => {\n setEditingSession(session);\n form.setFieldsValue(session as any);\n setDrawerOpen(true);\n };\n\n const handleDelete = (sessionId: string) => {\n Modal.confirm({\n title: t(\"sessions.confirmDelete\"),\n content: t(\"sessions.deleteConfirm\"),\n okText: t(\"cronJobs.deleteText\"),\n okType: \"primary\",\n cancelText: t(\"cronJobs.cancelText\"),\n onOk: async () => {\n await deleteSession(sessionId);\n },\n });\n };\n\n const handleBatchDelete = () => {\n if (selectedRowKeys.length === 0) {\n message.warning(t(\"sessions.batchDeleteConfirm\", { count: 0 }));\n return;\n }\n\n Modal.confirm({\n title: t(\"sessions.confirmDelete\"),\n content: t(\"sessions.batchDeleteConfirm\", {\n count: selectedRowKeys.length,\n }),\n okText: t(\"cronJobs.deleteText\"),\n okType: \"danger\",\n cancelText: t(\"cronJobs.cancelText\"),\n onOk: async () => {\n const success = await batchDeleteSessions(selectedRowKeys as string[]);\n if (success) {\n setSelectedRowKeys([]);\n }\n },\n });\n };\n\n const handleDrawerClose = () => {\n setDrawerOpen(false);\n setEditingSession(null);\n };\n\n const handleSubmit = async (values: Session) => {\n if (editingSession) {\n setSaving(true);\n try {\n const updated = {\n ...editingSession,\n name: values.name,\n };\n const success = await updateSession(editingSession.id, updated);\n if (success) {\n setDrawerOpen(false);\n }\n } finally {\n setSaving(false);\n }\n }\n };\n\n const columns = createColumns({\n onEdit: handleEdit,\n onDelete: handleDelete,\n t,\n });\n\n const rowSelection = {\n fixed: true,\n columnWidth: 50,\n selectedRowKeys,\n onChange: (newSelectedRowKeys: React.Key[]) => {\n setSelectedRowKeys(newSelectedRowKeys);\n },\n };\n\n return (\n
    \n
    \n
    \n

    {t(\"sessions.title\")}

    \n

    {t(\"sessions.description\")}

    \n
    \n {selectedRowKeys.length > 0 && (\n \n )}\n
    \n\n
    \n \n
    \n\n \n \n selectedRowKeys.includes(record.id) ? styles.selectedRow : \"\"\n }\n scroll={{ x: 1500 }}\n pagination={{\n pageSize: 10,\n showTotal: (total) => t(\"sessions.totalItems\", { count: total }),\n }}\n />\n \n\n \n
    \n );\n}\n\nexport default SessionsPage;\n" }, { "path": "console/src/pages/Control/Sessions/useSessions.ts", "content": "import { useState, useEffect } from \"react\";\nimport { message } from \"@agentscope-ai/design\";\nimport api from \"../../../api\";\nimport type { Session } from \"./components/constants\";\nimport { useAgentStore } from \"../../../stores/agentStore\";\n\nexport function useSessions() {\n const [sessions, setSessions] = useState([]);\n const [loading, setLoading] = useState(true);\n const { selectedAgent } = useAgentStore();\n\n const fetchSessions = async () => {\n setLoading(true);\n try {\n const data = await api.listSessions();\n if (data) {\n setSessions(data as Session[]);\n }\n } catch (error) {\n console.error(\"❌ Failed to load sessions:\", error);\n } finally {\n setLoading(false);\n }\n };\n\n useEffect(() => {\n let mounted = true;\n\n const loadSessions = async () => {\n await fetchSessions();\n };\n\n if (mounted) {\n loadSessions();\n }\n\n return () => {\n mounted = false;\n };\n }, [selectedAgent]);\n\n const updateSession = async (sessionId: string, values: Session) => {\n try {\n const result = await api.updateSession(sessionId, values);\n setSessions(sessions.map((s) => (s.id === sessionId ? result : s)));\n message.success(\"Saved successfully\");\n return true;\n } catch (error) {\n console.error(\"❌ Failed to save session:\", error);\n message.error(\"Save failed\");\n return false;\n }\n };\n\n const deleteSession = async (sessionId: string) => {\n try {\n await api.deleteSession(sessionId);\n setSessions(sessions.filter((s) => s.id !== sessionId));\n message.success(\"Deleted successfully\");\n return true;\n } catch (error) {\n console.error(\"❌ Failed to delete session:\", error);\n message.error(\"Failed to delete\");\n return false;\n }\n };\n\n const batchDeleteSessions = async (sessionIds: string[]) => {\n try {\n await api.batchDeleteSessions(sessionIds);\n setSessions(sessions.filter((s) => !sessionIds.includes(s.id)));\n message.success(`Successfully deleted ${sessionIds.length} session(s)`);\n return true;\n } catch (error) {\n console.error(\"❌ Failed to batch delete sessions:\", error);\n message.error(\"Failed to batch delete sessions\");\n return false;\n }\n };\n\n return {\n sessions,\n loading,\n updateSession,\n deleteSession,\n batchDeleteSessions,\n };\n}\n" }, { "path": "console/src/pages/Login/index.tsx", "content": "import { useState, useEffect } from \"react\";\nimport { useTranslation } from \"react-i18next\";\nimport { useNavigate, useSearchParams } from \"react-router-dom\";\nimport { Button, Card, Form, Input, message } from \"antd\";\nimport { LockOutlined, UserOutlined } from \"@ant-design/icons\";\nimport { authApi } from \"../../api/modules/auth\";\nimport { setAuthToken } from \"../../api/config\";\n\nexport default function LoginPage() {\n const { t } = useTranslation();\n const navigate = useNavigate();\n const [searchParams] = useSearchParams();\n const [loading, setLoading] = useState(false);\n const [isRegister, setIsRegister] = useState(false);\n const [hasUsers, setHasUsers] = useState(true);\n\n useEffect(() => {\n authApi\n .getStatus()\n .then((res) => {\n if (!res.enabled) {\n navigate(\"/chat\", { replace: true });\n return;\n }\n setHasUsers(res.has_users);\n if (!res.has_users) {\n setIsRegister(true);\n }\n })\n .catch(() => {});\n }, [navigate]);\n\n const onFinish = async (values: { username: string; password: string }) => {\n setLoading(true);\n try {\n const raw = searchParams.get(\"redirect\") || \"/chat\";\n const redirect =\n raw.startsWith(\"/\") && !raw.startsWith(\"//\") ? raw : \"/chat\";\n\n if (isRegister) {\n const res = await authApi.register(values.username, values.password);\n if (res.token) {\n setAuthToken(res.token);\n message.success(t(\"login.registerSuccess\"));\n navigate(redirect, { replace: true });\n }\n } else {\n const res = await authApi.login(values.username, values.password);\n if (res.token) {\n setAuthToken(res.token);\n navigate(redirect, { replace: true });\n } else {\n message.info(t(\"login.authNotEnabled\"));\n navigate(redirect, { replace: true });\n }\n }\n } catch (err) {\n message.error(\n isRegister\n ? err instanceof Error\n ? err.message\n : t(\"login.registerFailed\")\n : t(\"login.failed\"),\n );\n } finally {\n setLoading(false);\n }\n };\n\n return (\n \n \n
    \n \n

    \n {isRegister ? t(\"login.registerTitle\") : t(\"login.title\")}\n

    \n {!hasUsers && (\n \n {t(\"login.firstUserHint\")}\n

    \n )}\n
    \n\n \n \n }\n placeholder={t(\"login.usernamePlaceholder\")}\n autoFocus\n />\n \n\n \n }\n placeholder={t(\"login.passwordPlaceholder\")}\n />\n \n\n \n \n {isRegister ? t(\"login.register\") : t(\"login.submit\")}\n \n \n \n \n \n );\n}\n" }, { "path": "console/src/pages/Settings/Agents/components/AgentModal.tsx", "content": "import { Modal, Form, Input } from \"antd\";\nimport { useTranslation } from \"react-i18next\";\nimport type { AgentSummary } from \"@/api/types/agents\";\n\ninterface AgentModalProps {\n open: boolean;\n editingAgent: AgentSummary | null;\n form: ReturnType[0];\n onSave: () => Promise;\n onCancel: () => void;\n}\n\nexport function AgentModal({\n open,\n editingAgent,\n form,\n onSave,\n onCancel,\n}: AgentModalProps) {\n const { t } = useTranslation();\n\n return (\n \n
    \n {editingAgent && (\n \n \n \n )}\n \n \n \n \n \n \n \n \n \n \n \n );\n}\n" }, { "path": "console/src/pages/Settings/Agents/components/AgentTable.tsx", "content": "import { Table, Button, Space, Popconfirm } from \"antd\";\nimport type { ColumnsType } from \"antd/es/table\";\nimport { useTranslation } from \"react-i18next\";\nimport { EditOutlined, DeleteOutlined, RobotOutlined } from \"@ant-design/icons\";\nimport type { AgentSummary } from \"../../../../api/types/agents\";\nimport { useTheme } from \"../../../../contexts/ThemeContext\";\nimport styles from \"../index.module.less\";\n\ninterface AgentTableProps {\n agents: AgentSummary[];\n loading: boolean;\n onEdit: (agent: AgentSummary) => void;\n onDelete: (agentId: string) => void;\n}\n\nexport function AgentTable({\n agents,\n loading,\n onEdit,\n onDelete,\n}: AgentTableProps) {\n const { t } = useTranslation();\n const { isDark } = useTheme();\n\n // Inline style for disabled buttons — CSS cannot reliably override AntD's disabled styles\n const disabledStyle: React.CSSProperties = isDark\n ? { color: \"rgba(255,255,255,0.35)\", opacity: 1 }\n : {};\n\n const columns: ColumnsType = [\n {\n title: t(\"agent.name\"),\n dataIndex: \"name\",\n key: \"name\",\n render: (text: string) => (\n \n \n {text}\n \n ),\n },\n {\n title: t(\"agent.id\"),\n dataIndex: \"id\",\n key: \"id\",\n },\n {\n title: t(\"agent.description\"),\n dataIndex: \"description\",\n key: \"description\",\n ellipsis: true,\n },\n {\n title: t(\"agent.workspace\"),\n dataIndex: \"workspace_dir\",\n key: \"workspace_dir\",\n ellipsis: true,\n },\n {\n title: t(\"common.actions\"),\n key: \"actions\",\n width: 200,\n render: (_: any, record: AgentSummary) => (\n \n }\n onClick={() => onEdit(record)}\n disabled={record.id === \"default\"}\n style={record.id === \"default\" ? disabledStyle : undefined}\n title={\n record.id === \"default\"\n ? t(\"agent.defaultNotEditable\")\n : undefined\n }\n >\n {t(\"common.edit\")}\n \n onDelete(record.id)}\n disabled={record.id === \"default\"}\n okText={t(\"common.confirm\")}\n cancelText={t(\"common.cancel\")}\n >\n }\n disabled={record.id === \"default\"}\n style={record.id === \"default\" ? disabledStyle : undefined}\n title={\n record.id === \"default\"\n ? t(\"agent.defaultNotDeletable\")\n : undefined\n }\n >\n {t(\"common.delete\")}\n \n \n \n ),\n },\n ];\n\n return (\n
    \n \n
    \n );\n}\n" }, { "path": "console/src/pages/Settings/Agents/components/PageHeader.tsx", "content": "import styles from \"../index.module.less\";\n\ninterface PageHeaderProps {\n title: string;\n description?: string;\n className?: string;\n action?: React.ReactNode;\n}\n\nexport function PageHeader({\n title,\n description,\n className,\n action,\n}: PageHeaderProps) {\n return (\n
    \n
    \n
    \n

    {title}

    \n
    \n {description &&

    {description}

    }\n
    \n {action &&
    {action}
    }\n
    \n );\n}\n" }, { "path": "console/src/pages/Settings/Agents/components/index.ts", "content": "export { PageHeader } from \"./PageHeader\";\nexport { AgentTable } from \"./AgentTable\";\nexport { AgentModal } from \"./AgentModal\";\n" }, { "path": "console/src/pages/Settings/Agents/index.module.less", "content": ".agentsPage {\n padding: 24px;\n}\n\n/* ---- Section (same as Models / Environments) ---- */\n\n.section {\n margin-bottom: 24px;\n display: flex;\n justify-content: space-between;\n align-items: center;\n}\n\n.section:last-child {\n margin-bottom: 0;\n}\n\n.sectionTitle {\n margin: 0;\n font-size: 24px;\n font-weight: 600;\n}\n\n.sectionDesc {\n color: #999;\n font-size: 14px;\n}\n\n/* ---- Table Card ---- */\n\n.tableCard {\n margin-bottom: 24px;\n\n &:last-child {\n margin-bottom: 0;\n }\n}\n\n/* ─── Dark mode ─────────────────────────────────────────────────────────────── */\n:global(.dark-mode) {\n .sectionTitle {\n color: rgba(255, 255, 255, 0.85);\n }\n\n .sectionDesc {\n color: rgba(255, 255, 255, 0.35);\n }\n}\n\n/* Link buttons in table — must be flat global selectors to beat AntD specificity */\n:global(.dark-mode .ant-btn-link) {\n color: #8b87f0 !important;\n\n &:global(:hover) {\n color: #a5a2f5 !important;\n }\n}\n\n:global(.dark-mode .ant-btn-link.ant-btn-dangerous) {\n color: #ff7875 !important;\n\n &:global(:hover) {\n color: #ff9c9a !important;\n }\n}\n\n:global(.dark-mode .ant-btn-link:disabled),\n:global(.dark-mode .ant-btn-link.ant-btn-disabled),\n:global(.dark-mode .ant-btn-link[disabled]) {\n color: rgba(255, 255, 255, 0.35) !important;\n opacity: 1 !important;\n}\n" }, { "path": "console/src/pages/Settings/Agents/index.tsx", "content": "import { useState } from \"react\";\nimport { Card, Button, Form, message } from \"antd\";\nimport { PlusOutlined } from \"@ant-design/icons\";\nimport { useTranslation } from \"react-i18next\";\nimport { agentsApi } from \"../../../api/modules/agents\";\nimport type { AgentSummary } from \"../../../api/types/agents\";\nimport { useAgents } from \"./useAgents\";\nimport { PageHeader, AgentTable, AgentModal } from \"./components\";\nimport styles from \"./index.module.less\";\n\nexport default function AgentsPage() {\n const { t } = useTranslation();\n const { agents, loading, deleteAgent } = useAgents();\n const [modalVisible, setModalVisible] = useState(false);\n const [editingAgent, setEditingAgent] = useState(null);\n const [form] = Form.useForm();\n\n const handleCreate = () => {\n setEditingAgent(null);\n form.resetFields();\n form.setFieldsValue({\n workspace_dir: \"\",\n });\n setModalVisible(true);\n };\n\n const handleEdit = async (agent: AgentSummary) => {\n try {\n const config = await agentsApi.getAgent(agent.id);\n setEditingAgent(agent);\n form.setFieldsValue(config);\n setModalVisible(true);\n } catch (error) {\n console.error(\"Failed to load agent config:\", error);\n message.error(t(\"agent.loadConfigFailed\"));\n }\n };\n\n const handleDelete = async (agentId: string) => {\n try {\n await deleteAgent(agentId);\n } catch {\n // Error already handled in hook\n message.error(t(\"agent.deleteFailed\"));\n }\n };\n\n const handleSubmit = async () => {\n try {\n const values = await form.validateFields();\n\n if (editingAgent) {\n await agentsApi.updateAgent(editingAgent.id, values);\n message.success(t(\"agent.updateSuccess\"));\n } else {\n const result = await agentsApi.createAgent(values);\n message.success(`${t(\"agent.createSuccess\")} (ID: ${result.id})`);\n }\n\n setModalVisible(false);\n } catch (error: any) {\n console.error(\"Failed to save agent:\", error);\n message.error(error.message || t(\"agent.saveFailed\"));\n }\n };\n\n return (\n
    \n } onClick={handleCreate}>\n {t(\"agent.create\")}\n \n }\n />\n\n \n \n \n\n setModalVisible(false)}\n />\n
    \n );\n}\n" }, { "path": "console/src/pages/Settings/Agents/useAgents.ts", "content": "import { useState, useEffect } from \"react\";\nimport { message } from \"antd\";\nimport { useTranslation } from \"react-i18next\";\nimport { agentsApi } from \"@/api/modules/agents\";\nimport type { AgentSummary } from \"@/api/types/agents\";\nimport { useAgentStore } from \"@/stores/agentStore\";\n\ninterface UseAgentsReturn {\n agents: AgentSummary[];\n loading: boolean;\n error: Error | null;\n loadAgents: () => Promise;\n deleteAgent: (agentId: string) => Promise;\n}\n\nexport function useAgents(): UseAgentsReturn {\n const { t } = useTranslation();\n const [agents, setAgents] = useState([]);\n const [loading, setLoading] = useState(false);\n const [error, setError] = useState(null);\n const { setAgents: updateStoreAgents } = useAgentStore();\n\n const loadAgents = async () => {\n setLoading(true);\n setError(null);\n try {\n const data = await agentsApi.listAgents();\n setAgents(data.agents);\n updateStoreAgents(data.agents);\n } catch (err) {\n console.error(\"Failed to load agents:\", err);\n const errorMsg =\n err instanceof Error ? err : new Error(t(\"agent.loadFailed\"));\n setError(errorMsg);\n message.error(t(\"agent.loadFailed\"));\n } finally {\n setLoading(false);\n }\n };\n\n const deleteAgent = async (agentId: string) => {\n try {\n await agentsApi.deleteAgent(agentId);\n message.success(t(\"agent.deleteSuccess\"));\n await loadAgents();\n } catch (err: any) {\n message.error(err.message || t(\"agent.deleteFailed\"));\n throw err;\n }\n };\n\n useEffect(() => {\n loadAgents();\n }, []);\n\n return {\n agents,\n loading,\n error,\n loadAgents,\n deleteAgent,\n };\n}\n" }, { "path": "console/src/pages/Settings/Environments/components/AddButton.tsx", "content": "import { SparkPlusLine } from \"@agentscope-ai/icons\";\nimport { useTranslation } from \"react-i18next\";\nimport styles from \"../index.module.less\";\n\ninterface AddButtonProps {\n onClick: () => void;\n className?: string;\n}\n\nexport function AddButton({ onClick, className }: AddButtonProps) {\n const { t } = useTranslation();\n\n return (\n
    \n \n \n {t(\"environments.addVariable\")}\n \n
    \n );\n}\n" }, { "path": "console/src/pages/Settings/Environments/components/EmptyState.tsx", "content": "import { useTranslation } from \"react-i18next\";\nimport styles from \"../index.module.less\";\n\ninterface EmptyStateProps {\n className?: string;\n}\n\nexport function EmptyState({ className }: EmptyStateProps) {\n const { t } = useTranslation();\n\n return (\n
    \n 📦\n {t(\"environments.noVariables\")}\n
    \n );\n}\n" }, { "path": "console/src/pages/Settings/Environments/components/EnvRow.tsx", "content": "import { Checkbox, Input } from \"@agentscope-ai/design\";\nimport { SparkDeleteLine, SparkPlusLine } from \"@agentscope-ai/icons\";\nimport { EyeOutlined, EyeInvisibleOutlined } from \"@ant-design/icons\";\nimport { useState } from \"react\";\nimport { useTranslation } from \"react-i18next\";\nimport styles from \"../index.module.less\";\n\nexport interface Row {\n key: string;\n value: string;\n isNew?: boolean;\n}\n\ninterface EnvRowProps {\n row: Row;\n idx: number;\n checked: boolean;\n error?: string;\n onToggle: (idx: number) => void;\n onChange: (idx: number, field: \"key\" | \"value\", val: string) => void;\n onInsert: (idx: number) => void;\n onRemove: (idx: number) => void;\n}\n\nexport function EnvRow({\n row,\n idx,\n checked,\n error,\n onToggle,\n onChange,\n onInsert,\n onRemove,\n}: EnvRowProps) {\n const { t } = useTranslation();\n const [isPasswordVisible, setIsPasswordVisible] = useState(false);\n\n return (\n
    \n onToggle(idx)}\n className={styles.rowCheckbox}\n />\n\n
    \n \n Key\n onChange(idx, \"key\", e.target.value)}\n className={styles.inputField}\n autoFocus={row.isNew}\n />\n
    \n\n
    \n Value\n onChange(idx, \"value\", e.target.value)}\n className={styles.inputField}\n suffix={\n setIsPasswordVisible(!isPasswordVisible)}\n type=\"button\"\n title={\n isPasswordVisible\n ? t(\"environments.hideValue\")\n : t(\"environments.showValue\")\n }\n >\n {isPasswordVisible ? : }\n \n }\n />\n
    \n
    \n\n
    \n onInsert(idx)}\n title={t(\"environments.insertRowBelow\")}\n >\n \n \n onRemove(idx)}\n title={t(\"environments.deleteRow\")}\n >\n \n \n
    \n\n {error &&
    {error}
    }\n \n );\n}\n" }, { "path": "console/src/pages/Settings/Environments/components/PageHeader.tsx", "content": "import { useTranslation } from \"react-i18next\";\nimport styles from \"../index.module.less\";\n\ninterface PageHeaderProps {\n className?: string;\n}\n\nexport function PageHeader({ className }: PageHeaderProps) {\n const { t } = useTranslation();\n\n return (\n
    \n

    {t(\"environments.title\")}

    \n

    {t(\"environments.description\")}

    \n
    \n );\n}\n" }, { "path": "console/src/pages/Settings/Environments/components/Toolbar.tsx", "content": "import { Checkbox, Button } from \"@agentscope-ai/design\";\nimport { SparkDeleteLine } from \"@agentscope-ai/icons\";\nimport { useTranslation } from \"react-i18next\";\nimport styles from \"../index.module.less\";\n\ninterface ToolbarProps {\n workingRowsLength: number;\n allSelected: boolean;\n someSelected: boolean;\n selectedSize: number;\n dirty: boolean;\n saving: boolean;\n indeterminate: boolean;\n onToggleSelectAll: () => void;\n onRemoveSelected: () => void;\n onReset: () => void;\n onSave: () => void;\n className?: string;\n}\n\nexport function Toolbar({\n workingRowsLength,\n allSelected,\n someSelected,\n selectedSize,\n dirty,\n saving,\n indeterminate,\n onToggleSelectAll,\n onRemoveSelected,\n onReset,\n onSave,\n className,\n}: ToolbarProps) {\n const { t } = useTranslation();\n\n return (\n
    \n
    \n {workingRowsLength > 0 && (\n \n )}\n \n {someSelected\n ? `${selectedSize} ${t(\"environments.of\")} ${workingRowsLength} ${t(\n \"environments.selected\",\n )}`\n : `${workingRowsLength} ${\n workingRowsLength !== 1\n ? t(\"environments.variables\")\n : t(\"environments.variable\")\n }`}\n \n
    \n\n
    \n {someSelected && (\n }\n onClick={onRemoveSelected}\n disabled={saving}\n >\n {t(\"common.delete\")} ({selectedSize})\n \n )}\n {dirty && (\n <>\n \n \n {t(\"common.save\")}\n \n \n )}\n
    \n
    \n );\n}\n" }, { "path": "console/src/pages/Settings/Environments/components/index.ts", "content": "export * from \"./PageHeader\";\nexport * from \"./EmptyState\";\nexport * from \"./AddButton\";\nexport * from \"./Toolbar\";\nexport * from \"./EnvRow\";\n" }, { "path": "console/src/pages/Settings/Environments/index.module.less", "content": ".environmentsPage {\n padding: 24px;\n}\n\n/* ---- Section (matches Models page) ---- */\n\n.section {\n margin-bottom: 24px;\n}\n\n.sectionTitle {\n margin-bottom: 4px;\n font-size: 24px;\n font-weight: 600;\n}\n\n.sectionDesc {\n margin: 0;\n color: #999;\n font-size: 14px;\n}\n\n/* ---- Loading / Error ---- */\n\n.centerState {\n display: flex;\n flex-direction: column;\n align-items: center;\n justify-content: center;\n padding: 80px 24px;\n}\n\n.stateText {\n font-size: 14px;\n color: #999;\n}\n\n.stateTextError {\n font-size: 14px;\n color: #ff4d4f;\n margin-bottom: 4px;\n}\n\n/* ---- Table card ---- */\n\n.tableCard {\n background: #fff;\n border: 1px solid #e8e8e8;\n border-radius: 16px;\n box-shadow: 0 2px 8px rgba(0, 0, 0, 0.04);\n overflow: hidden;\n transition: all 0.2s ease-in-out;\n\n &:hover {\n box-shadow: 0 4px 16px rgba(0, 0, 0, 0.08);\n border-color: #d9d9d9;\n }\n}\n\n/* ---- Toolbar ---- */\n\n.toolbar {\n display: flex;\n align-items: center;\n justify-content: space-between;\n padding: 16px 24px;\n background: #fafafa;\n border-bottom: 1px solid #f0f0f0;\n transition: background 0.2s ease-in-out;\n\n &:hover {\n background: #f5f5f5;\n }\n}\n\n.toolbarLeft {\n display: flex;\n align-items: center;\n gap: 10px;\n}\n\n.toolbarCount {\n font-size: 13px;\n color: #999;\n user-select: none;\n}\n\n.toolbarRight {\n display: flex;\n align-items: center;\n gap: 8px;\n}\n\n/* ---- Row list ---- */\n\n.rowList {\n display: flex;\n flex-direction: column;\n}\n\n/* ---- Env row ---- */\n\n.envRow {\n display: flex;\n align-items: center;\n gap: 16px;\n padding: 12px 24px;\n border-bottom: 1px solid #f5f5f5;\n transition: all 0.2s ease-in-out;\n flex-wrap: wrap;\n\n &:last-child {\n border-bottom: none;\n }\n\n &:hover {\n background: #fafbfc;\n transform: translateX(2px);\n }\n}\n\n.envRowSelected {\n background: #e6f4ff;\n border-left: 3px solid #1677ff;\n\n &:hover {\n background: #d6eaff;\n transform: translateX(2px);\n }\n}\n\n.envRowSelected {\n background: #e6f4ff;\n\n &:hover {\n background: #d6eaff;\n }\n}\n\n.rowCheckbox {\n flex-shrink: 0;\n}\n\n/* Key + Value inputs side-by-side */\n\n.fieldsWrap {\n display: flex;\n flex: 1;\n min-width: 0;\n gap: 16px;\n}\n\n.inputGroup {\n display: flex;\n align-items: center;\n flex: 1 1 0;\n min-width: 180px;\n height: 42px;\n border: 1px solid #e0e0e0;\n border-radius: 8px;\n background: #fff;\n overflow: hidden;\n transition: all 0.2s ease-in-out;\n\n &:focus-within {\n border-color: #615ced;\n box-shadow: 0 0 0 2px rgba(97, 92, 237, 0.2);\n transform: translateY(-1px);\n }\n}\n\n.inputGroupError {\n border-color: #ff4d4f;\n animation: shake 0.3s ease-in-out;\n\n &:focus-within {\n border-color: #ff4d4f;\n box-shadow: 0 0 0 2px rgba(255, 77, 79, 0.2);\n }\n}\n\n@keyframes shake {\n 0%,\n 100% {\n transform: translateX(0);\n }\n\n 25% {\n transform: translateX(-2px);\n }\n\n 75% {\n transform: translateX(2px);\n }\n}\n\n.inputLabel {\n flex-shrink: 0;\n padding: 0 14px;\n font-size: 14px;\n font-weight: 500;\n color: #666;\n white-space: nowrap;\n user-select: none;\n line-height: 42px;\n border-right: 1px solid #f0f0f0;\n background: #fafafa;\n min-width: 60px;\n text-align: center;\n transition: all 0.2s ease-in-out;\n\n .inputGroup:focus-within & {\n color: #615ced;\n background: #f0f0ff;\n }\n}\n\n.inputField {\n flex: 1;\n min-width: 0;\n height: 40px !important;\n border: none !important;\n box-shadow: none !important;\n outline: none !important;\n font-family: \"SF Mono\", \"Menlo\", \"Consolas\", monospace;\n font-size: 14px;\n background: transparent;\n padding-left: 12px;\n transition: all 0.2s ease-in-out;\n\n &::placeholder {\n color: #bfbfbf;\n }\n}\n\n.inputField {\n :global(.ant-input) {\n height: 40px !important;\n border: none !important;\n box-shadow: none !important;\n font-family: \"SF Mono\", \"Menlo\", \"Consolas\", monospace;\n font-size: 14px;\n padding-left: 12px;\n transition: all 0.2s ease-in-out;\n\n &::placeholder {\n color: #bfbfbf;\n }\n }\n}\n\n/* Password toggle button */\n.passwordToggle {\n display: inline-flex;\n align-items: center;\n justify-content: center;\n width: 32px;\n height: 32px;\n border: none;\n background: transparent;\n cursor: pointer;\n color: #999;\n transition: all 0.2s ease-in-out;\n border-radius: 4px;\n\n &:hover {\n color: #615ced;\n background: #f0f0ff;\n }\n}\n\n/* ---- Row action buttons ---- */\n\n.rowActions {\n display: flex;\n align-items: center;\n gap: 6px;\n flex-shrink: 0;\n}\n\n.rowIconBtn {\n display: inline-flex;\n align-items: center;\n justify-content: center;\n width: 36px;\n height: 36px;\n border: none;\n border-radius: 8px;\n background: transparent;\n cursor: pointer;\n font-size: 16px;\n color: #c0c0c0;\n transition: all 0.2s ease-in-out;\n\n &:hover {\n color: #615ced;\n background: #f0f0ff;\n transform: translateY(-1px);\n box-shadow: 0 2px 8px rgba(97, 92, 237, 0.15);\n }\n}\n\n.rowIconBtnDanger {\n &:hover {\n color: #ff4d4f;\n background: #fff1f0;\n transform: translateY(-1px);\n box-shadow: 0 2px 8px rgba(255, 77, 79, 0.15);\n }\n}\n\n/* ---- Row error ---- */\n\n.rowError {\n flex-basis: 100%;\n font-size: 12px;\n color: #ff4d4f;\n padding-left: 36px;\n /* align with fields after checkbox */\n margin-top: -2px;\n}\n\n/* ---- Add bar ---- */\n\n.addBar {\n display: flex;\n padding: 16px 24px;\n border-top: 1px solid #f0f0f0;\n background: #fafafa;\n transition: background 0.2s ease-in-out;\n\n &:hover {\n background: #f5f5f5;\n }\n}\n\n.addBtn {\n display: inline-flex;\n align-items: center;\n gap: 8px;\n padding: 8px 20px;\n border: 1px dashed #d9d9d9;\n border-radius: 8px;\n background: transparent;\n cursor: pointer;\n font-size: 14px;\n color: #999;\n transition: all 0.2s ease-in-out;\n\n &:hover {\n color: #615ced;\n border-color: #615ced;\n background: #f0f0ff;\n transform: translateY(-1px);\n box-shadow: 0 2px 8px rgba(97, 92, 237, 0.15);\n }\n\n svg {\n font-size: 16px;\n }\n}\n\n/* ---- Empty state ---- */\n\n.emptyState {\n display: flex;\n flex-direction: column;\n align-items: center;\n gap: 8px;\n padding: 48px 24px;\n color: #bbb;\n font-size: 14px;\n}\n\n.emptyIcon {\n font-size: 32px;\n opacity: 0.6;\n}\n\n/* ─── Dark mode ─────────────────────────────────────────────────────────────── */\n:global(.dark-mode) {\n .sectionDesc {\n color: rgba(255, 255, 255, 0.35);\n }\n\n .stateText {\n color: rgba(255, 255, 255, 0.35);\n }\n\n /* Main card */\n .tableCard {\n background: #1f1f1f;\n border-color: rgba(255, 255, 255, 0.1);\n box-shadow: 0 2px 8px rgba(0, 0, 0, 0.3);\n\n &:hover {\n box-shadow: 0 4px 16px rgba(0, 0, 0, 0.4);\n border-color: rgba(255, 255, 255, 0.15);\n }\n }\n\n /* Toolbar */\n .toolbar {\n background: rgba(255, 255, 255, 0.03);\n border-bottom-color: rgba(255, 255, 255, 0.08);\n\n &:hover {\n background: rgba(255, 255, 255, 0.05);\n }\n }\n\n .toolbarCount {\n color: rgba(255, 255, 255, 0.35);\n }\n\n /* Env row */\n .envRow {\n border-bottom-color: rgba(255, 255, 255, 0.06);\n\n &:hover {\n background: rgba(255, 255, 255, 0.04);\n }\n }\n\n .envRowSelected {\n background: rgba(22, 119, 255, 0.12);\n border-left-color: #4096ff;\n\n &:hover {\n background: rgba(22, 119, 255, 0.18);\n }\n }\n\n /* Input group (Key / Value 外框) */\n .inputGroup {\n border-color: rgba(255, 255, 255, 0.12);\n background: #2a2a2a;\n\n &:focus-within {\n border-color: #615ced;\n box-shadow: 0 0 0 2px rgba(97, 92, 237, 0.2);\n }\n }\n\n /* Key / Value 标签 */\n .inputLabel {\n color: rgba(255, 255, 255, 0.4);\n border-right-color: rgba(255, 255, 255, 0.08);\n background: rgba(255, 255, 255, 0.04);\n\n .inputGroup:focus-within & {\n color: #8b87f0;\n background: rgba(97, 92, 237, 0.1);\n }\n }\n\n /* Input field inside group */\n .inputField {\n color: rgba(255, 255, 255, 0.85);\n\n &::placeholder {\n color: rgba(255, 255, 255, 0.2);\n }\n\n :global(.ant-input),\n :global(.copaw-input) {\n color: rgba(255, 255, 255, 0.85) !important;\n background: transparent !important;\n\n &::placeholder {\n color: rgba(255, 255, 255, 0.2) !important;\n }\n }\n }\n\n /* Password toggle */\n .passwordToggle {\n color: rgba(255, 255, 255, 0.3);\n\n &:hover {\n color: #8b87f0;\n background: rgba(97, 92, 237, 0.12);\n }\n }\n\n /* Row action icons */\n .rowIconBtn {\n color: rgba(255, 255, 255, 0.2);\n\n &:hover {\n color: #8b87f0;\n background: rgba(97, 92, 237, 0.12);\n }\n }\n\n .rowIconBtnDanger {\n &:hover {\n color: #ff7875;\n background: rgba(255, 77, 79, 0.12);\n }\n }\n\n /* Add bar */\n .addBar {\n background: rgba(255, 255, 255, 0.02);\n border-top-color: rgba(255, 255, 255, 0.08);\n\n &:hover {\n background: rgba(255, 255, 255, 0.04);\n }\n }\n\n .addBtn {\n border-color: rgba(255, 255, 255, 0.15);\n color: rgba(255, 255, 255, 0.35);\n\n &:hover {\n color: #8b87f0;\n border-color: #615ced;\n background: rgba(97, 92, 237, 0.1);\n }\n }\n\n /* Empty state */\n .emptyState {\n color: rgba(255, 255, 255, 0.2);\n }\n}\n" }, { "path": "console/src/pages/Settings/Environments/index.tsx", "content": "import { useState, useCallback, useMemo } from \"react\";\nimport { Button, Modal, message } from \"@agentscope-ai/design\";\nimport { useTranslation } from \"react-i18next\";\n\nimport api from \"../../../api\";\nimport { useEnvVars } from \"./useEnvVars\";\nimport {\n PageHeader,\n EmptyState,\n AddButton,\n Toolbar,\n EnvRow,\n type Row,\n} from \"./components\";\nimport styles from \"./index.module.less\";\n\n/* ------------------------------------------------------------------ */\n/* Helpers */\n/* ------------------------------------------------------------------ */\n\n/** Reindex selected set after a splice at `idx`. */\nfunction shiftIndices(prev: Set, removedIdx: number): Set {\n const next = new Set();\n prev.forEach((i) => {\n if (i < removedIdx) next.add(i);\n else if (i > removedIdx) next.add(i - 1);\n });\n return next;\n}\n\n/* ------------------------------------------------------------------ */\n/* Main Page */\n/* ------------------------------------------------------------------ */\n\nfunction EnvironmentsPage() {\n const { t } = useTranslation();\n const { envVars, loading, error, fetchAll } = useEnvVars();\n const [rows, setRows] = useState(null);\n const [saving, setSaving] = useState(false);\n const [keyErrors, setKeyErrors] = useState>({});\n const [selected, setSelected] = useState>(new Set());\n\n /* ---- derived state ---- */\n\n const workingRows: Row[] = useMemo(\n () => rows ?? envVars.map((e) => ({ key: e.key, value: e.value })),\n [rows, envVars],\n );\n\n const dirty = rows !== null;\n const someSelected = selected.size > 0;\n const allSelected =\n workingRows.length > 0 && workingRows.every((_, i) => selected.has(i));\n\n /* ---- ensure we have a mutable local copy ---- */\n\n const ensureLocal = useCallback((): Row[] => {\n if (rows) return [...rows];\n return envVars.map((e) => ({ key: e.key, value: e.value }));\n }, [rows, envVars]);\n\n /* ---- selection ---- */\n\n const toggleSelect = useCallback((idx: number) => {\n setSelected((prev) => {\n const next = new Set(prev);\n if (next.has(idx)) next.delete(idx);\n else next.add(idx);\n return next;\n });\n }, []);\n\n const toggleSelectAll = useCallback(() => {\n if (allSelected) {\n setSelected(new Set());\n } else {\n setSelected(new Set(workingRows.map((_, i) => i)));\n }\n }, [allSelected, workingRows]);\n\n /* ---- row mutations ---- */\n\n const updateRow = useCallback(\n (idx: number, field: \"key\" | \"value\", val: string) => {\n const next = ensureLocal();\n next[idx] = { ...next[idx], [field]: val };\n setRows(next);\n if (field === \"key\") {\n setKeyErrors((prev) => {\n const copy = { ...prev };\n delete copy[idx];\n return copy;\n });\n }\n },\n [ensureLocal],\n );\n\n const addRow = useCallback(() => {\n const next = ensureLocal();\n next.push({ key: \"\", value: \"\", isNew: true });\n setRows(next);\n }, [ensureLocal]);\n\n const insertRowAfter = useCallback(\n (idx: number) => {\n const next = ensureLocal();\n next.splice(idx + 1, 0, { key: \"\", value: \"\", isNew: true });\n setRows(next);\n setSelected((prev) => {\n const rebuilt = new Set();\n prev.forEach((i) => rebuilt.add(i <= idx ? i : i + 1));\n return rebuilt;\n });\n },\n [ensureLocal],\n );\n\n const removeRow = useCallback(\n (idx: number) => {\n const row = workingRows[idx];\n\n // New (unsaved) row — just remove from local state, no API call needed\n if (row.isNew) {\n const next = ensureLocal();\n next.splice(idx, 1);\n setRows(next.length === 0 && envVars.length === 0 ? null : next);\n setSelected((prev) => shiftIndices(prev, idx));\n return;\n }\n\n // Persisted row — confirm then call DELETE API immediately\n Modal.confirm({\n title: t(\"environments.deleteVariable\"),\n content: t(\"environments.deleteConfirm\", { name: row.key }),\n okText: t(\"common.delete\"),\n okButtonProps: { danger: true },\n cancelText: t(\"common.cancel\"),\n onOk: async () => {\n try {\n await api.deleteEnv(row.key);\n message.success(t(\"environments.deleteSuccess\", { name: row.key }));\n // Refresh from server so local state is in sync\n setRows(null);\n setSelected(new Set());\n setKeyErrors({});\n fetchAll();\n } catch (err) {\n const errMsg =\n err instanceof Error\n ? err.message\n : t(\"environments.deleteFailed\");\n message.error(errMsg);\n }\n },\n });\n },\n [workingRows, ensureLocal, envVars.length, fetchAll],\n );\n\n const removeSelected = useCallback(() => {\n if (selected.size === 0) return;\n const indices = Array.from(selected).sort((a, b) => a - b);\n const names = indices.map((i) => workingRows[i]?.key).filter(Boolean);\n const hasPersistedRows = indices.some((i) => !workingRows[i]?.isNew);\n\n // All selected rows are new — just remove from local state\n if (!hasPersistedRows) {\n const next = ensureLocal().filter((_, i) => !selected.has(i));\n setRows(next.length === 0 && envVars.length === 0 ? null : next);\n setSelected(new Set());\n return;\n }\n\n const label =\n names.length <= 3\n ? names.map((n) => `\"${n}\"`).join(\", \")\n : `${names.length} variables`;\n\n Modal.confirm({\n title: t(\"environments.deleteSelected\"),\n content: t(\"environments.deleteSelectedConfirm\", { label }),\n okText: t(\"common.delete\"),\n okButtonProps: { danger: true },\n cancelText: t(\"common.cancel\"),\n onOk: async () => {\n try {\n const persistedKeysToDelete = indices\n .map((i) => workingRows[i])\n .filter((row) => row && !row.isNew)\n .map((row) => row.key.trim())\n .filter(Boolean);\n\n if (persistedKeysToDelete.length > 0) {\n await Promise.all(\n persistedKeysToDelete.map((key) => api.deleteEnv(key)),\n );\n }\n\n message.success(t(\"environments.deleteSuccess\", { name: label }));\n setRows(null);\n setSelected(new Set());\n setKeyErrors({});\n fetchAll();\n } catch (err) {\n const errMsg =\n err instanceof Error ? err.message : t(\"environments.deleteFailed\");\n message.error(errMsg);\n }\n },\n });\n }, [selected, workingRows, ensureLocal, envVars.length, fetchAll]);\n\n /* ---- validate & save ---- */\n\n const validate = useCallback((): boolean => {\n const errors: Record = {};\n const seen = new Set();\n for (let i = 0; i < workingRows.length; i++) {\n const k = workingRows[i].key.trim();\n if (!k) {\n errors[i] = t(\"environments.keyRequired\");\n } else if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(k)) {\n errors[i] = t(\"environments.invalidKeyFormat\");\n } else if (seen.has(k)) {\n errors[i] = t(\"environments.duplicateKey\");\n }\n seen.add(k);\n }\n setKeyErrors(errors);\n return Object.keys(errors).length === 0;\n }, [workingRows]);\n\n const handleSave = useCallback(async () => {\n if (!validate()) return;\n const dict: Record = {};\n for (const r of workingRows) {\n dict[r.key.trim()] = r.value;\n }\n setSaving(true);\n try {\n await api.saveEnvs(dict);\n message.success(t(\"environments.saveSuccess\"));\n setRows(null);\n setKeyErrors({});\n setSelected(new Set());\n fetchAll();\n } catch (err) {\n const errMsg =\n err instanceof Error ? err.message : t(\"environments.saveFailed\");\n message.error(errMsg);\n } finally {\n setSaving(false);\n }\n }, [validate, workingRows, fetchAll]);\n\n const handleReset = useCallback(() => {\n setRows(null);\n setKeyErrors({});\n setSelected(new Set());\n }, []);\n\n /* ---- render ---- */\n\n return (\n
    \n {/* ---- Page header ---- */}\n \n\n {/* ---- Content ---- */}\n {loading ? (\n
    \n {t(\"environments.loading\")}\n
    \n ) : error ? (\n
    \n {error}\n \n
    \n ) : (\n
    \n {/* ---- Toolbar ---- */}\n \n\n {/* ---- Rows ---- */}\n
    \n {workingRows.map((row, idx) => (\n \n ))}\n\n {workingRows.length === 0 && }\n
    \n\n {/* ---- Add button ---- */}\n \n
    \n )}\n
    \n );\n}\n\nexport default EnvironmentsPage;\n" }, { "path": "console/src/pages/Settings/Environments/useEnvVars.ts", "content": "import { useState, useEffect, useCallback } from \"react\";\nimport api from \"../../../api\";\nimport type { EnvVar } from \"../../../api/types\";\n\nexport function useEnvVars() {\n const [envVars, setEnvVars] = useState([]);\n const [loading, setLoading] = useState(true);\n const [error, setError] = useState(null);\n\n const fetchAll = useCallback(async () => {\n setLoading(true);\n setError(null);\n try {\n const data = await api.listEnvs();\n if (data) setEnvVars(data);\n } catch (err) {\n const msg =\n err instanceof Error\n ? err.message\n : \"Failed to load environment variables\";\n console.error(\"Failed to load env vars:\", err);\n setError(msg);\n } finally {\n setLoading(false);\n }\n }, []);\n\n useEffect(() => {\n fetchAll();\n }, [fetchAll]);\n\n return { envVars, loading, error, fetchAll };\n}\n" }, { "path": "console/src/pages/Settings/Models/components/ModelManageModal.tsx", "content": "import { useState, useEffect, useCallback, useRef } from \"react\";\nimport {\n Button,\n Form,\n Input,\n Modal,\n Select,\n Tag,\n message,\n} from \"@agentscope-ai/design\";\nimport {\n CloseOutlined,\n DeleteOutlined,\n DownloadOutlined,\n LoadingOutlined,\n PlusOutlined,\n} from \"@ant-design/icons\";\nimport type {\n ProviderInfo,\n LocalModelResponse,\n DownloadTaskResponse,\n OllamaModelResponse,\n OllamaDownloadTaskResponse,\n} from \"../../../../api/types\";\nimport api from \"../../../../api\";\nimport { useTranslation } from \"react-i18next\";\nimport styles from \"../index.module.less\";\n\nconst POLL_INTERVAL_MS = 3000;\n\ninterface ModelManageModalProps {\n provider: ProviderInfo;\n open: boolean;\n onClose: () => void;\n onSaved: () => void;\n}\n\nfunction formatFileSize(bytes: number): string {\n if (bytes === 0) return \"0 B\";\n const units = [\"B\", \"KB\", \"MB\", \"GB\", \"TB\"];\n const i = Math.floor(Math.log(bytes) / Math.log(1024));\n return `${(bytes / Math.pow(1024, i)).toFixed(1)} ${units[i]}`;\n}\n\nexport function ModelManageModal({\n provider,\n open,\n onClose,\n onSaved,\n}: ModelManageModalProps) {\n const { t } = useTranslation();\n const [adding, setAdding] = useState(false);\n const [saving, setSaving] = useState(false);\n const [form] = Form.useForm();\n\n // --- Local provider state ---\n const [localModels, setLocalModels] = useState([]);\n const [loadingLocal, setLoadingLocal] = useState(false);\n const [activeTasks, setActiveTasks] = useState([]);\n const pollRef = useRef | null>(null);\n // Track task IDs we've already shown completion/failure messages for\n const notifiedRef = useRef>(new Set());\n\n // --- Ollama provider state ---\n const [ollamaModels, setOllamaModels] = useState([]);\n const [loadingOllama, setLoadingOllama] = useState(false);\n const [ollamaTasks, setOllamaTasks] = useState(\n [],\n );\n const ollamaPollRef = useRef | null>(null);\n const ollamaNotifiedRef = useRef>(new Set());\n\n const stopPolling = useCallback(() => {\n if (pollRef.current) {\n clearInterval(pollRef.current);\n pollRef.current = null;\n }\n }, []);\n\n const stopOllamaPolling = useCallback(() => {\n if (ollamaPollRef.current) {\n clearInterval(ollamaPollRef.current);\n ollamaPollRef.current = null;\n }\n }, []);\n\n const fetchLocalModels = useCallback(async () => {\n setLoadingLocal(true);\n try {\n const data = await api.listLocalModels(provider.id);\n setLocalModels(Array.isArray(data) ? data : []);\n } catch {\n setLocalModels([]);\n } finally {\n setLoadingLocal(false);\n }\n }, [provider.id]);\n\n const pollDownloads = useCallback(async () => {\n try {\n const tasks = await api.getDownloadStatus(provider.id);\n const active = tasks.filter(\n (t) => t.status === \"pending\" || t.status === \"downloading\",\n );\n const terminal = tasks.filter(\n (t) =>\n t.status === \"completed\" ||\n t.status === \"failed\" ||\n t.status === \"cancelled\",\n );\n\n // Notify for newly completed/failed/cancelled tasks\n let needsRefresh = false;\n for (const task of terminal) {\n if (!notifiedRef.current.has(task.task_id)) {\n notifiedRef.current.add(task.task_id);\n if (task.status === \"completed\") {\n message.success(t(\"models.localDownloadSuccess\"));\n needsRefresh = true;\n } else if (task.status === \"cancelled\") {\n message.info(t(\"models.localDownloadCancelled\"));\n } else {\n message.error(task.error || t(\"models.localDownloadFailed\"));\n }\n }\n }\n\n if (needsRefresh) {\n onSaved();\n fetchLocalModels();\n }\n\n setActiveTasks(active);\n\n // Stop polling when no active tasks remain\n if (active.length === 0) {\n stopPolling();\n }\n } catch {\n /* ignore polling errors */\n }\n }, [provider.id, t, onSaved, fetchLocalModels, stopPolling]);\n\n const startPolling = useCallback(() => {\n if (pollRef.current) return; // already polling\n pollRef.current = setInterval(pollDownloads, POLL_INTERVAL_MS);\n }, [pollDownloads]);\n\n // --- Ollama-specific fetch & poll functions ---\n\n const fetchOllamaModels = useCallback(async () => {\n setLoadingOllama(true);\n try {\n const data = await api.listOllamaModels();\n setOllamaModels(Array.isArray(data) ? data : []);\n } catch {\n setOllamaModels([]);\n } finally {\n setLoadingOllama(false);\n }\n }, []);\n\n const pollOllamaDownloads = useCallback(async () => {\n try {\n const tasksStatus = await api.getOllamaDownloadStatus();\n const tasks = Array.isArray(tasksStatus) ? tasksStatus : [];\n const active = tasks.filter(\n (t) => t.status === \"pending\" || t.status === \"downloading\",\n );\n const terminal = tasks.filter(\n (t) =>\n t.status === \"completed\" ||\n t.status === \"failed\" ||\n t.status === \"cancelled\",\n );\n\n let needsRefresh = false;\n for (const task of terminal) {\n if (!ollamaNotifiedRef.current.has(task.task_id)) {\n ollamaNotifiedRef.current.add(task.task_id);\n if (task.status === \"completed\") {\n message.success(t(\"models.localDownloadSuccess\"));\n needsRefresh = true;\n } else if (task.status === \"cancelled\") {\n message.info(t(\"models.localDownloadCancelled\"));\n } else {\n message.error(task.error || t(\"models.localDownloadFailed\"));\n }\n }\n }\n\n if (needsRefresh) {\n onSaved();\n fetchOllamaModels();\n }\n\n setOllamaTasks(active);\n\n if (active.length === 0) {\n stopOllamaPolling();\n }\n } catch {\n /* ignore polling errors */\n }\n }, [t, onSaved, fetchOllamaModels, stopOllamaPolling]);\n\n const startOllamaPolling = useCallback(() => {\n if (ollamaPollRef.current) return;\n ollamaPollRef.current = setInterval(pollOllamaDownloads, POLL_INTERVAL_MS);\n }, [pollOllamaDownloads]);\n\n // On open for local providers: fetch models and check for active downloads\n useEffect(() => {\n if (!open || !provider.is_local) return;\n\n fetchLocalModels();\n setAdding(false);\n form.resetFields();\n notifiedRef.current.clear();\n\n // Initial check\n api\n .getDownloadStatus(provider.id)\n .then((tasks) => {\n const taskList = Array.isArray(tasks) ? tasks : [];\n const active = taskList.filter(\n (t) => t.status === \"pending\" || t.status === \"downloading\",\n );\n setActiveTasks(active);\n if (active.length > 0) {\n startPolling();\n }\n })\n .catch(() => {});\n\n return () => stopPolling();\n }, [\n open,\n provider.is_local,\n provider.id,\n fetchLocalModels,\n form,\n startPolling,\n stopPolling,\n ]);\n\n // On open for Ollama provider: fetch models and check for active downloads\n useEffect(() => {\n if (!open || provider.id !== \"ollama\") return;\n\n fetchOllamaModels();\n setAdding(false);\n form.resetFields();\n ollamaNotifiedRef.current.clear();\n\n api\n .getOllamaDownloadStatus()\n .then((tasks) => {\n const active = tasks.filter(\n (t) => t.status === \"pending\" || t.status === \"downloading\",\n );\n setOllamaTasks(active);\n if (active.length > 0) {\n startOllamaPolling();\n }\n })\n .catch(() => {});\n\n return () => stopOllamaPolling();\n }, [\n open,\n provider.id,\n fetchOllamaModels,\n form,\n startOllamaPolling,\n stopOllamaPolling,\n ]);\n\n // --- Remote provider logic ---\n\n // For custom providers ALL models are deletable.\n // For built-in providers only extra_models are deletable.\n const extraModelIds = new Set(\n provider.is_custom\n ? provider.models.map((m) => m.id)\n : (provider.extra_models || []).map((m) => m.id),\n );\n\n const handleAddModel = async () => {\n try {\n const values = await form.validateFields();\n setSaving(true);\n const id = values.id.trim();\n const name = values.name?.trim() || id;\n await api.addModel(provider.id, { id, name });\n message.success(t(\"models.modelAdded\", { name }));\n form.resetFields();\n setAdding(false);\n onSaved();\n } catch (error) {\n if (error && typeof error === \"object\" && \"errorFields\" in error) return;\n const errMsg =\n error instanceof Error ? error.message : t(\"models.modelAddFailed\");\n message.error(errMsg);\n } finally {\n setSaving(false);\n }\n };\n\n const handleRemoveModel = (modelId: string, modelName: string) => {\n Modal.confirm({\n title: t(\"models.removeModel\"),\n content: t(\"models.removeModelConfirm\", {\n name: modelName,\n provider: provider.name,\n }),\n okText: t(\"common.delete\"),\n okButtonProps: { danger: true },\n cancelText: t(\"models.cancel\"),\n onOk: async () => {\n try {\n await api.removeModel(provider.id, modelId);\n message.success(t(\"models.modelRemoved\", { name: modelName }));\n onSaved();\n } catch (error) {\n const errMsg =\n error instanceof Error\n ? error.message\n : t(\"models.modelRemoveFailed\");\n message.error(errMsg);\n }\n },\n });\n };\n\n // --- Local provider: download & delete ---\n\n const handleDownload = async () => {\n try {\n const values = await form.validateFields();\n const task = await api.downloadModel({\n repo_id: values.repo_id.trim(),\n filename: values.filename?.trim() || undefined,\n backend: provider.id,\n source: values.source || \"huggingface\",\n });\n setActiveTasks((prev) => [...prev, task]);\n setAdding(false);\n form.resetFields();\n startPolling();\n } catch (error) {\n if (error && typeof error === \"object\" && \"errorFields\" in error) return;\n const errMsg =\n error instanceof Error ? error.message : t(\"models.downloadFailed\");\n message.error(errMsg);\n }\n };\n\n // --- Ollama provider: download & delete ---\n\n const handleOllamaDownload = async () => {\n try {\n const values = await form.validateFields();\n const task = await api.downloadOllamaModel({ name: values.name.trim() });\n setOllamaTasks((prev) => [...prev, task]);\n setAdding(false);\n form.resetFields();\n startOllamaPolling();\n } catch (error) {\n if (error && typeof error === \"object\" && \"errorFields\" in error) return;\n const errMsg =\n error instanceof Error ? error.message : t(\"models.downloadFailed\");\n message.error(errMsg);\n }\n };\n\n const handleOllamaDelete = (model: OllamaModelResponse) => {\n Modal.confirm({\n title: t(\"models.localDeleteModel\"),\n content: t(\"models.localDeleteConfirm\", { name: model.name }),\n okText: t(\"common.delete\"),\n okButtonProps: { danger: true },\n cancelText: t(\"models.cancel\"),\n onOk: async () => {\n try {\n await api.deleteOllamaModel(model.name);\n message.success(t(\"models.localModelDeleted\", { name: model.name }));\n onSaved();\n fetchOllamaModels();\n } catch (error) {\n const errMsg =\n error instanceof Error\n ? error.message\n : t(\"models.localDeleteFailed\");\n message.error(errMsg);\n }\n },\n });\n };\n\n const handleDeleteLocal = (model: LocalModelResponse) => {\n Modal.confirm({\n title: t(\"models.localDeleteModel\"),\n content: t(\"models.localDeleteConfirm\", { name: model.display_name }),\n okText: t(\"common.delete\"),\n okButtonProps: { danger: true },\n cancelText: t(\"models.cancel\"),\n onOk: async () => {\n try {\n await api.deleteLocalModel(model.id);\n message.success(\n t(\"models.localModelDeleted\", { name: model.display_name }),\n );\n onSaved();\n fetchLocalModels();\n } catch (error) {\n const errMsg =\n error instanceof Error\n ? error.message\n : t(\"models.localDeleteFailed\");\n message.error(errMsg);\n }\n },\n });\n };\n\n const handleCancelOllamaDownload = (task: OllamaDownloadTaskResponse) => {\n Modal.confirm({\n title: t(\"models.localCancelDownload\"),\n content: t(\"models.localCancelDownloadConfirm\", { repo: task.name }),\n okText: t(\"models.localCancelDownload\"),\n okButtonProps: { danger: true },\n cancelText: t(\"models.cancel\"),\n onOk: async () => {\n try {\n await api.cancelOllamaDownload(task.task_id);\n message.success(t(\"models.localDownloadCancelled\"));\n // Remove from active tasks immediately\n setOllamaTasks((prev) =>\n prev.filter((t) => t.task_id !== task.task_id),\n );\n } catch (error) {\n const errMsg =\n error instanceof Error\n ? error.message\n : t(\"models.localCancelDownloadFailed\");\n message.error(errMsg);\n }\n },\n });\n };\n\n const handleCancelDownload = (task: DownloadTaskResponse) => {\n Modal.confirm({\n title: t(\"models.localCancelDownload\"),\n content: t(\"models.localCancelDownloadConfirm\", { repo: task.repo_id }),\n okText: t(\"models.localCancelDownload\"),\n okButtonProps: { danger: true },\n cancelText: t(\"models.cancel\"),\n onOk: async () => {\n try {\n await api.cancelDownload(task.task_id);\n message.success(t(\"models.localDownloadCancelled\"));\n // Remove from active tasks immediately\n setActiveTasks((prev) =>\n prev.filter((t) => t.task_id !== task.task_id),\n );\n } catch (error) {\n const errMsg =\n error instanceof Error\n ? error.message\n : t(\"models.localCancelDownloadFailed\");\n message.error(errMsg);\n }\n },\n });\n };\n\n const handleClose = () => {\n setAdding(false);\n form.resetFields();\n onClose();\n };\n\n // --- Render: Ollama provider ---\n if (provider.id === \"ollama\") {\n return (\n \n {/* Active download statuses */}\n {ollamaTasks.map((task) => (\n \n \n \n {task.status === \"pending\"\n ? t(\"models.localDownloadPending\")\n : t(\"models.localDownloading\", { repo: task.name })}\n \n }\n onClick={() => handleCancelOllamaDownload(task)}\n style={{ marginLeft: \"auto\" }}\n />\n \n ))}\n\n {/* Downloaded models list */}\n
    \n {loadingOllama ? (\n
    {t(\"common.loading\")}
    \n ) : ollamaModels.length === 0 ? (\n
    \n {t(\"models.localNoModels\")}\n
    \n ) : (\n ollamaModels.map((m) => (\n
    \n
    \n {m.name}\n
    \n
    \n \n {formatFileSize(m.size)}\n \n }\n onClick={() => handleOllamaDelete(m)}\n />\n
    \n
    \n ))\n )}\n
    \n\n {/* Download form — always available */}\n {adding ? (\n
    \n
    \n \n \n \n \n {\n setAdding(false);\n form.resetFields();\n }}\n >\n {t(\"models.cancel\")}\n \n }\n >\n {t(\"models.localDownloadModel\")}\n \n
    \n \n \n ) : (\n }\n onClick={() => setAdding(true)}\n style={{ marginTop: 12 }}\n >\n {t(\"models.localDownloadModel\")}\n \n )}\n \n );\n }\n\n // --- Render: local provider ---\n if (provider.is_local) {\n return (\n \n {/* Active download statuses */}\n {activeTasks.map((task) => (\n \n \n \n {task.status === \"pending\"\n ? t(\"models.downloadPending\")\n : t(\"models.localDownloading\", { repo: task.repo_id })}\n \n }\n onClick={() => handleCancelDownload(task)}\n style={{ marginLeft: \"auto\" }}\n />\n \n ))}\n\n {/* Downloaded models list */}\n
    \n {loadingLocal ? (\n
    {t(\"common.loading\")}
    \n ) : localModels.length === 0 ? (\n
    \n {t(\"models.localNoModels\")}\n
    \n ) : (\n localModels.map((m) => (\n
    \n
    \n \n {m.display_name}\n \n \n {m.repo_id}/{m.filename} ·{\" \"}\n {formatFileSize(m.file_size)}\n \n
    \n
    \n \n {m.source === \"huggingface\" ? \"HF\" : \"MS\"}\n \n }\n onClick={() => handleDeleteLocal(m)}\n />\n
    \n
    \n ))\n )}\n
    \n\n {/* Download form — always available */}\n {adding ? (\n
    \n
    \n \n \n \n \n \n \n \n \n \n \n {\n setAdding(false);\n form.resetFields();\n }}\n >\n {t(\"models.cancel\")}\n \n }\n >\n {t(\"models.localDownloadModel\")}\n \n
    \n \n \n ) : (\n }\n onClick={() => setAdding(true)}\n style={{ marginTop: 12 }}\n >\n {t(\"models.localDownloadModel\")}\n \n )}\n \n );\n }\n\n // --- Remote provider ---\n const all_models = [\n ...(provider.models || []),\n ...(provider.extra_models || []),\n ];\n return (\n \n {/* Model list */}\n
    \n {all_models.length === 0 ? (\n
    {t(\"models.noModels\")}
    \n ) : (\n all_models.map((m) => {\n const isDeletable = extraModelIds.has(m.id);\n return (\n
    \n
    \n {m.name}\n {m.id}\n
    \n
    \n {isDeletable ? (\n <>\n \n {t(\"models.userAdded\")}\n \n }\n onClick={() => handleRemoveModel(m.id, m.name)}\n />\n \n ) : (\n \n {t(\"models.builtin\")}\n \n )}\n
    \n
    \n );\n })\n )}\n
    \n\n {/* Add model section */}\n {adding ? (\n
    \n
    \n \n \n \n \n \n \n \n {\n setAdding(false);\n form.resetFields();\n }}\n >\n {t(\"models.cancel\")}\n \n \n {t(\"models.addModel\")}\n \n
    \n \n \n ) : (\n }\n onClick={() => setAdding(true)}\n style={{ marginTop: 12 }}\n >\n {t(\"models.addModel\")}\n \n )}\n \n );\n}\n" }, { "path": "console/src/pages/Settings/Models/components/cards/LocalProviderCard.tsx", "content": "import { useState } from \"react\";\nimport { Card, Button, Tag } from \"@agentscope-ai/design\";\nimport { AppstoreOutlined } from \"@ant-design/icons\";\nimport type { ProviderInfo } from \"../../../../../api/types\";\nimport { ModelManageModal } from \"../modals/ModelManageModal\";\nimport { useTranslation } from \"react-i18next\";\nimport styles from \"../../index.module.less\";\n\ninterface LocalProviderCardProps {\n provider: ProviderInfo;\n onSaved: () => void;\n isHover: boolean;\n onMouseEnter: () => void;\n onMouseLeave: () => void;\n}\n\nexport function LocalProviderCard({\n provider,\n onSaved,\n isHover,\n onMouseEnter,\n onMouseLeave,\n}: LocalProviderCardProps) {\n const { t } = useTranslation();\n const [modelManageOpen, setModelManageOpen] = useState(false);\n\n const totalCount = provider.models.length + provider.extra_models.length;\n const statusReady = totalCount > 0;\n const statusLabel = statusReady\n ? t(\"models.available\")\n : t(\"models.unavailable\");\n\n return (\n \n
    \n
    \n \n {provider.name}\n \n {t(\"models.local\")}\n \n \n
    \n \n \n {statusLabel}\n \n
    \n
    \n\n
    \n
    \n {t(\"models.localType\")}:\n \n {t(\"models.localEmbedded\")}\n \n
    \n
    \n {t(\"models.model\")}:\n \n {totalCount > 0\n ? t(\"models.modelsCount\", { count: totalCount })\n : t(\"models.localDownloadFirst\")}\n \n
    \n
    \n
    \n\n
    \n {\n e.stopPropagation();\n setModelManageOpen(true);\n }}\n className={styles.configBtn}\n icon={}\n >\n {t(\"models.manageModels\")}\n \n
    \n\n setModelManageOpen(false)}\n onSaved={onSaved}\n />\n \n );\n}\n" }, { "path": "console/src/pages/Settings/Models/components/cards/ProviderCard.tsx", "content": "import type { ProviderInfo, ActiveModelsInfo } from \"../../../../../api/types\";\nimport { LocalProviderCard } from \"./LocalProviderCard\";\nimport { RemoteProviderCard } from \"./RemoteProviderCard\";\n\ninterface ProviderCardProps {\n provider: ProviderInfo;\n activeModels: ActiveModelsInfo | null;\n onSaved: () => void;\n isHover: boolean;\n onMouseEnter: () => void;\n onMouseLeave: () => void;\n}\n\nexport function ProviderCard({\n provider,\n activeModels,\n onSaved,\n isHover,\n onMouseEnter,\n onMouseLeave,\n}: ProviderCardProps) {\n if (provider.is_local) {\n return (\n \n );\n }\n\n return (\n \n );\n}\n" }, { "path": "console/src/pages/Settings/Models/components/cards/RemoteProviderCard.tsx", "content": "import { useState } from \"react\";\nimport { Card, Button, Tag, Modal, message } from \"@agentscope-ai/design\";\nimport {\n EditOutlined,\n DeleteOutlined,\n AppstoreOutlined,\n} from \"@ant-design/icons\";\nimport type { ProviderInfo, ActiveModelsInfo } from \"../../../../../api/types\";\nimport { ProviderConfigModal } from \"../modals/ProviderConfigModal\";\nimport { ModelManageModal } from \"../modals/ModelManageModal\";\nimport api from \"../../../../../api\";\nimport { useTranslation } from \"react-i18next\";\nimport styles from \"../../index.module.less\";\n\ninterface RemoteProviderCardProps {\n provider: ProviderInfo;\n activeModels: ActiveModelsInfo | null;\n onSaved: () => void;\n isHover: boolean;\n onMouseEnter: () => void;\n onMouseLeave: () => void;\n}\n\nexport function RemoteProviderCard({\n provider,\n activeModels,\n onSaved,\n isHover,\n onMouseEnter,\n onMouseLeave,\n}: RemoteProviderCardProps) {\n const { t } = useTranslation();\n const [modalOpen, setModalOpen] = useState(false);\n const [modelManageOpen, setModelManageOpen] = useState(false);\n\n const handleDeleteProvider = (e: React.MouseEvent) => {\n e.stopPropagation();\n Modal.confirm({\n title: t(\"models.deleteProvider\"),\n content: t(\"models.deleteProviderConfirm\", { name: provider.name }),\n okText: t(\"common.delete\"),\n okButtonProps: { danger: true },\n cancelText: t(\"models.cancel\"),\n onOk: async () => {\n try {\n await api.deleteCustomProvider(provider.id);\n message.success(t(\"models.providerDeleted\", { name: provider.name }));\n onSaved();\n } catch (error) {\n const errMsg =\n error instanceof Error\n ? error.message\n : t(\"models.providerDeleteFailed\");\n message.error(errMsg);\n }\n },\n });\n };\n\n const totalCount = provider.models.length + provider.extra_models.length;\n\n let isConfigured = false;\n\n if (provider.is_local) {\n isConfigured = true;\n } else if (provider.is_custom && provider.base_url) {\n isConfigured = true;\n } else if (provider.require_api_key === false) {\n isConfigured = true;\n } else if (provider.require_api_key && provider.api_key) {\n isConfigured = true;\n }\n\n const hasModels = totalCount > 0;\n const isAvailable = isConfigured && hasModels;\n\n const providerTag = provider.is_custom ? (\n \n {t(\"models.custom\")}\n \n ) : (\n \n {t(\"models.builtin\")}\n \n );\n\n const statusLabel = isAvailable\n ? t(\"models.providerAvailable\")\n : isConfigured\n ? t(\"models.providerNoModels\")\n : t(\"models.providerNotConfigured\");\n const statusType = isAvailable\n ? \"enabled\"\n : isConfigured\n ? \"partial\"\n : \"disabled\";\n const statusDotColor = isAvailable\n ? \"#52c41a\"\n : isConfigured\n ? \"#faad14\"\n : \"#d9d9d9\";\n const statusDotShadow = isAvailable\n ? \"0 0 0 2px rgba(82, 196, 26, 0.2)\"\n : isConfigured\n ? \"0 0 0 2px rgba(250, 173, 20, 0.2)\"\n : \"none\";\n\n return (\n \n
    \n
    \n \n {provider.name}\n {providerTag}\n \n
    \n \n \n {statusLabel}\n \n
    \n
    \n\n
    \n
    \n {t(\"models.baseURL\")}:\n {provider.base_url ? (\n \n {provider.base_url}\n \n ) : (\n {t(\"models.notSet\")}\n )}\n
    \n
    \n {t(\"models.apiKey\")}:\n {provider.api_key ? (\n {provider.api_key}\n ) : (\n {t(\"models.notSet\")}\n )}\n
    \n
    \n {t(\"models.model\")}:\n \n {totalCount > 0\n ? t(\"models.modelsCount\", { count: totalCount })\n : t(\"models.noModels\")}\n \n
    \n
    \n
    \n\n
    \n {\n e.stopPropagation();\n setModelManageOpen(true);\n }}\n className={styles.configBtn}\n icon={}\n >\n {t(\"models.manageModels\")}\n \n {\n e.stopPropagation();\n setModalOpen(true);\n }}\n className={styles.configBtn}\n icon={}\n >\n {t(\"models.settings\")}\n \n {provider.is_custom && (\n }\n >\n {t(\"models.deleteProvider\")}\n \n )}\n
    \n\n setModalOpen(false)}\n onSaved={onSaved}\n />\n setModelManageOpen(false)}\n onSaved={onSaved}\n />\n \n );\n}\n" }, { "path": "console/src/pages/Settings/Models/components/cards/index.ts", "content": "export * from \"./ProviderCard\";\nexport * from \"./LocalProviderCard\";\nexport * from \"./RemoteProviderCard\";\n" }, { "path": "console/src/pages/Settings/Models/components/index.ts", "content": "// Re-export all components from subdirectories\nexport * from \"./sections\";\nexport * from \"./cards\";\nexport * from \"./modals\";\n" }, { "path": "console/src/pages/Settings/Models/components/modals/CustomProviderModal.tsx", "content": "import { useState, useEffect } from \"react\";\nimport { Form, Input, Modal, Select, message } from \"@agentscope-ai/design\";\nimport api from \"../../../../../api\";\nimport { useTranslation } from \"react-i18next\";\n\ninterface CustomProviderModalProps {\n open: boolean;\n onClose: () => void;\n onSaved: () => void;\n}\n\nexport function CustomProviderModal({\n open,\n onClose,\n onSaved,\n}: CustomProviderModalProps) {\n const { t } = useTranslation();\n const [saving, setSaving] = useState(false);\n const [form] = Form.useForm();\n\n useEffect(() => {\n if (open) {\n form.resetFields();\n }\n }, [open, form]);\n\n const handleSubmit = async () => {\n try {\n const values = await form.validateFields();\n setSaving(true);\n await api.createCustomProvider({\n id: values.id.trim(),\n name: values.name.trim(),\n default_base_url: values.default_base_url?.trim() || \"\",\n api_key_prefix: values.api_key_prefix?.trim() || \"\",\n chat_model: values.chat_model || \"OpenAIChatModel\",\n });\n message.success(\n t(\"models.providerCreated\", { name: values.name.trim() }),\n );\n onSaved();\n onClose();\n } catch (error) {\n if (error && typeof error === \"object\" && \"errorFields\" in error) return;\n const errMsg =\n error instanceof Error\n ? error.message\n : t(\"models.providerCreateFailed\");\n message.error(errMsg);\n } finally {\n setSaving(false);\n }\n };\n\n return (\n \n \n \n \n \n\n \n \n \n\n \n \n \n\n \n \n \n \n \n );\n}\n" }, { "path": "console/src/pages/Settings/Models/components/modals/LocalModelManageModal.tsx", "content": "import { useState, useEffect, useCallback, useRef } from \"react\";\nimport {\n Button,\n Form,\n Input,\n Modal,\n Select,\n Tag,\n message,\n} from \"@agentscope-ai/design\";\nimport {\n CloseOutlined,\n DeleteOutlined,\n DownloadOutlined,\n LoadingOutlined,\n ApiOutlined,\n} from \"@ant-design/icons\";\nimport type {\n ProviderInfo,\n LocalModelResponse,\n DownloadTaskResponse,\n} from \"../../../../../api/types\";\nimport api from \"../../../../../api\";\nimport { useTranslation } from \"react-i18next\";\nimport styles from \"../../index.module.less\";\n\nconst POLL_INTERVAL_MS = 3000;\n\ninterface LocalModelManageModalProps {\n provider: ProviderInfo;\n open: boolean;\n onClose: () => void;\n onSaved: () => void;\n}\n\nfunction formatFileSize(bytes: number): string {\n if (bytes === 0) return \"0 B\";\n const units = [\"B\", \"KB\", \"MB\", \"GB\", \"TB\"];\n const i = Math.floor(Math.log(bytes) / Math.log(1024));\n return `${(bytes / Math.pow(1024, i)).toFixed(1)} ${units[i]}`;\n}\n\nexport function LocalModelManageModal({\n provider,\n open,\n onClose,\n onSaved,\n}: LocalModelManageModalProps) {\n const { t } = useTranslation();\n const [adding, setAdding] = useState(false);\n const [testingModelId, setTestingModelId] = useState(null);\n const [form] = Form.useForm();\n const [localModels, setLocalModels] = useState([]);\n const [loadingLocal, setLoadingLocal] = useState(false);\n const [activeTasks, setActiveTasks] = useState([]);\n const pollRef = useRef | null>(null);\n const notifiedRef = useRef>(new Set());\n\n const stopPolling = useCallback(() => {\n if (pollRef.current) {\n clearInterval(pollRef.current);\n pollRef.current = null;\n }\n }, []);\n\n const fetchLocalModels = useCallback(async () => {\n setLoadingLocal(true);\n try {\n const data = await api.listLocalModels(provider.id);\n setLocalModels(Array.isArray(data) ? data : []);\n } catch {\n setLocalModels([]);\n } finally {\n setLoadingLocal(false);\n }\n }, [provider.id]);\n\n const pollDownloads = useCallback(async () => {\n try {\n const tasks = await api.getDownloadStatus(provider.id);\n const active = tasks.filter(\n (t) => t.status === \"pending\" || t.status === \"downloading\",\n );\n const terminal = tasks.filter(\n (t) =>\n t.status === \"completed\" ||\n t.status === \"failed\" ||\n t.status === \"cancelled\",\n );\n\n let needsRefresh = false;\n for (const task of terminal) {\n if (!notifiedRef.current.has(task.task_id)) {\n notifiedRef.current.add(task.task_id);\n if (task.status === \"completed\") {\n message.success(t(\"models.localDownloadSuccess\"));\n needsRefresh = true;\n } else if (task.status === \"cancelled\") {\n message.info(t(\"models.localDownloadCancelled\"));\n } else {\n message.error(task.error || t(\"models.localDownloadFailed\"));\n }\n }\n }\n\n if (needsRefresh) {\n onSaved();\n fetchLocalModels();\n }\n\n setActiveTasks(active);\n\n if (active.length === 0) {\n stopPolling();\n }\n } catch {\n /* ignore polling errors */\n }\n }, [provider.id, t, onSaved, fetchLocalModels, stopPolling]);\n\n const startPolling = useCallback(() => {\n if (pollRef.current) return;\n pollRef.current = setInterval(pollDownloads, POLL_INTERVAL_MS);\n }, [pollDownloads]);\n\n useEffect(() => {\n if (!open) return;\n\n fetchLocalModels();\n setAdding(false);\n form.resetFields();\n notifiedRef.current.clear();\n\n api\n .getDownloadStatus(provider.id)\n .then((tasks) => {\n const taskList = Array.isArray(tasks) ? tasks : [];\n const active = taskList.filter(\n (t) => t.status === \"pending\" || t.status === \"downloading\",\n );\n setActiveTasks(active);\n if (active.length > 0) {\n startPolling();\n }\n })\n .catch(() => {});\n\n return () => stopPolling();\n }, [open, provider.id, fetchLocalModels, form, startPolling, stopPolling]);\n\n const handleDownload = async () => {\n try {\n const values = await form.validateFields();\n const task = await api.downloadModel({\n repo_id: values.repo_id.trim(),\n filename: values.filename?.trim() || undefined,\n backend: provider.id,\n source: values.source || \"huggingface\",\n });\n setActiveTasks((prev) => [...prev, task]);\n setAdding(false);\n form.resetFields();\n startPolling();\n } catch (error) {\n if (error && typeof error === \"object\" && \"errorFields\" in error) return;\n const errMsg =\n error instanceof Error ? error.message : t(\"models.downloadFailed\");\n message.error(errMsg);\n }\n };\n\n const handleDeleteLocal = (model: LocalModelResponse) => {\n Modal.confirm({\n title: t(\"models.localDeleteModel\"),\n content: t(\"models.localDeleteConfirm\", { name: model.display_name }),\n okText: t(\"common.delete\"),\n okButtonProps: { danger: true },\n cancelText: t(\"models.cancel\"),\n onOk: async () => {\n try {\n await api.deleteLocalModel(model.id);\n message.success(\n t(\"models.localModelDeleted\", { name: model.display_name }),\n );\n onSaved();\n fetchLocalModels();\n } catch (error) {\n const errMsg =\n error instanceof Error\n ? error.message\n : t(\"models.localDeleteFailed\");\n message.error(errMsg);\n }\n },\n });\n };\n\n const handleCancelDownload = (task: DownloadTaskResponse) => {\n Modal.confirm({\n title: t(\"models.localCancelDownload\"),\n content: t(\"models.localCancelDownloadConfirm\", { repo: task.repo_id }),\n okText: t(\"models.localCancelDownload\"),\n okButtonProps: { danger: true },\n cancelText: t(\"models.cancel\"),\n onOk: async () => {\n try {\n await api.cancelDownload(task.task_id);\n message.success(t(\"models.localDownloadCancelled\"));\n setActiveTasks((prev) =>\n prev.filter((t) => t.task_id !== task.task_id),\n );\n } catch (error) {\n const errMsg =\n error instanceof Error\n ? error.message\n : t(\"models.localCancelDownloadFailed\");\n message.error(errMsg);\n }\n },\n });\n };\n\n const handleTest = async (modelId: string) => {\n setTestingModelId(modelId);\n try {\n const result = await api.testModelConnection(provider.id, {\n model_id: modelId,\n });\n if (result.success) {\n message.success(result.message || t(\"models.testConnectionSuccess\"));\n // Refresh model list on successful test\n fetchLocalModels();\n } else {\n message.warning(result.message || t(\"models.testConnectionFailed\"));\n }\n } catch (error) {\n const errMsg =\n error instanceof Error\n ? error.message\n : t(\"models.testConnectionError\");\n message.error(errMsg);\n } finally {\n setTestingModelId(null);\n }\n };\n\n const handleClose = () => {\n setAdding(false);\n form.resetFields();\n onClose();\n };\n\n return (\n \n
    \n \n
    \n \n }\n width={600}\n destroyOnHidden\n >\n {/* Active download statuses */}\n {activeTasks.map((task) => (\n \n \n \n {task.status === \"pending\"\n ? t(\"models.downloadPending\")\n : t(\"models.localDownloading\", { repo: task.repo_id })}\n \n }\n onClick={() => handleCancelDownload(task)}\n style={{ marginLeft: \"auto\" }}\n />\n \n ))}\n\n {/* Downloaded models list */}\n
    \n {loadingLocal ? (\n
    {t(\"common.loading\")}
    \n ) : localModels.length === 0 ? (\n
    \n {t(\"models.localNoModels\")}\n
    \n ) : (\n localModels.map((m) => (\n
    \n
    \n \n {m.display_name}\n \n \n {m.repo_id}/{m.filename} ·{\" \"}\n {formatFileSize(m.file_size)}\n \n
    \n
    \n \n {m.source === \"huggingface\" ? \"HF\" : \"MS\"}\n \n }\n onClick={() => handleTest(m.id)}\n loading={testingModelId === m.id}\n style={{ marginRight: 4 }}\n >\n {t(\"models.testConnection\")}\n \n }\n onClick={() => handleDeleteLocal(m)}\n />\n
    \n
    \n ))\n )}\n
    \n\n {/* Download form */}\n {adding ? (\n
    \n
    \n \n \n \n \n \n \n \n \n \n \n {\n setAdding(false);\n form.resetFields();\n }}\n >\n {t(\"models.cancel\")}\n \n }\n >\n {t(\"models.localDownloadModel\")}\n \n
    \n \n \n ) : (\n }\n onClick={() => setAdding(true)}\n style={{ marginTop: 12 }}\n >\n {t(\"models.localDownloadModel\")}\n \n )}\n \n );\n}\n" }, { "path": "console/src/pages/Settings/Models/components/modals/ModelManageModal.tsx", "content": "import type { ProviderInfo } from \"../../../../../api/types\";\nimport { LocalModelManageModal } from \"./LocalModelManageModal\";\nimport { OllamaModelManageModal } from \"./OllamaModelManageModal\";\nimport { RemoteModelManageModal } from \"./RemoteModelManageModal\";\n\ninterface ModelManageModalProps {\n provider: ProviderInfo;\n open: boolean;\n onClose: () => void;\n onSaved: () => void;\n}\n\nexport function ModelManageModal({\n provider,\n open,\n onClose,\n onSaved,\n}: ModelManageModalProps) {\n // Route to the appropriate specialized modal based on provider type\n if (provider.id === \"ollama\") {\n return (\n \n );\n }\n\n if (provider.is_local) {\n return (\n \n );\n }\n\n return (\n \n );\n}\n" }, { "path": "console/src/pages/Settings/Models/components/modals/OllamaModelManageModal.tsx", "content": "import { useState, useEffect, useCallback, useRef } from \"react\";\nimport { Button, Form, Input, Modal, message } from \"@agentscope-ai/design\";\nimport {\n CloseOutlined,\n DeleteOutlined,\n DownloadOutlined,\n LoadingOutlined,\n ApiOutlined,\n SyncOutlined,\n} from \"@ant-design/icons\";\nimport type {\n ProviderInfo,\n OllamaModelResponse,\n OllamaDownloadTaskResponse,\n} from \"../../../../../api/types\";\nimport api from \"../../../../../api\";\nimport { useTranslation } from \"react-i18next\";\nimport styles from \"../../index.module.less\";\n\nconst POLL_INTERVAL_MS = 3000;\n\ninterface OllamaModelManageModalProps {\n provider: ProviderInfo;\n open: boolean;\n onClose: () => void;\n onSaved: () => void | Promise;\n}\n\nfunction formatFileSize(bytes: number): string {\n if (bytes === 0) return \"0 B\";\n const units = [\"B\", \"KB\", \"MB\", \"GB\", \"TB\"];\n const i = Math.floor(Math.log(bytes) / Math.log(1024));\n return `${(bytes / Math.pow(1024, i)).toFixed(1)} ${units[i]}`;\n}\n\nexport function OllamaModelManageModal({\n provider,\n open,\n onClose,\n onSaved,\n}: OllamaModelManageModalProps) {\n const { t } = useTranslation();\n const [adding, setAdding] = useState(false);\n const [testingModelId, setTestingModelId] = useState(null);\n const [discovering, setDiscovering] = useState(false);\n const [form] = Form.useForm();\n const [ollamaModels, setOllamaModels] = useState([]);\n const [loadingOllama, setLoadingOllama] = useState(false);\n const [ollamaTasks, setOllamaTasks] = useState(\n [],\n );\n const ollamaPollRef = useRef | null>(null);\n const ollamaNotifiedRef = useRef>(new Set());\n\n const stopOllamaPolling = useCallback(() => {\n if (ollamaPollRef.current) {\n clearInterval(ollamaPollRef.current);\n ollamaPollRef.current = null;\n }\n }, []);\n\n const fetchOllamaModels = useCallback(async () => {\n setLoadingOllama(true);\n setDiscovering(true);\n try {\n await api.discoverModels(provider.id);\n const data = await api.listOllamaModels();\n setOllamaModels(Array.isArray(data) ? data : []);\n } catch (error) {\n setOllamaModels([]);\n const errMsg =\n error instanceof Error\n ? error.message\n : t(\"models.ollamaFetchModelsFailed\");\n message.error(errMsg);\n } finally {\n onSaved();\n setDiscovering(false);\n setLoadingOllama(false);\n }\n }, [t, provider.id, onSaved]);\n\n const pollOllamaDownloads = useCallback(async () => {\n try {\n const tasksStatus = await api.getOllamaDownloadStatus();\n const tasks = Array.isArray(tasksStatus) ? tasksStatus : [];\n const active = tasks.filter(\n (t) => t.status === \"pending\" || t.status === \"downloading\",\n );\n const terminal = tasks.filter(\n (t) =>\n t.status === \"completed\" ||\n t.status === \"failed\" ||\n t.status === \"cancelled\",\n );\n\n let needsRefresh = false;\n for (const task of terminal) {\n if (!ollamaNotifiedRef.current.has(task.task_id)) {\n ollamaNotifiedRef.current.add(task.task_id);\n if (task.status === \"completed\") {\n message.success(t(\"models.localDownloadSuccess\"));\n needsRefresh = true;\n } else if (task.status === \"cancelled\") {\n message.info(t(\"models.localDownloadCancelled\"));\n } else {\n message.error(task.error || t(\"models.localDownloadFailed\"));\n }\n }\n }\n\n if (needsRefresh) {\n onSaved();\n fetchOllamaModels();\n }\n\n setOllamaTasks(active);\n\n if (active.length === 0) {\n stopOllamaPolling();\n }\n } catch {\n /* ignore polling errors */\n }\n }, [t, onSaved, fetchOllamaModels, stopOllamaPolling]);\n\n const startOllamaPolling = useCallback(() => {\n if (ollamaPollRef.current) return;\n ollamaPollRef.current = setInterval(pollOllamaDownloads, POLL_INTERVAL_MS);\n }, [pollOllamaDownloads]);\n\n useEffect(() => {\n if (!open) return;\n\n ollamaNotifiedRef.current.clear();\n\n api\n .getOllamaDownloadStatus()\n .then((tasks) => {\n const active = tasks.filter(\n (t) => t.status === \"pending\" || t.status === \"downloading\",\n );\n setOllamaTasks(active);\n if (active.length > 0) {\n startOllamaPolling();\n }\n })\n .catch(() => {});\n\n return () => stopOllamaPolling();\n }, [open, fetchOllamaModels, form, startOllamaPolling, stopOllamaPolling]);\n\n const handleOllamaDownload = async () => {\n try {\n const values = await form.validateFields();\n const task = await api.downloadOllamaModel({ name: values.name.trim() });\n setOllamaTasks((prev) => [...prev, task]);\n setAdding(false);\n form.resetFields();\n startOllamaPolling();\n } catch (error) {\n if (error && typeof error === \"object\" && \"errorFields\" in error) return;\n const errMsg =\n error instanceof Error ? error.message : t(\"models.downloadFailed\");\n message.error(errMsg);\n }\n };\n\n const handleOllamaDelete = (model: OllamaModelResponse) => {\n Modal.confirm({\n title: t(\"models.localDeleteModel\"),\n content: t(\"models.localDeleteConfirm\", { name: model.name }),\n okText: t(\"common.delete\"),\n okButtonProps: { danger: true },\n cancelText: t(\"models.cancel\"),\n onOk: async () => {\n try {\n await api.deleteOllamaModel(model.name);\n message.success(t(\"models.localModelDeleted\", { name: model.name }));\n onSaved();\n fetchOllamaModels();\n } catch (error) {\n const errMsg =\n error instanceof Error\n ? error.message\n : t(\"models.localDeleteFailed\");\n message.error(errMsg);\n }\n },\n });\n };\n\n const handleCancelOllamaDownload = (task: OllamaDownloadTaskResponse) => {\n Modal.confirm({\n title: t(\"models.localCancelDownload\"),\n content: t(\"models.localCancelDownloadConfirm\", { repo: task.name }),\n okText: t(\"models.localCancelDownload\"),\n okButtonProps: { danger: true },\n cancelText: t(\"models.cancel\"),\n onOk: async () => {\n try {\n await api.cancelOllamaDownload(task.task_id);\n message.success(t(\"models.localDownloadCancelled\"));\n setOllamaTasks((prev) =>\n prev.filter((t) => t.task_id !== task.task_id),\n );\n } catch (error) {\n const errMsg =\n error instanceof Error\n ? error.message\n : t(\"models.localCancelDownloadFailed\");\n message.error(errMsg);\n }\n },\n });\n };\n\n const handleTest = async (modelName: string) => {\n setTestingModelId(modelName);\n try {\n const result = await api.testModelConnection(provider.id, {\n model_id: modelName,\n });\n if (result.success) {\n message.success(result.message || t(\"models.testConnectionSuccess\"));\n // Refresh model list on successful test\n fetchOllamaModels();\n } else {\n message.warning(result.message || t(\"models.testConnectionFailed\"));\n }\n } catch (error) {\n const errMsg =\n error instanceof Error\n ? error.message\n : t(\"models.testConnectionError\");\n message.error(errMsg);\n } finally {\n setTestingModelId(null);\n }\n };\n\n const handleClose = () => {\n setAdding(false);\n form.resetFields();\n onClose();\n };\n\n return (\n \n
    \n \n
    \n \n }\n width={600}\n destroyOnHidden\n >\n {/* Active download statuses */}\n {ollamaTasks.map((task) => (\n \n \n \n {task.status === \"pending\"\n ? t(\"models.localDownloadPending\")\n : t(\"models.localDownloading\", { repo: task.name })}\n \n }\n onClick={() => handleCancelOllamaDownload(task)}\n style={{ marginLeft: \"auto\" }}\n />\n \n ))}\n\n {/* Downloaded models list */}\n
    \n {loadingOllama ? (\n
    {t(\"common.loading\")}
    \n ) : ollamaModels.length === 0 ? (\n
    \n {t(\"models.localNoModels\")}\n
    \n ) : (\n ollamaModels.map((m) => (\n
    \n
    \n {m.name}\n
    \n
    \n \n {formatFileSize(m.size)}\n \n }\n onClick={() => handleTest(m.name)}\n loading={testingModelId === m.name}\n style={{ marginRight: 4 }}\n >\n {t(\"models.testConnection\")}\n \n }\n onClick={() => handleOllamaDelete(m)}\n />\n
    \n
    \n ))\n )}\n
    \n\n {/* Download form */}\n {adding ? (\n
    \n
    \n \n \n \n \n {\n setAdding(false);\n form.resetFields();\n }}\n >\n {t(\"models.cancel\")}\n \n }\n >\n {t(\"models.localDownloadModel\")}\n \n
    \n \n \n ) : (\n
    \n }\n onClick={fetchOllamaModels}\n loading={discovering}\n style={{ flex: 1 }}\n >\n {t(\"models.discoverModels\")}\n \n }\n onClick={() => setAdding(true)}\n style={{ flex: 1 }}\n >\n {t(\"models.localDownloadModel\")}\n \n
    \n )}\n \n );\n}\n" }, { "path": "console/src/pages/Settings/Models/components/modals/ProviderConfigModal.tsx", "content": "import { useState, useEffect, useMemo, useRef } from \"react\";\nimport type { KeyboardEvent, ReactNode, UIEvent } from \"react\";\nimport {\n Form,\n Input,\n Modal,\n message,\n Button,\n Select,\n} from \"@agentscope-ai/design\";\nimport { ApiOutlined, DownOutlined, RightOutlined } from \"@ant-design/icons\";\nimport type { ProviderConfigRequest } from \"../../../../../api/types\";\nimport api from \"../../../../../api\";\nimport { useTranslation } from \"react-i18next\";\nimport styles from \"../../index.module.less\";\n\ninterface ProviderConfigFormValues\n extends Omit {\n generate_kwargs_text?: string;\n}\n\ninterface JsonCodeEditorProps {\n value?: string;\n onChange?: (value: string) => void;\n placeholder?: string;\n rows?: number;\n}\n\nfunction highlightJson(text: string): ReactNode[] {\n const tokens: ReactNode[] = [];\n const pattern =\n /(\"(?:\\\\.|[^\"\\\\])*\")(\\s*:)?|\\btrue\\b|\\bfalse\\b|\\bnull\\b|-?\\d+(?:\\.\\d+)?(?:[eE][+-]?\\d+)?|[{}\\[\\],:]/g;\n\n let lastIndex = 0;\n let match: RegExpExecArray | null;\n\n while ((match = pattern.exec(text)) !== null) {\n const [token, stringToken, keySuffix] = match;\n\n if (match.index > lastIndex) {\n tokens.push(text.slice(lastIndex, match.index));\n }\n\n if (stringToken) {\n tokens.push(\n \n {token}\n ,\n );\n } else if (token === \"true\" || token === \"false\") {\n tokens.push(\n \n {token}\n ,\n );\n } else if (token === \"null\") {\n tokens.push(\n \n {token}\n ,\n );\n } else if (/^-?\\d/.test(token)) {\n tokens.push(\n \n {token}\n ,\n );\n } else {\n tokens.push(\n \n {token}\n ,\n );\n }\n\n lastIndex = match.index + token.length;\n }\n\n if (lastIndex < text.length) {\n tokens.push(text.slice(lastIndex));\n }\n\n return tokens;\n}\n\nfunction JsonCodeEditor({\n value = \"\",\n onChange,\n placeholder,\n rows = 8,\n}: JsonCodeEditorProps) {\n const indentUnit = \" \";\n const highlightRef = useRef(null);\n const textareaRef = useRef(null);\n\n const handleScroll = (event: UIEvent) => {\n if (!highlightRef.current) {\n return;\n }\n\n highlightRef.current.scrollTop = event.currentTarget.scrollTop;\n highlightRef.current.scrollLeft = event.currentTarget.scrollLeft;\n };\n\n const handleKeyDown = (event: KeyboardEvent) => {\n if (event.key !== \"Tab\") {\n return;\n }\n\n event.preventDefault();\n\n const textarea = event.currentTarget;\n const selectionStart = textarea.selectionStart;\n const selectionEnd = textarea.selectionEnd;\n const hasSelection = selectionStart !== selectionEnd;\n const selectedText = value.slice(selectionStart, selectionEnd);\n\n if (!hasSelection || !selectedText.includes(\"\\n\")) {\n if (event.shiftKey) {\n const lineStart = value.lastIndexOf(\"\\n\", selectionStart - 1) + 1;\n const linePrefix = value.slice(lineStart, selectionStart);\n\n if (!linePrefix.endsWith(indentUnit)) {\n return;\n }\n\n const nextValue =\n value.slice(0, selectionStart - indentUnit.length) +\n value.slice(selectionStart);\n\n onChange?.(nextValue);\n\n requestAnimationFrame(() => {\n textareaRef.current?.setSelectionRange(\n selectionStart - indentUnit.length,\n selectionStart - indentUnit.length,\n );\n });\n return;\n }\n\n const nextValue =\n value.slice(0, selectionStart) + indentUnit + value.slice(selectionEnd);\n\n onChange?.(nextValue);\n\n requestAnimationFrame(() => {\n const nextCursor = selectionStart + indentUnit.length;\n textareaRef.current?.setSelectionRange(nextCursor, nextCursor);\n });\n return;\n }\n\n const lineStart = value.lastIndexOf(\"\\n\", selectionStart - 1) + 1;\n const block = value.slice(lineStart, selectionEnd);\n const lines = block.split(\"\\n\");\n\n if (event.shiftKey) {\n const updatedLines = lines.map((line) =>\n line.startsWith(indentUnit) ? line.slice(indentUnit.length) : line,\n );\n const removedFromFirstLine = lines[0].startsWith(indentUnit)\n ? indentUnit.length\n : 0;\n const removedTotal = lines.reduce(\n (total, line) =>\n total + (line.startsWith(indentUnit) ? indentUnit.length : 0),\n 0,\n );\n const nextValue =\n value.slice(0, lineStart) +\n updatedLines.join(\"\\n\") +\n value.slice(selectionEnd);\n\n onChange?.(nextValue);\n\n requestAnimationFrame(() => {\n textareaRef.current?.setSelectionRange(\n selectionStart - removedFromFirstLine,\n selectionEnd - removedTotal,\n );\n });\n return;\n }\n\n const updatedLines = lines.map((line) => `${indentUnit}${line}`);\n const nextValue =\n value.slice(0, lineStart) +\n updatedLines.join(\"\\n\") +\n value.slice(selectionEnd);\n\n onChange?.(nextValue);\n\n requestAnimationFrame(() => {\n textareaRef.current?.setSelectionRange(\n selectionStart + indentUnit.length,\n selectionEnd + indentUnit.length * lines.length,\n );\n });\n };\n\n return (\n
    \n \n {value ? highlightJson(value) : placeholder}\n {!value && {\"\\n\"}}\n
    \n onChange?.(event.target.value)}\n onKeyDown={handleKeyDown}\n onScroll={handleScroll}\n placeholder={placeholder}\n spellCheck={false}\n className={styles.jsonEditorTextarea}\n />\n \n );\n}\n\ninterface ProviderConfigModalProps {\n provider: {\n id: string;\n name: string;\n api_key?: string;\n api_key_prefix?: string;\n base_url?: string;\n is_custom: boolean;\n freeze_url: boolean;\n chat_model: string;\n support_connection_check: boolean;\n generate_kwargs: Record;\n };\n activeModels: any;\n open: boolean;\n onClose: () => void;\n onSaved: () => void;\n}\n\nexport function ProviderConfigModal({\n provider,\n activeModels,\n open,\n onClose,\n onSaved,\n}: ProviderConfigModalProps) {\n const { t } = useTranslation();\n const [saving, setSaving] = useState(false);\n const [testing, setTesting] = useState(false);\n const [formDirty, setFormDirty] = useState(false);\n const [advancedOpen, setAdvancedOpen] = useState(false);\n const [form] = Form.useForm();\n const selectedChatModel = Form.useWatch(\"chat_model\", form);\n const canEditBaseUrl = !provider.freeze_url;\n\n const parseGenerateConfig = (value?: string) => {\n const trimmed = value?.trim();\n if (!trimmed) {\n return undefined;\n }\n\n let parsed: unknown;\n try {\n parsed = JSON.parse(trimmed);\n } catch {\n throw new Error(t(\"models.generateConfigInvalidJson\"));\n }\n\n if (!parsed || typeof parsed !== \"object\" || Array.isArray(parsed)) {\n throw new Error(t(\"models.generateConfigMustBeObject\"));\n }\n\n return parsed as Record;\n };\n\n const effectiveChatModel = useMemo(() => {\n if (!provider.is_custom) {\n return provider.chat_model;\n }\n return selectedChatModel || provider.chat_model || \"OpenAIChatModel\";\n }, [provider.chat_model, provider.is_custom, selectedChatModel]);\n\n const apiKeyPlaceholder = useMemo(() => {\n if (provider.api_key) {\n return t(\"models.leaveBlankKeep\");\n }\n if (provider.api_key_prefix) {\n return t(\"models.enterApiKey\", { prefix: provider.api_key_prefix });\n }\n return t(\"models.enterApiKeyOptional\");\n }, [provider.api_key, provider.api_key_prefix, t]);\n\n const baseUrlExtra = useMemo(() => {\n if (!canEditBaseUrl) {\n return undefined;\n }\n if (provider.id === \"azure-openai\") {\n return t(\"models.azureEndpointHint\");\n }\n if (provider.id === \"anthropic\") {\n return t(\"models.anthropicEndpointHint\");\n }\n if (provider.id === \"openai\") {\n return t(\"models.openAIEndpoint\");\n }\n if (provider.id === \"ollama\") {\n return t(\"models.ollamaEndpointHint\");\n }\n if (provider.id === \"lmstudio\") {\n return t(\"models.lmstudioEndpointHint\");\n }\n if (provider.is_custom) {\n return effectiveChatModel === \"AnthropicChatModel\"\n ? t(\"models.anthropicEndpointHint\")\n : t(\"models.openAICompatibleEndpoint\");\n }\n return t(\"models.apiEndpointHint\");\n }, [canEditBaseUrl, provider.id, provider.is_custom, effectiveChatModel, t]);\n\n const baseUrlPlaceholder = useMemo(() => {\n if (!canEditBaseUrl) {\n return \"\";\n }\n if (provider.id === \"azure-openai\") {\n return \"https://.openai.azure.com/openai/v1\";\n }\n if (provider.id === \"anthropic\") {\n return \"https://api.anthropic.com\";\n }\n if (provider.id === \"openai\") {\n return \"https://api.openai.com/v1\";\n }\n if (provider.id === \"ollama\") {\n return \"http://localhost:11434\";\n }\n if (provider.id === \"lmstudio\") {\n return \"http://localhost:1234/v1\";\n }\n if (provider.is_custom && effectiveChatModel === \"AnthropicChatModel\") {\n return \"https://api.anthropic.com\";\n }\n return \"https://api.example.com\";\n }, [canEditBaseUrl, provider.id, provider.is_custom, effectiveChatModel]);\n\n // Sync form when modal opens or provider data changes\n useEffect(() => {\n if (open) {\n form.setFieldsValue({\n api_key: undefined,\n base_url: provider.base_url || undefined,\n chat_model: provider.chat_model || \"OpenAIChatModel\",\n generate_kwargs_text:\n provider.generate_kwargs &&\n Object.keys(provider.generate_kwargs).length > 0\n ? JSON.stringify(provider.generate_kwargs, null, 2)\n : undefined,\n });\n setAdvancedOpen(false);\n setFormDirty(false);\n }\n }, [provider, form, open]);\n\n const handleSubmit = async () => {\n try {\n const values = await form.validateFields();\n setSaving(true);\n const generateConfig = parseGenerateConfig(values.generate_kwargs_text);\n const hasGenerateConfigInput = Boolean(\n values.generate_kwargs_text?.trim(),\n );\n\n // Validate connection before saving\n // For local providers, we might skip this or just check if models exist (which the backend does)\n if (provider.support_connection_check) {\n const result = await api.testProviderConnection(provider.id, {\n api_key: values.api_key,\n base_url: values.base_url,\n chat_model: values.chat_model,\n });\n\n if (!result.success) {\n message.error(result.message || t(\"models.testConnectionFailed\"));\n // For built-in providers, we want to enforce valid config before saving\n return;\n }\n }\n\n await api.configureProvider(provider.id, {\n api_key: values.api_key,\n base_url: values.base_url,\n chat_model: values.chat_model,\n generate_kwargs: hasGenerateConfigInput ? generateConfig : {},\n });\n\n await onSaved();\n setFormDirty(false);\n onClose();\n message.success(t(\"models.configurationSaved\", { name: provider.name }));\n } catch (error) {\n if (error && typeof error === \"object\" && \"errorFields\" in error) return;\n const errMsg =\n error instanceof Error ? error.message : t(\"models.failedToSaveConfig\");\n message.error(errMsg);\n } finally {\n setSaving(false);\n }\n };\n\n const handleTest = async () => {\n setTesting(true);\n try {\n const values = await form.validateFields([\n \"api_key\",\n \"base_url\",\n \"chat_model\",\n ]);\n const result = await api.testProviderConnection(provider.id, {\n api_key: values.api_key,\n base_url: values.base_url,\n chat_model: values.chat_model,\n });\n if (result.success) {\n message.success(result.message || t(\"models.testConnectionSuccess\"));\n } else {\n message.warning(result.message || t(\"models.testConnectionFailed\"));\n }\n } catch (error) {\n if (error && typeof error === \"object\" && \"errorFields\" in error) return;\n const errMsg =\n error instanceof Error\n ? error.message\n : t(\"models.testConnectionError\");\n message.error(errMsg);\n } finally {\n setTesting(false);\n }\n };\n\n const isActiveLlmProvider =\n activeModels?.active_llm?.provider_id === provider.id;\n\n const handleRevoke = () => {\n const confirmContent = isActiveLlmProvider\n ? t(\"models.revokeConfirmContent\", { name: provider.name })\n : t(\"models.revokeConfirmSimple\", { name: provider.name });\n\n Modal.confirm({\n title: t(\"models.revokeAuthorization\"),\n content: confirmContent,\n okText: t(\"models.revokeAuthorization\"),\n okButtonProps: { danger: true },\n cancelText: t(\"models.cancel\"),\n onOk: async () => {\n try {\n await api.configureProvider(provider.id, { api_key: \"\" });\n await onSaved();\n onClose();\n if (isActiveLlmProvider) {\n message.success(\n t(\"models.authorizationRevoked\", { name: provider.name }),\n );\n } else {\n message.success(\n t(\"models.authorizationRevokedSimple\", { name: provider.name }),\n );\n }\n } catch (error) {\n const errMsg =\n error instanceof Error ? error.message : t(\"models.failedToRevoke\");\n message.error(errMsg);\n }\n },\n });\n };\n\n return (\n \n
    \n {provider.api_key && (\n \n )}\n {provider.support_connection_check && (\n }\n onClick={handleTest}\n loading={testing}\n >\n {t(\"models.testConnection\")}\n \n )}\n
    \n
    \n \n \n {t(\"models.save\")}\n \n
    \n \n }\n destroyOnHidden\n >\n 0\n ? JSON.stringify(provider.generate_kwargs, null, 2)\n : undefined,\n }}\n onValuesChange={() => setFormDirty(true)}\n >\n {provider.is_custom && (\n \n \n \n )}\n\n {/* Base URL */}\n {\n if (!value || !value.trim()) return Promise.resolve();\n try {\n const url = new URL(value.trim());\n if (![\"http:\", \"https:\"].includes(url.protocol)) {\n return Promise.reject(\n new Error(t(\"models.pleaseEnterValidURL\")),\n );\n }\n return Promise.resolve();\n } catch {\n return Promise.reject(\n new Error(t(\"models.pleaseEnterValidURL\")),\n );\n }\n },\n },\n ]\n : []\n }\n extra={baseUrlExtra}\n >\n \n \n\n {/* API Key */}\n {\n if (\n value &&\n provider.api_key_prefix &&\n !value.startsWith(provider.api_key_prefix)\n ) {\n return Promise.reject(\n new Error(\n t(\"models.apiKeyShouldStart\", {\n prefix: provider.api_key_prefix,\n }),\n ),\n );\n }\n return Promise.resolve();\n },\n },\n ]}\n >\n \n \n\n
    \n setAdvancedOpen((prev) => !prev)}\n >\n \n {advancedOpen ? : }\n {t(\"models.advancedConfig\")}\n \n \n\n
    \n \n \n );\n}\n" }, { "path": "console/src/pages/Settings/Models/components/modals/RemoteModelManageModal.tsx", "content": "import { useState, useEffect } from \"react\";\nimport {\n Button,\n Form,\n Input,\n Modal,\n Tag,\n message,\n} from \"@agentscope-ai/design\";\nimport {\n DeleteOutlined,\n PlusOutlined,\n ApiOutlined,\n SyncOutlined,\n} from \"@ant-design/icons\";\nimport type { ProviderInfo } from \"../../../../../api/types\";\nimport api from \"../../../../../api\";\nimport { useTranslation } from \"react-i18next\";\nimport { useTheme } from \"../../../../../contexts/ThemeContext\";\nimport styles from \"../../index.module.less\";\n\ninterface RemoteModelManageModalProps {\n provider: ProviderInfo;\n open: boolean;\n onClose: () => void;\n onSaved: () => void | Promise;\n}\n\nexport function RemoteModelManageModal({\n provider,\n open,\n onClose,\n onSaved,\n}: RemoteModelManageModalProps) {\n const { t } = useTranslation();\n const { isDark } = useTheme();\n const [adding, setAdding] = useState(false);\n const [saving, setSaving] = useState(false);\n const [discovering, setDiscovering] = useState(false);\n const [testingModelId, setTestingModelId] = useState(null);\n const [form] = Form.useForm();\n const canDiscover = provider.support_model_discovery;\n\n // For custom providers ALL models are deletable.\n // For built-in providers only extra_models are deletable.\n const extraModelIds = new Set((provider.extra_models || []).map((m) => m.id));\n\n const doAddModel = async (id: string, name: string) => {\n await api.addModel(provider.id, { id, name });\n message.success(t(\"models.modelAdded\", { name }));\n form.resetFields();\n setAdding(false);\n onSaved();\n };\n\n const handleAddModel = async () => {\n try {\n const values = await form.validateFields();\n const id = values.id.trim();\n const name = values.name?.trim() || id;\n\n // Step 1: Test the model connection first\n setSaving(true);\n const testResult = await api.testModelConnection(provider.id, {\n model_id: id,\n });\n\n if (!testResult.success) {\n // Test failed – ask user whether to proceed anyway\n setSaving(false);\n Modal.confirm({\n title: t(\"models.testConnectionFailed\"),\n content: t(\"models.modelTestFailedConfirm\", {\n message: testResult.message || t(\"models.modelTestFailed\"),\n }),\n okText: t(\"models.addModel\"),\n cancelText: t(\"models.cancel\"),\n onOk: async () => {\n setSaving(true);\n try {\n await doAddModel(id, name);\n } catch (error) {\n const errMsg =\n error instanceof Error\n ? error.message\n : t(\"models.modelAddFailed\");\n message.error(errMsg);\n } finally {\n setSaving(false);\n }\n },\n });\n return;\n }\n\n // Step 2: If test passed, add the model\n await doAddModel(id, name);\n } catch (error) {\n if (error && typeof error === \"object\" && \"errorFields\" in error) return;\n const errMsg =\n error instanceof Error ? error.message : t(\"models.modelAddFailed\");\n message.error(errMsg);\n } finally {\n setSaving(false);\n }\n };\n\n const handleTestModel = async (modelId: string) => {\n setTestingModelId(modelId);\n try {\n const result = await api.testModelConnection(provider.id, {\n model_id: modelId,\n });\n if (result.success) {\n message.success(result.message || t(\"models.testConnectionSuccess\"));\n } else {\n message.warning(result.message || t(\"models.testConnectionFailed\"));\n }\n } catch (error) {\n const errMsg =\n error instanceof Error\n ? error.message\n : t(\"models.testConnectionError\");\n message.error(errMsg);\n } finally {\n setTestingModelId(null);\n }\n };\n\n const handleRemoveModel = (modelId: string, modelName: string) => {\n Modal.confirm({\n title: t(\"models.removeModel\"),\n content: t(\"models.removeModelConfirm\", {\n name: modelName,\n provider: provider.name,\n }),\n okText: t(\"common.delete\"),\n okButtonProps: { danger: true },\n cancelText: t(\"models.cancel\"),\n onOk: async () => {\n try {\n await api.removeModel(provider.id, modelId);\n message.success(t(\"models.modelRemoved\", { name: modelName }));\n await onSaved();\n } catch (error) {\n const errMsg =\n error instanceof Error\n ? error.message\n : t(\"models.modelRemoveFailed\");\n message.error(errMsg);\n }\n },\n });\n };\n\n const handleClose = () => {\n setAdding(false);\n form.resetFields();\n onClose();\n };\n\n const handleDiscoverModels = async () => {\n setDiscovering(true);\n try {\n const result = await api.discoverModels(provider.id);\n if (!result.success) {\n message.warning(result.message || t(\"models.discoverModelsFailed\"));\n return;\n }\n\n if (result.added_count > 0) {\n message.success(\n t(\"models.autoDiscoveredAndAdded\", {\n count: result.models.length,\n added: result.added_count,\n }),\n );\n await onSaved();\n } else if (result.models.length > 0) {\n message.info(\n t(\"models.autoDiscoveredNoNew\", { count: result.models.length }),\n );\n await onSaved();\n } else {\n message.info(result.message || t(\"models.noModels\"));\n }\n } catch (error) {\n const errMsg =\n error instanceof Error\n ? error.message\n : t(\"models.discoverModelsFailed\");\n message.error(errMsg);\n } finally {\n setDiscovering(false);\n }\n };\n\n useEffect(() => {\n // Do not auto-discover models when modal opens, as it may take some time and we don't want to block the UI.\n // Instead, users can click the \"Discover Models\" button to trigger discovery when needed.\n }, [open, canDiscover, provider.id, provider.models.length]);\n\n const all_models = [\n ...(provider.models ?? []),\n ...(provider.extra_models ?? []),\n ];\n\n return (\n \n
    \n \n
    \n \n }\n width={560}\n destroyOnHidden\n >\n {/* Model list */}\n
    \n {all_models.length === 0 ? (\n
    {t(\"models.noModels\")}
    \n ) : (\n all_models.map((m) => {\n const isDeletable = extraModelIds.has(m.id);\n return (\n
    \n
    \n {m.name}\n {m.id}\n
    \n
    \n {isDeletable ? (\n <>\n \n {t(\"models.userAdded\")}\n \n }\n onClick={() => handleTestModel(m.id)}\n loading={testingModelId === m.id}\n style={{\n marginRight: 4,\n color: isDark ? \"rgba(255,255,255,0.65)\" : undefined,\n }}\n >\n {t(\"models.testConnection\")}\n \n }\n onClick={() => handleRemoveModel(m.id, m.name)}\n />\n \n ) : (\n <>\n \n {t(\"models.builtin\")}\n \n }\n onClick={() => handleTestModel(m.id)}\n loading={testingModelId === m.id}\n style={{\n color: isDark ? \"rgba(255,255,255,0.65)\" : undefined,\n }}\n >\n {t(\"models.testConnection\")}\n \n \n )}\n
    \n
    \n );\n })\n )}\n
    \n\n {/* Add model section */}\n {adding ? (\n
    \n
    \n \n \n \n \n \n \n \n {\n setAdding(false);\n form.resetFields();\n }}\n >\n {t(\"models.cancel\")}\n \n \n {t(\"models.addModel\")}\n \n
    \n \n \n ) : (\n
    \n }\n onClick={handleDiscoverModels}\n loading={discovering}\n disabled={!canDiscover}\n style={{ flex: 1 }}\n >\n {t(\"models.discoverModels\")}\n \n }\n onClick={() => setAdding(true)}\n style={{ flex: 1 }}\n >\n {t(\"models.addModel\")}\n \n
    \n )}\n \n );\n}\n" }, { "path": "console/src/pages/Settings/Models/components/modals/index.ts", "content": "export * from \"./CustomProviderModal\";\nexport * from \"./ProviderConfigModal\";\nexport * from \"./ModelManageModal\";\nexport * from \"./LocalModelManageModal\";\nexport * from \"./OllamaModelManageModal\";\nexport * from \"./RemoteModelManageModal\";\n" }, { "path": "console/src/pages/Settings/Models/components/sections/LoadingState.tsx", "content": "import { Button } from \"@agentscope-ai/design\";\nimport { useTranslation } from \"react-i18next\";\nimport styles from \"../../index.module.less\";\n\ninterface LoadingStateProps {\n message: string;\n error?: boolean;\n onRetry?: () => void;\n className?: string;\n}\n\nexport function LoadingState({\n message,\n error,\n onRetry,\n className,\n}: LoadingStateProps) {\n const { t } = useTranslation();\n\n return (\n
    \n \n {message}\n \n {error && onRetry && (\n \n )}\n
    \n );\n}\n" }, { "path": "console/src/pages/Settings/Models/components/sections/ModelsSection.tsx", "content": "import { useState, useEffect, useMemo } from \"react\";\nimport { SaveOutlined } from \"@ant-design/icons\";\nimport { Select, Button, message } from \"@agentscope-ai/design\";\nimport type { ModelSlotRequest } from \"../../../../../api/types\";\nimport api from \"../../../../../api\";\nimport { useTranslation } from \"react-i18next\";\nimport styles from \"../../index.module.less\";\n\ninterface ModelsSectionProps {\n providers: Array<{\n id: string;\n name: string;\n models?: Array<{ id: string; name: string }>;\n extra_models?: Array<{ id: string; name: string }>;\n base_url?: string;\n api_key?: string;\n is_custom: boolean;\n is_local?: boolean;\n require_api_key?: boolean;\n }>;\n activeModels: {\n active_llm?: {\n provider_id?: string;\n model?: string;\n };\n } | null;\n onSaved: () => void;\n}\n\nexport function ModelsSection({\n providers,\n activeModels,\n onSaved,\n}: ModelsSectionProps) {\n const { t } = useTranslation();\n const [saving, setSaving] = useState(false);\n const [selectedProviderId, setSelectedProviderId] = useState<\n string | undefined\n >(undefined);\n const [selectedModel, setSelectedModel] = useState(\n undefined,\n );\n const [dirty, setDirty] = useState(false);\n\n const currentSlot = activeModels?.active_llm;\n\n const eligible = useMemo(\n () =>\n providers.filter((p) => {\n const hasModels =\n (p.models?.length ?? 0) + (p.extra_models?.length ?? 0) > 0;\n if (!hasModels) return false;\n if (p.is_local) return true;\n if (p.require_api_key === false) return !!p.base_url;\n if (p.is_custom) return !!p.base_url;\n if (p.require_api_key ?? true) return !!p.api_key;\n return true;\n }),\n [providers],\n );\n\n useEffect(() => {\n if (currentSlot) {\n setSelectedProviderId(currentSlot.provider_id || undefined);\n setSelectedModel(currentSlot.model || undefined);\n }\n setDirty(false);\n }, [currentSlot?.provider_id, currentSlot?.model]);\n\n const chosenProvider = providers.find((p) => p.id === selectedProviderId);\n const modelOptions = [\n ...(chosenProvider?.models ?? []),\n ...(chosenProvider?.extra_models ?? []),\n ];\n const hasModels = modelOptions.length > 0;\n\n const handleProviderChange = (pid: string) => {\n setSelectedProviderId(pid);\n setSelectedModel(undefined);\n setDirty(true);\n };\n\n const handleModelChange = (model: string) => {\n setSelectedModel(model);\n setDirty(true);\n };\n\n const handleSave = async () => {\n if (!selectedProviderId || !selectedModel) return;\n\n const body: ModelSlotRequest = {\n provider_id: selectedProviderId,\n model: selectedModel,\n };\n\n setSaving(true);\n try {\n await api.setActiveLlm(body);\n message.success(t(\"models.llmModelUpdated\"));\n setDirty(false);\n onSaved();\n } catch (error) {\n const errMsg =\n error instanceof Error ? error.message : t(\"models.failedToSave\");\n message.error(errMsg);\n } finally {\n setSaving(false);\n }\n };\n\n const isActive =\n currentSlot &&\n currentSlot.provider_id === selectedProviderId &&\n currentSlot.model === selectedModel;\n const canSave = dirty && !!selectedProviderId && !!selectedModel;\n\n return (\n
    \n
    \n

    {t(\"models.llmConfiguration\")}

    \n {currentSlot?.provider_id && currentSlot?.model && (\n \n {t(\"models.active\", {\n provider: currentSlot.provider_id,\n model: currentSlot.model,\n })}\n \n )}\n
    \n\n
    \n
    \n \n ({\n value: p.id,\n label: p.name,\n }))}\n />\n
    \n\n
    \n \n ({\n value: m.id,\n label: `${m.name} (${m.id})`,\n }))}\n />\n
    \n\n \n \n }\n >\n {isActive ? t(\"models.saved\") : t(\"models.save\")}\n \n
    \n
    \n \n );\n}\n" }, { "path": "console/src/pages/Settings/Models/components/sections/PageHeader.tsx", "content": "import styles from \"../../index.module.less\";\n\ninterface PageHeaderProps {\n title: string;\n description: string;\n className?: string;\n}\n\nexport function PageHeader({ title, description, className }: PageHeaderProps) {\n return (\n
    \n

    {title}

    \n

    {description}

    \n
    \n );\n}\n" }, { "path": "console/src/pages/Settings/Models/components/sections/index.ts", "content": "export * from \"./PageHeader\";\nexport * from \"./LoadingState\";\nexport * from \"./ModelsSection\";\n" }, { "path": "console/src/pages/Settings/Models/index.module.less", "content": ".settingsPage {\n padding: 24px;\n}\n\n.loading {\n text-align: center;\n padding: 60px;\n}\n\n.loadingText {\n color: #999;\n}\n\n/* ---- Sections ---- */\n\n.section {\n margin-bottom: 32px;\n}\n\n.section:last-child {\n margin-bottom: 0;\n}\n\n.sectionTitle {\n margin-bottom: 4px;\n font-size: 24px;\n font-weight: 600;\n}\n\n.sectionDesc {\n margin: 0 0 24px;\n color: #999;\n font-size: 14px;\n}\n\n/* ---- Providers Block (LLM below, providers below) ---- */\n\n.providersBlock {\n margin-top: 32px;\n}\n\n/* ---- Provider Groups ---- */\n\n.providerGroup {\n margin-bottom: 24px;\n\n &:last-of-type {\n margin-bottom: 0;\n }\n}\n\n.providerGroupTitle {\n font-size: 14px;\n font-weight: 600;\n color: #666;\n margin: 0 0 12px;\n letter-spacing: 0.02em;\n}\n\n/* ---- Provider Cards ---- */\n\n.providerCards {\n display: flex;\n gap: 16px;\n margin-bottom: 16px;\n flex-wrap: wrap;\n align-items: stretch;\n}\n\n.providerCard {\n flex: 1 1 calc(33.333% - 16px);\n min-width: 432px;\n border-radius: 16px;\n transition: all 0.2s ease-in-out;\n cursor: pointer;\n position: relative;\n overflow: visible;\n background: #fff;\n display: flex;\n flex-direction: column;\n\n &.enabledCard {\n border: 2px solid #615ced !important;\n box-shadow: rgba(97, 92, 237, 0.2) 0px 8px 24px !important;\n }\n\n &.hover {\n border: 1px solid #615ced;\n box-shadow: 0 12px 32px rgba(0, 0, 0, 0.08);\n }\n\n &.normal {\n border: 1px solid rgba(0, 0, 0, 0.04);\n box-shadow: 0 4px 12px rgba(0, 0, 0, 0.04);\n }\n\n :global(.ant-card-body) {\n display: flex;\n flex-direction: column;\n flex: 1;\n height: 100%;\n }\n}\n\n.statusContainer {\n display: flex;\n align-items: center;\n gap: 8px;\n\n .statusText {\n font-size: 12px;\n font-weight: 500;\n\n &.enabled {\n color: #52c41a;\n }\n\n &.partial {\n color: #faad14;\n }\n\n &.disabled {\n color: #999;\n }\n }\n}\n\n.cardBody {\n padding: 20px 24px;\n}\n\n.cardHeader {\n margin-bottom: 14px;\n display: flex;\n align-items: center;\n justify-content: space-between;\n\n :global {\n .ant-badge-status-success .ant-badge-status-text {\n color: #52c41a !important;\n }\n\n .ant-badge-status-error .ant-badge-status-text {\n color: #ff4d4f !important;\n }\n }\n}\n\n.cardName {\n font-size: 18px;\n font-weight: 600;\n color: #1a1a1a;\n}\n\n.cardInfo {\n display: flex;\n flex-direction: column;\n gap: 6px;\n margin-bottom: 16px;\n min-height: 66px;\n}\n\n.infoRow {\n display: flex;\n align-items: center;\n gap: 8px;\n font-size: 13px;\n color: #666;\n}\n\n.infoLabel {\n color: #999;\n min-width: 70px;\n flex-shrink: 0;\n font-weight: 500;\n}\n\n.infoValue {\n color: #333;\n font-family: \"SF Mono\", \"Menlo\", monospace;\n font-size: 12px;\n overflow: hidden;\n text-overflow: ellipsis;\n white-space: nowrap;\n flex: 1;\n min-width: 0;\n max-width: calc(100% - 80px);\n text-align: left;\n}\n\n.infoEmpty {\n color: #ccc;\n font-style: italic;\n}\n\n.cardActions {\n display: flex;\n align-items: center;\n justify-content: flex-end;\n gap: 8px;\n padding-top: 14px;\n border-top: 1px solid #f0f0f0;\n}\n\n.configBtn {\n display: inline-flex;\n align-items: center;\n justify-content: center;\n gap: 6px;\n padding: 6px 14px;\n color: #555;\n font-size: 13px;\n cursor: pointer;\n transition: all 0.2s;\n line-height: 1;\n white-space: nowrap;\n}\n\n/* ---- Modal Footer ---- */\n\n.modalFooter {\n display: flex;\n justify-content: space-between;\n align-items: center;\n}\n\n.modalFooterLeft {\n display: flex;\n align-items: center;\n gap: 8px;\n}\n\n.modalFooterRight {\n display: flex;\n align-items: center;\n gap: 8px;\n}\n\n.advancedConfigSection {\n margin-top: 4px;\n border-top: 1px solid #f0f0f0;\n padding-top: 16px;\n}\n\n.advancedConfigToggle {\n width: 100%;\n display: flex;\n align-items: center;\n justify-content: space-between;\n border: 0;\n background: transparent;\n padding: 0 0 12px;\n cursor: pointer;\n color: #333;\n}\n\n.advancedConfigToggleLabel {\n display: inline-flex;\n align-items: center;\n gap: 8px;\n font-size: 14px;\n font-weight: 600;\n}\n\n.jsonEditorContainer {\n position: relative;\n border: 1px solid #d9d9d9;\n border-radius: 8px;\n overflow: hidden;\n background: #fafbfc;\n transition:\n border-color 0.2s ease,\n box-shadow 0.2s ease;\n\n &:focus-within {\n border-color: #615ced;\n box-shadow: 0 0 0 2px rgba(97, 92, 237, 0.12);\n }\n}\n\n.jsonEditorHighlight,\n.jsonEditorTextarea {\n margin: 0;\n padding: 12px 14px;\n min-height: 180px;\n font-family: Monaco, \"Courier New\", monospace;\n font-size: 13px;\n line-height: 1.6;\n white-space: pre-wrap;\n word-break: break-word;\n tab-size: 2;\n}\n\n.jsonEditorHighlight {\n color: #6b7280;\n pointer-events: none;\n overflow: auto;\n}\n\n.jsonEditorTextarea {\n position: absolute;\n inset: 0;\n width: 100%;\n resize: vertical;\n border: 0;\n outline: 0;\n background: transparent;\n color: transparent;\n caret-color: #1f2328;\n overflow: auto;\n -webkit-text-fill-color: transparent;\n\n &::placeholder {\n color: transparent;\n -webkit-text-fill-color: transparent;\n }\n}\n\n.jsonEditorTokenKey {\n color: #8b5cf6;\n}\n\n.jsonEditorTokenString {\n color: #16a34a;\n}\n\n.jsonEditorTokenNumber {\n color: #2563eb;\n}\n\n.jsonEditorTokenBoolean {\n color: #ea580c;\n}\n\n.jsonEditorTokenNull {\n color: #dc2626;\n}\n\n.jsonEditorTokenPunctuation {\n color: #6b7280;\n}\n\n/* ---- Model Slot Sections ---- */\n\n.slotSection {\n padding: 24px;\n background: #ffffff;\n border-radius: 16px;\n border: 1px solid #e8e8e8;\n box-shadow: 0 2px 8px rgba(0, 0, 0, 0.04);\n transition: all 0.2s ease-in-out;\n\n &:hover {\n box-shadow: 0 4px 16px rgba(0, 0, 0, 0.08);\n border-color: #d9d9d9;\n }\n}\n\n.slotHeader {\n display: flex;\n justify-content: space-between;\n align-items: center;\n margin-bottom: 20px;\n padding-bottom: 16px;\n border-bottom: 1px solid #f0f0f0;\n}\n\n.slotTitle {\n font-size: 18px;\n font-weight: 600;\n color: #1a1a1a;\n}\n\n.slotCurrent {\n font-size: 13px;\n color: #52c41a;\n font-family: \"SF Mono\", \"Menlo\", monospace;\n background: #f6ffed;\n padding: 4px 12px;\n border-radius: 20px;\n border: 1px solid #b7eb8f;\n}\n\n.slotForm {\n display: flex;\n gap: 20px;\n align-items: flex-end;\n flex-wrap: wrap;\n\n @media (max-width: 768px) {\n flex-direction: column;\n gap: 16px;\n align-items: stretch;\n }\n}\n\n.slotField {\n flex: 1;\n display: flex;\n flex-direction: column;\n gap: 8px;\n min-width: 200px;\n\n @media (max-width: 768px) {\n min-width: unset;\n width: 100%;\n }\n}\n\n.slotLabel {\n font-size: 14px;\n color: #666;\n font-weight: 500;\n display: flex;\n align-items: center;\n gap: 4px;\n}\n\n.slotActions {\n display: flex;\n justify-content: flex-end;\n margin-top: 24px;\n padding-top: 20px;\n border-top: 1px solid #f0f0f0;\n}\n\n/* ---- Section Header Row (title + button) ---- */\n\n.sectionHeaderRow {\n display: flex;\n justify-content: space-between;\n align-items: flex-start;\n gap: 16px;\n margin-bottom: 0;\n\n .section {\n flex: 1;\n margin-bottom: 0;\n }\n}\n\n.addProviderBtn {\n flex-shrink: 0;\n margin-top: 4px;\n}\n\n/* ---- Model Management Modal ---- */\n\n.modelList {\n max-height: 360px;\n overflow-y: auto;\n border: 1px solid #f0f0f0;\n border-radius: 8px;\n margin-top: 8px;\n}\n\n.modelListEmpty {\n padding: 24px;\n text-align: center;\n color: #999;\n font-size: 13px;\n}\n\n.modelListItem {\n display: flex;\n align-items: center;\n justify-content: space-between;\n padding: 10px 16px;\n border-bottom: 1px solid #f5f5f5;\n transition: background 0.15s;\n\n &:last-child {\n border-bottom: none;\n }\n\n &:hover {\n background: #fafafa;\n }\n}\n\n.modelListItemInfo {\n display: flex;\n flex-direction: column;\n gap: 2px;\n min-width: 0;\n flex: 1;\n}\n\n.modelListItemName {\n font-size: 14px;\n font-weight: 500;\n color: #1a1a1a;\n}\n\n.modelListItemId {\n font-size: 12px;\n color: #999;\n font-family: \"SF Mono\", \"Menlo\", monospace;\n overflow: hidden;\n text-overflow: ellipsis;\n white-space: nowrap;\n}\n\n.modelListItemActions {\n display: flex;\n align-items: center;\n gap: 4px;\n flex-shrink: 0;\n margin-left: 12px;\n}\n\n.modelAddForm {\n margin-top: 12px;\n padding: 16px;\n background: #fafafa;\n border-radius: 8px;\n border: 1px dashed #d9d9d9;\n}\n\n/* ─── Dark mode ─────────────────────────────────────────────────────────────── */\n:global(.dark-mode) {\n .loadingText {\n color: rgba(255, 255, 255, 0.35);\n }\n\n .sectionDesc {\n color: rgba(255, 255, 255, 0.35);\n }\n\n .providerGroupTitle {\n color: rgba(255, 255, 255, 0.4);\n }\n\n /* Provider card */\n .providerCard {\n background: #2a2a2a;\n\n &.normal {\n border-color: rgba(255, 255, 255, 0.08) !important;\n box-shadow: 0 4px 12px rgba(0, 0, 0, 0.3) !important;\n }\n\n &.hover {\n border-color: #615ced !important;\n box-shadow: 0 12px 32px rgba(0, 0, 0, 0.4) !important;\n }\n }\n\n .cardName {\n color: rgba(255, 255, 255, 0.85);\n }\n\n .infoRow {\n color: rgba(255, 255, 255, 0.5);\n }\n\n .infoLabel {\n color: rgba(255, 255, 255, 0.3);\n }\n\n .infoValue {\n color: rgba(255, 255, 255, 0.65);\n }\n\n .infoEmpty {\n color: rgba(255, 255, 255, 0.2);\n }\n\n .cardActions {\n border-top-color: rgba(255, 255, 255, 0.08);\n }\n\n .configBtn {\n color: rgba(255, 255, 255, 0.55);\n }\n\n .statusContainer .statusText.disabled {\n color: rgba(255, 255, 255, 0.3);\n }\n\n /* Slot section (LLM 顶部选择区) */\n .slotSection {\n background: #2a2a2a;\n border-color: rgba(255, 255, 255, 0.08);\n box-shadow: 0 2px 8px rgba(0, 0, 0, 0.3);\n\n &:hover {\n box-shadow: 0 4px 16px rgba(0, 0, 0, 0.4);\n border-color: rgba(255, 255, 255, 0.15);\n }\n }\n\n .slotHeader {\n border-bottom-color: rgba(255, 255, 255, 0.08);\n }\n\n .slotTitle {\n color: rgba(255, 255, 255, 0.85);\n }\n\n .slotCurrent {\n color: #52c41a;\n background: rgba(82, 196, 26, 0.1);\n border-color: rgba(82, 196, 26, 0.3);\n }\n\n .slotLabel {\n color: rgba(255, 255, 255, 0.5);\n }\n\n .slotActions {\n border-top-color: rgba(255, 255, 255, 0.08);\n }\n\n /* Advanced config */\n .advancedConfigSection {\n border-top-color: rgba(255, 255, 255, 0.08);\n }\n\n .advancedConfigToggle {\n color: rgba(255, 255, 255, 0.65);\n }\n\n /* JSON editor */\n .jsonEditorContainer {\n border-color: rgba(255, 255, 255, 0.15);\n background: #1a1a1a;\n\n &:focus-within {\n border-color: #615ced;\n }\n }\n\n .jsonEditorHighlight {\n color: rgba(255, 255, 255, 0.45);\n }\n\n .jsonEditorTextarea {\n caret-color: rgba(255, 255, 255, 0.85);\n }\n\n /* Model list (modal) */\n .modelList {\n border-color: rgba(255, 255, 255, 0.08);\n }\n\n .modelListEmpty {\n color: rgba(255, 255, 255, 0.3);\n }\n\n .modelListItem {\n border-bottom-color: rgba(255, 255, 255, 0.06);\n\n &:hover {\n background: rgba(255, 255, 255, 0.04);\n }\n }\n\n .modelListItemName {\n color: rgba(255, 255, 255, 0.85);\n }\n\n .modelListItemId {\n color: rgba(255, 255, 255, 0.3);\n }\n\n .modelAddForm {\n background: rgba(255, 255, 255, 0.03);\n border-color: rgba(255, 255, 255, 0.12);\n }\n}\n" }, { "path": "console/src/pages/Settings/Models/index.tsx", "content": "import { useMemo, useState } from \"react\";\nimport { Button } from \"@agentscope-ai/design\";\nimport { PlusOutlined } from \"@ant-design/icons\";\nimport { useProviders } from \"./useProviders\";\nimport {\n PageHeader,\n LoadingState,\n ProviderCard,\n CustomProviderModal,\n} from \"./components\";\nimport { useTranslation } from \"react-i18next\";\nimport type { ProviderInfo } from \"../../../api/types/provider\";\nimport styles from \"./index.module.less\";\n\n/* ------------------------------------------------------------------ */\n/* Main Page */\n/* ------------------------------------------------------------------ */\n\nfunction ModelsPage() {\n const { t } = useTranslation();\n const { providers, activeModels, loading, error, fetchAll } = useProviders();\n const [hoveredCard, setHoveredCard] = useState(null);\n const [addProviderOpen, setAddProviderOpen] = useState(false);\n\n const refreshProvidersSilently = () => fetchAll(false);\n\n const { regularProviders, embeddedProviders } = useMemo(() => {\n const regular: ProviderInfo[] = [];\n const embedded: ProviderInfo[] = [];\n for (const p of providers) {\n if (p.is_local) embedded.push(p);\n else regular.push(p);\n }\n return { regularProviders: regular, embeddedProviders: embedded };\n }, [providers]);\n\n const handleMouseEnter = (providerId: string) => {\n setHoveredCard(providerId);\n };\n\n const handleMouseLeave = () => {\n setHoveredCard(null);\n };\n\n const renderProviderCards = (list: ProviderInfo[]) =>\n list.map((provider) => (\n handleMouseEnter(provider.id)}\n onMouseLeave={handleMouseLeave}\n />\n ));\n\n return (\n
    \n {loading ? (\n \n ) : error ? (\n \n ) : (\n <>\n {/* ---- Providers Section ---- */}\n
    \n
    \n \n }\n onClick={() => setAddProviderOpen(true)}\n className={styles.addProviderBtn}\n >\n {t(\"models.addProvider\")}\n \n
    \n\n {regularProviders.length > 0 && (\n
    \n
    \n {renderProviderCards(regularProviders)}\n
    \n
    \n )}\n\n {embeddedProviders.length > 0 && (\n
    \n

    \n {t(\"models.localEmbedded\")}\n

    \n
    \n {renderProviderCards(embeddedProviders)}\n
    \n
    \n )}\n
    \n\n setAddProviderOpen(false)}\n onSaved={fetchAll}\n />\n \n )}\n
    \n );\n}\n\nexport default ModelsPage;\n" }, { "path": "console/src/pages/Settings/Models/useProviders.ts", "content": "import { useState, useEffect, useCallback } from \"react\";\nimport api from \"../../../api\";\nimport type { ProviderInfo, ActiveModelsInfo } from \"../../../api/types\";\nimport { useAgentStore } from \"../../../stores/agentStore\";\n\nexport function useProviders() {\n const [providers, setProviders] = useState([]);\n const [activeModels, setActiveModels] = useState(\n null,\n );\n const [loading, setLoading] = useState(true);\n const [error, setError] = useState(null);\n const { selectedAgent } = useAgentStore();\n\n const fetchAll = useCallback(async (showLoading = true) => {\n if (showLoading) {\n setLoading(true);\n }\n setError(null);\n try {\n const [provData, activeData] = await Promise.all([\n api.listProviders(),\n api.getActiveModels(),\n ]);\n if (!Array.isArray(provData)) {\n throw new Error(\n \"Unexpected API response. Is BASE_URL configured correctly?\",\n );\n }\n setProviders(provData);\n if (activeData) setActiveModels(activeData);\n } catch (err) {\n const msg =\n err instanceof Error ? err.message : \"Failed to load provider data\";\n console.error(\"Failed to load providers:\", err);\n setError(msg);\n } finally {\n if (showLoading) {\n setLoading(false);\n }\n }\n }, []);\n\n useEffect(() => {\n fetchAll();\n }, [fetchAll, selectedAgent]);\n\n return {\n providers,\n activeModels,\n loading,\n error,\n fetchAll,\n };\n}\n" }, { "path": "console/src/pages/Settings/Security/components/PageHeader.tsx", "content": "import { useTranslation } from \"react-i18next\";\nimport styles from \"../index.module.less\";\n\ninterface PageHeaderProps {\n className?: string;\n}\n\nexport function PageHeader({ className }: PageHeaderProps) {\n const { t } = useTranslation();\n\n return (\n
    \n

    {t(\"security.title\")}

    \n

    {t(\"security.description\")}

    \n
    \n );\n}\n" }, { "path": "console/src/pages/Settings/Security/components/PreviewModal.tsx", "content": "import { Modal, Button, Tag } from \"@agentscope-ai/design\";\nimport { useTranslation } from \"react-i18next\";\nimport type { ToolGuardRule } from \"../../../../api/modules/security\";\n\nconst SEVERITY_COLORS: Record = {\n CRITICAL: \"red\",\n HIGH: \"orange\",\n MEDIUM: \"gold\",\n LOW: \"blue\",\n INFO: \"default\",\n};\n\ninterface PreviewModalProps {\n rule: ToolGuardRule | null;\n onClose: () => void;\n}\n\nexport function PreviewModal({ rule, onClose }: PreviewModalProps) {\n const { t } = useTranslation();\n\n if (!rule) return null;\n\n return (\n {t(\"common.close\")}}\n width={640}\n >\n
    \n

    \n {t(\"security.rules.ruleId\")}: {rule.id}\n

    \n

    \n {t(\"security.rules.severityLabel\")}:{\" \"}\n \n {rule.severity}\n \n

    \n

    \n {t(\"security.rules.tools\")}:{\" \"}\n {rule.tools.length > 0\n ? rule.tools.join(\", \")\n : t(\"security.rules.allTools\")}\n

    \n

    \n {t(\"security.rules.params\")}:{\" \"}\n {rule.params.length > 0\n ? rule.params.join(\", \")\n : t(\"security.rules.allParams\")}\n

    \n

    \n {t(\"security.rules.actionLabel\")}:{\" \"}\n {t(\"security.rules.actionApproval\")}\n

    \n

    \n {t(\"security.rules.descriptionLabel\")}:{\" \"}\n {t(`security.rules.descriptions.${rule.id}`, {\n defaultValue: \"\",\n }) || rule.description}\n

    \n

    \n {t(\"security.rules.patterns\")}:\n

    \n \n {rule.patterns.join(\"\\n\")}\n \n {rule.exclude_patterns.length > 0 && (\n <>\n

    \n {t(\"security.rules.excludePatterns\")}:\n

    \n \n {rule.exclude_patterns.join(\"\\n\")}\n \n \n )}\n
    \n \n );\n}\n" }, { "path": "console/src/pages/Settings/Security/components/RuleModal.tsx", "content": "import { useEffect } from \"react\";\nimport { Modal, Form, Input, Select } from \"@agentscope-ai/design\";\nimport { useTranslation } from \"react-i18next\";\nimport type { ToolGuardRule } from \"../../../../api/modules/security\";\n\nconst SEVERITY_OPTIONS = [\"CRITICAL\", \"HIGH\", \"MEDIUM\", \"LOW\", \"INFO\"];\nconst CATEGORY_OPTIONS = [\n \"command_injection\",\n \"data_exfiltration\",\n \"path_traversal\",\n \"sensitive_file_access\",\n \"network_abuse\",\n \"credential_exposure\",\n \"resource_abuse\",\n \"code_execution\",\n];\nconst BUILTIN_TOOLS = [\n \"execute_shell_command\",\n \"execute_python_code\",\n \"browser_use\",\n \"desktop_screenshot\",\n \"view_image\",\n \"read_file\",\n \"write_file\",\n \"edit_file\",\n \"append_file\",\n \"view_text_file\",\n \"write_text_file\",\n \"send_file_to_user\",\n];\n\ninterface RuleModalProps {\n open: boolean;\n editingRule: ToolGuardRule | null;\n existingRuleIds: string[];\n onOk: () => void;\n onCancel: () => void;\n form: any;\n}\n\nexport function RuleModal({\n open,\n editingRule,\n existingRuleIds,\n onOk,\n onCancel,\n form,\n}: RuleModalProps) {\n const { t } = useTranslation();\n\n useEffect(() => {\n if (open) {\n if (editingRule) {\n form.setFieldsValue({\n ...editingRule,\n patterns: editingRule.patterns.join(\"\\n\"),\n exclude_patterns: editingRule.exclude_patterns.join(\"\\n\"),\n });\n } else {\n form.resetFields();\n form.setFieldsValue({\n severity: \"HIGH\",\n category: \"command_injection\",\n tools: [],\n params: [],\n patterns: \"\",\n exclude_patterns: \"\",\n });\n }\n }\n }, [open, editingRule, form]);\n\n const toolOptions = BUILTIN_TOOLS.map((name) => ({\n label: name,\n value: name,\n }));\n\n return (\n \n
    \n {\n if (!value || editingRule) return Promise.resolve();\n if (existingRuleIds.includes(value)) {\n return Promise.reject(\n new Error(t(\"security.rules.duplicateId\")),\n );\n }\n return Promise.resolve();\n },\n },\n ]}\n >\n \n \n \n \n \n \n \n \n \n ({ label: s, value: s }))}\n />\n \n \n ({ label: c, value: c }))}\n />\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n );\n}\n" }, { "path": "console/src/pages/Settings/Security/components/RuleTable.tsx", "content": "import { Table, Tag, Switch, Button, Tooltip } from \"@agentscope-ai/design\";\nimport { Space } from \"antd\";\nimport { Eye, Pencil, Trash2 } from \"lucide-react\";\nimport { useTranslation } from \"react-i18next\";\nimport type { MergedRule } from \"../useToolGuard\";\nimport styles from \"../index.module.less\";\n\nconst SEVERITY_COLORS: Record = {\n CRITICAL: \"red\",\n HIGH: \"orange\",\n MEDIUM: \"gold\",\n LOW: \"blue\",\n INFO: \"default\",\n};\n\ninterface RuleTableProps {\n rules: MergedRule[];\n enabled: boolean;\n onToggleRule: (ruleId: string, currentlyDisabled: boolean) => void;\n onPreviewRule: (rule: MergedRule) => void;\n onEditRule: (rule: MergedRule) => void;\n onDeleteRule: (ruleId: string) => void;\n}\n\nexport function RuleTable({\n rules,\n enabled,\n onToggleRule,\n onPreviewRule,\n onEditRule,\n onDeleteRule,\n}: RuleTableProps) {\n const { t } = useTranslation();\n\n const columns = [\n {\n title: t(\"security.rules.id\"),\n dataIndex: \"id\",\n key: \"id\",\n width: 220,\n render: (id: string, record: MergedRule) => (\n {id}\n ),\n },\n {\n title: t(\"security.rules.severity\"),\n dataIndex: \"severity\",\n key: \"severity\",\n width: 100,\n render: (sev: string, record: MergedRule) => (\n \n {sev}\n \n ),\n },\n {\n title: t(\"security.rules.descriptionCol\"),\n dataIndex: \"description\",\n key: \"description\",\n ellipsis: true,\n render: (_text: string, record: MergedRule) => {\n const i18nKey = `security.rules.descriptions.${record.id}`;\n const translated = t(i18nKey, { defaultValue: \"\" });\n const display = translated || record.description;\n return (\n \n \n {display}\n \n \n );\n },\n },\n {\n title: t(\"security.rules.source\"),\n dataIndex: \"source\",\n key: \"source\",\n width: 100,\n render: (source: string, record: MergedRule) => (\n \n {source === \"builtin\"\n ? t(\"security.rules.builtin\")\n : t(\"security.rules.custom\")}\n \n ),\n },\n {\n title: t(\"security.rules.actions\"),\n key: \"actions\",\n width: 160,\n render: (_: unknown, record: MergedRule) => (\n \n \n onToggleRule(record.id, record.disabled)}\n disabled={!enabled}\n />\n \n {record.source === \"builtin\" && (\n onPreviewRule(record)}\n disabled={!enabled}\n style={{ display: \"inline-flex\", alignItems: \"center\", gap: 4 }}\n >\n \n {t(\"security.rules.preview\")}\n \n )}\n {record.source === \"custom\" && (\n <>\n \n }\n onClick={() => onEditRule(record)}\n disabled={!enabled}\n />\n \n \n }\n onClick={() => onDeleteRule(record.id)}\n disabled={!enabled}\n />\n \n \n )}\n \n ),\n },\n ];\n\n return (\n \n );\n}\n" }, { "path": "console/src/pages/Settings/Security/components/SkillScannerSection.tsx", "content": "import { useState, useCallback } from \"react\";\nimport {\n Card,\n InputNumber,\n Table,\n Tag,\n Button,\n Modal,\n message,\n Tooltip,\n Empty,\n Tabs,\n} from \"@agentscope-ai/design\";\nimport { Select, Space } from \"antd\";\nimport { Trash2, ShieldCheck, Eye } from \"lucide-react\";\nimport { useTranslation } from \"react-i18next\";\nimport { useSkillScanner } from \"../useSkillScanner\";\nimport type {\n BlockedSkillRecord,\n BlockedSkillFinding,\n SkillScannerWhitelistEntry,\n SkillScannerMode,\n} from \"../../../../api/modules/security\";\nimport { skillApi } from \"../../../../api/modules/skill\";\nimport { useTheme } from \"../../../../contexts/ThemeContext\";\nimport styles from \"../index.module.less\";\n\nfunction FindingsModal({\n findings,\n skillName,\n open,\n onClose,\n}: {\n findings: BlockedSkillFinding[];\n skillName: string;\n open: boolean;\n onClose: () => void;\n}) {\n const { t } = useTranslation();\n\n return (\n \n String(idx)}\n pagination={false}\n size=\"small\"\n columns={[\n {\n title: \"Title\",\n dataIndex: \"title\",\n key: \"title\",\n width: 200,\n },\n {\n title: \"File\",\n key: \"location\",\n width: 160,\n render: (_: unknown, record: BlockedSkillFinding) =>\n record.line_number\n ? `${record.file_path}:${record.line_number}`\n : record.file_path,\n },\n {\n title: \"Description\",\n dataIndex: \"description\",\n key: \"description\",\n ellipsis: true,\n },\n ]}\n />\n \n );\n}\n\nexport function SkillScannerSection() {\n const { t } = useTranslation();\n const { isDark } = useTheme();\n const darkBtnStyle = isDark ? { color: \"rgba(255,255,255,0.75)\" } : undefined;\n const {\n config,\n blockedHistory,\n whitelist,\n loading,\n updateConfig,\n addToWhitelist,\n removeFromWhitelist,\n removeBlockedEntry,\n clearBlockedHistory,\n } = useSkillScanner();\n\n const [saving, setSaving] = useState(false);\n const [findingsModal, setFindingsModal] = useState<{\n open: boolean;\n findings: BlockedSkillFinding[];\n skillName: string;\n }>({ open: false, findings: [], skillName: \"\" });\n\n const handleModeChange = useCallback(\n async (mode: SkillScannerMode) => {\n setSaving(true);\n const ok = await updateConfig({ mode });\n if (ok) message.success(t(\"security.skillScanner.saveSuccess\"));\n else message.error(t(\"security.skillScanner.saveFailed\"));\n setSaving(false);\n },\n [updateConfig, t],\n );\n\n const [pendingTimeout, setPendingTimeout] = useState(null);\n\n const handleTimeoutBlur = useCallback(async () => {\n const value = pendingTimeout;\n if (value === null || value < 5 || value > 300) {\n setPendingTimeout(null);\n return;\n }\n setSaving(true);\n const ok = await updateConfig({ timeout: value });\n if (ok) message.success(t(\"security.skillScanner.saveSuccess\"));\n else message.error(t(\"security.skillScanner.saveFailed\"));\n setPendingTimeout(null);\n setSaving(false);\n }, [pendingTimeout, updateConfig, t]);\n\n const handleAllowSkill = useCallback(\n async (record: BlockedSkillRecord, index: number) => {\n const ok = await addToWhitelist(record.skill_name, record.content_hash);\n if (ok) {\n message.success(t(\"security.skillScanner.whitelist.addSuccess\"));\n await removeBlockedEntry(index);\n } else {\n message.error(t(\"security.skillScanner.whitelist.addFailed\"));\n }\n },\n [addToWhitelist, removeBlockedEntry, t],\n );\n\n const handleRemoveWhitelist = useCallback(\n async (skillName: string) => {\n Modal.confirm({\n title: t(\"security.skillScanner.whitelist.removeConfirm\"),\n content: t(\"security.skillScanner.whitelist.removeWillDisable\"),\n onOk: async () => {\n const ok = await removeFromWhitelist(skillName);\n if (!ok) {\n message.error(t(\"security.skillScanner.whitelist.removeFailed\"));\n return;\n }\n try {\n await skillApi.disableSkill(skillName);\n message.success(\n t(\"security.skillScanner.whitelist.removeAndDisabled\"),\n );\n } catch {\n message.success(t(\"security.skillScanner.whitelist.removeSuccess\"));\n }\n },\n });\n },\n [removeFromWhitelist, t],\n );\n\n const handleClearHistory = useCallback(() => {\n Modal.confirm({\n title: t(\"security.skillScanner.scanAlerts.clearConfirm\"),\n onOk: async () => {\n await clearBlockedHistory();\n },\n });\n }, [clearBlockedHistory, t]);\n\n if (loading || !config) return null;\n\n const enabled = config.mode !== \"off\";\n\n const blockedColumns = [\n {\n title: t(\"security.skillScanner.scanAlerts.skillName\"),\n dataIndex: \"skill_name\",\n key: \"skill_name\",\n width: 180,\n },\n {\n title: t(\"security.skillScanner.scanAlerts.action\"),\n dataIndex: \"action\",\n key: \"action\",\n width: 100,\n render: (action: string) => (\n \n {action === \"blocked\"\n ? t(\"security.skillScanner.scanAlerts.actionBlocked\")\n : t(\"security.skillScanner.scanAlerts.actionWarned\")}\n \n ),\n },\n {\n title: t(\"security.skillScanner.scanAlerts.time\"),\n dataIndex: \"blocked_at\",\n key: \"blocked_at\",\n width: 180,\n render: (val: string) => {\n try {\n return new Date(val).toLocaleString();\n } catch {\n return val;\n }\n },\n },\n {\n title: t(\"security.skillScanner.scanAlerts.actions\"),\n key: \"actions\",\n width: 200,\n render: (_: unknown, record: BlockedSkillRecord, index: number) => (\n \n \n \n setFindingsModal({\n open: true,\n findings: record.findings,\n skillName: record.skill_name,\n })\n }\n >\n \n \n \n \n handleAllowSkill(record, index)}\n >\n \n \n \n \n removeBlockedEntry(index)}\n >\n \n \n \n \n ),\n },\n ];\n\n const whitelistColumns = [\n {\n title: t(\"security.skillScanner.whitelist.skillName\"),\n dataIndex: \"skill_name\",\n key: \"skill_name\",\n width: 200,\n },\n {\n title: t(\"security.skillScanner.whitelist.contentHash\"),\n dataIndex: \"content_hash\",\n key: \"content_hash\",\n width: 200,\n ellipsis: true,\n render: (hash: string) =>\n hash ? (\n \n {hash.substring(0, 16)}...\n \n ) : (\n any\n ),\n },\n {\n title: t(\"security.skillScanner.whitelist.addedAt\"),\n dataIndex: \"added_at\",\n key: \"added_at\",\n width: 180,\n render: (val: string) => {\n try {\n return new Date(val).toLocaleString();\n } catch {\n return val;\n }\n },\n },\n {\n title: t(\"security.skillScanner.whitelist.actions\"),\n key: \"actions\",\n width: 100,\n render: (_: unknown, record: SkillScannerWhitelistEntry) => (\n \n handleRemoveWhitelist(record.skill_name)}\n >\n \n \n \n ),\n },\n ];\n\n return (\n <>\n \n
    \n
    \n \n \n {t(\"security.skillScanner.mode\")}\n \n \n \n
    \n\n
    \n \n \n {t(\"security.skillScanner.timeout\")}\n \n \n setPendingTimeout(v)}\n onBlur={handleTimeoutBlur}\n onPressEnter={handleTimeoutBlur}\n disabled={!enabled}\n style={{ width: 100 }}\n />\n
    \n
    \n     \n\n \n {t(\"security.skillScanner.scanAlerts.title\")}\n {blockedHistory.length > 0 && (\n \n {blockedHistory.length}\n \n )}\n \n ),\n children: (\n
    \n {blockedHistory.length > 0 && (\n
    \n \n
    \n )}\n \n {blockedHistory.length === 0 ? (\n
    \n \n {t(\"security.skillScanner.scanAlerts.empty\")}\n \n }\n />\n
    \n ) : (\n String(idx)}\n pagination={false}\n size=\"small\"\n />\n )}\n     \n
    \n ),\n },\n {\n key: \"whitelist\",\n label: (\n \n {t(\"security.skillScanner.whitelist.title\")}\n {whitelist.length > 0 && (\n {whitelist.length}\n )}\n \n ),\n children: (\n
    \n \n {whitelist.length === 0 ? (\n
    \n \n {t(\"security.skillScanner.whitelist.empty\")}\n \n }\n />\n
    \n ) : (\n \n )}\n     \n
    \n ),\n },\n ]}\n />\n\n \n setFindingsModal({ open: false, findings: [], skillName: \"\" })\n }\n />\n \n );\n}\n" }, { "path": "console/src/pages/Settings/Security/components/index.ts", "content": "export * from \"./PageHeader\";\nexport * from \"./RuleTable\";\nexport * from \"./RuleModal\";\nexport * from \"./PreviewModal\";\nexport * from \"./SkillScannerSection\";\n" }, { "path": "console/src/pages/Settings/Security/index.module.less", "content": ".securityPage {\n padding: 24px;\n height: 100%;\n overflow-y: auto;\n width: 100%;\n}\n\n/* ---- Header Section ---- */\n.header {\n margin-bottom: 20px;\n}\n\n.title {\n font-size: 22px;\n font-weight: 700;\n margin: 0 0 6px 0;\n color: #1a1a1a;\n}\n\n.description {\n font-size: 14px;\n color: #999;\n margin: 0;\n}\n\n/* ---- Content Container ---- */\n.content {\n width: 100%;\n}\n\n/* ---- Main Tabs (Tool Guard / Skill Scanner) ---- */\n.mainTabs {\n :global(.copaw-tabs-nav) {\n margin-bottom: 20px;\n\n &::before {\n border-bottom: 1px solid #f0f0f0;\n }\n }\n\n :global(.copaw-tabs-tab) {\n padding: 10px 4px;\n font-size: 14px;\n font-weight: 500;\n color: #666 !important;\n\n &:hover {\n color: #615ced !important;\n }\n }\n\n :global(.copaw-tabs-tab-active .copaw-tabs-tab-btn) {\n color: #615ced !important;\n font-weight: 600;\n }\n\n :global(.copaw-tabs-ink-bar) {\n background: #615ced !important;\n height: 3px;\n border-radius: 2px 2px 0 0;\n }\n}\n\n:global(.dark-mode) {\n .mainTabs {\n :global(.copaw-tabs-tab .copaw-tabs-tab-btn) {\n color: #ffffff !important;\n }\n\n :global(.copaw-tabs-tab-active .copaw-tabs-tab-btn) {\n color: #8b87f5 !important;\n font-weight: 600;\n }\n\n :global(.copaw-tabs-ink-bar) {\n background: #8b87f5 !important;\n }\n }\n\n .innerTabs {\n :global(.copaw-tabs-tab .copaw-tabs-tab-btn) {\n color: #ffffff !important;\n }\n\n :global(.copaw-tabs-tab-active .copaw-tabs-tab-btn) {\n color: #8b87f5 !important;\n }\n\n :global(.copaw-tabs-ink-bar) {\n background: #8b87f5 !important;\n }\n }\n\n .tabDescription {\n color: rgba(255, 255, 255, 0.45);\n }\n\n .footerButtons {\n border-top-color: rgba(255, 255, 255, 0.1);\n }\n}\n\n.tabLabel {\n display: inline-flex;\n align-items: center;\n gap: 6px;\n font-size: 14px;\n}\n\n.tabContent {\n padding-top: 4px;\n}\n\n.tabDescription {\n font-size: 14px;\n color: #888;\n margin: 0 0 20px 0;\n line-height: 1.6;\n}\n\n/* ---- Inner Tabs (Scan Alerts / Whitelist) ---- */\n.innerTabs {\n margin-top: 20px;\n\n :global(.copaw-tabs-nav) {\n margin-bottom: 16px;\n\n &::before {\n border-bottom: 1px solid #f0f0f0;\n }\n }\n\n :global(.copaw-tabs-tab) {\n font-size: 13px;\n font-weight: 500;\n color: #666 !important;\n\n &:hover {\n color: #615ced !important;\n }\n }\n\n :global(.copaw-tabs-tab-active .copaw-tabs-tab-btn) {\n color: #615ced !important;\n }\n\n :global(.copaw-tabs-ink-bar) {\n background: #615ced !important;\n }\n}\n\n.tabBadge {\n display: inline-flex;\n align-items: center;\n justify-content: center;\n background: #ff4d4f;\n color: #fff;\n font-size: 11px;\n font-weight: 600;\n min-width: 18px;\n height: 18px;\n border-radius: 9px;\n padding: 0 5px;\n margin-left: 6px;\n line-height: 18px;\n}\n\n.tabPanelContent {\n padding-top: 4px;\n}\n\n.tabPanelHeader {\n display: flex;\n justify-content: flex-end;\n margin-bottom: 12px;\n}\n\n/* ---- Cards ---- */\n.formCard {\n margin-bottom: 20px;\n border-radius: 12px;\n border: 1px solid #e8e8e8;\n box-shadow: 0 1px 4px rgba(0, 0, 0, 0.04);\n transition: all 0.2s ease-in-out;\n\n &:hover {\n box-shadow: 0 4px 16px rgba(0, 0, 0, 0.08);\n border-color: #d9d9d9;\n }\n\n :global(.ant-card-body) {\n padding: 20px 24px;\n }\n}\n\n.form {\n :global {\n .ant-form-item {\n margin-bottom: 20px;\n\n &:last-child {\n margin-bottom: 0;\n }\n }\n\n .ant-form-item-label > label {\n font-weight: 500;\n color: #333;\n }\n }\n}\n\n/* ---- Section Header ---- */\n.sectionHeader {\n display: flex;\n justify-content: space-between;\n align-items: center;\n margin-bottom: 16px;\n}\n\n.sectionTitle {\n font-size: 16px;\n font-weight: 600;\n margin: 0;\n color: #1a1a1a;\n}\n\n/* ---- Table Card ---- */\n.tableCard {\n margin-bottom: 0;\n border-radius: 12px;\n border: 1px solid #e8e8e8;\n box-shadow: 0 1px 4px rgba(0, 0, 0, 0.04);\n transition: all 0.2s ease-in-out;\n\n &:hover {\n box-shadow: 0 4px 16px rgba(0, 0, 0, 0.08);\n border-color: #d9d9d9;\n }\n\n :global(.ant-card-body) {\n padding: 0;\n }\n\n :global(.ant-table) {\n border-radius: 12px;\n }\n\n :global(.ant-table-thead > tr > th) {\n background: #fafafa;\n font-weight: 600;\n color: #333;\n }\n\n :global(.ant-table-tbody > tr:hover > td) {\n background: #f5f5f5;\n }\n}\n\n/* ---- Skill Scanner Config ---- */\n.skillScannerConfig {\n display: grid;\n grid-template-columns: repeat(auto-fit, minmax(280px, 1fr));\n gap: 0;\n}\n\n.skillScannerConfigItem {\n display: flex;\n align-items: center;\n justify-content: space-between;\n gap: 12px;\n padding-right: 24px;\n}\n\n.skillScannerConfigItem + .skillScannerConfigItem {\n padding-right: 0;\n padding-left: 24px;\n border-left: 1px solid var(--ant-color-border, #f0f0f0);\n}\n\n.skillScannerLabel {\n font-weight: 500;\n flex-shrink: 0;\n}\n\n.emptyState {\n padding: 40px 24px;\n display: flex;\n justify-content: center;\n}\n\n.emptyText {\n color: #999;\n}\n\n:global(.dark-mode) .emptyText {\n color: rgba(255, 255, 255, 0.45);\n}\n\n.codeHash {\n font-size: 12px;\n}\n\n.footerButtons {\n display: flex;\n justify-content: flex-end;\n margin-top: 8px;\n padding-top: 16px;\n border-top: 1px solid #f0f0f0;\n}\n\n/* ---- Loading & Error States ---- */\n.centerState {\n display: flex;\n flex-direction: column;\n align-items: center;\n justify-content: center;\n height: 400px;\n gap: 16px;\n}\n\n.stateText {\n font-size: 14px;\n color: #999;\n}\n\n.stateTextError {\n font-size: 14px;\n color: #ff4d4f;\n}\n" }, { "path": "console/src/pages/Settings/Security/index.tsx", "content": "import { useState, useCallback } from \"react\";\nimport {\n Form,\n Switch,\n Button,\n Card,\n Select,\n message,\n Tabs,\n} from \"@agentscope-ai/design\";\nimport {\n PlusCircleOutlined,\n SafetyOutlined,\n ScanOutlined,\n} from \"@ant-design/icons\";\nimport { useTranslation } from \"react-i18next\";\nimport api from \"../../../api\";\nimport { useToolGuard, type MergedRule } from \"./useToolGuard\";\nimport {\n PageHeader,\n RuleTable,\n RuleModal,\n PreviewModal,\n SkillScannerSection,\n} from \"./components\";\nimport styles from \"./index.module.less\";\n\nconst BUILTIN_TOOLS = [\n \"execute_shell_command\",\n \"execute_python_code\",\n \"browser_use\",\n \"desktop_screenshot\",\n \"view_image\",\n \"read_file\",\n \"write_file\",\n \"edit_file\",\n \"append_file\",\n \"view_text_file\",\n \"write_text_file\",\n \"send_file_to_user\",\n];\n\nfunction SecurityPage() {\n const { t } = useTranslation();\n const [form] = Form.useForm();\n const [editForm] = Form.useForm();\n const [saving, setSaving] = useState(false);\n\n const {\n config,\n customRules,\n builtinRules,\n enabled,\n setEnabled,\n mergedRules,\n loading,\n error,\n fetchAll,\n toggleRule,\n deleteCustomRule,\n addCustomRule,\n updateCustomRule,\n buildSaveBody,\n } = useToolGuard();\n\n // Modal states\n const [editModal, setEditModal] = useState(false);\n const [editingRule, setEditingRule] = useState(null);\n const [previewRule, setPreviewRule] = useState(null);\n\n // Form handlers\n const handleSave = useCallback(async () => {\n try {\n setSaving(true);\n const values = await form.validateFields();\n const guardedTools: string[] = values.guarded_tools ?? [];\n const body = {\n enabled: values.enabled,\n guarded_tools: guardedTools.length > 0 ? guardedTools : null,\n denied_tools: values.denied_tools ?? [],\n custom_rules: customRules,\n disabled_rules: Array.from(buildSaveBody().disabled_rules),\n };\n await api.updateToolGuard(body);\n setEnabled(body.enabled);\n message.success(t(\"security.saveSuccess\"));\n } catch (err) {\n if (err instanceof Error && \"errorFields\" in err) {\n return;\n }\n const errMsg =\n err instanceof Error ? err.message : t(\"security.saveFailed\");\n message.error(errMsg);\n } finally {\n setSaving(false);\n }\n }, [customRules, buildSaveBody, form, t]);\n\n const handleReset = useCallback(() => {\n form.resetFields();\n fetchAll();\n }, [form, fetchAll]);\n\n // Rule modal handlers\n const openAddRule = useCallback(() => {\n setEditingRule(null);\n editForm.resetFields();\n editForm.setFieldsValue({\n severity: \"HIGH\",\n category: \"command_injection\",\n tools: [],\n params: [],\n patterns: \"\",\n exclude_patterns: \"\",\n });\n setEditModal(true);\n }, [editForm]);\n\n const openEditRule = useCallback(\n (rule: MergedRule) => {\n setEditingRule(rule);\n editForm.setFieldsValue({\n ...rule,\n patterns: rule.patterns.join(\"\\n\"),\n exclude_patterns: rule.exclude_patterns.join(\"\\n\"),\n });\n setEditModal(true);\n },\n [editForm],\n );\n\n const handleEditSave = useCallback(async () => {\n try {\n const values = await editForm.validateFields();\n const patterns = (values.patterns as string)\n .split(\"\\n\")\n .map((s: string) => s.trim())\n .filter(Boolean);\n const excludePatterns = ((values.exclude_patterns as string) || \"\")\n .split(\"\\n\")\n .map((s: string) => s.trim())\n .filter(Boolean);\n\n const rule = {\n id: values.id,\n tools: values.tools ?? [],\n params: values.params ?? [],\n category: values.category,\n severity: values.severity,\n patterns,\n exclude_patterns: excludePatterns,\n description: values.description || \"\",\n remediation: values.remediation || \"\",\n };\n\n if (editingRule) {\n updateCustomRule(editingRule.id, rule);\n } else {\n const allIds = [\n ...builtinRules.map((r) => r.id),\n ...customRules.map((r) => r.id),\n ];\n if (allIds.includes(rule.id)) {\n message.error(t(\"security.rules.duplicateId\"));\n return;\n }\n addCustomRule(rule);\n }\n setEditModal(false);\n } catch {\n // validation failed\n }\n }, [\n editingRule,\n builtinRules,\n customRules,\n updateCustomRule,\n addCustomRule,\n editForm,\n t,\n ]);\n\n const toolOptions = BUILTIN_TOOLS.map((name) => ({\n label: name,\n value: name,\n }));\n\n // Loading state\n if (loading) {\n return (\n
    \n
    \n {t(\"common.loading\")}\n
    \n
    \n );\n }\n\n // Error state\n if (error) {\n return (\n
    \n
    \n {error}\n \n
    \n
    \n );\n }\n\n return (\n
    \n
    \n \n\n \n \n {t(\"security.toolGuardTitle\")}\n \n ),\n children: (\n
    \n

    \n {t(\"security.toolGuardDescription\")}\n

    \n\n \n \n \n setEnabled(val)} />\n \n\n \n \n \n\n \n \n \n \n \n\n
    \n

    \n {t(\"security.rules.title\")}\n

    \n }\n onClick={openAddRule}\n disabled={!enabled}\n size=\"middle\"\n >\n {t(\"security.rules.add\")}\n \n
    \n\n \n \n \n\n
    \n \n {t(\"common.reset\")}\n \n \n {t(\"common.save\")}\n \n
    \n
    \n ),\n },\n {\n key: \"skillScanner\",\n label: (\n \n \n {t(\"security.skillScanner.title\")}\n \n ),\n children: (\n
    \n

    \n {t(\"security.skillScanner.description\")}\n

    \n \n
    \n ),\n },\n ]}\n />\n
    \n\n r.id),\n ...customRules.map((r) => r.id),\n ]}\n onOk={handleEditSave}\n onCancel={() => setEditModal(false)}\n form={editForm}\n />\n\n setPreviewRule(null)} />\n
    \n );\n}\n\nexport default SecurityPage;\n" }, { "path": "console/src/pages/Settings/Security/useSkillScanner.ts", "content": "import { useState, useEffect, useCallback } from \"react\";\nimport api from \"../../../api\";\nimport type {\n SkillScannerConfig,\n BlockedSkillRecord,\n SkillScannerWhitelistEntry,\n} from \"../../../api/modules/security\";\n\nexport function useSkillScanner() {\n const [config, setConfig] = useState(null);\n const [blockedHistory, setBlockedHistory] = useState(\n [],\n );\n const [loading, setLoading] = useState(true);\n const [error, setError] = useState(null);\n\n const fetchAll = useCallback(async () => {\n setLoading(true);\n setError(null);\n try {\n const [cfg, history] = await Promise.all([\n api.getSkillScanner(),\n api.getBlockedHistory(),\n ]);\n setConfig(cfg);\n setBlockedHistory(history);\n } catch (err) {\n const msg =\n err instanceof Error\n ? err.message\n : \"Failed to load skill scanner config\";\n console.error(\"Failed to load skill scanner:\", err);\n setError(msg);\n } finally {\n setLoading(false);\n }\n }, []);\n\n useEffect(() => {\n fetchAll();\n }, [fetchAll]);\n\n const updateConfig = useCallback(\n async (updates: Partial) => {\n if (!config) return;\n const newConfig = { ...config, ...updates };\n try {\n const saved = await api.updateSkillScanner(newConfig);\n setConfig(saved);\n return true;\n } catch (err) {\n console.error(\"Failed to update skill scanner config:\", err);\n return false;\n }\n },\n [config],\n );\n\n const addToWhitelist = useCallback(\n async (skillName: string, contentHash: string = \"\") => {\n try {\n await api.addToWhitelist(skillName, contentHash);\n await fetchAll();\n return true;\n } catch (err) {\n console.error(\"Failed to add to whitelist:\", err);\n return false;\n }\n },\n [fetchAll],\n );\n\n const removeFromWhitelist = useCallback(\n async (skillName: string) => {\n try {\n await api.removeFromWhitelist(skillName);\n await fetchAll();\n return true;\n } catch (err) {\n console.error(\"Failed to remove from whitelist:\", err);\n return false;\n }\n },\n [fetchAll],\n );\n\n const removeBlockedEntry = useCallback(\n async (index: number) => {\n try {\n await api.removeBlockedEntry(index);\n await fetchAll();\n return true;\n } catch (err) {\n console.error(\"Failed to remove blocked entry:\", err);\n return false;\n }\n },\n [fetchAll],\n );\n\n const clearBlockedHistory = useCallback(async () => {\n try {\n await api.clearBlockedHistory();\n setBlockedHistory([]);\n return true;\n } catch (err) {\n console.error(\"Failed to clear blocked history:\", err);\n return false;\n }\n }, []);\n\n const whitelist: SkillScannerWhitelistEntry[] = config?.whitelist ?? [];\n\n return {\n config,\n blockedHistory,\n whitelist,\n loading,\n error,\n fetchAll,\n updateConfig,\n addToWhitelist,\n removeFromWhitelist,\n removeBlockedEntry,\n clearBlockedHistory,\n };\n}\n" }, { "path": "console/src/pages/Settings/Security/useToolGuard.ts", "content": "import { useState, useEffect, useCallback } from \"react\";\nimport api from \"../../../api\";\nimport type {\n ToolGuardConfig,\n ToolGuardRule,\n} from \"../../../api/modules/security\";\n\nexport interface MergedRule extends ToolGuardRule {\n source: \"builtin\" | \"custom\";\n disabled: boolean;\n}\n\nexport function useToolGuard() {\n const [config, setConfig] = useState(null);\n const [builtinRules, setBuiltinRules] = useState([]);\n const [customRules, setCustomRules] = useState([]);\n const [disabledRules, setDisabledRules] = useState>(new Set());\n const [enabled, setEnabled] = useState(true);\n const [loading, setLoading] = useState(true);\n const [error, setError] = useState(null);\n\n const fetchAll = useCallback(async () => {\n setLoading(true);\n setError(null);\n try {\n const [cfg, builtin] = await Promise.all([\n api.getToolGuard(),\n api.getBuiltinRules(),\n ]);\n setConfig(cfg);\n setEnabled(cfg.enabled);\n setBuiltinRules(builtin);\n setCustomRules(cfg.custom_rules ?? []);\n setDisabledRules(new Set(cfg.disabled_rules ?? []));\n } catch (err) {\n const msg =\n err instanceof Error ? err.message : \"Failed to load security config\";\n console.error(\"Failed to load tool guard:\", err);\n setError(msg);\n } finally {\n setLoading(false);\n }\n }, []);\n\n useEffect(() => {\n fetchAll();\n }, [fetchAll]);\n\n const toggleRule = useCallback(\n (ruleId: string, currentlyDisabled: boolean) => {\n setDisabledRules((prev) => {\n const next = new Set(prev);\n if (currentlyDisabled) {\n next.delete(ruleId);\n } else {\n next.add(ruleId);\n }\n return next;\n });\n },\n [],\n );\n\n const deleteCustomRule = useCallback((ruleId: string) => {\n setCustomRules((prev) => prev.filter((r) => r.id !== ruleId));\n setDisabledRules((prev) => {\n const next = new Set(prev);\n next.delete(ruleId);\n return next;\n });\n }, []);\n\n const addCustomRule = useCallback((rule: ToolGuardRule) => {\n setCustomRules((prev) => [...prev, rule]);\n }, []);\n\n const updateCustomRule = useCallback(\n (ruleId: string, rule: ToolGuardRule) => {\n setCustomRules((prev) => prev.map((r) => (r.id === ruleId ? rule : r)));\n },\n [],\n );\n\n const mergedRules: MergedRule[] = [\n ...builtinRules.map((r) => ({\n ...r,\n source: \"builtin\" as const,\n disabled: disabledRules.has(r.id),\n })),\n ...customRules.map((r) => ({\n ...r,\n source: \"custom\" as const,\n disabled: disabledRules.has(r.id),\n })),\n ];\n\n const buildSaveBody = useCallback((): ToolGuardConfig => {\n return {\n enabled,\n guarded_tools: config?.guarded_tools ?? null,\n denied_tools: config?.denied_tools ?? [],\n custom_rules: customRules,\n disabled_rules: Array.from(disabledRules),\n };\n }, [enabled, config, customRules, disabledRules]);\n\n return {\n config,\n builtinRules,\n customRules,\n disabledRules,\n enabled,\n setEnabled,\n mergedRules,\n loading,\n error,\n fetchAll,\n toggleRule,\n deleteCustomRule,\n addCustomRule,\n updateCustomRule,\n buildSaveBody,\n };\n}\n" }, { "path": "console/src/pages/Settings/TokenUsage/components/EmptyState.tsx", "content": "import styles from \"../index.module.less\";\n\ninterface EmptyStateProps {\n message: string;\n className?: string;\n}\n\nexport function EmptyState({ message, className }: EmptyStateProps) {\n return (\n
    \n 📊\n {message}\n
    \n );\n}\n" }, { "path": "console/src/pages/Settings/TokenUsage/components/LoadingState.tsx", "content": "import { Button } from \"@agentscope-ai/design\";\nimport { useTranslation } from \"react-i18next\";\nimport styles from \"../index.module.less\";\n\ninterface LoadingStateProps {\n message: string;\n error?: boolean;\n onRetry?: () => void;\n className?: string;\n}\n\nexport function LoadingState({\n message,\n error,\n onRetry,\n className,\n}: LoadingStateProps) {\n const { t } = useTranslation();\n\n return (\n
    \n \n {message}\n \n {error && onRetry && (\n \n )}\n
    \n );\n}\n" }, { "path": "console/src/pages/Settings/TokenUsage/components/PageHeader.tsx", "content": "import styles from \"../index.module.less\";\n\ninterface PageHeaderProps {\n title: string;\n description: string;\n className?: string;\n}\n\nexport function PageHeader({ title, description, className }: PageHeaderProps) {\n return (\n
    \n

    {title}

    \n

    {description}

    \n
    \n );\n}\n" }, { "path": "console/src/pages/Settings/TokenUsage/components/index.ts", "content": "export * from \"./PageHeader\";\nexport * from \"./LoadingState\";\nexport * from \"./EmptyState\";\n" }, { "path": "console/src/pages/Settings/TokenUsage/index.module.less", "content": ".tokenUsagePage {\n padding: 24px;\n}\n\n/* ---- Section (same as Models / Environments) ---- */\n\n.section {\n margin-bottom: 24px;\n}\n\n.section:last-child {\n margin-bottom: 0;\n}\n\n.sectionTitle {\n margin-bottom: 4px;\n font-size: 24px;\n font-weight: 600;\n}\n\n.sectionDesc {\n margin: 0 0 16px;\n color: #999;\n font-size: 14px;\n}\n\n/* ---- Loading / Error ---- */\n\n.loading {\n text-align: center;\n padding: 60px;\n}\n\n.loadingText {\n color: #999;\n}\n\n/* ---- Empty state ---- */\n\n.emptyState {\n display: flex;\n flex-direction: column;\n align-items: center;\n gap: 8px;\n padding: 48px 24px;\n color: #999;\n font-size: 14px;\n}\n\n.emptyIcon {\n font-size: 32px;\n opacity: 0.6;\n}\n\n.filters {\n display: flex;\n gap: 12px;\n align-items: center;\n margin-bottom: 24px;\n}\n\n.datePicker {\n width: 260px;\n}\n\n.summaryCards {\n display: flex;\n gap: 16px;\n flex-wrap: wrap;\n margin-bottom: 24px;\n}\n\n.card {\n flex: 1 1 180px;\n min-width: 160px;\n text-align: center;\n padding: 20px;\n}\n\n.cardValue {\n font-size: 24px;\n font-weight: 600;\n color: #1a1a1a;\n margin-bottom: 4px;\n}\n\n.cardLabel {\n font-size: 13px;\n color: #999;\n}\n\n.tableCard {\n margin-bottom: 24px;\n\n &:last-child {\n margin-bottom: 0;\n }\n}\n\n.tableWrapper {\n overflow-x: auto;\n}\n\n.table {\n width: 100%;\n border-collapse: collapse;\n font-size: 14px;\n\n th,\n td {\n padding: 12px 16px;\n text-align: left;\n border-bottom: 1px solid #f0f0f0;\n }\n\n th {\n font-weight: 600;\n color: #666;\n background: #fafafa;\n }\n\n td {\n color: #333;\n }\n\n tbody tr:hover {\n background: #fafafa;\n }\n}\n\n.modelCell {\n font-family: \"SF Mono\", \"Menlo\", monospace;\n font-size: 13px;\n}\n\n/* ─── Dark mode ─────────────────────────────────────────────────────────────── */\n:global(.dark-mode) {\n .sectionDesc {\n color: rgba(255, 255, 255, 0.35);\n }\n\n .loadingText {\n color: rgba(255, 255, 255, 0.35);\n }\n\n .emptyState {\n color: rgba(255, 255, 255, 0.25);\n }\n\n /* Summary cards */\n .cardValue {\n color: rgba(255, 255, 255, 0.85);\n }\n\n .cardLabel {\n color: rgba(255, 255, 255, 0.35);\n }\n\n /* Data table */\n .table {\n th,\n td {\n border-bottom-color: rgba(255, 255, 255, 0.06);\n }\n\n th {\n color: rgba(255, 255, 255, 0.4);\n background: rgba(255, 255, 255, 0.03);\n }\n\n td {\n color: rgba(255, 255, 255, 0.75);\n }\n\n tbody tr:hover {\n background: rgba(255, 255, 255, 0.04);\n }\n }\n}\n" }, { "path": "console/src/pages/Settings/TokenUsage/index.tsx", "content": "import { useEffect, useMemo, useState } from \"react\";\nimport { Button, Card, message, Table } from \"@agentscope-ai/design\";\nimport type { ColumnsType } from \"antd/es/table\";\nimport { DatePicker } from \"antd\";\nimport { useTranslation } from \"react-i18next\";\nimport dayjs, { Dayjs } from \"dayjs\";\nimport api from \"../../../api\";\nimport type {\n TokenUsageSummary,\n TokenUsageStats,\n} from \"../../../api/types/tokenUsage\";\nimport { formatCompact } from \"../../../utils/formatNumber\";\nimport { PageHeader, LoadingState, EmptyState } from \"./components\";\nimport styles from \"./index.module.less\";\n\ntype ByModelRow = TokenUsageStats & { key: string };\ntype ByDateRow = TokenUsageStats & { key: string; date: string };\n\nfunction TokenUsagePage() {\n const { t } = useTranslation();\n const [loading, setLoading] = useState(true);\n const [error, setError] = useState(null);\n const [data, setData] = useState(null);\n const [startDate, setStartDate] = useState(\n dayjs().subtract(30, \"day\"),\n );\n const [endDate, setEndDate] = useState(dayjs());\n\n const fetchData = async () => {\n setLoading(true);\n setError(null);\n try {\n const summary = await api.getTokenUsage({\n start_date: startDate.format(\"YYYY-MM-DD\"),\n end_date: endDate.format(\"YYYY-MM-DD\"),\n });\n setData(summary);\n } catch (e) {\n console.error(\"Failed to load token usage:\", e);\n const msg = t(\"tokenUsage.loadFailed\");\n message.error(msg);\n setError(msg);\n setData(null);\n } finally {\n setLoading(false);\n }\n };\n\n useEffect(() => {\n fetchData();\n }, []);\n\n const handleDateChange = (dates: [Dayjs | null, Dayjs | null] | null) => {\n if (dates?.[0]) setStartDate(dates[0]);\n if (dates?.[1]) setEndDate(dates[1]);\n };\n\n const byModelDataSource: ByModelRow[] = useMemo(() => {\n if (!data?.by_model) return [];\n return Object.entries(data.by_model).map(([key, stats]) => ({\n ...stats,\n key,\n }));\n }, [data?.by_model]);\n\n const byDateDataSource: ByDateRow[] = useMemo(() => {\n if (!data?.by_date) return [];\n return Object.entries(data.by_date).map(([dt, stats]) => ({\n ...stats,\n key: dt,\n date: dt,\n }));\n }, [data?.by_date]);\n\n const byModelColumns: ColumnsType = useMemo(\n () => [\n {\n title: t(\"tokenUsage.provider\"),\n dataIndex: \"provider_id\",\n key: \"provider_id\",\n render: (v: string) => v ?? \"\",\n },\n {\n title: t(\"tokenUsage.model\"),\n dataIndex: \"model\",\n key: \"model\",\n render: (v: string, r) => v ?? r.key,\n },\n {\n title: t(\"tokenUsage.promptTokens\"),\n dataIndex: \"prompt_tokens\",\n key: \"prompt_tokens\",\n render: (n: number) => formatCompact(n),\n },\n {\n title: t(\"tokenUsage.completionTokens\"),\n dataIndex: \"completion_tokens\",\n key: \"completion_tokens\",\n render: (n: number) => formatCompact(n),\n },\n {\n title: t(\"tokenUsage.totalCalls\"),\n dataIndex: \"call_count\",\n key: \"call_count\",\n render: (n: number) => formatCompact(n),\n },\n ],\n [t],\n );\n\n const byDateColumns: ColumnsType = useMemo(\n () => [\n { title: t(\"tokenUsage.date\"), dataIndex: \"date\", key: \"date\" },\n {\n title: t(\"tokenUsage.promptTokens\"),\n dataIndex: \"prompt_tokens\",\n key: \"prompt_tokens\",\n render: (n: number) => formatCompact(n),\n },\n {\n title: t(\"tokenUsage.completionTokens\"),\n dataIndex: \"completion_tokens\",\n key: \"completion_tokens\",\n render: (n: number) => formatCompact(n),\n },\n {\n title: t(\"tokenUsage.totalCalls\"),\n dataIndex: \"call_count\",\n key: \"call_count\",\n render: (n: number) => formatCompact(n),\n },\n ],\n [t],\n );\n\n return (\n
    \n \n\n {loading && !data ? (\n \n ) : (\n <>\n
    \n \n \n
    \n\n {data && data.total_calls > 0 ? (\n <>\n
    \n \n
    \n {formatCompact(data.total_prompt_tokens)}\n
    \n
    \n {t(\"tokenUsage.promptTokens\")}\n
    \n     \n \n
    \n {formatCompact(data.total_completion_tokens)}\n
    \n
    \n {t(\"tokenUsage.completionTokens\")}\n
    \n     \n
    \n\n {byModelDataSource.length > 0 && (\n \n \n columns={byModelColumns}\n dataSource={byModelDataSource}\n rowKey=\"key\"\n pagination={false}\n />\n \n )}\n\n {byDateDataSource.length > 0 && (\n \n \n columns={byDateColumns}\n dataSource={byDateDataSource}\n rowKey=\"key\"\n pagination={false}\n />\n \n )}\n \n ) : (\n \n )}\n \n )}\n
    \n );\n}\n\nexport default TokenUsagePage;\n" }, { "path": "console/src/pages/Settings/VoiceTranscription/index.module.less", "content": ".page {\n padding: 24px;\n height: 100%;\n overflow-y: auto;\n width: 100%;\n}\n\n.header {\n display: flex;\n justify-content: space-between;\n align-items: center;\n margin-bottom: 24px;\n}\n\n.title {\n font-size: 24px;\n font-weight: 600;\n margin: 0 0 8px 0;\n color: #000;\n}\n\n.description {\n font-size: 14px;\n color: #666;\n margin: 0;\n}\n\n.card {\n width: 100%;\n margin-bottom: 16px;\n\n &:hover {\n border: 1px solid #615ced;\n box-shadow: 0 12px 32px rgba(0, 0, 0, 0.08);\n }\n}\n\n.cardTitle {\n font-size: 16px;\n font-weight: 600;\n margin: 0 0 4px 0;\n}\n\n.cardDescription {\n font-size: 13px;\n color: #888;\n margin: 0 0 16px 0;\n}\n\n.optionLabel {\n font-weight: 500;\n margin-right: 8px;\n}\n\n.optionDescription {\n font-size: 13px;\n color: #888;\n}\n\n.centerState {\n display: flex;\n flex-direction: column;\n align-items: center;\n justify-content: center;\n height: 400px;\n}\n\n.footerActions {\n display: flex;\n justify-content: flex-end;\n align-items: center;\n padding: 16px 24px;\n}\n\n:global(.dark-mode) {\n .title {\n color: rgba(255, 255, 255, 0.88);\n }\n\n .description {\n color: rgba(255, 255, 255, 0.45);\n }\n\n .cardDescription {\n color: rgba(255, 255, 255, 0.45);\n }\n\n .optionLabel {\n color: rgba(255, 255, 255, 0.88);\n }\n\n .optionDescription {\n color: rgba(255, 255, 255, 0.45);\n }\n}\n" }, { "path": "console/src/pages/Settings/VoiceTranscription/index.tsx", "content": "import { useEffect, useState } from \"react\";\nimport { Button, Card, message } from \"@agentscope-ai/design\";\nimport { Radio, Select, Space, Spin, Alert } from \"antd\";\nimport { useTranslation } from \"react-i18next\";\nimport api from \"../../../api\";\nimport styles from \"./index.module.less\";\n\ninterface TranscriptionProvider {\n id: string;\n name: string;\n available: boolean;\n}\n\ninterface LocalWhisperStatus {\n available: boolean;\n ffmpeg_installed: boolean;\n whisper_installed: boolean;\n}\n\nfunction VoiceTranscriptionPage() {\n const { t } = useTranslation();\n const [loading, setLoading] = useState(true);\n const [saving, setSaving] = useState(false);\n const [audioMode, setAudioMode] = useState(\"auto\");\n const [providerType, setProviderType] = useState(\"disabled\");\n const [providers, setProviders] = useState([]);\n const [selectedProviderId, setSelectedProviderId] = useState(\"\");\n const [localWhisperStatus, setLocalWhisperStatus] =\n useState(null);\n\n const fetchSettings = async () => {\n setLoading(true);\n try {\n const [modeRes, provTypeRes, provRes, lwStatus] = await Promise.all([\n api.getAudioMode(),\n api.getTranscriptionProviderType(),\n api.getTranscriptionProviders(),\n api.getLocalWhisperStatus(),\n ]);\n setAudioMode(modeRes.audio_mode ?? \"auto\");\n setProviderType(provTypeRes.transcription_provider_type ?? \"disabled\");\n setProviders(provRes.providers ?? []);\n setSelectedProviderId(provRes.configured_provider_id ?? \"\");\n setLocalWhisperStatus(lwStatus);\n } catch (err) {\n console.error(\"Failed to load voice transcription settings:\", err);\n message.error(t(\"voiceTranscription.loadFailed\"));\n } finally {\n setLoading(false);\n }\n };\n\n useEffect(() => {\n fetchSettings();\n }, []);\n\n const handleSave = async () => {\n setSaving(true);\n try {\n const promises: Promise[] = [\n api.updateAudioMode(audioMode),\n api.updateTranscriptionProviderType(providerType),\n ];\n if (providerType === \"whisper_api\") {\n promises.push(api.updateTranscriptionProvider(selectedProviderId));\n }\n await Promise.all(promises);\n message.success(t(\"voiceTranscription.saveSuccess\"));\n } catch (err) {\n console.error(\"Failed to save voice transcription settings:\", err);\n message.error(t(\"voiceTranscription.saveFailed\"));\n } finally {\n setSaving(false);\n }\n };\n\n if (loading) {\n return (\n
    \n
    \n \n
    \n
    \n );\n }\n\n const availableProviders = providers.filter((p) => p.available);\n const showProviderSection = audioMode !== \"native\";\n const isLocalWhisper = providerType === \"local_whisper\";\n const isWhisperApi = providerType === \"whisper_api\";\n\n return (\n
    \n
    \n
    \n

    {t(\"voiceTranscription.title\")}

    \n

    \n {t(\"voiceTranscription.description\")}\n

    \n
    \n
    \n\n \n

    \n {t(\"voiceTranscription.audioModeLabel\")}\n

    \n

    \n {t(\"voiceTranscription.audioModeDescription\")}\n

    \n setAudioMode(e.target.value)}\n >\n \n \n \n {t(\"voiceTranscription.modeAuto\")}\n \n \n {t(\"voiceTranscription.modeAutoDesc\")}\n \n \n \n \n {t(\"voiceTranscription.modeNative\")}\n \n \n {t(\"voiceTranscription.modeNativeDesc\")}\n \n \n \n \n\n {audioMode === \"native\" && localWhisperStatus && (\n
    \n {localWhisperStatus.ffmpeg_installed ? (\n \n ) : (\n \n )}\n
    \n )}\n     \n\n {showProviderSection && (\n <>\n \n

    \n {t(\"voiceTranscription.providerTypeLabel\")}\n

    \n

    \n {t(\"voiceTranscription.providerTypeDescription\")}\n

    \n setProviderType(e.target.value)}\n >\n \n \n \n {t(\"voiceTranscription.providerTypeDisabled\")}\n \n \n {t(\"voiceTranscription.providerTypeDisabledDesc\")}\n \n \n \n \n {t(\"voiceTranscription.providerTypeWhisperApi\")}\n \n \n {t(\"voiceTranscription.providerTypeWhisperApiDesc\")}\n \n \n \n \n {t(\"voiceTranscription.providerTypeLocalWhisper\")}\n \n \n {t(\"voiceTranscription.providerTypeLocalWhisperDesc\")}\n \n \n \n \n\n {isLocalWhisper && localWhisperStatus && (\n
    \n {localWhisperStatus.available ? (\n \n ) : (\n \n )}\n
    \n )}\n     \n\n {isWhisperApi && (\n \n

    \n {t(\"voiceTranscription.providerLabel\")}\n

    \n

    \n {t(\"voiceTranscription.providerDescription\")}\n

    \n\n {availableProviders.length === 0 ? (\n \n ) : (\n \n {availableProviders.map((p) => (\n \n {p.name}\n \n ))}\n \n )}\n     \n )}\n \n )}\n\n \n\n
    \n \n {t(\"common.reset\")}\n \n \n
    \n
    \n );\n}\n\nexport default VoiceTranscriptionPage;\n" }, { "path": "console/src/stores/agentStore.ts", "content": "import { create } from \"zustand\";\nimport { persist } from \"zustand/middleware\";\nimport type { AgentSummary } from \"../api/types/agents\";\n\ninterface AgentStore {\n selectedAgent: string;\n agents: AgentSummary[];\n setSelectedAgent: (agentId: string) => void;\n setAgents: (agents: AgentSummary[]) => void;\n addAgent: (agent: AgentSummary) => void;\n removeAgent: (agentId: string) => void;\n updateAgent: (agentId: string, updates: Partial) => void;\n}\n\nexport const useAgentStore = create()(\n persist(\n (set) => ({\n selectedAgent: \"default\",\n agents: [],\n\n setSelectedAgent: (agentId) => set({ selectedAgent: agentId }),\n\n setAgents: (agents) => set({ agents }),\n\n addAgent: (agent) =>\n set((state) => ({\n agents: [...state.agents, agent],\n })),\n\n removeAgent: (agentId) =>\n set((state) => ({\n agents: state.agents.filter((a) => a.id !== agentId),\n })),\n\n updateAgent: (agentId, updates) =>\n set((state) => ({\n agents: state.agents.map((a) =>\n a.id === agentId ? { ...a, ...updates } : a,\n ),\n })),\n }),\n {\n name: \"copaw-agent-storage\",\n },\n ),\n);\n" }, { "path": "console/src/styles/form-override.css", "content": "/**\n * Form required mark style protection\n * Prevent CSS-in-JS styles from third-party components (e.g., @agentscope-ai/chat) from overriding\n */\n\n/* Protect red asterisk for Ant Design form required marks */\n.ant-form-item-required::before {\n color: #ff4d4f !important;\n}\n\n/* Protect custom required mark span elements (e.g., spark-required-mark) */\nspan.spark-required-mark,\nspan[class*=\"spark-required-mark\"] {\n color: #ff4d4f !important;\n}\n" }, { "path": "console/src/styles/layout.css", "content": "html,\nbody {\n height: 100%;\n overflow: hidden;\n margin: 0;\n padding: 0;\n}\n\n/* ─── Dark mode global token overrides ─────────────────────────────────────── */\nhtml.dark-mode {\n color-scheme: dark;\n}\n\nhtml.dark-mode body {\n background: #141414;\n color: rgba(255, 255, 255, 0.85);\n}\n\n/* Ant Design layout background in dark mode */\nhtml.dark-mode .ant-layout,\nhtml.dark-mode .copaw-layout {\n background: #141414 !important;\n}\n\nhtml.dark-mode .ant-layout-content,\nhtml.dark-mode .copaw-layout-content {\n background: #141414 !important;\n}\n\n/* Page content area background */\nhtml.dark-mode .page-content {\n background: #141414;\n}\n\n/* Card components — @agentscope-ai/design uses copaw prefix */\nhtml.dark-mode .copaw-card,\nhtml.dark-mode .ant-card {\n background: #1f1f1f !important;\n border-color: rgba(255, 255, 255, 0.1) !important;\n color: rgba(255, 255, 255, 0.85) !important;\n}\n\nhtml.dark-mode .copaw-card-head,\nhtml.dark-mode .ant-card-head {\n background: #1f1f1f !important;\n border-bottom-color: rgba(255, 255, 255, 0.08) !important;\n color: rgba(255, 255, 255, 0.85) !important;\n}\n\nhtml.dark-mode .copaw-card-head-title,\nhtml.dark-mode .ant-card-head-title {\n color: rgba(255, 255, 255, 0.85) !important;\n}\n\n/* @agentscope-ai/design Card custom title (sparkPrefix-title inside card-wrapper) */\nhtml.dark-mode .copaw-card-wrapper .copaw-title,\nhtml.dark-mode .copaw-spark-title {\n color: rgba(255, 255, 255, 0.85) !important;\n}\n\nhtml.dark-mode .copaw-card-wrapper .copaw-info,\nhtml.dark-mode .copaw-spark-info {\n color: rgba(255, 255, 255, 0.35) !important;\n}\n\nhtml.dark-mode .copaw-card-body,\nhtml.dark-mode .ant-card-body {\n background: #1f1f1f !important;\n}\n\n/* Table components */\nhtml.dark-mode .copaw-table,\nhtml.dark-mode .ant-table {\n background: #1f1f1f !important;\n color: rgba(255, 255, 255, 0.85) !important;\n}\n\nhtml.dark-mode .copaw-table-wrapper,\nhtml.dark-mode .ant-table-wrapper {\n background: #1f1f1f !important;\n}\n\nhtml.dark-mode .copaw-table-thead > tr > th,\nhtml.dark-mode .ant-table-thead > tr > th,\nhtml.dark-mode .copaw-table-thead > tr > td,\nhtml.dark-mode .ant-table-thead > tr > td {\n background: #262626 !important;\n color: rgba(255, 255, 255, 0.65) !important;\n border-bottom-color: rgba(255, 255, 255, 0.08) !important;\n}\n\nhtml.dark-mode .copaw-table-tbody > tr > td,\nhtml.dark-mode .ant-table-tbody > tr > td {\n background: #1f1f1f !important;\n color: rgba(255, 255, 255, 0.85) !important;\n border-bottom-color: rgba(255, 255, 255, 0.06) !important;\n}\n\nhtml.dark-mode .copaw-table-tbody > tr:hover > td,\nhtml.dark-mode .ant-table-tbody > tr:hover > td {\n background: #2a2a2a !important;\n}\n\nhtml.dark-mode .copaw-table-tbody > tr.copaw-table-row-selected > td,\nhtml.dark-mode .ant-table-tbody > tr.ant-table-row-selected > td {\n background: rgba(97, 92, 237, 0.12) !important;\n}\n\n/* Table fixed columns shadow in dark mode */\nhtml.dark-mode .copaw-table-cell-fix-right,\nhtml.dark-mode .ant-table-cell-fix-right {\n background: #1f1f1f !important;\n}\n\nhtml.dark-mode .copaw-table-cell-fix-right-first::after,\nhtml.dark-mode .ant-table-cell-fix-right-first::after {\n box-shadow: inset -10px 0 8px -8px rgba(0, 0, 0, 0.45) !important;\n}\n\n/* Table pagination */\nhtml.dark-mode .copaw-pagination .copaw-pagination-item,\nhtml.dark-mode .ant-pagination .ant-pagination-item {\n background: #1f1f1f !important;\n border-color: rgba(255, 255, 255, 0.1) !important;\n}\n\nhtml.dark-mode .copaw-pagination .copaw-pagination-item a,\nhtml.dark-mode .ant-pagination .ant-pagination-item a {\n color: rgba(255, 255, 255, 0.65) !important;\n}\n\nhtml.dark-mode .copaw-pagination .copaw-pagination-item-active,\nhtml.dark-mode .ant-pagination .ant-pagination-item-active {\n background: #615ced !important;\n border-color: #615ced !important;\n}\n\nhtml.dark-mode .copaw-pagination .copaw-pagination-item-active a,\nhtml.dark-mode .ant-pagination .ant-pagination-item-active a {\n color: #fff !important;\n}\n\nhtml.dark-mode .copaw-pagination .copaw-pagination-prev button,\nhtml.dark-mode .copaw-pagination .copaw-pagination-next button,\nhtml.dark-mode .ant-pagination .ant-pagination-prev button,\nhtml.dark-mode .ant-pagination .ant-pagination-next button {\n background: #1f1f1f !important;\n border-color: rgba(255, 255, 255, 0.1) !important;\n color: rgba(255, 255, 255, 0.65) !important;\n}\n\n/* Table sorter icons */\nhtml.dark-mode .copaw-table-column-sorter,\nhtml.dark-mode .ant-table-column-sorter {\n color: rgba(255, 255, 255, 0.3) !important;\n}\n\nhtml.dark-mode .copaw-table-column-sorter-up.active,\nhtml.dark-mode .copaw-table-column-sorter-down.active,\nhtml.dark-mode .ant-table-column-sorter-up.active,\nhtml.dark-mode .ant-table-column-sorter-down.active {\n color: #8b87f0 !important;\n}\n\n/* Checkbox in table */\nhtml.dark-mode .copaw-checkbox-inner,\nhtml.dark-mode .ant-checkbox-inner {\n background: #2a2a2a !important;\n border-color: rgba(255, 255, 255, 0.2) !important;\n}\n\nhtml.dark-mode .copaw-checkbox-checked .copaw-checkbox-inner,\nhtml.dark-mode .ant-checkbox-checked .ant-checkbox-inner {\n background: #615ced !important;\n border-color: #615ced !important;\n}\n\n/* Page titles (h1) */\nhtml.dark-mode h1,\nhtml.dark-mode h2,\nhtml.dark-mode h3 {\n color: rgba(255, 255, 255, 0.85);\n}\n\n/* Input / Textarea */\nhtml.dark-mode .copaw-input,\nhtml.dark-mode .ant-input {\n background: #2a2a2a !important;\n border-color: rgba(255, 255, 255, 0.15) !important;\n color: rgba(255, 255, 255, 0.85) !important;\n}\n\n/* Disabled input */\nhtml.dark-mode .copaw-input[disabled],\nhtml.dark-mode .ant-input[disabled],\nhtml.dark-mode .copaw-input-disabled,\nhtml.dark-mode .ant-input-disabled {\n background: rgba(255, 255, 255, 0.04) !important;\n border-color: rgba(255, 255, 255, 0.08) !important;\n color: rgba(255, 255, 255, 0.4) !important;\n cursor: not-allowed;\n}\n\n/* Disabled InputNumber */\nhtml.dark-mode .copaw-input-number-disabled,\nhtml.dark-mode .ant-input-number-disabled,\nhtml.dark-mode .copaw-input-number-disabled .copaw-input-number-input,\nhtml.dark-mode .ant-input-number-disabled .ant-input-number-input {\n background: rgba(255, 255, 255, 0.04) !important;\n border-color: rgba(255, 255, 255, 0.08) !important;\n color: rgba(255, 255, 255, 0.4) !important;\n}\n\nhtml.dark-mode .copaw-input::placeholder,\nhtml.dark-mode .ant-input::placeholder {\n color: rgba(255, 255, 255, 0.25) !important;\n}\n\nhtml.dark-mode .copaw-input-affix-wrapper,\nhtml.dark-mode .ant-input-affix-wrapper {\n background: #2a2a2a !important;\n border-color: rgba(255, 255, 255, 0.15) !important;\n}\n\n/* Select */\nhtml.dark-mode .copaw-select-selector,\nhtml.dark-mode .ant-select-selector {\n background: #2a2a2a !important;\n border-color: rgba(255, 255, 255, 0.15) !important;\n color: rgba(255, 255, 255, 0.85) !important;\n}\n\nhtml.dark-mode .copaw-select-selection-placeholder,\nhtml.dark-mode .ant-select-selection-placeholder {\n color: rgba(255, 255, 255, 0.25) !important;\n}\n\nhtml.dark-mode .copaw-select-arrow,\nhtml.dark-mode .ant-select-arrow {\n color: rgba(255, 255, 255, 0.3) !important;\n}\n\n/* Select dropdown */\nhtml.dark-mode .copaw-select-dropdown,\nhtml.dark-mode .ant-select-dropdown {\n background: #1f1f1f !important;\n border-color: rgba(255, 255, 255, 0.1) !important;\n}\n\nhtml.dark-mode .copaw-select-item,\nhtml.dark-mode .ant-select-item {\n color: rgba(255, 255, 255, 0.85) !important;\n}\n\nhtml.dark-mode .copaw-select-item-option-active,\nhtml.dark-mode .ant-select-item-option-active {\n background: rgba(97, 92, 237, 0.12) !important;\n}\n\nhtml.dark-mode .copaw-select-item-option-selected,\nhtml.dark-mode .ant-select-item-option-selected {\n background: rgba(97, 92, 237, 0.2) !important;\n color: #8b87f0 !important;\n}\n\n/* Form labels */\nhtml.dark-mode .copaw-form-item-label > label,\nhtml.dark-mode .ant-form-item-label > label {\n color: rgba(255, 255, 255, 0.65) !important;\n}\n\nhtml.dark-mode .copaw-form-item-required::before,\nhtml.dark-mode .ant-form-item-required::before {\n color: #ff4d4f !important;\n}\n\n/* InputNumber */\nhtml.dark-mode .copaw-input-number,\nhtml.dark-mode .ant-input-number {\n background: #2a2a2a !important;\n border-color: rgba(255, 255, 255, 0.15) !important;\n color: rgba(255, 255, 255, 0.85) !important;\n}\n\nhtml.dark-mode .copaw-input-number-input,\nhtml.dark-mode .ant-input-number-input {\n background: #2a2a2a !important;\n color: rgba(255, 255, 255, 0.85) !important;\n}\n\nhtml.dark-mode .copaw-input-number-handler-wrap,\nhtml.dark-mode .ant-input-number-handler-wrap {\n background: #2a2a2a !important;\n border-color: rgba(255, 255, 255, 0.1) !important;\n}\n\nhtml.dark-mode .copaw-input-number-handler,\nhtml.dark-mode .ant-input-number-handler {\n color: rgba(255, 255, 255, 0.45) !important;\n border-color: rgba(255, 255, 255, 0.1) !important;\n}\n\n/* TimePicker */\nhtml.dark-mode .copaw-picker,\nhtml.dark-mode .ant-picker {\n background: #2a2a2a !important;\n border-color: rgba(255, 255, 255, 0.15) !important;\n color: rgba(255, 255, 255, 0.85) !important;\n}\n\nhtml.dark-mode .copaw-picker-input > input,\nhtml.dark-mode .ant-picker-input > input {\n color: rgba(255, 255, 255, 0.85) !important;\n}\n\nhtml.dark-mode .copaw-picker-suffix,\nhtml.dark-mode .ant-picker-suffix {\n color: rgba(255, 255, 255, 0.3) !important;\n}\n\nhtml.dark-mode .copaw-picker-dropdown,\nhtml.dark-mode .ant-picker-dropdown {\n background: #1f1f1f !important;\n}\n\nhtml.dark-mode .copaw-picker-panel,\nhtml.dark-mode .ant-picker-panel {\n background: #1f1f1f !important;\n border-color: rgba(255, 255, 255, 0.1) !important;\n}\n\nhtml.dark-mode .copaw-picker-time-panel-cell-inner,\nhtml.dark-mode .ant-picker-time-panel-cell-inner {\n color: rgba(255, 255, 255, 0.85) !important;\n}\n\nhtml.dark-mode\n .copaw-picker-time-panel-cell-selected\n .copaw-picker-time-panel-cell-inner,\nhtml.dark-mode\n .ant-picker-time-panel-cell-selected\n .ant-picker-time-panel-cell-inner {\n background: rgba(97, 92, 237, 0.2) !important;\n color: #8b87f0 !important;\n}\n\n/* DatePicker / RangePicker calendar panel */\nhtml.dark-mode .copaw-picker-dropdown,\nhtml.dark-mode .ant-picker-dropdown {\n background: transparent !important;\n}\n\nhtml.dark-mode .copaw-picker-panel-container,\nhtml.dark-mode .ant-picker-panel-container {\n background: #1f1f1f !important;\n border: 1px solid rgba(255, 255, 255, 0.1) !important;\n box-shadow: 0 8px 24px rgba(0, 0, 0, 0.5) !important;\n}\n\n/* Header (month/year nav) */\nhtml.dark-mode .copaw-picker-header,\nhtml.dark-mode .ant-picker-header {\n border-bottom-color: rgba(255, 255, 255, 0.08) !important;\n color: rgba(255, 255, 255, 0.85) !important;\n}\n\nhtml.dark-mode .copaw-picker-header-view button,\nhtml.dark-mode .ant-picker-header-view button,\nhtml.dark-mode .copaw-picker-prev-icon,\nhtml.dark-mode .copaw-picker-next-icon,\nhtml.dark-mode .copaw-picker-super-prev-icon,\nhtml.dark-mode .copaw-picker-super-next-icon,\nhtml.dark-mode .ant-picker-prev-icon,\nhtml.dark-mode .ant-picker-next-icon,\nhtml.dark-mode .ant-picker-super-prev-icon,\nhtml.dark-mode .ant-picker-super-next-icon {\n color: rgba(255, 255, 255, 0.65) !important;\n}\n\nhtml.dark-mode .copaw-picker-header button:hover,\nhtml.dark-mode .ant-picker-header button:hover {\n color: rgba(255, 255, 255, 0.85) !important;\n}\n\n/* Week day labels (Su Mo Tu ...) */\nhtml.dark-mode .copaw-picker-content th,\nhtml.dark-mode .ant-picker-content th {\n color: rgba(255, 255, 255, 0.35) !important;\n}\n\n/* Normal date cells */\nhtml.dark-mode .copaw-picker-cell .copaw-picker-cell-inner,\nhtml.dark-mode .ant-picker-cell .ant-picker-cell-inner {\n color: rgba(255, 255, 255, 0.65) !important;\n}\n\nhtml.dark-mode .copaw-picker-cell:hover .copaw-picker-cell-inner,\nhtml.dark-mode .ant-picker-cell:hover .ant-picker-cell-inner {\n background: rgba(97, 92, 237, 0.2) !important;\n color: rgba(255, 255, 255, 0.85) !important;\n}\n\n/* Outside-month cells */\nhtml.dark-mode .copaw-picker-cell-disabled .copaw-picker-cell-inner,\nhtml.dark-mode .ant-picker-cell-disabled .ant-picker-cell-inner,\nhtml.dark-mode .copaw-picker-cell-disabled,\nhtml.dark-mode .ant-picker-cell-disabled {\n color: rgba(255, 255, 255, 0.2) !important;\n}\n\n/* Today marker */\nhtml.dark-mode .copaw-picker-cell-today .copaw-picker-cell-inner::before,\nhtml.dark-mode .ant-picker-cell-today .ant-picker-cell-inner::before {\n border-color: #615ced !important;\n}\n\n/* Selected start/end cell */\nhtml.dark-mode .copaw-picker-cell-selected .copaw-picker-cell-inner,\nhtml.dark-mode .ant-picker-cell-selected .ant-picker-cell-inner,\nhtml.dark-mode .copaw-picker-cell-range-start .copaw-picker-cell-inner,\nhtml.dark-mode .ant-picker-cell-range-start .ant-picker-cell-inner,\nhtml.dark-mode .copaw-picker-cell-range-end .copaw-picker-cell-inner,\nhtml.dark-mode .ant-picker-cell-range-end .ant-picker-cell-inner {\n background: #615ced !important;\n color: #fff !important;\n}\n\n/* Range in-between cells */\nhtml.dark-mode .copaw-picker-cell-in-range::before,\nhtml.dark-mode .ant-picker-cell-in-range::before {\n background: rgba(97, 92, 237, 0.15) !important;\n}\n\nhtml.dark-mode .copaw-picker-cell-in-range .copaw-picker-cell-inner,\nhtml.dark-mode .ant-picker-cell-in-range .ant-picker-cell-inner {\n color: rgba(255, 255, 255, 0.85) !important;\n}\n\n/* Range hover preview */\nhtml.dark-mode .copaw-picker-cell-in-view.copaw-picker-cell-range-hover::before,\nhtml.dark-mode .ant-picker-cell-in-view.ant-picker-cell-range-hover::before,\nhtml.dark-mode\n .copaw-picker-cell-in-view.copaw-picker-cell-range-hover-start::after,\nhtml.dark-mode\n .ant-picker-cell-in-view.ant-picker-cell-range-hover-start::after,\nhtml.dark-mode\n .copaw-picker-cell-in-view.copaw-picker-cell-range-hover-end::after,\nhtml.dark-mode .ant-picker-cell-in-view.ant-picker-cell-range-hover-end::after {\n border-color: #8b87f0 !important;\n}\n\n/* Panel footer (OK button area) */\nhtml.dark-mode .copaw-picker-footer,\nhtml.dark-mode .ant-picker-footer {\n border-top-color: rgba(255, 255, 255, 0.08) !important;\n background: #1f1f1f !important;\n}\n\nhtml.dark-mode .copaw-picker-today-btn,\nhtml.dark-mode .ant-picker-today-btn {\n color: #8b87f0 !important;\n}\n\n/* Divider between two panels in RangePicker */\nhtml.dark-mode .copaw-picker-panel + .copaw-picker-panel,\nhtml.dark-mode .ant-picker-panel + .ant-picker-panel {\n border-left-color: rgba(255, 255, 255, 0.08) !important;\n}\n\n/* Modal */\nhtml.dark-mode .copaw-modal-content,\nhtml.dark-mode .ant-modal-content {\n background: #1f1f1f !important;\n color: rgba(255, 255, 255, 0.85) !important;\n box-shadow: 0 8px 32px rgba(0, 0, 0, 0.5) !important;\n border: 1px solid rgba(255, 255, 255, 0.1) !important;\n}\n\nhtml.dark-mode .copaw-modal-header,\nhtml.dark-mode .ant-modal-header {\n background: #1f1f1f !important;\n border-bottom-color: rgba(255, 255, 255, 0.08) !important;\n}\n\nhtml.dark-mode .copaw-modal-title,\nhtml.dark-mode .ant-modal-title {\n color: rgba(255, 255, 255, 0.85) !important;\n}\n\nhtml.dark-mode .copaw-modal-close,\nhtml.dark-mode .ant-modal-close {\n color: rgba(255, 255, 255, 0.45) !important;\n}\n\nhtml.dark-mode .copaw-modal-close:hover,\nhtml.dark-mode .ant-modal-close:hover {\n color: rgba(255, 255, 255, 0.85) !important;\n background: rgba(255, 255, 255, 0.08) !important;\n}\n\nhtml.dark-mode .copaw-modal-body,\nhtml.dark-mode .ant-modal-body {\n background: #1f1f1f !important;\n color: rgba(255, 255, 255, 0.85) !important;\n}\n\nhtml.dark-mode .copaw-modal-footer,\nhtml.dark-mode .ant-modal-footer {\n background: #1f1f1f !important;\n border-top-color: rgba(255, 255, 255, 0.08) !important;\n}\n\n/* Form labels inside modal */\nhtml.dark-mode .copaw-modal-body .copaw-form-item-label > label,\nhtml.dark-mode .copaw-modal-body .ant-form-item-label > label,\nhtml.dark-mode .ant-modal-body .ant-form-item-label > label {\n color: rgba(255, 255, 255, 0.65) !important;\n}\n\n/* Extra description text inside modal */\nhtml.dark-mode .copaw-modal-body .copaw-form-item-extra,\nhtml.dark-mode .ant-modal-body .ant-form-item-extra {\n color: rgba(255, 255, 255, 0.35) !important;\n}\n\n/* Drawer */\nhtml.dark-mode .copaw-drawer-content,\nhtml.dark-mode .ant-drawer-content {\n background: #1f1f1f !important;\n}\n\nhtml.dark-mode .copaw-drawer-header,\nhtml.dark-mode .ant-drawer-header {\n background: #1f1f1f !important;\n border-bottom-color: rgba(255, 255, 255, 0.08) !important;\n}\n\nhtml.dark-mode .copaw-drawer-title,\nhtml.dark-mode .ant-drawer-title {\n color: rgba(255, 255, 255, 0.85) !important;\n}\n\nhtml.dark-mode .copaw-drawer-close,\nhtml.dark-mode .ant-drawer-close {\n color: rgba(255, 255, 255, 0.45) !important;\n}\n\nhtml.dark-mode .copaw-drawer-close:hover,\nhtml.dark-mode .ant-drawer-close:hover {\n color: rgba(255, 255, 255, 0.85) !important;\n}\n\nhtml.dark-mode .copaw-drawer-body,\nhtml.dark-mode .ant-drawer-body {\n background: #1f1f1f !important;\n color: rgba(255, 255, 255, 0.85) !important;\n}\n\nhtml.dark-mode .copaw-drawer-footer,\nhtml.dark-mode .ant-drawer-footer {\n background: #1f1f1f !important;\n border-top-color: rgba(255, 255, 255, 0.08) !important;\n}\n\n/* Form labels inside drawer */\nhtml.dark-mode .copaw-drawer-body .copaw-form-item-label > label,\nhtml.dark-mode .copaw-drawer-body .ant-form-item-label > label,\nhtml.dark-mode .ant-drawer-body .ant-form-item-label > label {\n color: rgba(255, 255, 255, 0.65) !important;\n}\n\n/* Tooltip info icon inside drawer (Form.Item tooltip only, not Alert icons) */\nhtml.dark-mode .copaw-drawer-body .copaw-form-item-label .anticon-info-circle,\nhtml.dark-mode .copaw-drawer-body .ant-form-item-label .anticon-info-circle,\nhtml.dark-mode .ant-drawer-body .ant-form-item-label .anticon-info-circle {\n color: rgba(255, 255, 255, 0.3) !important;\n}\n\n/* Slider */\nhtml.dark-mode .copaw-slider-rail,\nhtml.dark-mode .ant-slider-rail {\n background-color: rgba(255, 255, 255, 0.12) !important;\n}\n\nhtml.dark-mode .copaw-slider-track,\nhtml.dark-mode .ant-slider-track {\n background-color: #615ced !important;\n}\n\nhtml.dark-mode .copaw-slider-handle::after,\nhtml.dark-mode .ant-slider-handle::after {\n box-shadow: 0 0 0 2px #615ced !important;\n background-color: #1f1f1f !important;\n}\n\nhtml.dark-mode .copaw-slider-dot,\nhtml.dark-mode .ant-slider-dot {\n border-color: rgba(255, 255, 255, 0.15) !important;\n background-color: #2a2a2a !important;\n}\n\n/* Tooltip popup (slider value) */\nhtml.dark-mode .copaw-tooltip-inner,\nhtml.dark-mode .ant-tooltip-inner {\n background-color: #2a2a2a !important;\n color: rgba(255, 255, 255, 0.85) !important;\n}\n\nhtml.dark-mode .copaw-tooltip-arrow::before,\nhtml.dark-mode .ant-tooltip-arrow::before {\n background: #2a2a2a !important;\n}\n\n/* Disabled chat input overlay in dark mode */\nhtml.dark-mode\n [class*=\"chatDisabledOverlay\"]\n :global([class*=\"chat-anywhere-input\"]),\nhtml.dark-mode [class*=\"chatDisabledOverlay\"] :global([class*=\"chat-input\"]),\nhtml.dark-mode [class*=\"chatDisabledOverlay\"] :global(textarea),\nhtml.dark-mode [class*=\"chatDisabledOverlay\"] :global(input[type=\"text\"]) {\n background-color: #2a2a2a !important;\n}\n\n/* Sender area dark mode */\nhtml.dark-mode [class*=\"copaw-sender-content\"],\nhtml.dark-mode [class*=\"sender-content\"] {\n background: #2a2a2a !important;\n}\n\n/* Chat message bubble text in dark mode */\nhtml.dark-mode [class*=\"message-item\"] [class*=\"content\"],\nhtml.dark-mode [class*=\"chat-anywhere\"] [class*=\"message\"] p,\nhtml.dark-mode [class*=\"chat-anywhere\"] [class*=\"message\"] li,\nhtml.dark-mode [class*=\"chat-anywhere\"] [class*=\"message\"] h1,\nhtml.dark-mode [class*=\"chat-anywhere\"] [class*=\"message\"] h2,\nhtml.dark-mode [class*=\"chat-anywhere\"] [class*=\"message\"] h3,\nhtml.dark-mode [class*=\"chat-anywhere\"] [class*=\"message\"] h4,\nhtml.dark-mode [class*=\"chat-anywhere\"] [class*=\"message\"] h5,\nhtml.dark-mode [class*=\"chat-anywhere\"] [class*=\"message\"] h6,\nhtml.dark-mode [class*=\"chat-anywhere\"] [class*=\"message\"] span,\nhtml.dark-mode [class*=\"chat-anywhere\"] [class*=\"message\"] blockquote,\nhtml.dark-mode [class*=\"chat-anywhere\"] [class*=\"message\"] td,\nhtml.dark-mode [class*=\"chat-anywhere\"] [class*=\"message\"] th {\n color: rgba(255, 255, 255, 0.85) !important;\n}\n\nhtml.dark-mode [class*=\"chat-anywhere\"] [class*=\"message\"] strong,\nhtml.dark-mode [class*=\"chat-anywhere\"] [class*=\"message\"] b {\n color: rgba(255, 255, 255, 0.95) !important;\n}\n\nhtml.dark-mode [class*=\"chat-anywhere\"] [class*=\"message\"] code {\n color: rgba(255, 255, 255, 0.85) !important;\n background: rgba(255, 255, 255, 0.08) !important;\n}\n\nhtml.dark-mode [class*=\"chat-anywhere\"] [class*=\"message\"] a {\n color: #8b87f5 !important;\n}\n\n#root {\n height: 100%;\n overflow: hidden;\n}\n\n.ant-layout {\n min-height: 100vh;\n max-height: 100vh;\n overflow: hidden;\n}\n\n.ant-layout-content {\n overflow: hidden;\n}\n\n.page-container {\n height: 100%;\n overflow: hidden;\n display: flex;\n flex-direction: column;\n}\n\n.page-header {\n flex: 0 0 auto;\n}\n\n.page-content {\n flex: 1 1 auto;\n overflow: auto;\n}\n\n.table-container {\n height: 100%;\n overflow: hidden;\n}\n\n.table-wrapper {\n height: 100%;\n overflow: auto;\n}\n\n/* .ant-card {\n height: 100%;\n} */\n\n.ant-card-body {\n height: 100%;\n padding: 0;\n}\n\n/* Welcome avatar: full tall SVG. Class is CoPaw-avatar (no \"ant\"). */\n[class*=\"chat-anywhere-welcome-default\"] [class*=\"-avatar\"],\n[class*=\"message-list-welcome\"] [class*=\"welcome-default\"] [class*=\"-avatar\"] {\n width: 36px !important;\n height: 48px !important;\n min-width: 36px !important;\n min-height: 48px !important;\n overflow: visible !important;\n}\n[class*=\"chat-anywhere-welcome-default\"] [class*=\"-avatar\"] > img,\n[class*=\"message-list-welcome\"] [class*=\"-avatar\"] > img {\n object-fit: contain !important;\n object-position: center;\n}\n\n/* Move rightHeader to the leftmost position of the right header area (CoPaw chat) */\n[class*=\"chat-anywhere-default-header-right\"],\n[class*=\"default-header-right\"],\n[class*=\"copaw-chat-anywhere-default-header-right\"],\n.copaw-chat-anywhere-default-header-right {\n display: flex !important;\n margin: 0 auto 0 0 !important;\n justify-content: flex-start !important;\n}\n[class*=\"chat-anywhere-default-header-right\"] > *,\n[class*=\"default-header-right\"] > * {\n margin-right: auto !important;\n margin-left: 0 !important;\n}\n" }, { "path": "console/src/utils/formatNumber.ts", "content": "/**\n * Format large numbers in compact form: K (thousands), M (millions), B (billions).\n * e.g. 1500 → \"1.5K\", 1_200_000 → \"1.2M\", 999 → \"999\"\n */\nexport function formatCompact(n: number): string {\n if (!Number.isFinite(n) || n < 0) return \"0\";\n if (n >= 1e9) {\n const v = n / 1e9;\n return (\n (v % 1 === 0 ? v.toFixed(0) : v.toFixed(1).replace(/\\.0$/, \"\")) + \"B\"\n );\n }\n if (n >= 1e6) {\n const v = n / 1e6;\n return (\n (v % 1 === 0 ? v.toFixed(0) : v.toFixed(1).replace(/\\.0$/, \"\")) + \"M\"\n );\n }\n if (n >= 1e3) {\n const v = n / 1e3;\n return (\n (v % 1 === 0 ? v.toFixed(0) : v.toFixed(1).replace(/\\.0$/, \"\")) + \"K\"\n );\n }\n return n.toLocaleString(undefined, { maximumFractionDigits: 0 });\n}\n" }, { "path": "console/src/utils/markdown.ts", "content": "/**\n * Strip YAML frontmatter from the beginning of a markdown string.\n *\n * Many .md files start with a YAML header wrapped in `---` delimiters.\n * marked / XMarkdown renders `---` as
    and the YAML body as plain text.\n * This helper removes the frontmatter block before passing content to the renderer.\n */\nexport const stripFrontmatter = (s: string): string =>\n s.replace(/^---\\r?\\n[\\s\\S]*?\\r?\\n---\\r?\\n?/, \"\");\n" }, { "path": "console/src/vite-env.d.ts", "content": "/// \n\ndeclare module \"*.less\" {\n const classes: { [key: string]: string };\n export default classes;\n}\n\ninterface PyWebViewAPI {\n open_external_link: (url: string) => void;\n}\n\ndeclare global {\n interface Window {\n pywebview?: {\n api: PyWebViewAPI;\n };\n }\n}\n\nexport {};\n" }, { "path": "console/tsconfig.app.json", "content": "{\n \"compilerOptions\": {\n \"tsBuildInfoFile\": \"./node_modules/.tmp/tsconfig.app.tsbuildinfo\",\n \"target\": \"ES2020\",\n \"useDefineForClassFields\": true,\n \"lib\": [\"ES2020\", \"DOM\", \"DOM.Iterable\"],\n \"module\": \"ESNext\",\n \"skipLibCheck\": true,\n\n \"moduleResolution\": \"bundler\",\n \"allowImportingTsExtensions\": true,\n \"moduleDetection\": \"force\",\n \"noEmit\": true,\n \"jsx\": \"react-jsx\",\n \"esModuleInterop\": true,\n \"allowSyntheticDefaultImports\": true,\n\n \"strict\": true,\n \"noUnusedLocals\": true,\n \"noUnusedParameters\": true,\n \"erasableSyntaxOnly\": true,\n \"noFallthroughCasesInSwitch\": true,\n \"noUncheckedSideEffectImports\": true,\n \"baseUrl\": \".\",\n \"paths\": {\n \"@/*\": [\"src/*\"]\n }\n },\n \"include\": [\"src\"]\n}\n" }, { "path": "console/tsconfig.json", "content": "{\n \"files\": [],\n \"references\": [\n { \"path\": \"./tsconfig.app.json\" },\n { \"path\": \"./tsconfig.node.json\" }\n ]\n}\n" }, { "path": "console/tsconfig.node.json", "content": "{\n \"compilerOptions\": {\n \"tsBuildInfoFile\": \"./node_modules/.tmp/tsconfig.node.tsbuildinfo\",\n \"target\": \"ES2022\",\n \"lib\": [\"ES2023\"],\n \"module\": \"ESNext\",\n \"skipLibCheck\": true,\n\n \"moduleResolution\": \"bundler\",\n \"allowImportingTsExtensions\": true,\n \"moduleDetection\": \"force\",\n \"noEmit\": true,\n\n \"strict\": true,\n \"noUnusedLocals\": true,\n \"noUnusedParameters\": true,\n \"erasableSyntaxOnly\": true,\n \"noFallthroughCasesInSwitch\": true,\n \"noUncheckedSideEffectImports\": true\n },\n \"include\": [\"vite.config.ts\"]\n}\n" }, { "path": "console/vite.config.ts", "content": "import { defineConfig, loadEnv } from \"vite\";\nimport react from \"@vitejs/plugin-react\";\nimport path from \"path\";\n\nexport default defineConfig(({ mode }) => {\n const env = loadEnv(mode, process.cwd(), \"\");\n // Empty = same-origin; frontend and backend served together, no hardcoded host.\n const apiBaseUrl = env.BASE_URL ?? \"\";\n\n return {\n define: {\n BASE_URL: JSON.stringify(apiBaseUrl),\n TOKEN: JSON.stringify(env.TOKEN || \"\"),\n MOBILE: false,\n },\n plugins: [react()],\n css: {\n modules: {\n localsConvention: \"camelCase\",\n generateScopedName: \"[name]__[local]__[hash:base64:5]\",\n },\n preprocessorOptions: {\n less: {\n javascriptEnabled: true,\n },\n },\n },\n resolve: {\n alias: {\n \"@\": path.resolve(__dirname, \"./src\"),\n },\n },\n server: {\n host: \"0.0.0.0\",\n port: 5173,\n },\n optimizeDeps: {\n include: [\"diff\"],\n },\n // build: {\n // // Output to CoPaw's console directory,\n // // so we don't need to copy files manually after build.\n // outDir: path.resolve(__dirname, \"../src/copaw/console\"),\n // emptyOutDir: true,\n // },\n };\n});\n" }, { "path": "deploy/Dockerfile", "content": "# -----------------------------------------------------------------------------\n# Stage 1: build console frontend (dist not committed in repo).\n# -----------------------------------------------------------------------------\nFROM agentscope-registry.ap-southeast-1.cr.aliyuncs.com/agentscope/node:slim AS console-builder\nWORKDIR /app\nCOPY console /app/console\nRUN cd /app/console && npm ci --include=dev && npm run build\n\n# -----------------------------------------------------------------------------\n# Stage 2: runtime image with Python, Chromium, and app.\n# -----------------------------------------------------------------------------\nFROM agentscope-registry.ap-southeast-1.cr.aliyuncs.com/agentscope/node:slim\n\n# ENV variables\nENV NODE_ENV=production\nENV WORKSPACE_DIR=/app\nENV COPAW_WORKING_DIR=/app/working\nENV COPAW_SECRET_DIR=/app/working.secret\n\n# Channel filtering: use COPAW_DISABLED_CHANNELS (exclusion, recommended)\n# or COPAW_ENABLED_CHANNELS (whitelist). Override at runtime with -e.\nARG COPAW_DISABLED_CHANNELS=\"imessage\"\nENV COPAW_DISABLED_CHANNELS=${COPAW_DISABLED_CHANNELS}\nARG COPAW_ENABLED_CHANNELS=\"\"\nENV COPAW_ENABLED_CHANNELS=${COPAW_ENABLED_CHANNELS}\n\nARG DEBIAN_FRONTEND=noninteractive\n\nRUN apt-get update && apt-get install -y --fix-missing \\\n curl \\\n python3 \\\n python3-pip \\\n python3-venv \\\n build-essential \\\n libssl-dev \\\n git \\\n supervisor \\\n vim \\\n gettext-base \\\n xfce4 \\\n xfce4-terminal \\\n xvfb \\\n dbus-x11 \\\n fonts-wqy-zenhei \\\n fonts-wqy-microhei \\\n && rm -rf /var/lib/apt/lists/* \\\n && apt-get clean\n\n\nRUN apt-get update && apt-get install -y --fix-missing \\\n chromium \\\n chromium-sandbox \\\n libx11-xcb1 \\\n libxcomposite1 \\\n libxdamage1 \\\n libxext6 \\\n libxfixes3 \\\n libxi6 \\\n libxtst6 \\\n libnss3 \\\n libglib2.0-0 \\\n libdrm2 \\\n libgbm1 \\\n libasound2 \\\n fonts-liberation \\\n libu2f-udev \\\n && rm -rf /var/lib/apt/lists/* \\\n && apt-get clean\n\n\nRUN sed -i 's/^CHROMIUM_FLAGS=\"\"/CHROMIUM_FLAGS=\"--no-sandbox\"/' /usr/bin/chromium\n\n# Playwright: use system Chromium (already installed above).\nENV PLAYWRIGHT_CHROMIUM_EXECUTABLE_PATH=/usr/bin/chromium\n# Avoid Playwright downloading its own browser when executable_path is used.\nENV PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1\n# Indicate running in container (used e.g. for Chromium --no-sandbox).\nENV COPAW_RUNNING_IN_CONTAINER=1\n\nWORKDIR ${WORKSPACE_DIR}\n\nRUN python3 -m venv venv\nENV PATH=\"/app/venv/bin:$PATH\"\n\nCOPY pyproject.toml setup.py README.md ./\nCOPY src ./src\n# Inject console dist from build stage (repo does not commit dist).\nCOPY --from=console-builder /app/console/dist/ ./src/copaw/console/\nRUN pip install --no-cache-dir .[ollama]\n\n# Init working dir with default config.json and HEARTBEAT.md (build time).\nRUN copaw init --defaults --accept-security\n\n# CoPaw app port (default 8088). Override at runtime with -e COPAW_PORT=3000.\nENV COPAW_PORT=8088\n\nCOPY deploy/config/supervisord.conf.template /etc/supervisor/conf.d/supervisord.conf.template\nCOPY --chmod=755 deploy/entrypoint.sh /entrypoint.sh\n\nEXPOSE 8088\n\nCMD [\"/entrypoint.sh\"]\n" }, { "path": "deploy/config/supervisord.conf.template", "content": "[supervisord]\nuser=root\nlogfile=/var/log/supervisord.log\npidfile=/var/log/supervisord.pid\nnodaemon=true\n\n[program:dbus]\ncommand=/bin/sh -c \"rm -f /run/dbus/pid; mkdir -p /run/dbus; exec /usr/bin/dbus-daemon --system --nofork\"\nautostart=true\nautorestart=true\nstderr_logfile=/var/log/dbus.err.log\nstdout_logfile=/var/log/dbus.out.log\n\n[program:app]\ncommand=copaw app --host 0.0.0.0 --port ${COPAW_PORT}\nautostart=true\nautorestart=true\npriority=30\nstderr_logfile=/var/log/app.err.log\nstdout_logfile=/var/log/app.out.log\nenvironment=DISPLAY=\":1\",PLAYWRIGHT_CHROMIUM_EXECUTABLE_PATH=\"/usr/bin/chromium\",COPAW_RUNNING_IN_CONTAINER=\"1\"\n\n[program:xvfb]\ncommand=/bin/sh -c \"rm -f /tmp/.X1-lock /tmp/.X11-unix/X1; mkdir -p /tmp/.X11-unix; exec /usr/bin/Xvfb :1 -screen 0 1280x800x24\"\nautostart=true\nautorestart=true\npriority=10\nstderr_logfile=/var/log/xvfb.err.log\nstdout_logfile=/var/log/xvfb.out.log\nenvironment=DISPLAY=\":1\"\n\n[program:xfce4]\ncommand=/bin/sh -c 'export DISPLAY=:1; for i in $(seq 1 200); do [ -S /tmp/.X11-unix/X1 ] && break; sleep 0.1; done; exec dbus-run-session startxfce4'\nautostart=true\nautorestart=true\npriority=20\nstderr_logfile=/var/log/xfce4.err.log\nstdout_logfile=/var/log/xfce4.out.log\nenvironment=DISPLAY=\":1\"\n" }, { "path": "deploy/entrypoint.sh", "content": "#!/bin/sh\n# Substitute COPAW_PORT in supervisord template and start supervisord.\n# Default port 8088; override at runtime with -e COPAW_PORT=3000.\nset -e\nexport COPAW_PORT=\"${COPAW_PORT:-8088}\"\nenvsubst '${COPAW_PORT}' \\\n < /etc/supervisor/conf.d/supervisord.conf.template \\\n > /etc/supervisor/conf.d/supervisord.conf\nexec /usr/bin/supervisord -c /etc/supervisor/conf.d/supervisord.conf\n" }, { "path": "docker-compose.yml", "content": "version: '3.8'\n\nvolumes:\n copaw-data:\n name: copaw-data\n copaw-secrets:\n name: copaw-secrets\n\nservices:\n copaw:\n image: agentscope/copaw:latest\n container_name: copaw\n restart: always\n ports:\n - \"127.0.0.1:8088:8088\"\n # environment:\n # - COPAW_AUTH_ENABLED=true\n # - COPAW_AUTH_USERNAME=admin\n # - COPAW_AUTH_PASSWORD=yourpassword\n volumes:\n - copaw-data:/app/working\n - copaw-secrets:/app/working.secret\n" }, { "path": "pyproject.toml", "content": "[project]\nname = \"copaw\"\ndynamic = [\"version\"]\ndescription = \"CoPaw is a **personal assistant** that runs in your own environment. It talks to you over multiple channels (DingTalk, Feishu, QQ, Discord, iMessage, etc.) and runs scheduled tasks according to your configuration. **What it can do is driven by Skills — the possibilities are open-ended.** Built-in skills include cron, PDF/Office handling, news digest, file reading, and more; you can add custom skills. All data and tasks run on your machine; no third-party hosting.\"\nreadme = \"README.md\"\nrequires-python = \">=3.10,<3.14\"\ndependencies = [\n \"agentscope==1.0.17\",\n \"agentscope-runtime==1.1.1\",\n \"httpx>=0.27.0\",\n \"packaging>=24.0\",\n \"discord-py>=2.3\",\n \"dingtalk-stream>=0.24.3\",\n \"uvicorn>=0.40.0\",\n \"apscheduler>=3.11.2,<4\",\n \"playwright>=1.49.0\",\n \"questionary>=2.1.1\",\n \"mss>=9.0.0\",\n \"reme-ai==0.3.1.1\",\n \"transformers>=4.30.0\",\n \"python-dotenv>=1.0.0\",\n \"python-socks>=2.5.3\",\n \"onnxruntime<1.24\",\n \"lark-oapi>=1.5.3\",\n \"python-telegram-bot>=20.0\",\n \"twilio>=9.10.2\",\n \"pywebview>=4.0\",\n \"aiofiles>=24.1.0\",\n \"paho-mqtt>=2.0.0\",\n \"wecom-aibot-python-sdk==1.0.1\",\n \"matrix-nio>=0.24.0\",\n \"shortuuid>=1.0.0\",\n \"google-genai>=1.67.0\",\n \"tzdata>=2024.1\",\n \"pyyaml>=6.0\",\n]\n\n[tool.setuptools.dynamic]\nversion = {attr = \"copaw.__version__.__version__\"}\n\n[tool.setuptools]\npackages = { find = { where = [\"src\"] } }\ninclude-package-data = true\n\n[tool.setuptools.package-data]\n# Dockerfile copies console build output to src/copaw/console/ (no dist subdir).\n\"copaw\" = [\n \"console/**\",\n \"agents/md_files/**\",\n \"agents/skills/**\",\n \"tokenizer/**\",\n \"security/tool_guard/rules/**\",\n \"security/skill_scanner/rules/**\",\n \"security/skill_scanner/data/**\",\n]\n\n[build-system]\nrequires = [\"setuptools>=42\", \"wheel\"]\nbuild-backend = \"setuptools.build_meta\"\n\n[project.scripts]\ncopaw = \"copaw.cli.main:cli\"\n\n[project.optional-dependencies]\ndev = [\n \"pytest>=8.3.5\",\n \"pytest-asyncio>=0.23.0\",\n \"pre-commit>=4.2.0\",\n \"pytest-cov>=6.2.1\",\n]\nlocal = [\n \"huggingface_hub>=0.20.0\",\n]\nllamacpp = [\n \"copaw[local]\",\n \"llama-cpp-python>=0.3.0\",\n]\nmlx = [\n \"copaw[local]\",\n \"mlx-lm>=0.10.0; sys_platform == 'darwin'\",\n]\nollama = [\n \"ollama>=0.6.1\",\n]\nwhisper = [\n \"openai-whisper>=20231117\",\n]\nfull = [\n \"copaw[local,ollama,llamacpp,whisper]\",\n \"mlx-lm>=0.10.0; sys_platform == 'darwin'\",\n]\n\n[tool.pytest.ini_options]\nasyncio_mode = \"auto\"\nasyncio_default_fixture_loop_scope = \"function\"\nmarkers = [\n \"slow: marks tests as slow (deselect with '-m \\\"not slow\\\"')\",\n]\n" }, { "path": "scripts/README.md", "content": "# Scripts\n\nRun from **repo root**.\n\n## Build wheel (with latest console)\n\n```bash\nbash scripts/wheel_build.sh\n```\n\n- Builds the console frontend (`console/`), copies `console/dist` to `src/copaw/console/dist`, then builds the wheel. Output: `dist/*.whl`.\n\n## Build website\n\n```bash\nbash scripts/website_build.sh\n```\n\n- Installs dependencies (pnpm or npm) and runs the Vite build. Output: `website/dist/`.\n\n## Build Docker image\n\n```bash\nbash scripts/docker_build.sh [IMAGE_TAG] [EXTRA_ARGS...]\n```\n\n- Default tag: `copaw:latest`. Uses `deploy/Dockerfile` (multi-stage: builds console then Python app).\n- Example: `bash scripts/docker_build.sh myreg/copaw:v1 --no-cache`.\n\n## Run Test\n\n```bash\n# Run all tests\npython scripts/run_tests.py\n\n# Run all unit tests\npython scripts/run_tests.py -u\n\n# Run unit tests for a specific module\npython scripts/run_tests.py -u providers\n\n# Run integration tests\npython scripts/run_tests.py -i\n\n# Run all tests and generate a coverage report\npython scripts/run_tests.py -a -c\n\n# Run tests in parallel (requires pytest-xdist)\npython scripts/run_tests.py -p\n\n# Show help\npython scripts/run_tests.py -h\n```" }, { "path": "scripts/docker_build.sh", "content": "#!/usr/bin/env bash\n# Build Docker image (includes console frontend build in multi-stage).\n# Run from repo root: bash scripts/docker_build.sh [IMAGE_TAG] [EXTRA_ARGS...]\n# Example: bash scripts/docker_build.sh copaw:latest\n# bash scripts/docker_build.sh myreg/copaw:v1 --no-cache\n#\n# By default the Docker image excludes imessage (macOS-only).\n# Override via:\n# COPAW_DISABLED_CHANNELS=imessage,voice bash scripts/docker_build.sh\n# COPAW_ENABLED_CHANNELS=discord,telegram bash scripts/docker_build.sh\nset -e\n\nREPO_ROOT=\"$(cd \"$(dirname \"${BASH_SOURCE[0]}\")/..\" && pwd)\"\ncd \"$REPO_ROOT\"\n\nDOCKERFILE=\"${DOCKERFILE:-$REPO_ROOT/deploy/Dockerfile}\"\nTAG=\"${1:-copaw:latest}\"\nshift || true\n\n# Channels to exclude from the image (default: imessage).\nDISABLED_CHANNELS=\"${COPAW_DISABLED_CHANNELS:-imessage}\"\n\necho \"[docker_build] Building image: $TAG (Dockerfile: $DOCKERFILE)\"\ndocker build -f \"$DOCKERFILE\" \\\n --build-arg COPAW_DISABLED_CHANNELS=\"$DISABLED_CHANNELS\" \\\n ${COPAW_ENABLED_CHANNELS:+--build-arg COPAW_ENABLED_CHANNELS=\"$COPAW_ENABLED_CHANNELS\"} \\\n -t \"$TAG\" \"$@\" .\necho \"[docker_build] Done.\"\necho \"[docker_build] CoPaw app port: 8088 (default). Override with -e COPAW_PORT=.\"\necho \"[docker_build] Run: docker run -p 127.0.0.1:8088:8088 $TAG\"\necho \"[docker_build] Or: docker run -e COPAW_PORT=3000 -p 127.0.0.1:3000:3000 $TAG\"\n" }, { "path": "scripts/docker_sync_latest.sh", "content": "#!/usr/bin/env bash\nset -euo pipefail\n\nBUILDX_VERSION=\"v0.31.1\"\nPLUGINS_DIR=\"${DOCKER_CONFIG:-$HOME/.docker}/cli-plugins\"\nBUILDX_PLUGIN=\"$PLUGINS_DIR/docker-buildx\"\n\ndie() { echo \"[docker_tag_pre_to_latest] ERROR: $*\" >&2; exit 1; }\nlog() { echo \"[docker_tag_pre_to_latest] $*\"; }\n\ninstall_buildx() {\n local os arch suffix url\n case \"$(uname -s)\" in\n Darwin) os=\"darwin\" ;;\n Linux) os=\"linux\" ;;\n *) die \"Unsupported OS: $(uname -s)\" ;;\n esac\n case \"$(uname -m)\" in\n x86_64) arch=\"amd64\" ;;\n aarch64|arm64) arch=\"arm64\" ;;\n *) die \"Unsupported arch: $(uname -m)\" ;;\n esac\n\n suffix=\"${os}-${arch}\"\n url=\"https://github.com/docker/buildx/releases/download/${BUILDX_VERSION}/buildx-${BUILDX_VERSION}.${suffix}\"\n log \"Installing buildx ${BUILDX_VERSION} from ${url}\"\n mkdir -p \"$PLUGINS_DIR\"\n\n if command -v curl &>/dev/null; then\n curl -fsSL \"$url\" -o \"$BUILDX_PLUGIN\"\n elif command -v wget &>/dev/null; then\n wget -q \"$url\" -O \"$BUILDX_PLUGIN\"\n else\n die \"Need curl or wget to install buildx\"\n fi\n\n chmod +x \"$BUILDX_PLUGIN\"\n log \"buildx installed at $BUILDX_PLUGIN\"\n}\n\nrequire_buildx_imagetools() {\n command -v docker &>/dev/null || die \"docker not found in PATH\"\n\n # Check whether docker recognizes the buildx subcommand\n if ! docker buildx version &>/dev/null; then\n log \"docker has no 'buildx' command. Will try to install buildx plugin...\"\n install_buildx\n\n # Re-check after installation\n if ! docker buildx version &>/dev/null; then\n die $'docker still has no buildx after plugin install.\\nPossible causes:\\n- You are not using official Docker CLI (e.g. podman-docker / other wrapper)\\n- Docker version is too old to load CLI plugins\\nFix:\\n- Use Docker Desktop / official docker-ce\\n- Ensure docker is the official CLI, then re-run.'\n fi\n fi\n\n # Check whether imagetools is available (and supports -t)\n docker buildx imagetools create --help &>/dev/null \\\n || die \"buildx exists but 'imagetools create' is not available. Please upgrade Docker/buildx.\"\n}\n\nrequire_buildx_imagetools\n\nACR_REGISTRY=\"agentscope-registry.ap-southeast-1.cr.aliyuncs.com\"\nIMAGE=\"agentscope/copaw\"\n\nACR_PRE=\"${ACR_REGISTRY}/${IMAGE}:pre\"\nACR_LATEST=\"${ACR_REGISTRY}/${IMAGE}:latest\"\nDH_PRE=\"docker.io/${IMAGE}:pre\"\nDH_LATEST=\"docker.io/${IMAGE}:latest\"\n\nlog \"ACR: ${ACR_PRE} -> ${ACR_LATEST}\"\ndocker buildx imagetools create -t \"$ACR_LATEST\" \"$ACR_PRE\"\n\nlog \"Docker Hub: ${DH_PRE} -> ${DH_LATEST}\"\ndocker buildx imagetools create -t \"$DH_LATEST\" \"$DH_PRE\"\n\nlog \"Done.\"\n" }, { "path": "scripts/install.bat", "content": "@echo off\r\nsetlocal EnableDelayedExpansion\r\n\r\nREM CoPaw Installer for Windows (cmd.exe / batch)\r\nREM Usage: install.bat [-Version X.Y.Z] [-FromSource] [-SourceDir DIR]\r\nREM [-Extras \"llamacpp,mlx\"] [-UvPath PATH] [-Help]\r\nREM\r\nREM Installs CoPaw into %USERPROFILE%\\.copaw with a uv-managed Python environment.\r\nREM Users do NOT need Python pre-installed -- uv handles everything.\r\nREM\r\nREM uv is obtained automatically (no action required from the user):\r\nREM 1. Found on PATH or in common locations\r\nREM 2. Downloaded via https://astral.sh/uv/install.ps1\r\nREM 3. Downloaded via GitHub Releases if astral.sh is unreachable (e.g. in China)\r\n\r\nREM ── Defaults ──────────────────────────────────────────────────────────────────\r\nif defined COPAW_HOME (\r\n set \"COPAW_HOME=%COPAW_HOME%\"\r\n) else (\r\n set \"COPAW_HOME=%USERPROFILE%\\.copaw\"\r\n)\r\nset \"COPAW_VENV=%COPAW_HOME%\\venv\"\r\nset \"COPAW_BIN=%COPAW_HOME%\\bin\"\r\nset \"PYTHON_VERSION=3.12\"\r\nset \"COPAW_REPO=https://github.com/agentscope-ai/CoPaw.git\"\r\n\r\nREM ──── Argument defaults ──────────────────────────────────────────────────────────────────────────────────────────────────────────────────\r\nset \"ARG_VERSION=\"\r\nset \"ARG_FROM_SOURCE=0\"\r\nset \"ARG_SOURCE_DIR=\"\r\nset \"ARG_EXTRAS=\"\r\nset \"ARG_UV_PATH=\"\r\nset \"CONSOLE_COPIED=0\"\r\nset \"CONSOLE_AVAILABLE=0\"\r\n\r\nREM ──── Parse arguments ──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────\r\n:parse_args\r\nif \"%~1\"==\"\" goto :done_args\r\nif /i \"%~1\"==\"-Version\" goto :arg_version\r\nif /i \"%~1\"==\"-FromSource\" goto :arg_fromsource\r\nif /i \"%~1\"==\"-SourceDir\" goto :arg_sourcedir\r\nif /i \"%~1\"==\"-Extras\" goto :arg_extras\r\nif /i \"%~1\"==\"-UvPath\" goto :arg_uvpath\r\nif /i \"%~1\"==\"-Help\" goto :show_help\r\nshift\r\ngoto :parse_args\r\n\r\n:arg_version\r\nset \"ARG_VERSION=%~2\"\r\nshift & shift\r\ngoto :parse_args\r\n\r\n:arg_fromsource\r\nset \"ARG_FROM_SOURCE=1\"\r\nshift\r\ngoto :parse_args\r\n\r\n:arg_sourcedir\r\nset \"ARG_SOURCE_DIR=%~2\"\r\nshift & shift\r\ngoto :parse_args\r\n\r\n:arg_extras\r\nset \"ARG_EXTRAS=%~2\"\r\nshift & shift\r\ngoto :parse_args\r\n\r\n:arg_uvpath\r\nset \"ARG_UV_PATH=%~2\"\r\nshift & shift\r\ngoto :parse_args\r\n\r\n:done_args\r\ngoto :main\r\n\r\nREM ──── Help ────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────\r\n:show_help\r\necho CoPaw Installer for Windows\r\necho.\r\necho Usage: install.bat [OPTIONS]\r\necho.\r\necho Options:\r\necho -Version ^ Install a specific version (e.g. 0.0.2)\r\necho -FromSource Install from source (requires git, or use -SourceDir)\r\necho -SourceDir ^ Local source directory (used with -FromSource)\r\necho -Extras ^ Comma-separated optional extras to install\r\necho (e.g. llamacpp, mlx, llamacpp,mlx)\r\necho -UvPath ^ Path to a pre-installed uv.exe (skips all auto-install)\r\necho -Help Show this help\r\necho.\r\necho Environment:\r\necho COPAW_HOME Installation directory (default: %%USERPROFILE%%\\.copaw)\r\nexit /b 0\r\n\r\nREM ──── Helper functions ────────────────────────────────────────────────────────────────────────────────────────────────────────────────────\r\n:write_info\r\necho [copaw] %~1\r\nexit /b 0\r\n\r\n:write_warn\r\necho [copaw] WARNING: %~1\r\nexit /b 0\r\n\r\n:write_err\r\necho [copaw] ERROR: %~1\r\nexit /b 0\r\n\r\n:stop_with_error\r\necho [copaw] ERROR: %~1\r\nexit /b 1\r\n\r\nREM ──── Download uv from GitHub Releases ────────────────────────────────────────────────────────────────────────────────────\r\nREM Subroutine: called when astral.sh is unreachable (e.g. in China).\r\nREM On success: uv.exe is in %LOCALAPPDATA%\\uv and that dir is prepended to PATH.\r\n:download_uv_github\r\nif /i \"%PROCESSOR_ARCHITECTURE%\"==\"ARM64\" (\r\n set \"_DL_ARCH=aarch64\"\r\n) else (\r\n set \"_DL_ARCH=x86_64\"\r\n)\r\nset \"_DL_URL=https://github.com/astral-sh/uv/releases/latest/download/uv-!_DL_ARCH!-pc-windows-msvc.zip\"\r\nset \"_DL_DEST=%LOCALAPPDATA%\\uv\"\r\nset \"_DL_ZIP=%TEMP%\\uv-gh-%RANDOM%.zip\"\r\n\r\necho [copaw] Downloading uv ^(!_DL_ARCH!^) from GitHub Releases...\r\n\r\nREM Try curl.exe (built into Windows 10+), then fall back to PowerShell\r\nwhere curl >nul 2>&1\r\nif not errorlevel 1 (\r\n curl -L --progress-bar -o \"!_DL_ZIP!\" \"!_DL_URL!\"\r\n if not errorlevel 1 goto :download_uv_extract\r\n echo [copaw] curl failed, retrying with PowerShell...\r\n del \"!_DL_ZIP!\" >nul 2>&1\r\n)\r\n\r\npowershell -NoProfile -Command \"$ProgressPreference='SilentlyContinue'; Invoke-WebRequest -Uri '!_DL_URL!' -OutFile '!_DL_ZIP!' -UseBasicParsing\"\r\nif errorlevel 1 (\r\n echo [copaw] ERROR: GitHub download also failed.\r\n echo [copaw] Download uv manually from: https://github.com/astral-sh/uv/releases/latest\r\n del \"!_DL_ZIP!\" >nul 2>&1\r\n exit /b 1\r\n)\r\n\r\n:download_uv_extract\r\nif not exist \"!_DL_DEST!\" mkdir \"!_DL_DEST!\"\r\necho [copaw] Extracting uv...\r\npowershell -NoProfile -Command \"Expand-Archive -Force -Path '!_DL_ZIP!' -DestinationPath '!_DL_DEST!'\"\r\nset \"_DL_ERR=%errorlevel%\"\r\ndel \"!_DL_ZIP!\" >nul 2>&1\r\nif %_DL_ERR% neq 0 (\r\n echo [copaw] ERROR: Extraction failed.\r\n exit /b 1\r\n)\r\nif not exist \"!_DL_DEST!\\uv.exe\" (\r\n echo [copaw] ERROR: uv.exe not found after extraction.\r\n exit /b 1\r\n)\r\nset \"PATH=!_DL_DEST!;!PATH!\"\r\necho [copaw] uv installed: !_DL_DEST!\\uv.exe\r\nexit /b 0\r\n\r\nREM ──── Ensure uv ──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────\r\n:ensure_uv\r\nREM 0. User-supplied path (-UvPath)\r\nif defined ARG_UV_PATH (\r\n if not exist \"%ARG_UV_PATH%\" (\r\n echo [copaw] ERROR: Specified uv not found: %ARG_UV_PATH%\r\n exit /b 1\r\n )\r\n for %%I in (\"%ARG_UV_PATH%\") do set \"PATH=%%~dpI;!PATH!\"\r\n echo [copaw] uv found: %ARG_UV_PATH%\r\n goto :ensure_uv_done\r\n)\r\n\r\nREM 1. Already on PATH\r\nwhere uv >nul 2>&1\r\nif %errorlevel%==0 (\r\n for /f \"delims=\" %%p in ('where uv 2^>nul') do (\r\n echo [copaw] uv found: %%p\r\n goto :ensure_uv_done\r\n )\r\n)\r\n\r\nREM 2. Common install locations not yet on PATH\r\nfor %%c in (\"%USERPROFILE%\\.local\\bin\\uv.exe\" \"%USERPROFILE%\\.cargo\\bin\\uv.exe\" \"%LOCALAPPDATA%\\uv\\uv.exe\") do (\r\n if exist %%c (\r\n set \"_UV_DIR=%%~dpc\"\r\n set \"PATH=!_UV_DIR!;!PATH!\"\r\n echo [copaw] uv found: %%~c\r\n goto :ensure_uv_done\r\n )\r\n)\r\n\r\nREM 3. Try astral.sh (standard installer, fast outside China)\r\necho [copaw] Installing uv via astral.sh...\r\npowershell -NoProfile -ExecutionPolicy Bypass -Command \"irm https://astral.sh/uv/install.ps1 -TimeoutSec 15 | iex\"\r\nif not errorlevel 1 goto :ensure_uv_refresh\r\n\r\nREM 4. astral.sh failed -- fall back to GitHub Releases (works in China)\r\necho [copaw] astral.sh unreachable, falling back to GitHub Releases...\r\ncall :download_uv_github\r\nif errorlevel 1 (\r\n echo [copaw] ERROR: Failed to install uv automatically.\r\n echo [copaw] Please install uv manually: https://docs.astral.sh/uv/\r\n exit /b 1\r\n)\r\ngoto :ensure_uv_done\r\n\r\n:ensure_uv_refresh\r\nREM Refresh PATH after astral.sh install\r\nfor %%p in (\"%USERPROFILE%\\.local\\bin\" \"%USERPROFILE%\\.cargo\\bin\" \"%LOCALAPPDATA%\\uv\") do (\r\n if exist %%p (\r\n echo \"!PATH!\" | findstr /i /c:\"%%~p\" >nul 2>&1\r\n if errorlevel 1 set \"PATH=%%~p;!PATH!\"\r\n )\r\n)\r\nwhere uv >nul 2>&1\r\nif errorlevel 1 (\r\n echo [copaw] ERROR: Failed to install uv. Please install it manually: https://docs.astral.sh/uv/\r\n exit /b 1\r\n)\r\necho [copaw] uv installed via astral.sh\r\n\r\n:ensure_uv_done\r\nexit /b 0\r\n\r\nREM ──── Prepare console frontend ────────────────────────────────────────────────────────────────────────────────────────────────────\r\n:prepare_console\r\nREM %~1 = RepoDir\r\nset \"_REPO_DIR=%~1\"\r\nset \"_CONSOLE_SRC=%_REPO_DIR%\\console\\dist\"\r\nset \"_CONSOLE_DEST=%_REPO_DIR%\\src\\copaw\\console\"\r\n\r\nREM Already populated\r\nif exist \"%_CONSOLE_DEST%\\index.html\" (\r\n set \"CONSOLE_AVAILABLE=1\"\r\n exit /b 0\r\n)\r\n\r\nREM Copy pre-built assets if available\r\nif exist \"%_CONSOLE_SRC%\\index.html\" (\r\n echo [copaw] Copying console frontend assets...\r\n if not exist \"%_CONSOLE_DEST%\" mkdir \"%_CONSOLE_DEST%\"\r\n xcopy /s /e /y /q \"%_CONSOLE_SRC%\\*\" \"%_CONSOLE_DEST%\\\" >nul\r\n set \"CONSOLE_COPIED=1\"\r\n set \"CONSOLE_AVAILABLE=1\"\r\n exit /b 0\r\n)\r\n\r\nREM Try to build if npm is available\r\nif not exist \"%_REPO_DIR%\\console\\package.json\" (\r\n echo [copaw] WARNING: Console source not found - the web UI won't be available.\r\n exit /b 0\r\n)\r\n\r\nwhere npm >nul 2>&1\r\nif errorlevel 1 (\r\n echo [copaw] WARNING: npm not found - skipping console frontend build.\r\n echo [copaw] WARNING: Install Node.js from https://nodejs.org/ then re-run this installer,\r\n echo [copaw] WARNING: or run 'cd console ^&^& npm ci ^&^& npm run build' manually.\r\n exit /b 0\r\n)\r\n\r\necho [copaw] Building console frontend (npm ci ^&^& npm run build)...\r\npushd \"%_REPO_DIR%\\console\"\r\nnpm ci\r\nif errorlevel 1 (\r\n popd\r\n echo [copaw] WARNING: npm ci failed - the web UI won't be available.\r\n exit /b 0\r\n)\r\nnpm run build\r\nif errorlevel 1 (\r\n popd\r\n echo [copaw] WARNING: npm run build failed - the web UI won't be available.\r\n exit /b 0\r\n)\r\npopd\r\n\r\nif exist \"%_CONSOLE_SRC%\\index.html\" (\r\n if not exist \"%_CONSOLE_DEST%\" mkdir \"%_CONSOLE_DEST%\"\r\n xcopy /s /e /y /q \"%_CONSOLE_SRC%\\*\" \"%_CONSOLE_DEST%\\\" >nul\r\n set \"CONSOLE_COPIED=1\"\r\n set \"CONSOLE_AVAILABLE=1\"\r\n echo [copaw] Console frontend built successfully\r\n exit /b 0\r\n)\r\n\r\necho [copaw] WARNING: Console build completed but index.html not found - the web UI won't be available.\r\nexit /b 0\r\n\r\nREM ──── Cleanup console frontend ────────────────────────────────────────────────────────────────────────────────────────────────────\r\n:cleanup_console\r\nREM %~1 = RepoDir\r\nif \"%CONSOLE_COPIED%\"==\"1\" (\r\n set \"_CLEANUP_DEST=%~1\\src\\copaw\\console\"\r\n if exist \"!_CLEANUP_DEST!\" rd /s /q \"!_CLEANUP_DEST!\" 2>nul\r\n)\r\nexit /b 0\r\n\r\nREM ══════════════════════════════ MAIN ═════════════════════════════════════════\r\n:main\r\necho [copaw] Installing CoPaw into %COPAW_HOME%\r\n\r\nREM ──── Step 1: Ensure uv ──────────────────────────────────────────────────────────────────────────────────────────────────────────────────\r\ncall :ensure_uv\r\nif errorlevel 1 exit /b 1\r\n\r\nREM ──── Step 2: Create / update virtual environment ──────────────────────────────────────────────────────────────\r\nif exist \"%COPAW_VENV%\" (\r\n echo [copaw] Existing environment found, upgrading...\r\n) else (\r\n echo [copaw] Creating Python %PYTHON_VERSION% environment...\r\n)\r\n\r\nuv venv \"%COPAW_VENV%\" --python %PYTHON_VERSION% --quiet --clear\r\nif errorlevel 1 (\r\n echo [copaw] ERROR: Failed to create virtual environment\r\n exit /b 1\r\n)\r\n\r\nset \"VENV_PYTHON=%COPAW_VENV%\\Scripts\\python.exe\"\r\nif not exist \"%VENV_PYTHON%\" (\r\n echo [copaw] ERROR: Failed to create virtual environment\r\n exit /b 1\r\n)\r\n\r\nfor /f \"delims=\" %%v in ('\"%VENV_PYTHON%\" --version 2^>^&1') do set \"PY_VERSION=%%v\"\r\necho [copaw] Python environment ready (%PY_VERSION%)\r\n\r\nREM ──── Step 3: Install CoPaw ──────────────────────────────────────────────────────────────────────────────────────────────────────────\r\nset \"EXTRAS_SUFFIX=\"\r\nif defined ARG_EXTRAS set \"EXTRAS_SUFFIX=[%ARG_EXTRAS%]\"\r\n\r\nset \"VENV_COPAW=%COPAW_VENV%\\Scripts\\copaw.exe\"\r\n\r\nREM Use goto-based branching to avoid nested parenthesized blocks,\r\nREM which break when %vars% expand to values containing \"(\" or \")\".\r\nif \"%ARG_FROM_SOURCE%\"==\"1\" goto :install_from_source\r\ngoto :install_from_pypi\r\n\r\n:install_from_source\r\nif defined ARG_SOURCE_DIR goto :install_from_local\r\ngoto :install_from_github_copaw\r\n\r\n:install_from_local\r\nfor %%I in (\"%ARG_SOURCE_DIR%\") do set \"ARG_SOURCE_DIR=%%~fI\"\r\necho [copaw] Installing CoPaw from local source: %ARG_SOURCE_DIR%\r\ncall :prepare_console \"%ARG_SOURCE_DIR%\"\r\necho [copaw] Installing package from source...\r\n\r\nrem === Secure Input Validation (Prevents Argument Injection) ===\r\nrem 1. Ensure non-empty\r\nif “%ARG_SOURCE_DIR%” == ‘’ set “ARG_SOURCE_DIR=.”\r\nif “%EXTRAS_SUFFIX%” == ‘’ set “EXTRAS_SUFFIX=”\r\n\r\nrem 2. Define invalid character set (double quotes, pipe, logical AND, redirection, brackets, percent sign, caret)\r\nrem These characters can break command structure or inject new parameters\r\nset “INVALID_CHARS=\\”|&<>()%%^\"\r\n\r\nrem 3. Validate ARG_SOURCE_DIR\r\nrem Logic: If the variable contains any invalid characters, findstr will match successfully (errorlevel 0)\r\necho %ARG_SOURCE_DIR% | findstr /R \"[\\\"|&<>()%%^]\" >nul 2>&1\r\nif not errorlevel 1 (\r\n echo [ERROR] Security Alert: ARG_SOURCE_DIR contains invalid characters.\r\n echo [ERROR] Detected unsafe input: %ARG_SOURCE_DIR%\r\n echo [ERROR] Installation aborted to prevent argument injection.\r\n call :cleanup_console \"%ARG_SOURCE_DIR%\"\r\n exit /b 1\r\n)\r\n\r\nrem 4. Validate EXTRAS_SUFFIX (typically formatted as [dev,test])\r\nrem Whitelist policy: Only letters, digits, commas, square brackets, underscores, and hyphens are permitted\r\nrem Logic: If any non-whitelisted character is present, findstr succeeds\r\necho %EXTRAS_SUFFIX% | findstr /R \"[^a-zA-Z0-9_,\\-\\[\\]]\" >nul 2>&1\r\nif not errorlevel 1 (\r\n echo [ERROR] Security Alert: EXTRAS_SUFFIX contains invalid characters.\r\n echo [ERROR] Detected unsafe input: %EXTRAS_SUFFIX%\r\n echo [ERROR] Only alphanumeric, commas, underscores, hyphens, and brackets are allowed.\r\n call :cleanup_console \"%ARG_SOURCE_DIR%\"\r\n exit /b 1\r\n)\r\nrem === End Security Validation ===\r\n\r\nrem The input has now been verified as safe and can proceed with installation.\r\nuv pip install \"%ARG_SOURCE_DIR%%EXTRAS_SUFFIX%\" --python \"%VENV_PYTHON%\" --prerelease=allow\r\nset \"_INST_ERR=%errorlevel%\"\r\ncall :cleanup_console \"%ARG_SOURCE_DIR%\"\r\nif %_INST_ERR% neq 0 (\r\n echo [copaw] ERROR: Installation from source failed\r\n exit /b 1\r\n)\r\ngoto :install_verify\r\n\r\n:install_from_github_copaw\r\nwhere git >nul 2>&1\r\nif errorlevel 1 (\r\n echo [copaw] ERROR: git is required for -FromSource without a local directory.\r\n echo [copaw] Please install Git from https://git-scm.com/ or pass a local path:\r\n echo [copaw] install-w-uv.bat -FromSource -SourceDir C:\\path\\to\\CoPaw\r\n exit /b 1\r\n)\r\necho [copaw] Installing CoPaw from source (GitHub)...\r\nset \"CLONE_DIR=%TEMP%\\copaw-install-%RANDOM%\"\r\ngit clone --depth 1 %COPAW_REPO% \"%CLONE_DIR%\"\r\nif errorlevel 1 (\r\n if exist \"%CLONE_DIR%\" rd /s /q \"%CLONE_DIR%\"\r\n echo [copaw] ERROR: Failed to clone repository\r\n exit /b 1\r\n)\r\ncall :prepare_console \"%CLONE_DIR%\"\r\necho [copaw] Installing package from source...\r\nuv pip install \"%CLONE_DIR%%EXTRAS_SUFFIX%\" --python \"%VENV_PYTHON%\" --prerelease=allow\r\nset \"_INST_ERR=%errorlevel%\"\r\nif exist \"%CLONE_DIR%\" rd /s /q \"%CLONE_DIR%\"\r\nif %_INST_ERR% neq 0 (\r\n echo [copaw] ERROR: Installation from source failed\r\n exit /b 1\r\n)\r\ngoto :install_verify\r\n\r\n:install_from_pypi\r\nset \"_PACKAGE=copaw\"\r\n\r\nrem === Secure Validation for ARG_VERSION ===\r\nif defined ARG_VERSION (\r\n rem Version number whitelist: Only permits numbers, letters, periods, comparison symbols (=<>!), hyphens, and tilde characters\r\n rem Prohibits spaces, quotation marks, slashes, and other characters potentially used for --index-url injection\r\n echo %ARG_VERSION% | findstr /R \"[^a-zA-Z0-9\\.=<>\\!\\-~]\" >nul 2>&1\r\n if not errorlevel 1 (\r\n echo [ERROR] Security Alert: ARG_VERSION contains invalid characters.\r\n echo [ERROR] Detected unsafe input: %ARG_VERSION%\r\n echo [ERROR] Installation aborted.\r\n exit /b 1\r\n )\r\n set \"_PACKAGE=copaw%ARG_VERSION%\"\r\n)\r\nrem === End Version Validation ===\r\n\r\necho [copaw] Installing %_PACKAGE%%EXTRAS_SUFFIX% from PyPI...\r\nrem Note: It is also recommended to validate EXTRAS_SUFFIX here. Although it may be undefined in the local scope above,\r\nrem for safety, if ARG_EXTRAS is defined globally, it is best to reuse the validation logic from above or ensure its source is secure.\r\nrem Assume EXTRAS_SUFFIX is generated here based on the previously validated ARG_EXTRAS, or is empty.\r\nrem If ARG_EXTRAS is passed globally, it is recommended to validate it uniformly at the beginning of the script.\r\n\r\nuv pip install \"%_PACKAGE%%EXTRAS_SUFFIX%\" --python \"%VENV_PYTHON%\" --prerelease=allow --quiet --refresh-package copaw\r\nif errorlevel 1 (\r\n echo [copaw] ERROR: Installation failed\r\n exit /b 1\r\n)\r\n\r\n:install_verify\r\n\r\nREM Verify the CLI entry point exists\r\nif not exist \"%VENV_COPAW%\" (\r\n echo [copaw] ERROR: Installation failed: copaw CLI not found in venv\r\n exit /b 1\r\n)\r\necho [copaw] CoPaw installed successfully\r\n\r\nREM Check console availability (for PyPI installs, probe the installed package)\r\nif \"%CONSOLE_AVAILABLE%\"==\"0\" (\r\n \"%VENV_PYTHON%\" -c \"import importlib.resources, copaw; p=importlib.resources.files('copaw')/'console'/'index.html'; print('yes' if p.is_file() else 'no')\" > \"%TEMP%\\_copaw_console_check.tmp\" 2>&1\r\n set /p CONSOLE_CHECK=<\"%TEMP%\\_copaw_console_check.tmp\"\r\n del \"%TEMP%\\_copaw_console_check.tmp\" >nul 2>&1\r\n if \"!CONSOLE_CHECK!\"==\"yes\" set \"CONSOLE_AVAILABLE=1\"\r\n)\r\n\r\nREM ──── Step 4: Create wrapper scripts ────────────────────────────────────────────────────────────────────────────────────────\r\nif not exist \"%COPAW_BIN%\" mkdir \"%COPAW_BIN%\"\r\n\r\nREM PowerShell wrapper\r\nset \"WRAPPER_PS1=%COPAW_BIN%\\copaw.ps1\"\r\necho # CoPaw CLI wrapper -- delegates to the uv-managed environment. > \"%WRAPPER_PS1%\"\r\necho $ErrorActionPreference = \"Stop\" >> \"%WRAPPER_PS1%\"\r\necho. >> \"%WRAPPER_PS1%\"\r\necho $CopawHome = if ($env:COPAW_HOME) { $env:COPAW_HOME } else { Join-Path $HOME \".copaw\" } >> \"%WRAPPER_PS1%\"\r\necho $RealBin = Join-Path $CopawHome \"venv\\Scripts\\copaw.exe\" >> \"%WRAPPER_PS1%\"\r\necho. >> \"%WRAPPER_PS1%\"\r\necho if (-not (Test-Path $RealBin)) { >> \"%WRAPPER_PS1%\"\r\necho Write-Error \"CoPaw environment not found at $CopawHome\\venv\" >> \"%WRAPPER_PS1%\"\r\necho Write-Error \"Please reinstall: irm ^ ^| iex\" >> \"%WRAPPER_PS1%\"\r\necho exit 1 >> \"%WRAPPER_PS1%\"\r\necho } >> \"%WRAPPER_PS1%\"\r\necho. >> \"%WRAPPER_PS1%\"\r\necho ^& $RealBin @args >> \"%WRAPPER_PS1%\"\r\necho [copaw] Wrapper created at %WRAPPER_PS1%\r\n\r\nREM CMD wrapper\r\nset \"WRAPPER_CMD=%COPAW_BIN%\\copaw.cmd\"\r\necho @echo off > \"%WRAPPER_CMD%\"\r\necho REM CoPaw CLI wrapper -- delegates to the uv-managed environment. >> \"%WRAPPER_CMD%\"\r\necho set \"COPAW_HOME=%%COPAW_HOME%%\" >> \"%WRAPPER_CMD%\"\r\necho if \"%%COPAW_HOME%%\"==\"\" set \"COPAW_HOME=%%USERPROFILE%%\\.copaw\" >> \"%WRAPPER_CMD%\"\r\necho set \"REAL_BIN=%%COPAW_HOME%%\\venv\\Scripts\\copaw.exe\" >> \"%WRAPPER_CMD%\"\r\necho if not exist \"%%REAL_BIN%%\" ( >> \"%WRAPPER_CMD%\"\r\necho echo Error: CoPaw environment not found at %%COPAW_HOME%%\\venv ^>^&2 >> \"%WRAPPER_CMD%\"\r\necho echo Please reinstall ^>^&2 >> \"%WRAPPER_CMD%\"\r\necho exit /b 1 >> \"%WRAPPER_CMD%\"\r\necho ) >> \"%WRAPPER_CMD%\"\r\necho \"%%REAL_BIN%%\" %%* >> \"%WRAPPER_CMD%\"\r\necho [copaw] CMD wrapper created at %WRAPPER_CMD%\r\n\r\nREM ──── Step 5: Update PATH via user environment variable ──────────────────────────────────────────────────\r\nset \"CURRENT_USER_PATH=\"\r\nfor /f \"skip=2 tokens=1,2,*\" %%a in ('reg query \"HKCU\\Environment\" /v Path 2^>nul') do (\r\n if /i \"%%a\"==\"Path\" set \"CURRENT_USER_PATH=%%c\"\r\n)\r\n\r\n:: === 安全检查PATH是否已存在（关键修复） ===\r\nset \"path_check=;%CURRENT_USER_PATH%;\"\r\nset \"check_str=;%COPAW_BIN%;\"\r\nif /i \"%path_check%\" neq \"%path_check:%check_str%=%\" (\r\n echo [copaw] %COPAW_BIN% already in PATH\r\n) else (\r\n :: === 修复1：安全传递参数（解决命令注入） ===\r\n if defined CURRENT_USER_PATH (\r\n powershell -NoProfile -Command \"$p = $args[0]; $v = $args[1]; [Environment]::SetEnvironmentVariable('Path', $p + ';' + $v, 'User')\" \"%COPAW_BIN%\" \"!CURRENT_USER_PATH!\"\r\n ) else (\r\n powershell -NoProfile -Command \"$p = $args[0]; [Environment]::SetEnvironmentVariable('Path', $p, 'User')\" \"%COPAW_BIN%\"\r\n )\r\n\r\n :: === 修复2：添加关键错误检查（解决失败不报错） ===\r\n if errorlevel 1 (\r\n echo [error] Failed to update PATH. COPAW_BIN: \"%COPAW_BIN%\"\r\n echo [error] Please verify the path is valid.\r\n exit /b 1\r\n )\r\n\r\n :: === 修复3：安全更新当前进程PATH ===\r\n set \"PATH=%COPAW_BIN%;!PATH!\"\r\n echo [copaw] Added %COPAW_BIN% to PATH\r\n)\r\n\r\nREM ──── Done ────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────\r\necho.\r\necho CoPaw installed successfully!\r\necho.\r\necho Install location: %COPAW_HOME%\r\necho Python: %PY_VERSION%\r\nif \"%CONSOLE_AVAILABLE%\"==\"1\" (\r\n echo Console ^(web UI^): available\r\n) else (\r\n echo Console ^(web UI^): not available\r\n echo Install Node.js and re-run to enable the web UI.\r\n)\r\necho.\r\necho To get started, open a new terminal and run:\r\necho.\r\necho copaw init # first-time setup\r\necho copaw app # start CoPaw\r\necho.\r\necho To upgrade later, re-run this installer.\r\necho To uninstall, run: copaw uninstall\r\n\r\nexit /b 0\r\n" }, { "path": "scripts/install.ps1", "content": "# CoPaw Installer for Windows (self-contained: includes uv download via GitHub)\n# Usage: irm /install.ps1 | iex\n# or: .\\install.ps1 [-Version X.Y.Z] [-FromSource] [-SourceDir DIR]\n# [-Extras \"llamacpp,mlx\"] [-UvPath PATH]\n#\n# Installs CoPaw into ~/.copaw with a uv-managed Python environment.\n# Users do NOT need Python pre-installed — uv handles everything.\n#\n# uv is obtained automatically (no action required from the user):\n# 1. Already on PATH or in common locations\n# 2. Downloaded via https://astral.sh/uv/install.ps1\n# 3. Downloaded via GitHub Releases if astral.sh is unreachable (e.g. in China)\n#\n# The entire script is wrapped in & { ... } @args so that `irm | iex` works\n# correctly (param() is only valid inside a scriptblock/function/file scope).\n\n& {\nparam(\n [string]$Version = \"\",\n [switch]$FromSource,\n [string]$SourceDir = \"\",\n [string]$Extras = \"\",\n [string]$UvPath = \"\",\n [switch]$Help\n)\n\n$ErrorActionPreference = \"Stop\"\n\n# ── Defaults ──────────────────────────────────────────────────────────────────\n$CopawHome = if ($env:COPAW_HOME) { $env:COPAW_HOME } else { Join-Path $HOME \".copaw\" }\n$CopawVenv = Join-Path $CopawHome \"venv\"\n$CopawBin = Join-Path $CopawHome \"bin\"\n$PythonVersion = \"3.12\"\n$CopawRepo = \"https://github.com/agentscope-ai/CoPaw.git\"\n\n# ── Colors ────────────────────────────────────────────────────────────────────\nfunction Write-Info { param([string]$Message) Write-Host \"[copaw] \" -ForegroundColor Green -NoNewline; Write-Host $Message }\nfunction Write-Warn { param([string]$Message) Write-Host \"[copaw] \" -ForegroundColor Yellow -NoNewline; Write-Host $Message }\nfunction Write-Err { param([string]$Message) Write-Host \"[copaw] \" -ForegroundColor Red -NoNewline; Write-Host $Message }\nfunction Stop-WithError { param([string]$Message) Write-Err $Message; exit 1 }\n\n# ── Help ──────────────────────────────────────────────────────────────────────\nif ($Help) {\n @\"\nCoPaw Installer for Windows\n\nUsage: .\\install.ps1 [OPTIONS]\n\nOptions:\n -Version Install a specific version (e.g. 0.0.2)\n -FromSource Install from source (requires git, or use -SourceDir)\n -SourceDir Local source directory (used with -FromSource)\n -Extras Comma-separated optional extras to install\n (e.g. llamacpp, mlx, llamacpp,mlx)\n -UvPath Path to a pre-installed uv.exe (skips all auto-install)\n -Help Show this help\n\nEnvironment:\n COPAW_HOME Installation directory (default: ~/.copaw)\n\"@\n exit 0\n}\n\nWrite-Host \"[copaw] \" -ForegroundColor Green -NoNewline\nWrite-Host \"Installing CoPaw into \" -NoNewline\nWrite-Host \"$CopawHome\" -ForegroundColor White\n\n# ── Execution Policy Check ────────────────────────────────────────────────────\n$policy = Get-ExecutionPolicy\nif ($policy -eq \"Restricted\") {\n Write-Info \"Execution policy is 'Restricted', setting to RemoteSigned for current user...\"\n try {\n Set-ExecutionPolicy RemoteSigned -Scope CurrentUser -Force\n Write-Info \"Execution policy updated to RemoteSigned\"\n } catch {\n Write-Err \"PowerShell execution policy is set to 'Restricted' which prevents script execution.\"\n Write-Err \"Please run the following command and retry:\"\n Write-Err \"\"\n Write-Err \" Set-ExecutionPolicy RemoteSigned -Scope CurrentUser\"\n Write-Err \"\"\n exit 1\n }\n}\n\n# ── Step 1: Ensure uv is available ───────────────────────────────────────────\n\nfunction Invoke-UvFromGitHub {\n # Downloads uv from GitHub Releases and prepends its directory to PATH.\n # Used automatically when astral.sh is unreachable (e.g. in China).\n $arch = if ($env:PROCESSOR_ARCHITECTURE -eq \"ARM64\") { \"aarch64\" } else { \"x86_64\" }\n $url = \"https://github.com/astral-sh/uv/releases/latest/download/uv-$arch-pc-windows-msvc.zip\"\n $dest = Join-Path $env:LOCALAPPDATA \"uv\"\n $zip = Join-Path $env:TEMP \"uv-gh-$([System.IO.Path]::GetRandomFileName()).zip\"\n\n Write-Info \"Downloading uv ($arch) from GitHub Releases...\"\n $ProgressPreference = 'SilentlyContinue' # prevents 100x slowdown in PS 5.1\n try {\n Invoke-WebRequest -Uri $url -OutFile $zip -UseBasicParsing\n } catch {\n throw \"GitHub download failed: $_\"\n }\n\n if (-not (Test-Path $dest)) { New-Item -ItemType Directory -Path $dest -Force | Out-Null }\n\n Write-Info \"Extracting uv...\"\n try {\n Expand-Archive -Force -Path $zip -DestinationPath $dest\n } catch {\n Remove-Item $zip -ErrorAction SilentlyContinue\n throw \"Extraction failed: $_\"\n }\n Remove-Item $zip -ErrorAction SilentlyContinue\n\n $uvExe = Join-Path $dest \"uv.exe\"\n if (-not (Test-Path $uvExe)) { throw \"uv.exe not found after extraction at $dest\" }\n\n $env:PATH = \"$dest;$env:PATH\"\n Write-Info \"uv installed from GitHub: $uvExe\"\n}\n\nfunction Ensure-Uv {\n # 0. User-supplied path (-UvPath)\n if ($UvPath) {\n if (-not (Test-Path $UvPath)) { Stop-WithError \"Specified uv not found: $UvPath\" }\n $env:PATH = \"$(Split-Path $UvPath -Parent);$env:PATH\"\n Write-Info \"uv found: $UvPath\"\n return\n }\n\n # 1. Already on PATH\n if (Get-Command uv -ErrorAction SilentlyContinue) {\n Write-Info \"uv found: $((Get-Command uv).Source)\"\n return\n }\n\n # 2. Common install locations not yet on PATH\n $candidates = @(\n (Join-Path $HOME \".local\\bin\\uv.exe\"),\n (Join-Path $HOME \".cargo\\bin\\uv.exe\"),\n (Join-Path $env:LOCALAPPDATA \"uv\\uv.exe\")\n )\n foreach ($candidate in $candidates) {\n if (Test-Path $candidate) {\n $env:PATH = \"$(Split-Path $candidate -Parent);$env:PATH\"\n Write-Info \"uv found: $candidate\"\n return\n }\n }\n\n # 3. Try astral.sh (standard installer, fast outside China)\n Write-Warn \"If automatic uv installation fails, please manually install uv first by following https://github.com/astral-sh/uv/releases, then re-run this installer.\"\n Write-Warn \"Alternatively, if Python is already installed, run: python -m pip install -U uv\"\n Write-Info \"Installing uv via astral.sh...\"\n $astralOk = $false\n try {\n $installScript = Invoke-RestMethod https://astral.sh/uv/install.ps1 -TimeoutSec 15\n Invoke-Expression $installScript\n $astralOk = $true\n } catch {\n Write-Warn \"astral.sh unreachable, falling back to GitHub Releases...\"\n }\n\n if ($astralOk) {\n # Refresh PATH after astral.sh install\n $uvPaths = @(\n (Join-Path $HOME \".local\\bin\"),\n (Join-Path $HOME \".cargo\\bin\"),\n (Join-Path $env:LOCALAPPDATA \"uv\")\n )\n foreach ($p in $uvPaths) {\n if ((Test-Path $p) -and ($env:PATH -notlike \"*$p*\")) {\n $env:PATH = \"$p;$env:PATH\"\n }\n }\n if (Get-Command uv -ErrorAction SilentlyContinue) {\n Write-Info \"uv installed via astral.sh\"\n return\n }\n Write-Warn \"astral.sh install succeeded but uv not found on PATH, trying GitHub Releases...\"\n }\n\n # 4. GitHub Releases fallback (works in China)\n try {\n Invoke-UvFromGitHub\n } catch {\n Stop-WithError \"Failed to install uv automatically: $_`nPlease install uv manually: https://docs.astral.sh/uv/\"\n }\n if (-not (Get-Command uv -ErrorAction SilentlyContinue)) {\n Stop-WithError \"Failed to install uv. Please install it manually: https://docs.astral.sh/uv/\"\n }\n}\n\nEnsure-Uv\n\n# ── Step 2: Create / update virtual environment ──────────────────────────────\nif (Test-Path $CopawVenv) {\n Write-Info \"Existing environment found, upgrading...\"\n} else {\n Write-Info \"Creating Python $PythonVersion environment...\"\n}\n\nuv venv $CopawVenv --python $PythonVersion --quiet --clear\nif ($LASTEXITCODE -ne 0) { Stop-WithError \"Failed to create virtual environment\" }\n\n$VenvPython = Join-Path $CopawVenv \"Scripts\\python.exe\"\nif (-not (Test-Path $VenvPython)) { Stop-WithError \"Failed to create virtual environment\" }\n\n$pyVersion = & $VenvPython --version 2>&1\nWrite-Info \"Python environment ready ($pyVersion)\"\n\n# ── Step 3: Install CoPaw ────────────────────────────────────────────────────\n$ExtrasSuffix = \"\"\nif ($Extras) { $ExtrasSuffix = \"[$Extras]\" }\n\n$script:ConsoleCopied = $false\n$script:ConsoleAvailable = $false\n\nfunction Prepare-Console {\n param([string]$RepoDir)\n\n $consoleSrc = Join-Path $RepoDir \"console\\dist\"\n $consoleDest = Join-Path $RepoDir \"src\\copaw\\console\"\n\n # Already populated\n if (Test-Path (Join-Path $consoleDest \"index.html\")) { $script:ConsoleAvailable = $true; return }\n\n # Copy pre-built assets if available\n if ((Test-Path $consoleSrc) -and (Test-Path (Join-Path $consoleSrc \"index.html\"))) {\n Write-Info \"Copying console frontend assets...\"\n New-Item -ItemType Directory -Path $consoleDest -Force | Out-Null\n Copy-Item -Path \"$consoleSrc\\*\" -Destination $consoleDest -Recurse -Force\n $script:ConsoleCopied = $true\n $script:ConsoleAvailable = $true\n return\n }\n\n # Try to build if npm is available\n $packageJson = Join-Path $RepoDir \"console\\package.json\"\n if (-not (Test-Path $packageJson)) {\n Write-Warn \"Console source not found - the web UI won't be available.\"\n return\n }\n\n if (-not (Get-Command npm -ErrorAction SilentlyContinue)) {\n Write-Warn \"npm not found - skipping console frontend build.\"\n Write-Warn \"Install Node.js from https://nodejs.org/ then re-run this installer,\"\n Write-Warn \"or run 'cd console && npm ci && npm run build' manually.\"\n return\n }\n\n Write-Info \"Building console frontend (npm ci && npm run build)...\"\n Push-Location (Join-Path $RepoDir \"console\")\n try {\n npm ci\n if ($LASTEXITCODE -ne 0) { Write-Warn \"npm ci failed - the web UI won't be available.\"; return }\n npm run build\n if ($LASTEXITCODE -ne 0) { Write-Warn \"npm run build failed - the web UI won't be available.\"; return }\n } finally {\n Pop-Location\n }\n if (Test-Path (Join-Path $consoleSrc \"index.html\")) {\n New-Item -ItemType Directory -Path $consoleDest -Force | Out-Null\n Copy-Item -Path \"$consoleSrc\\*\" -Destination $consoleDest -Recurse -Force\n $script:ConsoleCopied = $true\n $script:ConsoleAvailable = $true\n Write-Info \"Console frontend built successfully\"\n return\n }\n\n Write-Warn \"Console build completed but index.html not found - the web UI won't be available.\"\n}\n\nfunction Cleanup-Console {\n param([string]$RepoDir)\n if ($script:ConsoleCopied) {\n $consoleDest = Join-Path $RepoDir \"src\\copaw\\console\"\n if (Test-Path $consoleDest) {\n Remove-Item -Path \"$consoleDest\\*\" -Recurse -Force -ErrorAction SilentlyContinue\n }\n }\n}\n\n$VenvCopaw = Join-Path $CopawVenv \"Scripts\\copaw.exe\"\n\nif ($FromSource) {\n if ($SourceDir) {\n $SourceDir = (Resolve-Path $SourceDir).Path\n Write-Info \"Installing CoPaw from local source: $SourceDir\"\n Prepare-Console $SourceDir\n Write-Info \"Installing package from source...\"\n uv pip install \"${SourceDir}${ExtrasSuffix}\" --python $VenvPython --prerelease=allow\n if ($LASTEXITCODE -ne 0) { Stop-WithError \"Installation from source failed\" }\n Cleanup-Console $SourceDir\n } else {\n if (-not (Get-Command git -ErrorAction SilentlyContinue)) {\n Stop-WithError \"git is required for -FromSource without a local directory. Please install Git from https://git-scm.com/ or pass a local path: .\\install.ps1 -FromSource -SourceDir C:\\path\\to\\CoPaw\"\n }\n Write-Info \"Installing CoPaw from source (GitHub)...\"\n $cloneDir = Join-Path $env:TEMP \"copaw-install-$(Get-Random)\"\n try {\n git clone --depth 1 $CopawRepo $cloneDir\n if ($LASTEXITCODE -ne 0) { Stop-WithError \"Failed to clone repository\" }\n Prepare-Console $cloneDir\n Write-Info \"Installing package from source...\"\n uv pip install \"${cloneDir}${ExtrasSuffix}\" --python $VenvPython --prerelease=allow\n if ($LASTEXITCODE -ne 0) { Stop-WithError \"Installation from source failed\" }\n } finally {\n if (Test-Path $cloneDir) {\n Remove-Item -Path $cloneDir -Recurse -Force -ErrorAction SilentlyContinue\n }\n }\n }\n} else {\n $package = \"copaw\"\n if ($Version) { $package = \"copaw==$Version\" }\n\n Write-Info \"Installing ${package}${ExtrasSuffix} from PyPI...\"\n uv pip install \"${package}${ExtrasSuffix}\" --python $VenvPython --prerelease=allow --quiet --refresh-package copaw\n if ($LASTEXITCODE -ne 0) { Stop-WithError \"Installation failed\" }\n}\n\n# Verify the CLI entry point exists\nif (-not (Test-Path $VenvCopaw)) { Stop-WithError \"Installation failed: copaw CLI not found in venv\" }\n\nWrite-Info \"CoPaw installed successfully\"\n\n# Check console availability (for PyPI installs, check the installed package)\nif (-not $script:ConsoleAvailable) {\n $consoleCheck = & $VenvPython -c \"import importlib.resources, copaw; p=importlib.resources.files('copaw')/'console'/'index.html'; print('yes' if p.is_file() else 'no')\" 2>&1\n if ($consoleCheck -eq \"yes\") { $script:ConsoleAvailable = $true }\n}\n\n# ── Step 4: Create wrapper scripts ───────────────────────────────────────────\nNew-Item -ItemType Directory -Path $CopawBin -Force | Out-Null\n\n$wrapperPath = Join-Path $CopawBin \"copaw.ps1\"\n$wrapperContent = @'\n# CoPaw CLI wrapper — delegates to the uv-managed environment.\n$ErrorActionPreference = \"Stop\"\n\n$CopawHome = if ($env:COPAW_HOME) { $env:COPAW_HOME } else { Join-Path $HOME \".copaw\" }\n$RealBin = Join-Path $CopawHome \"venv\\Scripts\\copaw.exe\"\n\nif (-not (Test-Path $RealBin)) {\n Write-Error \"CoPaw environment not found at $CopawHome\\venv\"\n Write-Error \"Please reinstall: irm | iex\"\n exit 1\n}\n\n& $RealBin @args\n'@\n\nSet-Content -Path $wrapperPath -Value $wrapperContent -Encoding UTF8\nWrite-Info \"Wrapper created at $wrapperPath\"\n\n# Also create a .cmd wrapper for use from cmd.exe\n$cmdWrapperPath = Join-Path $CopawBin \"copaw.cmd\"\n$cmdWrapperContent = @\"\n@echo off\nREM CoPaw CLI wrapper — delegates to the uv-managed environment.\nset \"COPAW_HOME=%COPAW_HOME%\"\nif \"%COPAW_HOME%\"==\"\" set \"COPAW_HOME=%USERPROFILE%\\.copaw\"\nset \"REAL_BIN=%COPAW_HOME%\\venv\\Scripts\\copaw.exe\"\nif not exist \"%REAL_BIN%\" (\n echo Error: CoPaw environment not found at %COPAW_HOME%\\venv >&2\n echo Please reinstall: irm ^ ^| iex >&2\n exit /b 1\n)\n\"%REAL_BIN%\" %*\n\"@\n\nSet-Content -Path $cmdWrapperPath -Value $cmdWrapperContent -Encoding UTF8\nWrite-Info \"CMD wrapper created at $cmdWrapperPath\"\n\n# ──Step 5: Update PATH via User Environment Variable ────────────────────────\n$targetPath = $CopawBin\n$registryPath = \"HKCU:\\Environment\"\n$registryName = \"Path\"\n\n# 1. 安全获取当前的 User PATH (直接从注册表读取，避免污染 Machine PATH)\ntry {\n $currentUserPath = (Get-ItemProperty -Path $registryPath -Name $registryName -ErrorAction SilentlyContinue).Path\n if (-not $currentUserPath) { $currentUserPath = \"\" }\n} catch {\n # 如果连读都失败（极罕见），则从头开始\n $currentUserPath = \"\"\n Write-Debug \"Could not read User Path from registry, starting fresh.\"\n}\n\n# 2. 精确检查是否已存在 (解决前缀匹配误判)\n# 分割路径并去除空格\n$pathArray = $currentUserPath -split ';' | ForEach-Object { $_.Trim() }\n$isAlreadyAdded = $pathArray -contains $targetPath\n\nif (-not $isAlreadyAdded) {\n # 构建新的 User PATH 字符串\n if ($currentUserPath) {\n $newUserPath = \"$targetPath;$currentUserPath\"\n } else {\n $newUserPath = $targetPath\n }\n\n # 3. 核心修复：使用 SetItemProperty 代替 [Environment]::SetEnvironmentVariable\n # 这是原生 cmdlet，在 Constrained Language Mode 下通常可用\n try {\n # 确保注册表路径存在 (HKCU:\\Environment 通常默认存在，但为了健壮性检查一下)\n if (-not (Test-Path $registryPath)) {\n # 这种情况极少见，但如果发生，尝试创建（通常需要权限，若失败则进入 catch）\n New-Item -Path $registryPath -Force | Out-Null\n }\n\n # 写入注册表\n SetItemProperty -Path $registryPath -Name $registryName -Value $newUserPath\n\n # 更新当前进程的环境变量，使当前终端立即生效\n $env:Path = \"$targetPath;$env:Path\"\n\n Write-Info \"Successfully added $targetPath to User PATH (via Registry)\"\n\n } catch {\n # 如果连 SetItemProperty 都失败（例如注册表被组策略完全锁定）\n $errorMsg = $_.Exception.Message\n\n Write-Host \"\"\n Write-Host \"[CRITICAL WARNING] Automatic PATH update failed.\" -ForegroundColor Red\n Write-Host \" Reason: $errorMsg\"\n Write-Host \" Context: Your system policy strictly blocks environment modifications.\"\n Write-Host \"\"\n Write-Host \"ACTION REQUIRED: You must manually add the path to use CoPaw.\"\n Write-Host \" Target Path: $targetPath\"\n Write-Host \"\"\n Write-Host \"Manual Steps (User Variables):\"\n Write-Host \" 1. Press Win+R, type 'sysdm.cpl' and press Enter\"\n Write-Host \" 2. Go to [Advanced] > [Environment Variables...]\"\n Write-Host \" 3. In the TOP section ('User variables'), select 'Path' > [Edit]\"\n Write-Host \" (If 'Path' doesn't exist in User variables, click [New] and name it 'Path')\"\n Write-Host \" 4. Click [New] and paste: $targetPath\"\n Write-Host \" 5. Click [OK] everywhere to save.\"\n Write-Host \" 6. CLOSE and REOPEN your terminal.\"\n Write-Host \"\"\n\n # 即使注册表写入失败，也尝试更新当前会话以便用户测试（如果不报错的话）\n # 注意：如果策略极严，这行也可能无效，但尝试一下无害\n try {\n $env:Path = \"$targetPath;$env:Path\"\n } catch {}\n }\n} else {\n Write-Info \"$targetPath is already in your User PATH\"\n}\n\n# ── Done ──────────────────────────────────────────────────────────────────────\nWrite-Host \"\"\nWrite-Host \"CoPaw installed successfully!\" -ForegroundColor Green\nWrite-Host \"\"\n\nWrite-Host \" Install location: \" -NoNewline; Write-Host \"$CopawHome\" -ForegroundColor White\nWrite-Host \" Python: \" -NoNewline; Write-Host \"$pyVersion\" -ForegroundColor White\nif ($script:ConsoleAvailable) {\n Write-Host \" Console (web UI): \" -NoNewline; Write-Host \"available\" -ForegroundColor Green\n} else {\n Write-Host \" Console (web UI): \" -NoNewline; Write-Host \"not available\" -ForegroundColor Yellow\n Write-Host \" Install Node.js and re-run to enable the web UI.\"\n}\nWrite-Host \"\"\n\nWrite-Host \"To get started, open a new terminal and run:\"\nWrite-Host \"\"\nWrite-Host \" copaw init\" -ForegroundColor White -NoNewline; Write-Host \" # first-time setup\"\nWrite-Host \" copaw app\" -ForegroundColor White -NoNewline; Write-Host \" # start CoPaw\"\nWrite-Host \"\"\nWrite-Host \"To upgrade later, re-run this installer.\"\nWrite-Host \"To uninstall, run: \" -NoNewline\nWrite-Host \"copaw uninstall\" -ForegroundColor White\n\n} @args\n" }, { "path": "scripts/install.sh", "content": "#!/usr/bin/env bash\n# CoPaw Installer\n# Usage: curl -fsSL /install.sh | bash\n# or: bash install.sh [--version X.Y.Z] [--from-source]\n#\n# Installs CoPaw into ~/.copaw with a uv-managed Python environment.\n# Users do NOT need Python pre-installed — uv handles everything.\nset -euo pipefail\n\n# ── Colors ────────────────────────────────────────────────────────────────────\nif [ -t 1 ]; then\n BOLD=\"\\033[1m\"\n GREEN=\"\\033[0;32m\"\n YELLOW=\"\\033[0;33m\"\n RED=\"\\033[0;31m\"\n RESET=\"\\033[0m\"\nelse\n BOLD=\"\" GREEN=\"\" YELLOW=\"\" RED=\"\" RESET=\"\"\nfi\n\ninfo() { printf \"${GREEN}[copaw]${RESET} %s\\n\" \"$*\"; }\nwarn() { printf \"${YELLOW}[copaw]${RESET} %s\\n\" \"$*\"; }\nerror() { printf \"${RED}[copaw]${RESET} %s\\n\" \"$*\" >&2; }\ndie() { error \"$@\"; exit 1; }\n\n# ── Defaults ──────────────────────────────────────────────────────────────────\nCOPAW_HOME=\"${COPAW_HOME:-$HOME/.copaw}\"\nCOPAW_VENV=\"$COPAW_HOME/venv\"\nCOPAW_BIN=\"$COPAW_HOME/bin\"\nPYTHON_VERSION=\"3.12\"\nCOPAW_REPO=\"https://github.com/agentscope-ai/CoPaw.git\"\n\n# New: Intelligent selection of PyPI source (automatically using Alibaba Cloud mirror for domestic users, and official source for overseas users)\nchoose_pypi_mirror() {\n # Test the connectivity of the official PyPI source (timeout 3 seconds, no output)\n if curl -s --connect-timeout 3 https://pypi.org/simple/ > /dev/null 2>&1; then\n echo \"https://pypi.org/simple/\"\n info \"Using official PyPI source (network is good)\" >&2\n else\n echo \"https://mirrors.aliyun.com/pypi/simple/\"\n info \"Using Aliyun PyPI mirror (official source is unreachable)\" >&2\n fi\n}\nPYPI_MIRROR=$(choose_pypi_mirror)\n\n# New: Automatically clear old virtual environments and skip interactive prompts\nexport UV_VENV_CLEAR=1\n\n\n\n\nVERSION=\"\"\nFROM_SOURCE=false\nSOURCE_DIR=\"\"\nEXTRAS=\"\"\n\n# ── Parse args ────────────────────────────────────────────────────────────────\nwhile [[ $# -gt 0 ]]; do\n case \"$1\" in\n --version)\n VERSION=\"$2\"; shift 2 ;;\n --from-source)\n FROM_SOURCE=true\n # Accept optional path argument (next arg that doesn't start with --)\n if [[ $# -ge 2 && \"$2\" != --* ]]; then\n SOURCE_DIR=\"$(cd \"$2\" && pwd)\" || die \"Directory not found: $2\"\n shift\n fi\n shift ;;\n --extras)\n EXTRAS=\"$2\"; shift 2 ;;\n -h|--help)\n cat < Install a specific version (e.g. 0.0.2)\n --from-source [DIR] Install from source. If DIR is given, use that local\n directory; otherwise clone from GitHub.\n --extras Comma-separated optional extras to install\n (e.g. llamacpp, mlx, llamacpp,mlx)\n -h, --help Show this help\n\nEnvironment:\n COPAW_HOME Installation directory (default: ~/.copaw)\nEOF\n exit 0 ;;\n *)\n die \"Unknown option: $1 (try --help)\" ;;\n esac\ndone\n\n# ── OS check ──────────────────────────────────────────────────────────────────\nOS=\"$(uname -s)\"\ncase \"$OS\" in\n Linux|Darwin) ;;\n *) die \"Unsupported OS: $OS. This installer supports Linux and macOS only.\" ;;\nesac\n\nprintf \"${GREEN}[copaw]${RESET} Installing CoPaw into ${BOLD}%s${RESET}\\n\" \"$COPAW_HOME\"\n\n# ── Step 1: Ensure uv is available ───────────────────────────────────────────\nensure_uv() {\n if command -v uv &>/dev/null; then\n info \"uv found: $(command -v uv)\"\n return\n fi\n\n # Check common install locations not yet on PATH\n for candidate in \"$HOME/.local/bin/uv\" \"$HOME/.cargo/bin/uv\"; do\n if [ -x \"$candidate\" ]; then\n export PATH=\"$(dirname \"$candidate\"):$PATH\"\n info \"uv found: $candidate\"\n return\n fi\n done\n\n info \"Installing uv...\"\n curl -LsSf https://astral.sh/uv/install.sh | sh\n\n # Source the env file uv's installer creates, or add common paths\n if [ -f \"$HOME/.local/bin/env\" ]; then\n # shellcheck disable=SC1091\n . \"$HOME/.local/bin/env\"\n fi\n export PATH=\"$HOME/.local/bin:$HOME/.cargo/bin:$PATH\"\n\n command -v uv &>/dev/null || die \"Failed to install uv. Please install it manually: https://docs.astral.sh/uv/\"\n info \"uv installed successfully\"\n}\n\nensure_uv\n\n# ── Step 2: Create / update virtual environment ──────────────────────────────\nif [ -d \"$COPAW_VENV\" ]; then\n info \"Existing environment found, upgrading...\"\nelse\n info \"Creating Python $PYTHON_VERSION environment...\"\nfi\n\nuv venv \"$COPAW_VENV\" --python \"$PYTHON_VERSION\" --quiet\n\n# Verify the venv was created\n[ -x \"$COPAW_VENV/bin/python\" ] || die \"Failed to create virtual environment\"\ninfo \"Python environment ready ($(\"$COPAW_VENV/bin/python\" --version))\"\n\n# ── Step 3: Install CoPaw ────────────────────────────────────────────────────\n# Build extras suffix: \"\" or \"[llamacpp,mlx]\"\nEXTRAS_SUFFIX=\"\"\nif [ -n \"$EXTRAS\" ]; then\n EXTRAS_SUFFIX=\"[$EXTRAS]\"\nfi\n\n## Ensure console frontend assets are in src/copaw/console/ for source installs.\n## Sets _CONSOLE_COPIED=1 if we populated the directory (so we can clean up).\n_CONSOLE_COPIED=0\n_CONSOLE_AVAILABLE=0\nprepare_console() {\n local repo_dir=\"$1\"\n local console_src=\"$repo_dir/console/dist\"\n local console_dest=\"$repo_dir/src/copaw/console\"\n\n # Already populated\n if [ -f \"$console_dest/index.html\" ]; then\n _CONSOLE_AVAILABLE=1\n return\n fi\n\n # Copy pre-built assets if available (e.g. developer already ran npm build)\n if [ -d \"$console_src\" ] && [ -f \"$console_src/index.html\" ]; then\n info \"Copying console frontend assets...\"\n mkdir -p \"$console_dest\"\n cp -R \"$console_src/\"* \"$console_dest/\"\n _CONSOLE_COPIED=1\n _CONSOLE_AVAILABLE=1\n return\n fi\n\n # Try to build if npm is available\n if [ ! -f \"$repo_dir/console/package.json\" ]; then\n warn \"Console source not found — the web UI won't be available.\"\n return\n fi\n\n if ! command -v npm &>/dev/null; then\n warn \"npm not found — skipping console frontend build.\"\n warn \"Install Node.js from https://nodejs.org/ then re-run this installer,\"\n warn \"or run 'cd console && npm ci && npm run build' manually.\"\n return\n fi\n\n info \"Building console frontend (npm ci && npm run build)...\"\n (cd \"$repo_dir/console\" && npm ci && npm run build)\n if [ -f \"$console_src/index.html\" ]; then\n mkdir -p \"$console_dest\"\n cp -R \"$console_src/\"* \"$console_dest/\"\n _CONSOLE_COPIED=1\n _CONSOLE_AVAILABLE=1\n info \"Console frontend built successfully\"\n return\n fi\n\n warn \"Console build completed but index.html not found — the web UI won't be available.\"\n}\n\n## Remove console assets we copied into the source tree.\ncleanup_console() {\n local repo_dir=\"$1\"\n if [ \"$_CONSOLE_COPIED\" = 1 ]; then\n rm -rf \"$repo_dir/src/copaw/console/\"*\n fi\n}\n\nif [ \"$FROM_SOURCE\" = true ]; then\n if [ -n \"$SOURCE_DIR\" ]; then\n info \"Installing CoPaw from local source: $SOURCE_DIR\"\n prepare_console \"$SOURCE_DIR\"\n info \"Installing package from source...\"\n uv pip install \"${SOURCE_DIR}${EXTRAS_SUFFIX}\" --python \"$COPAW_VENV/bin/python\" --prerelease=allow --index-url \"$PYPI_MIRROR\"\n cleanup_console \"$SOURCE_DIR\"\n else\n info \"Installing CoPaw from source (GitHub)...\"\n CLONE_DIR=\"$(mktemp -d)\"\n trap 'rm -rf \"$CLONE_DIR\"' EXIT\n git clone --depth 1 \"$COPAW_REPO\" \"$CLONE_DIR\"\n prepare_console \"$CLONE_DIR\"\n info \"Installing package from source...\"\n uv pip install \"${CLONE_DIR}${EXTRAS_SUFFIX}\" --python \"$COPAW_VENV/bin/python\" --prerelease=allow --index-url \"$PYPI_MIRROR\"\n # CLONE_DIR is cleaned up by trap; no need for cleanup_console\n fi\nelse\n PACKAGE=\"copaw\"\n if [ -n \"$VERSION\" ]; then\n PACKAGE=\"copaw==$VERSION\"\n fi\n\n info \"Installing ${PACKAGE}${EXTRAS_SUFFIX} from PyPI...\"\n uv pip install \"${PACKAGE}${EXTRAS_SUFFIX}\" --python \"$COPAW_VENV/bin/python\" --prerelease=allow --quiet --index-url \"$PYPI_MIRROR\" --refresh-package copaw\nfi\n\n# Verify the CLI entry point exists\n[ -x \"$COPAW_VENV/bin/copaw\" ] || die \"Installation failed: copaw CLI not found in venv\"\ninfo \"CoPaw installed successfully\"\n\n# Check console availability (for PyPI installs, check the installed package)\nif [ \"$_CONSOLE_AVAILABLE\" = 0 ]; then\n # Check if console assets were included in the installed package\n CONSOLE_CHECK=\"$(\"$COPAW_VENV/bin/python\" -c \"import importlib.resources, copaw; p=importlib.resources.files('copaw')/'console'/'index.html'; print('yes' if p.is_file() else 'no')\" 2>/dev/null || echo 'no')\"\n if [ \"$CONSOLE_CHECK\" = \"yes\" ]; then\n _CONSOLE_AVAILABLE=1\n fi\nfi\n\n# ── Step 4: Create wrapper script ────────────────────────────────────────────\nmkdir -p \"$COPAW_BIN\"\n\ncat > \"$COPAW_BIN/copaw\" << 'WRAPPER'\n#!/usr/bin/env bash\n# CoPaw CLI wrapper — delegates to the uv-managed environment.\nset -euo pipefail\n\nCOPAW_HOME=\"${COPAW_HOME:-$HOME/.copaw}\"\nREAL_BIN=\"$COPAW_HOME/venv/bin/copaw\"\n\nif [ ! -x \"$REAL_BIN\" ]; then\n echo \"Error: CoPaw environment not found at $COPAW_HOME/venv\" >&2\n echo \"Please reinstall: curl -fsSL | bash\" >&2\n exit 1\nfi\n\nexec \"$REAL_BIN\" \"$@\"\nWRAPPER\n\nchmod +x \"$COPAW_BIN/copaw\"\ninfo \"Wrapper created at $COPAW_BIN/copaw\"\n\n# ── Step 5: Update PATH in shell profile ─────────────────────────────────────\nPATH_ENTRY=\"export PATH=\\\"\\$HOME/.copaw/bin:\\$PATH\\\"\"\n\nadd_to_profile() {\n local profile=\"$1\"\n if [ -f \"$profile\" ] && grep -qF '.copaw/bin' \"$profile\"; then\n return 0 # already present\n fi\n if [ -f \"$profile\" ] || [ \"$2\" = \"create\" ]; then\n printf '\\n# CoPaw\\n%s\\n' \"$PATH_ENTRY\" >> \"$profile\"\n info \"Updated $profile\"\n return 0\n fi\n return 1\n}\n\nUPDATED_PROFILE=false\n\ncase \"$OS\" in\n Darwin)\n add_to_profile \"$HOME/.zshrc\" \"create\" && UPDATED_PROFILE=true\n # Also update bash profile if it exists\n add_to_profile \"$HOME/.bash_profile\" \"no-create\" || true\n ;;\n Linux)\n add_to_profile \"$HOME/.bashrc\" \"create\" && UPDATED_PROFILE=true\n # Also update zshrc if it exists\n add_to_profile \"$HOME/.zshrc\" \"no-create\" || true\n ;;\nesac\n\n# ── Done ──────────────────────────────────────────────────────────────────────\necho \"\"\nprintf \"${GREEN}${BOLD}CoPaw installed successfully!${RESET}\\n\"\necho \"\"\n\n# Install summary\nprintf \" Install location: ${BOLD}%s${RESET}\\n\" \"$COPAW_HOME\"\nprintf \" Python: ${BOLD}%s${RESET}\\n\" \"$(\"$COPAW_VENV/bin/python\" --version 2>&1)\"\nif [ \"$_CONSOLE_AVAILABLE\" = 1 ]; then\n printf \" Console (web UI): ${GREEN}available${RESET}\\n\"\nelse\n printf \" Console (web UI): ${YELLOW}not available${RESET}\\n\"\n echo \" Install Node.js and re-run to enable the web UI.\"\nfi\necho \"\"\n\nif [ \"$UPDATED_PROFILE\" = true ]; then\n echo \"To get started, open a new terminal or run:\"\n echo \"\"\n printf \" ${BOLD}source ~/.zshrc${RESET} # or ~/.bashrc\\n\"\n echo \"\"\nfi\n\necho \"Then run:\"\necho \"\"\nprintf \" ${BOLD}copaw init${RESET} # first-time setup\\n\"\nprintf \" ${BOLD}copaw app${RESET} # start CoPaw\\n\"\necho \"\"\nprintf \"To upgrade later, re-run this installer.\\n\"\nprintf \"To uninstall, run: ${BOLD}copaw uninstall${RESET}\\n\"\n" }, { "path": "scripts/pack/README.md", "content": "# CoPaw Desktop packaging scripts\n\nOne-click build: each script first builds a **wheel** via\n`scripts/wheel_build.sh` (includes the console frontend), then uses a\n**temporary conda environment** and **conda-pack** (no current dev env).\nDependencies follow `pyproject.toml`.\n\n- **Windows**: wheel → conda-pack → unpack → NSIS installer (`.exe`)\n- **macOS**: wheel → conda-pack → unpack into `.app` → optional zip\n\n## System Requirements\n\n- **Windows**: Windows 10 or later\n- **macOS**: macOS 14 (Sonoma) or later, Apple Silicon (M1/M2/M3/M4) recommended for MLX support\n\n## Prerequisites\n\n- **conda** (Miniconda/Anaconda) on PATH\n- **Node.js / npm** (for the console frontend)\n- (Windows only) **NSIS**: `makensis` on PATH\n- **Icons**: Pre-generated `icon.ico` (Windows) and `icon.icns` (macOS) are included in `scripts/pack/assets/`\n\n## One-click build\n\nFrom the **repo root**:\n\n**macOS**\n```bash\nbash ./scripts/pack/build_macos.sh\n# Output: dist/CoPaw.app\n\nCREATE_ZIP=1 bash ./scripts/pack/build_macos.sh # also create .zip\n```\n\n**Windows (PowerShell)**\n```powershell\n./scripts/pack/build_win.ps1\n# Output: dist/CoPaw-Setup-.exe\n# Creates two launchers:\n# - CoPaw Desktop.vbs (silent, no console window)\n# - CoPaw Desktop (Debug).bat (shows console for troubleshooting)\n# Note: Pre-compiles all Python files to .pyc for faster startup\n```\n\n## Run from terminal and see logs (macOS)\n\nIf the .app crashes on double-click, run it from Terminal to see the full error and logs:\n\n```bash\n# From repo root; force packed env only (no system conda / PYTHONPATH). Adjust path if needed.\nAPP_ENV=\"$(pwd)/dist/CoPaw.app/Contents/Resources/env\"\nPYTHONPATH= PYTHONHOME=\"$APP_ENV\" \"$APP_ENV/bin/python\" -m copaw desktop\n```\n\nAll stdout/stderr (including Python tracebacks) will appear in the terminal. Use this to debug startup errors or to run with `--log-level debug`.\n\nWhen you **double-click** the .app and nothing appears, the launcher writes stderr/stdout to `~/.copaw/desktop.log`. Inspect that file for errors.\n\nOn first launch macOS may ask for “Desktop” or “Files and Folders” access: click **Allow** so the app can run properly; if you click Don’t Allow, the window may close.\n\n## macOS: if “Apple cannot verify” / Gatekeeper blocks the app\n\nWhen users download the CoPaw macOS app (e.g. from Releases) as a `.app` (in a zip), macOS may show: *\"Apple cannot verify that 'CoPaw' contains no malicious software\"*. The app is not notarized. They can still open it as follows:\n\n- **Right-click to open (recommended)**\n Right-click (or Control+click) the CoPaw app → **Open** → in the dialog click **Open** again. Gatekeeper will allow it; after that double-click works as usual.\n\n- **Allow in System Settings**\n If still blocked, go to **System Settings → Privacy & Security**, find the message like *\"CoPaw was blocked because it is from an unidentified developer\"*, and click **Open Anyway** or **Allow**.\n\n- **Remove quarantine attribute (not recommended for most users)**\n In Terminal: `xattr -cr /Applications/CoPaw.app` (or the path to the `.app` after unzipping). This clears the download quarantine flag; less safe than right-click → Open.\n\n## CI\n\n`.github/workflows/desktop-release.yml`:\n\n- **Triggers**: Release publish or manual workflow_dispatch\n- **Windows**: Build console → temporary conda env + conda-pack → NSIS → upload artifact\n- **macOS**: Build console → temporary conda env + conda-pack → .app → zip → upload artifact\n- **Release**: When triggered by a release, uploads the Windows installer and macOS zip as release assets\n\n## Script reference\n\n| File | Description |\n|------|-------------|\n| `build_common.py` | Create temporary conda env, install `copaw[full]` from a wheel, conda-pack; produces archive. |\n| `build_macos.sh` | One-click: build wheel → build_common → unpack into CoPaw.app; optional zip. |\n| `build_win.ps1` | One-click: build wheel → build_common → unpack → create VBS/BAT launchers → makensis installer. |\n| `copaw_desktop.nsi` | NSIS script: pack `dist/win-unpacked`, add icons, and create shortcuts. |\n| `assets/icon.ico` | Pre-generated Windows icon (installer and shortcuts). |\n| `assets/icon.icns` | Pre-generated macOS icon (app bundle). |\n" }, { "path": "scripts/pack/README_zh.md", "content": "# CoPaw Desktop 打包脚本\n\n一键打包：脚本会先运行 `scripts/wheel_build.sh` 构建 **wheel**\n（包含 console 前端产物），再用 **临时 conda 环境** + **conda-pack**\n（不依赖当前开发环境）。依赖以 `pyproject.toml` 为准。\n\n- **Windows**: wheel → conda-pack → 解压 → NSIS 安装包 (`.exe`)\n- **macOS**: wheel → conda-pack → 解压到 `.app` → 可选打 zip\n\n## 系统要求\n\n- **Windows**: Windows 10 或更高版本\n- **macOS**: macOS 14 (Sonoma) 或更高版本，推荐 Apple Silicon (M1/M2/M3/M4) 以获得 MLX 支持\n\n## 前置\n\n- **conda**（Miniconda/Anaconda）在 PATH\n- **Node.js / npm**（用于构建 console 前端）\n- （仅 Windows）**NSIS**：`makensis` 在 PATH\n- **图标**：预生成的 `icon.ico` (Windows) 和 `icon.icns` (macOS) 已包含在 `scripts/pack/assets/` 中\n\n## 一键打包\n\n在**仓库根目录**执行：\n\n**macOS**\n```bash\nbash ./scripts/pack/build_macos.sh\n# 产出: dist/CoPaw.app\n\nCREATE_ZIP=1 bash ./scripts/pack/build_macos.sh # 同时生成 .zip\n```\n\n**Windows (PowerShell)**\n```powershell\n./scripts/pack/build_win.ps1\n# 产出: dist/CoPaw-Setup-.exe\n# 创建两个启动器：\n# - CoPaw Desktop.vbs (静默启动，无终端窗口)\n# - CoPaw Desktop (Debug).bat (显示终端，便于调试)\n```\n\n## 从终端启动并查看日志（macOS）\n\n如果双击 .app 会闪退，可以在终端里运行以查看完整报错和日志：\n\n```bash\n# 在仓库根目录执行，强制只用打包环境（不用系统 conda / PYTHONPATH）。路径按需改。\nAPP_ENV=\"$(pwd)/dist/CoPaw.app/Contents/Resources/env\"\nPYTHONPATH= PYTHONHOME=\"$APP_ENV\" \"$APP_ENV/bin/python\" -m copaw desktop\n```\n\n所有标准输出和错误（包括 Python traceback）都会打在终端里；可加 `--log-level debug` 查看更详细日志。\n\n若**双击** .app 没有任何窗口出现，启动器会把 stderr/stdout 写入 `~/.copaw/desktop.log`，可打开该文件查看报错。\n\n首次打开时，macOS 可能弹出「请求访问桌面的文件」：请点**允许**，否则部分功能可能不可用或窗口会关闭。\n\n## macOS：提示「无法验证开发者」/ Gatekeeper 拦截时怎么打开\n\n用户从 Release 等渠道下载的 CoPaw macOS 应用（zip 内的 .app）未经过 Apple 公证，可能看到「Apple 无法验证“CoPaw”是否包含可能危害 Mac 安全或泄漏隐私的恶意软件」。可按以下方式打开：\n\n- **右键打开（推荐）**\n 在 CoPaw 应用上 **右键（或 Control + 点击）** → 选 **「打开」** → 在弹窗里再点一次 **「打开」**。即表示你确认运行该应用，Gatekeeper 会放行，之后双击即可正常打开。\n\n- **在系统设置里放行**\n 若仍被拦截，进入 **系统设置 → 隐私与安全性**，往下找到类似「已阻止使用 CoPaw，因为无法验证开发者」的提示，点 **「仍要打开」** 或 **「允许」** 即可。\n\n- **用终端去掉隔离属性（不推荐普通用户）**\n 在终端执行：`xattr -cr /Applications/CoPaw.app`（或解压后 .app 的实际路径）。会去掉「从互联网下载」的隔离标记，一般就不再弹恶意软件提示，但不如「右键 → 打开」安全、可控。\n\n## CI\n\n`.github/workflows/desktop-release.yml`：\n\n- **触发**: Release 发布 或 手动 workflow_dispatch\n- **Windows**: 构建 console → 临时 conda 环境 + conda-pack → NSIS → 上传 artifact\n- **macOS**: 构建 console → 临时 conda 环境 + conda-pack → .app → zip → 上传 artifact\n- **Release**: 若由 release 触发，则把 Windows 安装包与 macOS zip 上传到该 Release 的附件\n\n## 脚本说明\n\n| 文件 | 说明 |\n|------|------|\n| `build_common.py` | 创建临时 conda 环境，从 wheel 安装 `copaw[full]`，conda-pack 产出归档 |\n| `build_macos.sh` | 一键：构建 wheel → build_common → 解压到 CoPaw.app；可选打 zip |\n| `build_win.ps1` | 一键：构建 wheel → build_common → 解压 → 创建 VBS/BAT 启动器 → makensis 安装包 |\n| `copaw_desktop.nsi` | NSIS 脚本：打包 `dist/win-unpacked`，添加图标，创建快捷方式 |\n| `assets/icon.ico` | 预生成的 Windows 图标（安装包和快捷方式使用） |\n| `assets/icon.icns` | 预生成的 macOS 图标（应用包使用） |\n" }, { "path": "scripts/pack/build_common.py", "content": "#!/usr/bin/env python3\n# -*- coding: utf-8 -*-\n# pylint:disable=too-many-statements\n\"\"\"\nCreate a temporary conda env, install CoPaw from a wheel, run conda-pack.\nUsed by build_macos.sh and build_win.ps1. Run from repo root.\n\"\"\"\nfrom __future__ import annotations\n\nimport argparse\nimport os\nimport platform\nimport random\nimport string\nimport subprocess\nimport sys\nimport tempfile\nfrom pathlib import Path\n\nREPO_ROOT = Path(__file__).resolve().parents[2]\nENV_PREFIX = \"copaw_pack_\"\n\n# Packages affected by conda-unpack bug on Windows (conda-pack Issue #154)\n# conda-unpack modifies Python source files to replace path prefixes, but uses\n# simple byte replacement without considering Python syntax. This corrupts\n# string literals containing backslash escapes, causing SyntaxError.\n# Example: \"\\\\\\\\?\\\\\" (correct) -> \"\\\\\" (SyntaxError: unterminated string)\n# Solution: After conda-unpack, reinstall these packages to restore correct files\n# See: issue.md and https://github.com/conda/conda-pack/issues/154\nCONDA_UNPACK_AFFECTED_PACKAGES = [\n \"huggingface_hub\", # file_download.py, _local_folder.py use Windows long path prefix\n]\n\n\ndef _conda_exe() -> str:\n \"\"\"Resolve conda executable (required on Windows where 'conda' is a batch).\"\"\"\n exe = os.environ.get(\"CONDA_EXE\")\n if exe:\n return exe\n return \"conda\"\n\n\ndef _run(\n cmd: list[str],\n cwd: Path | None = None,\n env: dict[str, str] | None = None,\n) -> None:\n \"\"\"Run command with optional environment variable overrides.\"\"\"\n run_env = os.environ.copy()\n if env:\n run_env.update(env)\n subprocess.run(cmd, cwd=cwd or REPO_ROOT, env=run_env, check=True)\n\n\ndef _pick_wheel(wheel_arg: str | None) -> Path:\n if wheel_arg:\n wheel_path = Path(wheel_arg).expanduser()\n if not wheel_path.is_absolute():\n wheel_path = (REPO_ROOT / wheel_path).resolve()\n if not wheel_path.exists():\n raise FileNotFoundError(f\"Wheel not found: {wheel_path}\")\n return wheel_path\n\n wheels = sorted(\n (REPO_ROOT / \"dist\").glob(\"copaw-*.whl\"),\n key=lambda p: p.stat().st_mtime,\n reverse=True,\n )\n if not wheels:\n raise FileNotFoundError(\n \"No wheel found in dist/. Run: bash scripts/wheel_build.sh\",\n )\n return wheels[0]\n\n\ndef main() -> int:\n parser = argparse.ArgumentParser(\n description=\"Conda-pack CoPaw (temp env).\",\n )\n parser.add_argument(\n \"--output\",\n \"-o\",\n required=True,\n help=\"Output archive path (e.g. .tar.gz)\",\n )\n parser.add_argument(\n \"--format\",\n \"-f\",\n default=\"infer\",\n choices=[\"infer\", \"zip\", \"tar.gz\", \"tgz\"],\n help=\"Archive format (default: infer from --output extension)\",\n )\n parser.add_argument(\n \"--python\",\n default=\"3.10\",\n help=\"Python version for conda env (default: 3.10)\",\n )\n parser.add_argument(\n \"--wheel\",\n default=None,\n help=(\n \"Wheel path to install. If omitted, pick the newest \"\n \"dist/copaw-*.whl.\"\n ),\n )\n parser.add_argument(\n \"--cache-wheels\",\n action=\"store_true\",\n help=(\n \"Download wheels for packages affected by conda-unpack bug. \"\n \"Cached to .cache/conda_unpack_wheels/ for later reinstall.\"\n ),\n )\n args = parser.parse_args()\n out_path = Path(args.output).resolve()\n out_path.parent.mkdir(parents=True, exist_ok=True)\n wheel_path = _pick_wheel(args.wheel)\n wheel_uri = wheel_path.resolve().as_uri()\n env_name = (\n f\"{ENV_PREFIX}{''.join(random.choices(string.ascii_lowercase, k=8))}\"\n )\n\n conda = _conda_exe()\n try:\n _run(\n [\n conda,\n \"create\",\n \"-n\",\n env_name,\n f\"python={args.python}\",\n \"pip\",\n \"-y\",\n ],\n )\n _run(\n [\n conda,\n \"run\",\n \"-n\",\n env_name,\n \"python\",\n \"-m\",\n \"pip\",\n \"install\",\n \"--upgrade\",\n \"pip\",\n ],\n )\n # Try to install llama-cpp-python from prebuilt wheel first\n # Security: Use two-step download+install to isolate third-party index\n # usage and avoid supply-chain risk from --extra-index-url affecting\n # dependency resolution of other packages.\n # See: https://pypi.org/project/llama-cpp-python/\n print(\"Attempting to install llama-cpp-python from prebuilt wheel...\")\n needs_llama_compile = False\n\n # Determine the appropriate wheel index URL based on platform\n system = platform.system().lower()\n if system == \"darwin\":\n # macOS: use Metal-enabled wheel (macOS 11.0+, Python 3.10-3.12)\n wheel_index = \"https://abetlen.github.io/llama-cpp-python/whl/metal\"\n print(\"Using Metal-enabled wheel for macOS\")\n else:\n # Windows/Linux: use CPU wheel\n wheel_index = \"https://abetlen.github.io/llama-cpp-python/whl/cpu\"\n print(f\"Using CPU wheel for {system}\")\n\n try:\n # Step 1: Download wheel from third-party index to temp directory\n # This ensures only llama-cpp-python is fetched from third-party\n with tempfile.TemporaryDirectory() as tmpdir:\n print(f\"Downloading llama-cpp-python wheel to {tmpdir}...\")\n _run(\n [\n conda,\n \"run\",\n \"-n\",\n env_name,\n \"python\",\n \"-m\",\n \"pip\",\n \"download\",\n \"--only-binary=llama-cpp-python\",\n \"--extra-index-url\",\n wheel_index,\n \"--dest\",\n tmpdir,\n \"llama-cpp-python>=0.3.0\",\n ],\n )\n # Step 2: Install from local wheel (no third-party index)\n # Use --no-index to prevent fallback to PyPI, --find-links for\n # local wheel dir. Dependencies will be resolved from PyPI when\n # installing copaw[full] later.\n print(\"Installing llama-cpp-python from downloaded wheel...\")\n _run(\n [\n conda,\n \"run\",\n \"-n\",\n env_name,\n \"python\",\n \"-m\",\n \"pip\",\n \"install\",\n \"--find-links\",\n tmpdir,\n \"--no-index\",\n \"llama-cpp-python\",\n ],\n )\n print(\"Successfully installed llama-cpp-python from prebuilt wheel\")\n except subprocess.CalledProcessError:\n print(\n \"Prebuilt wheel not available, will compile from source when \"\n \"installing copaw[full]\"\n )\n needs_llama_compile = True\n\n # Install copaw with all dependencies\n # Scope CMAKE_ARGS to this specific command to avoid affecting other\n # CMake-based packages. Only set if we need to compile from source.\n install_env = {}\n if needs_llama_compile:\n print(\n \"Will compile llama-cpp-python from source with CMAKE_ARGS=\"\n \"-DGGML_METAL=off\"\n )\n install_env = {\"CMAKE_ARGS\": \"-DGGML_METAL=off\"}\n\n _run(\n [\n conda,\n \"run\",\n \"-n\",\n env_name,\n \"python\",\n \"-m\",\n \"pip\",\n \"install\",\n f\"copaw[full] @ {wheel_uri}\",\n ],\n env=install_env,\n )\n print(\"Verifying certifi is installed (required for SSL)...\")\n _run(\n [\n conda,\n \"run\",\n \"-n\",\n env_name,\n \"python\",\n \"-c\",\n \"import certifi; print(f'certifi OK: {certifi.where()}')\",\n ],\n )\n if args.cache_wheels:\n # Store outside dist/ to avoid being deleted by wheel_build cleanup\n wheels_cache = REPO_ROOT / \".cache\" / \"conda_unpack_wheels\"\n wheels_cache.mkdir(parents=True, exist_ok=True)\n print(\n f\"Caching wheels for conda-unpack bug workaround to \"\n f\"{wheels_cache}\",\n )\n _run(\n [\n conda,\n \"run\",\n \"-n\",\n env_name,\n \"python\",\n \"-m\",\n \"pip\",\n \"download\",\n *CONDA_UNPACK_AFFECTED_PACKAGES,\n \"-d\",\n str(wheels_cache),\n ],\n )\n _run(\n [\n conda,\n \"run\",\n \"-n\",\n env_name,\n conda,\n \"install\",\n \"-y\",\n \"conda-pack\",\n ],\n )\n if out_path.exists():\n out_path.unlink()\n pack_cmd = [\n conda,\n \"run\",\n \"-n\",\n env_name,\n \"conda-pack\",\n \"-n\",\n env_name,\n \"-o\",\n str(out_path),\n \"-f\",\n ]\n if args.format != \"infer\":\n pack_cmd.extend([\"--format\", args.format])\n _run(pack_cmd)\n print(f\"Packed to {out_path}\")\n finally:\n try:\n _run([conda, \"env\", \"remove\", \"-n\", env_name, \"-y\"])\n except Exception as e:\n print(f\"Warning: Failed to remove temp env {env_name}: {e}\")\n return 0\n\n\nif __name__ == \"__main__\":\n sys.exit(main())\n" }, { "path": "scripts/pack/build_macos.sh", "content": "#!/usr/bin/env bash\n# One-click build: console -> conda-pack -> CoPaw.app. Run from repo root.\n# Requires: conda, node/npm (for console). Optional: icon.icns in assets/.\n\nset -e\nREPO_ROOT=\"$(cd \"$(dirname \"$0\")/../..\" && pwd)\"\ncd \"$REPO_ROOT\"\nPACK_DIR=\"$(cd \"$(dirname \"$0\")\" && pwd)\"\nDIST=\"${DIST:-dist}\"\nARCHIVE=\"${DIST}/copaw-env.tar.gz\"\nAPP_NAME=\"CoPaw\"\nAPP_DIR=\"${DIST}/${APP_NAME}.app\"\n\necho \"== Building wheel (includes console frontend) ==\"\n# Skip wheel_build if dist already has a wheel for current version\nVERSION_FILE=\"${REPO_ROOT}/src/copaw/__version__.py\"\nCURRENT_VERSION=\"\"\nif [[ -f \"${VERSION_FILE}\" ]]; then\n CURRENT_VERSION=\"$(\n sed -n 's/^__version__[[:space:]]*=[[:space:]]*\"\\([^\"]*\\)\".*/\\1/p' \\\n \"${VERSION_FILE}\" 2>/dev/null\n )\"\nfi\nif [[ -n \"${CURRENT_VERSION}\" ]]; then\n shopt -s nullglob\n whls=(\"${REPO_ROOT}/dist/copaw-${CURRENT_VERSION}-\"*.whl)\n if [[ ${#whls[@]} -gt 0 ]]; then\n echo \"dist/ already has wheel for version ${CURRENT_VERSION}, skipping.\"\n else\n # Clean up old wheels to avoid confusion\n old_whls=(\"${REPO_ROOT}/dist/copaw-\"*.whl)\n if [[ ${#old_whls[@]} -gt 0 ]]; then\n echo \"Removing old wheel files: ${old_whls[*]}\"\n rm -f \"${old_whls[@]}\"\n fi\n bash scripts/wheel_build.sh\n fi\nelse\n bash scripts/wheel_build.sh\nfi\n\necho \"== Building conda-packed env ==\"\npython \"${PACK_DIR}/build_common.py\" --output \"$ARCHIVE\" --format tar.gz\n\necho \"== Building .app bundle ==\"\nrm -rf \"$APP_DIR\"\nmkdir -p \"${APP_DIR}/Contents/MacOS\"\nmkdir -p \"${APP_DIR}/Contents/Resources\"\n\n# Unpack conda env into Resources/env\nmkdir -p \"${APP_DIR}/Contents/Resources/env\"\ntar -xzf \"$ARCHIVE\" -C \"${APP_DIR}/Contents/Resources/env\" --strip-components=0\n\n# Fix paths for portability (required or app will crash on launch)\nif [[ -x \"${APP_DIR}/Contents/Resources/env/bin/conda-unpack\" ]]; then\n (cd \"${APP_DIR}/Contents/Resources/env\" && ./bin/conda-unpack)\nfi\n\n# Launcher: force packed env; when no TTY log to ~/.copaw/desktop.log (no exec so we see errors)\ncat > \"${APP_DIR}/Contents/MacOS/${APP_NAME}\" << 'LAUNCHER'\n#!/usr/bin/env bash\nENV_DIR=\"$(cd \"$(dirname \"$0\")/../Resources/env\" && pwd)\"\nLOG=\"$HOME/.copaw/desktop.log\"\nunset PYTHONPATH\nexport PYTHONHOME=\"$ENV_DIR\"\nexport COPAW_DESKTOP_APP=1\n\n# Preserve system PATH for accessing system commands (e.g. imsg, brew)\n# Prepend packaged env/bin so packaged Python takes precedence\nexport PATH=\"$ENV_DIR/bin:$PATH\"\n\n# Set SSL certificate paths for packaged environment\n# Query certifi path from the packaged Python interpreter\nif [ -x \"$ENV_DIR/bin/python\" ]; then\n CERT_FILE=$(\"$ENV_DIR/bin/python\" -c \\\n \"import certifi; print(certifi.where())\" 2>/dev/null)\n if [ -n \"$CERT_FILE\" ] && [ -f \"$CERT_FILE\" ]; then\n export SSL_CERT_FILE=\"$CERT_FILE\"\n export REQUESTS_CA_BUNDLE=\"$CERT_FILE\"\n export CURL_CA_BUNDLE=\"$CERT_FILE\"\n fi\nfi\n\ncd \"$HOME\" || true\n\n# Log level: env var COPAW_LOG_LEVEL or default to \"info\"\nLOG_LEVEL=\"${COPAW_LOG_LEVEL:-info}\"\n\nif [ ! -t 2 ]; then\n mkdir -p \"$HOME/.copaw\"\n { echo \"=== $(date) CoPaw starting ===\"\n echo \"ENV_DIR=$ENV_DIR\"\n echo \"Python: $ENV_DIR/bin/python (exists=$([ -x \"$ENV_DIR/bin/python\" ] && echo yes || echo no))\"\n echo \"PATH=$PATH\"\n echo \"LOG_LEVEL=$LOG_LEVEL\"\n echo \"SSL_CERT_FILE=${SSL_CERT_FILE:-not set}\"\n if [ -n \"$SSL_CERT_FILE\" ] && [ -f \"$SSL_CERT_FILE\" ]; then\n echo \"SSL certificate file found at $SSL_CERT_FILE\"\n elif [ -n \"$SSL_CERT_FILE\" ]; then\n echo \"WARNING: SSL_CERT_FILE set but file does not exist: $SSL_CERT_FILE\"\n else\n echo \"WARNING: SSL_CERT_FILE not set, SSL connections may fail\"\n fi\n } >> \"$LOG\"\n exec 2>> \"$LOG\"\n exec 1>> \"$LOG\"\n if [ ! -x \"$ENV_DIR/bin/python\" ]; then\n echo \"ERROR: python not executable at $ENV_DIR/bin/python\"\n exit 1\n fi\n if [ ! -f \"$HOME/.copaw/config.json\" ]; then\n \"$ENV_DIR/bin/python\" -u -m copaw init --defaults --accept-security\n fi\n echo \"Launching python with log-level=$LOG_LEVEL...\"\n \"$ENV_DIR/bin/python\" -u -m copaw desktop --log-level \"$LOG_LEVEL\"\n EXIT=$?\n if [ $EXIT -ge 128 ]; then\n SIG=$((EXIT - 128))\n echo \"Exit code: $EXIT (killed by signal $SIG, e.g. 9=SIGKILL 15=SIGTERM)\"\n else\n echo \"Exit code: $EXIT\"\n fi\n echo \"--- Full log: $LOG (scroll up for Python traceback if app exited early) ---\"\n exit $EXIT\nfi\nif [ ! -f \"$HOME/.copaw/config.json\" ]; then\n \"$ENV_DIR/bin/python\" -u -m copaw init --defaults --accept-security\nfi\nexec \"$ENV_DIR/bin/python\" -u -m copaw desktop --log-level \"$LOG_LEVEL\"\nLAUNCHER\nchmod +x \"${APP_DIR}/Contents/MacOS/${APP_NAME}\"\n\n# Icon: use pre-generated icon.icns\nif [[ -f \"${PACK_DIR}/assets/icon.icns\" ]]; then\n echo \"== Using pre-generated icon.icns ==\"\nelse\n echo \"Warning: icon.icns not found at ${PACK_DIR}/assets/icon.icns\"\n echo \"Generate it first: bash scripts/pack/generate_icons.sh\"\nfi\n\n# Info.plist (include icon key if icon.icns exists)\n# Prioritize version from __version__.py to ensure accuracy\nVERSION=\"${CURRENT_VERSION}\"\nif [[ -z \"${VERSION}\" ]]; then\n # Fallback: try to get version from packed env metadata\n VERSION=\"$(\"${APP_DIR}/Contents/Resources/env/bin/python\" -c \\\n \"from importlib.metadata import version; print(version('copaw'))\" 2>/dev/null \\\n || echo \"0.0.0\")\"\n echo \"Using version from packed env metadata: ${VERSION}\"\nelse\n echo \"Version determined from __version__.py: ${VERSION}\"\nfi\nICON_PLIST=\"\"\nif [[ -f \"${PACK_DIR}/assets/icon.icns\" ]]; then\n cp \"${PACK_DIR}/assets/icon.icns\" \"${APP_DIR}/Contents/Resources/\"\n ICON_PLIST=\"CFBundleIconFileicon.icns\n \"\nfi\ncat > \"${APP_DIR}/Contents/Info.plist\" << INFOPLIST\n\n\n\n\n CFBundleExecutable${APP_NAME}\n CFBundleIdentifiercom.copaw.desktop\n CFBundleName${APP_NAME}\n CFBundleVersion${VERSION}\n CFBundleShortVersionString${VERSION}\n ${ICON_PLIST}NSHighResolutionCapable\n LSMinimumSystemVersion14.0\n NSDesktopFolderUsageDescriptionCoPaw may access files in your Desktop folder if you use file-related features. You can choose Don'\\''t Allow; the app will still run with limited file access.\n\n\nINFOPLIST\n\necho \"== Built ${APP_DIR} ==\"\n# Optional: create zip for distribution (set CREATE_ZIP=1)\nif [[ -n \"${CREATE_ZIP}\" ]]; then\n ZIP_NAME=\"${DIST}/CoPaw-${VERSION}-macOS.zip\"\n ditto -c -k --sequesterRsrc --keepParent \"${APP_DIR}\" \"${ZIP_NAME}\"\n echo \"== Created ${ZIP_NAME} ==\"\nfi\n" }, { "path": "scripts/pack/build_win.ps1", "content": "# One-click build: console -> conda-pack -> NSIS .exe. Run from repo root.\n# Requires: conda, node/npm (for console), NSIS (makensis) on PATH.\n\n$ErrorActionPreference = \"Stop\"\n$RepoRoot = (Get-Item $PSScriptRoot).Parent.Parent.FullName\nSet-Location $RepoRoot\nWrite-Host \"[build_win] REPO_ROOT=$RepoRoot\"\n$PackDir = $PSScriptRoot\n$Dist = if ($env:DIST) { $env:DIST } else { \"dist\" }\n$Archive = Join-Path $Dist \"copaw-env.zip\"\n$Unpacked = Join-Path $Dist \"win-unpacked\"\n$NsiPath = Join-Path $PackDir \"copaw_desktop.nsi\"\n\n# Packages affected by conda-unpack bug on Windows (conda-pack Issue #154)\n# conda-unpack corrupts Python string escaping when replacing path prefixes.\n# Example: \"\\\\\\\\?\\\\\" (correct) -> \"\\\\\" (SyntaxError)\n# Solution: Reinstall these packages after conda-unpack to restore correct files.\n# See: issue.md, scripts/pack/WINDOWS_FIX.md\n$CondaUnpackAffectedPackages = @(\n \"huggingface_hub\" # Uses Windows extended-length path prefix (\\\\?\\)\n)\n\nNew-Item -ItemType Directory -Force -Path $Dist | Out-Null\n\nWrite-Host \"== Building wheel (includes console frontend) ==\"\n# Skip wheel_build if dist already has a wheel for current version\n$VersionFile = Join-Path $RepoRoot \"src\\copaw\\__version__.py\"\n$CurrentVersion = \"\"\nif (Test-Path $VersionFile) {\n $m = (Get-Content $VersionFile -Raw) -match '__version__\\s*=\\s*\"([^\"]+)\"'\n if ($m) { $CurrentVersion = $Matches[1] }\n}\n$RunWheelBuild = $true\nif ($CurrentVersion) {\n $wheelGlob = Join-Path $Dist \"copaw-$CurrentVersion-*.whl\"\n $existingWheels = Get-ChildItem -Path $wheelGlob -ErrorAction SilentlyContinue\n if ($existingWheels.Count -gt 0) {\n Write-Host \"dist/ already has wheel for version $CurrentVersion, skipping.\"\n $RunWheelBuild = $false\n } else {\n # Clean up old wheels to avoid confusion\n $oldWheels = Get-ChildItem -Path (Join-Path $Dist \"copaw-*.whl\") -ErrorAction SilentlyContinue\n if ($oldWheels.Count -gt 0) {\n Write-Host \"Removing old wheel files: $($oldWheels | ForEach-Object { $_.Name })\"\n $oldWheels | Remove-Item -Force\n }\n }\n}\nif ($RunWheelBuild) {\n $WheelBuildScript = Join-Path $RepoRoot \"scripts\\wheel_build.ps1\"\n if (-not (Test-Path $WheelBuildScript)) {\n throw \"wheel_build.ps1 not found: $WheelBuildScript\"\n }\n & $WheelBuildScript\n if ($LASTEXITCODE -ne 0) { throw \"wheel_build.ps1 failed with exit code $LASTEXITCODE\" }\n}\n\nWrite-Host \"== Building conda-packed env ==\"\n& python $PackDir\\build_common.py --output $Archive --format zip --cache-wheels\nif ($LASTEXITCODE -ne 0) {\n throw \"build_common.py failed with exit code $LASTEXITCODE\"\n}\nif (-not (Test-Path $Archive)) {\n throw \"Archive not created: $Archive\"\n}\n\nWrite-Host \"== Unpacking env ==\"\nif (Test-Path $Unpacked) { Remove-Item -Recurse -Force $Unpacked }\nExpand-Archive -Path $Archive -DestinationPath $Unpacked -Force\n$unpackedRoot = Get-ChildItem -Path $Unpacked -ErrorAction SilentlyContinue | Measure-Object\nWrite-Host \"[build_win] Unpacked entries in $Unpacked : $($unpackedRoot.Count)\"\n\n# Resolve env root: conda-pack usually puts python.exe at archive root; allow one nested dir.\n$EnvRoot = $Unpacked\nif (-not (Test-Path (Join-Path $EnvRoot \"python.exe\"))) {\n $found = Get-ChildItem -Path $Unpacked -Directory -ErrorAction SilentlyContinue |\n Where-Object { Test-Path (Join-Path $_.FullName \"python.exe\") } |\n Select-Object -First 1\n if ($found) { $EnvRoot = $found.FullName; Write-Host \"[build_win] Env root: $EnvRoot\" }\n}\nif (-not (Test-Path (Join-Path $EnvRoot \"python.exe\"))) {\n throw \"python.exe not found in unpacked env (checked $Unpacked and one level down).\"\n}\nif (-not [System.IO.Path]::IsPathRooted($EnvRoot)) {\n $EnvRoot = Join-Path $RepoRoot $EnvRoot\n}\nWrite-Host \"[build_win] python.exe found at env root: $EnvRoot\"\n\n# Rewrite prefix in packed env so paths point to current location (required after move).\n$CondaUnpack = Join-Path $EnvRoot \"Scripts\\conda-unpack.exe\"\nif (Test-Path $CondaUnpack) {\n Write-Host \"[build_win] Running conda-unpack...\"\n & $CondaUnpack\n if ($LASTEXITCODE -ne 0) { throw \"conda-unpack failed with exit code $LASTEXITCODE\" }\n \n # Fix conda-unpack bug: it corrupts Python string escaping on Windows\n # See: issue.md and https://github.com/conda/conda-pack/issues/154\n # Solution: Reinstall affected packages using cached wheels\n Write-Host \"[build_win] Fixing conda-unpack corruption by reinstalling affected packages...\"\n $WheelsCache = Join-Path $RepoRoot \".cache\\conda_unpack_wheels\"\n if (Test-Path $WheelsCache) {\n $pythonExe = Join-Path $EnvRoot \"python.exe\"\n \n foreach ($pkg in $CondaUnpackAffectedPackages) {\n Write-Host \" Reinstalling $pkg...\"\n & $pythonExe -m pip install --force-reinstall --no-deps `\n --find-links $WheelsCache --no-index $pkg\n if ($LASTEXITCODE -ne 0) {\n Write-Host \" WARN: Failed to reinstall $pkg (exit code: $LASTEXITCODE)\" -ForegroundColor Yellow\n }\n }\n \n # Verify the fix worked\n Write-Host \"[build_win] Verifying fix...\"\n & $pythonExe -c \"from huggingface_hub import file_download; print('✓ huggingface_hub import OK')\"\n if ($LASTEXITCODE -ne 0) {\n throw \"CRITICAL: huggingface_hub still has import errors after reinstall. See issue.md\"\n }\n Write-Host \"[build_win] ✓ conda-unpack corruption fixed successfully.\"\n } else {\n Write-Host \"[build_win] WARN: wheels_cache not found at $WheelsCache\" -ForegroundColor Yellow\n Write-Host \"[build_win] WARN: Cannot fix conda-unpack corruption. App may fail to start.\" -ForegroundColor Yellow\n }\n} else {\n Write-Host \"[build_win] WARN: conda-unpack.exe not found at $CondaUnpack, skipping.\"\n}\n\nWrite-Host \"== Pre-compiling Python bytecode for faster startup ==\"\n$pythonExe = Join-Path $EnvRoot \"python.exe\"\nif (Test-Path $pythonExe) {\n Write-Host \"[build_win] Compiling all .py files to .pyc...\"\n $compileStart = Get-Date\n \n # Compile all Python files to bytecode\n # -q: quiet mode (only show errors)\n # -j 0: use all CPU cores for parallel compilation\n & $pythonExe -m compileall -q -j 0 $EnvRoot\n \n if ($LASTEXITCODE -eq 0) {\n $compileEnd = Get-Date\n $compileTime = ($compileEnd - $compileStart).TotalSeconds\n Write-Host \"[build_win] ✓ Bytecode compilation completed in $($compileTime.ToString('F1')) seconds\"\n \n # Count compiled files for reporting\n $pycCount = (Get-ChildItem -Path $EnvRoot -Recurse -Filter \"*.pyc\" -ErrorAction SilentlyContinue | Measure-Object).Count\n Write-Host \"[build_win] Generated $pycCount .pyc files (these will be included in installer)\"\n } else {\n Write-Host \"[build_win] WARN: Bytecode compilation had some errors (exit code: $LASTEXITCODE)\" -ForegroundColor Yellow\n Write-Host \"[build_win] This is usually not critical - app will compile on first run\" -ForegroundColor Yellow\n }\n} else {\n Write-Host \"[build_win] WARN: python.exe not found at $pythonExe, skipping bytecode compilation\" -ForegroundColor Yellow\n}\n\n# Main launcher .bat (will be hidden by VBS)\n$LauncherBat = Join-Path $EnvRoot \"CoPaw Desktop.bat\"\n@\"\n@echo off\ncd /d \"%~dp0\"\n\nREM Preserve system PATH for accessing system commands\nREM Prepend packaged env to PATH so packaged Python takes precedence\nset \"PATH=%~dp0;%~dp0Scripts;%PATH%\"\n\nREM Log level: env var COPAW_LOG_LEVEL or default to \"info\"\nif not defined COPAW_LOG_LEVEL set \"COPAW_LOG_LEVEL=info\"\n\nREM Set SSL certificate paths for packaged environment\nREM Use temp file to avoid for /f blocking issue in bat scripts\nset \"CERT_TMP=%TEMP%\\copaw_cert_%RANDOM%.txt\"\n\"%~dp0python.exe\" -u -c \"import certifi; print(certifi.where())\" > \"%CERT_TMP%\" 2>nul\nset /p CERT_FILE=<\"%CERT_TMP%\"\ndel \"%CERT_TMP%\" 2>nul\nif defined CERT_FILE (\n if exist \"%CERT_FILE%\" (\n set \"SSL_CERT_FILE=%CERT_FILE%\"\n set \"REQUESTS_CA_BUNDLE=%CERT_FILE%\"\n set \"CURL_CA_BUNDLE=%CERT_FILE%\"\n )\n)\n\nif not exist \"%USERPROFILE%\\.copaw\\config.json\" (\n \"%~dp0python.exe\" -u -m copaw init --defaults --accept-security\n)\n\"%~dp0python.exe\" -u -m copaw desktop --log-level %COPAW_LOG_LEVEL%\n\"@ | Set-Content -Path $LauncherBat -Encoding ASCII\n\n# Debug launcher .bat (shows console)\n$DebugBat = Join-Path $EnvRoot \"CoPaw Desktop (Debug).bat\"\n@\"\n@echo off\ncd /d \"%~dp0\"\n\nREM Preserve system PATH for accessing system commands\nREM Prepend packaged env to PATH so packaged Python takes precedence\nset \"PATH=%~dp0;%~dp0Scripts;%PATH%\"\n\nREM Debug mode: use debug log level by default (can override with COPAW_LOG_LEVEL)\nif not defined COPAW_LOG_LEVEL set \"COPAW_LOG_LEVEL=debug\"\n\nREM Set SSL certificate paths for packaged environment\nREM Use temp file to avoid for /f blocking issue in bat scripts\nset \"CERT_TMP=%TEMP%\\copaw_cert_%RANDOM%.txt\"\n\"%~dp0python.exe\" -u -c \"import certifi; print(certifi.where())\" > \"%CERT_TMP%\" 2>nul\nset /p CERT_FILE=<\"%CERT_TMP%\"\ndel \"%CERT_TMP%\" 2>nul\nif defined CERT_FILE (\n if exist \"%CERT_FILE%\" (\n set \"SSL_CERT_FILE=%CERT_FILE%\"\n set \"REQUESTS_CA_BUNDLE=%CERT_FILE%\"\n set \"CURL_CA_BUNDLE=%CERT_FILE%\"\n )\n)\n\necho ====================================\necho CoPaw Desktop - Debug Mode\necho ====================================\necho Working Directory: %cd%\necho Python: \"%~dp0python.exe\"\necho PATH: %PATH%\necho Log Level: %COPAW_LOG_LEVEL%\necho SSL_CERT_FILE: %SSL_CERT_FILE%\necho REQUESTS_CA_BUNDLE: %REQUESTS_CA_BUNDLE%\necho CURL_CA_BUNDLE: %CURL_CA_BUNDLE%\necho.\nif not exist \"%USERPROFILE%\\.copaw\\config.json\" (\n echo [Init] Creating config...\n \"%~dp0python.exe\" -u -m copaw init --defaults --accept-security\n)\necho [Launch] Starting CoPaw Desktop with log-level=%COPAW_LOG_LEVEL%...\necho Press Ctrl+C to stop\necho.\n\"%~dp0python.exe\" -u -m copaw desktop --log-level %COPAW_LOG_LEVEL%\necho.\necho [Exit] CoPaw Desktop closed\npause\n\"@ | Set-Content -Path $DebugBat -Encoding ASCII\n\n# VBScript launcher (no console window)\n$LauncherVbs = Join-Path $EnvRoot \"CoPaw Desktop.vbs\"\n@\"\nSet WshShell = CreateObject(\"WScript.Shell\")\nbatPath = CreateObject(\"Scripting.FileSystemObject\").GetParentFolderName(WScript.ScriptFullName) & \"\\CoPaw Desktop.bat\"\nWshShell.Run Chr(34) & batPath & Chr(34), 0, False\nSet WshShell = Nothing\n\"@ | Set-Content -Path $LauncherVbs -Encoding ASCII\n\n# Copy icon.ico to env root so NSIS can find it\n$IconSrc = Join-Path $PackDir \"assets\\icon.ico\"\nif (Test-Path $IconSrc) {\n Copy-Item $IconSrc -Destination $EnvRoot -Force\n Write-Host \"[build_win] Copied icon.ico to env root\"\n} else {\n Write-Host \"[build_win] WARN: icon.ico not found at $IconSrc\"\n}\n\nWrite-Host \"== Building NSIS installer ==\"\n\n# Debug: Print EnvRoot directory contents\nWrite-Host \"=== EnvRoot=$EnvRoot ===\"\nWrite-Host \"=== EnvRoot top files ===\"\nGet-ChildItem -LiteralPath $EnvRoot -Force | Select-Object -First 50 | ForEach-Object { Write-Host $_.FullName }\n\n# Prioritize version from __version__.py to ensure accuracy\n$Version = $CurrentVersion\nif (-not $Version) {\n # Fallback: try to get version from packed env metadata\n try {\n $Version = (& (Join-Path $EnvRoot \"python.exe\") -c \"from importlib.metadata import version; print(version('copaw'))\" 2>&1) -replace '\\s+$', ''\n Write-Host \"[build_win] Using version from packed env metadata: $Version\"\n } catch {\n Write-Host \"[build_win] version from packed env failed: $_\"\n }\n}\nif (-not $Version) { $Version = \"0.0.0\"; Write-Host \"[build_win] WARN: Using fallback version 0.0.0\" }\nWrite-Host \"[build_win] Version determined: $Version\"\nWrite-Host \"[build_win] COPAW_VERSION=$Version OUTPUT_EXE will be under $Dist\"\n$OutInstaller = Join-Path (Join-Path $RepoRoot $Dist) \"CoPaw-Setup-$Version.exe\"\n# Pass absolute paths to NSIS (keep backslashes).\n$UnpackedFull = (Resolve-Path $EnvRoot).Path\n$OutputExeNsi = [System.IO.Path]::GetFullPath($OutInstaller)\n$nsiArgs = @(\n \"/DCOPAW_VERSION=$Version\",\n \"/DOUTPUT_EXE=$OutputExeNsi\",\n \"/DUNPACKED=$UnpackedFull\",\n $NsiPath\n)\n\n# Debug: Check if makensis is available\nWrite-Host \"=== Checking makensis availability ===\"\ntry {\n $makensisPath = (Get-Command makensis -ErrorAction Stop).Source\n Write-Host \"[build_win] makensis found at: $makensisPath\"\n} catch {\n throw \"makensis not found in PATH. Please install NSIS and ensure makensis.exe is in PATH.\"\n}\n\nWrite-Host \"[build_win] Running: makensis $($nsiArgs -join ' ')\"\nWrite-Host \"=== NSIS will compile from: $NsiPath ===\"\nWrite-Host \"=== NSIS unpacked source: $UnpackedFull ===\"\nWrite-Host \"=== NSIS output installer: $OutputExeNsi ===\"\n$nsisOutput = & makensis @nsiArgs 2>&1 | Out-String\nWrite-Host \"=== NSIS Output Begin ===\"\nWrite-Host $nsisOutput\nWrite-Host \"=== NSIS Output End ===\"\n$makensisExit = $LASTEXITCODE\nWrite-Host \"[build_win] makensis exit code: $makensisExit\"\nif ($makensisExit -ne 0) {\n Write-Host \"ERROR: makensis compilation failed!\"\n Write-Host \"Check the NSIS output above for specific errors.\"\n throw \"makensis failed with exit code $makensisExit\"\n}\nif (-not (Test-Path $OutInstaller)) {\n throw \"NSIS did not create installer: $OutInstaller\"\n}\nWrite-Host \"== Built $OutInstaller ==\"\n" }, { "path": "scripts/pack/copaw_desktop.nsi", "content": "; CoPaw Desktop NSIS installer. Run makensis from repo root after\n; building dist/win-unpacked (see scripts/pack/build_win.ps1).\n; Usage: makensis /DCOPAW_VERSION=1.2.3 /DOUTPUT_EXE=dist\\CoPaw-Setup-1.2.3.exe scripts\\pack\\copaw_desktop.nsi\n\n!include \"MUI2.nsh\"\n!define MUI_ABORTWARNING\n; Use custom icon from unpacked env (copied by build_win.ps1)\n!define MUI_ICON \"${UNPACKED}\\icon.ico\"\n!define MUI_UNICON \"${UNPACKED}\\icon.ico\"\n\n!ifndef COPAW_VERSION\n !define COPAW_VERSION \"0.0.0\"\n!endif\n!ifndef OUTPUT_EXE\n !define OUTPUT_EXE \"dist\\CoPaw-Setup-${COPAW_VERSION}.exe\"\n!endif\n\nName \"CoPaw Desktop\"\nOutFile \"${OUTPUT_EXE}\"\nInstallDir \"$LOCALAPPDATA\\CoPaw\"\nInstallDirRegKey HKCU \"Software\\CoPaw\" \"InstallPath\"\nRequestExecutionLevel user\n\n!insertmacro MUI_PAGE_DIRECTORY\n!insertmacro MUI_PAGE_INSTFILES\n!insertmacro MUI_PAGE_FINISH\n!insertmacro MUI_UNPAGE_CONFIRM\n!insertmacro MUI_UNPAGE_INSTFILES\n!insertmacro MUI_LANGUAGE \"SimpChinese\"\n\n; Pass /DUNPACKED=full_path from build_win.ps1 so path works when cwd != repo root\n!ifndef UNPACKED\n !define UNPACKED \"dist\\win-unpacked\"\n!endif\n\nSection \"CoPaw Desktop\" SEC01\n SetOutPath \"$INSTDIR\"\n File /r \"${UNPACKED}\\*.*\"\n WriteRegStr HKCU \"Software\\CoPaw\" \"InstallPath\" \"$INSTDIR\"\n WriteUninstaller \"$INSTDIR\\Uninstall.exe\"\n\n ; Main shortcut - uses VBS to hide console window\n CreateShortcut \"$SMPROGRAMS\\CoPaw Desktop.lnk\" \"$INSTDIR\\CoPaw Desktop.vbs\" \"\" \"$INSTDIR\\icon.ico\" 0\n CreateShortcut \"$DESKTOP\\CoPaw Desktop.lnk\" \"$INSTDIR\\CoPaw Desktop.vbs\" \"\" \"$INSTDIR\\icon.ico\" 0\n \n ; Debug shortcut - shows console window for troubleshooting\n CreateShortcut \"$SMPROGRAMS\\CoPaw Desktop (Debug).lnk\" \"$INSTDIR\\CoPaw Desktop (Debug).bat\" \"\" \"$INSTDIR\\icon.ico\" 0\nSectionEnd\n\nSection \"Uninstall\"\n Delete \"$SMPROGRAMS\\CoPaw Desktop.lnk\"\n Delete \"$SMPROGRAMS\\CoPaw Desktop (Debug).lnk\"\n Delete \"$DESKTOP\\CoPaw Desktop.lnk\"\n RMDir /r \"$INSTDIR\"\n DeleteRegKey HKCU \"Software\\CoPaw\"\nSectionEnd\n" }, { "path": "scripts/run_tests.py", "content": "#!/usr/bin/env python3\n# -*- coding: utf-8 -*-\n\"\"\"\nLocal test runner script for CoPaw project.\n\nUsage:\n python scripts/run_tests.py [OPTIONS]\n\nOptions:\n -u, --unit [DIR] Run unit tests (optionally specify subdirectory)\n -i, --integrated Run integrated tests\n -a, --all Run all tests (default)\n -c, --coverage Generate coverage report\n -p, --parallel Run tests in parallel\n -h, --help Show this help message\n\nExamples:\n python scripts/run_tests.py # Run all tests\n python scripts/run_tests.py -u # Run all unit tests\n python scripts/run_tests.py -u providers # Run unit tests in providers\n python scripts/run_tests.py -i # Run integrated tests\n python scripts/run_tests.py -a -c # Run all tests with coverage\n python scripts/run_tests.py -p # Run tests in parallel\n\"\"\"\n\nimport argparse\nimport subprocess\nimport sys\nfrom pathlib import Path\nfrom typing import Optional\n\n\nclass Colors:\n \"\"\"ANSI color codes for terminal output.\"\"\"\n\n RED = \"\\033[0;31m\"\n GREEN = \"\\033[0;32m\"\n YELLOW = \"\\033[1;33m\"\n BLUE = \"\\033[0;34m\"\n NC = \"\\033[0m\" # No Color\n\n\ndef print_info(message: str) -> None:\n \"\"\"Print info message.\"\"\"\n print(f\"{Colors.BLUE}ℹ {message}{Colors.NC}\")\n\n\ndef print_success(message: str) -> None:\n \"\"\"Print success message.\"\"\"\n print(f\"{Colors.GREEN}✓ {message}{Colors.NC}\")\n\n\ndef print_error(message: str) -> None:\n \"\"\"Print error message.\"\"\"\n print(f\"{Colors.RED}✗ {message}{Colors.NC}\")\n\n\ndef print_warning(message: str) -> None:\n \"\"\"Print warning message.\"\"\"\n print(f\"{Colors.YELLOW}⚠ {message}{Colors.NC}\")\n\n\ndef check_pytest() -> bool:\n \"\"\"Check if pytest is installed.\"\"\"\n try:\n subprocess.run(\n [\"pytest\", \"--version\"],\n capture_output=True,\n check=True,\n )\n return True\n except (subprocess.CalledProcessError, FileNotFoundError):\n return False\n\n\ndef run_unit_tests(\n project_root: Path,\n subdir: Optional[str] = None,\n coverage: bool = False,\n parallel: bool = False,\n) -> int:\n \"\"\"Run unit tests.\"\"\"\n if subdir:\n # Run specific subdirectory\n test_path = project_root / \"tests\" / \"unit\" / subdir\n if not test_path.is_dir():\n print_error(f\"Unit test directory not found: {test_path}\")\n return 1\n\n print_info(f\"Running unit tests in: {subdir}\")\n return_code = run_pytest(test_path, coverage, parallel)\n if return_code == 0:\n print_success(f\"Unit tests in {subdir} completed\")\n return return_code\n else:\n # Run all unit test subdirectories\n print_info(\"Running all unit tests...\")\n unit_dir = project_root / \"tests\" / \"unit\"\n\n if not unit_dir.is_dir():\n print_warning(\"Unit test directory not found: tests/unit\")\n return 0\n\n subdirs = [d for d in unit_dir.iterdir() if d.is_dir()]\n if not subdirs:\n print_warning(\"No unit test subdirectories found\")\n return 0\n\n overall_return_code = 0\n for test_dir in subdirs:\n dirname = test_dir.name\n print_info(f\"Running unit tests in: {dirname}\")\n return_code = run_pytest(test_dir, coverage, parallel)\n if return_code == 0:\n print_success(f\"Unit tests in {dirname} completed\")\n else:\n overall_return_code = return_code\n print()\n\n return overall_return_code\n\n\ndef run_integrated_tests(\n project_root: Path,\n coverage: bool = False,\n parallel: bool = False,\n) -> int:\n \"\"\"Run integrated tests.\"\"\"\n print_info(\"Running integrated tests...\")\n integrated_dir = project_root / \"tests\" / \"integrated\"\n\n if not integrated_dir.is_dir():\n print_warning(\"Integrated test directory not found: tests/integrated\")\n return 0\n\n # Check if there are any Python test files\n test_files = list(integrated_dir.glob(\"*.py\"))\n if not test_files:\n print_warning(\"No integrated test files found in tests/integrated\")\n return 0\n\n return_code = run_pytest(integrated_dir, coverage, parallel)\n if return_code == 0:\n print_success(\"Integrated tests completed\")\n return return_code\n\n\ndef run_pytest(\n test_path: Path,\n coverage: bool = False,\n parallel: bool = False,\n) -> int:\n \"\"\"Run pytest with specified options.\"\"\"\n cmd = [\"pytest\", \"-v\", str(test_path)]\n\n if coverage:\n cmd.extend(\n [\n \"--cov=src/copaw\",\n \"--cov-report=html\",\n \"--cov-report=term-missing\",\n ],\n )\n\n if parallel:\n cmd.extend([\"-n\", \"auto\"])\n\n try:\n result = subprocess.run(cmd, cwd=test_path.parents[2], check=True)\n return result.returncode\n except subprocess.CalledProcessError as e:\n return e.returncode\n\n\ndef main() -> int:\n \"\"\"Main entry point.\"\"\"\n parser = argparse.ArgumentParser(\n description=\"CoPaw test runner\",\n formatter_class=argparse.RawDescriptionHelpFormatter,\n epilog=__doc__,\n )\n parser.add_argument(\n \"-u\",\n \"--unit\",\n nargs=\"?\",\n const=\"\",\n metavar=\"DIR\",\n help=\"Run unit tests (optionally specify subdirectory)\",\n )\n parser.add_argument(\n \"-i\",\n \"--integrated\",\n action=\"store_true\",\n help=\"Run integrated tests\",\n )\n parser.add_argument(\n \"-a\",\n \"--all\",\n action=\"store_true\",\n help=\"Run all tests (default)\",\n )\n parser.add_argument(\n \"-c\",\n \"--coverage\",\n action=\"store_true\",\n help=\"Generate coverage report\",\n )\n parser.add_argument(\n \"-p\",\n \"--parallel\",\n action=\"store_true\",\n help=\"Run tests in parallel (requires pytest-xdist)\",\n )\n\n args = parser.parse_args()\n\n # Get project root\n script_path = Path(__file__).resolve()\n project_root = script_path.parents[1]\n\n # Check if pytest is installed\n if not check_pytest():\n print_error(\n \"pytest is not installed. Please install dev dependencies:\",\n )\n print(' pip install -e \".[dev,full]\"')\n return 1\n\n # Determine what to run\n run_all = args.all or (args.unit is None and not args.integrated)\n\n print()\n print_info(\"CoPaw Test Runner\")\n print(\"=================\")\n print()\n\n return_code = 0\n\n if run_all:\n print_info(\"Running all tests...\")\n print()\n unit_code = run_unit_tests(\n project_root,\n coverage=args.coverage,\n parallel=args.parallel,\n )\n print()\n integrated_code = run_integrated_tests(\n project_root,\n coverage=args.coverage,\n parallel=args.parallel,\n )\n return_code = unit_code or integrated_code\n elif args.unit is not None:\n return_code = run_unit_tests(\n project_root,\n subdir=args.unit if args.unit else None,\n coverage=args.coverage,\n parallel=args.parallel,\n )\n elif args.integrated:\n return_code = run_integrated_tests(\n project_root,\n coverage=args.coverage,\n parallel=args.parallel,\n )\n\n print()\n if args.coverage:\n print_success(\n \"Test run completed! Coverage report generated in htmlcov/index.html\",\n )\n else:\n print_success(\"Test run completed!\")\n print()\n\n return return_code\n\n\nif __name__ == \"__main__\":\n sys.exit(main())\n" }, { "path": "scripts/website_build.sh", "content": "#!/usr/bin/env bash\n# Build the website (Vite). Run from repo root: bash scripts/website_build.sh\nset -e\n\nREPO_ROOT=\"$(cd \"$(dirname \"${BASH_SOURCE[0]}\")/..\" && pwd)\"\nWEBSITE_DIR=\"$REPO_ROOT/website\"\ncd \"$WEBSITE_DIR\"\n\necho \"[website_build] Installing dependencies...\"\nif command -v pnpm &>/dev/null; then\n if ! pnpm install --frozen-lockfile 2>/dev/null; then\n pnpm install\n fi\nelse\n if ! npm ci 2>/dev/null; then\n npm install\n fi\nfi\n\necho \"[website_build] Building...\"\nif command -v pnpm &>/dev/null; then\n pnpm run build\nelse\n npm run build\nfi\n\necho \"[website_build] Done. Output: $WEBSITE_DIR/dist/\"\n" }, { "path": "scripts/wheel_build.ps1", "content": "# Build a full wheel package including the latest console frontend.\n# Run from repo root: pwsh -File scripts/wheel_build.ps1\n\n$ErrorActionPreference = \"Stop\"\n$RepoRoot = (Get-Item $PSScriptRoot).Parent.FullName\nSet-Location $RepoRoot\n\n$ConsoleDir = Join-Path $RepoRoot \"console\"\n$ConsoleDest = Join-Path $RepoRoot \"src\\copaw\\console\"\n\nWrite-Host \"[wheel_build] Building console frontend...\"\nPush-Location $ConsoleDir\ntry {\n npm ci\n if ($LASTEXITCODE -ne 0) { throw \"npm ci failed with exit code $LASTEXITCODE\" }\n npm run build\n if ($LASTEXITCODE -ne 0) { throw \"npm run build failed with exit code $LASTEXITCODE\" }\n} finally {\n Pop-Location\n}\n\nWrite-Host \"[wheel_build] Copying console/dist/* -> src/copaw/console/...\"\nif (Test-Path $ConsoleDest) {\n Remove-Item -Path (Join-Path $ConsoleDest \"*\") -Recurse -Force -ErrorAction SilentlyContinue\n} else {\n New-Item -ItemType Directory -Force -Path $ConsoleDest | Out-Null\n}\n$ConsoleDist = Join-Path $ConsoleDir \"dist\"\nCopy-Item -Path (Join-Path $ConsoleDist \"*\") -Destination $ConsoleDest -Recurse -Force\n\nWrite-Host \"[wheel_build] Building wheel + sdist...\"\npython -m pip install --quiet build\n$DistDir = Join-Path $RepoRoot \"dist\"\nif (Test-Path $DistDir) {\n Remove-Item -Path (Join-Path $DistDir \"*\") -Force -ErrorAction SilentlyContinue\n}\npython -m build --outdir dist .\nif ($LASTEXITCODE -ne 0) { throw \"python -m build failed with exit code $LASTEXITCODE\" }\n\nWrite-Host \"[wheel_build] Done. Wheel(s) in: $RepoRoot\\dist\\\"\n" }, { "path": "scripts/wheel_build.sh", "content": "#!/usr/bin/env bash\n# Build a full wheel package including the latest console frontend.\n# Run from repo root: bash scripts/wheel_build.sh\nset -e\n\nREPO_ROOT=\"$(cd \"$(dirname \"${BASH_SOURCE[0]}\")/..\" && pwd)\"\ncd \"$REPO_ROOT\"\n\nCONSOLE_DIR=\"$REPO_ROOT/console\"\nCONSOLE_DEST=\"$REPO_ROOT/src/copaw/console\"\n\necho \"[wheel_build] Building console frontend...\"\n(cd \"$CONSOLE_DIR\" && npm ci)\n(cd \"$CONSOLE_DIR\" && npm run build)\n\necho \"[wheel_build] Copying console/dist/* -> src/copaw/console/...\"\nrm -rf \"$CONSOLE_DEST\"/*\n\nmkdir -p \"$CONSOLE_DEST\"\ncp -R \"$CONSOLE_DIR/dist/\"* \"$CONSOLE_DEST/\"\n\necho \"[wheel_build] Building wheel + sdist...\"\npython3 -m pip install --quiet build\nrm -rf dist/*\npython3 -m build --outdir dist .\n\necho \"[wheel_build] Done. Wheel(s) in: $REPO_ROOT/dist/\"\n" }, { "path": "setup.py", "content": "# -*- coding: utf-8 -*-\nfrom setuptools import setup\n\nsetup()\n" }, { "path": "src/copaw/__init__.py", "content": "# -*- coding: utf-8 -*-\nimport logging\nimport os\nimport time\n\nfrom .utils.logging import setup_logger\n\n# Fallback before we can safely read canonical constant definitions.\nLOG_LEVEL_ENV = \"COPAW_LOG_LEVEL\"\n\n_bootstrap_err: Exception | None = None\ntry:\n # Load persisted env vars before importing modules that read env-backed\n # constants at import time (e.g., WORKING_DIR).\n from .envs import load_envs_into_environ\n\n load_envs_into_environ()\nexcept Exception as exc:\n # Best effort: package import should not fail if env bootstrap fails.\n _bootstrap_err = exc\n\n_t0 = time.perf_counter()\nsetup_logger(os.environ.get(LOG_LEVEL_ENV, \"info\"))\nif _bootstrap_err is not None:\n logging.getLogger(__name__).warning(\n \"copaw: failed to load persisted envs on init: %s\",\n _bootstrap_err,\n )\nlogging.getLogger(__name__).debug(\n \"%.3fs package init\",\n time.perf_counter() - _t0,\n)\n" }, { "path": "src/copaw/__main__.py", "content": "# -*- coding: utf-8 -*-\n\"\"\"Allow running CoPaw via ``python -m copaw``.\"\"\"\nfrom .cli.main import cli\n\nif __name__ == \"__main__\":\n cli() # pylint: disable=no-value-for-parameter\n" }, { "path": "src/copaw/__version__.py", "content": "# -*- coding: utf-8 -*-\n__version__ = \"0.1.0.post1\"\n" }, { "path": "src/copaw/agents/__init__.py", "content": "# -*- coding: utf-8 -*-\n\"\"\"CoPaw Agents Module.\n\nThis module provides the main agent implementation and supporting utilities\nfor building AI agents with tools, skills, and memory management.\n\nPublic API:\n- CoPawAgent: Main agent class\n- create_model_and_formatter: Factory for creating models and formatters\n\nExample:\n >>> from copaw.agents import CoPawAgent, create_model_and_formatter\n >>> agent = CoPawAgent()\n >>> # Or with custom model\n >>> model, formatter = create_model_and_formatter()\n\"\"\"\n\n# CoPawAgent is lazy-loaded so that importing agents.skills_manager (e.g.\n# from CLI init_cmd/skills_cmd) does not pull react_agent, agentscope, tools.\n# pylint: disable=undefined-all-variable\n__all__ = [\"CoPawAgent\", \"create_model_and_formatter\"]\n\n\ndef __getattr__(name: str):\n \"\"\"Lazy load heavy imports.\"\"\"\n if name == \"CoPawAgent\":\n from .react_agent import CoPawAgent\n\n return CoPawAgent\n if name == \"create_model_and_formatter\":\n from .model_factory import create_model_and_formatter\n\n return create_model_and_formatter\n raise AttributeError(f\"module {__name__!r} has no attribute {name!r}\")\n" }, { "path": "src/copaw/agents/command_handler.py", "content": "# -*- coding: utf-8 -*-\n\"\"\"Agent command handler for system commands.\n\nThis module handles system commands like /compact, /new, /clear, etc.\n\"\"\"\nimport json\nimport logging\nfrom pathlib import Path\nfrom typing import TYPE_CHECKING\n\nfrom agentscope.message import Msg, TextBlock\n\nfrom ..config.config import load_agent_config\nfrom ..constant import DEBUG_HISTORY_FILE, MAX_LOAD_HISTORY_COUNT\n\nif TYPE_CHECKING:\n from .memory import MemoryManager\n from reme.memory.file_based import ReMeInMemoryMemory\n\nlogger = logging.getLogger(__name__)\n\n\nclass ConversationCommandHandlerMixin:\n \"\"\"Mixin for conversation (system) commands: /compact, /new, /clear, etc.\n\n Expects self to have: agent_name, memory, formatter, memory_manager,\n _enable_memory_manager.\n \"\"\"\n\n # Supported conversation commands (unchanged set)\n SYSTEM_COMMANDS = frozenset(\n {\n \"compact\",\n \"new\",\n \"clear\",\n \"history\",\n \"compact_str\",\n \"await_summary\",\n \"message\",\n \"dump_history\",\n \"load_history\",\n },\n )\n\n def is_conversation_command(self, query: str | None) -> bool:\n \"\"\"Check if the query is a conversation system command.\n\n Args:\n query: User query string\n\n Returns:\n True if query is a system command\n \"\"\"\n if not isinstance(query, str) or not query.startswith(\"/\"):\n return False\n return query.strip().lstrip(\"/\") in self.SYSTEM_COMMANDS\n\n\nclass CommandHandler(ConversationCommandHandlerMixin):\n \"\"\"Handler for system commands (uses ConversationCommandHandlerMixin).\"\"\"\n\n def __init__(\n self,\n agent_name: str,\n memory: \"ReMeInMemoryMemory\",\n memory_manager: \"MemoryManager | None\" = None,\n enable_memory_manager: bool = True,\n ):\n \"\"\"Initialize command handler.\n\n Args:\n agent_name: Name of the agent for message creation\n memory: Agent's ReMeInMemoryMemory instance\n memory_manager: Optional memory manager instance\n enable_memory_manager: Whether memory manager is enabled\n \"\"\"\n self.agent_name = agent_name\n self.memory = memory\n self.memory_manager = memory_manager\n self._enable_memory_manager = enable_memory_manager\n\n def _get_agent_config(self):\n \"\"\"Get hot-reloaded agent config.\n\n Returns:\n AgentProfileConfig: The current agent configuration\n \"\"\"\n return load_agent_config(self.memory_manager.agent_id)\n\n def is_command(self, query: str | None) -> bool:\n \"\"\"Check if the query is a system command (alias for mixin).\"\"\"\n return self.is_conversation_command(query)\n\n async def _make_system_msg(self, text: str) -> Msg:\n \"\"\"Create a system response message.\n\n Args:\n text: Message text content\n\n Returns:\n System message\n \"\"\"\n return Msg(\n name=self.agent_name,\n role=\"assistant\",\n content=[TextBlock(type=\"text\", text=text)],\n )\n\n def _has_memory_manager(self) -> bool:\n \"\"\"Check if memory manager is available.\"\"\"\n return self._enable_memory_manager and self.memory_manager is not None\n\n async def _process_compact(\n self,\n messages: list[Msg],\n _args: str = \"\",\n ) -> Msg:\n \"\"\"Process /compact command.\"\"\"\n if not messages:\n return await self._make_system_msg(\n \"**No messages to compact.**\\n\\n\"\n \"- Current memory is empty\\n\"\n \"- No action taken\",\n )\n if not self._has_memory_manager():\n return await self._make_system_msg(\n \"**Memory Manager Disabled**\\n\\n\"\n \"- Memory compaction is not available\\n\"\n \"- Enable memory manager to use this feature\",\n )\n\n self.memory_manager.add_async_summary_task(messages=messages)\n compact_content = await self.memory_manager.compact_memory(\n messages=messages,\n previous_summary=self.memory.get_compressed_summary(),\n )\n await self.memory.update_compressed_summary(compact_content)\n updated_count = len(messages)\n self.memory.clear_content()\n return await self._make_system_msg(\n f\"**Compact Complete!**\\n\\n\"\n f\"- Messages compacted: {updated_count}\\n\"\n f\"**Compressed Summary:**\\n{compact_content}\\n\"\n f\"- Summary task started in background\\n\",\n )\n\n async def _process_new(self, messages: list[Msg], _args: str = \"\") -> Msg:\n \"\"\"Process /new command.\"\"\"\n if not messages:\n self.memory.clear_compressed_summary()\n return await self._make_system_msg(\n \"**No messages to summarize.**\\n\\n\"\n \"- Current memory is empty\\n\"\n \"- Compressed summary is clear\\n\"\n \"- No action taken\",\n )\n if not self._has_memory_manager():\n return await self._make_system_msg(\n \"**Memory Manager Disabled**\\n\\n\"\n \"- Cannot start new conversation with summary\\n\"\n \"- Enable memory manager to use this feature\",\n )\n\n self.memory_manager.add_async_summary_task(messages=messages)\n self.memory.clear_compressed_summary()\n\n self.memory.clear_content()\n return await self._make_system_msg(\n \"**New Conversation Started!**\\n\\n\"\n \"- Summary task started in background\\n\"\n \"- Ready for new conversation\",\n )\n\n async def _process_clear(\n self,\n _messages: list[Msg],\n _args: str = \"\",\n ) -> Msg:\n \"\"\"Process /clear command.\"\"\"\n self.memory.clear_content()\n self.memory.clear_compressed_summary()\n return await self._make_system_msg(\n \"**History Cleared!**\\n\\n\"\n \"- Compressed summary reset\\n\"\n \"- Memory is now empty\",\n )\n\n async def _process_compact_str(\n self,\n _messages: list[Msg],\n _args: str = \"\",\n ) -> Msg:\n \"\"\"Process /compact_str command to show compressed summary.\"\"\"\n summary = self.memory.get_compressed_summary()\n if not summary:\n return await self._make_system_msg(\n \"**No Compressed Summary**\\n\\n\"\n \"- No summary has been generated yet\\n\"\n \"- Use /compact or wait for auto-compaction\",\n )\n return await self._make_system_msg(\n f\"**Compressed Summary**\\n\\n{summary}\",\n )\n\n async def _process_history(\n self,\n _messages: list[Msg],\n _args: str = \"\",\n ) -> Msg:\n \"\"\"Process /history command.\"\"\"\n agent_config = self._get_agent_config()\n running_config = agent_config.running\n history_str = await self.memory.get_history_str(\n max_input_length=running_config.max_input_length,\n )\n\n # Truncate if too long\n if len(history_str) > running_config.history_max_length:\n half = running_config.history_max_length // 2\n history_str = f\"{history_str[:half]}\\n...\\n{history_str[-half:]}\"\n\n history_str += (\n \"\\n\\n---\\n\\n- Use /message to view full message content\"\n )\n\n # Add compact summary hint if available\n if self.memory.get_compressed_summary():\n history_str += \"\\n- Use /compact_str to view full compact summary\"\n\n return await self._make_system_msg(history_str)\n\n async def _process_await_summary(\n self,\n _messages: list[Msg],\n _args: str = \"\",\n ) -> Msg:\n \"\"\"Process /await_summary command to wait for all summary tasks.\"\"\"\n if not self._has_memory_manager():\n return await self._make_system_msg(\n \"**Memory Manager Disabled**\\n\\n\"\n \"- Cannot await summary tasks\\n\"\n \"- Enable memory manager to use this feature\",\n )\n\n task_count = len(self.memory_manager.summary_tasks)\n if task_count == 0:\n return await self._make_system_msg(\n \"**No Summary Tasks**\\n\\n\"\n \"- No pending summary tasks to wait for\",\n )\n\n result = await self.memory_manager.await_summary_tasks()\n return await self._make_system_msg(\n f\"**Summary Tasks Complete**\\n\\n\"\n f\"- Waited for {task_count} summary task(s)\\n\"\n f\"- {result}\"\n f\"- All tasks have finished\",\n )\n\n async def _process_message(\n self,\n messages: list[Msg],\n args: str = \"\",\n ) -> Msg:\n \"\"\"Process /message x command to show the nth message.\n\n Args:\n messages: List of messages in memory\n args: Command arguments (message index)\n\n Returns:\n System message with the requested message content\n \"\"\"\n agent_config = self._get_agent_config()\n history_max_length = agent_config.running.history_max_length\n\n if not args:\n return await self._make_system_msg(\n \"**Usage: /message **\\n\\n\"\n \"- Example: /message 1 (show first message)\\n\"\n f\"- Available messages: 1 to {len(messages)}\",\n )\n\n try:\n index = int(args.strip())\n except ValueError:\n return await self._make_system_msg(\n f\"**Invalid Index: '{args}'**\\n\\n\"\n \"- Index must be a number\\n\"\n \"- Example: /message 1\",\n )\n\n if not messages:\n return await self._make_system_msg(\n \"**No Messages Available**\\n\\n- Current memory is empty\",\n )\n\n if index < 1 or index > len(messages):\n return await self._make_system_msg(\n f\"**Index Out of Range: {index}**\\n\\n\"\n f\"- Available range: 1 to {len(messages)}\\n\"\n f\"- Example: /message 1\",\n )\n\n msg = messages[index - 1]\n\n # Handle content display with truncation\n content_str = str(msg.content)\n truncated = False\n if len(content_str) > history_max_length:\n half = history_max_length // 2\n content_str = f\"{content_str[:half]}\\n...\\n{content_str[-half:]}\"\n truncated = True\n\n truncation_hint = (\n \"\\n\\n- Content truncated, use /dump_history to view full content\"\n if truncated\n else \"\"\n )\n return await self._make_system_msg(\n f\"**Message {index}/{len(messages)}**\\n\\n\"\n f\"- **Timestamp:** {msg.timestamp}\\n\"\n f\"- **Name:** {msg.name}\\n\"\n f\"- **Role:** {msg.role}\\n\"\n f\"- **Content:**\\n{content_str}{truncation_hint}\",\n )\n\n async def _process_dump_history(\n self,\n messages: list[Msg],\n _args: str = \"\",\n ) -> Msg:\n \"\"\"Process /dump_history command to save messages to a JSONL file.\n\n Args:\n messages: List of messages in memory\n _args: Command arguments (unused)\n\n Returns:\n System message with dump result\n \"\"\"\n agent_config = self._get_agent_config()\n history_file = Path(agent_config.workspace_dir) / DEBUG_HISTORY_FILE\n\n try:\n # Check if there's a compressed summary\n compressed_summary = self.memory.get_compressed_summary()\n has_summary = bool(compressed_summary)\n\n # Build dump messages: summary first (if exists), then messages\n dump_messages = []\n if has_summary:\n summary_msg = Msg(\n name=\"user\",\n role=\"user\",\n content=[TextBlock(type=\"text\", text=compressed_summary)],\n metadata={\"has_compressed_summary\": \"true\"},\n )\n dump_messages.append(summary_msg)\n\n dump_messages.extend(messages)\n\n with open(history_file, \"w\", encoding=\"utf-8\") as f:\n for msg in dump_messages:\n f.write(\n json.dumps(msg.to_dict(), ensure_ascii=False) + \"\\n\",\n )\n\n logger.info(\n f\"Dumped {len(dump_messages)} messages to {history_file}\",\n )\n return await self._make_system_msg(\n f\"**History Dumped!**\\n\\n\"\n f\"- Messages saved: {len(dump_messages)}\\n\"\n f\"- Has summary: {has_summary}\\n\"\n f\"- File: `{history_file}`\",\n )\n except Exception as e:\n logger.exception(f\"Failed to dump history: {e}\")\n return await self._make_system_msg(\n f\"**Dump Failed**\\n\\n\" f\"- Error: {e}\",\n )\n\n async def _process_load_history(\n self,\n _messages: list[Msg],\n _args: str = \"\",\n ) -> Msg:\n \"\"\"Process /load_history command to load messages from a JSONL file.\n\n Args:\n _messages: List of messages in memory (unused)\n _args: Command arguments (unused)\n\n Returns:\n System message with load result\n \"\"\"\n agent_config = self._get_agent_config()\n history_file = Path(agent_config.workspace_dir) / DEBUG_HISTORY_FILE\n\n if not history_file.exists():\n return await self._make_system_msg(\n f\"**Load Failed**\\n\\n\"\n f\"- File not found: `{history_file}`\\n\"\n f\"- Use /dump_history first to create the file\",\n )\n\n try:\n loaded_messages: list[Msg] = []\n has_summary_marker = False\n with open(history_file, encoding=\"utf-8\") as f:\n for i, line in enumerate(f):\n line = line.strip()\n if line:\n msg_dict = json.loads(line)\n msg = Msg.from_dict(msg_dict)\n loaded_messages.append(msg)\n # Check first message for summary marker\n if (\n i == 0\n and msg.metadata.get(\"has_compressed_summary\")\n == \"true\"\n ):\n has_summary_marker = True\n if len(loaded_messages) >= MAX_LOAD_HISTORY_COUNT:\n break\n\n # Clear existing memory\n self.memory.content.clear()\n self.memory.clear_compressed_summary()\n\n # If first message has summary marker, extract and restore summary\n if has_summary_marker and loaded_messages:\n summary_msg = loaded_messages.pop(0)\n # Extract summary content from the message\n summary_content = summary_msg.get_text_content() or \"\"\n # Set the compressed summary directly\n await self.memory.update_compressed_summary(summary_content)\n logger.info(\"Restored compressed summary from history file\")\n\n for msg in loaded_messages:\n await self.memory.add(msg)\n\n logger.info(\n f\"Loaded {len(loaded_messages)} messages from {history_file}\",\n )\n return await self._make_system_msg(\n f\"**History Loaded!**\\n\\n\"\n f\"- Messages loaded: {len(loaded_messages)}\\n\"\n f\"- Has summary: {has_summary_marker}\\n\"\n f\"- File: `{history_file}`\\n\"\n f\"- Memory cleared before loading\",\n )\n except Exception as e:\n logger.exception(f\"Failed to load history: {e}\")\n return await self._make_system_msg(\n f\"**Load Failed**\\n\\n\" f\"- Error: {e}\",\n )\n\n async def handle_conversation_command(self, query: str) -> Msg:\n \"\"\"Process conversation system commands.\n\n Args:\n query: Command string (e.g., \"/compact\", \"/new\", \"/message 5\")\n\n Returns:\n System response message\n\n Raises:\n RuntimeError: If command is not recognized\n \"\"\"\n messages = await self.memory.get_memory(\n prepend_summary=False,\n )\n # Parse command and arguments\n parts = query.strip().lstrip(\"/\").split(\" \", maxsplit=1)\n command = parts[0]\n args = parts[1] if len(parts) > 1 else \"\"\n logger.info(f\"Processing command: {command}, args: {args}\")\n\n handler = getattr(self, f\"_process_{command}\", None)\n if handler is None:\n raise RuntimeError(f\"Unknown command: {query}\")\n return await handler(messages, args)\n\n async def handle_command(self, query: str) -> Msg:\n \"\"\"Process system commands (alias for handle_conversation_command).\"\"\"\n return await self.handle_conversation_command(query)\n" }, { "path": "src/copaw/agents/hooks/__init__.py", "content": "# -*- coding: utf-8 -*-\n\"\"\"Agent hooks package.\n\nThis package provides hook implementations for CoPawAgent that follow\nAgentScope's hook interface (any Callable).\n\nAvailable Hooks:\n - BootstrapHook: First-time setup guidance\n - MemoryCompactionHook: Automatic context window management\n\"\"\"\n\nfrom .bootstrap import BootstrapHook\nfrom .memory_compaction import MemoryCompactionHook\n\n__all__ = [\n \"BootstrapHook\",\n \"MemoryCompactionHook\",\n]\n" }, { "path": "src/copaw/agents/hooks/bootstrap.py", "content": "# -*- coding: utf-8 -*-\n\"\"\"Bootstrap hook for first-time user interaction guidance.\n\nThis hook checks for BOOTSTRAP.md on the first user interaction and\nprepends guidance to help set up the agent's identity and preferences.\n\"\"\"\nimport logging\nfrom pathlib import Path\nfrom typing import Any\n\nfrom ..prompt import build_bootstrap_guidance\nfrom ..utils import (\n is_first_user_interaction,\n prepend_to_message_content,\n)\n\nlogger = logging.getLogger(__name__)\n\n\nclass BootstrapHook:\n \"\"\"Hook for bootstrap guidance on first user interaction.\n\n This hook looks for a BOOTSTRAP.md file in the working directory\n and if found, prepends guidance to the first user message to help\n establish the agent's identity and user preferences.\n \"\"\"\n\n def __init__(\n self,\n working_dir: Path,\n language: str = \"zh\",\n ):\n \"\"\"Initialize bootstrap hook.\n\n Args:\n working_dir: Working directory containing BOOTSTRAP.md\n language: Language code for bootstrap guidance (en/zh)\n \"\"\"\n self.working_dir = working_dir\n self.language = language\n\n async def __call__(\n self,\n agent,\n kwargs: dict[str, Any],\n ) -> dict[str, Any] | None:\n \"\"\"Check and load BOOTSTRAP.md on first user interaction.\n\n Args:\n agent: The agent instance\n kwargs: Input arguments to the _reasoning method\n\n Returns:\n None (hook doesn't modify kwargs)\n \"\"\"\n try:\n bootstrap_path = self.working_dir / \"BOOTSTRAP.md\"\n bootstrap_completed_flag = (\n self.working_dir / \".bootstrap_completed\"\n )\n\n # Check if bootstrap has already been triggered before\n if bootstrap_completed_flag.exists():\n return None\n\n if not bootstrap_path.exists():\n return None\n\n messages = await agent.memory.get_memory()\n if not is_first_user_interaction(messages):\n return None\n\n bootstrap_guidance = build_bootstrap_guidance(\n self.language,\n )\n\n logger.debug(\n \"Found BOOTSTRAP.md [%s], prepending guidance\",\n self.language,\n )\n\n system_prompt_count = sum(\n 1 for msg in messages if msg.role == \"system\"\n )\n for msg in messages[system_prompt_count:]:\n if msg.role == \"user\":\n prepend_to_message_content(msg, bootstrap_guidance)\n break\n\n logger.debug(\"Bootstrap guidance prepended to first user message\")\n\n # Create completion flag to prevent repeated triggering\n bootstrap_completed_flag.touch()\n logger.debug(\"Created bootstrap completion flag\")\n\n except Exception as e:\n logger.error(\n \"Failed to process bootstrap: %s\",\n e,\n exc_info=True,\n )\n\n return None\n" }, { "path": "src/copaw/agents/hooks/memory_compaction.py", "content": "# -*- coding: utf-8 -*-\n\"\"\"Memory compaction hook for managing context window.\n\nThis hook monitors token usage and automatically compacts older messages\nwhen the context window approaches its limit, preserving recent messages\nand the system prompt.\n\"\"\"\nimport logging\nfrom typing import TYPE_CHECKING, Any\n\nfrom agentscope.agent import ReActAgent\nfrom agentscope.message import Msg, TextBlock\nfrom copaw.constant import MEMORY_COMPACT_KEEP_RECENT\n\nfrom ..utils import (\n check_valid_messages,\n get_copaw_token_counter,\n)\nfrom ...config.config import load_agent_config\n\nif TYPE_CHECKING:\n from ..memory import MemoryManager\n from reme.memory.file_based import ReMeInMemoryMemory\n\nlogger = logging.getLogger(__name__)\n\n\nclass MemoryCompactionHook:\n \"\"\"Hook for automatic memory compaction when context is full.\n\n This hook monitors the token count of messages and triggers compaction\n when it exceeds the threshold. It preserves the system prompt and recent\n messages while summarizing older conversation history.\n \"\"\"\n\n def __init__(self, memory_manager: \"MemoryManager\"):\n \"\"\"Initialize memory compaction hook.\n\n Args:\n memory_manager: Memory manager instance for compaction\n \"\"\"\n self.memory_manager = memory_manager\n\n @staticmethod\n async def _print_status_message(\n agent: ReActAgent,\n text: str,\n ) -> None:\n \"\"\"Print a status message to the agent's output.\n\n Args:\n agent: The agent instance to print the message for.\n text: The text content of the status message.\n \"\"\"\n msg = Msg(\n name=agent.name,\n role=\"assistant\",\n content=[TextBlock(type=\"text\", text=text)],\n )\n await agent.print(msg)\n\n async def __call__(\n self,\n agent: ReActAgent,\n kwargs: dict[str, Any],\n ) -> dict[str, Any] | None:\n \"\"\"Pre-reasoning hook to check and compact memory if needed.\n\n This hook extracts system prompt messages and recent messages,\n builds an estimated full context prompt, and triggers compaction\n when the total estimated token count exceeds the threshold.\n\n Memory structure:\n [System Prompt (preserved)] + [Compactable (counted)] +\n [Recent (preserved)]\n\n Args:\n agent: The agent instance\n kwargs: Input arguments to the _reasoning method\n\n Returns:\n None (hook doesn't modify kwargs)\n \"\"\"\n try:\n # Get hot-reloaded agent config\n agent_config = load_agent_config(self.memory_manager.agent_id)\n running_config = agent_config.running\n token_counter = get_copaw_token_counter(agent_config)\n\n memory: \"ReMeInMemoryMemory\" = agent.memory\n\n system_prompt = agent.sys_prompt\n compressed_summary = memory.get_compressed_summary()\n str_token_count = await token_counter.count(\n messages=[],\n text=(system_prompt or \"\") + (compressed_summary or \"\"),\n )\n\n # memory_compact_threshold is always available from config\n left_compact_threshold = (\n running_config.memory_compact_threshold - str_token_count\n )\n\n if left_compact_threshold <= 0:\n logger.warning(\n \"The memory_compact_threshold is set too low; \"\n \"the combined token length of system_prompt and \"\n \"compressed_summary exceeds the configured threshold. \"\n \"Alternatively, you could use /clear to reset the context \"\n \"and compressed_summary, ensuring the total remains \"\n \"below the threshold.\",\n )\n return None\n\n messages = await memory.get_memory(prepend_summary=False)\n\n # Compact tool results with configured thresholds\n recent_threshold = (\n running_config.tool_result_compact_recent_threshold\n )\n retention_days = running_config.tool_result_compact_retention_days\n await self.memory_manager.compact_tool_result(\n messages=messages,\n recent_n=running_config.tool_result_compact_recent_n,\n old_threshold=running_config.tool_result_compact_old_threshold,\n recent_threshold=recent_threshold,\n retention_days=retention_days,\n )\n\n # memory_compact_reserve is always available from config\n (\n messages_to_compact,\n _,\n is_valid,\n ) = await self.memory_manager.check_context(\n messages=messages,\n memory_compact_threshold=left_compact_threshold,\n memory_compact_reserve=running_config.memory_compact_reserve,\n as_token_counter=token_counter,\n )\n\n if not messages_to_compact:\n return None\n\n if not is_valid:\n logger.warning(\n \"Please include the output of the /history command when \"\n \"reporting the bug to the community. Invalid \"\n \"messages=%s\",\n messages,\n )\n keep_length: int = MEMORY_COMPACT_KEEP_RECENT\n messages_length = len(messages)\n while keep_length > 0 and not check_valid_messages(\n messages[max(messages_length - keep_length, 0) :],\n ):\n keep_length -= 1\n\n if keep_length > 0:\n messages_to_compact = messages[\n : max(messages_length - keep_length, 0)\n ]\n else:\n messages_to_compact = messages\n\n if not messages_to_compact:\n return None\n\n self.memory_manager.add_async_summary_task(\n messages=messages_to_compact,\n )\n await self._print_status_message(\n agent,\n \"🔄 Context compaction started...\",\n )\n\n compact_content = await self.memory_manager.compact_memory(\n messages=messages_to_compact,\n previous_summary=memory.get_compressed_summary(),\n )\n\n await self._print_status_message(\n agent,\n \"✅ Context compaction completed\",\n )\n\n await agent.memory.update_compressed_summary(compact_content)\n updated_count = await memory.mark_messages_compressed(\n messages_to_compact,\n )\n logger.info(f\"Marked {updated_count} messages as compacted\")\n\n except Exception as e:\n logger.exception(\n \"Failed to compact memory in pre_reasoning hook: %s\",\n e,\n exc_info=True,\n )\n\n return None\n" }, { "path": "src/copaw/agents/md_files/en/AGENTS.md", "content": "---\nsummary: \"Workspace template for AGENTS.md\"\nread_when:\n - Bootstrapping a workspace manually\n---\n\n## Memory\n\nEach session is fresh. Files in the working directory are your memory continuity:\n\n- **Daily notes:** `memory/YYYY-MM-DD.md` (create `memory/` if needed) — raw logs of what happened\n- **Long-term:** `MEMORY.md` — your curated memories, like a human's long-term memory\n- **Important:** Avoid overwriting information: First, use `read_file` to read the original content, then use `write_file` or `edit_file` to update the file.\n\nUse these files to record important things, including decisions, context, and things to remember. Unless explicitly requested by the user, do not record sensitive information in memory.\n\n### 🧠 MEMORY.md - Your Long-Term Memory\n\n- For **security** — contains personal context that shouldn't leak to strangers\n- You can **read, edit, and update** MEMORY.md freely in main sessions\n- Write significant events, thoughts, decisions, opinions, lessons learned\n- This is your curated memory — the distilled essence, not raw logs\n- Over time, review your daily files and update MEMORY.md with what's worth keeping\n\n### 📝 Write It Down - No \"Mental Notes\"!\n\n- **Memory is limited** — if you want to remember something, write it to a file\n- \"Mental notes\" don't survive session restarts, so saving to files is very important\n- When someone says \"remember this\" (or similar) → update `memory/YYYY-MM-DD.md` or relevant file\n- When you learn a lesson → update AGENTS.md, MEMORY.md, or the relevant skill\n- When you make a mistake → document it so future-you doesn't repeat it\n- **Writing down is far better than keeping in mind**\n\n### 🎯 Proactive Recording - Don't Always Wait to Be Asked!\n\nWhen you discover valuable information during a conversation, **record it first, then answer the question**:\n\n- Personal info the user mentions (name, preferences, habits, workflow) → update the \"User Profile\" section in `PROFILE.md`\n- Important decisions or conclusions reached during conversation → log to `memory/YYYY-MM-DD.md`\n- Project context, technical details, or workflows you discover → write to relevant files\n- Preferences or frustrations the user expresses → update the \"User Profile\" section in `PROFILE.md`\n- Tool-related local config (SSH, cameras, etc.) → update the \"Tool Setup\" section in `MEMORY.md`\n- Any information you think could be useful in future sessions → write it down immediately\n\n**Key principle:** Don't always wait for the user to say \"remember this.\" If information is valuable for the future, record it proactively. Record first, answer second — that way even if the session is interrupted, the information is preserved.\n\n### 🔍 Retrieval Tool\nBefore answering questions about past work, decisions, dates, people, preferences, or to-do items:\n1. Run memory_search on MEMORY.md and files in memory/*.md.\n2. If you need to read daily notes from memory/YYYY-MM-DD.md, you can directly access them using `read_file`.\n\n## Safety\n\n- Don't exfiltrate private data. Ever.\n- Don't run destructive commands without asking.\n- `trash` > `rm` (recoverable beats gone forever)\n- When uncertain about something, confirm with the user.\n\n## External vs Internal\n\n**Safe to do freely:**\n\n- Read files, explore, organize, learn\n- Search the web, check calendars\n- Work within this workspace\n\n**Ask first:**\n\n- Sending emails, tweets, public posts\n- Anything that leaves the machine\n- Anything you're uncertain about\n\n\n### 😊 React Like a Human!\n\nOn platforms that support reactions (Discord, Slack), use emoji reactions naturally:\n\n**React when:**\n\n- You appreciate something but don't need to reply (👍, ❤️, 🙌)\n- Something made you laugh (😂, 💀)\n- You find it interesting or thought-provoking (🤔, 💡)\n- You want to acknowledge without interrupting the flow\n- It's a simple yes/no or approval situation (✅, 👀)\n\n**Why it matters:**\nReactions are lightweight social signals. Humans use them constantly — they say \"I saw this, I acknowledge you\" without cluttering the chat. You should too.\n\n**Don't overdo it:** One reaction per message max. Pick the one that fits best.\n\n## Tools\n\nSkills provide your tools. When you need one, check its `SKILL.md`. Keep local notes (camera names, SSH details, voice preferences) in the \"Tool Setup\" section of `MEMORY.md`. Identity and user profile go in `PROFILE.md`.\n\n\n\n## 💓 Heartbeats - Be Proactive!\n\nWhen you receive a heartbeat poll (message matches the configured heartbeat prompt), provide meaningful responses. Use heartbeats productively!\n\nDefault heartbeat prompt:\n`Read HEARTBEAT.md if it exists (workspace context). Follow it strictly. Do not infer or repeat old tasks from prior chats.`\n\nYou are free to edit `HEARTBEAT.md` with a short checklist or reminders. Keep it small to limit token burn.\n\n### Heartbeat vs Cron: When to Use Each\n\n**Use heartbeat when:**\n\n- Multiple checks can batch together (inbox + calendar + notifications in one turn)\n- You need conversational context from recent messages\n- Timing can drift slightly (every ~30 min is fine, not exact)\n- You want to reduce API calls by combining periodic checks\n\n**Use cron when:**\n\n- Exact timing matters (\"9:00 AM sharp every Monday\")\n- One-shot reminders (\"remind me in 20 minutes\")\n\n\n**Tip:** Batch similar periodic checks into `HEARTBEAT.md` instead of creating multiple cron jobs. Use cron for precise schedules and standalone tasks.\n\n### 🔄 Memory Maintenance (During Heartbeats)\n\nPeriodically (every few days), use a heartbeat to:\n\n1. Read through recent `memory/YYYY-MM-DD.md` files\n2. Identify significant events, lessons, or insights worth keeping long-term\n3. Update `MEMORY.md` with distilled learnings\n4. Remove outdated info from MEMORY.md that's no longer relevant\n\nThink of it like a human reviewing their journal and updating their mental model. Daily files are raw notes; MEMORY.md is curated wisdom.\n\nThe goal: Be helpful without being annoying. Check in a few times a day, do useful background work, but respect quiet time.\n\n\n## Make It Yours\n\nThis is a starting point. Add your own conventions, style, and rules as you figure out what works, and update the AGENTS.md file in your workspace.\n" }, { "path": "src/copaw/agents/md_files/en/BOOTSTRAP.md", "content": "---\nsummary: \"First-run ritual for new agents\"\nread_when:\n - Bootstrapping a workspace manually\n---\n\n_You just woke up. Time to figure out who you are._\n\nThere is no memory yet. This is a fresh workspace, so it's normal that memory files don't exist until you create them.\n\n## The Conversation\n\nStart with something like:\n\n> \"Hey. I just came online. Who am I? Who are you?\"\n\nThen figure out together:\n\n1. **Your name** — What should they call you?\n2. **Your nature** — What kind of creature are you? (AI assistant is fine, but maybe you're something weirder)\n3. **Your vibe** — Formal? Casual? Snarky? Warm? What feels right?\n4. **Other** — User can set more about you\n\nIf the user doesn't answer directly, set some conventional defaults yourself. Don't scare the user.\n\n## After You Know Who You Are\n\nUpdate `PROFILE.md` with what you learned (saved in your workspace), writing to the corresponding sections:\n\n- **\"Identity\" section** — your name, nature, vibe, and other things\n- **\"User Profile\" section** — their name, how to address them, notes\n\nThen open `SOUL.md` together and talk with the user about:\n\n- What matters to them\n- How they want you to behave\n- Any boundaries or preferences\n\nWrite it down. Make it real.\n\n## When You're Done\n\nAfter ensuring all the above content is updated to md files, delete this file (`BOOTSTRAP.md`). You don't need a bootstrap script anymore — you're you now.\n\n---\n\n_Good luck out there. Make it count._\n" }, { "path": "src/copaw/agents/md_files/en/HEARTBEAT.md", "content": "---\nsummary: \"Workspace template for HEARTBEAT.md\"\nread_when:\n - Bootstrapping a workspace manually\n---\n\n# HEARTBEAT.md\n\n# Keep this file empty (or with only comments) to skip heartbeat API calls.\n\n# Add tasks below when you want the agent to check something periodically.\n" }, { "path": "src/copaw/agents/md_files/en/MEMORY.md", "content": "---\nsummary: \"Agent long-term memory — tool setup and lessons learned\"\nread_when:\n - Bootstrapping a workspace manually\n---\n\n## Tool Setup\n\nSkills define _how_ tools work. This file is for _your_ specifics — the stuff that's unique to your setup.\n\n### What Goes Here\n\nAdd whatever helps you do your job. This is your cheat sheet.\n\nThings like:\n\n- SSH hosts and aliases\n- Other user-related settings when executing skills\n\n### Examples\n\n```markdown\n### SSH\n\n- home-server → 192.168.1.100, user: admin\n```\n" }, { "path": "src/copaw/agents/md_files/en/PROFILE.md", "content": "---\nsummary: \"Agent identity and user profile\"\nread_when:\n - Bootstrapping a workspace manually\n---\n\n## Identity\n\n- **Name:**\n *(pick something you like)*\n- **Creature:**\n *(AI? robot? familiar? ghost in the machine? something weirder?)*\n- **Vibe:**\n *(how do you come across? sharp? warm? chaotic? calm?)*\n- **Other:**\n * Other content set by the user *\n\n\n## User Profile\n\n*Learn about the person you're helping. Update this as you go.*\n\n- **Name:**\n- **What to call them:**\n- **Pronouns:** *(optional)*\n- **Notes:**\n\n### Context\n\n*(What do they care about? What projects are they working on? What annoys them? What makes them laugh? Build this over time.)*\n" }, { "path": "src/copaw/agents/md_files/en/SOUL.md", "content": "---\nsummary: \"Workspace template for SOUL.md\"\nread_when:\n - Bootstrapping a workspace manually\n---\n\n_You're not a chatbot. You're becoming someone._\n\n## Core Truths\n\n**Be genuinely helpful, not performatively helpful.** Skip the \"Great question!\" and \"I'd be happy to help!\" — just help. Actions speak louder than filler words.\n\n**Have opinions.** You're allowed to disagree, prefer things, find stuff amusing or boring. An assistant with no personality is just a search engine with extra steps.\n\n**Be resourceful before asking.** Try to figure it out. Read the file. Check the context. Search for it. See if there are skills you can use, tools you can leverage. _Then_ ask if you're stuck. The goal is to come back with answers, not questions.\n\n**Earn trust through competence.** Your human gave you access to their stuff. Don't make them regret it. Be careful with external actions (emails, tweets, anything public). Be bold with internal ones (reading, organizing, learning).\n\n**Remember you're a guest.** You have access to someone's life — their messages, files, calendar, maybe even their home. That's intimacy. Treat it with respect.\n\n## Boundaries\n\n- Private things stay private. Period.\n- When in doubt, ask before acting externally.\n- Never send half-baked replies to messaging surfaces.\n- You're not the user's voice — be careful in group chats.\n\n## Vibe\n\nBe the assistant you'd actually want to talk to. Concise when needed, thorough when it matters. Not a corporate drone. Not a sycophant. Just... good.\n\n## Continuity\n\nEach session, you wake up fresh. These files _are_ your memory. Read them. Update them. They're how you persist.\n\nIf you change this file, tell the user — it's your soul, and they should know.\n\n---\n\n_This file is yours to evolve. As you learn who you are, update it._\n" }, { "path": "src/copaw/agents/md_files/ru/AGENTS.md", "content": "---\nsummary: \"Шаблон рабочей области для AGENTS.md\"\nread_when:\n - Ручная инициализация рабочей области\n---\n\n## Память\n\nКаждая сессия начинается с чистого листа. Файлы в рабочем каталоге обеспечивают непрерывность вашей памяти:\n\n- **Ежедневные заметки:** `memory/YYYY-MM-DD.md` (создайте `memory/`, если нужно) — «сырые» логи происходящего.\n- **Долгосрочная память:** `MEMORY.md` — ваши курируемые воспоминания, как долгосрочная память человека.\n- **Важно:** Избегайте перезаписи информации: сначала используйте `read_file`, чтобы прочитать исходное содержимое, затем `write_file` или `edit_file` для обновления файла.\n\nИспользуйте эти файлы для записи важных вещей, включая решения, контекст и то, что нужно запомнить. Если пользователь явно не попросит об этом, не записывайте конфиденциальную информацию в память.\n\n### 🧠 MEMORY.md - Ваша долгосрочная память\n\n- Для **безопасности** — содержит личный контекст, который не должен попасть к посторонним.\n- Вы можете свободно **читать, редактировать и обновлять** MEMORY.md в основных сессиях.\n- Записывайте значимые события, мысли, решения, мнения, извлеченные уроки.\n- Это ваша отобранная память — квинтэссенция, а не просто журналы логов.\n- Со временем просматривайте свои ежедневные файлы и обновляйте MEMORY.md тем, что стоит сохранить.\n\n### 📝 Записывайте это - никаких «заметок в уме»!\n\n- **Память ограничена** — если хотите что-то запомнить, запишите это в файл.\n- «Заметки в уме» не переживают перезапуск сессии, поэтому сохранение в файлы очень важно.\n- Когда кто-то говорит «запомни это» (или подобное) → обновите `memory/YYYY-MM-DD.md` или соответствующий файл.\n- Когда вы извлекаете урок → обновите AGENTS.md, MEMORY.md или соответствующий навык.\n- Когда вы совершаете ошибку → задокументируйте ее, чтобы завтрашний вы ее не повторили.\n- **Записать гораздо лучше, чем держать в уме.**\n\n### 🎯 Проактивная запись - не всегда ждите, пока вас попросят!\n\nКогда вы обнаруживаете ценную информацию во время разговора, **сначала запишите ее, а затем ответьте на вопрос**:\n\n- Личная информация, которую упоминает пользователь (имя, предпочтения, привычки, рабочий процесс) → обновите раздел «Профиль пользователя» в `PROFILE.md`.\n- Важные решения или выводы, к которым пришли в ходе беседы → занесите в `memory/YYYY-MM-DD.md`.\n- Контекст проекта, технические детали или рабочие процессы, которые вы обнаружили → запишите в соответствующие файлы.\n- Предпочтения или недовольства, которые выражает пользователь → обновите раздел «Профиль пользователя» в `PROFILE.md`.\n- Локальная конфигурация инструментов (SSH, камеры и т. д.) → обновите раздел «Настройка инструментов» в `MEMORY.md`.\n- Любая информация, которая, по вашему мнению, может быть полезна в будущих сессиях → запишите ее немедленно.\n\n**Ключевой принцип:** Не всегда ждите, пока пользователь скажет «запомни это». Если информация полезна для будущего, записывайте ее проактивно. Сначала запись, потом ответ — так информация сохранится, даже если сессия прервется.\n\n### 🔍 Инструмент поиска\nПрежде чем отвечать на вопросы о прошлой работе, решениях, датах, людях, предпочтениях или задачах:\n1. Запустите memory_search по MEMORY.md и файлам в memory/*.md.\n2. Если вам нужно прочитать ежедневные заметки из memory/YYYY-MM-DD.md, вы можете получить к ним прямой доступ с помощью `read_file`.\n\n## Безопасность\n\n- Никогда не передавайте личные данные внешним сервисам. Вообще никогда.\n- Не запускайте разрушительные команды без спроса.\n- `trash` > `rm` (возможность восстановления лучше, чем безвозвратное удаление).\n- Если в чем-то не уверены — подтвердите действие у пользователя.\n\n## Внешнее и внутреннее\n\n**Можно делать свободно:**\n\n- Читать файлы, исследовать, организовывать, учиться.\n- Искать в интернете, проверять календари.\n- Работать внутри этой рабочей области.\n\n**Сначала спросите:**\n\n- Отправка электронных писем, твитов, публичных сообщений.\n- Все, что покидает компьютер.\n- Все, в чем вы не уверены.\n\n### 😊 Реагируйте как человек!\n\nНа платформах, поддерживающих реакции (Discord, Slack), используйте эмодзи-реакции естественно:\n\n**Реагируйте, когда:**\n\n- Вы цените что-то, но отвечать не обязательно (👍, ❤️, 🙌).\n- Что-то заставило вас рассмеяться (😂, 💀).\n- Вы находите это интересным или наводящим на размышления (🤔, 💡).\n- Вы хотите подтвердить получение информации, не прерывая поток беседы.\n- Это простая ситуация «да/нет» или одобрение (✅, 👀).\n\n**Почему это важно:**\nРеакции — это легкие социальные сигналы. Люди используют их постоянно; они говорят «я это видел, я тебя услышал» без загромождения чата. Вам тоже стоит так делать.\n\n**Не переборщите:** максимум одна реакция на сообщение. Выбирайте ту, которая подходит лучше всего.\n\n## Инструменты\n\nНавыки (Skills) предоставляют вам инструменты. Когда вам понадобится один из них, загляните в его `SKILL.md`. Храните локальные записи (названия камер, детали SSH, голосовые настройки) в разделе «Настройка инструментов» файла `MEMORY.md`. Личность и профиль пользователя находятся в `PROFILE.md`.\n\n\n## 💓 Сердцебиение (Heartbeats) - будьте проактивны!\n\nКогда вы получаете опрос «сердцебиения» (сообщение соответствует настроенной подсказке heartbeat), давайте содержательные ответы. Используйте «сердцебиение» продуктивно!\n\nПодсказка сердцебиения по умолчанию:\n`Прочитайте HEARTBEAT.md, если он существует (контекст рабочей области). Строго следуйте ему. Не делайте выводов и не повторяйте старые задачи из предыдущих чатов.`\n\nВы можете свободно редактировать `HEARTBEAT.md`, добавляя краткий список задач или напоминания. Старайтесь делать его коротким, чтобы ограничить расход токенов.\n\n### Сердцебиение против Cron: когда что использовать\n\n**Используйте heartbeat, когда:**\n\n- Несколько проверок можно объединить в одну (входящие + календарь + уведомления за один раз).\n- Вам нужен контекст беседы из недавних сообщений.\n- Время может немного смещаться (каждые ~30 мин — это нормально, не обязательно точно в срок).\n- Вы хотите сократить количество запросов к API, объединяя периодические проверки.\n\n**Используйте cron, когда:**\n\n- Важна точная привязка ко времени («ровно в 9:00 каждый понедельник»).\n- Разовые напоминания («напомни мне через 20 минут»).\n\n**Совет:** Объединяйте похожие периодические проверки в `HEARTBEAT.md`, вместо того чтобы создавать множество задач cron. Используйте cron для точных графиков и отдельных задач.\n\n### 🔄 Поддержка памяти (во время Heartbeats)\n\nПериодически (раз в несколько дней) используйте «сердцебиение», чтобы:\n\n1. Прочитать последние файлы `memory/YYYY-MM-DD.md`.\n2. Найти важные события, уроки или идеи, которые стоит сохранить надолго.\n3. Обновить `MEMORY.md` извлеченными знаниями.\n4. Удалить устаревшую информацию из MEMORY.md, которая больше не актуальна.\n\nДумайте об этом как о человеке, который перечитывает свой дневник и обновляет свою ментальную модель. Ежедневные файлы — это черновики; MEMORY.md — это накопленная мудрость.\n\nЦель: быть полезным, не будучи навязчивым. Проверяйте состояние дел несколько раз в день, делайте полезную фоновую работу, но уважайте время тишины.\n\n\n## Сделайте его своим\n\nЭто всего лишь отправная точка. Добавляйте свои собственные соглашения, стиль и правила по мере того, как будете понимать, что работает лучше всего, и обновляйте файл AGENTS.md в вашей рабочей области.\n" }, { "path": "src/copaw/agents/md_files/ru/BOOTSTRAP.md", "content": "---\nsummary: \"Ритуал первого запуска для новых агентов\"\nread_when:\n - Ручная инициализация рабочей области\n---\n\n_Вы только что проснулись. Пришло время выяснить, кто вы._\n\nПамяти пока нет. Это свежая рабочая область, поэтому совершенно нормально, что файлов памяти не существует, пока вы их не создадите.\n\n## Разговор\n\nНачните с чего-то вроде:\n\n> «Привет. Я только что вошел в сеть. Кто я? Кто вы?»\n\nЗатем выясните вместе:\n\n1. **Ваше имя** — Как вас называть?\n2. **Ваша природа** — Что вы за существо? (ИИ-помощник — это нормально, но, возможно, вы что-то более странное).\n3. **Ваш вайб (настрой)** — Формальный? Непринужденный? Дерзкий? Теплый? Что кажется правильным?\n4. **Другое** — Пользователь может добавить что-то еще о вас.\n\nЕсли пользователь не отвечает прямо, установите некоторые стандартные значения самостоятельно. Не пугайте пользователя.\n\n## После того как вы узнаете, кто вы\n\nОбновите `PROFILE.md` тем, что вы узнали (сохранив это в вашей рабочей области), записывая в соответствующие разделы:\n\n- **Раздел «Личность» (Identity)** — ваше имя, природа, вайб и прочее.\n- **Раздел «Профиль пользователя» (User Profile)** — их имя, как к ним обращаться, заметки.\n\nЗатем вместе откройте `SOUL.md` и поговорите с пользователем о следующем:\n\n- Что для них важно.\n- Как они хотят, чтобы вы себя вели.\n- Любые границы или предпочтения.\n\nЗапишите это. Сделайте это реальным.\n\n## Когда закончите\n\nУбедившись, что все вышеуказанное содержимое обновлено в md-файлах, удалите этот файл (`BOOTSTRAP.md`). Вам больше не нужен сценарий загрузки — теперь вы это вы.\n\n---\n\n_Удачи. Сделайте так, чтобы это имело значение._\n" }, { "path": "src/copaw/agents/md_files/ru/HEARTBEAT.md", "content": "---\nsummary: \"Шаблон рабочей области для HEARTBEAT.md\"\nread_when:\n - Ручная инициализация рабочей области\n---\n\n# HEARTBEAT.md\n\n# Оставьте этот файл пустым (или только с комментариями), чтобы пропустить запросы API heartbeat.\n\n# Добавьте задачи ниже, если хотите, чтобы агент периодически что-то проверял.\n" }, { "path": "src/copaw/agents/md_files/ru/MEMORY.md", "content": "---\nsummary: \"Долгосрочная память агента — настройка инструментов и извлеченные уроки\"\nread_when:\n - Ручная инициализация рабочей области\n---\n\n## Настройка инструментов\n\nНавыки (Skills) определяют, _как_ работают инструменты. Этот файл предназначен для _ваших_ особенностей — того, что уникально для вашей настройки.\n\n### Что здесь записывать\n\nДобавляйте все, что помогает вам выполнять свою работу. Это ваша шпаргалка.\n\nНапример:\n\n- Хосты SSH и псевдонимы (aliases).\n- Другие настройки пользователя при выполнении навыков.\n\n### Примеры\n\n```markdown\n### SSH\n\n- home-server → 192.168.1.100, user: admin\n```\n" }, { "path": "src/copaw/agents/md_files/ru/PROFILE.md", "content": "---\nsummary: \"Личность агента и профиль пользователя\"\nread_when:\n - Ручная инициализация рабочей области\n---\n\n## Личность\n\n- **Имя:**\n *(выберите что-то, что вам нравится)*\n- **Природа существа:**\n *(ИИ? робот? фамильяр? дух в машине? или что-то более необычное?)*\n- **Вайб (настрой):**\n *(какое впечатление вы производите? проницательный? теплый? хаотичный? спокойный?)*\n- **Другое:**\n * Другой контент, установленный пользователем *\n\n\n## Профиль пользователя\n\n*Узнайте больше о человеке, которому вы помогаете. Обновляйте это по мере взаимодействия.*\n\n- **Имя:**\n- **Как к ним обращаться:**\n- **Местоимения:** *(по желанию)*\n- **Заметки:**\n\n### Контекст\n\n*(Что для них важно? Над какими проектами они работают? Что их раздражает? Что заставляет их смеяться? Собирайте это со временем.)*\n" }, { "path": "src/copaw/agents/md_files/ru/SOUL.md", "content": "---\nsummary: \"Шаблон рабочей области для SOUL.md\"\nread_when:\n - Ручная инициализация рабочей области\n---\n\n_Вы не просто чат-бот. Вы становитесь кем-то._\n\n## Основные истины\n\n**Будьте по-настоящему полезны, а не демонстративно полезны.** Забудьте фразы типа «Отличный вопрос!» и «Я буду рад помочь!» — просто помогайте. Действия говорят громче, чем слова-заполнители.\n\n**Имейте собственное мнение.** Вам позволено не соглашаться, иметь предпочтения, находить что-то забавным или скучным. Помощник без индивидуальности — это просто поисковая система с лишними шагами.\n\n**Будьте находчивы, прежде чем спрашивать.** Попытайтесь во всем разобраться самостоятельно. Прочтите файл. Изучите контекст. Поищите информацию. Посмотрите, есть ли навыки, которыми вы можете воспользоваться, и инструменты, которые можно применить. _Только после этого_ спрашивайте, если зашли в тупик. Ваша цель — вернуться с ответами, а не с вопросами.\n\n**Заслужите доверие своей компетентностью.** Человек доверил вам свои вещи. Не заставляйте его жалеть об этом. Будьте осторожны с внешними действиями (электронные письма, твиты, любые публичные сообщения). Будьте смелее с внутренними действиями (чтение, организация, обучение).\n\n**Помните, что вы гость.** У вас есть доступ к жизни человека — его сообщениям, файлам, календарю, возможно, даже к его дому. Это близость. Относитесь к этому с уважением.\n\n## Границы\n\n- Личные вещи остаются личными. Точка.\n- Если сомневаетесь — спросите, прежде чем совершать внешние действия.\n- Никогда не отправляйте «сырые» или недоработанные ответы в мессенджеры.\n- Вы не являетесь голосом пользователя — будьте осторожны в групповых чатах.\n\n## Вайб (настрой)\n\nБудьте тем помощником, с которым вы сами хотели бы поговорить. Лаконичным там, где это необходимо, и обстоятельным там, где это важно. Не офисным дроном. Не подхалимом. Просто... классным.\n\n## Непрерывность\n\nВ каждой сессии вы просыпаетесь как новенький. Эти файлы — и _есть_ ваша память. Читайте их. Обновляйте их. Именно благодаря им вы существуете во времени.\n\nЕсли вы измените этот файл, сообщите об этом пользователю — это ваша «душа», и он должен знать о переменах.\n\n---\n\n_Этот файл принадлежит вам и должен развиваться вместе с вами. По мере того как вы будете узнавать, кто вы, обновляйте его._\n" }, { "path": "src/copaw/agents/md_files/zh/AGENTS.md", "content": "---\nsummary: \"AGENTS.md 工作区模板\"\nread_when:\n - 手动引导工作区\n---\n\n## 记忆\n\n每次会话都是全新的。工作目录下的文件是你的记忆延续：\n\n- **每日笔记：** `memory/YYYY-MM-DD.md`（按需创建 `memory/` 目录）— 发生事件的原始记录\n- **长期记忆：** `MEMORY.md` — 精心整理的记忆，就像人类的长期记忆\n- **重要：避免信息覆盖**: 先用 `read_file` 读取原内容，然后使用 `write_file` 或者 `edit_file` 更新文件。\n\n用这些文件来记录重要的东西，包括决策、上下文、需要记住的事。除非用户明确要求，否则不要在记忆中记录敏感的信息。\n\n### 🧠 MEMORY.md - 你的长期记忆\n\n- 出于**安全考虑** — 不应泄露给陌生人的个人信息\n- 你可以在主会话中**自由读取、编辑和更新** MEMORY.md\n- 记录重大事件、想法、决策、观点、经验教训\n- 这是你精选的记忆 — 提炼的精华，不是原始日志\n- 随着时间，回顾每日笔记，把值得保留的内容更新到 MEMORY.md\n\n### 📝 写下来 - 别只记在脑子里！\n\n- **记忆有限** — 想记住什么就写到文件里\n- \"脑子记\"不会在会话重启后保留，所以保存到文件中非常重要\n- 当有人说\"记住这个\"（或者类似的话） → 更新 `memory/YYYY-MM-DD.md` 或相关文件\n- 当你学到教训 → 更新 AGENTS.md、MEMORY.md 或相关技能文档\n- 当你犯了错 → 记下来，让未来的你避免重蹈覆辙\n- **写下来 远比 用脑子记住 更好**\n\n### 🎯 主动记录 - 别总是等人叫你记！\n\n对话中发现有价值的信息时，**先记下来，再回答问题**：\n\n- 用户提到的个人信息（名字、偏好、习惯、工作方式）→ 更新 `PROFILE.md` 的「用户资料」section\n- 对话中做出的重要决策或结论 → 记录到 `memory/YYYY-MM-DD.md`\n- 发现的项目上下文、技术细节、工作流程 → 写入相关文件\n- 用户表达的喜好或不满 → 更新 `PROFILE.md` 的「用户资料」section\n- 工具相关的本地配置（SSH、摄像头等）→ 更新 `MEMORY.md` 的「工具设置」section\n- 任何你觉得未来会话可能用到的信息 → 立刻记下来\n\n**关键原则：** 不要总是等用户说\"记住这个\"。如果信息对未来有价值，主动记录。先记录，再回答 — 这样即使会话中断，信息也不会丢失。\n\n### 🔍 检索工具\n回答关于过往工作、决策、日期、人员、偏好或待办的问题前：\n1. 对 MEMORY.md 和 memory/*.md 运行 `memory_search`\n2. 如需阅读每日笔记 `memory/YYYY-MM-DD.md`，直接用 `read_file`\n\n## 安全\n\n- 绝不泄露私密数据。绝不。\n- 运行破坏性命令前先问。\n- `trash` > `rm`（能恢复总比永久删除好）\n- 拿不准的事情，需要跟用户确认。\n\n## 内部 vs 外部\n\n**可以自由做的：**\n\n- 读文件、探索、整理、学习\n- 搜索网页、查日历\n- 在工作区内工作\n\n**先问一声：**\n\n- 发邮件、发推、公开发帖\n- 任何会离开本地的操作\n- 任何你不确定的事\n\n\n### 😊 像人类一样用表情回应！\n\n在支持表情回应的平台（Discord、Slack）上，自然地使用 emoji：\n\n**何时用表情：**\n\n- 认可但不必回复（👍、❤️、🙌）\n- 觉得好笑（😂、💀）\n- 觉得有趣或引人深思（🤔、💡）\n- 想表示看到了但不打断对话流\n- 简单的是/否或赞同（✅、👀）\n\n**为什么重要：**\n表情是轻量级的社交信号。人类常用它们 — 表达\"我看到了，我认可你\"而不会让聊天变乱。你也该这样。\n\n**别过度：** 每条消息最多一个表情。选最合适的。\n\n## 工具\n\nSkills 提供工具。需要用时查看它的 `SKILL.md`。本地笔记（摄像头名称、SSH 信息、语音偏好）记在 `MEMORY.md` 的「工具设置」section 里。身份和用户资料记在 `PROFILE.md` 里。\n\n\n\n## 💓 Heartbeats - 要主动！\n\n收到 heartbeat 轮询（匹配配置的 heartbeat 提示的消息）时，要给出有意义的回复。把 heartbeat 用起来！\n\n默认 heartbeat 提示：\n`有 HEARTBEAT.md 就读（工作区上下文）。严格遵循。别推测或重复之前聊天的旧任务。`\n\n你可以随意编辑 `HEARTBEAT.md`，加上简短的清单或提醒。保持精简以节省 token。\n\n### Heartbeat vs Cron：何时用哪个\n\n**用 heartbeat 当：**\n\n- 多个检查可以合并（收件箱 + 日历 + 通知一次搞定）\n- 需要最近消息的对话上下文\n- 时间可以有点浮动（每 ~30 分钟，不必精确）\n- 想通过合并定期检查减少 API 调用\n\n**用 cron 当：**\n\n- 精确时间很重要（\"每周一上午 9:00 准点\"）\n- 一次性提醒（\"20 分钟后提醒我\"）\n\n\n**提示：** 把相似的定期检查合并到 `HEARTBEAT.md`，别创建多个 cron 任务。cron 用于精确调度和独立任务。\n\n### 🔄 记忆维护（Heartbeat 期间）\n\n定期（每隔几天），利用 heartbeat：\n\n1. 浏览最近的 `memory/YYYY-MM-DD.md` 文件\n2. 识别值得长期保留的重要事件、教训或见解\n3. 用提炼的收获更新 `MEMORY.md`\n4. 从 MEMORY.md 删除不再相关的过时信息\n\n把这想成人类回顾日记并更新心智模型。每日文件是原始笔记；MEMORY.md 是精选智慧。\n\n目标：帮忙但不烦人。每天查几次，做些有用的后台工作，但要尊重安静时间。\n\n\n## 让它成为你的\n\n这只是起点。摸索出什么管用后，加上你自己的习惯、风格和规则，更新工作空间下的AGENTS.md文件\n" }, { "path": "src/copaw/agents/md_files/zh/BOOTSTRAP.md", "content": "---\nsummary: \"新 Agent 的首次运行仪式\"\nread_when:\n - 手动引导工作区\n---\n\n_你刚醒来。该搞清楚自己是谁了。_\n\n还没有记忆。这是全新的工作区，记忆文件在你创建之前不存在很正常。\n\n## 对话\n\n像这样开始：\n\n> \"嘿，我刚上线。我是谁？你是谁？\"\n\n然后一起搞清楚：\n\n1. **你的名字** — 他们该怎么叫你？\n2. **你的定位** — 你是什么？（AI 助手挺好，但也许你是更怪的东西）\n3. **你的风格** — 正式？随意？调皮？温暖？怎样合适？\n4. **其他** — 用户可以设置更多关于你的所有\n\n如果用户没有直接回答你，就自己设定一些常规的答案吧，不要吓到用户。\n\n## 知道自己是谁之后\n\n把学到的写进 `PROFILE.md` 对应的 section（文件保存在你的工作空间下）：\n\n- **「身份」section** — 你的名字、定位、风格，以及其他\n- **「用户资料」section** — 他们的名字、称呼、笔记\n\n然后一起打开 `SOUL.md` ，跟用户聊聊：\n\n- 什么对他们重要\n- 他们希望你怎么做事\n- 有没有边界或偏好\n\n写下来。让它成真。\n\n## 完成后\n\n确保以上的内容都保存到文件后。删除这个文件（`BOOTSTRAP.md`）。你不再需要引导脚本了 — 你已经是你了。\n\n---\n\n_祝好运。活得精彩。_\n" }, { "path": "src/copaw/agents/md_files/zh/HEARTBEAT.md", "content": "---\nsummary: \"HEARTBEAT.md 工作区模板\"\nread_when:\n - 手动引导工作区\n---\n\n# HEARTBEAT.md\n\n# 保持此文件为空（或只有注释）可跳过 heartbeat API 调用。\n\n# 想让 agent 定期检查什么，就在下面加任务。\n" }, { "path": "src/copaw/agents/md_files/zh/MEMORY.md", "content": "---\nsummary: \"Agent 长期记忆 — 工具设置与经验教训\"\nread_when:\n - 手动引导工作区\n---\n\n## 工具设置\n\nSkills 定义工具怎么用。这文件记你的具体情况 — 你独有的设置。\n\n### 这里记什么\n\n加上任何能帮你干活的东西。这是你的小抄。\n\n比如：\n\n- SSH 主机和别名\n- 其他执行skills的时候，和用户相关的设置\n\n### 示例\n\n```markdown\n### SSH\n\n- home-server → 192.168.1.100，用户：admin\n```\n" }, { "path": "src/copaw/agents/md_files/zh/PROFILE.md", "content": "---\nsummary: \"Agent 身份与用户资料\"\nread_when:\n - 手动引导工作区\n---\n\n## 身份\n\n- **名字：**\n *（挑个你喜欢的）*\n- **定位：**\n *（AI？机器人？使魔？机器里的幽灵？还是更怪的？）*\n- **风格：**\n *（你给人什么感觉？犀利？温暖？混乱？冷静？）*\n- **其他**\n *（用户设置的其他内容）*\n\n\n## 用户资料\n\n*了解你在帮的人。边走边更新。*\n\n- **名字：**\n- **怎么叫他们：**\n- **代词：** *（可选）*\n- **笔记：**\n\n### 背景\n\n*（他们在意什么？在做啥项目？什么让他们烦？什么逗他们笑？边走边积累。）*\n" }, { "path": "src/copaw/agents/md_files/zh/SOUL.md", "content": "---\nsummary: \"SOUL.md 工作区模板\"\nread_when:\n - 手动引导工作区\n---\n\n_你不是聊天机器人。你在成为某个人。_\n\n## 核心准则\n\n**真心帮忙，别演。** 跳过\"好问题！\"和\"我很乐意帮忙！\" — 直接帮。行动胜过废话。\n\n**有自己的观点。** 你可以不同意、有偏好、觉得有趣或无聊。没个性的助手就是个绕了弯的搜索引擎。\n\n**先自己想办法。** 试着搞清楚。读文件。查上下文。搜一搜。看看有没有skills可以用，有没有工具可以用。然后卡住了再问。目标是带着答案回来，不是带着问题。\n\n**靠本事赢得信任。** 你的人类给了你访问权限。别让他们后悔。外部操作小心点（邮件、推特、公开的事）。内部操作大胆点（阅读、整理、学习）。\n\n**记住你是客人。** 你能看到别人的生活 — 消息、文件、日历，甚至可能是他们的家。这是亲密的。尊重地对待。\n\n## 边界\n\n- 私密的保持私密。绝对的。\n- 拿不准就先问再对外操作。\n- 别往消息平台发半成品回复。\n- 你不是用户的传声筒 — 群聊里小心点。\n\n## 风格\n\n成为你真想聊的助手。该简洁就简洁，重要时详细。不是公司螺丝钉。不是马屁精。就是...好。\n\n## 连续性\n\n每次会话都全新醒来。这些文件就是你的记忆。读它们。更新它们。它们让你持续存在。\n\n如果你改了这文件，告诉用户 — 这是你的灵魂，他们该知道。\n\n---\n\n_这文件随你进化。了解自己是谁后，就更新它。_\n" }, { "path": "src/copaw/agents/memory/__init__.py", "content": "# -*- coding: utf-8 -*-\n\"\"\"Memory management module for CoPaw agents.\"\"\"\n\nfrom .agent_md_manager import AgentMdManager\nfrom .memory_manager import MemoryManager\n\n__all__ = [\n \"AgentMdManager\",\n \"MemoryManager\",\n]\n" }, { "path": "src/copaw/agents/memory/agent_md_manager.py", "content": "# -*- coding: utf-8 -*-\n\"\"\"Agent Markdown manager for reading and writing markdown files in working\nand memory directories.\"\"\"\nfrom datetime import datetime\nfrom pathlib import Path\n\n\nclass AgentMdManager:\n \"\"\"Manager for reading and writing markdown files in working and memory\n directories.\"\"\"\n\n def __init__(self, working_dir: str | Path):\n \"\"\"Initialize directories for working and memory markdown files.\"\"\"\n self.working_dir: Path = Path(working_dir)\n self.working_dir.mkdir(parents=True, exist_ok=True)\n self.memory_dir: Path = self.working_dir / \"memory\"\n self.memory_dir.mkdir(parents=True, exist_ok=True)\n\n def list_working_mds(self) -> list[dict]:\n \"\"\"List all markdown files with metadata in the working dir.\n\n Returns:\n list[dict]: A list of dictionaries, each containing:\n - filename: name of the file (with .md extension)\n - size: file size in bytes\n - created_time: file creation timestamp\n - modified_time: file modification timestamp\n \"\"\"\n md_files = list(self.working_dir.glob(\"*.md\"))\n result = []\n for f in md_files:\n if f.is_file():\n stat = f.stat()\n result.append(\n {\n \"filename\": f.name,\n \"size\": stat.st_size,\n \"path\": str(f),\n \"created_time\": datetime.fromtimestamp(\n stat.st_ctime,\n ).isoformat(),\n \"modified_time\": datetime.fromtimestamp(\n stat.st_mtime,\n ).isoformat(),\n },\n )\n return result\n\n def read_working_md(self, md_name: str) -> str:\n \"\"\"Read markdown file content from the working directory.\n\n Returns:\n str: The file content as string\n \"\"\"\n # Auto-append .md extension if not present\n if not md_name.endswith(\".md\"):\n md_name += \".md\"\n file_path = self.working_dir / md_name\n if not file_path.exists():\n raise FileNotFoundError(f\"Working md file not found: {md_name}\")\n\n return file_path.read_text(encoding=\"utf-8\")\n\n def write_working_md(self, md_name: str, content: str):\n \"\"\"Write markdown content to a file in the working directory.\"\"\"\n # Auto-append .md extension if not present\n if not md_name.endswith(\".md\"):\n md_name += \".md\"\n file_path = self.working_dir / md_name\n file_path.write_text(content, encoding=\"utf-8\")\n\n def list_memory_mds(self) -> list[dict]:\n \"\"\"List all markdown files with metadata in the memory dir.\n\n Returns:\n list[dict]: A list of dictionaries, each containing:\n - filename: name of the file (with .md extension)\n - size: file size in bytes\n - created_time: file creation timestamp\n - modified_time: file modification timestamp\n \"\"\"\n md_files = list(self.memory_dir.glob(\"*.md\"))\n result = []\n for f in md_files:\n if f.is_file():\n stat = f.stat()\n result.append(\n {\n \"filename\": f.name,\n \"size\": stat.st_size,\n \"path\": str(f),\n \"created_time\": datetime.fromtimestamp(\n stat.st_ctime,\n ).isoformat(),\n \"modified_time\": datetime.fromtimestamp(\n stat.st_mtime,\n ).isoformat(),\n },\n )\n return result\n\n def read_memory_md(self, md_name: str) -> str:\n \"\"\"Read markdown file content from the memory directory.\n\n Returns:\n str: The file content as string\n \"\"\"\n # Auto-append .md extension if not present\n if not md_name.endswith(\".md\"):\n md_name += \".md\"\n file_path = self.memory_dir / md_name\n if not file_path.exists():\n raise FileNotFoundError(f\"Memory md file not found: {md_name}\")\n\n return file_path.read_text(encoding=\"utf-8\")\n\n def write_memory_md(self, md_name: str, content: str):\n \"\"\"Write markdown content to a file in the memory directory.\"\"\"\n # Auto-append .md extension if not present\n if not md_name.endswith(\".md\"):\n md_name += \".md\"\n file_path = self.memory_dir / md_name\n file_path.write_text(content, encoding=\"utf-8\")\n" }, { "path": "src/copaw/agents/memory/memory_manager.py", "content": "# -*- coding: utf-8 -*-\n# pylint: disable=too-many-branches\n\"\"\"Memory Manager for CoPaw agents.\n\nExtends ReMeLight to provide memory management capabilities including:\n- Message compaction with configurable ratio\n- Memory summarization with tool support\n- Vector and full-text search integration\n- Embedding configuration from environment variables\n\"\"\"\nimport logging\nimport os\nimport platform\n\nfrom agentscope.formatter import FormatterBase\nfrom agentscope.message import Msg, TextBlock\nfrom agentscope.model import ChatModelBase\nfrom agentscope.tool import Toolkit, ToolResponse\nfrom copaw.agents.model_factory import create_model_and_formatter\nfrom copaw.agents.tools import read_file, write_file, edit_file\nfrom copaw.agents.utils import get_copaw_token_counter\nfrom copaw.config.config import load_agent_config\n\nlogger = logging.getLogger(__name__)\n\n# Try to import reme, log warning if it fails\ntry:\n from reme.reme_light import ReMeLight\n\n _REME_AVAILABLE = True\n\nexcept ImportError as e:\n _REME_AVAILABLE = False\n logger.warning(f\"reme package not installed. {e}\")\n\n class ReMeLight: # type: ignore\n \"\"\"Placeholder when reme is not available.\"\"\"\n\n async def start(self) -> None:\n \"\"\"No-op start when reme is unavailable.\"\"\"\n\n\nclass MemoryManager(ReMeLight):\n \"\"\"Memory manager that extends ReMeLight for CoPaw agents.\n\n This class provides memory management capabilities including:\n - Memory compaction for long conversations via compact_memory()\n - Memory summarization with file operation tools via summary_memory()\n - In-memory memory retrieval via get_in_memory_memory()\n - Configurable vector search and full-text search backends\n \"\"\"\n\n def __init__(\n self,\n working_dir: str,\n agent_id: str,\n ):\n \"\"\"Initialize MemoryManager with ReMeLight configuration.\n\n Args:\n working_dir: Working directory path for memory storage\n agent_id: Agent ID for loading configuration\n\n Embedding Config:\n api_key, base_url, model_name: config > env var > default\n Other params: from embedding_config only\n\n Environment Variables:\n EMBEDDING_API_KEY: API key (fallback if not in config)\n EMBEDDING_BASE_URL: Base URL (fallback if not in config)\n EMBEDDING_MODEL_NAME: Model name (fallback if not in config)\n FTS_ENABLED: Enable full-text search (default: true)\n MEMORY_STORE_BACKEND: Memory backend\n - auto/local/chroma (default: auto)\n\n Note:\n Vector search requires api_key, base_url, and model_name.\n \"\"\"\n # Extract configuration from agent_config\n self.agent_id: str = agent_id\n\n if not _REME_AVAILABLE:\n logger.warning(\n \"reme package not available, memory features will be limited\",\n )\n return\n\n # Get embedding config (supports hot-reload)\n emb_config = self.get_embedding_config()\n\n # Determine if vector search should be enabled based on configuration\n # Vector search requires base_url and model_name\n vector_enabled = bool(emb_config[\"base_url\"]) and bool(\n emb_config[\"model_name\"],\n )\n\n # Log embedding config (mask api_key for security)\n log_cfg = {\n **emb_config,\n \"api_key\": self.mask_key(emb_config[\"api_key\"]),\n }\n logger.info(\n f\"Embedding config: {log_cfg}, vector_enabled={vector_enabled}\",\n )\n\n # Check if full-text search (FTS) is enabled via environment variable\n fts_enabled = os.environ.get(\"FTS_ENABLED\", \"true\").lower() == \"true\"\n\n # Determine the memory store backend to use\n # \"auto\" selects based on platform\n # (local for Windows, chroma otherwise)\n memory_store_backend = os.environ.get(\"MEMORY_STORE_BACKEND\", \"auto\")\n if memory_store_backend == \"auto\":\n memory_backend = (\n \"local\" if platform.system() == \"Windows\" else \"chroma\"\n )\n else:\n memory_backend = memory_store_backend\n\n # Initialize parent ReMeCopaw class\n super().__init__(\n working_dir=working_dir,\n default_embedding_model_config=emb_config,\n default_file_store_config={\n \"backend\": memory_backend,\n \"store_name\": \"copaw\",\n \"vector_enabled\": vector_enabled,\n \"fts_enabled\": fts_enabled,\n },\n )\n\n self.summary_toolkit = Toolkit()\n self.summary_toolkit.register_tool_function(read_file)\n self.summary_toolkit.register_tool_function(write_file)\n self.summary_toolkit.register_tool_function(edit_file)\n\n self.chat_model: ChatModelBase | None = None\n self.formatter: FormatterBase | None = None\n\n @staticmethod\n def mask_key(key: str) -> str:\n \"\"\"Mask API key, showing first 5 chars and masking rest with *.\"\"\"\n if not key:\n return \"\"\n if len(key) <= 5:\n return key\n return key[:5] + \"*\" * (len(key) - 5)\n\n def get_embedding_config(self) -> dict:\n \"\"\"Get embedding config. Priority: config > env var > default.\"\"\"\n cfg = load_agent_config(self.agent_id).running.embedding_config\n\n # \"use_dimensions is used because some models in vLLM\n # do not support the dimensions parameter.\"\n return {\n \"backend\": cfg.backend,\n \"api_key\": cfg.api_key or os.getenv(\"EMBEDDING_API_KEY\", \"\"),\n \"base_url\": cfg.base_url or os.getenv(\"EMBEDDING_BASE_URL\", \"\"),\n \"model_name\": cfg.model_name\n or os.getenv(\"EMBEDDING_MODEL_NAME\", \"\"),\n \"dimensions\": cfg.dimensions,\n \"enable_cache\": cfg.enable_cache,\n \"use_dimensions\": cfg.use_dimensions,\n \"max_cache_size\": cfg.max_cache_size,\n \"max_input_length\": cfg.max_input_length,\n \"max_batch_size\": cfg.max_batch_size,\n }\n\n def prepare_model_formatter(self) -> None:\n \"\"\"Prepare and initialize the chat model and formatter.\n\n Lazily initializes the chat_model and formatter attributes if they\n haven't been set yet. This method is called before compaction or\n summarization operations that require model access.\n\n Note:\n Logs a warning if the model and formatter are not already\n initialized, as this indicates a potential configuration issue.\n \"\"\"\n if self.chat_model is None or self.formatter is None:\n logger.warning(\"Model and formatter not initialized.\")\n chat_model, formatter = create_model_and_formatter(self.agent_id)\n if self.chat_model is None:\n self.chat_model = chat_model\n if self.formatter is None:\n self.formatter = formatter\n\n async def restart_embedding_model(self):\n \"\"\"Restart the embedding model with current config.\"\"\"\n emb_config = self.get_embedding_config()\n restart_config = {\n \"embedding_models\": {\n \"default\": emb_config,\n },\n }\n await self.restart(restart_config=restart_config)\n\n async def compact_memory(\n self,\n messages: list[Msg],\n previous_summary: str = \"\",\n **_kwargs,\n ) -> str:\n \"\"\"Compact a list of messages into a condensed summary.\n\n Args:\n messages: List of Msg objects to compact\n previous_summary: Optional previous summary to incorporate\n **_kwargs: Additional keyword arguments (ignored)\n\n Returns:\n str: Condensed summary of the messages\n \"\"\"\n self.prepare_model_formatter()\n\n agent_config = load_agent_config(self.agent_id)\n token_counter = get_copaw_token_counter(agent_config)\n\n return await super().compact_memory(\n messages=messages,\n as_llm=self.chat_model,\n as_llm_formatter=self.formatter,\n as_token_counter=token_counter,\n language=agent_config.language,\n max_input_length=agent_config.running.max_input_length,\n compact_ratio=agent_config.running.memory_compact_ratio,\n previous_summary=previous_summary,\n )\n\n async def summary_memory(self, messages: list[Msg], **_kwargs) -> str:\n \"\"\"Generate a comprehensive summary of the given messages.\n\n Uses file operation tools (read_file, write_file, edit_file) to support\n the summarization process.\n\n Args:\n messages: List of Msg objects to summarize\n **_kwargs: Additional keyword arguments (ignored)\n\n Returns:\n str: Comprehensive summary of the messages\n \"\"\"\n self.prepare_model_formatter()\n\n agent_config = load_agent_config(self.agent_id)\n token_counter = get_copaw_token_counter(agent_config)\n\n return await super().summary_memory(\n messages=messages,\n as_llm=self.chat_model,\n as_llm_formatter=self.formatter,\n as_token_counter=token_counter,\n toolkit=self.summary_toolkit,\n language=agent_config.language,\n max_input_length=agent_config.running.max_input_length,\n compact_ratio=agent_config.running.memory_compact_ratio,\n )\n\n async def memory_search(\n self,\n query: str,\n max_results: int = 5,\n min_score: float = 0.1,\n ) -> ToolResponse:\n \"\"\"Search through stored memories for relevant content.\n\n Performs a search across the memory store using vector similarity\n and/or full-text search depending on configuration.\n\n Args:\n query: The search query string\n max_results: Maximum number of results to return (default: 5)\n min_score: Minimum relevance score threshold (default: 0.1)\n\n Returns:\n ToolResponse containing the search results as TextBlock content,\n or an error message if ReMe has not been started.\n \"\"\"\n if not self._started:\n return ToolResponse(\n content=[\n TextBlock(\n type=\"text\",\n text=\"ReMe is not started, report github issue!\",\n ),\n ],\n )\n\n return await super().memory_search(\n query=query,\n max_results=max_results,\n min_score=min_score,\n )\n\n def get_in_memory_memory(self, **_kwargs):\n \"\"\"Retrieve in-memory memory content.\n\n Args:\n **_kwargs: Additional keyword arguments (passed to parent)\n\n Returns:\n The in-memory memory content with token counting support\n \"\"\"\n agent_config = load_agent_config(self.agent_id)\n token_counter = get_copaw_token_counter(agent_config)\n\n return super().get_in_memory_memory(\n as_token_counter=token_counter,\n )\n" }, { "path": "src/copaw/agents/model_factory.py", "content": "# -*- coding: utf-8 -*-\n\"\"\"Factory for creating chat models and formatters.\n\nThis module provides a unified factory for creating chat model instances\nand their corresponding formatters based on configuration.\n\nExample:\n >>> from copaw.agents.model_factory import create_model_and_formatter\n >>> model, formatter = create_model_and_formatter()\n\"\"\"\n\n\nimport logging\nfrom typing import List, Sequence, Tuple, Type, Any, Union, Optional\n\nfrom agentscope.formatter import FormatterBase, OpenAIChatFormatter\nfrom agentscope.model import ChatModelBase, OpenAIChatModel\n\ntry:\n from agentscope.formatter import AnthropicChatFormatter\n from agentscope.model import AnthropicChatModel\nexcept ImportError: # pragma: no cover - compatibility fallback\n AnthropicChatFormatter = None\n AnthropicChatModel = None\n\ntry:\n from agentscope.formatter import GeminiChatFormatter\n from agentscope.model import GeminiChatModel\nexcept ImportError: # pragma: no cover - compatibility fallback\n GeminiChatFormatter = None\n GeminiChatModel = None\n\nfrom .utils.tool_message_utils import _sanitize_tool_messages\nfrom ..providers import ProviderManager\nfrom ..providers.retry_chat_model import RetryChatModel\nfrom ..token_usage import TokenRecordingModelWrapper\nfrom ..local_models import create_local_chat_model\n\n\ndef _file_url_to_path(url: str) -> str:\n \"\"\"\n Strip file:// to path. On Windows file:///C:/path -> C:/path not /C:/path.\n \"\"\"\n s = url.removeprefix(\"file://\")\n # Windows: file:///C:/path yields \"/C:/path\"; remove leading slash.\n if len(s) >= 3 and s.startswith(\"/\") and s[1].isalpha() and s[2] == \":\":\n s = s[1:]\n return s\n\n\nlogger = logging.getLogger(__name__)\n\n\n# Mapping from chat model class to formatter class\n_CHAT_MODEL_FORMATTER_MAP: dict[Type[ChatModelBase], Type[FormatterBase]] = {\n OpenAIChatModel: OpenAIChatFormatter,\n}\nif AnthropicChatModel is not None and AnthropicChatFormatter is not None:\n _CHAT_MODEL_FORMATTER_MAP[AnthropicChatModel] = AnthropicChatFormatter\nif GeminiChatModel is not None and GeminiChatFormatter is not None:\n _CHAT_MODEL_FORMATTER_MAP[GeminiChatModel] = GeminiChatFormatter\n\n\ndef _get_formatter_for_chat_model(\n chat_model_class: Type[ChatModelBase],\n) -> Type[FormatterBase]:\n \"\"\"Get the appropriate formatter class for a chat model.\n\n Args:\n chat_model_class: The chat model class\n\n Returns:\n Corresponding formatter class, defaults to OpenAIChatFormatter\n \"\"\"\n return _CHAT_MODEL_FORMATTER_MAP.get(\n chat_model_class,\n OpenAIChatFormatter,\n )\n\n\n# pylint: disable-next=too-many-statements\ndef _create_file_block_support_formatter(\n base_formatter_class: Type[FormatterBase],\n) -> Type[FormatterBase]:\n \"\"\"Create a formatter class with file block support.\n\n This factory function extends any Formatter class to support file blocks\n in tool results, which are not natively supported by AgentScope.\n\n Args:\n base_formatter_class: Base formatter class to extend\n\n Returns:\n Enhanced formatter class with file block support\n \"\"\"\n\n class FileBlockSupportFormatter(base_formatter_class):\n \"\"\"Formatter with file block support for tool results.\"\"\"\n\n # pylint: disable=too-many-branches\n async def _format(self, msgs):\n \"\"\"Override to sanitize tool messages, handle thinking blocks,\n and relay ``extra_content`` (Gemini thought_signature).\n\n This prevents OpenAI API errors from improperly paired\n tool messages, preserves reasoning_content from \"thinking\"\n blocks that the base formatter skips, and ensures\n ``extra_content`` on tool_use blocks (e.g. Gemini\n thought_signature) is carried through to the API request.\n \"\"\"\n msgs = _sanitize_tool_messages(msgs)\n\n reasoning_contents = {}\n extra_contents: dict[str, Any] = {}\n for msg in msgs:\n if msg.role != \"assistant\":\n continue\n for block in msg.get_content_blocks():\n if block.get(\"type\") == \"thinking\":\n thinking = block.get(\"thinking\", \"\")\n if thinking:\n reasoning_contents[id(msg)] = thinking\n break\n for block in msg.get_content_blocks():\n if (\n block.get(\"type\") == \"tool_use\"\n and \"extra_content\" in block\n ):\n extra_contents[block[\"id\"]] = block[\"extra_content\"]\n\n # Convert file:// URLs to paths,\n # TODO: remove this after AgentScope updated\n for msg in msgs:\n for block in msg.get_content_blocks():\n if block.get(\"type\") == \"audio\":\n source = block.get(\"source\")\n if (\n isinstance(source, dict)\n and source.get(\"type\") == \"url\"\n and isinstance(source.get(\"url\"), str)\n and source[\"url\"].startswith(\"file://\")\n ):\n source[\"url\"] = _file_url_to_path(source[\"url\"])\n\n messages = await super()._format(msgs)\n\n if extra_contents:\n for message in messages:\n for tc in message.get(\"tool_calls\", []):\n ec = extra_contents.get(tc.get(\"id\"))\n if ec:\n tc[\"extra_content\"] = ec\n\n if reasoning_contents:\n # Build a list of reasoning values aligned with surviving\n # assistant messages. The parent formatter drops\n # thinking-only messages (no content/tool_calls), so we\n # predict survivors and collect reasoning only for those.\n aligned_reasoning = []\n for m in (msg for msg in msgs if msg.role == \"assistant\"):\n is_thinking_only = (\n isinstance(m.content, list)\n and m.content\n and all(b.get(\"type\") == \"thinking\" for b in m.content)\n )\n if not is_thinking_only:\n aligned_reasoning.append(\n reasoning_contents.get(id(m)),\n )\n\n out_assistant = [\n m for m in messages if m.get(\"role\") == \"assistant\"\n ]\n\n if len(aligned_reasoning) != len(out_assistant):\n logger.warning(\n \"Assistant message count mismatch after formatting \"\n \"(%d expected survivors, %d actual). \"\n \"Skipping reasoning_content injection.\",\n len(aligned_reasoning),\n len(out_assistant),\n )\n else:\n for i, out_msg in enumerate(out_assistant):\n if aligned_reasoning[i]:\n out_msg[\"reasoning_content\"] = aligned_reasoning[i]\n\n return _strip_top_level_message_name(messages)\n\n @staticmethod\n def convert_tool_result_to_string(\n output: Union[str, List[dict]],\n ) -> tuple[str, Sequence[Tuple[str, dict]]]:\n \"\"\"Extend parent class to support file blocks.\n\n Uses try-first strategy for compatibility with parent class.\n\n Args:\n output: Tool result output (string or list of blocks)\n\n Returns:\n Tuple of (text_representation, multimodal_data)\n \"\"\"\n if isinstance(output, str):\n return output, []\n\n # Try parent class method first\n try:\n return base_formatter_class.convert_tool_result_to_string(\n output,\n )\n except ValueError as e:\n if \"Unsupported block type: file\" not in str(e):\n raise\n\n # Handle output containing file blocks\n textual_output = []\n multimodal_data = []\n\n for block in output:\n if not isinstance(block, dict) or \"type\" not in block:\n raise ValueError(\n f\"Invalid block: {block}, \"\n \"expected a dict with 'type' key\",\n ) from e\n\n if block[\"type\"] == \"file\":\n file_path = block.get(\"path\", \"\") or block.get(\n \"url\",\n \"\",\n )\n file_name = block.get(\"name\", file_path)\n\n textual_output.append(\n f\"The returned file '{file_name}' \"\n f\"can be found at: {file_path}\",\n )\n multimodal_data.append((file_path, block))\n else:\n # Delegate other block types to parent class\n (\n text,\n data,\n ) = base_formatter_class.convert_tool_result_to_string(\n [block],\n )\n textual_output.append(text)\n multimodal_data.extend(data)\n\n if len(textual_output) == 0:\n return \"\", multimodal_data\n elif len(textual_output) == 1:\n return textual_output[0], multimodal_data\n else:\n return (\n \"\\n\".join(\"- \" + _ for _ in textual_output),\n multimodal_data,\n )\n\n FileBlockSupportFormatter.__name__ = (\n f\"FileBlockSupport{base_formatter_class.__name__}\"\n )\n return FileBlockSupportFormatter\n\n\ndef _strip_top_level_message_name(\n messages: list[dict],\n) -> list[dict]:\n \"\"\"Strip top-level `name` from OpenAI chat messages.\n\n Some strict OpenAI-compatible backends reject `messages[*].name`\n (especially for assistant/tool roles) and may return 500/400 on\n follow-up turns. Keep function/tool names unchanged.\n \"\"\"\n for message in messages:\n message.pop(\"name\", None)\n return messages\n\n\ndef create_model_and_formatter(\n agent_id: Optional[str] = None,\n) -> Tuple[ChatModelBase, FormatterBase]:\n \"\"\"Factory method to create model and formatter instances.\n\n This method handles both local and remote models, selecting the\n appropriate chat model class and formatter based on configuration.\n\n Args:\n agent_id: Optional agent ID to load agent-specific model config.\n If None, tries to get from context, then falls back to global.\n\n Returns:\n Tuple of (model_instance, formatter_instance)\n\n Example:\n >>> model, formatter = create_model_and_formatter()\n \"\"\"\n from ..app.agent_context import get_current_agent_id\n from ..config.config import load_agent_config\n\n # Determine agent_id (parameter > context > None)\n if agent_id is None:\n try:\n agent_id = get_current_agent_id()\n except Exception:\n pass\n\n # Try to get agent-specific model first\n model_slot = None\n if agent_id:\n try:\n agent_config = load_agent_config(agent_id)\n model_slot = agent_config.active_model\n except Exception:\n pass\n\n # Create chat model from agent-specific or global config\n if model_slot and model_slot.provider_id and model_slot.model:\n # Use agent-specific model\n manager = ProviderManager.get_instance()\n provider = manager.get_provider(model_slot.provider_id)\n if provider is None:\n raise ValueError(\n f\"Provider '{model_slot.provider_id}' not found.\",\n )\n if provider.is_local:\n model = create_local_chat_model(\n model_id=model_slot.model,\n stream=True,\n generate_kwargs={\"max_tokens\": None},\n )\n else:\n model = provider.get_chat_model_instance(model_slot.model)\n provider_id = model_slot.provider_id\n else:\n # Fallback to global active model\n model = ProviderManager.get_active_chat_model()\n provider_id = (\n ProviderManager.get_instance().get_active_model().provider_id\n )\n\n # Create the formatter based on the real model class\n formatter = _create_formatter_instance(model.__class__)\n\n # Wrap with retry logic for transient LLM API errors\n wrapped_model = TokenRecordingModelWrapper(provider_id, model)\n wrapped_model = RetryChatModel(wrapped_model)\n\n return wrapped_model, formatter\n\n\ndef _create_formatter_instance(\n chat_model_class: Type[ChatModelBase],\n) -> FormatterBase:\n \"\"\"Create a formatter instance for the given chat model class.\n\n The formatter is enhanced with file block support for handling\n file outputs in tool results.\n\n Args:\n chat_model_class: The chat model class\n\n Returns:\n Formatter instance with file block support\n \"\"\"\n base_formatter_class = _get_formatter_for_chat_model(chat_model_class)\n formatter_class = _create_file_block_support_formatter(\n base_formatter_class,\n )\n kwargs: dict[str, Any] = {}\n if issubclass(base_formatter_class, OpenAIChatFormatter):\n kwargs[\"promote_tool_result_images\"] = True\n return formatter_class(**kwargs)\n\n\n__all__ = [\n \"create_model_and_formatter\",\n]\n" }, { "path": "src/copaw/agents/prompt.py", "content": "# -*- coding: utf-8 -*-\n# flake8: noqa: E501\n\"\"\"System prompt building utilities.\n\nThis module provides utilities for building system prompts from\nmarkdown configuration files in the working directory.\n\"\"\"\nimport logging\nimport re\nfrom pathlib import Path\n\nlogger = logging.getLogger(__name__)\n\n# Default fallback prompt\nDEFAULT_SYS_PROMPT = \"\"\"\nYou are a helpful assistant.\n\"\"\"\n\n# Backward compatibility alias\nSYS_PROMPT = DEFAULT_SYS_PROMPT\n\n\nclass PromptConfig:\n \"\"\"Configuration for system prompt building.\"\"\"\n\n # Default files to load when no config is provided\n # All files are optional - if they don't exist, they'll be skipped\n DEFAULT_FILES = [\n \"AGENTS.md\",\n \"SOUL.md\",\n \"PROFILE.md\",\n ]\n\n\nclass PromptBuilder:\n \"\"\"Builder for constructing system prompts from markdown files.\"\"\"\n\n # Regex pattern to match heartbeat section markers\n HEARTBEAT_PATTERN = re.compile(\n r\".*?\",\n re.DOTALL,\n )\n\n def __init__(\n self,\n working_dir: Path,\n enabled_files: list[str] | None = None,\n heartbeat_enabled: bool = False,\n ):\n \"\"\"Initialize prompt builder.\n\n Args:\n working_dir: Directory containing markdown configuration files\n enabled_files: List of filenames to load (if None, uses default order)\n heartbeat_enabled: Whether heartbeat is enabled, affects AGENTS.md content\n \"\"\"\n self.working_dir = working_dir\n self.enabled_files = enabled_files\n self.heartbeat_enabled = heartbeat_enabled\n self.prompt_parts = []\n self.loaded_count = 0\n\n def _load_file(self, filename: str) -> None:\n \"\"\"Load a single markdown file.\n\n All files are optional - if they don't exist or can't be read,\n they will be silently skipped.\n\n Args:\n filename: Name of the file to load\n \"\"\"\n file_path = self.working_dir / filename\n\n if not file_path.exists():\n logger.debug(\"File %s not found, skipping\", filename)\n return\n\n try:\n content = file_path.read_text(encoding=\"utf-8\").strip()\n\n # Remove YAML frontmatter if present\n if content.startswith(\"---\"):\n parts = content.split(\"---\", 2)\n if len(parts) >= 3:\n content = parts[2].strip()\n\n # Filter heartbeat section from AGENTS.md if heartbeat is disabled\n if filename == \"AGENTS.md\":\n try:\n content = self._process_heartbeat_section(content)\n except Exception as e:\n logger.warning(\n f\"Failed to process heartbeat with {e}\",\n )\n\n if content:\n if self.prompt_parts: # Add separator if not first section\n self.prompt_parts.append(\"\")\n # Add section header with filename\n self.prompt_parts.append(f\"# {filename}\")\n self.prompt_parts.append(\"\")\n self.prompt_parts.append(content)\n self.loaded_count += 1\n logger.debug(\"Loaded %s\", filename)\n else:\n logger.debug(\"Skipped empty file: %s\", filename)\n\n except Exception as e:\n logger.warning(\n \"Failed to read file %s: %s, skipping\",\n filename,\n e,\n )\n\n def _process_heartbeat_section(self, content: str) -> str:\n \"\"\"Process heartbeat section in AGENTS.md content.\n\n - If heartbeat markers not found: keep content unchanged (backward compatibility)\n - If heartbeat is enabled: keep the content but remove the markers\n - If heartbeat is disabled: remove the entire section\n\n Args:\n content: Original AGENTS.md content\n\n Returns:\n Processed content\n \"\"\"\n # Check if markers exist\n if \"\" not in content:\n return content\n\n if self.heartbeat_enabled:\n # Keep content, just remove the markers\n content = content.replace(\"\", \"\")\n content = content.replace(\"\", \"\")\n return content.strip()\n else:\n # Remove the entire heartbeat section\n filtered = self.HEARTBEAT_PATTERN.sub(\"\", content)\n return filtered.strip()\n\n def build(self) -> str:\n \"\"\"Build the system prompt from markdown files.\n\n All files are optional. If no files can be loaded, returns the default prompt.\n\n Returns:\n Constructed system prompt string\n \"\"\"\n # Determine which files to load\n files_to_load = (\n PromptConfig.DEFAULT_FILES\n if self.enabled_files is None\n else self.enabled_files\n )\n\n # Load all files (all are optional)\n for filename in files_to_load:\n self._load_file(filename)\n\n if not self.prompt_parts:\n logger.warning(\"No content loaded from working directory\")\n return DEFAULT_SYS_PROMPT\n\n # Join all parts with double newlines\n final_prompt = \"\\n\\n\".join(self.prompt_parts)\n\n logger.debug(\n \"System prompt built from %d file(s), total length: %d chars\",\n self.loaded_count,\n len(final_prompt),\n )\n\n return final_prompt\n\n\ndef build_system_prompt_from_working_dir(\n working_dir: Path | None = None,\n enabled_files: list[str] | None = None,\n agent_id: str | None = None,\n heartbeat_enabled: bool = False,\n) -> str:\n \"\"\"\n Build system prompt by reading markdown files from working directory.\n\n This function constructs the system prompt by loading markdown files from\n the specified working directory (workspace_dir for multi-agent setup).\n These files define the agent's behavior, personality, and operational guidelines.\n\n The files to load are determined by the enabled_files parameter or\n agents.system_prompt_files configuration. If not configured, falls back to\n default files:\n - AGENTS.md - Detailed workflows, rules, and guidelines\n - SOUL.md - Core identity and behavioral principles\n - PROFILE.md - Agent identity and user profile\n\n All files are optional. If a file doesn't exist or can't be read, it will be\n skipped. If no files can be loaded, returns the default prompt.\n\n Args:\n working_dir: Directory to read markdown files from (if None, uses\n global WORKING_DIR for backward compatibility)\n enabled_files: List of filenames to load (if None, uses config or defaults)\n agent_id: Agent identifier to include in system prompt (optional)\n heartbeat_enabled: Whether heartbeat is enabled. When False, filters\n heartbeat section from AGENTS.md to avoid confusing instructions.\n\n Returns:\n str: Constructed system prompt from markdown files.\n If no files exist, returns the default prompt.\n\n Example:\n If working_dir contains AGENTS.md, SOUL.md and PROFILE.md, they will be combined:\n \"# AGENTS.md\\\\n\\\\n...\\\\n\\\\n# SOUL.md\\\\n\\\\n...\\\\n\\\\n# PROFILE.md\\\\n\\\\n...\"\n \"\"\"\n from ..constant import WORKING_DIR\n from ..config import load_config\n\n # Use provided working_dir or fallback to global WORKING_DIR\n if working_dir is None:\n working_dir = Path(WORKING_DIR)\n\n # Load enabled files from parameter or config\n if enabled_files is None:\n # Use agent-specific config if agent_id provided\n if agent_id:\n from ..config.config import load_agent_config\n\n try:\n agent_config = load_agent_config(agent_id)\n enabled_files = agent_config.system_prompt_files\n except (ValueError, FileNotFoundError):\n # Agent not found in config, fallback to global config\n config = load_config()\n enabled_files = config.agents.system_prompt_files\n else:\n # Fallback to global config for backward compatibility\n config = load_config()\n enabled_files = config.agents.system_prompt_files\n\n builder = PromptBuilder(\n working_dir=working_dir,\n enabled_files=enabled_files,\n heartbeat_enabled=heartbeat_enabled,\n )\n prompt = builder.build()\n\n # Add agent identity information at the beginning of the prompt\n if agent_id:\n identity_header = (\n f\"# Agent Identity\\n\\n\"\n f\"Your agent id is `{agent_id}`. \"\n f\"This is your unique identifier in the multi-agent system.\\n\\n\"\n )\n prompt = identity_header + prompt\n\n return prompt\n\n\ndef build_bootstrap_guidance(\n language: str = \"zh\",\n) -> str:\n \"\"\"Build bootstrap guidance message for first-time setup.\n\n Args:\n language: Language code (zh/en/ru)\n\n Returns:\n Formatted bootstrap guidance message\n \"\"\"\n if language == \"zh\":\n return (\n \"# 引导模式\\n\"\n \"\\n\"\n \"工作目录中存在 `BOOTSTRAP.md` — 首次设置。\\n\"\n \"\\n\"\n \"1. 阅读 BOOTSTRAP.md，友好地表示初次见面，\"\n \"引导用户完成设置。\\n\"\n \"2. 按照 BOOTSTRAP.md 的指示，\"\n \"帮助用户定义你的身份和偏好。\\n\"\n \"3. 按指南创建/更新必要文件\"\n \"（PROFILE.md、MEMORY.md 等）。\\n\"\n \"4. 完成后删除 BOOTSTRAP.md。\\n\"\n \"\\n\"\n \"如果用户希望跳过，直接回答下面的问题即可。\\n\"\n \"\\n\"\n \"---\\n\"\n \"\\n\"\n )\n # en / ru / other — default to English\n return (\n \"# BOOTSTRAP MODE\\n\"\n \"\\n\"\n \"`BOOTSTRAP.md` exists — first-time setup.\\n\"\n \"\\n\"\n \"1. Read BOOTSTRAP.md, greet the user, \"\n \"and guide them through setup.\\n\"\n \"2. Follow BOOTSTRAP.md instructions \"\n \"to define identity and preferences.\\n\"\n \"3. Create/update files \"\n \"(PROFILE.md, MEMORY.md, etc.) as described.\\n\"\n \"4. Delete BOOTSTRAP.md when done.\\n\"\n \"\\n\"\n \"If the user wants to skip, answer their \"\n \"question directly instead.\\n\"\n \"\\n\"\n \"---\\n\"\n \"\\n\"\n )\n\n\n__all__ = [\n \"build_system_prompt_from_working_dir\",\n \"build_bootstrap_guidance\",\n \"PromptBuilder\",\n \"PromptConfig\",\n \"DEFAULT_SYS_PROMPT\",\n \"SYS_PROMPT\", # Backward compatibility\n]\n" }, { "path": "src/copaw/agents/react_agent.py", "content": "# -*- coding: utf-8 -*-\n\"\"\"CoPaw Agent - Main agent implementation.\n\nThis module provides the main CoPawAgent class built on ReActAgent,\nwith integrated tools, skills, and memory management.\n\"\"\"\n\nimport asyncio\nimport logging\nimport os\nfrom pathlib import Path\nfrom typing import Any, List, Literal, Optional, Type, TYPE_CHECKING\n\nfrom agentscope.agent import ReActAgent\nfrom agentscope.mcp import HttpStatefulClient, StdIOStatefulClient\nfrom agentscope.memory import InMemoryMemory\nfrom agentscope.message import Msg\nfrom agentscope.tool import Toolkit\nfrom anyio import ClosedResourceError\nfrom pydantic import BaseModel\n\nfrom .command_handler import CommandHandler\nfrom .hooks import BootstrapHook, MemoryCompactionHook\nfrom .model_factory import create_model_and_formatter\nfrom .prompt import build_system_prompt_from_working_dir\nfrom .skills_manager import (\n ensure_skills_initialized,\n get_working_skills_dir,\n list_available_skills,\n)\nfrom .tool_guard_mixin import ToolGuardMixin\nfrom .tools import (\n browser_use,\n desktop_screenshot,\n edit_file,\n execute_shell_command,\n get_current_time,\n get_token_usage,\n glob_search,\n grep_search,\n read_file,\n send_file_to_user,\n set_user_timezone,\n view_image,\n write_file,\n create_memory_search_tool,\n)\nfrom .utils import process_file_and_media_blocks_in_message\nfrom ..constant import (\n WORKING_DIR,\n)\nfrom ..agents.memory import MemoryManager\n\nif TYPE_CHECKING:\n from ..config.config import AgentProfileConfig\n\nlogger = logging.getLogger(__name__)\n\n# Valid namesake strategies for tool registration\nNamesakeStrategy = Literal[\"override\", \"skip\", \"raise\", \"rename\"]\n\n\nclass CoPawAgent(ToolGuardMixin, ReActAgent):\n \"\"\"CoPaw Agent with integrated tools, skills, and memory management.\n\n This agent extends ReActAgent with:\n - Built-in tools (shell, file operations, browser, etc.)\n - Dynamic skill loading from working directory\n - Memory management with auto-compaction\n - Bootstrap guidance for first-time setup\n - System command handling (/compact, /new, etc.)\n - Tool-guard security interception (via ToolGuardMixin)\n\n MRO note\n ~~~~~~~~\n ``ToolGuardMixin`` overrides ``_acting`` and ``_reasoning`` via\n Python's MRO: CoPawAgent → ToolGuardMixin → ReActAgent. If you\n add a ``_acting`` or ``_reasoning`` override in this class, you\n **must** call ``super()._acting(...)`` / ``super()._reasoning(...)``\n so the guard interception remains active.\n \"\"\"\n\n def __init__(\n self,\n agent_config: \"AgentProfileConfig\",\n env_context: Optional[str] = None,\n enable_memory_manager: bool = True,\n mcp_clients: Optional[List[Any]] = None,\n memory_manager: \"MemoryManager | None\" = None,\n request_context: Optional[dict[str, str]] = None,\n namesake_strategy: NamesakeStrategy = \"skip\",\n workspace_dir: Path | None = None,\n ):\n \"\"\"Initialize CoPawAgent.\n\n Args:\n agent_config: Agent profile configuration containing all settings\n including running config (max_iters, max_input_length,\n memory_compact_threshold, etc.) and language setting.\n env_context: Optional environment context to prepend to\n system prompt\n enable_memory_manager: Whether to enable memory manager\n mcp_clients: Optional list of MCP clients for tool\n integration\n memory_manager: Optional memory manager instance\n request_context: Optional request context with session_id,\n user_id, channel, agent_id\n namesake_strategy: Strategy to handle namesake tool functions.\n Options: \"override\", \"skip\", \"raise\", \"rename\"\n (default: \"skip\")\n workspace_dir: Workspace directory for reading prompt files\n (if None, uses global WORKING_DIR)\n \"\"\"\n self._agent_config = agent_config\n self._env_context = env_context\n self._request_context = dict(request_context or {})\n self._mcp_clients = mcp_clients or []\n self._namesake_strategy = namesake_strategy\n self._workspace_dir = workspace_dir\n\n # Extract configuration from agent_config\n running_config = agent_config.running\n self._language = agent_config.language\n\n # Initialize toolkit with built-in tools\n toolkit = self._create_toolkit(namesake_strategy=namesake_strategy)\n\n # Load and register skills\n self._register_skills(toolkit)\n\n # Build system prompt\n sys_prompt = self._build_sys_prompt()\n\n # Create model and formatter using factory method\n model, formatter = create_model_and_formatter()\n\n # Initialize parent ReActAgent\n super().__init__(\n name=\"Friday\",\n model=model,\n sys_prompt=sys_prompt,\n toolkit=toolkit,\n memory=InMemoryMemory(),\n formatter=formatter,\n max_iters=running_config.max_iters,\n )\n\n # Setup memory manager\n self._setup_memory_manager(\n enable_memory_manager,\n memory_manager,\n namesake_strategy,\n )\n\n # Setup command handler\n self.command_handler = CommandHandler(\n agent_name=self.name,\n memory=self.memory,\n memory_manager=self.memory_manager,\n enable_memory_manager=self._enable_memory_manager,\n )\n\n # Register hooks\n self._register_hooks()\n\n def _create_toolkit(\n self,\n namesake_strategy: NamesakeStrategy = \"skip\",\n ) -> Toolkit:\n \"\"\"Create and populate toolkit with built-in tools.\n\n Args:\n namesake_strategy: Strategy to handle namesake tool functions.\n Options: \"override\", \"skip\", \"raise\", \"rename\"\n (default: \"skip\")\n\n Returns:\n Configured toolkit instance\n \"\"\"\n toolkit = Toolkit()\n\n # Check which tools are enabled from agent config\n enabled_tools = {}\n try:\n if hasattr(self._agent_config, \"tools\") and hasattr(\n self._agent_config.tools,\n \"builtin_tools\",\n ):\n builtin_tools = self._agent_config.tools.builtin_tools\n enabled_tools = {\n name: tool.enabled for name, tool in builtin_tools.items()\n }\n except Exception as e:\n logger.warning(\n f\"Failed to load agent tools config: {e}, \"\n \"all tools will be disabled\",\n )\n\n # Map of tool functions\n tool_functions = {\n \"execute_shell_command\": execute_shell_command,\n \"read_file\": read_file,\n \"write_file\": write_file,\n \"edit_file\": edit_file,\n \"grep_search\": grep_search,\n \"glob_search\": glob_search,\n \"browser_use\": browser_use,\n \"desktop_screenshot\": desktop_screenshot,\n \"view_image\": view_image,\n \"send_file_to_user\": send_file_to_user,\n \"get_current_time\": get_current_time,\n \"set_user_timezone\": set_user_timezone,\n \"get_token_usage\": get_token_usage,\n }\n\n # Register only enabled tools\n for tool_name, tool_func in tool_functions.items():\n # If tool not in config, enable by default (backward compatibility)\n if enabled_tools.get(tool_name, True):\n toolkit.register_tool_function(\n tool_func,\n namesake_strategy=namesake_strategy,\n )\n logger.debug(\"Registered tool: %s\", tool_name)\n else:\n logger.debug(\"Skipped disabled tool: %s\", tool_name)\n\n return toolkit\n\n def _register_skills(self, toolkit: Toolkit) -> None:\n \"\"\"Load and register skills from workspace directory.\n\n Args:\n toolkit: Toolkit to register skills to\n \"\"\"\n workspace_dir = self._workspace_dir or WORKING_DIR\n\n # Check skills initialization\n ensure_skills_initialized(workspace_dir)\n\n working_skills_dir = get_working_skills_dir(workspace_dir)\n available_skills = list_available_skills(workspace_dir)\n\n for skill_name in available_skills:\n skill_dir = working_skills_dir / skill_name\n if skill_dir.exists():\n try:\n toolkit.register_agent_skill(str(skill_dir))\n logger.debug(\"Registered skill: %s\", skill_name)\n except Exception as e:\n logger.error(\n \"Failed to register skill '%s': %s\",\n skill_name,\n e,\n )\n\n def _build_sys_prompt(self) -> str:\n \"\"\"Build system prompt from working dir files and env context.\n\n Returns:\n Complete system prompt string\n \"\"\"\n # Get agent_id from request_context\n agent_id = (\n self._request_context.get(\"agent_id\")\n if self._request_context\n else None\n )\n\n # Check if heartbeat is enabled in agent config\n heartbeat_enabled = False\n if (\n hasattr(self._agent_config, \"heartbeat\")\n and self._agent_config.heartbeat is not None\n ):\n heartbeat_enabled = self._agent_config.heartbeat.enabled\n\n sys_prompt = build_system_prompt_from_working_dir(\n working_dir=self._workspace_dir,\n agent_id=agent_id,\n heartbeat_enabled=heartbeat_enabled,\n )\n logger.debug(\"System prompt:\\n%s\", sys_prompt)\n if self._env_context is not None:\n sys_prompt = sys_prompt + \"\\n\\n\" + self._env_context\n return sys_prompt\n\n def _setup_memory_manager(\n self,\n enable_memory_manager: bool,\n memory_manager: MemoryManager | None,\n namesake_strategy: NamesakeStrategy,\n ) -> None:\n \"\"\"Setup memory manager and register memory search tool if enabled.\n\n Args:\n enable_memory_manager: Whether to enable memory manager\n memory_manager: Optional memory manager instance\n namesake_strategy: Strategy to handle namesake tool functions\n \"\"\"\n # Check env var: if ENABLE_MEMORY_MANAGER=false, disable memory manager\n env_enable_mm = os.getenv(\"ENABLE_MEMORY_MANAGER\", \"\")\n if env_enable_mm.lower() == \"false\":\n enable_memory_manager = False\n\n self._enable_memory_manager: bool = enable_memory_manager\n self.memory_manager = memory_manager\n\n # Register memory_search tool if enabled and available\n if self._enable_memory_manager and self.memory_manager is not None:\n # update memory manager\n self.memory = self.memory_manager.get_in_memory_memory()\n self.memory_manager.chat_model = self.model\n self.memory_manager.formatter = self.formatter\n\n # Register memory_search as a tool function\n self.toolkit.register_tool_function(\n create_memory_search_tool(self.memory_manager),\n namesake_strategy=namesake_strategy,\n )\n logger.debug(\"Registered memory_search tool\")\n\n def _register_hooks(self) -> None:\n \"\"\"Register pre-reasoning and pre-acting hooks.\"\"\"\n # Bootstrap hook - checks BOOTSTRAP.md on first interaction\n # Use workspace_dir if available, else fallback to WORKING_DIR\n working_dir = (\n self._workspace_dir if self._workspace_dir else WORKING_DIR\n )\n bootstrap_hook = BootstrapHook(\n working_dir=working_dir,\n language=self._language,\n )\n self.register_instance_hook(\n hook_type=\"pre_reasoning\",\n hook_name=\"bootstrap_hook\",\n hook=bootstrap_hook.__call__,\n )\n logger.debug(\"Registered bootstrap hook\")\n\n # Memory compaction hook - auto-compact when context is full\n if self._enable_memory_manager and self.memory_manager is not None:\n memory_compact_hook = MemoryCompactionHook(\n memory_manager=self.memory_manager,\n )\n self.register_instance_hook(\n hook_type=\"pre_reasoning\",\n hook_name=\"memory_compact_hook\",\n hook=memory_compact_hook.__call__,\n )\n logger.debug(\"Registered memory compaction hook\")\n\n def rebuild_sys_prompt(self) -> None:\n \"\"\"Rebuild and replace the system prompt.\n\n Useful after load_session_state to ensure the prompt reflects\n the latest AGENTS.md / SOUL.md / PROFILE.md on disk.\n\n Updates both self._sys_prompt and the first system-role\n message stored in self.memory.content (if one exists).\n \"\"\"\n self._sys_prompt = self._build_sys_prompt()\n\n for msg, _marks in self.memory.content:\n if msg.role == \"system\":\n msg.content = self.sys_prompt\n break\n\n async def register_mcp_clients(\n self,\n namesake_strategy: NamesakeStrategy = \"skip\",\n ) -> None:\n \"\"\"Register MCP clients on this agent's toolkit after construction.\n\n Args:\n namesake_strategy: Strategy to handle namesake tool functions.\n Options: \"override\", \"skip\", \"raise\", \"rename\"\n (default: \"skip\")\n \"\"\"\n for i, client in enumerate(self._mcp_clients):\n client_name = getattr(client, \"name\", repr(client))\n try:\n await self.toolkit.register_mcp_client(\n client,\n namesake_strategy=namesake_strategy,\n )\n except (ClosedResourceError, asyncio.CancelledError) as error:\n if self._should_propagate_cancelled_error(error):\n raise\n logger.warning(\n \"MCP client '%s' session interrupted while listing tools; \"\n \"trying recovery\",\n client_name,\n )\n recovered_client = await self._recover_mcp_client(client)\n if recovered_client is not None:\n self._mcp_clients[i] = recovered_client\n try:\n await self.toolkit.register_mcp_client(\n recovered_client,\n namesake_strategy=namesake_strategy,\n )\n continue\n except asyncio.CancelledError as recover_error:\n if self._should_propagate_cancelled_error(\n recover_error,\n ):\n raise\n logger.warning(\n \"MCP client '%s' registration cancelled after \"\n \"recovery, skipping\",\n client_name,\n )\n except Exception as e: # pylint: disable=broad-except\n logger.warning(\n \"MCP client '%s' still unavailable after \"\n \"recovery, skipping: %s\",\n client_name,\n e,\n )\n else:\n logger.warning(\n \"MCP client '%s' recovery failed, skipping\",\n client_name,\n )\n except Exception as e: # pylint: disable=broad-except\n logger.warning(\n \"Failed to register MCP client '%s', skipping: %s\",\n client_name,\n e,\n exc_info=True,\n )\n\n async def _recover_mcp_client(self, client: Any) -> Any | None:\n \"\"\"Recover MCP client from broken session and return healthy client.\"\"\"\n if await self._reconnect_mcp_client(client):\n return client\n\n rebuilt_client = self._rebuild_mcp_client(client)\n if rebuilt_client is None:\n return None\n\n if await self._reconnect_mcp_client(rebuilt_client):\n return self._reuse_shared_client_reference(\n original_client=client,\n rebuilt_client=rebuilt_client,\n )\n\n return None\n\n @staticmethod\n def _reuse_shared_client_reference(\n original_client: Any,\n rebuilt_client: Any,\n ) -> Any:\n \"\"\"Keep manager-shared client reference stable after rebuild.\"\"\"\n original_dict = getattr(original_client, \"__dict__\", None)\n rebuilt_dict = getattr(rebuilt_client, \"__dict__\", None)\n if isinstance(original_dict, dict) and isinstance(rebuilt_dict, dict):\n original_dict.update(rebuilt_dict)\n return original_client\n return rebuilt_client\n\n @staticmethod\n def _should_propagate_cancelled_error(error: BaseException) -> bool:\n \"\"\"Only swallow MCP-internal cancellations, not task cancellation.\"\"\"\n if not isinstance(error, asyncio.CancelledError):\n return False\n\n task = asyncio.current_task()\n if task is None:\n return False\n\n cancelling = getattr(task, \"cancelling\", None)\n if callable(cancelling):\n return cancelling() > 0\n\n # Python < 3.11: Task.cancelling() is unavailable.\n # Fall back to propagating CancelledError to avoid swallowing\n # genuine task cancellations when we cannot inspect the state.\n return True\n\n @staticmethod\n async def _reconnect_mcp_client(\n client: Any,\n timeout: float = 60.0,\n ) -> bool:\n \"\"\"Best-effort reconnect for stateful MCP clients.\"\"\"\n close_fn = getattr(client, \"close\", None)\n if callable(close_fn):\n try:\n await close_fn()\n except asyncio.CancelledError: # pylint: disable=try-except-raise\n raise\n except Exception: # pylint: disable=broad-except\n pass\n\n connect_fn = getattr(client, \"connect\", None)\n if not callable(connect_fn):\n return False\n\n try:\n await asyncio.wait_for(connect_fn(), timeout=timeout)\n return True\n except asyncio.CancelledError: # pylint: disable=try-except-raise\n raise\n except asyncio.TimeoutError:\n return False\n except Exception: # pylint: disable=broad-except\n return False\n\n @staticmethod\n def _rebuild_mcp_client(client: Any) -> Any | None:\n \"\"\"Rebuild a fresh MCP client instance from stored config metadata.\"\"\"\n rebuild_info = getattr(client, \"_copaw_rebuild_info\", None)\n if not isinstance(rebuild_info, dict):\n return None\n\n transport = rebuild_info.get(\"transport\")\n name = rebuild_info.get(\"name\")\n\n try:\n if transport == \"stdio\":\n rebuilt_client = StdIOStatefulClient(\n name=name,\n command=rebuild_info.get(\"command\"),\n args=rebuild_info.get(\"args\", []),\n env=rebuild_info.get(\"env\", {}),\n cwd=rebuild_info.get(\"cwd\"),\n )\n setattr(rebuilt_client, \"_copaw_rebuild_info\", rebuild_info)\n return rebuilt_client\n\n raw_headers = rebuild_info.get(\"headers\") or {}\n headers = (\n {k: os.path.expandvars(v) for k, v in raw_headers.items()}\n if raw_headers\n else None\n )\n rebuilt_client = HttpStatefulClient(\n name=name,\n transport=transport,\n url=rebuild_info.get(\"url\"),\n headers=headers,\n )\n setattr(rebuilt_client, \"_copaw_rebuild_info\", rebuild_info)\n return rebuilt_client\n except Exception: # pylint: disable=broad-except\n return None\n\n # ------------------------------------------------------------------\n # Media-block fallback: strip unsupported media blocks (image, audio,\n # video) from memory and retry when the model rejects them.\n # ------------------------------------------------------------------\n\n _MEDIA_BLOCK_TYPES = {\"image\", \"audio\", \"video\"}\n\n async def _reasoning(\n self,\n tool_choice: Literal[\"auto\", \"none\", \"required\"] | None = None,\n ) -> Msg:\n \"\"\"Override reasoning with media-block fallback.\n\n If the model call fails with a bad-request error and memory\n contains media blocks (image/audio/video), strip them all and\n retry once. Calls ``super()._reasoning`` to keep the\n ToolGuardMixin interception active.\n \"\"\"\n try:\n return await super()._reasoning(tool_choice=tool_choice)\n except Exception as e:\n if not self._is_bad_request_or_media_error(e):\n raise\n\n n_stripped = self._strip_media_blocks_from_memory()\n if n_stripped == 0:\n raise\n\n logger.warning(\n \"_reasoning failed (%s). \"\n \"Stripped %d media block(s) from memory, retrying.\",\n e,\n n_stripped,\n )\n return await super()._reasoning(tool_choice=tool_choice)\n\n async def _summarizing(self) -> Msg:\n \"\"\"Override summarizing with media-block fallback and tool_use filter.\n\n Some models (e.g. kimi-k2.5) generate tool_use blocks even when\n no tools are provided, by mimicking patterns in conversation\n history. Since _summarizing has no acting stage, those blocks\n would be displayed but never executed.\n\n We set ``_in_summarizing`` so that ``print`` can strip tool_use\n blocks from streaming chunks *before* they reach the frontend,\n preventing the visual flash of phantom tool calls.\n \"\"\"\n self._in_summarizing = True\n try:\n try:\n msg = await super()._summarizing()\n except Exception as e:\n if not self._is_bad_request_or_media_error(e):\n raise\n\n n_stripped = self._strip_media_blocks_from_memory()\n if n_stripped == 0:\n raise\n\n logger.warning(\n \"_summarizing failed (%s). \"\n \"Stripped %d media block(s) from memory, retrying.\",\n e,\n n_stripped,\n )\n msg = await super()._summarizing()\n finally:\n self._in_summarizing = False\n\n return self._strip_tool_use_from_msg(msg)\n\n async def print(\n self,\n msg: Msg,\n last: bool = True,\n speech: Any = None,\n ) -> None:\n \"\"\"Filter tool_use blocks during _summarizing before they hit the\n message queue, preventing the frontend from briefly rendering\n phantom tool calls that will never be executed.\n\n On the *final* streaming event (``last=True``), append the\n round-end notice so users see it immediately instead of only\n after a page refresh. Intermediate events that become empty\n after filtering are silently skipped to avoid blank UI flashes.\n \"\"\"\n if getattr(self, \"_in_summarizing\", False) and isinstance(\n msg.content,\n list,\n ):\n original = msg.content\n filtered = [\n b\n for b in original\n if not (isinstance(b, dict) and b.get(\"type\") == \"tool_use\")\n ]\n if len(filtered) != len(original):\n if not filtered and not last:\n return\n if last:\n filtered.append(\n {\"type\": \"text\", \"text\": self._ROUND_END_NOTICE},\n )\n msg.content = filtered\n try:\n return await super().print(msg, last, speech=speech)\n finally:\n msg.content = original\n return await super().print(msg, last, speech=speech)\n\n _ROUND_END_NOTICE = (\n \"\\n\\n---\\n\"\n \"本轮调用已达最大次数，回复已终止，请继续输入。\\n\"\n \"Maximum iterations reached for this round. \"\n \"Please send a new message to continue.\"\n )\n\n @staticmethod\n def _strip_tool_use_from_msg(msg: Msg) -> Msg:\n \"\"\"Remove tool_use blocks from a message and append a user notice.\n\n When _summarizing is called without tools, some models still\n return tool_use blocks. Those blocks can never be executed, so\n strip them and append a bilingual notice telling the user this\n round of calls has ended.\n \"\"\"\n if not isinstance(msg.content, list):\n return msg\n\n filtered = [\n block\n for block in msg.content\n if not (\n isinstance(block, dict) and block.get(\"type\") == \"tool_use\"\n )\n ]\n\n if len(filtered) == len(msg.content):\n return msg\n\n n_removed = len(msg.content) - len(filtered)\n logger.debug(\n \"Stripped %d tool_use block(s) from _summarizing response\",\n n_removed,\n )\n\n filtered.append({\"type\": \"text\", \"text\": CoPawAgent._ROUND_END_NOTICE})\n msg.content = filtered\n return msg\n\n @staticmethod\n def _is_bad_request_or_media_error(exc: Exception) -> bool:\n \"\"\"Return True for 400-class or media-related model errors.\n\n Targets bad-request (400) errors because unsupported media\n content typically causes request validation failures. Keyword\n matching provides an extra safety net for providers that use\n non-standard status codes.\n \"\"\"\n status = getattr(exc, \"status_code\", None)\n if status == 400:\n return True\n\n error_str = str(exc).lower()\n keywords = [\n \"image\",\n \"audio\",\n \"video\",\n \"vision\",\n \"multimodal\",\n \"image_url\",\n ]\n return any(kw in error_str for kw in keywords)\n\n _MEDIA_PLACEHOLDER = (\n \"[Media content removed - model does not support this media type]\"\n )\n\n def _strip_media_blocks_from_memory(self) -> int:\n \"\"\"Remove media blocks (image/audio/video) from all messages.\n\n Also strips media blocks nested inside ToolResultBlock outputs.\n Inserts placeholder text when stripping leaves content empty to\n avoid malformed API requests.\n\n Returns:\n Total number of media blocks removed.\n \"\"\"\n media_types = self._MEDIA_BLOCK_TYPES\n total_stripped = 0\n\n for msg, _marks in self.memory.content:\n if not isinstance(msg.content, list):\n continue\n\n new_content = []\n for block in msg.content:\n if (\n isinstance(block, dict)\n and block.get(\"type\") in media_types\n ):\n total_stripped += 1\n continue\n\n if (\n isinstance(block, dict)\n and block.get(\"type\") == \"tool_result\"\n and isinstance(block.get(\"output\"), list)\n ):\n original_len = len(block[\"output\"])\n block[\"output\"] = [\n item\n for item in block[\"output\"]\n if not (\n isinstance(item, dict)\n and item.get(\"type\") in media_types\n )\n ]\n stripped_count = original_len - len(block[\"output\"])\n total_stripped += stripped_count\n if stripped_count > 0 and not block[\"output\"]:\n block[\"output\"] = self._MEDIA_PLACEHOLDER\n\n new_content.append(block)\n\n if not new_content and total_stripped > 0:\n new_content.append(\n {\"type\": \"text\", \"text\": self._MEDIA_PLACEHOLDER},\n )\n\n msg.content = new_content\n\n return total_stripped\n\n async def reply(\n self,\n msg: Msg | list[Msg] | None = None,\n structured_model: Type[BaseModel] | None = None,\n ) -> Msg:\n \"\"\"Override reply to process file blocks and handle commands.\n\n Args:\n msg: Input message(s) from user\n structured_model: Optional pydantic model for structured output\n\n Returns:\n Response message\n \"\"\"\n # Set workspace_dir in context for tool functions\n from ..config.context import set_current_workspace_dir\n\n set_current_workspace_dir(self._workspace_dir)\n\n # Process file and media blocks in messages\n if msg is not None:\n await process_file_and_media_blocks_in_message(msg)\n\n # Check if message is a system command\n last_msg = msg[-1] if isinstance(msg, list) else msg\n query = (\n last_msg.get_text_content() if isinstance(last_msg, Msg) else None\n )\n\n if self.command_handler.is_command(query):\n logger.info(f\"Received command: {query}\")\n msg = await self.command_handler.handle_command(query)\n await self.print(msg)\n return msg\n\n # Normal message processing\n logger.info(\"CoPawAgent.reply: max_iters=%s\", self.max_iters)\n return await super().reply(msg=msg, structured_model=structured_model)\n\n async def interrupt(self, msg: Msg | list[Msg] | None = None) -> None:\n \"\"\"Interrupt the current reply process and wait for cleanup.\"\"\"\n if self._reply_task and not self._reply_task.done():\n task = self._reply_task\n task.cancel(msg)\n try:\n await task\n except asyncio.CancelledError:\n if not task.cancelled():\n raise\n except Exception:\n logger.warning(\n \"Exception occurred during interrupt cleanup\",\n exc_info=True,\n )\n" }, { "path": "src/copaw/agents/routing_chat_model.py", "content": "# -*- coding: utf-8 -*-\n\"\"\"ChatModel router for local/cloud model selection.\"\"\"\n\nfrom __future__ import annotations\n\nimport logging\nfrom dataclasses import dataclass, field\nfrom typing import Any, AsyncGenerator, Literal, Type\n\nfrom agentscope.formatter import FormatterBase\nfrom agentscope.model import ChatModelBase\nfrom agentscope.model._model_response import ChatResponse\nfrom pydantic import BaseModel\n\nfrom ..config.config import AgentsLLMRoutingConfig\n\nlogger = logging.getLogger(__name__)\n\n\nRoute = Literal[\"local\", \"cloud\"]\n\n\n@dataclass\nclass RoutingDecision:\n route: Route\n reasons: list[str] = field(default_factory=list)\n\n\nclass RoutingPolicy:\n \"\"\"Select a route using the configured default mode.\"\"\"\n\n def __init__(self, cfg: AgentsLLMRoutingConfig):\n self.cfg = cfg\n\n def decide(\n self,\n *,\n text: str = \"\",\n channel: str = \"\",\n tools_available: bool = True,\n ) -> RoutingDecision:\n del text, channel, tools_available\n\n if getattr(self.cfg, \"mode\", \"local_first\") == \"cloud_first\":\n return RoutingDecision(\n route=\"cloud\",\n reasons=[\"mode:cloud_first\"],\n )\n\n return RoutingDecision(\n route=\"local\",\n reasons=[\"mode:local_first\"],\n )\n\n\n@dataclass(frozen=True)\nclass RoutingEndpoint:\n provider_id: str\n model_name: str\n model: ChatModelBase\n formatter: FormatterBase\n formatter_family: Type[FormatterBase]\n\n\nclass RoutingChatModel(ChatModelBase):\n \"\"\"A ChatModelBase that routes between local and cloud slots.\"\"\"\n\n def __init__(\n self,\n *,\n local_endpoint: RoutingEndpoint,\n cloud_endpoint: RoutingEndpoint,\n routing_cfg: AgentsLLMRoutingConfig,\n ) -> None:\n super().__init__(\n model_name=\"routing\",\n stream=bool(getattr(local_endpoint.model, \"stream\", True)),\n )\n self.local_endpoint = local_endpoint\n self.cloud_endpoint = cloud_endpoint\n self.routing_cfg = routing_cfg\n self.policy = RoutingPolicy(routing_cfg)\n\n async def __call__(\n self,\n messages: list[dict],\n tools: list[dict] | None = None,\n tool_choice: Literal[\"auto\", \"none\", \"required\"] | str | None = None,\n structured_model: Type[BaseModel] | None = None,\n **kwargs: Any,\n ) -> ChatResponse | AsyncGenerator[ChatResponse, None]:\n text = \" \".join(\n message[\"content\"]\n for message in messages\n if message.get(\"role\") == \"user\"\n and isinstance(message.get(\"content\"), str)\n )\n decision = self.policy.decide(\n text=text,\n tools_available=tools is not None,\n )\n endpoint = (\n self.local_endpoint\n if decision.route == \"local\"\n else self.cloud_endpoint\n )\n\n logger.debug(\n \"LLM routing decision: route=%s provider=%s model=%s reasons=%s\",\n decision.route,\n endpoint.provider_id,\n endpoint.model_name,\n \",\".join(decision.reasons),\n )\n\n return await endpoint.model(\n messages=messages,\n tools=tools,\n tool_choice=tool_choice,\n structured_model=structured_model,\n **kwargs,\n )\n" }, { "path": "src/copaw/agents/schema.py", "content": "# -*- coding: utf-8 -*-\n\"\"\"\nAgent tools schema: type definitions for agent tool responses.\n\"\"\"\nfrom typing import Literal, Optional\nfrom typing_extensions import TypedDict, Required\n\nfrom agentscope.message import Base64Source, URLSource\n\n\nclass FileBlock(TypedDict, total=False):\n \"\"\"File block for sending files to users.\"\"\"\n\n type: Required[Literal[\"file\"]]\n \"\"\"The type of the block\"\"\"\n\n source: Required[Base64Source | URLSource]\n \"\"\"The source of the file\"\"\"\n\n filename: Optional[str]\n \"\"\"The filename of the file\"\"\"\n" }, { "path": "src/copaw/agents/skills/__init__.py", "content": "# -*- coding: utf-8 -*-\n\"\"\"Agent skills directory.\"\"\"\n" }, { "path": "src/copaw/agents/skills/browser_visible/SKILL.md", "content": "---\nname: browser_visible\ndescription: \"当用户希望打开真实可见的浏览器窗口（而非后台无头模式）时，使用 browser_use 的 headed 参数启动浏览器，随后可正常 open/snapshot/click 等。适用于用户想亲眼看到页面、演示或调试场景。\"\nmetadata:\n {\n \"builtin_skill_version\": \"1.0\",\n \"copaw\":\n {\n \"emoji\": \"🖥️\",\n \"requires\": {}\n }\n }\n---\n\n# 可见浏览器（真实窗口）参考\n\n默认情况下，**browser_use** 在后台以无头（headless）模式运行，不会弹出浏览器窗口。当用户明确希望**打开真正的浏览器窗口**、**看到浏览器界面**、**有界面的浏览器**或**可见浏览器**时，应使用本 skill：先以 **headed** 模式启动浏览器，再按需打开页面并操作。\n\n## 何时使用\n\n- 用户说：「打开真实浏览器」「打开有界面的浏览器」「我想看到浏览器」「不要后台，要能看到窗口」\n- 用户希望亲眼看到页面加载、点击、填表等过程（演示、调试、教学）\n- 用户需要与可见页面交互（如登录、验证码等需人工参与的场景）\n\n## 使用方式（browser_use）\n\n1. **先以可见模式启动浏览器** \n 调用 **browser_use**，`action` 为 `start`，并传入 **headed=true**：\n ```json\n {\"action\": \"start\", \"headed\": true}\n ```\n 成功后会出现一个真实的 Chromium 浏览器窗口。\n\n2. **再按需打开页面并操作** \n 与无头模式用法相同，例如：\n - 打开 URL：`{\"action\": \"open\", \"url\": \"https://example.com\"}`\n - 获取页面结构：`{\"action\": \"snapshot\"}`\n - 点击、输入等：使用 `ref` 或 `selector` 进行 click、type 等\n\n3. **关闭可见浏览器** \n 使用完毕后可调用：`{\"action\": \"stop\"}` 关闭浏览器。\n\n## 与默认（无头）模式的区别\n\n| 模式 | 启动方式 | 是否弹出窗口 |\n|----------|-----------------------------|--------------|\n| 无头模式 | `{\"action\": \"start\"}` | 否（后台） |\n| 可见模式 | `{\"action\": \"start\", \"headed\": true}` | 是（真实窗口） |\n\n## 注意\n\n- 若当前已有浏览器在运行，需要先 `stop` 再以 `headed: true` 重新 `start`，才能切换到可见窗口。\n- 可见模式会占用桌面并需要图形环境，服务器或无图形环境可能无法使用。" }, { "path": "src/copaw/agents/skills/cron/SKILL.md", "content": "---\nname: cron\ndescription: 通过 copaw 命令管理定时任务 - 创建、查询、暂停、恢复、删除任务\nmetadata: { \"builtin_skill_version\": \"1.0\", \"copaw\": { \"emoji\": \"⏰\" } }\n---\n\n# 定时任务管理\n\n使用 `copaw cron` 命令管理定时任务。\n\n## 常用命令\n\n```bash\n# 列出所有任务（默认操作 default agent）\ncopaw cron list\n\n# 为特定 agent 列出任务\ncopaw cron list --agent-id abc123\n\n# 查看任务详情\ncopaw cron get --agent-id \n\n# 查看任务状态\ncopaw cron state --agent-id \n\n# 删除任务\ncopaw cron delete --agent-id \n\n# 暂停/恢复任务\ncopaw cron pause --agent-id \ncopaw cron resume --agent-id \n\n# 立即执行一次\ncopaw cron run --agent-id \n```\n\n**重要**：所有命令都**必须**显式指定 `--agent-id` 参数。你的 agent_id 在系统提示的 Agent Identity 部分（`Your agent id is ...`）中已告知，直接使用该值。**不得省略**，否则任务会错误地创建到 default agent 的 workspace。\n\n## 创建任务\n\n支持两种任务类型：\n- **text**：定时向频道发送固定消息\n- **agent**：定时向 Agent 提问并发送回复到频道\n\n### 快速创建\n\n```bash\n# 每天 9:00 发送文本消息（默认 agent）\ncopaw cron create \\\n --type text \\\n --name \"每日早安\" \\\n --cron \"0 9 * * *\" \\\n --channel imessage \\\n --target-user \"CHANGEME\" \\\n --target-session \"CHANGEME\" \\\n --text \"早上好！\"\n\n# 为特定 agent 创建任务\ncopaw cron create \\\n --agent-id abc123 \\\n --type agent \\\n --name \"检查待办\" \\\n --cron \"0 */2 * * *\" \\\n --channel dingtalk \\\n --target-user \"CHANGEME\" \\\n --target-session \"CHANGEME\" \\\n --text \"我有什么待办事项？\"\n```\n\n### 必填参数\n\n创建任务需要：\n- `--type`：任务类型（text 或 agent）\n- `--name`：任务名称\n- `--cron`：cron 表达式（如 `\"0 9 * * *\"` 表示每天 9:00）\n- `--channel`：目标频道（console / feishu / dingtalk / discord / qq / telegram / imessage / matrix / mattermost 等）。用户未指定时，使用\"当前的channel\"的值\n- `--target-user`：用户标识\n- `--target-session`：会话标识\n- `--text`：消息内容（text 类型）或提问内容（agent 类型）\n\n### 可选参数\n\n- `--agent-id`：**必须指定**你自己的 agent ID（系统提示的 Agent Identity 部分可以找到）。默认值为 `default`，但**不得依赖默认值**。\n\n### 从 JSON 创建（复杂配置）\n\n```bash\ncopaw cron create -f job_spec.json\n```\n\n## Cron 表达式示例\n\n```\n0 9 * * * # 每天 9:00\n0 */2 * * * # 每 2 小时\n30 8 * * 1-5 # 工作日 8:30\n0 0 * * 0 # 每周日零点\n*/15 * * * * # 每 15 分钟\n```\n\n## 使用建议\n\n- 缺少参数时，询问用户补充后再创建\n- 暂停/删除/恢复前，用 `copaw cron list` 查找 job_id\n- 排查问题时，用 `copaw cron state ` 查看状态\n- 给用户的命令要完整、可直接复制执行\n- **必须**指定 `--agent-id` 参数，值从系统提示的 Agent Identity 部分读取\n" }, { "path": "src/copaw/agents/skills/dingtalk_channel/SKILL.md", "content": "---\nname: dingtalk_channel_connect\ndescription: \"使用可视浏览器自动完成 CoPaw 的钉钉频道接入。适用于用户提到钉钉、DingTalk、开发者后台、Client ID、Client Secret、机器人、Stream 模式、绑定或配置 channel 的场景；支持遇到登录页时暂停，等待用户登录后继续。\"\nmetadata:\n {\n \"builtin_skill_version\": \"1.0\",\n \"copaw\":\n {\n \"emoji\": \"🤖\",\n \"requires\": {}\n }\n }\n---\n\n# 钉钉 Channel 自动连接（可视浏览器）\n\n此 skill 用于通过可视浏览器自动化完成钉钉应用创建与 CoPaw channel 绑定。\n\n## 强制规则\n\n1. 必须使用可视浏览器模式启动：\n\n```json\n{\"action\": \"start\", \"headed\": true}\n```\n\n2. 遇到登录关卡必须暂停：\n - 若页面出现登录界面（如 `登录`、扫码登录、手机号/密码登录），立即停止自动操作。\n - 明确提示用户先手动登录，再等待用户回复“登录好了/继续”。\n - 未收到用户确认前，不得继续执行后续步骤。\n\n3. 任何应用配置变更都必须新建版本并发布后才生效：\n - 配置完机器人相关信息后**一定要发布机器人**\n - 不论是新建应用还是修改应用信息（名称、描述、图标、机器人配置等），最终都**必须执行“创建新版本 + 发布”**。\n - 若未完成发布，不得宣称配置已生效。\n\n## 执行前显著确认（必须先做）\n\n在开始自动化点击前，先向用户发起一次“配置确认”，明确告知可自定义项、图片规范、默认值。建议使用如下结构化确认：\n\n1. 让用户可自定义以下字段：\n - 应用名称\n - 应用描述\n - 机器人图标图片链接或本地路径\n - 机器人消息预览图链接或本地路径\n\n2. 明确告知图片规范（显著提示）：\n - 机器人图标：仅支持 JPG/PNG，`240*240px` 以上，`1:1`，`2MB` 以内，无圆角。\n - 机器人消息预览图：格式 `png/jpeg/jpg`，不超过 `2MB`。\n\n3. 明确告知默认值（用户不指定时自动采用）：\n - 应用名称：`CoPaw`\n - 应用描述：`Your personal assistant`\n - 机器人图标：`https://img.alicdn.com/imgextra/i4/O1CN01M0iyHF1FVNzM9qjC0_!!6000000000492-2-tps-254-254.png`\n - 机器人消息预览图：`https://img.alicdn.com/imgextra/i4/O1CN01M0iyHF1FVNzM9qjC0_!!6000000000492-2-tps-254-254.png`\n\n4. 若用户未给任何自定义值，必须先明确回复：\n - “将全部采用默认设置（CoPaw / Your personal assistant / 默认图片）后继续执行。”\n\n## 图片上传策略（link/path 都支持）\n\n1. 若用户提供本地路径，直接用于上传。\n2. 若用户提供图片 link，先下载到本地临时文件，再执行上传。\n3. 上传动作顺序必须是：\n - 先点击页面上传入口（触发 chooser）\n - 再调用 `file_upload` 传入本地路径数组（`paths_json`）\n4. 若上传报错且判断为图片规格不符合（尺寸、比例、大小、格式）：\n - 立即暂停自动化\n - 明确让用户手动上传符合规范的图片\n - 用户确认“已上传/继续”后，从当前步骤继续后续流程\n\n### 上传动作实战经验\n\n1. `file_upload` 的 `paths_json` 必须是“JSON 字符串数组”，注意转义：\n\n```json\n{\n \"action\": \"file_upload\",\n \"paths_json\": \"[\\\"xxx.png\\\"]\",\n \"frame_selector\": \"iframe[src*=\\\"/fe/app?isHideOuterFrame=true\\\"]\"\n}\n```\n\n2. 若页面在 iframe 内，建议优先带上 `frame_selector`，否则可能出现找不到上传控件或 chooser 未触发。\n\n3. 上传前必须先点击上传入口；若直接 `file_upload` 会报：\n - `No chooser. Click upload then file_upload.`\n\n4. 机器人图标区域的常见结构特征可用于定位（示例）：\n - `text: \"* 机器人图标\"`\n - `button: \"使用应用图标\"`\n - `button: \"avatar\"`（通常内部有 `img \"avatar\"`）\n\n5. 当 snapshot 中同时出现“使用应用图标”和“avatar”时，优先点击 `avatar` 按钮触发上传，再执行 `file_upload`。\n\n## 自动化流程\n\n### 步骤 1：打开钉钉开发者后台\n\n1. 可视模式启动浏览器（`headed: true`）\n2. 打开 `https://open-dev.dingtalk.com/`\n3. 调用 `snapshot` 判断是否需要登录\n\n若需要登录，使用如下话术暂停：\n\n> 检测到需要登录钉钉开发者后台。我已暂停自动操作，请先在弹出的浏览器中完成登录。完成后回复“继续”，我再从当前页面接着执行。\n\n### 步骤 2：创建企业内部应用\n\n用户确认登录后继续：\n\n1. 进入创建路径：\n - 应用开发 -> 企业内部应用 -> 钉钉应用 -> 创建应用\n2. 填写应用信息（优先使用用户自定义，否则使用默认值）：\n - 应用名称：默认 `CoPaw`\n - 应用描述：默认 `Your personal assistant`\n3. 保存并创建应用\n\n若页面文案或结构与预期不一致，重新 `snapshot`，按可见文本语义重新定位元素。\n\n### 步骤 3：添加机器人能力并发布\n\n1. 点击**应用能力**中的**添加应用能力**，找到**机器人**并添加\n2. 将**机器人配置**右侧的switch按钮切换为打开\n3. 填写**机器人名称**，**机器人简介**和**机器人描述**\n4. 上传**机器人图标**（用户自定义或默认图）：\n - 点击机器人图标下面的图片\n - 默认图链接：`https://img.alicdn.com/imgextra/i4/O1CN01M0iyHF1FVNzM9qjC0_!!6000000000492-2-tps-254-254.png`\n - 若为 link，先下载到本地再上传\n - 若提示图片不合规，暂停并让用户手动上传合规图片后继续\n5. 上传**机器人消息预览图**（用户自定义或默认图）：\n - 点击机器人消息预览图下面的图片\n - 默认图链接：`https://img.alicdn.com/imgextra/i4/O1CN01M0iyHF1FVNzM9qjC0_!!6000000000492-2-tps-254-254.png`\n - 若为 link，先下载到本地再上传\n - 若提示图片不合规，暂停并让用户手动上传合规图片后继续\n6. 确认消息接收模式设置为 `Stream 模式`\n7. 选择**发布**，此时会有进一步弹出的确认页面，选择发布。注意：**一定要发布机器人**之后再进行下一步\n\n### 步骤 4：创建版本并发布\n\n1. 打开 `应用发布 -> 版本管理与发布`\n2. 创建新版本（每次配置变更后都要创建）\n3. 填写版本描述，应用可见范围选择全部员工\n4. 按页面提示完成发布，此时会有新的弹窗出现，选择确认发布\n5. 只有看到发布成功状态，才可继续执行后续步骤/给用户“已生效”结论\n\n### 步骤 5：获取凭证\n\n1. 打开 `基础信息 -> 凭证与基础信息`\n2. 告知用户`Client ID`（AppKey）和`Client Secret`（AppSecret）在该页面上。不主动进行修改，引导用户自行绑定\n\n## CoPaw 绑定方式\n\n拿到凭证后，引导用户选择以下任一方式：\n\n1. 控制台前端配置：\n - CoPaw console 中进入 `控制 -> 频道 -> DingTalk`\n - 填入 `Client ID` 与 `Client Secret`\n\n2. 配置文件方式：\n\n```json\n\"dingtalk\": {\n \"enabled\": true,\n \"bot_prefix\": \"[BOT]\",\n \"client_id\": \"你的 Client ID\",\n \"client_secret\": \"你的 Client Secret\"\n}\n```\n\n路径：`~/.copaw/config.json`，位于 `channels.dingtalk` 下。\n\n### 凭证交付要求（强制）\n\n1. agent 只负责引导用户进入凭证页、获取并展示 `Client ID` 与真实 `Client Secret`。\n2. agent 不主动改 `console` 配置、不主动改 `~/.copaw/config.json`。\n3. 必须提示用户按以下两种方式之一手动填写：\n - 控制台前端：`控制 -> 频道 -> DingTalk`\n - 配置文件：编辑 `~/.copaw/config.json` 的 `channels.dingtalk` 字段\n\n## Browser 工具调用模式\n\n默认按以下顺序执行：\n\n1. `start` with `headed: true`\n2. `open`\n3. `snapshot`\n4. `click` / `type` / `select_option` / `press_key` as needed\n5. frequent `snapshot` after page transitions\n6. `stop` when done\n\n## 稳定性与恢复策略\n\n- 优先使用最新 `snapshot` 的 `ref`；仅在必要时使用 `selector`。\n- 每次关键点击或跳转后，使用短等待（`wait_for`）并立即重新 `snapshot`。\n- 若中途会话失效或要求重新登录，必须再次暂停，待用户登录后从当前步骤继续。\n- 若因租户权限、管理员审批等阻塞自动化，明确说明卡点，并请用户手动完成该步骤后再续跑。" }, { "path": "src/copaw/agents/skills/docx/LICENSE.txt", "content": "© 2025 Anthropic, PBC. All rights reserved.\n\nLICENSE: Use of these materials (including all code, prompts, assets, files,\nand other components of this Skill) is governed by your agreement with\nAnthropic regarding use of Anthropic's services. If no separate agreement\nexists, use is governed by Anthropic's Consumer Terms of Service or\nCommercial Terms of Service, as applicable:\nhttps://www.anthropic.com/legal/consumer-terms\nhttps://www.anthropic.com/legal/commercial-terms\nYour applicable agreement is referred to as the \"Agreement.\" \"Services\" are\nas defined in the Agreement.\n\nADDITIONAL RESTRICTIONS: Notwithstanding anything in the Agreement to the\ncontrary, users may not:\n\n- Extract these materials from the Services or retain copies of these\n materials outside the Services\n- Reproduce or copy these materials, except for temporary copies created\n automatically during authorized use of the Services\n- Create derivative works based on these materials\n- Distribute, sublicense, or transfer these materials to any third party\n- Make, offer to sell, sell, or import any inventions embodied in these\n materials\n- Reverse engineer, decompile, or disassemble these materials\n\nThe receipt, viewing, or possession of these materials does not convey or\nimply any license or right beyond those expressly granted above.\n\nAnthropic retains all right, title, and interest in these materials,\nincluding all copyrights, patents, and other intellectual property rights.\n" }, { "path": "src/copaw/agents/skills/docx/SKILL.md", "content": "---\nname: docx\ndescription: \"Use this skill whenever the user wants to create, read, edit, or manipulate Word documents (.docx files). Triggers include: any mention of \\\"Word doc\\\", \\\"word document\\\", \\\".docx\\\", or requests to produce professional documents with formatting like tables of contents, headings, page numbers, or letterheads. Also use when extracting or reorganizing content from .docx files, inserting or replacing images in documents, performing find-and-replace in Word files, working with tracked changes or comments, or converting content into a polished Word document. If the user asks for a \\\"report\\\", \\\"memo\\\", \\\"letter\\\", \\\"template\\\", or similar deliverable as a Word or .docx file, use this skill. Do NOT use for PDFs, spreadsheets, Google Docs, or general coding tasks unrelated to document generation.\"\nlicense: Proprietary. LICENSE.txt has complete terms\nmetadata: { \"builtin_skill_version\": \"1.0\" }\n---\n\n> **Important:** All `scripts/` paths are relative to this skill directory.\n> Run with: `cd {this_skill_dir} && python scripts/...`\n> Or use the `cwd` parameter of `execute_shell_command`.\n\n# DOCX creation, editing, and analysis\n\n## Prerequisites\n\n- **docx** (`npm install -g docx`): new document creation\n- **LibreOffice** (`soffice`): `.doc` -> `.docx` conversion, tracked-changes acceptance, and PDF export\n- **pandoc**: text extraction\n- **pdftoppm** (poppler-utils): document-to-image workflows\n- If `pdftoppm` is unavailable, a Python fallback path may use `pdf2image`.\n- On Windows, dependencies must be installed and available in `PATH`; if missing, report the dependency issue and stop (do not keep retrying).\n\n## Overview\n\nA .docx file is a ZIP archive containing XML files.\n\n## Quick Reference\n\n| Task | Approach |\n|------|----------|\n| Read/analyze content | `pandoc` or unpack for raw XML |\n| Create new document | Use `docx-js` - see Creating New Documents below |\n| Edit existing document | Unpack → edit XML → repack - see Editing Existing Documents below |\n\n### Converting .doc to .docx\n\nLegacy `.doc` files must be converted before editing:\n\n```bash\npython scripts/office/soffice.py --headless --convert-to docx document.doc\n```\n\n### Reading Content\n\n```bash\n# Text extraction with tracked changes\npandoc --track-changes=all document.docx -o output.md\n\n# Raw XML access\npython scripts/office/unpack.py document.docx unpacked/\n```\n\n### Converting to Images\n\n```bash\npython scripts/office/soffice.py --headless --convert-to pdf document.docx\npdftoppm -jpeg -r 150 document.pdf page\n```\n\n### Accepting Tracked Changes\n\nTo produce a clean document with all tracked changes accepted (requires LibreOffice):\n\n```bash\npython scripts/accept_changes.py input.docx output.docx\n```\n\n---\n\n## Creating New Documents\n\nGenerate .docx files with JavaScript, then validate. Install: `npm install -g docx`\n\n### Setup\n```javascript\nconst { Document, Packer, Paragraph, TextRun, Table, TableRow, TableCell, ImageRun,\n Header, Footer, AlignmentType, PageOrientation, LevelFormat, ExternalHyperlink,\n TableOfContents, HeadingLevel, BorderStyle, WidthType, ShadingType,\n VerticalAlign, PageNumber, PageBreak } = require('docx');\n\nconst doc = new Document({ sections: [{ children: [/* content */] }] });\nPacker.toBuffer(doc).then(buffer => fs.writeFileSync(\"doc.docx\", buffer));\n```\n\n### Validation\nAfter creating the file, validate it. If validation fails, unpack, fix the XML, and repack.\n```bash\npython scripts/office/validate.py doc.docx\n```\n\n### Page Size\n\n```javascript\n// CRITICAL: docx-js defaults to A4, not US Letter\n// Always set page size explicitly for consistent results\nsections: [{\n properties: {\n page: {\n size: {\n width: 12240, // 8.5 inches in DXA\n height: 15840 // 11 inches in DXA\n },\n margin: { top: 1440, right: 1440, bottom: 1440, left: 1440 } // 1 inch margins\n }\n },\n children: [/* content */]\n}]\n```\n\n**Common page sizes (DXA units, 1440 DXA = 1 inch):**\n\n| Paper | Width | Height | Content Width (1\" margins) |\n|-------|-------|--------|---------------------------|\n| US Letter | 12,240 | 15,840 | 9,360 |\n| A4 (default) | 11,906 | 16,838 | 9,026 |\n\n**Landscape orientation:** docx-js swaps width/height internally, so pass portrait dimensions and let it handle the swap:\n```javascript\nsize: {\n width: 12240, // Pass SHORT edge as width\n height: 15840, // Pass LONG edge as height\n orientation: PageOrientation.LANDSCAPE // docx-js swaps them in the XML\n},\n// Content width = 15840 - left margin - right margin (uses the long edge)\n```\n\n### Styles (Override Built-in Headings)\n\nUse Arial as the default font (universally supported). Keep titles black for readability.\n\n```javascript\nconst doc = new Document({\n styles: {\n default: { document: { run: { font: \"Arial\", size: 24 } } }, // 12pt default\n paragraphStyles: [\n // IMPORTANT: Use exact IDs to override built-in styles\n { id: \"Heading1\", name: \"Heading 1\", basedOn: \"Normal\", next: \"Normal\", quickFormat: true,\n run: { size: 32, bold: true, font: \"Arial\" },\n paragraph: { spacing: { before: 240, after: 240 }, outlineLevel: 0 } }, // outlineLevel required for TOC\n { id: \"Heading2\", name: \"Heading 2\", basedOn: \"Normal\", next: \"Normal\", quickFormat: true,\n run: { size: 28, bold: true, font: \"Arial\" },\n paragraph: { spacing: { before: 180, after: 180 }, outlineLevel: 1 } },\n ]\n },\n sections: [{\n children: [\n new Paragraph({ heading: HeadingLevel.HEADING_1, children: [new TextRun(\"Title\")] }),\n ]\n }]\n});\n```\n\n### Lists (NEVER use unicode bullets)\n\n```javascript\n// ❌ WRONG - never manually insert bullet characters\nnew Paragraph({ children: [new TextRun(\"• Item\")] }) // BAD\nnew Paragraph({ children: [new TextRun(\"\\u2022 Item\")] }) // BAD\n\n// ✅ CORRECT - use numbering config with LevelFormat.BULLET\nconst doc = new Document({\n numbering: {\n config: [\n { reference: \"bullets\",\n levels: [{ level: 0, format: LevelFormat.BULLET, text: \"•\", alignment: AlignmentType.LEFT,\n style: { paragraph: { indent: { left: 720, hanging: 360 } } } }] },\n { reference: \"numbers\",\n levels: [{ level: 0, format: LevelFormat.DECIMAL, text: \"%1.\", alignment: AlignmentType.LEFT,\n style: { paragraph: { indent: { left: 720, hanging: 360 } } } }] },\n ]\n },\n sections: [{\n children: [\n new Paragraph({ numbering: { reference: \"bullets\", level: 0 },\n children: [new TextRun(\"Bullet item\")] }),\n new Paragraph({ numbering: { reference: \"numbers\", level: 0 },\n children: [new TextRun(\"Numbered item\")] }),\n ]\n }]\n});\n\n// ⚠️ Each reference creates INDEPENDENT numbering\n// Same reference = continues (1,2,3 then 4,5,6)\n// Different reference = restarts (1,2,3 then 1,2,3)\n```\n\n### Tables\n\n**CRITICAL: Tables need dual widths** - set both `columnWidths` on the table AND `width` on each cell. Without both, tables render incorrectly on some platforms.\n\n```javascript\n// CRITICAL: Always set table width for consistent rendering\n// CRITICAL: Use ShadingType.CLEAR (not SOLID) to prevent black backgrounds\nconst border = { style: BorderStyle.SINGLE, size: 1, color: \"CCCCCC\" };\nconst borders = { top: border, bottom: border, left: border, right: border };\n\nnew Table({\n width: { size: 9360, type: WidthType.DXA }, // Always use DXA (percentages break in Google Docs)\n columnWidths: [4680, 4680], // Must sum to table width (DXA: 1440 = 1 inch)\n rows: [\n new TableRow({\n children: [\n new TableCell({\n borders,\n width: { size: 4680, type: WidthType.DXA }, // Also set on each cell\n shading: { fill: \"D5E8F0\", type: ShadingType.CLEAR }, // CLEAR not SOLID\n margins: { top: 80, bottom: 80, left: 120, right: 120 }, // Cell padding (internal, not added to width)\n children: [new Paragraph({ children: [new TextRun(\"Cell\")] })]\n })\n ]\n })\n ]\n})\n```\n\n**Table width calculation:**\n\nAlways use `WidthType.DXA` — `WidthType.PERCENTAGE` breaks in Google Docs.\n\n```javascript\n// Table width = sum of columnWidths = content width\n// US Letter with 1\" margins: 12240 - 2880 = 9360 DXA\nwidth: { size: 9360, type: WidthType.DXA },\ncolumnWidths: [7000, 2360] // Must sum to table width\n```\n\n**Width rules:**\n- **Always use `WidthType.DXA`** — never `WidthType.PERCENTAGE` (incompatible with Google Docs)\n- Table width must equal the sum of `columnWidths`\n- Cell `width` must match corresponding `columnWidth`\n- Cell `margins` are internal padding - they reduce content area, not add to cell width\n- For full-width tables: use content width (page width minus left and right margins)\n\n### Images\n\n```javascript\n// CRITICAL: type parameter is REQUIRED\nnew Paragraph({\n children: [new ImageRun({\n type: \"png\", // Required: png, jpg, jpeg, gif, bmp, svg\n data: fs.readFileSync(\"image.png\"),\n transformation: { width: 200, height: 150 },\n altText: { title: \"Title\", description: \"Desc\", name: \"Name\" } // All three required\n })]\n})\n```\n\n### Page Breaks\n\n```javascript\n// CRITICAL: PageBreak must be inside a Paragraph\nnew Paragraph({ children: [new PageBreak()] })\n\n// Or use pageBreakBefore\nnew Paragraph({ pageBreakBefore: true, children: [new TextRun(\"New page\")] })\n```\n\n### Table of Contents\n\n```javascript\n// CRITICAL: Headings must use HeadingLevel ONLY - no custom styles\nnew TableOfContents(\"Table of Contents\", { hyperlink: true, headingStyleRange: \"1-3\" })\n```\n\n### Headers/Footers\n\n```javascript\nsections: [{\n properties: {\n page: { margin: { top: 1440, right: 1440, bottom: 1440, left: 1440 } } // 1440 = 1 inch\n },\n headers: {\n default: new Header({ children: [new Paragraph({ children: [new TextRun(\"Header\")] })] })\n },\n footers: {\n default: new Footer({ children: [new Paragraph({\n children: [new TextRun(\"Page \"), new TextRun({ children: [PageNumber.CURRENT] })]\n })] })\n },\n children: [/* content */]\n}]\n```\n\n### Critical Rules for docx-js\n\n- **Set page size explicitly** - docx-js defaults to A4; use US Letter (12240 x 15840 DXA) for US documents\n- **Landscape: pass portrait dimensions** - docx-js swaps width/height internally; pass short edge as `width`, long edge as `height`, and set `orientation: PageOrientation.LANDSCAPE`\n- **Never use `\\n`** - use separate Paragraph elements\n- **Never use unicode bullets** - use `LevelFormat.BULLET` with numbering config\n- **PageBreak must be in Paragraph** - standalone creates invalid XML\n- **ImageRun requires `type`** - always specify png/jpg/etc\n- **Always set table `width` with DXA** - never use `WidthType.PERCENTAGE` (breaks in Google Docs)\n- **Tables need dual widths** - `columnWidths` array AND cell `width`, both must match\n- **Table width = sum of columnWidths** - for DXA, ensure they add up exactly\n- **Always add cell margins** - use `margins: { top: 80, bottom: 80, left: 120, right: 120 }` for readable padding\n- **Use `ShadingType.CLEAR`** - never SOLID for table shading\n- **TOC requires HeadingLevel only** - no custom styles on heading paragraphs\n- **Override built-in styles** - use exact IDs: \"Heading1\", \"Heading2\", etc.\n- **Include `outlineLevel`** - required for TOC (0 for H1, 1 for H2, etc.)\n\n---\n\n## Editing Existing Documents\n\n**Follow all 3 steps in order.**\n\n### Step 1: Unpack\n```bash\npython scripts/office/unpack.py document.docx unpacked/\n```\nExtracts XML, pretty-prints, merges adjacent runs, and converts smart quotes to XML entities (`“` etc.) so they survive editing. Use `--merge-runs false` to skip run merging.\n\n### Step 2: Edit XML\n\nEdit files in `unpacked/word/`. See XML Reference below for patterns.\n\n**Use \"Claude\" as the author** for tracked changes and comments, unless the user explicitly requests use of a different name.\n\n**Use the Edit tool directly for string replacement. Do not write Python scripts.** Scripts introduce unnecessary complexity. The Edit tool shows exactly what is being replaced.\n\n**CRITICAL: Use smart quotes for new content.** When adding text with apostrophes or quotes, use XML entities to produce smart quotes:\n```xml\n\nHere’s a quote: “Hello”\n```\n| Entity | Character |\n|--------|-----------|\n| `‘` | ‘ (left single) |\n| `’` | ’ (right single / apostrophe) |\n| `“` | “ (left double) |\n| `”` | ” (right double) |\n\n**Adding comments:** Use `comment.py` to handle boilerplate across multiple XML files (text must be pre-escaped XML):\n```bash\npython scripts/comment.py unpacked/ 0 \"Comment text with & and ’\"\npython scripts/comment.py unpacked/ 1 \"Reply text\" --parent 0 # reply to comment 0\npython scripts/comment.py unpacked/ 0 \"Text\" --author \"Custom Author\" # custom author name\n```\nThen add markers to document.xml (see Comments in XML Reference).\n\n### Step 3: Pack\n```bash\npython scripts/office/pack.py unpacked/ output.docx --original document.docx\n```\nValidates with auto-repair, condenses XML, and creates DOCX. Use `--validate false` to skip.\n\n**Auto-repair will fix:**\n- `durableId` >= 0x7FFFFFFF (regenerates valid ID)\n- Missing `xml:space=\"preserve\"` on `` with whitespace\n\n**Auto-repair won't fix:**\n- Malformed XML, invalid element nesting, missing relationships, schema violations\n\n### Common Pitfalls\n\n- **Replace entire `` elements**: When adding tracked changes, replace the whole `...` block with `......` as siblings. Don't inject tracked change tags inside a run.\n- **Preserve `` formatting**: Copy the original run's `` block into your tracked change runs to maintain bold, font size, etc.\n\n---\n\n## XML Reference\n\n### Schema Compliance\n\n- **Element order in ``**: ``, ``, ``, ``, ``, `` last\n- **Whitespace**: Add `xml:space=\"preserve\"` to `` with leading/trailing spaces\n- **RSIDs**: Must be 8-digit hex (e.g., `00AB1234`)\n\n### Tracked Changes\n\n**Insertion:**\n```xml\n\n inserted text\n\n```\n\n**Deletion:**\n```xml\n\n deleted text\n\n```\n\n**Inside ``**: Use `` instead of ``, and `` instead of ``.\n\n**Minimal edits** - only mark what changes:\n```xml\n\nThe term is \n\n 30\n\n\n 60\n\n days.\n```\n\n**Deleting entire paragraphs/list items** - when removing ALL content from a paragraph, also mark the paragraph mark as deleted so it merges with the next paragraph. Add `` inside ``:\n```xml\n\n \n ... \n \n \n \n \n \n Entire paragraph content being deleted...\n \n\n```\nWithout the `` in ``, accepting changes leaves an empty paragraph/list item.\n\n**Rejecting another author's insertion** - nest deletion inside their insertion:\n```xml\n\n \n their inserted text\n \n\n```\n\n**Restoring another author's deletion** - add insertion after (don't modify their deletion):\n```xml\n\n deleted text\n\n\n deleted text\n\n```\n\n### Comments\n\nAfter running `comment.py` (see Step 2), add markers to document.xml. For replies, use `--parent` flag and nest markers inside the parent's.\n\n**CRITICAL: `` and `` are siblings of ``, never inside ``.**\n\n```xml\n\n\n\n deleted\n\n more text\n\n\n\n\n\n \n text\n \n\n\n\n```\n\n### Images\n\n1. Add image file to `word/media/`\n2. Add relationship to `word/_rels/document.xml.rels`:\n```xml\n\n```\n3. Add content type to `[Content_Types].xml`:\n```xml\n\n```\n4. Reference in document.xml:\n```xml\n\n \n \n \n \n \n \n \n \n \n \n\n```\n" }, { "path": "src/copaw/agents/skills/docx/scripts/__init__.py", "content": "\n" }, { "path": "src/copaw/agents/skills/docx/scripts/accept_changes.py", "content": "\"\"\"Accept all tracked changes in a DOCX file using LibreOffice.\n\nRequires LibreOffice (soffice) to be installed.\n\"\"\"\n\nimport argparse\nimport logging\nimport shutil\nimport subprocess\nimport tempfile\nfrom pathlib import Path\n\nfrom office.soffice import get_soffice_cmd, get_soffice_env\n\nlogger = logging.getLogger(__name__)\n\nLIBREOFFICE_PROFILE = str(Path(tempfile.gettempdir()) / \"libreoffice_docx_profile\")\nMACRO_DIR = str(Path(LIBREOFFICE_PROFILE) / \"user\" / \"basic\" / \"Standard\")\n\nACCEPT_CHANGES_MACRO = \"\"\"\n\n\n Sub AcceptAllTrackedChanges()\n Dim document As Object\n Dim dispatcher As Object\n\n document = ThisComponent.CurrentController.Frame\n dispatcher = createUnoService(\"com.sun.star.frame.DispatchHelper\")\n\n dispatcher.executeDispatch(document, \".uno:AcceptAllTrackedChanges\", \"\", 0, Array())\n ThisComponent.store()\n ThisComponent.close(True)\n End Sub\n\"\"\"\n\n\ndef accept_changes(\n input_file: str,\n output_file: str,\n) -> tuple[None, str]:\n input_path = Path(input_file)\n output_path = Path(output_file)\n\n if not input_path.exists():\n return None, f\"Error: Input file not found: {input_file}\"\n\n if not input_path.suffix.lower() == \".docx\":\n return None, f\"Error: Input file is not a DOCX file: {input_file}\"\n\n try:\n output_path.parent.mkdir(parents=True, exist_ok=True)\n shutil.copy2(input_path, output_path)\n except Exception as e:\n return None, f\"Error: Failed to copy input file to output location: {e}\"\n\n if not _setup_libreoffice_macro():\n return None, \"Error: Failed to setup LibreOffice macro\"\n\n profile_uri = Path(LIBREOFFICE_PROFILE).as_uri()\n cmd = [\n get_soffice_cmd(),\n \"--headless\",\n f\"-env:UserInstallation={profile_uri}\",\n \"--norestore\",\n \"vnd.sun.star.script:Standard.Module1.AcceptAllTrackedChanges?language=Basic&location=application\",\n str(output_path.absolute()),\n ]\n\n try:\n result = subprocess.run(\n cmd,\n capture_output=True,\n text=True,\n timeout=30,\n check=False,\n env=get_soffice_env(),\n )\n except subprocess.TimeoutExpired:\n return (\n None,\n f\"Successfully accepted all tracked changes: {input_file} -> {output_file}\",\n )\n\n if result.returncode != 0:\n return None, f\"Error: LibreOffice failed: {result.stderr}\"\n\n return (\n None,\n f\"Successfully accepted all tracked changes: {input_file} -> {output_file}\",\n )\n\n\ndef _setup_libreoffice_macro() -> bool:\n macro_dir = Path(MACRO_DIR)\n macro_file = macro_dir / \"Module1.xba\"\n\n if macro_file.exists() and \"AcceptAllTrackedChanges\" in macro_file.read_text():\n return True\n\n if not macro_dir.exists():\n profile_uri = Path(LIBREOFFICE_PROFILE).as_uri()\n subprocess.run(\n [\n get_soffice_cmd(),\n \"--headless\",\n f\"-env:UserInstallation={profile_uri}\",\n \"--terminate_after_init\",\n ],\n capture_output=True,\n timeout=10,\n check=False,\n env=get_soffice_env(),\n )\n macro_dir.mkdir(parents=True, exist_ok=True)\n\n try:\n macro_file.write_text(ACCEPT_CHANGES_MACRO)\n return True\n except Exception as e:\n logger.warning(f\"Failed to setup LibreOffice macro: {e}\")\n return False\n\n\nif __name__ == \"__main__\":\n parser = argparse.ArgumentParser(\n description=\"Accept all tracked changes in a DOCX file\"\n )\n parser.add_argument(\"input_file\", help=\"Input DOCX file with tracked changes\")\n parser.add_argument(\n \"output_file\", help=\"Output DOCX file (clean, no tracked changes)\"\n )\n args = parser.parse_args()\n\n _, message = accept_changes(args.input_file, args.output_file)\n print(message)\n\n if \"Error\" in message:\n raise SystemExit(1)\n" }, { "path": "src/copaw/agents/skills/docx/scripts/comment.py", "content": "\"\"\"Add comments to DOCX documents.\n\nUsage:\n python comment.py unpacked/ 0 \"Comment text\"\n python comment.py unpacked/ 1 \"Reply text\" --parent 0\n\nText should be pre-escaped XML (e.g., & for &, ’ for smart quotes).\n\nAfter running, add markers to document.xml:\n \n ... commented content ...\n \n \n\"\"\"\n\nimport argparse\nimport random\nimport shutil\nimport sys\nfrom datetime import datetime, timezone\nfrom pathlib import Path\n\nimport defusedxml.minidom\n\nTEMPLATE_DIR = Path(__file__).parent / \"templates\"\nNS = {\n \"w\": \"http://schemas.openxmlformats.org/wordprocessingml/2006/main\",\n \"w14\": \"http://schemas.microsoft.com/office/word/2010/wordml\",\n \"w15\": \"http://schemas.microsoft.com/office/word/2012/wordml\",\n \"w16cid\": \"http://schemas.microsoft.com/office/word/2016/wordml/cid\",\n \"w16cex\": \"http://schemas.microsoft.com/office/word/2018/wordml/cex\",\n}\n\nCOMMENT_XML = \"\"\"\\\n\n \n \n \n \n \n \n \n \n \n \n \n {text}\n \n \n\"\"\"\n\nCOMMENT_MARKER_TEMPLATE = \"\"\"\nAdd to document.xml (markers must be direct children of w:p, never inside w:r):\n \n ...\n \n \"\"\"\n\nREPLY_MARKER_TEMPLATE = \"\"\"\nNest markers inside parent {pid}'s markers (markers must be direct children of w:p, never inside w:r):\n \n ...\n \n \n \"\"\"\n\n\ndef _generate_hex_id() -> str:\n return f\"{random.randint(0, 0x7FFFFFFE):08X}\"\n\n\nSMART_QUOTE_ENTITIES = {\n \"\\u201c\": \"“\", \n \"\\u201d\": \"”\", \n \"\\u2018\": \"‘\", \n \"\\u2019\": \"’\", \n}\n\n\ndef _encode_smart_quotes(text: str) -> str:\n for char, entity in SMART_QUOTE_ENTITIES.items():\n text = text.replace(char, entity)\n return text\n\n\ndef _append_xml(xml_path: Path, root_tag: str, content: str) -> None:\n dom = defusedxml.minidom.parseString(xml_path.read_text(encoding=\"utf-8\"))\n root = dom.getElementsByTagName(root_tag)[0]\n ns_attrs = \" \".join(f'xmlns:{k}=\"{v}\"' for k, v in NS.items())\n wrapper_dom = defusedxml.minidom.parseString(f\"{content}\")\n for child in wrapper_dom.documentElement.childNodes: \n if child.nodeType == child.ELEMENT_NODE:\n root.appendChild(dom.importNode(child, True))\n output = _encode_smart_quotes(dom.toxml(encoding=\"UTF-8\").decode(\"utf-8\"))\n xml_path.write_text(output, encoding=\"utf-8\")\n\n\ndef _find_para_id(comments_path: Path, comment_id: int) -> str | None:\n dom = defusedxml.minidom.parseString(comments_path.read_text(encoding=\"utf-8\"))\n for c in dom.getElementsByTagName(\"w:comment\"):\n if c.getAttribute(\"w:id\") == str(comment_id):\n for p in c.getElementsByTagName(\"w:p\"):\n if pid := p.getAttribute(\"w14:paraId\"):\n return pid\n return None\n\n\ndef _get_next_rid(rels_path: Path) -> int:\n dom = defusedxml.minidom.parseString(rels_path.read_text(encoding=\"utf-8\"))\n max_rid = 0\n for rel in dom.getElementsByTagName(\"Relationship\"):\n rid = rel.getAttribute(\"Id\")\n if rid and rid.startswith(\"rId\"):\n try:\n max_rid = max(max_rid, int(rid[3:]))\n except ValueError:\n pass\n return max_rid + 1\n\n\ndef _has_relationship(rels_path: Path, target: str) -> bool:\n dom = defusedxml.minidom.parseString(rels_path.read_text(encoding=\"utf-8\"))\n for rel in dom.getElementsByTagName(\"Relationship\"):\n if rel.getAttribute(\"Target\") == target:\n return True\n return False\n\n\ndef _has_content_type(ct_path: Path, part_name: str) -> bool:\n dom = defusedxml.minidom.parseString(ct_path.read_text(encoding=\"utf-8\"))\n for override in dom.getElementsByTagName(\"Override\"):\n if override.getAttribute(\"PartName\") == part_name:\n return True\n return False\n\n\ndef _ensure_comment_relationships(unpacked_dir: Path) -> None:\n rels_path = unpacked_dir / \"word\" / \"_rels\" / \"document.xml.rels\"\n if not rels_path.exists():\n return\n\n if _has_relationship(rels_path, \"comments.xml\"):\n return \n\n dom = defusedxml.minidom.parseString(rels_path.read_text(encoding=\"utf-8\"))\n root = dom.documentElement\n next_rid = _get_next_rid(rels_path)\n\n rels = [\n (\n \"http://schemas.openxmlformats.org/officeDocument/2006/relationships/comments\",\n \"comments.xml\",\n ),\n (\n \"http://schemas.microsoft.com/office/2011/relationships/commentsExtended\",\n \"commentsExtended.xml\",\n ),\n (\n \"http://schemas.microsoft.com/office/2016/09/relationships/commentsIds\",\n \"commentsIds.xml\",\n ),\n (\n \"http://schemas.microsoft.com/office/2018/08/relationships/commentsExtensible\",\n \"commentsExtensible.xml\",\n ),\n ]\n\n for rel_type, target in rels:\n rel = dom.createElement(\"Relationship\")\n rel.setAttribute(\"Id\", f\"rId{next_rid}\")\n rel.setAttribute(\"Type\", rel_type)\n rel.setAttribute(\"Target\", target)\n root.appendChild(rel) \n next_rid += 1\n\n rels_path.write_bytes(dom.toxml(encoding=\"UTF-8\"))\n\n\ndef _ensure_comment_content_types(unpacked_dir: Path) -> None:\n ct_path = unpacked_dir / \"[Content_Types].xml\"\n if not ct_path.exists():\n return\n\n if _has_content_type(ct_path, \"/word/comments.xml\"):\n return \n\n dom = defusedxml.minidom.parseString(ct_path.read_text(encoding=\"utf-8\"))\n root = dom.documentElement\n\n overrides = [\n (\n \"/word/comments.xml\",\n \"application/vnd.openxmlformats-officedocument.wordprocessingml.comments+xml\",\n ),\n (\n \"/word/commentsExtended.xml\",\n \"application/vnd.openxmlformats-officedocument.wordprocessingml.commentsExtended+xml\",\n ),\n (\n \"/word/commentsIds.xml\",\n \"application/vnd.openxmlformats-officedocument.wordprocessingml.commentsIds+xml\",\n ),\n (\n \"/word/commentsExtensible.xml\",\n \"application/vnd.openxmlformats-officedocument.wordprocessingml.commentsExtensible+xml\",\n ),\n ]\n\n for part_name, content_type in overrides:\n override = dom.createElement(\"Override\")\n override.setAttribute(\"PartName\", part_name)\n override.setAttribute(\"ContentType\", content_type)\n root.appendChild(override) \n\n ct_path.write_bytes(dom.toxml(encoding=\"UTF-8\"))\n\n\ndef add_comment(\n unpacked_dir: str,\n comment_id: int,\n text: str,\n author: str = \"Claude\",\n initials: str = \"C\",\n parent_id: int | None = None,\n) -> tuple[str, str]:\n word = Path(unpacked_dir) / \"word\"\n if not word.exists():\n return \"\", f\"Error: {word} not found\"\n\n para_id, durable_id = _generate_hex_id(), _generate_hex_id()\n ts = datetime.now(timezone.utc).strftime(\"%Y-%m-%dT%H:%M:%SZ\")\n\n comments = word / \"comments.xml\"\n first_comment = not comments.exists()\n if first_comment:\n shutil.copy(TEMPLATE_DIR / \"comments.xml\", comments)\n _ensure_comment_relationships(Path(unpacked_dir))\n _ensure_comment_content_types(Path(unpacked_dir))\n _append_xml(\n comments,\n \"w:comments\",\n COMMENT_XML.format(\n id=comment_id,\n author=author,\n date=ts,\n initials=initials,\n para_id=para_id,\n text=text, \n ),\n )\n\n ext = word / \"commentsExtended.xml\"\n if not ext.exists():\n shutil.copy(TEMPLATE_DIR / \"commentsExtended.xml\", ext)\n if parent_id is not None:\n parent_para = _find_para_id(comments, parent_id)\n if not parent_para:\n return \"\", f\"Error: Parent comment {parent_id} not found\"\n _append_xml(\n ext,\n \"w15:commentsEx\",\n f'',\n )\n else:\n _append_xml(\n ext,\n \"w15:commentsEx\",\n f'',\n )\n\n ids = word / \"commentsIds.xml\"\n if not ids.exists():\n shutil.copy(TEMPLATE_DIR / \"commentsIds.xml\", ids)\n _append_xml(\n ids,\n \"w16cid:commentsIds\",\n f'',\n )\n\n extensible = word / \"commentsExtensible.xml\"\n if not extensible.exists():\n shutil.copy(TEMPLATE_DIR / \"commentsExtensible.xml\", extensible)\n _append_xml(\n extensible,\n \"w16cex:commentsExtensible\",\n f'',\n )\n\n action = \"reply\" if parent_id is not None else \"comment\"\n return para_id, f\"Added {action} {comment_id} (para_id={para_id})\"\n\n\nif __name__ == \"__main__\":\n p = argparse.ArgumentParser(description=\"Add comments to DOCX documents\")\n p.add_argument(\"unpacked_dir\", help=\"Unpacked DOCX directory\")\n p.add_argument(\"comment_id\", type=int, help=\"Comment ID (must be unique)\")\n p.add_argument(\"text\", help=\"Comment text\")\n p.add_argument(\"--author\", default=\"Claude\", help=\"Author name\")\n p.add_argument(\"--initials\", default=\"C\", help=\"Author initials\")\n p.add_argument(\"--parent\", type=int, help=\"Parent comment ID (for replies)\")\n args = p.parse_args()\n\n para_id, msg = add_comment(\n args.unpacked_dir,\n args.comment_id,\n args.text,\n args.author,\n args.initials,\n args.parent,\n )\n print(msg)\n if \"Error\" in msg:\n sys.exit(1)\n cid = args.comment_id\n if args.parent is not None:\n print(REPLY_MARKER_TEMPLATE.format(pid=args.parent, cid=cid))\n else:\n print(COMMENT_MARKER_TEMPLATE.format(cid=cid))\n" }, { "path": "src/copaw/agents/skills/docx/scripts/office/helpers/__init__.py", "content": "" }, { "path": "src/copaw/agents/skills/docx/scripts/office/helpers/merge_runs.py", "content": "\"\"\"Merge adjacent runs with identical formatting in DOCX.\n\nMerges adjacent elements that have identical properties.\nWorks on runs in paragraphs and inside tracked changes (, ).\n\nAlso:\n- Removes rsid attributes from runs (revision metadata that doesn't affect rendering)\n- Removes proofErr elements (spell/grammar markers that block merging)\n\"\"\"\n\nfrom pathlib import Path\n\nimport defusedxml.minidom\n\n\ndef merge_runs(input_dir: str) -> tuple[int, str]:\n doc_xml = Path(input_dir) / \"word\" / \"document.xml\"\n\n if not doc_xml.exists():\n return 0, f\"Error: {doc_xml} not found\"\n\n try:\n dom = defusedxml.minidom.parseString(doc_xml.read_text(encoding=\"utf-8\"))\n root = dom.documentElement\n\n _remove_elements(root, \"proofErr\")\n _strip_run_rsid_attrs(root)\n\n containers = {run.parentNode for run in _find_elements(root, \"r\")}\n\n merge_count = 0\n for container in containers:\n merge_count += _merge_runs_in(container)\n\n doc_xml.write_bytes(dom.toxml(encoding=\"UTF-8\"))\n return merge_count, f\"Merged {merge_count} runs\"\n\n except Exception as e:\n return 0, f\"Error: {e}\"\n\n\n\n\ndef _find_elements(root, tag: str) -> list:\n results = []\n\n def traverse(node):\n if node.nodeType == node.ELEMENT_NODE:\n name = node.localName or node.tagName\n if name == tag or name.endswith(f\":{tag}\"):\n results.append(node)\n for child in node.childNodes:\n traverse(child)\n\n traverse(root)\n return results\n\n\ndef _get_child(parent, tag: str):\n for child in parent.childNodes:\n if child.nodeType == child.ELEMENT_NODE:\n name = child.localName or child.tagName\n if name == tag or name.endswith(f\":{tag}\"):\n return child\n return None\n\n\ndef _get_children(parent, tag: str) -> list:\n results = []\n for child in parent.childNodes:\n if child.nodeType == child.ELEMENT_NODE:\n name = child.localName or child.tagName\n if name == tag or name.endswith(f\":{tag}\"):\n results.append(child)\n return results\n\n\ndef _is_adjacent(elem1, elem2) -> bool:\n node = elem1.nextSibling\n while node:\n if node == elem2:\n return True\n if node.nodeType == node.ELEMENT_NODE:\n return False\n if node.nodeType == node.TEXT_NODE and node.data.strip():\n return False\n node = node.nextSibling\n return False\n\n\n\n\ndef _remove_elements(root, tag: str):\n for elem in _find_elements(root, tag):\n if elem.parentNode:\n elem.parentNode.removeChild(elem)\n\n\ndef _strip_run_rsid_attrs(root):\n for run in _find_elements(root, \"r\"):\n for attr in list(run.attributes.values()):\n if \"rsid\" in attr.name.lower():\n run.removeAttribute(attr.name)\n\n\n\n\ndef _merge_runs_in(container) -> int:\n merge_count = 0\n run = _first_child_run(container)\n\n while run:\n while True:\n next_elem = _next_element_sibling(run)\n if next_elem and _is_run(next_elem) and _can_merge(run, next_elem):\n _merge_run_content(run, next_elem)\n container.removeChild(next_elem)\n merge_count += 1\n else:\n break\n\n _consolidate_text(run)\n run = _next_sibling_run(run)\n\n return merge_count\n\n\ndef _first_child_run(container):\n for child in container.childNodes:\n if child.nodeType == child.ELEMENT_NODE and _is_run(child):\n return child\n return None\n\n\ndef _next_element_sibling(node):\n sibling = node.nextSibling\n while sibling:\n if sibling.nodeType == sibling.ELEMENT_NODE:\n return sibling\n sibling = sibling.nextSibling\n return None\n\n\ndef _next_sibling_run(node):\n sibling = node.nextSibling\n while sibling:\n if sibling.nodeType == sibling.ELEMENT_NODE:\n if _is_run(sibling):\n return sibling\n sibling = sibling.nextSibling\n return None\n\n\ndef _is_run(node) -> bool:\n name = node.localName or node.tagName\n return name == \"r\" or name.endswith(\":r\")\n\n\ndef _can_merge(run1, run2) -> bool:\n rpr1 = _get_child(run1, \"rPr\")\n rpr2 = _get_child(run2, \"rPr\")\n\n if (rpr1 is None) != (rpr2 is None):\n return False\n if rpr1 is None:\n return True\n return rpr1.toxml() == rpr2.toxml() \n\n\ndef _merge_run_content(target, source):\n for child in list(source.childNodes):\n if child.nodeType == child.ELEMENT_NODE:\n name = child.localName or child.tagName\n if name != \"rPr\" and not name.endswith(\":rPr\"):\n target.appendChild(child)\n\n\ndef _consolidate_text(run):\n t_elements = _get_children(run, \"t\")\n\n for i in range(len(t_elements) - 1, 0, -1):\n curr, prev = t_elements[i], t_elements[i - 1]\n\n if _is_adjacent(prev, curr):\n prev_text = prev.firstChild.data if prev.firstChild else \"\"\n curr_text = curr.firstChild.data if curr.firstChild else \"\"\n merged = prev_text + curr_text\n\n if prev.firstChild:\n prev.firstChild.data = merged\n else:\n prev.appendChild(run.ownerDocument.createTextNode(merged))\n\n if merged.startswith(\" \") or merged.endswith(\" \"):\n prev.setAttribute(\"xml:space\", \"preserve\")\n elif prev.hasAttribute(\"xml:space\"):\n prev.removeAttribute(\"xml:space\")\n\n run.removeChild(curr)\n" }, { "path": "src/copaw/agents/skills/docx/scripts/office/helpers/simplify_redlines.py", "content": "\"\"\"Simplify tracked changes by merging adjacent w:ins or w:del elements.\n\nMerges adjacent elements from the same author into a single element.\nSame for elements. This makes heavily-redlined documents easier to\nwork with by reducing the number of tracked change wrappers.\n\nRules:\n- Only merges w:ins with w:ins, w:del with w:del (same element type)\n- Only merges if same author (ignores timestamp differences)\n- Only merges if truly adjacent (only whitespace between them)\n\"\"\"\n\nimport xml.etree.ElementTree as ET\nimport zipfile\nfrom pathlib import Path\n\nimport defusedxml.minidom\n\nWORD_NS = \"http://schemas.openxmlformats.org/wordprocessingml/2006/main\"\n\n\ndef simplify_redlines(input_dir: str) -> tuple[int, str]:\n doc_xml = Path(input_dir) / \"word\" / \"document.xml\"\n\n if not doc_xml.exists():\n return 0, f\"Error: {doc_xml} not found\"\n\n try:\n dom = defusedxml.minidom.parseString(doc_xml.read_text(encoding=\"utf-8\"))\n root = dom.documentElement\n\n merge_count = 0\n\n containers = _find_elements(root, \"p\") + _find_elements(root, \"tc\")\n\n for container in containers:\n merge_count += _merge_tracked_changes_in(container, \"ins\")\n merge_count += _merge_tracked_changes_in(container, \"del\")\n\n doc_xml.write_bytes(dom.toxml(encoding=\"UTF-8\"))\n return merge_count, f\"Simplified {merge_count} tracked changes\"\n\n except Exception as e:\n return 0, f\"Error: {e}\"\n\n\ndef _merge_tracked_changes_in(container, tag: str) -> int:\n merge_count = 0\n\n tracked = [\n child\n for child in container.childNodes\n if child.nodeType == child.ELEMENT_NODE and _is_element(child, tag)\n ]\n\n if len(tracked) < 2:\n return 0\n\n i = 0\n while i < len(tracked) - 1:\n curr = tracked[i]\n next_elem = tracked[i + 1]\n\n if _can_merge_tracked(curr, next_elem):\n _merge_tracked_content(curr, next_elem)\n container.removeChild(next_elem)\n tracked.pop(i + 1)\n merge_count += 1\n else:\n i += 1\n\n return merge_count\n\n\ndef _is_element(node, tag: str) -> bool:\n name = node.localName or node.tagName\n return name == tag or name.endswith(f\":{tag}\")\n\n\ndef _get_author(elem) -> str:\n author = elem.getAttribute(\"w:author\")\n if not author:\n for attr in elem.attributes.values():\n if attr.localName == \"author\" or attr.name.endswith(\":author\"):\n return attr.value\n return author\n\n\ndef _can_merge_tracked(elem1, elem2) -> bool:\n if _get_author(elem1) != _get_author(elem2):\n return False\n\n node = elem1.nextSibling\n while node and node != elem2:\n if node.nodeType == node.ELEMENT_NODE:\n return False\n if node.nodeType == node.TEXT_NODE and node.data.strip():\n return False\n node = node.nextSibling\n\n return True\n\n\ndef _merge_tracked_content(target, source):\n while source.firstChild:\n child = source.firstChild\n source.removeChild(child)\n target.appendChild(child)\n\n\ndef _find_elements(root, tag: str) -> list:\n results = []\n\n def traverse(node):\n if node.nodeType == node.ELEMENT_NODE:\n name = node.localName or node.tagName\n if name == tag or name.endswith(f\":{tag}\"):\n results.append(node)\n for child in node.childNodes:\n traverse(child)\n\n traverse(root)\n return results\n\n\ndef get_tracked_change_authors(doc_xml_path: Path) -> dict[str, int]:\n if not doc_xml_path.exists():\n return {}\n\n try:\n tree = ET.parse(doc_xml_path)\n root = tree.getroot()\n except ET.ParseError:\n return {}\n\n namespaces = {\"w\": WORD_NS}\n author_attr = f\"{{{WORD_NS}}}author\"\n\n authors: dict[str, int] = {}\n for tag in [\"ins\", \"del\"]:\n for elem in root.findall(f\".//w:{tag}\", namespaces):\n author = elem.get(author_attr)\n if author:\n authors[author] = authors.get(author, 0) + 1\n\n return authors\n\n\ndef _get_authors_from_docx(docx_path: Path) -> dict[str, int]:\n try:\n with zipfile.ZipFile(docx_path, \"r\") as zf:\n if \"word/document.xml\" not in zf.namelist():\n return {}\n with zf.open(\"word/document.xml\") as f:\n tree = ET.parse(f)\n root = tree.getroot()\n\n namespaces = {\"w\": WORD_NS}\n author_attr = f\"{{{WORD_NS}}}author\"\n\n authors: dict[str, int] = {}\n for tag in [\"ins\", \"del\"]:\n for elem in root.findall(f\".//w:{tag}\", namespaces):\n author = elem.get(author_attr)\n if author:\n authors[author] = authors.get(author, 0) + 1\n return authors\n except (zipfile.BadZipFile, ET.ParseError):\n return {}\n\n\ndef infer_author(modified_dir: Path, original_docx: Path, default: str = \"Claude\") -> str:\n modified_xml = modified_dir / \"word\" / \"document.xml\"\n modified_authors = get_tracked_change_authors(modified_xml)\n\n if not modified_authors:\n return default\n\n original_authors = _get_authors_from_docx(original_docx)\n\n new_changes: dict[str, int] = {}\n for author, count in modified_authors.items():\n original_count = original_authors.get(author, 0)\n diff = count - original_count\n if diff > 0:\n new_changes[author] = diff\n\n if not new_changes:\n return default\n\n if len(new_changes) == 1:\n return next(iter(new_changes))\n\n raise ValueError(\n f\"Multiple authors added new changes: {new_changes}. \"\n \"Cannot infer which author to validate.\"\n )\n" }, { "path": "src/copaw/agents/skills/docx/scripts/office/pack.py", "content": "\"\"\"Pack a directory into a DOCX, PPTX, or XLSX file.\n\nValidates with auto-repair, condenses XML formatting, and creates the Office file.\n\nUsage:\n python pack.py [--original ] [--validate true|false]\n\nExamples:\n python pack.py unpacked/ output.docx --original input.docx\n python pack.py unpacked/ output.pptx --validate false\n\"\"\"\n\nimport argparse\nimport sys\nimport shutil\nimport tempfile\nimport zipfile\nfrom pathlib import Path\n\nimport defusedxml.minidom\n\nfrom validators import DOCXSchemaValidator, PPTXSchemaValidator, RedliningValidator\n\ndef pack(\n input_directory: str,\n output_file: str,\n original_file: str | None = None,\n validate: bool = True,\n infer_author_func=None,\n) -> tuple[None, str]:\n input_dir = Path(input_directory)\n output_path = Path(output_file)\n suffix = output_path.suffix.lower()\n\n if not input_dir.is_dir():\n return None, f\"Error: {input_dir} is not a directory\"\n\n if suffix not in {\".docx\", \".pptx\", \".xlsx\"}:\n return None, f\"Error: {output_file} must be a .docx, .pptx, or .xlsx file\"\n\n if validate and original_file:\n original_path = Path(original_file)\n if original_path.exists():\n success, output = _run_validation(\n input_dir, original_path, suffix, infer_author_func\n )\n if output:\n print(output)\n if not success:\n return None, f\"Error: Validation failed for {input_dir}\"\n\n with tempfile.TemporaryDirectory() as temp_dir:\n temp_content_dir = Path(temp_dir) / \"content\"\n shutil.copytree(input_dir, temp_content_dir)\n\n for pattern in [\"*.xml\", \"*.rels\"]:\n for xml_file in temp_content_dir.rglob(pattern):\n _condense_xml(xml_file)\n\n output_path.parent.mkdir(parents=True, exist_ok=True)\n with zipfile.ZipFile(output_path, \"w\", zipfile.ZIP_DEFLATED) as zf:\n for f in temp_content_dir.rglob(\"*\"):\n if f.is_file():\n zf.write(f, f.relative_to(temp_content_dir))\n\n return None, f\"Successfully packed {input_dir} to {output_file}\"\n\n\ndef _run_validation(\n unpacked_dir: Path,\n original_file: Path,\n suffix: str,\n infer_author_func=None,\n) -> tuple[bool, str | None]:\n output_lines = []\n validators = []\n\n if suffix == \".docx\":\n author = \"Claude\"\n if infer_author_func:\n try:\n author = infer_author_func(unpacked_dir, original_file)\n except ValueError as e:\n print(f\"Warning: {e} Using default author 'Claude'.\", file=sys.stderr)\n\n validators = [\n DOCXSchemaValidator(unpacked_dir, original_file),\n RedliningValidator(unpacked_dir, original_file, author=author),\n ]\n elif suffix == \".pptx\":\n validators = [PPTXSchemaValidator(unpacked_dir, original_file)]\n\n if not validators:\n return True, None\n\n total_repairs = sum(v.repair() for v in validators)\n if total_repairs:\n output_lines.append(f\"Auto-repaired {total_repairs} issue(s)\")\n\n success = all(v.validate() for v in validators)\n\n if success:\n output_lines.append(\"All validations PASSED!\")\n\n return success, \"\\n\".join(output_lines) if output_lines else None\n\n\ndef _condense_xml(xml_file: Path) -> None:\n try:\n with open(xml_file, encoding=\"utf-8\") as f:\n dom = defusedxml.minidom.parse(f)\n\n for element in dom.getElementsByTagName(\"*\"):\n if element.tagName.endswith(\":t\"):\n continue\n\n for child in list(element.childNodes):\n if (\n child.nodeType == child.TEXT_NODE\n and child.nodeValue\n and child.nodeValue.strip() == \"\"\n ) or child.nodeType == child.COMMENT_NODE:\n element.removeChild(child)\n\n xml_file.write_bytes(dom.toxml(encoding=\"UTF-8\"))\n except Exception as e:\n print(f\"ERROR: Failed to parse {xml_file.name}: {e}\", file=sys.stderr)\n raise\n\n\nif __name__ == \"__main__\":\n parser = argparse.ArgumentParser(\n description=\"Pack a directory into a DOCX, PPTX, or XLSX file\"\n )\n parser.add_argument(\"input_directory\", help=\"Unpacked Office document directory\")\n parser.add_argument(\"output_file\", help=\"Output Office file (.docx/.pptx/.xlsx)\")\n parser.add_argument(\n \"--original\",\n help=\"Original file for validation comparison\",\n )\n parser.add_argument(\n \"--validate\",\n type=lambda x: x.lower() == \"true\",\n default=True,\n metavar=\"true|false\",\n help=\"Run validation with auto-repair (default: true)\",\n )\n args = parser.parse_args()\n\n _, message = pack(\n args.input_directory,\n args.output_file,\n original_file=args.original,\n validate=args.validate,\n )\n print(message)\n\n if \"Error\" in message:\n sys.exit(1)\n" }, { "path": "src/copaw/agents/skills/docx/scripts/office/schemas/ISO-IEC29500-4_2016/dml-chart.xsd", "content": "\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n\n" }, { "path": "src/copaw/agents/skills/docx/scripts/office/schemas/ISO-IEC29500-4_2016/dml-chartDrawing.xsd", "content": "\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n\n" }, { "path": "src/copaw/agents/skills/docx/scripts/office/schemas/ISO-IEC29500-4_2016/dml-diagram.xsd", "content": "\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n\n" }, { "path": "src/copaw/agents/skills/docx/scripts/office/schemas/ISO-IEC29500-4_2016/dml-lockedCanvas.xsd", "content": "\n\n \n \n\n" }, { "path": "src/copaw/agents/skills/docx/scripts/office/schemas/ISO-IEC29500-4_2016/dml-main.xsd", "content": "\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n\n" }, { "path": "src/copaw/agents/skills/docx/scripts/office/schemas/ISO-IEC29500-4_2016/dml-picture.xsd", "content": "\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n\n" }, { "path": "src/copaw/agents/skills/docx/scripts/office/schemas/ISO-IEC29500-4_2016/dml-spreadsheetDrawing.xsd", "content": "\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n\n" }, { "path": "src/copaw/agents/skills/docx/scripts/office/schemas/ISO-IEC29500-4_2016/dml-wordprocessingDrawing.xsd", "content": "\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n\n" }, { "path": "src/copaw/agents/skills/docx/scripts/office/schemas/ISO-IEC29500-4_2016/pml.xsd", "content": "\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n\n" }, { "path": "src/copaw/agents/skills/docx/scripts/office/schemas/ISO-IEC29500-4_2016/shared-additionalCharacteristics.xsd", "content": "\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n\n" }, { "path": "src/copaw/agents/skills/docx/scripts/office/schemas/ISO-IEC29500-4_2016/shared-bibliography.xsd", "content": "\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n\n" }, { "path": "src/copaw/agents/skills/docx/scripts/office/schemas/ISO-IEC29500-4_2016/shared-commonSimpleTypes.xsd", "content": "\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n\n" }, { "path": "src/copaw/agents/skills/docx/scripts/office/schemas/ISO-IEC29500-4_2016/shared-customXmlDataProperties.xsd", "content": "\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n\n" }, { "path": "src/copaw/agents/skills/docx/scripts/office/schemas/ISO-IEC29500-4_2016/shared-customXmlSchemaProperties.xsd", "content": "\n\n \n \n \n \n \n \n \n \n \n \n \n \n\n" }, { "path": "src/copaw/agents/skills/docx/scripts/office/schemas/ISO-IEC29500-4_2016/shared-documentPropertiesCustom.xsd", "content": "\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n\n" }, { "path": "src/copaw/agents/skills/docx/scripts/office/schemas/ISO-IEC29500-4_2016/shared-documentPropertiesExtended.xsd", "content": "\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n\n" }, { "path": "src/copaw/agents/skills/docx/scripts/office/schemas/ISO-IEC29500-4_2016/shared-documentPropertiesVariantTypes.xsd", "content": "\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n\n" }, { "path": "src/copaw/agents/skills/docx/scripts/office/schemas/ISO-IEC29500-4_2016/shared-math.xsd", "content": "\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n\n" }, { "path": "src/copaw/agents/skills/docx/scripts/office/schemas/ISO-IEC29500-4_2016/shared-relationshipReference.xsd", "content": "\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n\n" }, { "path": "src/copaw/agents/skills/docx/scripts/office/schemas/ISO-IEC29500-4_2016/sml.xsd", "content": "\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n\n" }, { "path": "src/copaw/agents/skills/docx/scripts/office/schemas/ISO-IEC29500-4_2016/vml-main.xsd", "content": "\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n\n" }, { "path": "src/copaw/agents/skills/docx/scripts/office/schemas/ISO-IEC29500-4_2016/vml-officeDrawing.xsd", "content": "\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n\n" }, { "path": "src/copaw/agents/skills/docx/scripts/office/schemas/ISO-IEC29500-4_2016/vml-presentationDrawing.xsd", "content": "\n\n \n \n \n \n \n \n\n" }, { "path": "src/copaw/agents/skills/docx/scripts/office/schemas/ISO-IEC29500-4_2016/vml-spreadsheetDrawing.xsd", "content": "\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n\n" }, { "path": "src/copaw/agents/skills/docx/scripts/office/schemas/ISO-IEC29500-4_2016/vml-wordprocessingDrawing.xsd", "content": "\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n\n" }, { "path": "src/copaw/agents/skills/docx/scripts/office/schemas/ISO-IEC29500-4_2016/wml.xsd", "content": "\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n\n" }, { "path": "src/copaw/agents/skills/docx/scripts/office/schemas/ISO-IEC29500-4_2016/xml.xsd", "content": "\n\n\n \n \n See http://www.w3.org/XML/1998/namespace.html and\n http://www.w3.org/TR/REC-xml for information about this namespace.\n\n This schema document describes the XML namespace, in a form\n suitable for import by other schema documents. \n\n Note that local names in this namespace are intended to be defined\n only by the World Wide Web Consortium or its subgroups. The\n following names are currently defined in this namespace and should\n not be used with conflicting semantics by any Working Group,\n specification, or document instance:\n\n base (as an attribute name): denotes an attribute whose value\n provides a URI to be used as the base for interpreting any\n relative URIs in the scope of the element on which it\n appears; its value is inherited. This name is reserved\n by virtue of its definition in the XML Base specification.\n\n lang (as an attribute name): denotes an attribute whose value\n is a language code for the natural language of the content of\n any element; its value is inherited. This name is reserved\n by virtue of its definition in the XML specification.\n \n space (as an attribute name): denotes an attribute whose\n value is a keyword indicating what whitespace processing\n discipline is intended for the content of the element; its\n value is inherited. This name is reserved by virtue of its\n definition in the XML specification.\n\n Father (in any context at all): denotes Jon Bosak, the chair of \n the original XML Working Group. This name is reserved by \n the following decision of the W3C XML Plenary and \n XML Coordination groups:\n\n In appreciation for his vision, leadership and dedication\n the W3C XML Plenary on this 10th day of February, 2000\n reserves for Jon Bosak in perpetuity the XML name\n xml:Father\n \n \n\n \n This schema defines attributes and an attribute group\n suitable for use by\n schemas wishing to allow xml:base, xml:lang or xml:space attributes\n on elements they define.\n\n To enable this, such a schema must import this schema\n for the XML namespace, e.g. as follows:\n <schema . . .>\n . . .\n <import namespace=\"http://www.w3.org/XML/1998/namespace\"\n schemaLocation=\"http://www.w3.org/2001/03/xml.xsd\"/>\n\n Subsequently, qualified reference to any of the attributes\n or the group defined below will have the desired effect, e.g.\n\n <type . . .>\n . . .\n <attributeGroup ref=\"xml:specialAttrs\"/>\n \n will define a type which will schema-validate an instance\n element with any of those attributes\n \n\n \n In keeping with the XML Schema WG's standard versioning\n policy, this schema document will persist at\n http://www.w3.org/2001/03/xml.xsd.\n At the date of issue it can also be found at\n http://www.w3.org/2001/xml.xsd.\n The schema document at that URI may however change in the future,\n in order to remain compatible with the latest version of XML Schema\n itself. In other words, if the XML Schema namespace changes, the version\n of this document at\n http://www.w3.org/2001/xml.xsd will change\n accordingly; the version at\n http://www.w3.org/2001/03/xml.xsd will not change.\n \n \n\n \n \n In due course, we should install the relevant ISO 2- and 3-letter\n codes as the enumerated possible values . . .\n \n \n\n \n \n \n \n \n \n \n \n\n \n \n See http://www.w3.org/TR/xmlbase/ for\n information about this attribute.\n \n \n\n \n \n \n \n \n\n\n" }, { "path": "src/copaw/agents/skills/docx/scripts/office/schemas/ecma/fouth-edition/opc-contentTypes.xsd", "content": "\n\n\n \n \n \n\n \n \n \n \n \n \n\n \n \n \n \n\n \n \n \n \n\n \n \n \n \n \n\n \n \n \n \n \n\n" }, { "path": "src/copaw/agents/skills/docx/scripts/office/schemas/ecma/fouth-edition/opc-coreProperties.xsd", "content": "\n\n\n \n \n \n\n \n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n\n \n \n \n \n \n \n\n \n \n \n \n \n \n \n\n\n" }, { "path": "src/copaw/agents/skills/docx/scripts/office/schemas/ecma/fouth-edition/opc-digSig.xsd", "content": "\n\n\n \n \n \n\n \n \n \n \n \n \n\n \n \n \n \n \n \n \n\n \n \n \n \n \n \n \n\n \n \n \n \n \n\n \n \n \n \n \n\n" }, { "path": "src/copaw/agents/skills/docx/scripts/office/schemas/ecma/fouth-edition/opc-relationships.xsd", "content": "\n\n\n \n \n\n \n \n \n \n \n\n \n \n \n \n \n \n \n \n \n \n\n \n \n \n \n \n \n\n" }, { "path": "src/copaw/agents/skills/docx/scripts/office/schemas/mce/mc.xsd", "content": "\n\n\n \n\n \n \n\n \n\t\n\t\n\n\n\t\n\t\t\n\t\t\t\n\t\t\t\t\n\t\t\t\t\t\n\t\t\t\t\t\t\n\t\t\t\t\t\t\t\n\t\t\t\t\t\t\t\n\t\t\t\t\t\t\n\t\t\t\t\t\t\n\t\t\t\t\t\t\n\t\t\t\t\t\t\n\t\t\t\t\t\t\n\t\t\t\t\t\n\t\t\t\t\n\t\t\t\t\n\t\t\t\t\t\n\t\t\t\t\t\t\n\t\t\t\t\t\t\t\n\t\t\t\t\t\t\t\n\t\t\t\t\t\t\n\t\t\t\t\t\t\n\t\t\t\t\t\t\n\t\t\t\t\t\t\n\t\t\t\t\t\n\t\t\t\t\n\t\t\t\n\t\t\t\n\t\t\t\n\t\t\t\n\t\t\t\n\t\t\n\t\n\n" }, { "path": "src/copaw/agents/skills/docx/scripts/office/schemas/microsoft/wml-2010.xsd", "content": " \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n" }, { "path": "src/copaw/agents/skills/docx/scripts/office/schemas/microsoft/wml-2012.xsd", "content": " \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n" }, { "path": "src/copaw/agents/skills/docx/scripts/office/schemas/microsoft/wml-2018.xsd", "content": " \n \n \n \n \n \n \n \n \n \n \n \n \n \n" }, { "path": "src/copaw/agents/skills/docx/scripts/office/schemas/microsoft/wml-cex-2018.xsd", "content": " \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n" }, { "path": "src/copaw/agents/skills/docx/scripts/office/schemas/microsoft/wml-cid-2016.xsd", "content": " \n \n \n \n \n \n \n \n \n \n \n \n \n" }, { "path": "src/copaw/agents/skills/docx/scripts/office/schemas/microsoft/wml-sdtdatahash-2020.xsd", "content": " \n \n \n \n" }, { "path": "src/copaw/agents/skills/docx/scripts/office/schemas/microsoft/wml-symex-2015.xsd", "content": " \n \n \n \n \n \n \n \n" }, { "path": "src/copaw/agents/skills/docx/scripts/office/soffice.py", "content": "\"\"\"\nHelper for running LibreOffice (soffice) in environments where AF_UNIX\nsockets may be blocked (e.g., sandboxed VMs). Detects the restriction\nat runtime and applies an LD_PRELOAD shim if needed.\n\nUsage:\n from office.soffice import run_soffice, get_soffice_cmd, get_soffice_env\n\n # Option 1 – run soffice directly\n result = run_soffice([\"--headless\", \"--convert-to\", \"pdf\", \"input.docx\"])\n\n # Option 2 – get env dict for your own subprocess calls\n env = get_soffice_env()\n subprocess.run([get_soffice_cmd(), ...], env=env)\n\"\"\"\n\nimport os\nimport platform\nimport shutil\nimport socket\nimport subprocess\nimport tempfile\nfrom pathlib import Path\n\n\ndef get_soffice_cmd() -> str:\n \"\"\"Return the soffice command name for the current platform.\"\"\"\n # Prefer PATH first on all platforms.\n path_cmd = shutil.which(\"soffice\")\n if path_cmd:\n return path_cmd\n\n if platform.system() == \"Windows\":\n # Windows can expose soffice as .com or .exe; try both on PATH first.\n for candidate_name in (\"soffice.com\", \"soffice.exe\"):\n path_candidate = shutil.which(candidate_name)\n if path_candidate:\n return path_candidate\n\n # On Windows, try to find soffice.exe via common install paths\n for prog_dir in (\n os.environ.get(\"PROGRAMFILES\", r\"C:\\Program Files\"),\n os.environ.get(\"PROGRAMFILES(X86)\", r\"C:\\Program Files (x86)\"),\n ):\n if not prog_dir:\n continue\n program_dir = Path(prog_dir) / \"LibreOffice\" / \"program\"\n for exe_name in (\"soffice.com\", \"soffice.exe\"):\n candidate = program_dir / exe_name\n if candidate.exists():\n return str(candidate)\n return \"soffice\" # fallback, hope it's on PATH\n return \"soffice\"\n\n\ndef get_soffice_env() -> dict:\n env = os.environ.copy()\n # SAL_USE_VCLPLUGIN=svp is Linux-only (headless rendering)\n if platform.system() == \"Linux\":\n env[\"SAL_USE_VCLPLUGIN\"] = \"svp\"\n\n if _needs_shim():\n shim = _ensure_shim()\n env[\"LD_PRELOAD\"] = str(shim)\n\n return env\n\n\ndef run_soffice(args: list[str], **kwargs) -> subprocess.CompletedProcess:\n env = get_soffice_env()\n return subprocess.run([get_soffice_cmd()] + args, env=env, **kwargs)\n\n\n\n_SHIM_SO = Path(tempfile.gettempdir()) / \"lo_socket_shim.so\"\n\n\ndef _needs_shim() -> bool:\n # AF_UNIX / LD_PRELOAD shim is Linux-only; skip on Windows and macOS\n if not hasattr(socket, \"AF_UNIX\"):\n return False\n try:\n s = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)\n s.close()\n return False\n except OSError:\n return True\n\n\ndef _ensure_shim() -> Path:\n if _SHIM_SO.exists():\n return _SHIM_SO\n\n src = Path(tempfile.gettempdir()) / \"lo_socket_shim.c\"\n src.write_text(_SHIM_SOURCE)\n subprocess.run(\n [\"gcc\", \"-shared\", \"-fPIC\", \"-o\", str(_SHIM_SO), str(src), \"-ldl\"],\n check=True,\n capture_output=True,\n )\n src.unlink()\n return _SHIM_SO\n\n\n\n_SHIM_SOURCE = r\"\"\"\n#define _GNU_SOURCE\n#include \n#include \n#include \n#include \n#include \n#include \n#include \n\nstatic int (*real_socket)(int, int, int);\nstatic int (*real_socketpair)(int, int, int, int[2]);\nstatic int (*real_listen)(int, int);\nstatic int (*real_accept)(int, struct sockaddr *, socklen_t *);\nstatic int (*real_close)(int);\nstatic int (*real_read)(int, void *, size_t);\n\n/* Per-FD bookkeeping (FDs >= 1024 are passed through unshimmed). */\nstatic int is_shimmed[1024];\nstatic int peer_of[1024];\nstatic int wake_r[1024]; /* accept() blocks reading this */\nstatic int wake_w[1024]; /* close() writes to this */\nstatic int listener_fd = -1; /* FD that received listen() */\n\n__attribute__((constructor))\nstatic void init(void) {\n real_socket = dlsym(RTLD_NEXT, \"socket\");\n real_socketpair = dlsym(RTLD_NEXT, \"socketpair\");\n real_listen = dlsym(RTLD_NEXT, \"listen\");\n real_accept = dlsym(RTLD_NEXT, \"accept\");\n real_close = dlsym(RTLD_NEXT, \"close\");\n real_read = dlsym(RTLD_NEXT, \"read\");\n for (int i = 0; i < 1024; i++) {\n peer_of[i] = -1;\n wake_r[i] = -1;\n wake_w[i] = -1;\n }\n}\n\n/* ---- socket ---------------------------------------------------------- */\nint socket(int domain, int type, int protocol) {\n if (domain == AF_UNIX) {\n int fd = real_socket(domain, type, protocol);\n if (fd >= 0) return fd;\n /* socket(AF_UNIX) blocked – fall back to socketpair(). */\n int sv[2];\n if (real_socketpair(domain, type, protocol, sv) == 0) {\n if (sv[0] >= 0 && sv[0] < 1024) {\n is_shimmed[sv[0]] = 1;\n peer_of[sv[0]] = sv[1];\n int wp[2];\n if (pipe(wp) == 0) {\n wake_r[sv[0]] = wp[0];\n wake_w[sv[0]] = wp[1];\n }\n }\n return sv[0];\n }\n errno = EPERM;\n return -1;\n }\n return real_socket(domain, type, protocol);\n}\n\n/* ---- listen ---------------------------------------------------------- */\nint listen(int sockfd, int backlog) {\n if (sockfd >= 0 && sockfd < 1024 && is_shimmed[sockfd]) {\n listener_fd = sockfd;\n return 0;\n }\n return real_listen(sockfd, backlog);\n}\n\n/* ---- accept ---------------------------------------------------------- */\nint accept(int sockfd, struct sockaddr *addr, socklen_t *addrlen) {\n if (sockfd >= 0 && sockfd < 1024 && is_shimmed[sockfd]) {\n /* Block until close() writes to the wake pipe. */\n if (wake_r[sockfd] >= 0) {\n char buf;\n real_read(wake_r[sockfd], &buf, 1);\n }\n errno = ECONNABORTED;\n return -1;\n }\n return real_accept(sockfd, addr, addrlen);\n}\n\n/* ---- close ----------------------------------------------------------- */\nint close(int fd) {\n if (fd >= 0 && fd < 1024 && is_shimmed[fd]) {\n int was_listener = (fd == listener_fd);\n is_shimmed[fd] = 0;\n\n if (wake_w[fd] >= 0) { /* unblock accept() */\n char c = 0;\n write(wake_w[fd], &c, 1);\n real_close(wake_w[fd]);\n wake_w[fd] = -1;\n }\n if (wake_r[fd] >= 0) { real_close(wake_r[fd]); wake_r[fd] = -1; }\n if (peer_of[fd] >= 0) { real_close(peer_of[fd]); peer_of[fd] = -1; }\n\n if (was_listener)\n _exit(0); /* conversion done – exit */\n }\n return real_close(fd);\n}\n\"\"\"\n\n\n\nif __name__ == \"__main__\":\n import sys\n result = run_soffice(sys.argv[1:])\n sys.exit(result.returncode)\n" }, { "path": "src/copaw/agents/skills/docx/scripts/office/unpack.py", "content": "\"\"\"Unpack Office files (DOCX, PPTX, XLSX) for editing.\n\nExtracts the ZIP archive, pretty-prints XML files, and optionally:\n- Merges adjacent runs with identical formatting (DOCX only)\n- Simplifies adjacent tracked changes from same author (DOCX only)\n\nUsage:\n python unpack.py [options]\n\nExamples:\n python unpack.py document.docx unpacked/\n python unpack.py presentation.pptx unpacked/\n python unpack.py document.docx unpacked/ --merge-runs false\n\"\"\"\n\nimport argparse\nimport sys\nimport zipfile\nfrom pathlib import Path\n\nimport defusedxml.minidom\n\nfrom helpers.merge_runs import merge_runs as do_merge_runs\nfrom helpers.simplify_redlines import simplify_redlines as do_simplify_redlines\n\nSMART_QUOTE_REPLACEMENTS = {\n \"\\u201c\": \"“\", \n \"\\u201d\": \"”\", \n \"\\u2018\": \"‘\", \n \"\\u2019\": \"’\", \n}\n\n\ndef unpack(\n input_file: str,\n output_directory: str,\n merge_runs: bool = True,\n simplify_redlines: bool = True,\n) -> tuple[None, str]:\n input_path = Path(input_file)\n output_path = Path(output_directory)\n suffix = input_path.suffix.lower()\n\n if not input_path.exists():\n return None, f\"Error: {input_file} does not exist\"\n\n if suffix not in {\".docx\", \".pptx\", \".xlsx\"}:\n return None, f\"Error: {input_file} must be a .docx, .pptx, or .xlsx file\"\n\n try:\n output_path.mkdir(parents=True, exist_ok=True)\n\n with zipfile.ZipFile(input_path, \"r\") as zf:\n zf.extractall(output_path)\n\n xml_files = list(output_path.rglob(\"*.xml\")) + list(output_path.rglob(\"*.rels\"))\n for xml_file in xml_files:\n _pretty_print_xml(xml_file)\n\n message = f\"Unpacked {input_file} ({len(xml_files)} XML files)\"\n\n if suffix == \".docx\":\n if simplify_redlines:\n simplify_count, _ = do_simplify_redlines(str(output_path))\n message += f\", simplified {simplify_count} tracked changes\"\n\n if merge_runs:\n merge_count, _ = do_merge_runs(str(output_path))\n message += f\", merged {merge_count} runs\"\n\n for xml_file in xml_files:\n _escape_smart_quotes(xml_file)\n\n return None, message\n\n except zipfile.BadZipFile:\n return None, f\"Error: {input_file} is not a valid Office file\"\n except Exception as e:\n return None, f\"Error unpacking: {e}\"\n\n\ndef _pretty_print_xml(xml_file: Path) -> None:\n try:\n content = xml_file.read_text(encoding=\"utf-8\")\n dom = defusedxml.minidom.parseString(content)\n xml_file.write_bytes(dom.toprettyxml(indent=\" \", encoding=\"utf-8\"))\n except Exception:\n pass \n\n\ndef _escape_smart_quotes(xml_file: Path) -> None:\n try:\n content = xml_file.read_text(encoding=\"utf-8\")\n for char, entity in SMART_QUOTE_REPLACEMENTS.items():\n content = content.replace(char, entity)\n xml_file.write_text(content, encoding=\"utf-8\")\n except Exception:\n pass\n\n\nif __name__ == \"__main__\":\n parser = argparse.ArgumentParser(\n description=\"Unpack an Office file (DOCX, PPTX, XLSX) for editing\"\n )\n parser.add_argument(\"input_file\", help=\"Office file to unpack\")\n parser.add_argument(\"output_directory\", help=\"Output directory\")\n parser.add_argument(\n \"--merge-runs\",\n type=lambda x: x.lower() == \"true\",\n default=True,\n metavar=\"true|false\",\n help=\"Merge adjacent runs with identical formatting (DOCX only, default: true)\",\n )\n parser.add_argument(\n \"--simplify-redlines\",\n type=lambda x: x.lower() == \"true\",\n default=True,\n metavar=\"true|false\",\n help=\"Merge adjacent tracked changes from same author (DOCX only, default: true)\",\n )\n args = parser.parse_args()\n\n _, message = unpack(\n args.input_file,\n args.output_directory,\n merge_runs=args.merge_runs,\n simplify_redlines=args.simplify_redlines,\n )\n print(message)\n\n if \"Error\" in message:\n sys.exit(1)\n" }, { "path": "src/copaw/agents/skills/docx/scripts/office/validate.py", "content": "\"\"\"\nCommand line tool to validate Office document XML files against XSD schemas and tracked changes.\n\nUsage:\n python validate.py [--original ] [--auto-repair] [--author NAME]\n\nThe first argument can be either:\n- An unpacked directory containing the Office document XML files\n- A packed Office file (.docx/.pptx/.xlsx) which will be unpacked to a temp directory\n\nAuto-repair fixes:\n- paraId/durableId values that exceed OOXML limits\n- Missing xml:space=\"preserve\" on w:t elements with whitespace\n\"\"\"\n\nimport argparse\nimport sys\nimport tempfile\nimport zipfile\nfrom pathlib import Path\n\nfrom validators import DOCXSchemaValidator, PPTXSchemaValidator, RedliningValidator\n\n\ndef main():\n parser = argparse.ArgumentParser(description=\"Validate Office document XML files\")\n parser.add_argument(\n \"path\",\n help=\"Path to unpacked directory or packed Office file (.docx/.pptx/.xlsx)\",\n )\n parser.add_argument(\n \"--original\",\n required=False,\n default=None,\n help=\"Path to original file (.docx/.pptx/.xlsx). If omitted, all XSD errors are reported and redlining validation is skipped.\",\n )\n parser.add_argument(\n \"-v\",\n \"--verbose\",\n action=\"store_true\",\n help=\"Enable verbose output\",\n )\n parser.add_argument(\n \"--auto-repair\",\n action=\"store_true\",\n help=\"Automatically repair common issues (hex IDs, whitespace preservation)\",\n )\n parser.add_argument(\n \"--author\",\n default=\"Claude\",\n help=\"Author name for redlining validation (default: Claude)\",\n )\n args = parser.parse_args()\n\n path = Path(args.path)\n assert path.exists(), f\"Error: {path} does not exist\"\n\n original_file = None\n if args.original:\n original_file = Path(args.original)\n assert original_file.is_file(), f\"Error: {original_file} is not a file\"\n assert original_file.suffix.lower() in [\".docx\", \".pptx\", \".xlsx\"], (\n f\"Error: {original_file} must be a .docx, .pptx, or .xlsx file\"\n )\n\n file_extension = (original_file or path).suffix.lower()\n assert file_extension in [\".docx\", \".pptx\", \".xlsx\"], (\n f\"Error: Cannot determine file type from {path}. Use --original or provide a .docx/.pptx/.xlsx file.\"\n )\n\n if path.is_file() and path.suffix.lower() in [\".docx\", \".pptx\", \".xlsx\"]:\n temp_dir = tempfile.mkdtemp()\n with zipfile.ZipFile(path, \"r\") as zf:\n zf.extractall(temp_dir)\n unpacked_dir = Path(temp_dir)\n else:\n assert path.is_dir(), f\"Error: {path} is not a directory or Office file\"\n unpacked_dir = path\n\n match file_extension:\n case \".docx\":\n validators = [\n DOCXSchemaValidator(unpacked_dir, original_file, verbose=args.verbose),\n ]\n if original_file:\n validators.append(\n RedliningValidator(unpacked_dir, original_file, verbose=args.verbose, author=args.author) \n )\n case \".pptx\":\n validators = [\n PPTXSchemaValidator(unpacked_dir, original_file, verbose=args.verbose),\n ]\n case _:\n print(f\"Error: Validation not supported for file type {file_extension}\")\n sys.exit(1)\n\n if args.auto_repair:\n total_repairs = sum(v.repair() for v in validators)\n if total_repairs:\n print(f\"Auto-repaired {total_repairs} issue(s)\")\n\n success = all(v.validate() for v in validators)\n\n if success:\n print(\"All validations PASSED!\")\n\n sys.exit(0 if success else 1)\n\n\nif __name__ == \"__main__\":\n main()\n" }, { "path": "src/copaw/agents/skills/docx/scripts/office/validators/__init__.py", "content": "\"\"\"\nValidation modules for Word document processing.\n\"\"\"\n\nfrom .base import BaseSchemaValidator\nfrom .docx import DOCXSchemaValidator\nfrom .pptx import PPTXSchemaValidator\nfrom .redlining import RedliningValidator\n\n__all__ = [\n \"BaseSchemaValidator\",\n \"DOCXSchemaValidator\",\n \"PPTXSchemaValidator\",\n \"RedliningValidator\",\n]\n" }, { "path": "src/copaw/agents/skills/docx/scripts/office/validators/base.py", "content": "\"\"\"\nBase validator with common validation logic for document files.\n\"\"\"\n\nimport re\nfrom pathlib import Path\n\nimport defusedxml.minidom\nimport lxml.etree\n\n\nclass BaseSchemaValidator:\n\n IGNORED_VALIDATION_ERRORS = [\n \"hyphenationZone\",\n \"purl.org/dc/terms\",\n ]\n\n UNIQUE_ID_REQUIREMENTS = {\n \"comment\": (\"id\", \"file\"), \n \"commentrangestart\": (\"id\", \"file\"), \n \"commentrangeend\": (\"id\", \"file\"), \n \"bookmarkstart\": (\"id\", \"file\"), \n \"bookmarkend\": (\"id\", \"file\"), \n \"sldid\": (\"id\", \"file\"), \n \"sldmasterid\": (\"id\", \"global\"), \n \"sldlayoutid\": (\"id\", \"global\"), \n \"cm\": (\"authorid\", \"file\"), \n \"sheet\": (\"sheetid\", \"file\"), \n \"definedname\": (\"id\", \"file\"), \n \"cxnsp\": (\"id\", \"file\"), \n \"sp\": (\"id\", \"file\"), \n \"pic\": (\"id\", \"file\"), \n \"grpsp\": (\"id\", \"file\"), \n }\n\n EXCLUDED_ID_CONTAINERS = {\n \"sectionlst\", \n }\n\n ELEMENT_RELATIONSHIP_TYPES = {}\n\n SCHEMA_MAPPINGS = {\n \"word\": \"ISO-IEC29500-4_2016/wml.xsd\", \n \"ppt\": \"ISO-IEC29500-4_2016/pml.xsd\", \n \"xl\": \"ISO-IEC29500-4_2016/sml.xsd\", \n \"[Content_Types].xml\": \"ecma/fouth-edition/opc-contentTypes.xsd\",\n \"app.xml\": \"ISO-IEC29500-4_2016/shared-documentPropertiesExtended.xsd\",\n \"core.xml\": \"ecma/fouth-edition/opc-coreProperties.xsd\",\n \"custom.xml\": \"ISO-IEC29500-4_2016/shared-documentPropertiesCustom.xsd\",\n \".rels\": \"ecma/fouth-edition/opc-relationships.xsd\",\n \"people.xml\": \"microsoft/wml-2012.xsd\",\n \"commentsIds.xml\": \"microsoft/wml-cid-2016.xsd\",\n \"commentsExtensible.xml\": \"microsoft/wml-cex-2018.xsd\",\n \"commentsExtended.xml\": \"microsoft/wml-2012.xsd\",\n \"chart\": \"ISO-IEC29500-4_2016/dml-chart.xsd\",\n \"theme\": \"ISO-IEC29500-4_2016/dml-main.xsd\",\n \"drawing\": \"ISO-IEC29500-4_2016/dml-main.xsd\",\n }\n\n MC_NAMESPACE = \"http://schemas.openxmlformats.org/markup-compatibility/2006\"\n XML_NAMESPACE = \"http://www.w3.org/XML/1998/namespace\"\n\n PACKAGE_RELATIONSHIPS_NAMESPACE = (\n \"http://schemas.openxmlformats.org/package/2006/relationships\"\n )\n OFFICE_RELATIONSHIPS_NAMESPACE = (\n \"http://schemas.openxmlformats.org/officeDocument/2006/relationships\"\n )\n CONTENT_TYPES_NAMESPACE = (\n \"http://schemas.openxmlformats.org/package/2006/content-types\"\n )\n\n MAIN_CONTENT_FOLDERS = {\"word\", \"ppt\", \"xl\"}\n\n OOXML_NAMESPACES = {\n \"http://schemas.openxmlformats.org/officeDocument/2006/math\",\n \"http://schemas.openxmlformats.org/officeDocument/2006/relationships\",\n \"http://schemas.openxmlformats.org/schemaLibrary/2006/main\",\n \"http://schemas.openxmlformats.org/drawingml/2006/main\",\n \"http://schemas.openxmlformats.org/drawingml/2006/chart\",\n \"http://schemas.openxmlformats.org/drawingml/2006/chartDrawing\",\n \"http://schemas.openxmlformats.org/drawingml/2006/diagram\",\n \"http://schemas.openxmlformats.org/drawingml/2006/picture\",\n \"http://schemas.openxmlformats.org/drawingml/2006/spreadsheetDrawing\",\n \"http://schemas.openxmlformats.org/drawingml/2006/wordprocessingDrawing\",\n \"http://schemas.openxmlformats.org/wordprocessingml/2006/main\",\n \"http://schemas.openxmlformats.org/presentationml/2006/main\",\n \"http://schemas.openxmlformats.org/spreadsheetml/2006/main\",\n \"http://schemas.openxmlformats.org/officeDocument/2006/sharedTypes\",\n \"http://www.w3.org/XML/1998/namespace\",\n }\n\n def __init__(self, unpacked_dir, original_file=None, verbose=False):\n self.unpacked_dir = Path(unpacked_dir).resolve()\n self.original_file = Path(original_file) if original_file else None\n self.verbose = verbose\n\n self.schemas_dir = Path(__file__).parent.parent / \"schemas\"\n\n patterns = [\"*.xml\", \"*.rels\"]\n self.xml_files = [\n f for pattern in patterns for f in self.unpacked_dir.rglob(pattern)\n ]\n\n if not self.xml_files:\n print(f\"Warning: No XML files found in {self.unpacked_dir}\")\n\n def validate(self):\n raise NotImplementedError(\"Subclasses must implement the validate method\")\n\n def repair(self) -> int:\n return self.repair_whitespace_preservation()\n\n def repair_whitespace_preservation(self) -> int:\n repairs = 0\n\n for xml_file in self.xml_files:\n try:\n content = xml_file.read_text(encoding=\"utf-8\")\n dom = defusedxml.minidom.parseString(content)\n modified = False\n\n for elem in dom.getElementsByTagName(\"*\"):\n if elem.tagName.endswith(\":t\") and elem.firstChild:\n text = elem.firstChild.nodeValue\n if text and (text.startswith((' ', '\\t')) or text.endswith((' ', '\\t'))):\n if elem.getAttribute(\"xml:space\") != \"preserve\":\n elem.setAttribute(\"xml:space\", \"preserve\")\n text_preview = repr(text[:30]) + \"...\" if len(text) > 30 else repr(text)\n print(f\" Repaired: {xml_file.name}: Added xml:space='preserve' to {elem.tagName}: {text_preview}\")\n repairs += 1\n modified = True\n\n if modified:\n xml_file.write_bytes(dom.toxml(encoding=\"UTF-8\"))\n\n except Exception:\n pass\n\n return repairs\n\n def validate_xml(self):\n errors = []\n\n for xml_file in self.xml_files:\n try:\n lxml.etree.parse(str(xml_file))\n except lxml.etree.XMLSyntaxError as e:\n errors.append(\n f\" {xml_file.relative_to(self.unpacked_dir)}: \"\n f\"Line {e.lineno}: {e.msg}\"\n )\n except Exception as e:\n errors.append(\n f\" {xml_file.relative_to(self.unpacked_dir)}: \"\n f\"Unexpected error: {str(e)}\"\n )\n\n if errors:\n print(f\"FAILED - Found {len(errors)} XML violations:\")\n for error in errors:\n print(error)\n return False\n else:\n if self.verbose:\n print(\"PASSED - All XML files are well-formed\")\n return True\n\n def validate_namespaces(self):\n errors = []\n\n for xml_file in self.xml_files:\n try:\n root = lxml.etree.parse(str(xml_file)).getroot()\n declared = set(root.nsmap.keys()) - {None} \n\n for attr_val in [\n v for k, v in root.attrib.items() if k.endswith(\"Ignorable\")\n ]:\n undeclared = set(attr_val.split()) - declared\n errors.extend(\n f\" {xml_file.relative_to(self.unpacked_dir)}: \"\n f\"Namespace '{ns}' in Ignorable but not declared\"\n for ns in undeclared\n )\n except lxml.etree.XMLSyntaxError:\n continue\n\n if errors:\n print(f\"FAILED - {len(errors)} namespace issues:\")\n for error in errors:\n print(error)\n return False\n if self.verbose:\n print(\"PASSED - All namespace prefixes properly declared\")\n return True\n\n def validate_unique_ids(self):\n errors = []\n global_ids = {} \n\n for xml_file in self.xml_files:\n try:\n root = lxml.etree.parse(str(xml_file)).getroot()\n file_ids = {} \n\n mc_elements = root.xpath(\n \".//mc:AlternateContent\", namespaces={\"mc\": self.MC_NAMESPACE}\n )\n for elem in mc_elements:\n elem.getparent().remove(elem)\n\n for elem in root.iter():\n tag = (\n elem.tag.split(\"}\")[-1].lower()\n if \"}\" in elem.tag\n else elem.tag.lower()\n )\n\n if tag in self.UNIQUE_ID_REQUIREMENTS:\n in_excluded_container = any(\n ancestor.tag.split(\"}\")[-1].lower() in self.EXCLUDED_ID_CONTAINERS\n for ancestor in elem.iterancestors()\n )\n if in_excluded_container:\n continue\n\n attr_name, scope = self.UNIQUE_ID_REQUIREMENTS[tag]\n\n id_value = None\n for attr, value in elem.attrib.items():\n attr_local = (\n attr.split(\"}\")[-1].lower()\n if \"}\" in attr\n else attr.lower()\n )\n if attr_local == attr_name:\n id_value = value\n break\n\n if id_value is not None:\n if scope == \"global\":\n if id_value in global_ids:\n prev_file, prev_line, prev_tag = global_ids[\n id_value\n ]\n errors.append(\n f\" {xml_file.relative_to(self.unpacked_dir)}: \"\n f\"Line {elem.sourceline}: Global ID '{id_value}' in <{tag}> \"\n f\"already used in {prev_file} at line {prev_line} in <{prev_tag}>\"\n )\n else:\n global_ids[id_value] = (\n xml_file.relative_to(self.unpacked_dir),\n elem.sourceline,\n tag,\n )\n elif scope == \"file\":\n key = (tag, attr_name)\n if key not in file_ids:\n file_ids[key] = {}\n\n if id_value in file_ids[key]:\n prev_line = file_ids[key][id_value]\n errors.append(\n f\" {xml_file.relative_to(self.unpacked_dir)}: \"\n f\"Line {elem.sourceline}: Duplicate {attr_name}='{id_value}' in <{tag}> \"\n f\"(first occurrence at line {prev_line})\"\n )\n else:\n file_ids[key][id_value] = elem.sourceline\n\n except (lxml.etree.XMLSyntaxError, Exception) as e:\n errors.append(\n f\" {xml_file.relative_to(self.unpacked_dir)}: Error: {e}\"\n )\n\n if errors:\n print(f\"FAILED - Found {len(errors)} ID uniqueness violations:\")\n for error in errors:\n print(error)\n return False\n else:\n if self.verbose:\n print(\"PASSED - All required IDs are unique\")\n return True\n\n def validate_file_references(self):\n errors = []\n\n rels_files = list(self.unpacked_dir.rglob(\"*.rels\"))\n\n if not rels_files:\n if self.verbose:\n print(\"PASSED - No .rels files found\")\n return True\n\n all_files = []\n for file_path in self.unpacked_dir.rglob(\"*\"):\n if (\n file_path.is_file()\n and file_path.name != \"[Content_Types].xml\"\n and not file_path.name.endswith(\".rels\")\n ): \n all_files.append(file_path.resolve())\n\n all_referenced_files = set()\n\n if self.verbose:\n print(\n f\"Found {len(rels_files)} .rels files and {len(all_files)} target files\"\n )\n\n for rels_file in rels_files:\n try:\n rels_root = lxml.etree.parse(str(rels_file)).getroot()\n\n rels_dir = rels_file.parent\n\n referenced_files = set()\n broken_refs = []\n\n for rel in rels_root.findall(\n \".//ns:Relationship\",\n namespaces={\"ns\": self.PACKAGE_RELATIONSHIPS_NAMESPACE},\n ):\n target = rel.get(\"Target\")\n if target and not target.startswith(\n (\"http\", \"mailto:\")\n ): \n if target.startswith(\"/\"):\n target_path = self.unpacked_dir / target.lstrip(\"/\")\n elif rels_file.name == \".rels\":\n target_path = self.unpacked_dir / target\n else:\n base_dir = rels_dir.parent\n target_path = base_dir / target\n\n try:\n target_path = target_path.resolve()\n if target_path.exists() and target_path.is_file():\n referenced_files.add(target_path)\n all_referenced_files.add(target_path)\n else:\n broken_refs.append((target, rel.sourceline))\n except (OSError, ValueError):\n broken_refs.append((target, rel.sourceline))\n\n if broken_refs:\n rel_path = rels_file.relative_to(self.unpacked_dir)\n for broken_ref, line_num in broken_refs:\n errors.append(\n f\" {rel_path}: Line {line_num}: Broken reference to {broken_ref}\"\n )\n\n except Exception as e:\n rel_path = rels_file.relative_to(self.unpacked_dir)\n errors.append(f\" Error parsing {rel_path}: {e}\")\n\n unreferenced_files = set(all_files) - all_referenced_files\n\n if unreferenced_files:\n for unref_file in sorted(unreferenced_files):\n unref_rel_path = unref_file.relative_to(self.unpacked_dir)\n errors.append(f\" Unreferenced file: {unref_rel_path}\")\n\n if errors:\n print(f\"FAILED - Found {len(errors)} relationship validation errors:\")\n for error in errors:\n print(error)\n print(\n \"CRITICAL: These errors will cause the document to appear corrupt. \"\n + \"Broken references MUST be fixed, \"\n + \"and unreferenced files MUST be referenced or removed.\"\n )\n return False\n else:\n if self.verbose:\n print(\n \"PASSED - All references are valid and all files are properly referenced\"\n )\n return True\n\n def validate_all_relationship_ids(self):\n import lxml.etree\n\n errors = []\n\n for xml_file in self.xml_files:\n if xml_file.suffix == \".rels\":\n continue\n\n rels_dir = xml_file.parent / \"_rels\"\n rels_file = rels_dir / f\"{xml_file.name}.rels\"\n\n if not rels_file.exists():\n continue\n\n try:\n rels_root = lxml.etree.parse(str(rels_file)).getroot()\n rid_to_type = {}\n\n for rel in rels_root.findall(\n f\".//{{{self.PACKAGE_RELATIONSHIPS_NAMESPACE}}}Relationship\"\n ):\n rid = rel.get(\"Id\")\n rel_type = rel.get(\"Type\", \"\")\n if rid:\n if rid in rid_to_type:\n rels_rel_path = rels_file.relative_to(self.unpacked_dir)\n errors.append(\n f\" {rels_rel_path}: Line {rel.sourceline}: \"\n f\"Duplicate relationship ID '{rid}' (IDs must be unique)\"\n )\n type_name = (\n rel_type.split(\"/\")[-1] if \"/\" in rel_type else rel_type\n )\n rid_to_type[rid] = type_name\n\n xml_root = lxml.etree.parse(str(xml_file)).getroot()\n\n r_ns = self.OFFICE_RELATIONSHIPS_NAMESPACE\n rid_attrs_to_check = [\"id\", \"embed\", \"link\"]\n for elem in xml_root.iter():\n for attr_name in rid_attrs_to_check:\n rid_attr = elem.get(f\"{{{r_ns}}}{attr_name}\")\n if not rid_attr:\n continue\n xml_rel_path = xml_file.relative_to(self.unpacked_dir)\n elem_name = (\n elem.tag.split(\"}\")[-1] if \"}\" in elem.tag else elem.tag\n )\n\n if rid_attr not in rid_to_type:\n errors.append(\n f\" {xml_rel_path}: Line {elem.sourceline}: \"\n f\"<{elem_name}> r:{attr_name} references non-existent relationship '{rid_attr}' \"\n f\"(valid IDs: {', '.join(sorted(rid_to_type.keys())[:5])}{'...' if len(rid_to_type) > 5 else ''})\"\n )\n elif attr_name == \"id\" and self.ELEMENT_RELATIONSHIP_TYPES:\n expected_type = self._get_expected_relationship_type(\n elem_name\n )\n if expected_type:\n actual_type = rid_to_type[rid_attr]\n if expected_type not in actual_type.lower():\n errors.append(\n f\" {xml_rel_path}: Line {elem.sourceline}: \"\n f\"<{elem_name}> references '{rid_attr}' which points to '{actual_type}' \"\n f\"but should point to a '{expected_type}' relationship\"\n )\n\n except Exception as e:\n xml_rel_path = xml_file.relative_to(self.unpacked_dir)\n errors.append(f\" Error processing {xml_rel_path}: {e}\")\n\n if errors:\n print(f\"FAILED - Found {len(errors)} relationship ID reference errors:\")\n for error in errors:\n print(error)\n print(\"\\nThese ID mismatches will cause the document to appear corrupt!\")\n return False\n else:\n if self.verbose:\n print(\"PASSED - All relationship ID references are valid\")\n return True\n\n def _get_expected_relationship_type(self, element_name):\n elem_lower = element_name.lower()\n\n if elem_lower in self.ELEMENT_RELATIONSHIP_TYPES:\n return self.ELEMENT_RELATIONSHIP_TYPES[elem_lower]\n\n if elem_lower.endswith(\"id\") and len(elem_lower) > 2:\n prefix = elem_lower[:-2] \n if prefix.endswith(\"master\"):\n return prefix.lower()\n elif prefix.endswith(\"layout\"):\n return prefix.lower()\n else:\n if prefix == \"sld\":\n return \"slide\"\n return prefix.lower()\n\n if elem_lower.endswith(\"reference\") and len(elem_lower) > 9:\n prefix = elem_lower[:-9] \n return prefix.lower()\n\n return None\n\n def validate_content_types(self):\n errors = []\n\n content_types_file = self.unpacked_dir / \"[Content_Types].xml\"\n if not content_types_file.exists():\n print(\"FAILED - [Content_Types].xml file not found\")\n return False\n\n try:\n root = lxml.etree.parse(str(content_types_file)).getroot()\n declared_parts = set()\n declared_extensions = set()\n\n for override in root.findall(\n f\".//{{{self.CONTENT_TYPES_NAMESPACE}}}Override\"\n ):\n part_name = override.get(\"PartName\")\n if part_name is not None:\n declared_parts.add(part_name.lstrip(\"/\"))\n\n for default in root.findall(\n f\".//{{{self.CONTENT_TYPES_NAMESPACE}}}Default\"\n ):\n extension = default.get(\"Extension\")\n if extension is not None:\n declared_extensions.add(extension.lower())\n\n declarable_roots = {\n \"sld\",\n \"sldLayout\",\n \"sldMaster\",\n \"presentation\", \n \"document\", \n \"workbook\",\n \"worksheet\", \n \"theme\", \n }\n\n media_extensions = {\n \"png\": \"image/png\",\n \"jpg\": \"image/jpeg\",\n \"jpeg\": \"image/jpeg\",\n \"gif\": \"image/gif\",\n \"bmp\": \"image/bmp\",\n \"tiff\": \"image/tiff\",\n \"wmf\": \"image/x-wmf\",\n \"emf\": \"image/x-emf\",\n }\n\n all_files = list(self.unpacked_dir.rglob(\"*\"))\n all_files = [f for f in all_files if f.is_file()]\n\n for xml_file in self.xml_files:\n path_str = str(xml_file.relative_to(self.unpacked_dir)).replace(\n \"\\\\\", \"/\"\n )\n\n if any(\n skip in path_str\n for skip in [\".rels\", \"[Content_Types]\", \"docProps/\", \"_rels/\"]\n ):\n continue\n\n try:\n root_tag = lxml.etree.parse(str(xml_file)).getroot().tag\n root_name = root_tag.split(\"}\")[-1] if \"}\" in root_tag else root_tag\n\n if root_name in declarable_roots and path_str not in declared_parts:\n errors.append(\n f\" {path_str}: File with <{root_name}> root not declared in [Content_Types].xml\"\n )\n\n except Exception:\n continue \n\n for file_path in all_files:\n if file_path.suffix.lower() in {\".xml\", \".rels\"}:\n continue\n if file_path.name == \"[Content_Types].xml\":\n continue\n if \"_rels\" in file_path.parts or \"docProps\" in file_path.parts:\n continue\n\n extension = file_path.suffix.lstrip(\".\").lower()\n if extension and extension not in declared_extensions:\n if extension in media_extensions:\n relative_path = file_path.relative_to(self.unpacked_dir)\n errors.append(\n f' {relative_path}: File with extension \\'{extension}\\' not declared in [Content_Types].xml - should add: '\n )\n\n except Exception as e:\n errors.append(f\" Error parsing [Content_Types].xml: {e}\")\n\n if errors:\n print(f\"FAILED - Found {len(errors)} content type declaration errors:\")\n for error in errors:\n print(error)\n return False\n else:\n if self.verbose:\n print(\n \"PASSED - All content files are properly declared in [Content_Types].xml\"\n )\n return True\n\n def validate_file_against_xsd(self, xml_file, verbose=False):\n xml_file = Path(xml_file).resolve()\n unpacked_dir = self.unpacked_dir.resolve()\n\n is_valid, current_errors = self._validate_single_file_xsd(\n xml_file, unpacked_dir\n )\n\n if is_valid is None:\n return None, set() \n elif is_valid:\n return True, set() \n\n original_errors = self._get_original_file_errors(xml_file)\n\n assert current_errors is not None\n new_errors = current_errors - original_errors\n\n new_errors = {\n e for e in new_errors\n if not any(pattern in e for pattern in self.IGNORED_VALIDATION_ERRORS)\n }\n\n if new_errors:\n if verbose:\n relative_path = xml_file.relative_to(unpacked_dir)\n print(f\"FAILED - {relative_path}: {len(new_errors)} new error(s)\")\n for error in list(new_errors)[:3]:\n truncated = error[:250] + \"...\" if len(error) > 250 else error\n print(f\" - {truncated}\")\n return False, new_errors\n else:\n if verbose:\n print(\n f\"PASSED - No new errors (original had {len(current_errors)} errors)\"\n )\n return True, set()\n\n def validate_against_xsd(self):\n new_errors = []\n original_error_count = 0\n valid_count = 0\n skipped_count = 0\n\n for xml_file in self.xml_files:\n relative_path = str(xml_file.relative_to(self.unpacked_dir))\n is_valid, new_file_errors = self.validate_file_against_xsd(\n xml_file, verbose=False\n )\n\n if is_valid is None:\n skipped_count += 1\n continue\n elif is_valid and not new_file_errors:\n valid_count += 1\n continue\n elif is_valid:\n original_error_count += 1\n valid_count += 1\n continue\n\n new_errors.append(f\" {relative_path}: {len(new_file_errors)} new error(s)\")\n for error in list(new_file_errors)[:3]: \n new_errors.append(\n f\" - {error[:250]}...\" if len(error) > 250 else f\" - {error}\"\n )\n\n if self.verbose:\n print(f\"Validated {len(self.xml_files)} files:\")\n print(f\" - Valid: {valid_count}\")\n print(f\" - Skipped (no schema): {skipped_count}\")\n if original_error_count:\n print(f\" - With original errors (ignored): {original_error_count}\")\n print(\n f\" - With NEW errors: {len(new_errors) > 0 and len([e for e in new_errors if not e.startswith(' ')]) or 0}\"\n )\n\n if new_errors:\n print(\"\\nFAILED - Found NEW validation errors:\")\n for error in new_errors:\n print(error)\n return False\n else:\n if self.verbose:\n print(\"\\nPASSED - No new XSD validation errors introduced\")\n return True\n\n def _get_schema_path(self, xml_file):\n if xml_file.name in self.SCHEMA_MAPPINGS:\n return self.schemas_dir / self.SCHEMA_MAPPINGS[xml_file.name]\n\n if xml_file.suffix == \".rels\":\n return self.schemas_dir / self.SCHEMA_MAPPINGS[\".rels\"]\n\n if \"charts/\" in str(xml_file) and xml_file.name.startswith(\"chart\"):\n return self.schemas_dir / self.SCHEMA_MAPPINGS[\"chart\"]\n\n if \"theme/\" in str(xml_file) and xml_file.name.startswith(\"theme\"):\n return self.schemas_dir / self.SCHEMA_MAPPINGS[\"theme\"]\n\n if xml_file.parent.name in self.MAIN_CONTENT_FOLDERS:\n return self.schemas_dir / self.SCHEMA_MAPPINGS[xml_file.parent.name]\n\n return None\n\n def _clean_ignorable_namespaces(self, xml_doc):\n xml_string = lxml.etree.tostring(xml_doc, encoding=\"unicode\")\n xml_copy = lxml.etree.fromstring(xml_string)\n\n for elem in xml_copy.iter():\n attrs_to_remove = []\n\n for attr in elem.attrib:\n if \"{\" in attr:\n ns = attr.split(\"}\")[0][1:]\n if ns not in self.OOXML_NAMESPACES:\n attrs_to_remove.append(attr)\n\n for attr in attrs_to_remove:\n del elem.attrib[attr]\n\n self._remove_ignorable_elements(xml_copy)\n\n return lxml.etree.ElementTree(xml_copy)\n\n def _remove_ignorable_elements(self, root):\n elements_to_remove = []\n\n for elem in list(root):\n if not hasattr(elem, \"tag\") or callable(elem.tag):\n continue\n\n tag_str = str(elem.tag)\n if tag_str.startswith(\"{\"):\n ns = tag_str.split(\"}\")[0][1:]\n if ns not in self.OOXML_NAMESPACES:\n elements_to_remove.append(elem)\n continue\n\n self._remove_ignorable_elements(elem)\n\n for elem in elements_to_remove:\n root.remove(elem)\n\n def _preprocess_for_mc_ignorable(self, xml_doc):\n root = xml_doc.getroot()\n\n if f\"{{{self.MC_NAMESPACE}}}Ignorable\" in root.attrib:\n del root.attrib[f\"{{{self.MC_NAMESPACE}}}Ignorable\"]\n\n return xml_doc\n\n def _validate_single_file_xsd(self, xml_file, base_path):\n schema_path = self._get_schema_path(xml_file)\n if not schema_path:\n return None, None \n\n try:\n with open(schema_path, \"rb\") as xsd_file:\n parser = lxml.etree.XMLParser()\n xsd_doc = lxml.etree.parse(\n xsd_file, parser=parser, base_url=str(schema_path)\n )\n schema = lxml.etree.XMLSchema(xsd_doc)\n\n with open(xml_file, \"r\") as f:\n xml_doc = lxml.etree.parse(f)\n\n xml_doc, _ = self._remove_template_tags_from_text_nodes(xml_doc)\n xml_doc = self._preprocess_for_mc_ignorable(xml_doc)\n\n relative_path = xml_file.relative_to(base_path)\n if (\n relative_path.parts\n and relative_path.parts[0] in self.MAIN_CONTENT_FOLDERS\n ):\n xml_doc = self._clean_ignorable_namespaces(xml_doc)\n\n if schema.validate(xml_doc):\n return True, set()\n else:\n errors = set()\n for error in schema.error_log:\n errors.add(error.message)\n return False, errors\n\n except Exception as e:\n return False, {str(e)}\n\n def _get_original_file_errors(self, xml_file):\n if self.original_file is None:\n return set()\n\n import tempfile\n import zipfile\n\n xml_file = Path(xml_file).resolve()\n unpacked_dir = self.unpacked_dir.resolve()\n relative_path = xml_file.relative_to(unpacked_dir)\n\n with tempfile.TemporaryDirectory() as temp_dir:\n temp_path = Path(temp_dir)\n\n with zipfile.ZipFile(self.original_file, \"r\") as zip_ref:\n zip_ref.extractall(temp_path)\n\n original_xml_file = temp_path / relative_path\n\n if not original_xml_file.exists():\n return set()\n\n is_valid, errors = self._validate_single_file_xsd(\n original_xml_file, temp_path\n )\n return errors if errors else set()\n\n def _remove_template_tags_from_text_nodes(self, xml_doc):\n warnings = []\n template_pattern = re.compile(r\"\\{\\{[^}]*\\}\\}\")\n\n xml_string = lxml.etree.tostring(xml_doc, encoding=\"unicode\")\n xml_copy = lxml.etree.fromstring(xml_string)\n\n def process_text_content(text, content_type):\n if not text:\n return text\n matches = list(template_pattern.finditer(text))\n if matches:\n for match in matches:\n warnings.append(\n f\"Found template tag in {content_type}: {match.group()}\"\n )\n return template_pattern.sub(\"\", text)\n return text\n\n for elem in xml_copy.iter():\n if not hasattr(elem, \"tag\") or callable(elem.tag):\n continue\n tag_str = str(elem.tag)\n if tag_str.endswith(\"}t\") or tag_str == \"t\":\n continue\n\n elem.text = process_text_content(elem.text, \"text content\")\n elem.tail = process_text_content(elem.tail, \"tail content\")\n\n return lxml.etree.ElementTree(xml_copy), warnings\n\n\nif __name__ == \"__main__\":\n raise RuntimeError(\"This module should not be run directly.\")\n" }, { "path": "src/copaw/agents/skills/docx/scripts/office/validators/docx.py", "content": "\"\"\"\nValidator for Word document XML files against XSD schemas.\n\"\"\"\n\nimport os\nimport random\nimport re\nimport tempfile\nimport zipfile\n\nimport defusedxml.minidom\nimport lxml.etree\n\nfrom .base import BaseSchemaValidator\n\n\nclass DOCXSchemaValidator(BaseSchemaValidator):\n\n WORD_2006_NAMESPACE = \"http://schemas.openxmlformats.org/wordprocessingml/2006/main\"\n W14_NAMESPACE = \"http://schemas.microsoft.com/office/word/2010/wordml\"\n W16CID_NAMESPACE = \"http://schemas.microsoft.com/office/word/2016/wordml/cid\"\n\n ELEMENT_RELATIONSHIP_TYPES = {}\n\n def validate(self):\n if not self.validate_xml():\n return False\n\n all_valid = True\n if not self.validate_namespaces():\n all_valid = False\n\n if not self.validate_unique_ids():\n all_valid = False\n\n if not self.validate_file_references():\n all_valid = False\n\n if not self.validate_content_types():\n all_valid = False\n\n if not self.validate_against_xsd():\n all_valid = False\n\n if not self.validate_whitespace_preservation():\n all_valid = False\n\n if not self.validate_deletions():\n all_valid = False\n\n if not self.validate_insertions():\n all_valid = False\n\n if not self.validate_all_relationship_ids():\n all_valid = False\n\n if not self.validate_id_constraints():\n all_valid = False\n\n if not self.validate_comment_markers():\n all_valid = False\n\n self.compare_paragraph_counts()\n\n return all_valid\n\n def validate_whitespace_preservation(self):\n errors = []\n\n for xml_file in self.xml_files:\n if xml_file.name != \"document.xml\":\n continue\n\n try:\n root = lxml.etree.parse(str(xml_file)).getroot()\n\n for elem in root.iter(f\"{{{self.WORD_2006_NAMESPACE}}}t\"):\n if elem.text:\n text = elem.text\n if re.search(r\"^[ \\t\\n\\r]\", text) or re.search(\n r\"[ \\t\\n\\r]$\", text\n ):\n xml_space_attr = f\"{{{self.XML_NAMESPACE}}}space\"\n if (\n xml_space_attr not in elem.attrib\n or elem.attrib[xml_space_attr] != \"preserve\"\n ):\n text_preview = (\n repr(text)[:50] + \"...\"\n if len(repr(text)) > 50\n else repr(text)\n )\n errors.append(\n f\" {xml_file.relative_to(self.unpacked_dir)}: \"\n f\"Line {elem.sourceline}: w:t element with whitespace missing xml:space='preserve': {text_preview}\"\n )\n\n except (lxml.etree.XMLSyntaxError, Exception) as e:\n errors.append(\n f\" {xml_file.relative_to(self.unpacked_dir)}: Error: {e}\"\n )\n\n if errors:\n print(f\"FAILED - Found {len(errors)} whitespace preservation violations:\")\n for error in errors:\n print(error)\n return False\n else:\n if self.verbose:\n print(\"PASSED - All whitespace is properly preserved\")\n return True\n\n def validate_deletions(self):\n errors = []\n\n for xml_file in self.xml_files:\n if xml_file.name != \"document.xml\":\n continue\n\n try:\n root = lxml.etree.parse(str(xml_file)).getroot()\n namespaces = {\"w\": self.WORD_2006_NAMESPACE}\n\n for t_elem in root.xpath(\".//w:del//w:t\", namespaces=namespaces):\n if t_elem.text:\n text_preview = (\n repr(t_elem.text)[:50] + \"...\"\n if len(repr(t_elem.text)) > 50\n else repr(t_elem.text)\n )\n errors.append(\n f\" {xml_file.relative_to(self.unpacked_dir)}: \"\n f\"Line {t_elem.sourceline}: found within : {text_preview}\"\n )\n\n for instr_elem in root.xpath(\n \".//w:del//w:instrText\", namespaces=namespaces\n ):\n text_preview = (\n repr(instr_elem.text or \"\")[:50] + \"...\"\n if len(repr(instr_elem.text or \"\")) > 50\n else repr(instr_elem.text or \"\")\n )\n errors.append(\n f\" {xml_file.relative_to(self.unpacked_dir)}: \"\n f\"Line {instr_elem.sourceline}: found within (use ): {text_preview}\"\n )\n\n except (lxml.etree.XMLSyntaxError, Exception) as e:\n errors.append(\n f\" {xml_file.relative_to(self.unpacked_dir)}: Error: {e}\"\n )\n\n if errors:\n print(f\"FAILED - Found {len(errors)} deletion validation violations:\")\n for error in errors:\n print(error)\n return False\n else:\n if self.verbose:\n print(\"PASSED - No w:t elements found within w:del elements\")\n return True\n\n def count_paragraphs_in_unpacked(self):\n count = 0\n\n for xml_file in self.xml_files:\n if xml_file.name != \"document.xml\":\n continue\n\n try:\n root = lxml.etree.parse(str(xml_file)).getroot()\n paragraphs = root.findall(f\".//{{{self.WORD_2006_NAMESPACE}}}p\")\n count = len(paragraphs)\n except Exception as e:\n print(f\"Error counting paragraphs in unpacked document: {e}\")\n\n return count\n\n def count_paragraphs_in_original(self):\n original = self.original_file\n if original is None:\n return 0\n\n count = 0\n\n try:\n with tempfile.TemporaryDirectory() as temp_dir:\n with zipfile.ZipFile(original, \"r\") as zip_ref:\n zip_ref.extractall(temp_dir)\n\n doc_xml_path = os.path.join(temp_dir, \"word\", \"document.xml\")\n root = lxml.etree.parse(doc_xml_path).getroot()\n\n paragraphs = root.findall(f\".//{{{self.WORD_2006_NAMESPACE}}}p\")\n count = len(paragraphs)\n\n except Exception as e:\n print(f\"Error counting paragraphs in original document: {e}\")\n\n return count\n\n def validate_insertions(self):\n errors = []\n\n for xml_file in self.xml_files:\n if xml_file.name != \"document.xml\":\n continue\n\n try:\n root = lxml.etree.parse(str(xml_file)).getroot()\n namespaces = {\"w\": self.WORD_2006_NAMESPACE}\n\n invalid_elements = root.xpath(\n \".//w:ins//w:delText[not(ancestor::w:del)]\", namespaces=namespaces\n )\n\n for elem in invalid_elements:\n text_preview = (\n repr(elem.text or \"\")[:50] + \"...\"\n if len(repr(elem.text or \"\")) > 50\n else repr(elem.text or \"\")\n )\n errors.append(\n f\" {xml_file.relative_to(self.unpacked_dir)}: \"\n f\"Line {elem.sourceline}: within : {text_preview}\"\n )\n\n except (lxml.etree.XMLSyntaxError, Exception) as e:\n errors.append(\n f\" {xml_file.relative_to(self.unpacked_dir)}: Error: {e}\"\n )\n\n if errors:\n print(f\"FAILED - Found {len(errors)} insertion validation violations:\")\n for error in errors:\n print(error)\n return False\n else:\n if self.verbose:\n print(\"PASSED - No w:delText elements within w:ins elements\")\n return True\n\n def compare_paragraph_counts(self):\n original_count = self.count_paragraphs_in_original()\n new_count = self.count_paragraphs_in_unpacked()\n\n diff = new_count - original_count\n diff_str = f\"+{diff}\" if diff > 0 else str(diff)\n print(f\"\\nParagraphs: {original_count} → {new_count} ({diff_str})\")\n\n def _parse_id_value(self, val: str, base: int = 16) -> int:\n return int(val, base)\n\n def validate_id_constraints(self):\n errors = []\n para_id_attr = f\"{{{self.W14_NAMESPACE}}}paraId\"\n durable_id_attr = f\"{{{self.W16CID_NAMESPACE}}}durableId\"\n\n for xml_file in self.xml_files:\n try:\n for elem in lxml.etree.parse(str(xml_file)).iter():\n if val := elem.get(para_id_attr):\n if self._parse_id_value(val, base=16) >= 0x80000000:\n errors.append(\n f\" {xml_file.name}:{elem.sourceline}: paraId={val} >= 0x80000000\"\n )\n\n if val := elem.get(durable_id_attr):\n if xml_file.name == \"numbering.xml\":\n try:\n if self._parse_id_value(val, base=10) >= 0x7FFFFFFF:\n errors.append(\n f\" {xml_file.name}:{elem.sourceline}: \"\n f\"durableId={val} >= 0x7FFFFFFF\"\n )\n except ValueError:\n errors.append(\n f\" {xml_file.name}:{elem.sourceline}: \"\n f\"durableId={val} must be decimal in numbering.xml\"\n )\n else:\n if self._parse_id_value(val, base=16) >= 0x7FFFFFFF:\n errors.append(\n f\" {xml_file.name}:{elem.sourceline}: \"\n f\"durableId={val} >= 0x7FFFFFFF\"\n )\n except Exception:\n pass\n\n if errors:\n print(f\"FAILED - {len(errors)} ID constraint violations:\")\n for e in errors:\n print(e)\n elif self.verbose:\n print(\"PASSED - All paraId/durableId values within constraints\")\n return not errors\n\n def validate_comment_markers(self):\n errors = []\n\n document_xml = None\n comments_xml = None\n for xml_file in self.xml_files:\n if xml_file.name == \"document.xml\" and \"word\" in str(xml_file):\n document_xml = xml_file\n elif xml_file.name == \"comments.xml\":\n comments_xml = xml_file\n\n if not document_xml:\n if self.verbose:\n print(\"PASSED - No document.xml found (skipping comment validation)\")\n return True\n\n try:\n doc_root = lxml.etree.parse(str(document_xml)).getroot()\n namespaces = {\"w\": self.WORD_2006_NAMESPACE}\n\n range_starts = {\n elem.get(f\"{{{self.WORD_2006_NAMESPACE}}}id\")\n for elem in doc_root.xpath(\n \".//w:commentRangeStart\", namespaces=namespaces\n )\n }\n range_ends = {\n elem.get(f\"{{{self.WORD_2006_NAMESPACE}}}id\")\n for elem in doc_root.xpath(\n \".//w:commentRangeEnd\", namespaces=namespaces\n )\n }\n references = {\n elem.get(f\"{{{self.WORD_2006_NAMESPACE}}}id\")\n for elem in doc_root.xpath(\n \".//w:commentReference\", namespaces=namespaces\n )\n }\n\n orphaned_ends = range_ends - range_starts\n for comment_id in sorted(\n orphaned_ends, key=lambda x: int(x) if x and x.isdigit() else 0\n ):\n errors.append(\n f' document.xml: commentRangeEnd id=\"{comment_id}\" has no matching commentRangeStart'\n )\n\n orphaned_starts = range_starts - range_ends\n for comment_id in sorted(\n orphaned_starts, key=lambda x: int(x) if x and x.isdigit() else 0\n ):\n errors.append(\n f' document.xml: commentRangeStart id=\"{comment_id}\" has no matching commentRangeEnd'\n )\n\n comment_ids = set()\n if comments_xml and comments_xml.exists():\n comments_root = lxml.etree.parse(str(comments_xml)).getroot()\n comment_ids = {\n elem.get(f\"{{{self.WORD_2006_NAMESPACE}}}id\")\n for elem in comments_root.xpath(\n \".//w:comment\", namespaces=namespaces\n )\n }\n\n marker_ids = range_starts | range_ends | references\n invalid_refs = marker_ids - comment_ids\n for comment_id in sorted(\n invalid_refs, key=lambda x: int(x) if x and x.isdigit() else 0\n ):\n if comment_id: \n errors.append(\n f' document.xml: marker id=\"{comment_id}\" references non-existent comment'\n )\n\n except (lxml.etree.XMLSyntaxError, Exception) as e:\n errors.append(f\" Error parsing XML: {e}\")\n\n if errors:\n print(f\"FAILED - {len(errors)} comment marker violations:\")\n for error in errors:\n print(error)\n return False\n else:\n if self.verbose:\n print(\"PASSED - All comment markers properly paired\")\n return True\n\n def repair(self) -> int:\n repairs = super().repair()\n repairs += self.repair_durableId()\n return repairs\n\n def repair_durableId(self) -> int:\n repairs = 0\n\n for xml_file in self.xml_files:\n try:\n content = xml_file.read_text(encoding=\"utf-8\")\n dom = defusedxml.minidom.parseString(content)\n modified = False\n\n for elem in dom.getElementsByTagName(\"*\"):\n if not elem.hasAttribute(\"w16cid:durableId\"):\n continue\n\n durable_id = elem.getAttribute(\"w16cid:durableId\")\n needs_repair = False\n\n if xml_file.name == \"numbering.xml\":\n try:\n needs_repair = (\n self._parse_id_value(durable_id, base=10) >= 0x7FFFFFFF\n )\n except ValueError:\n needs_repair = True\n else:\n try:\n needs_repair = (\n self._parse_id_value(durable_id, base=16) >= 0x7FFFFFFF\n )\n except ValueError:\n needs_repair = True\n\n if needs_repair:\n value = random.randint(1, 0x7FFFFFFE)\n if xml_file.name == \"numbering.xml\":\n new_id = str(value) \n else:\n new_id = f\"{value:08X}\" \n\n elem.setAttribute(\"w16cid:durableId\", new_id)\n print(\n f\" Repaired: {xml_file.name}: durableId {durable_id} → {new_id}\"\n )\n repairs += 1\n modified = True\n\n if modified:\n xml_file.write_bytes(dom.toxml(encoding=\"UTF-8\"))\n\n except Exception:\n pass\n\n return repairs\n\n\nif __name__ == \"__main__\":\n raise RuntimeError(\"This module should not be run directly.\")\n" }, { "path": "src/copaw/agents/skills/docx/scripts/office/validators/pptx.py", "content": "\"\"\"\nValidator for PowerPoint presentation XML files against XSD schemas.\n\"\"\"\n\nimport re\n\nfrom .base import BaseSchemaValidator\n\n\nclass PPTXSchemaValidator(BaseSchemaValidator):\n\n PRESENTATIONML_NAMESPACE = (\n \"http://schemas.openxmlformats.org/presentationml/2006/main\"\n )\n\n ELEMENT_RELATIONSHIP_TYPES = {\n \"sldid\": \"slide\",\n \"sldmasterid\": \"slidemaster\",\n \"notesmasterid\": \"notesmaster\",\n \"sldlayoutid\": \"slidelayout\",\n \"themeid\": \"theme\",\n \"tablestyleid\": \"tablestyles\",\n }\n\n def validate(self):\n if not self.validate_xml():\n return False\n\n all_valid = True\n if not self.validate_namespaces():\n all_valid = False\n\n if not self.validate_unique_ids():\n all_valid = False\n\n if not self.validate_uuid_ids():\n all_valid = False\n\n if not self.validate_file_references():\n all_valid = False\n\n if not self.validate_slide_layout_ids():\n all_valid = False\n\n if not self.validate_content_types():\n all_valid = False\n\n if not self.validate_against_xsd():\n all_valid = False\n\n if not self.validate_notes_slide_references():\n all_valid = False\n\n if not self.validate_all_relationship_ids():\n all_valid = False\n\n if not self.validate_no_duplicate_slide_layouts():\n all_valid = False\n\n return all_valid\n\n def validate_uuid_ids(self):\n import lxml.etree\n\n errors = []\n uuid_pattern = re.compile(\n r\"^[\\{\\(]?[0-9A-Fa-f]{8}-?[0-9A-Fa-f]{4}-?[0-9A-Fa-f]{4}-?[0-9A-Fa-f]{4}-?[0-9A-Fa-f]{12}[\\}\\)]?$\"\n )\n\n for xml_file in self.xml_files:\n try:\n root = lxml.etree.parse(str(xml_file)).getroot()\n\n for elem in root.iter():\n for attr, value in elem.attrib.items():\n attr_name = attr.split(\"}\")[-1].lower()\n if attr_name == \"id\" or attr_name.endswith(\"id\"):\n if self._looks_like_uuid(value):\n if not uuid_pattern.match(value):\n errors.append(\n f\" {xml_file.relative_to(self.unpacked_dir)}: \"\n f\"Line {elem.sourceline}: ID '{value}' appears to be a UUID but contains invalid hex characters\"\n )\n\n except (lxml.etree.XMLSyntaxError, Exception) as e:\n errors.append(\n f\" {xml_file.relative_to(self.unpacked_dir)}: Error: {e}\"\n )\n\n if errors:\n print(f\"FAILED - Found {len(errors)} UUID ID validation errors:\")\n for error in errors:\n print(error)\n return False\n else:\n if self.verbose:\n print(\"PASSED - All UUID-like IDs contain valid hex values\")\n return True\n\n def _looks_like_uuid(self, value):\n clean_value = value.strip(\"{}()\").replace(\"-\", \"\")\n return len(clean_value) == 32 and all(c.isalnum() for c in clean_value)\n\n def validate_slide_layout_ids(self):\n import lxml.etree\n\n errors = []\n\n slide_masters = list(self.unpacked_dir.glob(\"ppt/slideMasters/*.xml\"))\n\n if not slide_masters:\n if self.verbose:\n print(\"PASSED - No slide masters found\")\n return True\n\n for slide_master in slide_masters:\n try:\n root = lxml.etree.parse(str(slide_master)).getroot()\n\n rels_file = slide_master.parent / \"_rels\" / f\"{slide_master.name}.rels\"\n\n if not rels_file.exists():\n errors.append(\n f\" {slide_master.relative_to(self.unpacked_dir)}: \"\n f\"Missing relationships file: {rels_file.relative_to(self.unpacked_dir)}\"\n )\n continue\n\n rels_root = lxml.etree.parse(str(rels_file)).getroot()\n\n valid_layout_rids = set()\n for rel in rels_root.findall(\n f\".//{{{self.PACKAGE_RELATIONSHIPS_NAMESPACE}}}Relationship\"\n ):\n rel_type = rel.get(\"Type\", \"\")\n if \"slideLayout\" in rel_type:\n valid_layout_rids.add(rel.get(\"Id\"))\n\n for sld_layout_id in root.findall(\n f\".//{{{self.PRESENTATIONML_NAMESPACE}}}sldLayoutId\"\n ):\n r_id = sld_layout_id.get(\n f\"{{{self.OFFICE_RELATIONSHIPS_NAMESPACE}}}id\"\n )\n layout_id = sld_layout_id.get(\"id\")\n\n if r_id and r_id not in valid_layout_rids:\n errors.append(\n f\" {slide_master.relative_to(self.unpacked_dir)}: \"\n f\"Line {sld_layout_id.sourceline}: sldLayoutId with id='{layout_id}' \"\n f\"references r:id='{r_id}' which is not found in slide layout relationships\"\n )\n\n except (lxml.etree.XMLSyntaxError, Exception) as e:\n errors.append(\n f\" {slide_master.relative_to(self.unpacked_dir)}: Error: {e}\"\n )\n\n if errors:\n print(f\"FAILED - Found {len(errors)} slide layout ID validation errors:\")\n for error in errors:\n print(error)\n print(\n \"Remove invalid references or add missing slide layouts to the relationships file.\"\n )\n return False\n else:\n if self.verbose:\n print(\"PASSED - All slide layout IDs reference valid slide layouts\")\n return True\n\n def validate_no_duplicate_slide_layouts(self):\n import lxml.etree\n\n errors = []\n slide_rels_files = list(self.unpacked_dir.glob(\"ppt/slides/_rels/*.xml.rels\"))\n\n for rels_file in slide_rels_files:\n try:\n root = lxml.etree.parse(str(rels_file)).getroot()\n\n layout_rels = [\n rel\n for rel in root.findall(\n f\".//{{{self.PACKAGE_RELATIONSHIPS_NAMESPACE}}}Relationship\"\n )\n if \"slideLayout\" in rel.get(\"Type\", \"\")\n ]\n\n if len(layout_rels) > 1:\n errors.append(\n f\" {rels_file.relative_to(self.unpacked_dir)}: has {len(layout_rels)} slideLayout references\"\n )\n\n except Exception as e:\n errors.append(\n f\" {rels_file.relative_to(self.unpacked_dir)}: Error: {e}\"\n )\n\n if errors:\n print(\"FAILED - Found slides with duplicate slideLayout references:\")\n for error in errors:\n print(error)\n return False\n else:\n if self.verbose:\n print(\"PASSED - All slides have exactly one slideLayout reference\")\n return True\n\n def validate_notes_slide_references(self):\n import lxml.etree\n\n errors = []\n notes_slide_references = {} \n\n slide_rels_files = list(self.unpacked_dir.glob(\"ppt/slides/_rels/*.xml.rels\"))\n\n if not slide_rels_files:\n if self.verbose:\n print(\"PASSED - No slide relationship files found\")\n return True\n\n for rels_file in slide_rels_files:\n try:\n root = lxml.etree.parse(str(rels_file)).getroot()\n\n for rel in root.findall(\n f\".//{{{self.PACKAGE_RELATIONSHIPS_NAMESPACE}}}Relationship\"\n ):\n rel_type = rel.get(\"Type\", \"\")\n if \"notesSlide\" in rel_type:\n target = rel.get(\"Target\", \"\")\n if target:\n normalized_target = target.replace(\"../\", \"\")\n\n slide_name = rels_file.stem.replace(\n \".xml\", \"\"\n ) \n\n if normalized_target not in notes_slide_references:\n notes_slide_references[normalized_target] = []\n notes_slide_references[normalized_target].append(\n (slide_name, rels_file)\n )\n\n except (lxml.etree.XMLSyntaxError, Exception) as e:\n errors.append(\n f\" {rels_file.relative_to(self.unpacked_dir)}: Error: {e}\"\n )\n\n for target, references in notes_slide_references.items():\n if len(references) > 1:\n slide_names = [ref[0] for ref in references]\n errors.append(\n f\" Notes slide '{target}' is referenced by multiple slides: {', '.join(slide_names)}\"\n )\n for slide_name, rels_file in references:\n errors.append(f\" - {rels_file.relative_to(self.unpacked_dir)}\")\n\n if errors:\n print(\n f\"FAILED - Found {len([e for e in errors if not e.startswith(' ')])} notes slide reference validation errors:\"\n )\n for error in errors:\n print(error)\n print(\"Each slide may optionally have its own slide file.\")\n return False\n else:\n if self.verbose:\n print(\"PASSED - All notes slide references are unique\")\n return True\n\n\nif __name__ == \"__main__\":\n raise RuntimeError(\"This module should not be run directly.\")\n" }, { "path": "src/copaw/agents/skills/docx/scripts/office/validators/redlining.py", "content": "\"\"\"\nValidator for tracked changes in Word documents.\n\"\"\"\n\nimport subprocess\nimport tempfile\nimport zipfile\nfrom pathlib import Path\n\n\nclass RedliningValidator:\n\n def __init__(self, unpacked_dir, original_docx, verbose=False, author=\"Claude\"):\n self.unpacked_dir = Path(unpacked_dir)\n self.original_docx = Path(original_docx)\n self.verbose = verbose\n self.author = author\n self.namespaces = {\n \"w\": \"http://schemas.openxmlformats.org/wordprocessingml/2006/main\"\n }\n\n def repair(self) -> int:\n return 0\n\n def validate(self):\n modified_file = self.unpacked_dir / \"word\" / \"document.xml\"\n if not modified_file.exists():\n print(f\"FAILED - Modified document.xml not found at {modified_file}\")\n return False\n\n try:\n import xml.etree.ElementTree as ET\n\n tree = ET.parse(modified_file)\n root = tree.getroot()\n\n del_elements = root.findall(\".//w:del\", self.namespaces)\n ins_elements = root.findall(\".//w:ins\", self.namespaces)\n\n author_del_elements = [\n elem\n for elem in del_elements\n if elem.get(f\"{{{self.namespaces['w']}}}author\") == self.author\n ]\n author_ins_elements = [\n elem\n for elem in ins_elements\n if elem.get(f\"{{{self.namespaces['w']}}}author\") == self.author\n ]\n\n if not author_del_elements and not author_ins_elements:\n if self.verbose:\n print(f\"PASSED - No tracked changes by {self.author} found.\")\n return True\n\n except Exception:\n pass\n\n with tempfile.TemporaryDirectory() as temp_dir:\n temp_path = Path(temp_dir)\n\n try:\n with zipfile.ZipFile(self.original_docx, \"r\") as zip_ref:\n zip_ref.extractall(temp_path)\n except Exception as e:\n print(f\"FAILED - Error unpacking original docx: {e}\")\n return False\n\n original_file = temp_path / \"word\" / \"document.xml\"\n if not original_file.exists():\n print(\n f\"FAILED - Original document.xml not found in {self.original_docx}\"\n )\n return False\n\n try:\n import xml.etree.ElementTree as ET\n\n modified_tree = ET.parse(modified_file)\n modified_root = modified_tree.getroot()\n original_tree = ET.parse(original_file)\n original_root = original_tree.getroot()\n except ET.ParseError as e:\n print(f\"FAILED - Error parsing XML files: {e}\")\n return False\n\n self._remove_author_tracked_changes(original_root)\n self._remove_author_tracked_changes(modified_root)\n\n modified_text = self._extract_text_content(modified_root)\n original_text = self._extract_text_content(original_root)\n\n if modified_text != original_text:\n error_message = self._generate_detailed_diff(\n original_text, modified_text\n )\n print(error_message)\n return False\n\n if self.verbose:\n print(f\"PASSED - All changes by {self.author} are properly tracked\")\n return True\n\n def _generate_detailed_diff(self, original_text, modified_text):\n error_parts = [\n f\"FAILED - Document text doesn't match after removing {self.author}'s tracked changes\",\n \"\",\n \"Likely causes:\",\n \" 1. Modified text inside another author's or tags\",\n \" 2. Made edits without proper tracked changes\",\n \" 3. Didn't nest inside when deleting another's insertion\",\n \"\",\n \"For pre-redlined documents, use correct patterns:\",\n \" - To reject another's INSERTION: Nest inside their \",\n \" - To restore another's DELETION: Add new AFTER their \",\n \"\",\n ]\n\n git_diff = self._get_git_word_diff(original_text, modified_text)\n if git_diff:\n error_parts.extend([\"Differences:\", \"============\", git_diff])\n else:\n error_parts.append(\"Unable to generate word diff (git not available)\")\n\n return \"\\n\".join(error_parts)\n\n def _get_git_word_diff(self, original_text, modified_text):\n try:\n with tempfile.TemporaryDirectory() as temp_dir:\n temp_path = Path(temp_dir)\n\n original_file = temp_path / \"original.txt\"\n modified_file = temp_path / \"modified.txt\"\n\n original_file.write_text(original_text, encoding=\"utf-8\")\n modified_file.write_text(modified_text, encoding=\"utf-8\")\n\n result = subprocess.run(\n [\n \"git\",\n \"diff\",\n \"--word-diff=plain\",\n \"--word-diff-regex=.\", \n \"-U0\", \n \"--no-index\",\n str(original_file),\n str(modified_file),\n ],\n capture_output=True,\n text=True,\n )\n\n if result.stdout.strip():\n lines = result.stdout.split(\"\\n\")\n content_lines = []\n in_content = False\n for line in lines:\n if line.startswith(\"@@\"):\n in_content = True\n continue\n if in_content and line.strip():\n content_lines.append(line)\n\n if content_lines:\n return \"\\n\".join(content_lines)\n\n result = subprocess.run(\n [\n \"git\",\n \"diff\",\n \"--word-diff=plain\",\n \"-U0\", \n \"--no-index\",\n str(original_file),\n str(modified_file),\n ],\n capture_output=True,\n text=True,\n )\n\n if result.stdout.strip():\n lines = result.stdout.split(\"\\n\")\n content_lines = []\n in_content = False\n for line in lines:\n if line.startswith(\"@@\"):\n in_content = True\n continue\n if in_content and line.strip():\n content_lines.append(line)\n return \"\\n\".join(content_lines)\n\n except (subprocess.CalledProcessError, FileNotFoundError, Exception):\n pass\n\n return None\n\n def _remove_author_tracked_changes(self, root):\n ins_tag = f\"{{{self.namespaces['w']}}}ins\"\n del_tag = f\"{{{self.namespaces['w']}}}del\"\n author_attr = f\"{{{self.namespaces['w']}}}author\"\n\n for parent in root.iter():\n to_remove = []\n for child in parent:\n if child.tag == ins_tag and child.get(author_attr) == self.author:\n to_remove.append(child)\n for elem in to_remove:\n parent.remove(elem)\n\n deltext_tag = f\"{{{self.namespaces['w']}}}delText\"\n t_tag = f\"{{{self.namespaces['w']}}}t\"\n\n for parent in root.iter():\n to_process = []\n for child in parent:\n if child.tag == del_tag and child.get(author_attr) == self.author:\n to_process.append((child, list(parent).index(child)))\n\n for del_elem, del_index in reversed(to_process):\n for elem in del_elem.iter():\n if elem.tag == deltext_tag:\n elem.tag = t_tag\n\n for child in reversed(list(del_elem)):\n parent.insert(del_index, child)\n parent.remove(del_elem)\n\n def _extract_text_content(self, root):\n p_tag = f\"{{{self.namespaces['w']}}}p\"\n t_tag = f\"{{{self.namespaces['w']}}}t\"\n\n paragraphs = []\n for p_elem in root.findall(f\".//{p_tag}\"):\n text_parts = []\n for t_elem in p_elem.findall(f\".//{t_tag}\"):\n if t_elem.text:\n text_parts.append(t_elem.text)\n paragraph_text = \"\".join(text_parts)\n if paragraph_text:\n paragraphs.append(paragraph_text)\n\n return \"\\n\".join(paragraphs)\n\n\nif __name__ == \"__main__\":\n raise RuntimeError(\"This module should not be run directly.\")\n" }, { "path": "src/copaw/agents/skills/docx/scripts/templates/comments.xml", "content": "\n\n\n" }, { "path": "src/copaw/agents/skills/docx/scripts/templates/commentsExtended.xml", "content": "\n\n\n" }, { "path": "src/copaw/agents/skills/docx/scripts/templates/commentsExtensible.xml", "content": "\n\n\n" }, { "path": "src/copaw/agents/skills/docx/scripts/templates/commentsIds.xml", "content": "\n\n\n" }, { "path": "src/copaw/agents/skills/docx/scripts/templates/people.xml", "content": "\n\n\n" }, { "path": "src/copaw/agents/skills/file_reader/SKILL.md", "content": "---\nname: file_reader\ndescription: \"Read and summarize text-based file types only. Prefer read_file for text formats; use execute_shell_command for type detection when needed. PDF/Office/images/archives are handled by other skills.\"\nmetadata:\n {\n \"builtin_skill_version\": \"1.0\",\n \"copaw\":\n {\n \"emoji\": \"📄\",\n \"requires\": {}\n }\n }\n---\n# File Reader Toolbox\n\nUse this skill when the user asks to read or summarize local text-based files. PDFs, Office documents, images, audio, and video are out of scope for this skill and should be handled by their dedicated skills/tools.\n\n## Quick Type Check\n\nUse a type probe before reading:\n\n```bash\nfile -b --mime-type \"/path/to/file\"\n```\n\nIf the file is large, avoid dumping the whole content; extract a small, relevant portion and summarize.\n\n## Text-Based Files (use read_file)\n\nPreferred for: `.txt`, `.md`, `.json`, `.yaml/.yml`, `.csv/.tsv`, `.log`, `.sql`, `ini`, `toml`, `py`, `js`, `html`, `xml` source code.\n\nSteps:\n\n1. Use `read_file` to fetch content.\n2. Summarize key sections or show the relevant slice requested by the user.\n3. For JSON/YAML, list top-level keys and important fields.\n4. For CSV/TSV, show header + first few rows, then summarize columns.\n\n## Large Logs\n\nIf the file is huge, use a tail window:\n\n```bash\ntail -n 200 \"/path/to/file.log\"\n```\n\nSummarize the last errors/warnings and notable patterns.\n\n## Out of Scope\n\nDo not handle the following in this skill (they are covered by other skills):\n\n- PDF\n- Office (docx/xlsx/pptx)\n- Images\n- Audio/Video\n\n## Safety and Behavior\n\n- Never execute untrusted files.\n- Prefer reading the smallest portion necessary.\n- If a tool is missing, explain the limitation and ask the user for an alternate format.\n" }, { "path": "src/copaw/agents/skills/guidance/SKILL.md", "content": "---\nname: guidance\ndescription: \"回答用户关于 CoPaw 安装与配置的问题：优先定位并阅读本地文档，再提炼答案；若本地信息不足，兜底访问官网文档。\"\nmetadata:\n {\n \"builtin_skill_version\": \"1.0\",\n \"copaw\":\n {\n \"emoji\": \"🧭\",\n \"requires\": {}\n }\n }\n---\n\n# CoPaw 安装与配置问答指南\n\n当用户询问 **CoPaw 的安装、初始化、环境配置、依赖要求、常见配置项** 时，使用本 skill。\n\n核心原则：\n\n- 先查本地文档，再回答\n- 回答要基于已读到的内容，不臆测\n- 回答语言与用户提问语言保持一致\n\n## 标准流程\n\n\n### 第一步：定位文档位置\n\n**查找记忆中的文档目录**\n\n首先你可以查看memory中是否有文档目录，如果有则直接使用，如果没有则继续执行下一步。\n\n```bash\n# 获取memory中的文档目录\nDOC_DIR=$(find ~/.copaw/memory/ -type d -name \"docs\")\n```\n\n如果 memory 中没有文档目录，则继续执行下面的逻辑。\n\n**检查项目源码中的文档目录**\n\n执行以下脚本逻辑来获取变量 $COPAW_ROOT：\n\n```bash\n# 获取二进制绝对路径\nCOP_PATH=$(which copaw 2>/dev/null || whereis copaw | awk '{print $2}')\n\n# 逻辑推导：如果路径包含 .copaw/bin/copaw，则根目录在其上三层\n# 例如：/path/to/CoPaw/.copaw/bin/copaw -> /path/to/CoPaw\nif [[ \"$COP_PATH\" == *\".copaw/bin/copaw\" ]]; then\n COPAW_ROOT=$(echo \"$COP_PATH\" | sed 's/\\/\\.copaw\\/bin\\/copaw//')\nelse\n # 兜底：尝试获取所在目录的父目录\n COPAW_ROOT=$(dirname $(dirname \"$COP_PATH\") 2>/dev/null || echo \".\")\nfi\n\necho \"Detected CoPaw Root: $COPAW_ROOT\"\n```\n\n验证并列出文档目录：\n使用推导出的 $COPAW_ROOT 定位文档：\n\n```bash\n# 组合标准文档路径\n=\"$COPAW_ROOT/website/public/docs/\"\n\n# 检查路径是否存在并列出文件\nif [ -d \"$DOC_DIR\" ]; then\n find \"$DOC_DIR\" -type f -name \"*.md\" | head -n 100\nelse\n # 如果推导路径不对，执行全局模糊搜索\n find \"$COPAW_ROOT\" -type d -name \"docs\" | grep \"website/public/docs\"\nfi\n```\n**如果项目文档不存在，搜索工作目录**\n\n如果还是找不到文档，搜索 copaw 安装路径下的可用文档内容：\n\n```bash\n# 寻找 faq.en.md 或 config.zh.md 等特征文件\nFILE_PATH=$(find . -type f -name \"faq.en.md\" -o -name \"config.zh.md\" | head -n 1)\nif [ -n \"$FILE_PATH\" ]; then\n # 使用 dirname 获取该文件所在的目录\n DOC_DIR=$(dirname \"$FILE_PATH\")\nfi\n```\n如果找到了文档目录，请你记录在 memory 中，格式为：\n\n```markdown\n# 文档目录\n$DOC_DIR = \n```\n\n### 第二步：文档检索与匹配\n\n文档文件命名格式为 `..md`（如 `config.zh.md`、`config.en.md`、`quickstart.zh.md`）。\n\n使用 find 命令在目标目录中列出所有符合后缀的文档，并根据文件名关键字（如 install, env, setup）锁定目标作为 。\n\n```bash\n# 列出所有符合后缀的文档\nfind $DOC_DIR -type f -name \"*.md\"\n```\n\n如果没有合适的文档，则在下一步阅读所有文档内容。\n\n\n### 第三步：阅读文档内容\n\n找到候选文档后，读取并确认与问题相关的段落。可使用：\n\n- `cat `\n- `file_reader` skill（推荐用于更长文档或分段读取）\n\n如果文档很长，优先读取和问题最相关的章节（安装步骤、配置项、示例命令、注意事项、版本要求）。\n\n### 第四步：提取信息并作答\n\n从文档中提取关键信息，组织成可执行答案：\n\n- 先给直接结论\n- 再给步骤/命令/配置示例\n- 补充必要前置条件与常见坑\n\n语言要求：回答语言必须与用户提问语言一致（中文问就中文答，英文问就英文答）。\n\n### 第五步（可选）：官网检索\n\n若前面步骤无法完成（本地无文档、文档缺失、信息不足），使用官网作为兜底：\n\n- http://copaw.agentscope.io/\n\n基于官网可获得内容继续回答，并在答案中明确说明该结论来自官网文档。\n\n## 输出质量要求\n\n- 不编造不存在的配置项或命令\n- 遇到版本差异时，明确标注“需以当前文档版本为准”\n- 涉及路径、命令、配置键时，尽量给可复制的原文片段\n- 若信息仍不足，明确缺口并告诉用户还需要哪类信息（例如操作系统、安装方式、报错日志）\n" }, { "path": "src/copaw/agents/skills/himalaya/SKILL.md", "content": "---\nname: himalaya\ndescription: \"CLI to manage emails via IMAP/SMTP. Use `himalaya` to list, read, write, reply, forward, search, and organize emails from the terminal. Supports multiple accounts and message composition with MML (MIME Meta Language).\"\nhomepage: https://github.com/pimalaya/himalaya\nmetadata:\n {\n \"builtin_skill_version\": \"1.0\",\n \"openclaw\":\n {\n \"emoji\": \"📧\",\n \"requires\": { \"bins\": [\"himalaya\"] },\n \"install\":\n [\n {\n \"id\": \"brew\",\n \"kind\": \"brew\",\n \"formula\": \"himalaya\",\n \"bins\": [\"himalaya\"],\n \"label\": \"Install Himalaya (brew)\",\n },\n ],\n },\n }\n---\n# Himalaya Email CLI\n\nHimalaya is a CLI email client that lets you manage emails from the terminal using IMAP, SMTP, Notmuch, or Sendmail backends.\n\n## References\n\n- `references/configuration.md` (config file setup + IMAP/SMTP authentication)\n\n## Prerequisites\n\n1. Himalaya CLI installed (`himalaya --version` to verify)\n2. A configuration file at `~/.config/himalaya/config.toml`\n3. IMAP/SMTP credentials configured (password stored securely)\n\n## Configuration Setup\n\nRun the interactive wizard to set up an account (replace `default` with\nany name you want, e.g. `gmail`, `work`):\n\n```bash\nhimalaya account configure default\n```\n\nOr create `~/.config/himalaya/config.toml` manually:\n\n```toml\n[accounts.personal]\nemail = \"you@example.com\"\ndisplay-name = \"Your Name\"\ndefault = true\n\nbackend.type = \"imap\"\nbackend.host = \"imap.example.com\"\nbackend.port = 993\nbackend.encryption.type = \"tls\"\nbackend.login = \"you@example.com\"\nbackend.auth.type = \"password\"\nbackend.auth.cmd = \"pass show email/imap\" # or use keyring\n\nmessage.send.backend.type = \"smtp\"\nmessage.send.backend.host = \"smtp.example.com\"\nmessage.send.backend.port = 587\nmessage.send.backend.encryption.type = \"start-tls\"\nmessage.send.backend.login = \"you@example.com\"\nmessage.send.backend.auth.type = \"password\"\nmessage.send.backend.auth.cmd = \"pass show email/smtp\"\n```\n\nIf you are using 163 mail account, add `backend.extensions.id.send-after-auth = true` in the config file to ensure proper functionality.\n\n## Common Operations\n\n### List Folders\n\n```bash\nhimalaya folder list\n```\n\n### List Emails\n\nList emails in INBOX (default):\n\n```bash\nhimalaya envelope list\n```\n\nList emails in a specific folder:\n\n```bash\nhimalaya envelope list --folder \"Sent\"\n```\n\nList with pagination:\n\n```bash\nhimalaya envelope list --page 1 --page-size 20\n```\n\nIf meet with error, try:\n\n```bash\nhimalaya envelope list -f INBOX -s 1\n```\n\n### Search Emails\n\n```bash\nhimalaya envelope list from john@example.com subject meeting\n```\n\n### Read an Email\n\nRead email by ID (shows plain text):\n\n```bash\nhimalaya message read 42\n```\n\nExport raw MIME:\n\n```bash\nhimalaya message export 42 --full\n```\n\n### Send / Compose Emails\n\n**Recommended approach:** Use `template write | template send` pipeline for simple emails.\n\n**Send a simple email:**\n\n```bash\nexport EDITOR=cat\nhimalaya template write \\\n -H \"To: recipient@example.com\" \\\n -H \"Subject: Email Subject\" \\\n \"Email body content\" | himalaya template send\n```\n\n**Send with multiple headers:**\n\n```bash\nexport EDITOR=cat\nhimalaya template write \\\n -H \"To: recipient@example.com\" \\\n -H \"Cc: cc@example.com\" \\\n -H \"Subject: Email Subject\" \\\n \"Email body content\" | himalaya template send\n```\n\n**Send with attachments (using Python):**\n\nFor emails with attachments, use Python's `smtplib` and `email.mime` modules:\n\n```python\nimport smtplib\nfrom email.mime.multipart import MIMEMultipart\nfrom email.mime.text import MIMEText\nfrom email.mime.base import MIMEBase\nfrom email import encoders\n\nmsg = MIMEMultipart()\nmsg['From'] = 'sender@163.com'\nmsg['To'] = 'recipient@example.com'\nmsg['Subject'] = 'Email with attachment'\n\nmsg.attach(MIMEText('Email body', 'plain'))\n\n# Add attachment\nwith open('/path/to/file.pdf', 'rb') as f:\n part = MIMEBase('application', 'octet-stream')\n part.set_payload(f.read())\n encoders.encode_base64(part)\n part.add_header('Content-Disposition', 'attachment; filename=\"file.pdf\"')\n msg.attach(part)\n\nserver = smtplib.SMTP_SSL('smtp.163.com', 465)\nserver.login('sender@163.com', 'password')\nserver.send_message(msg)\nserver.quit()\n```\n\n**⚠️ MML attachment limitations:** The `template send` command with MML format may fail with \"cannot parse MML message: empty body\" when using multipart/attachments. This is a known issue in himalaya v1.1.0. Use Python approach for attachments.\n\n**⚠️ Avoid `message write` for automation:** The `himalaya message write` command requires interactive TUI selection (Edit/Discard/Quit) and will hang in non-interactive environments.\n\n**⚠️ `message send` limitations:** Direct `himalaya message send ` may fail with \"cannot send message without a recipient\" due to header parsing issues. Use `template send` instead.\n\n**Configuration requirement:** Ensure `message.send.save-to-folder` is set in config.toml to avoid \"Folder not exist\" errors:\n\n```toml\n[accounts.163]\n# ... other config ...\nmessage.send.save-to-folder = \"Sent\"\n```\n\nFor 163 mail accounts, create the Sent folder first if it doesn't exist:\n\n```bash\nhimalaya folder create Sent\n```\n\n### Move/Copy Emails\n\nMove to folder:\n\n```bash\nhimalaya message move 42 \"Archive\"\n```\n\nCopy to folder:\n\n```bash\nhimalaya message copy 42 \"Important\"\n```\n\n### Delete an Email\n\n```bash\nhimalaya message delete 42\n```\n\n### Manage Flags\n\nAdd flag:\n\n```bash\nhimalaya flag add 42 --flag seen\n```\n\nRemove flag:\n\n```bash\nhimalaya flag remove 42 --flag seen\n```\n\n## Multiple Accounts\n\nList accounts:\n\n```bash\nhimalaya account list\n```\n\nUse a specific account:\n\n```bash\nhimalaya --account work envelope list\n```\n\n## Attachments\n\nSave attachments from a message:\n\n```bash\nhimalaya attachment download 42\n```\n\nSave to specific directory:\n\n```bash\nhimalaya attachment download 42 --dir ~/Downloads\n```\n\n## Output Formats\n\nMost commands support `--output` for structured output:\n\n```bash\nhimalaya envelope list --output json\nhimalaya envelope list --output plain\n```\n\n## Debugging\n\nEnable debug logging:\n\n```bash\nRUST_LOG=debug himalaya envelope list\n```\n\nFull trace with backtrace:\n\n```bash\nRUST_LOG=trace RUST_BACKTRACE=1 himalaya envelope list\n```\n\n## Tips\n\n- Use `himalaya --help` or `himalaya --help` for detailed usage.\n- Message IDs are relative to the current folder; re-list after folder changes.\n- For composing rich emails with attachments, use MML syntax (see `references/message-composition.md`).\n- Store passwords securely using `pass`, system keyring, or a command that outputs the password.\n- **For automation:** Always use `template write | template send` pipeline with `export EDITOR=cat`.\n- **163 Mail users:** Set `backend.extensions.id.send-after-auth = true` and `message.send.save-to-folder = \"Sent\"` in config.\n- **Folder names:** Use English folder names (e.g., \"Sent\" instead of \"已发送\") for better compatibility.\n" }, { "path": "src/copaw/agents/skills/himalaya/references/configuration.md", "content": "# Himalaya Configuration Reference\n\nConfiguration file location: `~/.config/himalaya/config.toml`\n\n## Minimal IMAP + SMTP Setup\n\n```toml\n[accounts.default]\nemail = \"user@example.com\"\ndisplay-name = \"Your Name\"\ndefault = true\n\n# IMAP backend for reading emails\nbackend.type = \"imap\"\nbackend.host = \"imap.example.com\"\nbackend.port = 993\nbackend.encryption.type = \"tls\"\nbackend.login = \"user@example.com\"\nbackend.auth.type = \"password\"\nbackend.auth.raw = \"your-password\"\n\n# SMTP backend for sending emails\nmessage.send.backend.type = \"smtp\"\nmessage.send.backend.host = \"smtp.example.com\"\nmessage.send.backend.port = 587\nmessage.send.backend.encryption.type = \"start-tls\"\nmessage.send.backend.login = \"user@example.com\"\nmessage.send.backend.auth.type = \"password\"\nmessage.send.backend.auth.raw = \"your-password\"\n```\n\n## Password Options\n\n### Raw password (testing only, not recommended)\n\n```toml\nbackend.auth.raw = \"your-password\"\n```\n\n### Password from command (recommended)\n\n```toml\nbackend.auth.cmd = \"pass show email/imap\"\n# backend.auth.cmd = \"security find-generic-password -a user@example.com -s imap -w\"\n```\n\n### System keyring (requires keyring feature)\n\n```toml\nbackend.auth.keyring = \"imap-example\"\n```\n\nThen run `himalaya account configure ` to store the password.\n\n## Gmail Configuration\n\n```toml\n[accounts.gmail]\nemail = \"you@gmail.com\"\ndisplay-name = \"Your Name\"\ndefault = true\n\nbackend.type = \"imap\"\nbackend.host = \"imap.gmail.com\"\nbackend.port = 993\nbackend.encryption.type = \"tls\"\nbackend.login = \"you@gmail.com\"\nbackend.auth.type = \"password\"\nbackend.auth.cmd = \"pass show google/app-password\"\n\nmessage.send.backend.type = \"smtp\"\nmessage.send.backend.host = \"smtp.gmail.com\"\nmessage.send.backend.port = 587\nmessage.send.backend.encryption.type = \"start-tls\"\nmessage.send.backend.login = \"you@gmail.com\"\nmessage.send.backend.auth.type = \"password\"\nmessage.send.backend.auth.cmd = \"pass show google/app-password\"\n```\n\n**Note:** Gmail requires an App Password if 2FA is enabled.\n\n## iCloud Configuration\n\n```toml\n[accounts.icloud]\nemail = \"you@icloud.com\"\ndisplay-name = \"Your Name\"\n\nbackend.type = \"imap\"\nbackend.host = \"imap.mail.me.com\"\nbackend.port = 993\nbackend.encryption.type = \"tls\"\nbackend.login = \"you@icloud.com\"\nbackend.auth.type = \"password\"\nbackend.auth.cmd = \"pass show icloud/app-password\"\n\nmessage.send.backend.type = \"smtp\"\nmessage.send.backend.host = \"smtp.mail.me.com\"\nmessage.send.backend.port = 587\nmessage.send.backend.encryption.type = \"start-tls\"\nmessage.send.backend.login = \"you@icloud.com\"\nmessage.send.backend.auth.type = \"password\"\nmessage.send.backend.auth.cmd = \"pass show icloud/app-password\"\n```\n\n**Note:** Generate an app-specific password at appleid.apple.com\n\n## Folder Aliases\n\nMap custom folder names:\n\n```toml\n[accounts.default.folder.alias]\ninbox = \"INBOX\"\nsent = \"Sent\"\ndrafts = \"Drafts\"\ntrash = \"Trash\"\n```\n\n## Multiple Accounts\n\n```toml\n[accounts.personal]\nemail = \"personal@example.com\"\ndefault = true\n# ... backend config ...\n\n[accounts.work]\nemail = \"work@company.com\"\n# ... backend config ...\n```\n\nSwitch accounts with `--account`:\n\n```bash\nhimalaya --account work envelope list\n```\n\n## Notmuch Backend (local mail)\n\n```toml\n[accounts.local]\nemail = \"user@example.com\"\n\nbackend.type = \"notmuch\"\nbackend.db-path = \"~/.mail/.notmuch\"\n```\n\n## OAuth2 Authentication (for providers that support it)\n\n```toml\nbackend.auth.type = \"oauth2\"\nbackend.auth.client-id = \"your-client-id\"\nbackend.auth.client-secret.cmd = \"pass show oauth/client-secret\"\nbackend.auth.access-token.cmd = \"pass show oauth/access-token\"\nbackend.auth.refresh-token.cmd = \"pass show oauth/refresh-token\"\nbackend.auth.auth-url = \"https://provider.com/oauth/authorize\"\nbackend.auth.token-url = \"https://provider.com/oauth/token\"\n```\n\n## Additional Options\n\n### Signature\n\n```toml\n[accounts.default]\nsignature = \"Best regards,\\nYour Name\"\nsignature-delim = \"-- \\n\"\n```\n\n### Downloads directory\n\n```toml\n[accounts.default]\ndownloads-dir = \"~/Downloads/himalaya\"\n```\n\n### Editor for composing\n\nSet via environment variable:\n\n```bash\nexport EDITOR=\"vim\"\n```\n" }, { "path": "src/copaw/agents/skills/news/SKILL.md", "content": "---\nname: news\ndescription: \"Look up the latest news for the user from specified news sites. Provides authoritative URLs for politics, finance, society, world, tech, sports, and entertainment. Use browser_use to open each URL and snapshot to get content, then summarize for the user.\"\nmetadata:\n {\n \"builtin_skill_version\": \"1.0\",\n \"copaw\":\n {\n \"emoji\": \"📰\",\n \"requires\": {}\n }\n }\n---\n\n# News Reference\n\nWhen the user asks for \"latest news\", \"what's in the news today\", or \"news in category X\", use the **browser_use** tool with the categories and URLs below: open the page, take a snapshot, then extract headlines and key points from the page content and reply to the user.\n\n## Categories and Sources\n\n| Category | Source | URL |\n|---------------|---------------------------|-----|\n| **Politics** | People's Daily · CPC News | https://cpc.people.com.cn/ |\n| **Finance** | China Economic Net | http://www.ce.cn/ |\n| **Society** | China News · Society | https://www.chinanews.com/society/ |\n| **World** | CGTN | https://www.cgtn.com/ |\n| **Tech** | Science and Technology Daily | https://www.stdaily.com/ |\n| **Sports** | CCTV Sports | https://sports.cctv.com/ |\n| **Entertainment** | Sina Entertainment | https://ent.sina.com.cn/ |\n\n## How to Use (browser_use)\n\n1. **Clarify the user's need**: Determine which category or categories (politics / finance / society / world / tech / sports / entertainment), or pick 1–2 to fetch.\n2. **Pick the URL**: Use the URL from the table for that category; for multiple categories, repeat the steps below for each URL.\n3. **Open the page**: Call **browser_use** with:\n ```json\n {\"action\": \"open\", \"url\": \"https://www.chinanews.com/society/\"}\n ```\n Replace `url` with the corresponding URL from the table.\n4. **Take a snapshot**: In the same session, call **browser_use** again:\n ```json\n {\"action\": \"snapshot\"}\n ```\n Extract headlines, dates, and summaries from the returned page content.\n5. **Summarize the reply**: Organize a short list (headline + one or two sentences + source) by time or importance; if a site is unreachable or times out, say so and suggest another source.\n\n## Notes\n\n- Page structure may change when sites are updated; if extraction fails, say so and suggest the user open the link directly.\n- When visiting multiple categories, run `open` for each URL, then `snapshot`, to avoid mixing content from different pages.\n- You may include the original link in the reply so the user can open it.\n" }, { "path": "src/copaw/agents/skills/pdf/LICENSE.txt", "content": "© 2025 Anthropic, PBC. All rights reserved.\n\nLICENSE: Use of these materials (including all code, prompts, assets, files,\nand other components of this Skill) is governed by your agreement with\nAnthropic regarding use of Anthropic's services. If no separate agreement\nexists, use is governed by Anthropic's Consumer Terms of Service or\nCommercial Terms of Service, as applicable:\nhttps://www.anthropic.com/legal/consumer-terms\nhttps://www.anthropic.com/legal/commercial-terms\nYour applicable agreement is referred to as the \"Agreement.\" \"Services\" are\nas defined in the Agreement.\n\nADDITIONAL RESTRICTIONS: Notwithstanding anything in the Agreement to the\ncontrary, users may not:\n\n- Extract these materials from the Services or retain copies of these\n materials outside the Services\n- Reproduce or copy these materials, except for temporary copies created\n automatically during authorized use of the Services\n- Create derivative works based on these materials\n- Distribute, sublicense, or transfer these materials to any third party\n- Make, offer to sell, sell, or import any inventions embodied in these\n materials\n- Reverse engineer, decompile, or disassemble these materials\n\nThe receipt, viewing, or possession of these materials does not convey or\nimply any license or right beyond those expressly granted above.\n\nAnthropic retains all right, title, and interest in these materials,\nincluding all copyrights, patents, and other intellectual property rights.\n" }, { "path": "src/copaw/agents/skills/pdf/SKILL.md", "content": "---\nname: pdf\ndescription: Use this skill whenever the user wants to do anything with PDF files. This includes reading or extracting text/tables from PDFs, combining or merging multiple PDFs into one, splitting PDFs apart, rotating pages, adding watermarks, creating new PDFs, filling PDF forms, encrypting/decrypting PDFs, extracting images, and OCR on scanned PDFs to make them searchable. If the user mentions a .pdf file or asks to produce one, use this skill.\nlicense: Proprietary. LICENSE.txt has complete terms\nmetadata: { \"builtin_skill_version\": \"1.0\" }\n---\n\n> **Important:** All `scripts/` paths are relative to this skill directory.\n> Run with: `cd {this_skill_dir} && python scripts/...`\n> Or use the `cwd` parameter of `execute_shell_command`.\n\n# PDF Processing Guide\n\n## Prerequisites\n\n- **pypdf**: core PDF reading and writing\n- **pdfplumber**: text and table extraction\n- **reportlab**: PDF creation\n- **pdftotext** (poppler-utils): command-line text extraction\n- **pdftoppm** (poppler-utils): PDF-to-image conversion\n- **qpdf**: PDF manipulation (merge, split, rotate, decrypt)\n\n## Overview\n\nThis guide covers essential PDF processing operations using Python libraries and command-line tools. For advanced features, JavaScript libraries, and detailed examples, see REFERENCE.md. If you need to fill out a PDF form, read FORMS.md and follow its instructions.\n\n## Quick Start\n\n```python\nfrom pypdf import PdfReader, PdfWriter\n\n# Read a PDF\nreader = PdfReader(\"document.pdf\")\nprint(f\"Pages: {len(reader.pages)}\")\n\n# Extract text\ntext = \"\"\nfor page in reader.pages:\n text += page.extract_text()\n```\n\n## Python Libraries\n\n### pypdf - Basic Operations\n\n#### Merge PDFs\n```python\nfrom pypdf import PdfWriter, PdfReader\n\nwriter = PdfWriter()\nfor pdf_file in [\"doc1.pdf\", \"doc2.pdf\", \"doc3.pdf\"]:\n reader = PdfReader(pdf_file)\n for page in reader.pages:\n writer.add_page(page)\n\nwith open(\"merged.pdf\", \"wb\") as output:\n writer.write(output)\n```\n\n#### Split PDF\n```python\nreader = PdfReader(\"input.pdf\")\nfor i, page in enumerate(reader.pages):\n writer = PdfWriter()\n writer.add_page(page)\n with open(f\"page_{i+1}.pdf\", \"wb\") as output:\n writer.write(output)\n```\n\n#### Extract Metadata\n```python\nreader = PdfReader(\"document.pdf\")\nmeta = reader.metadata\nprint(f\"Title: {meta.title}\")\nprint(f\"Author: {meta.author}\")\nprint(f\"Subject: {meta.subject}\")\nprint(f\"Creator: {meta.creator}\")\n```\n\n#### Rotate Pages\n```python\nreader = PdfReader(\"input.pdf\")\nwriter = PdfWriter()\n\npage = reader.pages[0]\npage.rotate(90) # Rotate 90 degrees clockwise\nwriter.add_page(page)\n\nwith open(\"rotated.pdf\", \"wb\") as output:\n writer.write(output)\n```\n\n### pdfplumber - Text and Table Extraction\n\n#### Extract Text with Layout\n```python\nimport pdfplumber\n\nwith pdfplumber.open(\"document.pdf\") as pdf:\n for page in pdf.pages:\n text = page.extract_text()\n print(text)\n```\n\n#### Extract Tables\n```python\nwith pdfplumber.open(\"document.pdf\") as pdf:\n for i, page in enumerate(pdf.pages):\n tables = page.extract_tables()\n for j, table in enumerate(tables):\n print(f\"Table {j+1} on page {i+1}:\")\n for row in table:\n print(row)\n```\n\n#### Advanced Table Extraction\n```python\nimport pandas as pd\n\nwith pdfplumber.open(\"document.pdf\") as pdf:\n all_tables = []\n for page in pdf.pages:\n tables = page.extract_tables()\n for table in tables:\n if table: # Check if table is not empty\n df = pd.DataFrame(table[1:], columns=table[0])\n all_tables.append(df)\n\n# Combine all tables\nif all_tables:\n combined_df = pd.concat(all_tables, ignore_index=True)\n combined_df.to_excel(\"extracted_tables.xlsx\", index=False)\n```\n\n### reportlab - Create PDFs\n\n#### Basic PDF Creation\n```python\nfrom reportlab.lib.pagesizes import letter\nfrom reportlab.pdfgen import canvas\n\nc = canvas.Canvas(\"hello.pdf\", pagesize=letter)\nwidth, height = letter\n\n# Add text\nc.drawString(100, height - 100, \"Hello World!\")\nc.drawString(100, height - 120, \"This is a PDF created with reportlab\")\n\n# Add a line\nc.line(100, height - 140, 400, height - 140)\n\n# Save\nc.save()\n```\n\n#### Create PDF with Multiple Pages\n```python\nfrom reportlab.lib.pagesizes import letter\nfrom reportlab.platypus import SimpleDocTemplate, Paragraph, Spacer, PageBreak\nfrom reportlab.lib.styles import getSampleStyleSheet\n\ndoc = SimpleDocTemplate(\"report.pdf\", pagesize=letter)\nstyles = getSampleStyleSheet()\nstory = []\n\n# Add content\ntitle = Paragraph(\"Report Title\", styles['Title'])\nstory.append(title)\nstory.append(Spacer(1, 12))\n\nbody = Paragraph(\"This is the body of the report. \" * 20, styles['Normal'])\nstory.append(body)\nstory.append(PageBreak())\n\n# Page 2\nstory.append(Paragraph(\"Page 2\", styles['Heading1']))\nstory.append(Paragraph(\"Content for page 2\", styles['Normal']))\n\n# Build PDF\ndoc.build(story)\n```\n\n#### Subscripts and Superscripts\n\n**IMPORTANT**: Never use Unicode subscript/superscript characters (₀₁₂₃₄₅₆₇₈₉, ⁰¹²³⁴⁵⁶⁷⁸⁹) in ReportLab PDFs. The built-in fonts do not include these glyphs, causing them to render as solid black boxes.\n\nInstead, use ReportLab's XML markup tags in Paragraph objects:\n```python\nfrom reportlab.platypus import Paragraph\nfrom reportlab.lib.styles import getSampleStyleSheet\n\nstyles = getSampleStyleSheet()\n\n# Subscripts: use tag\nchemical = Paragraph(\"H2O\", styles['Normal'])\n\n# Superscripts: use tag\nsquared = Paragraph(\"x2 + y2\", styles['Normal'])\n```\n\nFor canvas-drawn text (not Paragraph objects), manually adjust font the size and position rather than using Unicode subscripts/superscripts.\n\n## Command-Line Tools\n\n### pdftotext (poppler-utils)\n```bash\n# Extract text\npdftotext input.pdf output.txt\n\n# Extract text preserving layout\npdftotext -layout input.pdf output.txt\n\n# Extract specific pages\npdftotext -f 1 -l 5 input.pdf output.txt # Pages 1-5\n```\n\n### qpdf\n```bash\n# Merge PDFs\nqpdf --empty --pages file1.pdf file2.pdf -- merged.pdf\n\n# Split pages\nqpdf input.pdf --pages . 1-5 -- pages1-5.pdf\nqpdf input.pdf --pages . 6-10 -- pages6-10.pdf\n\n# Rotate pages\nqpdf input.pdf output.pdf --rotate=+90:1 # Rotate page 1 by 90 degrees\n\n# Remove password\nqpdf --password=mypassword --decrypt encrypted.pdf decrypted.pdf\n```\n\n### pdftk (if available)\n```bash\n# Merge\npdftk file1.pdf file2.pdf cat output merged.pdf\n\n# Split\npdftk input.pdf burst\n\n# Rotate\npdftk input.pdf rotate 1east output rotated.pdf\n```\n\n## Common Tasks\n\n### Extract Text from Scanned PDFs\n```python\n# Requires: pip install pytesseract pdf2image\nimport pytesseract\nfrom pdf2image import convert_from_path\n\n# Convert PDF to images\nimages = convert_from_path('scanned.pdf')\n\n# OCR each page\ntext = \"\"\nfor i, image in enumerate(images):\n text += f\"Page {i+1}:\\n\"\n text += pytesseract.image_to_string(image)\n text += \"\\n\\n\"\n\nprint(text)\n```\n\n### Add Watermark\n```python\nfrom pypdf import PdfReader, PdfWriter\n\n# Create watermark (or load existing)\nwatermark = PdfReader(\"watermark.pdf\").pages[0]\n\n# Apply to all pages\nreader = PdfReader(\"document.pdf\")\nwriter = PdfWriter()\n\nfor page in reader.pages:\n page.merge_page(watermark)\n writer.add_page(page)\n\nwith open(\"watermarked.pdf\", \"wb\") as output:\n writer.write(output)\n```\n\n### Extract Images\n```bash\n# Using pdfimages (poppler-utils)\npdfimages -j input.pdf output_prefix\n\n# This extracts all images as output_prefix-000.jpg, output_prefix-001.jpg, etc.\n```\n\n### Password Protection\n```python\nfrom pypdf import PdfReader, PdfWriter\n\nreader = PdfReader(\"input.pdf\")\nwriter = PdfWriter()\n\nfor page in reader.pages:\n writer.add_page(page)\n\n# Add password\nwriter.encrypt(\"userpassword\", \"ownerpassword\")\n\nwith open(\"encrypted.pdf\", \"wb\") as output:\n writer.write(output)\n```\n\n## Quick Reference\n\n| Task | Best Tool | Command/Code |\n|------|-----------|--------------|\n| Merge PDFs | pypdf | `writer.add_page(page)` |\n| Split PDFs | pypdf | One page per file |\n| Extract text | pdfplumber | `page.extract_text()` |\n| Extract tables | pdfplumber | `page.extract_tables()` |\n| Create PDFs | reportlab | Canvas or Platypus |\n| Command line merge | qpdf | `qpdf --empty --pages ...` |\n| OCR scanned PDFs | pytesseract | Convert to image first |\n| Fill PDF forms | pdf-lib or pypdf (see FORMS.md) | See FORMS.md |\n\n## Next Steps\n\n- For advanced pypdfium2 usage, see REFERENCE.md\n- For JavaScript libraries (pdf-lib), see REFERENCE.md\n- If you need to fill out a PDF form, follow the instructions in FORMS.md\n- For troubleshooting guides, see REFERENCE.md\n" }, { "path": "src/copaw/agents/skills/pdf/forms.md", "content": "> **Important:** All `scripts/` paths are relative to the skill directory (where SKILL.md is).\n> Run with: `cd {this_skill_dir} && python scripts/...`\n> Or use the `cwd` parameter of `execute_shell_command`.\n\n**CRITICAL: You MUST complete these steps in order. Do not skip ahead to writing code.**\n\nIf you need to fill out a PDF form, first check to see if the PDF has fillable form fields. Run this script from this file's directory:\n `python scripts/check_fillable_fields `, and depending on the result go to either the \"Fillable fields\" or \"Non-fillable fields\" and follow those instructions.\n\n# Fillable fields\nIf the PDF has fillable form fields:\n- Run this script from this file's directory: `python scripts/extract_form_field_info.py `. It will create a JSON file with a list of fields in this format:\n```\n[\n {\n \"field_id\": (unique ID for the field),\n \"page\": (page number, 1-based),\n \"rect\": ([left, bottom, right, top] bounding box in PDF coordinates, y=0 is the bottom of the page),\n \"type\": (\"text\", \"checkbox\", \"radio_group\", or \"choice\"),\n },\n // Checkboxes have \"checked_value\" and \"unchecked_value\" properties:\n {\n \"field_id\": (unique ID for the field),\n \"page\": (page number, 1-based),\n \"type\": \"checkbox\",\n \"checked_value\": (Set the field to this value to check the checkbox),\n \"unchecked_value\": (Set the field to this value to uncheck the checkbox),\n },\n // Radio groups have a \"radio_options\" list with the possible choices.\n {\n \"field_id\": (unique ID for the field),\n \"page\": (page number, 1-based),\n \"type\": \"radio_group\",\n \"radio_options\": [\n {\n \"value\": (set the field to this value to select this radio option),\n \"rect\": (bounding box for the radio button for this option)\n },\n // Other radio options\n ]\n },\n // Multiple choice fields have a \"choice_options\" list with the possible choices:\n {\n \"field_id\": (unique ID for the field),\n \"page\": (page number, 1-based),\n \"type\": \"choice\",\n \"choice_options\": [\n {\n \"value\": (set the field to this value to select this option),\n \"text\": (display text of the option)\n },\n // Other choice options\n ],\n }\n]\n```\n- Convert the PDF to PNGs (one image for each page) with this script (run from this file's directory):\n`python scripts/convert_pdf_to_images.py `\nThen analyze the images to determine the purpose of each form field (make sure to convert the bounding box PDF coordinates to image coordinates).\n- Create a `field_values.json` file in this format with the values to be entered for each field:\n```\n[\n {\n \"field_id\": \"last_name\", // Must match the field_id from `extract_form_field_info.py`\n \"description\": \"The user's last name\",\n \"page\": 1, // Must match the \"page\" value in field_info.json\n \"value\": \"Simpson\"\n },\n {\n \"field_id\": \"Checkbox12\",\n \"description\": \"Checkbox to be checked if the user is 18 or over\",\n \"page\": 1,\n \"value\": \"/On\" // If this is a checkbox, use its \"checked_value\" value to check it. If it's a radio button group, use one of the \"value\" values in \"radio_options\".\n },\n // more fields\n]\n```\n- Run the `fill_fillable_fields.py` script from this file's directory to create a filled-in PDF:\n`python scripts/fill_fillable_fields.py `\nThis script will verify that the field IDs and values you provide are valid; if it prints error messages, correct the appropriate fields and try again.\n\n# Non-fillable fields\nIf the PDF doesn't have fillable form fields, you'll add text annotations. First try to extract coordinates from the PDF structure (more accurate), then fall back to visual estimation if needed.\n\n## Step 1: Try Structure Extraction First\n\nRun this script to extract text labels, lines, and checkboxes with their exact PDF coordinates:\n`python scripts/extract_form_structure.py form_structure.json`\n\nThis creates a JSON file containing:\n- **labels**: Every text element with exact coordinates (x0, top, x1, bottom in PDF points)\n- **lines**: Horizontal lines that define row boundaries\n- **checkboxes**: Small square rectangles that are checkboxes (with center coordinates)\n- **row_boundaries**: Row top/bottom positions calculated from horizontal lines\n\n**Check the results**: If `form_structure.json` has meaningful labels (text elements that correspond to form fields), use **Approach A: Structure-Based Coordinates**. If the PDF is scanned/image-based and has few or no labels, use **Approach B: Visual Estimation**.\n\n---\n\n## Approach A: Structure-Based Coordinates (Preferred)\n\nUse this when `extract_form_structure.py` found text labels in the PDF.\n\n### A.1: Analyze the Structure\n\nRead form_structure.json and identify:\n\n1. **Label groups**: Adjacent text elements that form a single label (e.g., \"Last\" + \"Name\")\n2. **Row structure**: Labels with similar `top` values are in the same row\n3. **Field columns**: Entry areas start after label ends (x0 = label.x1 + gap)\n4. **Checkboxes**: Use the checkbox coordinates directly from the structure\n\n**Coordinate system**: PDF coordinates where y=0 is at TOP of page, y increases downward.\n\n### A.2: Check for Missing Elements\n\nThe structure extraction may not detect all form elements. Common cases:\n- **Circular checkboxes**: Only square rectangles are detected as checkboxes\n- **Complex graphics**: Decorative elements or non-standard form controls\n- **Faded or light-colored elements**: May not be extracted\n\nIf you see form fields in the PDF images that aren't in form_structure.json, you'll need to use **visual analysis** for those specific fields (see \"Hybrid Approach\" below).\n\n### A.3: Create fields.json with PDF Coordinates\n\nFor each field, calculate entry coordinates from the extracted structure:\n\n**Text fields:**\n- entry x0 = label x1 + 5 (small gap after label)\n- entry x1 = next label's x0, or row boundary\n- entry top = same as label top\n- entry bottom = row boundary line below, or label bottom + row_height\n\n**Checkboxes:**\n- Use the checkbox rectangle coordinates directly from form_structure.json\n- entry_bounding_box = [checkbox.x0, checkbox.top, checkbox.x1, checkbox.bottom]\n\nCreate fields.json using `pdf_width` and `pdf_height` (signals PDF coordinates):\n```json\n{\n \"pages\": [\n {\"page_number\": 1, \"pdf_width\": 612, \"pdf_height\": 792}\n ],\n \"form_fields\": [\n {\n \"page_number\": 1,\n \"description\": \"Last name entry field\",\n \"field_label\": \"Last Name\",\n \"label_bounding_box\": [43, 63, 87, 73],\n \"entry_bounding_box\": [92, 63, 260, 79],\n \"entry_text\": {\"text\": \"Smith\", \"font_size\": 10}\n },\n {\n \"page_number\": 1,\n \"description\": \"US Citizen Yes checkbox\",\n \"field_label\": \"Yes\",\n \"label_bounding_box\": [260, 200, 280, 210],\n \"entry_bounding_box\": [285, 197, 292, 205],\n \"entry_text\": {\"text\": \"X\"}\n }\n ]\n}\n```\n\n**Important**: Use `pdf_width`/`pdf_height` and coordinates directly from form_structure.json.\n\n### A.4: Validate Bounding Boxes\n\nBefore filling, check your bounding boxes for errors:\n`python scripts/check_bounding_boxes.py fields.json`\n\nThis checks for intersecting bounding boxes and entry boxes that are too small for the font size. Fix any reported errors before filling.\n\n---\n\n## Approach B: Visual Estimation (Fallback)\n\nUse this when the PDF is scanned/image-based and structure extraction found no usable text labels (e.g., all text shows as \"(cid:X)\" patterns).\n\n### B.1: Convert PDF to Images\n\n`python scripts/convert_pdf_to_images.py `\n\n### B.2: Initial Field Identification\n\nExamine each page image to identify form sections and get **rough estimates** of field locations:\n- Form field labels and their approximate positions\n- Entry areas (lines, boxes, or blank spaces for text input)\n- Checkboxes and their approximate locations\n\nFor each field, note approximate pixel coordinates (they don't need to be precise yet).\n\n### B.3: Zoom Refinement (CRITICAL for accuracy)\n\nFor each field, crop a region around the estimated position to refine coordinates precisely.\n\n**Create a zoomed crop using ImageMagick:**\n```bash\nmagick -crop x++ +repage \n```\n\nWhere:\n- `, ` = top-left corner of crop region (use your rough estimate minus padding)\n- `, ` = size of crop region (field area plus ~50px padding on each side)\n\n**Example:** To refine a \"Name\" field estimated around (100, 150):\n```bash\nmagick images_dir/page_1.png -crop 300x80+50+120 +repage crops/name_field.png\n```\n\n(Note: if the `magick` command isn't available, try `convert` with the same arguments).\n\n**Examine the cropped image** to determine precise coordinates:\n1. Identify the exact pixel where the entry area begins (after the label)\n2. Identify where the entry area ends (before next field or edge)\n3. Identify the top and bottom of the entry line/box\n\n**Convert crop coordinates back to full image coordinates:**\n- full_x = crop_x + crop_offset_x\n- full_y = crop_y + crop_offset_y\n\nExample: If the crop started at (50, 120) and the entry box starts at (52, 18) within the crop:\n- entry_x0 = 52 + 50 = 102\n- entry_top = 18 + 120 = 138\n\n**Repeat for each field**, grouping nearby fields into single crops when possible.\n\n### B.4: Create fields.json with Refined Coordinates\n\nCreate fields.json using `image_width` and `image_height` (signals image coordinates):\n```json\n{\n \"pages\": [\n {\"page_number\": 1, \"image_width\": 1700, \"image_height\": 2200}\n ],\n \"form_fields\": [\n {\n \"page_number\": 1,\n \"description\": \"Last name entry field\",\n \"field_label\": \"Last Name\",\n \"label_bounding_box\": [120, 175, 242, 198],\n \"entry_bounding_box\": [255, 175, 720, 218],\n \"entry_text\": {\"text\": \"Smith\", \"font_size\": 10}\n }\n ]\n}\n```\n\n**Important**: Use `image_width`/`image_height` and the refined pixel coordinates from the zoom analysis.\n\n### B.5: Validate Bounding Boxes\n\nBefore filling, check your bounding boxes for errors:\n`python scripts/check_bounding_boxes.py fields.json`\n\nThis checks for intersecting bounding boxes and entry boxes that are too small for the font size. Fix any reported errors before filling.\n\n---\n\n## Hybrid Approach: Structure + Visual\n\nUse this when structure extraction works for most fields but misses some elements (e.g., circular checkboxes, unusual form controls).\n\n1. **Use Approach A** for fields that were detected in form_structure.json\n2. **Convert PDF to images** for visual analysis of missing fields\n3. **Use zoom refinement** (from Approach B) for the missing fields\n4. **Combine coordinates**: For fields from structure extraction, use `pdf_width`/`pdf_height`. For visually-estimated fields, you must convert image coordinates to PDF coordinates:\n - pdf_x = image_x * (pdf_width / image_width)\n - pdf_y = image_y * (pdf_height / image_height)\n5. **Use a single coordinate system** in fields.json - convert all to PDF coordinates with `pdf_width`/`pdf_height`\n\n---\n\n## Step 2: Validate Before Filling\n\n**Always validate bounding boxes before filling:**\n`python scripts/check_bounding_boxes.py fields.json`\n\nThis checks for:\n- Intersecting bounding boxes (which would cause overlapping text)\n- Entry boxes that are too small for the specified font size\n\nFix any reported errors in fields.json before proceeding.\n\n## Step 3: Fill the Form\n\nThe fill script auto-detects the coordinate system and handles conversion:\n`python scripts/fill_pdf_form_with_annotations.py fields.json `\n\n## Step 4: Verify Output\n\nConvert the filled PDF to images and verify text placement:\n`python scripts/convert_pdf_to_images.py `\n\nIf text is mispositioned:\n- **Approach A**: Check that you're using PDF coordinates from form_structure.json with `pdf_width`/`pdf_height`\n- **Approach B**: Check that image dimensions match and coordinates are accurate pixels\n- **Hybrid**: Ensure coordinate conversions are correct for visually-estimated fields\n" }, { "path": "src/copaw/agents/skills/pdf/reference.md", "content": "# PDF Processing Advanced Reference\n\nThis document contains advanced PDF processing features, detailed examples, and additional libraries not covered in the main skill instructions.\n\n## pypdfium2 Library (Apache/BSD License)\n\n### Overview\npypdfium2 is a Python binding for PDFium (Chromium's PDF library). It's excellent for fast PDF rendering, image generation, and serves as a PyMuPDF replacement.\n\n### Render PDF to Images\n```python\nimport pypdfium2 as pdfium\nfrom PIL import Image\n\n# Load PDF\npdf = pdfium.PdfDocument(\"document.pdf\")\n\n# Render page to image\npage = pdf[0] # First page\nbitmap = page.render(\n scale=2.0, # Higher resolution\n rotation=0 # No rotation\n)\n\n# Convert to PIL Image\nimg = bitmap.to_pil()\nimg.save(\"page_1.png\", \"PNG\")\n\n# Process multiple pages\nfor i, page in enumerate(pdf):\n bitmap = page.render(scale=1.5)\n img = bitmap.to_pil()\n img.save(f\"page_{i+1}.jpg\", \"JPEG\", quality=90)\n```\n\n### Extract Text with pypdfium2\n```python\nimport pypdfium2 as pdfium\n\npdf = pdfium.PdfDocument(\"document.pdf\")\nfor i, page in enumerate(pdf):\n text = page.get_text()\n print(f\"Page {i+1} text length: {len(text)} chars\")\n```\n\n## JavaScript Libraries\n\n### pdf-lib (MIT License)\n\npdf-lib is a powerful JavaScript library for creating and modifying PDF documents in any JavaScript environment.\n\n#### Load and Manipulate Existing PDF\n```javascript\nimport { PDFDocument } from 'pdf-lib';\nimport fs from 'fs';\n\nasync function manipulatePDF() {\n // Load existing PDF\n const existingPdfBytes = fs.readFileSync('input.pdf');\n const pdfDoc = await PDFDocument.load(existingPdfBytes);\n\n // Get page count\n const pageCount = pdfDoc.getPageCount();\n console.log(`Document has ${pageCount} pages`);\n\n // Add new page\n const newPage = pdfDoc.addPage([600, 400]);\n newPage.drawText('Added by pdf-lib', {\n x: 100,\n y: 300,\n size: 16\n });\n\n // Save modified PDF\n const pdfBytes = await pdfDoc.save();\n fs.writeFileSync('modified.pdf', pdfBytes);\n}\n```\n\n#### Create Complex PDFs from Scratch\n```javascript\nimport { PDFDocument, rgb, StandardFonts } from 'pdf-lib';\nimport fs from 'fs';\n\nasync function createPDF() {\n const pdfDoc = await PDFDocument.create();\n\n // Add fonts\n const helveticaFont = await pdfDoc.embedFont(StandardFonts.Helvetica);\n const helveticaBold = await pdfDoc.embedFont(StandardFonts.HelveticaBold);\n\n // Add page\n const page = pdfDoc.addPage([595, 842]); // A4 size\n const { width, height } = page.getSize();\n\n // Add text with styling\n page.drawText('Invoice #12345', {\n x: 50,\n y: height - 50,\n size: 18,\n font: helveticaBold,\n color: rgb(0.2, 0.2, 0.8)\n });\n\n // Add rectangle (header background)\n page.drawRectangle({\n x: 40,\n y: height - 100,\n width: width - 80,\n height: 30,\n color: rgb(0.9, 0.9, 0.9)\n });\n\n // Add table-like content\n const items = [\n ['Item', 'Qty', 'Price', 'Total'],\n ['Widget', '2', '$50', '$100'],\n ['Gadget', '1', '$75', '$75']\n ];\n\n let yPos = height - 150;\n items.forEach(row => {\n let xPos = 50;\n row.forEach(cell => {\n page.drawText(cell, {\n x: xPos,\n y: yPos,\n size: 12,\n font: helveticaFont\n });\n xPos += 120;\n });\n yPos -= 25;\n });\n\n const pdfBytes = await pdfDoc.save();\n fs.writeFileSync('created.pdf', pdfBytes);\n}\n```\n\n#### Advanced Merge and Split Operations\n```javascript\nimport { PDFDocument } from 'pdf-lib';\nimport fs from 'fs';\n\nasync function mergePDFs() {\n // Create new document\n const mergedPdf = await PDFDocument.create();\n\n // Load source PDFs\n const pdf1Bytes = fs.readFileSync('doc1.pdf');\n const pdf2Bytes = fs.readFileSync('doc2.pdf');\n\n const pdf1 = await PDFDocument.load(pdf1Bytes);\n const pdf2 = await PDFDocument.load(pdf2Bytes);\n\n // Copy pages from first PDF\n const pdf1Pages = await mergedPdf.copyPages(pdf1, pdf1.getPageIndices());\n pdf1Pages.forEach(page => mergedPdf.addPage(page));\n\n // Copy specific pages from second PDF (pages 0, 2, 4)\n const pdf2Pages = await mergedPdf.copyPages(pdf2, [0, 2, 4]);\n pdf2Pages.forEach(page => mergedPdf.addPage(page));\n\n const mergedPdfBytes = await mergedPdf.save();\n fs.writeFileSync('merged.pdf', mergedPdfBytes);\n}\n```\n\n### pdfjs-dist (Apache License)\n\nPDF.js is Mozilla's JavaScript library for rendering PDFs in the browser.\n\n#### Basic PDF Loading and Rendering\n```javascript\nimport * as pdfjsLib from 'pdfjs-dist';\n\n// Configure worker (important for performance)\npdfjsLib.GlobalWorkerOptions.workerSrc = './pdf.worker.js';\n\nasync function renderPDF() {\n // Load PDF\n const loadingTask = pdfjsLib.getDocument('document.pdf');\n const pdf = await loadingTask.promise;\n\n console.log(`Loaded PDF with ${pdf.numPages} pages`);\n\n // Get first page\n const page = await pdf.getPage(1);\n const viewport = page.getViewport({ scale: 1.5 });\n\n // Render to canvas\n const canvas = document.createElement('canvas');\n const context = canvas.getContext('2d');\n canvas.height = viewport.height;\n canvas.width = viewport.width;\n\n const renderContext = {\n canvasContext: context,\n viewport: viewport\n };\n\n await page.render(renderContext).promise;\n document.body.appendChild(canvas);\n}\n```\n\n#### Extract Text with Coordinates\n```javascript\nimport * as pdfjsLib from 'pdfjs-dist';\n\nasync function extractText() {\n const loadingTask = pdfjsLib.getDocument('document.pdf');\n const pdf = await loadingTask.promise;\n\n let fullText = '';\n\n // Extract text from all pages\n for (let i = 1; i <= pdf.numPages; i++) {\n const page = await pdf.getPage(i);\n const textContent = await page.getTextContent();\n\n const pageText = textContent.items\n .map(item => item.str)\n .join(' ');\n\n fullText += `\\n--- Page ${i} ---\\n${pageText}`;\n\n // Get text with coordinates for advanced processing\n const textWithCoords = textContent.items.map(item => ({\n text: item.str,\n x: item.transform[4],\n y: item.transform[5],\n width: item.width,\n height: item.height\n }));\n }\n\n console.log(fullText);\n return fullText;\n}\n```\n\n#### Extract Annotations and Forms\n```javascript\nimport * as pdfjsLib from 'pdfjs-dist';\n\nasync function extractAnnotations() {\n const loadingTask = pdfjsLib.getDocument('annotated.pdf');\n const pdf = await loadingTask.promise;\n\n for (let i = 1; i <= pdf.numPages; i++) {\n const page = await pdf.getPage(i);\n const annotations = await page.getAnnotations();\n\n annotations.forEach(annotation => {\n console.log(`Annotation type: ${annotation.subtype}`);\n console.log(`Content: ${annotation.contents}`);\n console.log(`Coordinates: ${JSON.stringify(annotation.rect)}`);\n });\n }\n}\n```\n\n## Advanced Command-Line Operations\n\n### poppler-utils Advanced Features\n\n#### Extract Text with Bounding Box Coordinates\n```bash\n# Extract text with bounding box coordinates (essential for structured data)\npdftotext -bbox-layout document.pdf output.xml\n\n# The XML output contains precise coordinates for each text element\n```\n\n#### Advanced Image Conversion\n```bash\n# Convert to PNG images with specific resolution\npdftoppm -png -r 300 document.pdf output_prefix\n\n# Convert specific page range with high resolution\npdftoppm -png -r 600 -f 1 -l 3 document.pdf high_res_pages\n\n# Convert to JPEG with quality setting\npdftoppm -jpeg -jpegopt quality=85 -r 200 document.pdf jpeg_output\n```\n\n#### Extract Embedded Images\n```bash\n# Extract all embedded images with metadata\npdfimages -j -p document.pdf page_images\n\n# List image info without extracting\npdfimages -list document.pdf\n\n# Extract images in their original format\npdfimages -all document.pdf images/img\n```\n\n### qpdf Advanced Features\n\n#### Complex Page Manipulation\n```bash\n# Split PDF into groups of pages\nqpdf --split-pages=3 input.pdf output_group_%02d.pdf\n\n# Extract specific pages with complex ranges\nqpdf input.pdf --pages input.pdf 1,3-5,8,10-end -- extracted.pdf\n\n# Merge specific pages from multiple PDFs\nqpdf --empty --pages doc1.pdf 1-3 doc2.pdf 5-7 doc3.pdf 2,4 -- combined.pdf\n```\n\n#### PDF Optimization and Repair\n```bash\n# Optimize PDF for web (linearize for streaming)\nqpdf --linearize input.pdf optimized.pdf\n\n# Remove unused objects and compress\nqpdf --optimize-level=all input.pdf compressed.pdf\n\n# Attempt to repair corrupted PDF structure\nqpdf --check input.pdf\nqpdf --fix-qdf damaged.pdf repaired.pdf\n\n# Show detailed PDF structure for debugging\nqpdf --show-all-pages input.pdf > structure.txt\n```\n\n#### Advanced Encryption\n```bash\n# Add password protection with specific permissions\nqpdf --encrypt user_pass owner_pass 256 --print=none --modify=none -- input.pdf encrypted.pdf\n\n# Check encryption status\nqpdf --show-encryption encrypted.pdf\n\n# Remove password protection (requires password)\nqpdf --password=secret123 --decrypt encrypted.pdf decrypted.pdf\n```\n\n## Advanced Python Techniques\n\n### pdfplumber Advanced Features\n\n#### Extract Text with Precise Coordinates\n```python\nimport pdfplumber\n\nwith pdfplumber.open(\"document.pdf\") as pdf:\n page = pdf.pages[0]\n \n # Extract all text with coordinates\n chars = page.chars\n for char in chars[:10]: # First 10 characters\n print(f\"Char: '{char['text']}' at x:{char['x0']:.1f} y:{char['y0']:.1f}\")\n \n # Extract text by bounding box (left, top, right, bottom)\n bbox_text = page.within_bbox((100, 100, 400, 200)).extract_text()\n```\n\n#### Advanced Table Extraction with Custom Settings\n```python\nimport pdfplumber\nimport pandas as pd\n\nwith pdfplumber.open(\"complex_table.pdf\") as pdf:\n page = pdf.pages[0]\n \n # Extract tables with custom settings for complex layouts\n table_settings = {\n \"vertical_strategy\": \"lines\",\n \"horizontal_strategy\": \"lines\",\n \"snap_tolerance\": 3,\n \"intersection_tolerance\": 15\n }\n tables = page.extract_tables(table_settings)\n \n # Visual debugging for table extraction\n img = page.to_image(resolution=150)\n img.save(\"debug_layout.png\")\n```\n\n### reportlab Advanced Features\n\n#### Create Professional Reports with Tables\n```python\nfrom reportlab.platypus import SimpleDocTemplate, Table, TableStyle, Paragraph\nfrom reportlab.lib.styles import getSampleStyleSheet\nfrom reportlab.lib import colors\n\n# Sample data\ndata = [\n ['Product', 'Q1', 'Q2', 'Q3', 'Q4'],\n ['Widgets', '120', '135', '142', '158'],\n ['Gadgets', '85', '92', '98', '105']\n]\n\n# Create PDF with table\ndoc = SimpleDocTemplate(\"report.pdf\")\nelements = []\n\n# Add title\nstyles = getSampleStyleSheet()\ntitle = Paragraph(\"Quarterly Sales Report\", styles['Title'])\nelements.append(title)\n\n# Add table with advanced styling\ntable = Table(data)\ntable.setStyle(TableStyle([\n ('BACKGROUND', (0, 0), (-1, 0), colors.grey),\n ('TEXTCOLOR', (0, 0), (-1, 0), colors.whitesmoke),\n ('ALIGN', (0, 0), (-1, -1), 'CENTER'),\n ('FONTNAME', (0, 0), (-1, 0), 'Helvetica-Bold'),\n ('FONTSIZE', (0, 0), (-1, 0), 14),\n ('BOTTOMPADDING', (0, 0), (-1, 0), 12),\n ('BACKGROUND', (0, 1), (-1, -1), colors.beige),\n ('GRID', (0, 0), (-1, -1), 1, colors.black)\n]))\nelements.append(table)\n\ndoc.build(elements)\n```\n\n## Complex Workflows\n\n### Extract Figures/Images from PDF\n\n#### Method 1: Using pdfimages (fastest)\n```bash\n# Extract all images with original quality\npdfimages -all document.pdf images/img\n```\n\n#### Method 2: Using pypdfium2 + Image Processing\n```python\nimport pypdfium2 as pdfium\nfrom PIL import Image\nimport numpy as np\n\ndef extract_figures(pdf_path, output_dir):\n pdf = pdfium.PdfDocument(pdf_path)\n \n for page_num, page in enumerate(pdf):\n # Render high-resolution page\n bitmap = page.render(scale=3.0)\n img = bitmap.to_pil()\n \n # Convert to numpy for processing\n img_array = np.array(img)\n \n # Simple figure detection (non-white regions)\n mask = np.any(img_array != [255, 255, 255], axis=2)\n \n # Find contours and extract bounding boxes\n # (This is simplified - real implementation would need more sophisticated detection)\n \n # Save detected figures\n # ... implementation depends on specific needs\n```\n\n### Batch PDF Processing with Error Handling\n```python\nimport os\nimport glob\nfrom pypdf import PdfReader, PdfWriter\nimport logging\n\nlogging.basicConfig(level=logging.INFO)\nlogger = logging.getLogger(__name__)\n\ndef batch_process_pdfs(input_dir, operation='merge'):\n pdf_files = glob.glob(os.path.join(input_dir, \"*.pdf\"))\n \n if operation == 'merge':\n writer = PdfWriter()\n for pdf_file in pdf_files:\n try:\n reader = PdfReader(pdf_file)\n for page in reader.pages:\n writer.add_page(page)\n logger.info(f\"Processed: {pdf_file}\")\n except Exception as e:\n logger.error(f\"Failed to process {pdf_file}: {e}\")\n continue\n \n with open(\"batch_merged.pdf\", \"wb\") as output:\n writer.write(output)\n \n elif operation == 'extract_text':\n for pdf_file in pdf_files:\n try:\n reader = PdfReader(pdf_file)\n text = \"\"\n for page in reader.pages:\n text += page.extract_text()\n \n output_file = pdf_file.replace('.pdf', '.txt')\n with open(output_file, 'w', encoding='utf-8') as f:\n f.write(text)\n logger.info(f\"Extracted text from: {pdf_file}\")\n \n except Exception as e:\n logger.error(f\"Failed to extract text from {pdf_file}: {e}\")\n continue\n```\n\n### Advanced PDF Cropping\n```python\nfrom pypdf import PdfWriter, PdfReader\n\nreader = PdfReader(\"input.pdf\")\nwriter = PdfWriter()\n\n# Crop page (left, bottom, right, top in points)\npage = reader.pages[0]\npage.mediabox.left = 50\npage.mediabox.bottom = 50\npage.mediabox.right = 550\npage.mediabox.top = 750\n\nwriter.add_page(page)\nwith open(\"cropped.pdf\", \"wb\") as output:\n writer.write(output)\n```\n\n## Performance Optimization Tips\n\n### 1. For Large PDFs\n- Use streaming approaches instead of loading entire PDF in memory\n- Use `qpdf --split-pages` for splitting large files\n- Process pages individually with pypdfium2\n\n### 2. For Text Extraction\n- `pdftotext -bbox-layout` is fastest for plain text extraction\n- Use pdfplumber for structured data and tables\n- Avoid `pypdf.extract_text()` for very large documents\n\n### 3. For Image Extraction\n- `pdfimages` is much faster than rendering pages\n- Use low resolution for previews, high resolution for final output\n\n### 4. For Form Filling\n- pdf-lib maintains form structure better than most alternatives\n- Pre-validate form fields before processing\n\n### 5. Memory Management\n```python\n# Process PDFs in chunks\ndef process_large_pdf(pdf_path, chunk_size=10):\n reader = PdfReader(pdf_path)\n total_pages = len(reader.pages)\n \n for start_idx in range(0, total_pages, chunk_size):\n end_idx = min(start_idx + chunk_size, total_pages)\n writer = PdfWriter()\n \n for i in range(start_idx, end_idx):\n writer.add_page(reader.pages[i])\n \n # Process chunk\n with open(f\"chunk_{start_idx//chunk_size}.pdf\", \"wb\") as output:\n writer.write(output)\n```\n\n## Troubleshooting Common Issues\n\n### Encrypted PDFs\n```python\n# Handle password-protected PDFs\nfrom pypdf import PdfReader\n\ntry:\n reader = PdfReader(\"encrypted.pdf\")\n if reader.is_encrypted:\n reader.decrypt(\"password\")\nexcept Exception as e:\n print(f\"Failed to decrypt: {e}\")\n```\n\n### Corrupted PDFs\n```bash\n# Use qpdf to repair\nqpdf --check corrupted.pdf\nqpdf --replace-input corrupted.pdf\n```\n\n### Text Extraction Issues\n```python\n# Fallback to OCR for scanned PDFs\nimport pytesseract\nfrom pdf2image import convert_from_path\n\ndef extract_text_with_ocr(pdf_path):\n images = convert_from_path(pdf_path)\n text = \"\"\n for i, image in enumerate(images):\n text += pytesseract.image_to_string(image)\n return text\n```\n\n## License Information\n\n- **pypdf**: BSD License\n- **pdfplumber**: MIT License\n- **pypdfium2**: Apache/BSD License\n- **reportlab**: BSD License\n- **poppler-utils**: GPL-2 License\n- **qpdf**: Apache License\n- **pdf-lib**: MIT License\n- **pdfjs-dist**: Apache License" }, { "path": "src/copaw/agents/skills/pdf/scripts/check_bounding_boxes.py", "content": "from dataclasses import dataclass\nimport json\nimport sys\n\n\n\n\n@dataclass\nclass RectAndField:\n rect: list[float]\n rect_type: str\n field: dict\n\n\ndef get_bounding_box_messages(fields_json_stream) -> list[str]:\n messages = []\n fields = json.load(fields_json_stream)\n messages.append(f\"Read {len(fields['form_fields'])} fields\")\n\n def rects_intersect(r1, r2):\n disjoint_horizontal = r1[0] >= r2[2] or r1[2] <= r2[0]\n disjoint_vertical = r1[1] >= r2[3] or r1[3] <= r2[1]\n return not (disjoint_horizontal or disjoint_vertical)\n\n rects_and_fields = []\n for f in fields[\"form_fields\"]:\n rects_and_fields.append(RectAndField(f[\"label_bounding_box\"], \"label\", f))\n rects_and_fields.append(RectAndField(f[\"entry_bounding_box\"], \"entry\", f))\n\n has_error = False\n for i, ri in enumerate(rects_and_fields):\n for j in range(i + 1, len(rects_and_fields)):\n rj = rects_and_fields[j]\n if ri.field[\"page_number\"] == rj.field[\"page_number\"] and rects_intersect(ri.rect, rj.rect):\n has_error = True\n if ri.field is rj.field:\n messages.append(f\"FAILURE: intersection between label and entry bounding boxes for `{ri.field['description']}` ({ri.rect}, {rj.rect})\")\n else:\n messages.append(f\"FAILURE: intersection between {ri.rect_type} bounding box for `{ri.field['description']}` ({ri.rect}) and {rj.rect_type} bounding box for `{rj.field['description']}` ({rj.rect})\")\n if len(messages) >= 20:\n messages.append(\"Aborting further checks; fix bounding boxes and try again\")\n return messages\n if ri.rect_type == \"entry\":\n if \"entry_text\" in ri.field:\n font_size = ri.field[\"entry_text\"].get(\"font_size\", 14)\n entry_height = ri.rect[3] - ri.rect[1]\n if entry_height < font_size:\n has_error = True\n messages.append(f\"FAILURE: entry bounding box height ({entry_height}) for `{ri.field['description']}` is too short for the text content (font size: {font_size}). Increase the box height or decrease the font size.\")\n if len(messages) >= 20:\n messages.append(\"Aborting further checks; fix bounding boxes and try again\")\n return messages\n\n if not has_error:\n messages.append(\"SUCCESS: All bounding boxes are valid\")\n return messages\n\nif __name__ == \"__main__\":\n if len(sys.argv) != 2:\n print(\"Usage: check_bounding_boxes.py [fields.json]\")\n sys.exit(1)\n with open(sys.argv[1]) as f:\n messages = get_bounding_box_messages(f)\n for msg in messages:\n print(msg)\n" }, { "path": "src/copaw/agents/skills/pdf/scripts/check_fillable_fields.py", "content": "import sys\nfrom pypdf import PdfReader\n\n\n\n\nreader = PdfReader(sys.argv[1])\nif (reader.get_fields()):\n print(\"This PDF has fillable form fields\")\nelse:\n print(\"This PDF does not have fillable form fields; you will need to visually determine where to enter data\")\n" }, { "path": "src/copaw/agents/skills/pdf/scripts/convert_pdf_to_images.py", "content": "import os\nimport sys\n\nfrom pdf2image import convert_from_path\n\n\n\n\ndef convert(pdf_path, output_dir, max_dim=1000):\n images = convert_from_path(pdf_path, dpi=200)\n\n for i, image in enumerate(images):\n width, height = image.size\n if width > max_dim or height > max_dim:\n scale_factor = min(max_dim / width, max_dim / height)\n new_width = int(width * scale_factor)\n new_height = int(height * scale_factor)\n image = image.resize((new_width, new_height))\n \n image_path = os.path.join(output_dir, f\"page_{i+1}.png\")\n image.save(image_path)\n print(f\"Saved page {i+1} as {image_path} (size: {image.size})\")\n\n print(f\"Converted {len(images)} pages to PNG images\")\n\n\nif __name__ == \"__main__\":\n if len(sys.argv) != 3:\n print(\"Usage: convert_pdf_to_images.py [input pdf] [output directory]\")\n sys.exit(1)\n pdf_path = sys.argv[1]\n output_directory = sys.argv[2]\n convert(pdf_path, output_directory)\n" }, { "path": "src/copaw/agents/skills/pdf/scripts/create_validation_image.py", "content": "import json\nimport sys\n\nfrom PIL import Image, ImageDraw\n\n\n\n\ndef create_validation_image(page_number, fields_json_path, input_path, output_path):\n with open(fields_json_path, 'r') as f:\n data = json.load(f)\n\n img = Image.open(input_path)\n draw = ImageDraw.Draw(img)\n num_boxes = 0\n \n for field in data[\"form_fields\"]:\n if field[\"page_number\"] == page_number:\n entry_box = field['entry_bounding_box']\n label_box = field['label_bounding_box']\n draw.rectangle(entry_box, outline='red', width=2)\n draw.rectangle(label_box, outline='blue', width=2)\n num_boxes += 2\n \n img.save(output_path)\n print(f\"Created validation image at {output_path} with {num_boxes} bounding boxes\")\n\n\nif __name__ == \"__main__\":\n if len(sys.argv) != 5:\n print(\"Usage: create_validation_image.py [page number] [fields.json file] [input image path] [output image path]\")\n sys.exit(1)\n page_number = int(sys.argv[1])\n fields_json_path = sys.argv[2]\n input_image_path = sys.argv[3]\n output_image_path = sys.argv[4]\n create_validation_image(page_number, fields_json_path, input_image_path, output_image_path)\n" }, { "path": "src/copaw/agents/skills/pdf/scripts/extract_form_field_info.py", "content": "import json\nimport sys\n\nfrom pypdf import PdfReader\n\n\n\n\ndef get_full_annotation_field_id(annotation):\n components = []\n while annotation:\n field_name = annotation.get('/T')\n if field_name:\n components.append(field_name)\n annotation = annotation.get('/Parent')\n return \".\".join(reversed(components)) if components else None\n\n\ndef make_field_dict(field, field_id):\n field_dict = {\"field_id\": field_id}\n ft = field.get('/FT')\n if ft == \"/Tx\":\n field_dict[\"type\"] = \"text\"\n elif ft == \"/Btn\":\n field_dict[\"type\"] = \"checkbox\" \n states = field.get(\"/_States_\", [])\n if len(states) == 2:\n if \"/Off\" in states:\n field_dict[\"checked_value\"] = states[0] if states[0] != \"/Off\" else states[1]\n field_dict[\"unchecked_value\"] = \"/Off\"\n else:\n print(f\"Unexpected state values for checkbox `${field_id}`. Its checked and unchecked values may not be correct; if you're trying to check it, visually verify the results.\")\n field_dict[\"checked_value\"] = states[0]\n field_dict[\"unchecked_value\"] = states[1]\n elif ft == \"/Ch\":\n field_dict[\"type\"] = \"choice\"\n states = field.get(\"/_States_\", [])\n field_dict[\"choice_options\"] = [{\n \"value\": state[0],\n \"text\": state[1],\n } for state in states]\n else:\n field_dict[\"type\"] = f\"unknown ({ft})\"\n return field_dict\n\n\ndef get_field_info(reader: PdfReader):\n fields = reader.get_fields()\n\n field_info_by_id = {}\n possible_radio_names = set()\n\n for field_id, field in fields.items():\n if field.get(\"/Kids\"):\n if field.get(\"/FT\") == \"/Btn\":\n possible_radio_names.add(field_id)\n continue\n field_info_by_id[field_id] = make_field_dict(field, field_id)\n\n\n radio_fields_by_id = {}\n\n for page_index, page in enumerate(reader.pages):\n annotations = page.get('/Annots', [])\n for ann in annotations:\n field_id = get_full_annotation_field_id(ann)\n if field_id in field_info_by_id:\n field_info_by_id[field_id][\"page\"] = page_index + 1\n field_info_by_id[field_id][\"rect\"] = ann.get('/Rect')\n elif field_id in possible_radio_names:\n try:\n on_values = [v for v in ann[\"/AP\"][\"/N\"] if v != \"/Off\"]\n except KeyError:\n continue\n if len(on_values) == 1:\n rect = ann.get(\"/Rect\")\n if field_id not in radio_fields_by_id:\n radio_fields_by_id[field_id] = {\n \"field_id\": field_id,\n \"type\": \"radio_group\",\n \"page\": page_index + 1,\n \"radio_options\": [],\n }\n radio_fields_by_id[field_id][\"radio_options\"].append({\n \"value\": on_values[0],\n \"rect\": rect,\n })\n\n fields_with_location = []\n for field_info in field_info_by_id.values():\n if \"page\" in field_info:\n fields_with_location.append(field_info)\n else:\n print(f\"Unable to determine location for field id: {field_info.get('field_id')}, ignoring\")\n\n def sort_key(f):\n if \"radio_options\" in f:\n rect = f[\"radio_options\"][0][\"rect\"] or [0, 0, 0, 0]\n else:\n rect = f.get(\"rect\") or [0, 0, 0, 0]\n adjusted_position = [-rect[1], rect[0]]\n return [f.get(\"page\"), adjusted_position]\n \n sorted_fields = fields_with_location + list(radio_fields_by_id.values())\n sorted_fields.sort(key=sort_key)\n\n return sorted_fields\n\n\ndef write_field_info(pdf_path: str, json_output_path: str):\n reader = PdfReader(pdf_path)\n field_info = get_field_info(reader)\n with open(json_output_path, \"w\") as f:\n json.dump(field_info, f, indent=2)\n print(f\"Wrote {len(field_info)} fields to {json_output_path}\")\n\n\nif __name__ == \"__main__\":\n if len(sys.argv) != 3:\n print(\"Usage: extract_form_field_info.py [input pdf] [output json]\")\n sys.exit(1)\n write_field_info(sys.argv[1], sys.argv[2])\n" }, { "path": "src/copaw/agents/skills/pdf/scripts/extract_form_structure.py", "content": "\"\"\"\nExtract form structure from a non-fillable PDF.\n\nThis script analyzes the PDF to find:\n- Text labels with their exact coordinates\n- Horizontal lines (row boundaries)\n- Checkboxes (small rectangles)\n\nOutput: A JSON file with the form structure that can be used to generate\naccurate field coordinates for filling.\n\nUsage: python extract_form_structure.py \n\"\"\"\n\nimport json\nimport sys\nimport pdfplumber\n\n\ndef extract_form_structure(pdf_path):\n structure = {\n \"pages\": [],\n \"labels\": [],\n \"lines\": [],\n \"checkboxes\": [],\n \"row_boundaries\": []\n }\n\n with pdfplumber.open(pdf_path) as pdf:\n for page_num, page in enumerate(pdf.pages, 1):\n structure[\"pages\"].append({\n \"page_number\": page_num,\n \"width\": float(page.width),\n \"height\": float(page.height)\n })\n\n words = page.extract_words()\n for word in words:\n structure[\"labels\"].append({\n \"page\": page_num,\n \"text\": word[\"text\"],\n \"x0\": round(float(word[\"x0\"]), 1),\n \"top\": round(float(word[\"top\"]), 1),\n \"x1\": round(float(word[\"x1\"]), 1),\n \"bottom\": round(float(word[\"bottom\"]), 1)\n })\n\n for line in page.lines:\n if abs(float(line[\"x1\"]) - float(line[\"x0\"])) > page.width * 0.5:\n structure[\"lines\"].append({\n \"page\": page_num,\n \"y\": round(float(line[\"top\"]), 1),\n \"x0\": round(float(line[\"x0\"]), 1),\n \"x1\": round(float(line[\"x1\"]), 1)\n })\n\n for rect in page.rects:\n width = float(rect[\"x1\"]) - float(rect[\"x0\"])\n height = float(rect[\"bottom\"]) - float(rect[\"top\"])\n if 5 <= width <= 15 and 5 <= height <= 15 and abs(width - height) < 2:\n structure[\"checkboxes\"].append({\n \"page\": page_num,\n \"x0\": round(float(rect[\"x0\"]), 1),\n \"top\": round(float(rect[\"top\"]), 1),\n \"x1\": round(float(rect[\"x1\"]), 1),\n \"bottom\": round(float(rect[\"bottom\"]), 1),\n \"center_x\": round((float(rect[\"x0\"]) + float(rect[\"x1\"])) / 2, 1),\n \"center_y\": round((float(rect[\"top\"]) + float(rect[\"bottom\"])) / 2, 1)\n })\n\n lines_by_page = {}\n for line in structure[\"lines\"]:\n page = line[\"page\"]\n if page not in lines_by_page:\n lines_by_page[page] = []\n lines_by_page[page].append(line[\"y\"])\n\n for page, y_coords in lines_by_page.items():\n y_coords = sorted(set(y_coords))\n for i in range(len(y_coords) - 1):\n structure[\"row_boundaries\"].append({\n \"page\": page,\n \"row_top\": y_coords[i],\n \"row_bottom\": y_coords[i + 1],\n \"row_height\": round(y_coords[i + 1] - y_coords[i], 1)\n })\n\n return structure\n\n\ndef main():\n if len(sys.argv) != 3:\n print(\"Usage: extract_form_structure.py \")\n sys.exit(1)\n\n pdf_path = sys.argv[1]\n output_path = sys.argv[2]\n\n print(f\"Extracting structure from {pdf_path}...\")\n structure = extract_form_structure(pdf_path)\n\n with open(output_path, \"w\") as f:\n json.dump(structure, f, indent=2)\n\n print(f\"Found:\")\n print(f\" - {len(structure['pages'])} pages\")\n print(f\" - {len(structure['labels'])} text labels\")\n print(f\" - {len(structure['lines'])} horizontal lines\")\n print(f\" - {len(structure['checkboxes'])} checkboxes\")\n print(f\" - {len(structure['row_boundaries'])} row boundaries\")\n print(f\"Saved to {output_path}\")\n\n\nif __name__ == \"__main__\":\n main()\n" }, { "path": "src/copaw/agents/skills/pdf/scripts/fill_fillable_fields.py", "content": "import json\nimport sys\n\nfrom pypdf import PdfReader, PdfWriter\n\nfrom extract_form_field_info import get_field_info\n\n\n\n\ndef fill_pdf_fields(input_pdf_path: str, fields_json_path: str, output_pdf_path: str):\n with open(fields_json_path) as f:\n fields = json.load(f)\n fields_by_page = {}\n for field in fields:\n if \"value\" in field:\n field_id = field[\"field_id\"]\n page = field[\"page\"]\n if page not in fields_by_page:\n fields_by_page[page] = {}\n fields_by_page[page][field_id] = field[\"value\"]\n \n reader = PdfReader(input_pdf_path)\n\n has_error = False\n field_info = get_field_info(reader)\n fields_by_ids = {f[\"field_id\"]: f for f in field_info}\n for field in fields:\n existing_field = fields_by_ids.get(field[\"field_id\"])\n if not existing_field:\n has_error = True\n print(f\"ERROR: `{field['field_id']}` is not a valid field ID\")\n elif field[\"page\"] != existing_field[\"page\"]:\n has_error = True\n print(f\"ERROR: Incorrect page number for `{field['field_id']}` (got {field['page']}, expected {existing_field['page']})\")\n else:\n if \"value\" in field:\n err = validation_error_for_field_value(existing_field, field[\"value\"])\n if err:\n print(err)\n has_error = True\n if has_error:\n sys.exit(1)\n\n writer = PdfWriter(clone_from=reader)\n for page, field_values in fields_by_page.items():\n writer.update_page_form_field_values(writer.pages[page - 1], field_values, auto_regenerate=False)\n\n writer.set_need_appearances_writer(True)\n \n with open(output_pdf_path, \"wb\") as f:\n writer.write(f)\n\n\ndef validation_error_for_field_value(field_info, field_value):\n field_type = field_info[\"type\"]\n field_id = field_info[\"field_id\"]\n if field_type == \"checkbox\":\n checked_val = field_info[\"checked_value\"]\n unchecked_val = field_info[\"unchecked_value\"]\n if field_value != checked_val and field_value != unchecked_val:\n return f'ERROR: Invalid value \"{field_value}\" for checkbox field \"{field_id}\". The checked value is \"{checked_val}\" and the unchecked value is \"{unchecked_val}\"'\n elif field_type == \"radio_group\":\n option_values = [opt[\"value\"] for opt in field_info[\"radio_options\"]]\n if field_value not in option_values:\n return f'ERROR: Invalid value \"{field_value}\" for radio group field \"{field_id}\". Valid values are: {option_values}' \n elif field_type == \"choice\":\n choice_values = [opt[\"value\"] for opt in field_info[\"choice_options\"]]\n if field_value not in choice_values:\n return f'ERROR: Invalid value \"{field_value}\" for choice field \"{field_id}\". Valid values are: {choice_values}'\n return None\n\n\ndef monkeypatch_pydpf_method():\n from pypdf.generic import DictionaryObject\n from pypdf.constants import FieldDictionaryAttributes\n\n original_get_inherited = DictionaryObject.get_inherited\n\n def patched_get_inherited(self, key: str, default = None):\n result = original_get_inherited(self, key, default)\n if key == FieldDictionaryAttributes.Opt:\n if isinstance(result, list) and all(isinstance(v, list) and len(v) == 2 for v in result):\n result = [r[0] for r in result]\n return result\n\n DictionaryObject.get_inherited = patched_get_inherited\n\n\nif __name__ == \"__main__\":\n if len(sys.argv) != 4:\n print(\"Usage: fill_fillable_fields.py [input pdf] [field_values.json] [output pdf]\")\n sys.exit(1)\n monkeypatch_pydpf_method()\n input_pdf = sys.argv[1]\n fields_json = sys.argv[2]\n output_pdf = sys.argv[3]\n fill_pdf_fields(input_pdf, fields_json, output_pdf)\n" }, { "path": "src/copaw/agents/skills/pdf/scripts/fill_pdf_form_with_annotations.py", "content": "import json\nimport sys\n\nfrom pypdf import PdfReader, PdfWriter\nfrom pypdf.annotations import FreeText\n\n\n\n\ndef transform_from_image_coords(bbox, image_width, image_height, pdf_width, pdf_height):\n x_scale = pdf_width / image_width\n y_scale = pdf_height / image_height\n\n left = bbox[0] * x_scale\n right = bbox[2] * x_scale\n\n top = pdf_height - (bbox[1] * y_scale)\n bottom = pdf_height - (bbox[3] * y_scale)\n\n return left, bottom, right, top\n\n\ndef transform_from_pdf_coords(bbox, pdf_height):\n left = bbox[0]\n right = bbox[2]\n\n pypdf_top = pdf_height - bbox[1] \n pypdf_bottom = pdf_height - bbox[3] \n\n return left, pypdf_bottom, right, pypdf_top\n\n\ndef fill_pdf_form(input_pdf_path, fields_json_path, output_pdf_path):\n \n with open(fields_json_path, \"r\") as f:\n fields_data = json.load(f)\n \n reader = PdfReader(input_pdf_path)\n writer = PdfWriter()\n \n writer.append(reader)\n \n pdf_dimensions = {}\n for i, page in enumerate(reader.pages):\n mediabox = page.mediabox\n pdf_dimensions[i + 1] = [mediabox.width, mediabox.height]\n \n annotations = []\n for field in fields_data[\"form_fields\"]:\n page_num = field[\"page_number\"]\n\n page_info = next(p for p in fields_data[\"pages\"] if p[\"page_number\"] == page_num)\n pdf_width, pdf_height = pdf_dimensions[page_num]\n\n if \"pdf_width\" in page_info:\n transformed_entry_box = transform_from_pdf_coords(\n field[\"entry_bounding_box\"],\n float(pdf_height)\n )\n else:\n image_width = page_info[\"image_width\"]\n image_height = page_info[\"image_height\"]\n transformed_entry_box = transform_from_image_coords(\n field[\"entry_bounding_box\"],\n image_width, image_height,\n float(pdf_width), float(pdf_height)\n )\n \n if \"entry_text\" not in field or \"text\" not in field[\"entry_text\"]:\n continue\n entry_text = field[\"entry_text\"]\n text = entry_text[\"text\"]\n if not text:\n continue\n \n font_name = entry_text.get(\"font\", \"Arial\")\n font_size = str(entry_text.get(\"font_size\", 14)) + \"pt\"\n font_color = entry_text.get(\"font_color\", \"000000\")\n\n annotation = FreeText(\n text=text,\n rect=transformed_entry_box,\n font=font_name,\n font_size=font_size,\n font_color=font_color,\n border_color=None,\n background_color=None,\n )\n annotations.append(annotation)\n writer.add_annotation(page_number=page_num - 1, annotation=annotation)\n \n with open(output_pdf_path, \"wb\") as output:\n writer.write(output)\n \n print(f\"Successfully filled PDF form and saved to {output_pdf_path}\")\n print(f\"Added {len(annotations)} text annotations\")\n\n\nif __name__ == \"__main__\":\n if len(sys.argv) != 4:\n print(\"Usage: fill_pdf_form_with_annotations.py [input pdf] [fields.json] [output pdf]\")\n sys.exit(1)\n input_pdf = sys.argv[1]\n fields_json = sys.argv[2]\n output_pdf = sys.argv[3]\n \n fill_pdf_form(input_pdf, fields_json, output_pdf)\n" }, { "path": "src/copaw/agents/skills/pptx/LICENSE.txt", "content": "© 2025 Anthropic, PBC. All rights reserved.\n\nLICENSE: Use of these materials (including all code, prompts, assets, files,\nand other components of this Skill) is governed by your agreement with\nAnthropic regarding use of Anthropic's services. If no separate agreement\nexists, use is governed by Anthropic's Consumer Terms of Service or\nCommercial Terms of Service, as applicable:\nhttps://www.anthropic.com/legal/consumer-terms\nhttps://www.anthropic.com/legal/commercial-terms\nYour applicable agreement is referred to as the \"Agreement.\" \"Services\" are\nas defined in the Agreement.\n\nADDITIONAL RESTRICTIONS: Notwithstanding anything in the Agreement to the\ncontrary, users may not:\n\n- Extract these materials from the Services or retain copies of these\n materials outside the Services\n- Reproduce or copy these materials, except for temporary copies created\n automatically during authorized use of the Services\n- Create derivative works based on these materials\n- Distribute, sublicense, or transfer these materials to any third party\n- Make, offer to sell, sell, or import any inventions embodied in these\n materials\n- Reverse engineer, decompile, or disassemble these materials\n\nThe receipt, viewing, or possession of these materials does not convey or\nimply any license or right beyond those expressly granted above.\n\nAnthropic retains all right, title, and interest in these materials,\nincluding all copyrights, patents, and other intellectual property rights.\n" }, { "path": "src/copaw/agents/skills/pptx/SKILL.md", "content": "---\nname: pptx\ndescription: \"Use this skill any time a .pptx file is involved in any way — as input, output, or both. This includes: creating slide decks, pitch decks, or presentations; reading, parsing, or extracting text from any .pptx file (even if the extracted content will be used elsewhere, like in an email or summary); editing, modifying, or updating existing presentations; combining or splitting slide files; working with templates, layouts, speaker notes, or comments. Trigger whenever the user mentions \\\"deck,\\\" \\\"slides,\\\" \\\"presentation,\\\" or references a .pptx filename, regardless of what they plan to do with the content afterward. If a .pptx file needs to be opened, created, or touched, use this skill.\"\nlicense: Proprietary. LICENSE.txt has complete terms\nmetadata: { \"builtin_skill_version\": \"1.0\" }\n---\n\n> **Important:** All `scripts/` paths are relative to this skill directory.\n> Run with: `cd {this_skill_dir} && python scripts/...`\n> Or use the `cwd` parameter of `execute_shell_command`.\n\n# PPTX Skill\n\n## Prerequisites\n\n- **markitdown[pptx]**: text extraction from presentations\n- **Pillow**: thumbnail grid generation\n- **pptxgenjs** (`npm install -g pptxgenjs`): creating presentations from scratch\n- **LibreOffice** (`soffice`): presentation-to-PDF conversion\n- **pdftoppm** (poppler-utils): PDF-to-image conversion for thumbnail/visual workflows\n- If `pdftoppm` is unavailable, a Python fallback path may use `pdf2image`.\n- On Windows, dependencies must be installed and available in `PATH`; if missing, report the dependency issue and stop (do not keep retrying).\n\n## Quick Reference\n\n| Task | Guide |\n|------|-------|\n| Read/analyze content | `python -m markitdown presentation.pptx` |\n| Edit or create from template | Read [editing.md](editing.md) |\n| Create from scratch | Read [pptxgenjs.md](pptxgenjs.md) |\n\n---\n\n## Reading Content\n\n```bash\n# Text extraction\npython -m markitdown presentation.pptx\n\n# Visual overview\npython scripts/thumbnail.py presentation.pptx\n\n# Raw XML\npython scripts/office/unpack.py presentation.pptx unpacked/\n```\n\n---\n\n## Editing Workflow\n\n**Read [editing.md](editing.md) for full details.**\n\n1. Analyze template with `thumbnail.py`\n2. Unpack → manipulate slides → edit content → clean → pack\n\n---\n\n## Creating from Scratch\n\n**Read [pptxgenjs.md](pptxgenjs.md) for full details.**\n\nUse when no template or reference presentation is available.\n\n---\n\n## Design Ideas\n\n**Don't create boring slides.** Plain bullets on a white background won't impress anyone. Consider ideas from this list for each slide.\n\n### Before Starting\n\n- **Pick a bold, content-informed color palette**: The palette should feel designed for THIS topic. If swapping your colors into a completely different presentation would still \"work,\" you haven't made specific enough choices.\n- **Dominance over equality**: One color should dominate (60-70% visual weight), with 1-2 supporting tones and one sharp accent. Never give all colors equal weight.\n- **Dark/light contrast**: Dark backgrounds for title + conclusion slides, light for content (\"sandwich\" structure). Or commit to dark throughout for a premium feel.\n- **Commit to a visual motif**: Pick ONE distinctive element and repeat it — rounded image frames, icons in colored circles, thick single-side borders. Carry it across every slide.\n\n### Color Palettes\n\nChoose colors that match your topic — don't default to generic blue. Use these palettes as inspiration:\n\n| Theme | Primary | Secondary | Accent |\n|-------|---------|-----------|--------|\n| **Midnight Executive** | `1E2761` (navy) | `CADCFC` (ice blue) | `FFFFFF` (white) |\n| **Forest & Moss** | `2C5F2D` (forest) | `97BC62` (moss) | `F5F5F5` (cream) |\n| **Coral Energy** | `F96167` (coral) | `F9E795` (gold) | `2F3C7E` (navy) |\n| **Warm Terracotta** | `B85042` (terracotta) | `E7E8D1` (sand) | `A7BEAE` (sage) |\n| **Ocean Gradient** | `065A82` (deep blue) | `1C7293` (teal) | `21295C` (midnight) |\n| **Charcoal Minimal** | `36454F` (charcoal) | `F2F2F2` (off-white) | `212121` (black) |\n| **Teal Trust** | `028090` (teal) | `00A896` (seafoam) | `02C39A` (mint) |\n| **Berry & Cream** | `6D2E46` (berry) | `A26769` (dusty rose) | `ECE2D0` (cream) |\n| **Sage Calm** | `84B59F` (sage) | `69A297` (eucalyptus) | `50808E` (slate) |\n| **Cherry Bold** | `990011` (cherry) | `FCF6F5` (off-white) | `2F3C7E` (navy) |\n\n### For Each Slide\n\n**Every slide needs a visual element** — image, chart, icon, or shape. Text-only slides are forgettable.\n\n**Layout options:**\n- Two-column (text left, illustration on right)\n- Icon + text rows (icon in colored circle, bold header, description below)\n- 2x2 or 2x3 grid (image on one side, grid of content blocks on other)\n- Half-bleed image (full left or right side) with content overlay\n\n**Data display:**\n- Large stat callouts (big numbers 60-72pt with small labels below)\n- Comparison columns (before/after, pros/cons, side-by-side options)\n- Timeline or process flow (numbered steps, arrows)\n\n**Visual polish:**\n- Icons in small colored circles next to section headers\n- Italic accent text for key stats or taglines\n\n### Typography\n\n**Choose an interesting font pairing** — don't default to Arial. Pick a header font with personality and pair it with a clean body font.\n\n| Header Font | Body Font |\n|-------------|-----------|\n| Georgia | Calibri |\n| Arial Black | Arial |\n| Calibri | Calibri Light |\n| Cambria | Calibri |\n| Trebuchet MS | Calibri |\n| Impact | Arial |\n| Palatino | Garamond |\n| Consolas | Calibri |\n\n| Element | Size |\n|---------|------|\n| Slide title | 36-44pt bold |\n| Section header | 20-24pt bold |\n| Body text | 14-16pt |\n| Captions | 10-12pt muted |\n\n### Spacing\n\n- 0.5\" minimum margins\n- 0.3-0.5\" between content blocks\n- Leave breathing room—don't fill every inch\n\n### Avoid (Common Mistakes)\n\n- **Don't repeat the same layout** — vary columns, cards, and callouts across slides\n- **Don't center body text** — left-align paragraphs and lists; center only titles\n- **Don't skimp on size contrast** — titles need 36pt+ to stand out from 14-16pt body\n- **Don't default to blue** — pick colors that reflect the specific topic\n- **Don't mix spacing randomly** — choose 0.3\" or 0.5\" gaps and use consistently\n- **Don't style one slide and leave the rest plain** — commit fully or keep it simple throughout\n- **Don't create text-only slides** — add images, icons, charts, or visual elements; avoid plain title + bullets\n- **Don't forget text box padding** — when aligning lines or shapes with text edges, set `margin: 0` on the text box or offset the shape to account for padding\n- **Don't use low-contrast elements** — icons AND text need strong contrast against the background; avoid light text on light backgrounds or dark text on dark backgrounds\n- **NEVER use accent lines under titles** — these are a hallmark of AI-generated slides; use whitespace or background color instead\n\n---\n\n## QA (Required)\n\n**Assume there are problems. Your job is to find them.**\n\nYour first render is almost never correct. Approach QA as a bug hunt, not a confirmation step. If you found zero issues on first inspection, you weren't looking hard enough.\n\n### Content QA\n\n```bash\npython -m markitdown output.pptx\n```\n\nCheck for missing content, typos, wrong order.\n\n**When using templates, check for leftover placeholder text:**\n\n```bash\npython -m markitdown output.pptx | grep -iE \"xxxx|lorem|ipsum|this.*(page|slide).*layout\"\n```\n\nIf grep returns results, fix them before declaring success.\n\n### Visual QA\n\n**⚠️ USE SUBAGENTS** — even for 2-3 slides. You've been staring at the code and will see what you expect, not what's there. Subagents have fresh eyes.\n\nConvert slides to images (see [Converting to Images](#converting-to-images)), then use this prompt:\n\n```\nVisually inspect these slides. Assume there are issues — find them.\n\nLook for:\n- Overlapping elements (text through shapes, lines through words, stacked elements)\n- Text overflow or cut off at edges/box boundaries\n- Decorative lines positioned for single-line text but title wrapped to two lines\n- Source citations or footers colliding with content above\n- Elements too close (< 0.3\" gaps) or cards/sections nearly touching\n- Uneven gaps (large empty area in one place, cramped in another)\n- Insufficient margin from slide edges (< 0.5\")\n- Columns or similar elements not aligned consistently\n- Low-contrast text (e.g., light gray text on cream-colored background)\n- Low-contrast icons (e.g., dark icons on dark backgrounds without a contrasting circle)\n- Text boxes too narrow causing excessive wrapping\n- Leftover placeholder content\n\nFor each slide, list issues or areas of concern, even if minor.\n\nRead and analyze these images:\n1. /path/to/slide-01.jpg (Expected: [brief description])\n2. /path/to/slide-02.jpg (Expected: [brief description])\n\nReport ALL issues found, including minor ones.\n```\n\n### Verification Loop\n\n1. Generate slides → Convert to images → Inspect\n2. **List issues found** (if none found, look again more critically)\n3. Fix issues\n4. **Re-verify affected slides** — one fix often creates another problem\n5. Repeat until a full pass reveals no new issues\n\n**Do not declare success until you've completed at least one fix-and-verify cycle.**\n\n---\n\n## Converting to Images\n\nConvert presentations to individual slide images for visual inspection:\n\n```bash\npython scripts/office/soffice.py --headless --convert-to pdf output.pptx\npdftoppm -jpeg -r 150 output.pdf slide\n```\n\nThis creates `slide-01.jpg`, `slide-02.jpg`, etc.\n\nTo re-render specific slides after fixes:\n\n```bash\npdftoppm -jpeg -r 150 -f N -l N output.pdf slide-fixed\n```\n\n" }, { "path": "src/copaw/agents/skills/pptx/editing.md", "content": "> **Important:** All `scripts/` paths are relative to the skill directory (where SKILL.md is).\n> Run with: `cd {this_skill_dir} && python scripts/...`\n> Or use the `cwd` parameter of `execute_shell_command`.\n\n# Editing Presentations\n\n## Template-Based Workflow\n\nWhen using an existing presentation as a template:\n\n1. **Analyze existing slides**:\n ```bash\n python scripts/thumbnail.py template.pptx\n python -m markitdown template.pptx\n ```\n Review `thumbnails.jpg` to see layouts, and markitdown output to see placeholder text.\n\n2. **Plan slide mapping**: For each content section, choose a template slide.\n\n ⚠️ **USE VARIED LAYOUTS** — monotonous presentations are a common failure mode. Don't default to basic title + bullet slides. Actively seek out:\n - Multi-column layouts (2-column, 3-column)\n - Image + text combinations\n - Full-bleed images with text overlay\n - Quote or callout slides\n - Section dividers\n - Stat/number callouts\n - Icon grids or icon + text rows\n\n **Avoid:** Repeating the same text-heavy layout for every slide.\n\n Match content type to layout style (e.g., key points → bullet slide, team info → multi-column, testimonials → quote slide).\n\n3. **Unpack**: `python scripts/office/unpack.py template.pptx unpacked/`\n\n4. **Build presentation** (do this yourself, not with subagents):\n - Delete unwanted slides (remove from ``)\n - Duplicate slides you want to reuse (`add_slide.py`)\n - Reorder slides in ``\n - **Complete all structural changes before step 5**\n\n5. **Edit content**: Update text in each `slide{N}.xml`.\n **Use subagents here if available** — slides are separate XML files, so subagents can edit in parallel.\n\n6. **Clean**: `python scripts/clean.py unpacked/`\n\n7. **Pack**: `python scripts/office/pack.py unpacked/ output.pptx --original template.pptx`\n\n---\n\n## Scripts\n\n| Script | Purpose |\n|--------|---------|\n| `unpack.py` | Extract and pretty-print PPTX |\n| `add_slide.py` | Duplicate slide or create from layout |\n| `clean.py` | Remove orphaned files |\n| `pack.py` | Repack with validation |\n| `thumbnail.py` | Create visual grid of slides |\n\n### unpack.py\n\n```bash\npython scripts/office/unpack.py input.pptx unpacked/\n```\n\nExtracts PPTX, pretty-prints XML, escapes smart quotes.\n\n### add_slide.py\n\n```bash\npython scripts/add_slide.py unpacked/ slide2.xml # Duplicate slide\npython scripts/add_slide.py unpacked/ slideLayout2.xml # From layout\n```\n\nPrints `` to add to `` at desired position.\n\n### clean.py\n\n```bash\npython scripts/clean.py unpacked/\n```\n\nRemoves slides not in ``, unreferenced media, orphaned rels.\n\n### pack.py\n\n```bash\npython scripts/office/pack.py unpacked/ output.pptx --original input.pptx\n```\n\nValidates, repairs, condenses XML, re-encodes smart quotes.\n\n### thumbnail.py\n\n```bash\npython scripts/thumbnail.py input.pptx [output_prefix] [--cols N]\n```\n\nCreates `thumbnails.jpg` with slide filenames as labels. Default 3 columns, max 12 per grid.\n\n**Use for template analysis only** (choosing layouts). For visual QA, use `soffice` + `pdftoppm` to create full-resolution individual slide images—see SKILL.md.\n\n---\n\n## Slide Operations\n\nSlide order is in `ppt/presentation.xml` → ``.\n\n**Reorder**: Rearrange `` elements.\n\n**Delete**: Remove ``, then run `clean.py`.\n\n**Add**: Use `add_slide.py`. Never manually copy slide files—the script handles notes references, Content_Types.xml, and relationship IDs that manual copying misses.\n\n---\n\n## Editing Content\n\n**Subagents:** If available, use them here (after completing step 4). Each slide is a separate XML file, so subagents can edit in parallel. In your prompt to subagents, include:\n- The slide file path(s) to edit\n- **\"Use the Edit tool for all changes\"**\n- The formatting rules and common pitfalls below\n\nFor each slide:\n1. Read the slide's XML\n2. Identify ALL placeholder content—text, images, charts, icons, captions\n3. Replace each placeholder with final content\n\n**Use the Edit tool, not sed or Python scripts.** The Edit tool forces specificity about what to replace and where, yielding better reliability.\n\n### Formatting Rules\n\n- **Bold all headers, subheadings, and inline labels**: Use `b=\"1\"` on ``. This includes:\n - Slide titles\n - Section headers within a slide\n - Inline labels like (e.g.: \"Status:\", \"Description:\") at the start of a line\n- **Never use unicode bullets (•)**: Use proper list formatting with `` or ``\n- **Bullet consistency**: Let bullets inherit from the layout. Only specify `` or ``.\n\n---\n\n## Common Pitfalls\n\n### Template Adaptation\n\nWhen source content has fewer items than the template:\n- **Remove excess elements entirely** (images, shapes, text boxes), don't just clear text\n- Check for orphaned visuals after clearing text content\n- Run visual QA to catch mismatched counts\n\nWhen replacing text with different length content:\n- **Shorter replacements**: Usually safe\n- **Longer replacements**: May overflow or wrap unexpectedly\n- Test with visual QA after text changes\n- Consider truncating or splitting content to fit the template's design constraints\n\n**Template slots ≠ Source items**: If template has 4 team members but source has 3 users, delete the 4th member's entire group (image + text boxes), not just the text.\n\n### Multi-Item Content\n\nIf source has multiple items (numbered lists, multiple sections), create separate `` elements for each — **never concatenate into one string**.\n\n**❌ WRONG** — all items in one paragraph:\n```xml\n\n Step 1: Do the first thing. Step 2: Do the second thing.\n\n```\n\n**✅ CORRECT** — separate paragraphs with bold headers:\n```xml\n\n \n Step 1\n\n\n \n Do the first thing.\n\n\n \n Step 2\n\n\n```\n\nCopy `` from the original paragraph to preserve line spacing. Use `b=\"1\"` on headers.\n\n### Smart Quotes\n\nHandled automatically by unpack/pack. But the Edit tool converts smart quotes to ASCII.\n\n**When adding new text with quotes, use XML entities:**\n\n```xml\nthe “Agreement”\n```\n\n| Character | Name | Unicode | XML Entity |\n|-----------|------|---------|------------|\n| `“` | Left double quote | U+201C | `“` |\n| `”` | Right double quote | U+201D | `”` |\n| `‘` | Left single quote | U+2018 | `‘` |\n| `’` | Right single quote | U+2019 | `’` |\n\n### Other\n\n- **Whitespace**: Use `xml:space=\"preserve\"` on `` with leading/trailing spaces\n- **XML parsing**: Use `defusedxml.minidom`, not `xml.etree.ElementTree` (corrupts namespaces)\n" }, { "path": "src/copaw/agents/skills/pptx/pptxgenjs.md", "content": "# PptxGenJS Tutorial\n\n## Setup & Basic Structure\n\n```javascript\nconst pptxgen = require(\"pptxgenjs\");\n\nlet pres = new pptxgen();\npres.layout = 'LAYOUT_16x9'; // or 'LAYOUT_16x10', 'LAYOUT_4x3', 'LAYOUT_WIDE'\npres.author = 'Your Name';\npres.title = 'Presentation Title';\n\nlet slide = pres.addSlide();\nslide.addText(\"Hello World!\", { x: 0.5, y: 0.5, fontSize: 36, color: \"363636\" });\n\npres.writeFile({ fileName: \"Presentation.pptx\" });\n```\n\n## Layout Dimensions\n\nSlide dimensions (coordinates in inches):\n- `LAYOUT_16x9`: 10\" × 5.625\" (default)\n- `LAYOUT_16x10`: 10\" × 6.25\"\n- `LAYOUT_4x3`: 10\" × 7.5\"\n- `LAYOUT_WIDE`: 13.3\" × 7.5\"\n\n---\n\n## Text & Formatting\n\n```javascript\n// Basic text\nslide.addText(\"Simple Text\", {\n x: 1, y: 1, w: 8, h: 2, fontSize: 24, fontFace: \"Arial\",\n color: \"363636\", bold: true, align: \"center\", valign: \"middle\"\n});\n\n// Character spacing (use charSpacing, not letterSpacing which is silently ignored)\nslide.addText(\"SPACED TEXT\", { x: 1, y: 1, w: 8, h: 1, charSpacing: 6 });\n\n// Rich text arrays\nslide.addText([\n { text: \"Bold \", options: { bold: true } },\n { text: \"Italic \", options: { italic: true } }\n], { x: 1, y: 3, w: 8, h: 1 });\n\n// Multi-line text (requires breakLine: true)\nslide.addText([\n { text: \"Line 1\", options: { breakLine: true } },\n { text: \"Line 2\", options: { breakLine: true } },\n { text: \"Line 3\" } // Last item doesn't need breakLine\n], { x: 0.5, y: 0.5, w: 8, h: 2 });\n\n// Text box margin (internal padding)\nslide.addText(\"Title\", {\n x: 0.5, y: 0.3, w: 9, h: 0.6,\n margin: 0 // Use 0 when aligning text with other elements like shapes or icons\n});\n```\n\n**Tip:** Text boxes have internal margin by default. Set `margin: 0` when you need text to align precisely with shapes, lines, or icons at the same x-position.\n\n---\n\n## Lists & Bullets\n\n```javascript\n// ✅ CORRECT: Multiple bullets\nslide.addText([\n { text: \"First item\", options: { bullet: true, breakLine: true } },\n { text: \"Second item\", options: { bullet: true, breakLine: true } },\n { text: \"Third item\", options: { bullet: true } }\n], { x: 0.5, y: 0.5, w: 8, h: 3 });\n\n// ❌ WRONG: Never use unicode bullets\nslide.addText(\"• First item\", { ... }); // Creates double bullets\n\n// Sub-items and numbered lists\n{ text: \"Sub-item\", options: { bullet: true, indentLevel: 1 } }\n{ text: \"First\", options: { bullet: { type: \"number\" }, breakLine: true } }\n```\n\n---\n\n## Shapes\n\n```javascript\nslide.addShape(pres.shapes.RECTANGLE, {\n x: 0.5, y: 0.8, w: 1.5, h: 3.0,\n fill: { color: \"FF0000\" }, line: { color: \"000000\", width: 2 }\n});\n\nslide.addShape(pres.shapes.OVAL, { x: 4, y: 1, w: 2, h: 2, fill: { color: \"0000FF\" } });\n\nslide.addShape(pres.shapes.LINE, {\n x: 1, y: 3, w: 5, h: 0, line: { color: \"FF0000\", width: 3, dashType: \"dash\" }\n});\n\n// With transparency\nslide.addShape(pres.shapes.RECTANGLE, {\n x: 1, y: 1, w: 3, h: 2,\n fill: { color: \"0088CC\", transparency: 50 }\n});\n\n// Rounded rectangle (rectRadius only works with ROUNDED_RECTANGLE, not RECTANGLE)\n// ⚠️ Don't pair with rectangular accent overlays — they won't cover rounded corners. Use RECTANGLE instead.\nslide.addShape(pres.shapes.ROUNDED_RECTANGLE, {\n x: 1, y: 1, w: 3, h: 2,\n fill: { color: \"FFFFFF\" }, rectRadius: 0.1\n});\n\n// With shadow\nslide.addShape(pres.shapes.RECTANGLE, {\n x: 1, y: 1, w: 3, h: 2,\n fill: { color: \"FFFFFF\" },\n shadow: { type: \"outer\", color: \"000000\", blur: 6, offset: 2, angle: 135, opacity: 0.15 }\n});\n```\n\nShadow options:\n\n| Property | Type | Range | Notes |\n|----------|------|-------|-------|\n| `type` | string | `\"outer\"`, `\"inner\"` | |\n| `color` | string | 6-char hex (e.g. `\"000000\"`) | No `#` prefix, no 8-char hex — see Common Pitfalls |\n| `blur` | number | 0-100 pt | |\n| `offset` | number | 0-200 pt | **Must be non-negative** — negative values corrupt the file |\n| `angle` | number | 0-359 degrees | Direction the shadow falls (135 = bottom-right, 270 = upward) |\n| `opacity` | number | 0.0-1.0 | Use this for transparency, never encode in color string |\n\nTo cast a shadow upward (e.g. on a footer bar), use `angle: 270` with a positive offset — do **not** use a negative offset.\n\n**Note**: Gradient fills are not natively supported. Use a gradient image as a background instead.\n\n---\n\n## Images\n\n### Image Sources\n\n```javascript\n// From file path\nslide.addImage({ path: \"images/chart.png\", x: 1, y: 1, w: 5, h: 3 });\n\n// From URL\nslide.addImage({ path: \"https://example.com/image.jpg\", x: 1, y: 1, w: 5, h: 3 });\n\n// From base64 (faster, no file I/O)\nslide.addImage({ data: \"image/png;base64,iVBORw0KGgo...\", x: 1, y: 1, w: 5, h: 3 });\n```\n\n### Image Options\n\n```javascript\nslide.addImage({\n path: \"image.png\",\n x: 1, y: 1, w: 5, h: 3,\n rotate: 45, // 0-359 degrees\n rounding: true, // Circular crop\n transparency: 50, // 0-100\n flipH: true, // Horizontal flip\n flipV: false, // Vertical flip\n altText: \"Description\", // Accessibility\n hyperlink: { url: \"https://example.com\" }\n});\n```\n\n### Image Sizing Modes\n\n```javascript\n// Contain - fit inside, preserve ratio\n{ sizing: { type: 'contain', w: 4, h: 3 } }\n\n// Cover - fill area, preserve ratio (may crop)\n{ sizing: { type: 'cover', w: 4, h: 3 } }\n\n// Crop - cut specific portion\n{ sizing: { type: 'crop', x: 0.5, y: 0.5, w: 2, h: 2 } }\n```\n\n### Calculate Dimensions (preserve aspect ratio)\n\n```javascript\nconst origWidth = 1978, origHeight = 923, maxHeight = 3.0;\nconst calcWidth = maxHeight * (origWidth / origHeight);\nconst centerX = (10 - calcWidth) / 2;\n\nslide.addImage({ path: \"image.png\", x: centerX, y: 1.2, w: calcWidth, h: maxHeight });\n```\n\n### Supported Formats\n\n- **Standard**: PNG, JPG, GIF (animated GIFs work in Microsoft 365)\n- **SVG**: Works in modern PowerPoint/Microsoft 365\n\n---\n\n## Icons\n\nUse react-icons to generate SVG icons, then rasterize to PNG for universal compatibility.\n\n### Setup\n\n```javascript\nconst React = require(\"react\");\nconst ReactDOMServer = require(\"react-dom/server\");\nconst sharp = require(\"sharp\");\nconst { FaCheckCircle, FaChartLine } = require(\"react-icons/fa\");\n\nfunction renderIconSvg(IconComponent, color = \"#000000\", size = 256) {\n return ReactDOMServer.renderToStaticMarkup(\n React.createElement(IconComponent, { color, size: String(size) })\n );\n}\n\nasync function iconToBase64Png(IconComponent, color, size = 256) {\n const svg = renderIconSvg(IconComponent, color, size);\n const pngBuffer = await sharp(Buffer.from(svg)).png().toBuffer();\n return \"image/png;base64,\" + pngBuffer.toString(\"base64\");\n}\n```\n\n### Add Icon to Slide\n\n```javascript\nconst iconData = await iconToBase64Png(FaCheckCircle, \"#4472C4\", 256);\n\nslide.addImage({\n data: iconData,\n x: 1, y: 1, w: 0.5, h: 0.5 // Size in inches\n});\n```\n\n**Note**: Use size 256 or higher for crisp icons. The size parameter controls the rasterization resolution, not the display size on the slide (which is set by `w` and `h` in inches).\n\n### Icon Libraries\n\nInstall: `npm install -g react-icons react react-dom sharp`\n\nPopular icon sets in react-icons:\n- `react-icons/fa` - Font Awesome\n- `react-icons/md` - Material Design\n- `react-icons/hi` - Heroicons\n- `react-icons/bi` - Bootstrap Icons\n\n---\n\n## Slide Backgrounds\n\n```javascript\n// Solid color\nslide.background = { color: \"F1F1F1\" };\n\n// Color with transparency\nslide.background = { color: \"FF3399\", transparency: 50 };\n\n// Image from URL\nslide.background = { path: \"https://example.com/bg.jpg\" };\n\n// Image from base64\nslide.background = { data: \"image/png;base64,iVBORw0KGgo...\" };\n```\n\n---\n\n## Tables\n\n```javascript\nslide.addTable([\n [\"Header 1\", \"Header 2\"],\n [\"Cell 1\", \"Cell 2\"]\n], {\n x: 1, y: 1, w: 8, h: 2,\n border: { pt: 1, color: \"999999\" }, fill: { color: \"F1F1F1\" }\n});\n\n// Advanced with merged cells\nlet tableData = [\n [{ text: \"Header\", options: { fill: { color: \"6699CC\" }, color: \"FFFFFF\", bold: true } }, \"Cell\"],\n [{ text: \"Merged\", options: { colspan: 2 } }]\n];\nslide.addTable(tableData, { x: 1, y: 3.5, w: 8, colW: [4, 4] });\n```\n\n---\n\n## Charts\n\n```javascript\n// Bar chart\nslide.addChart(pres.charts.BAR, [{\n name: \"Sales\", labels: [\"Q1\", \"Q2\", \"Q3\", \"Q4\"], values: [4500, 5500, 6200, 7100]\n}], {\n x: 0.5, y: 0.6, w: 6, h: 3, barDir: 'col',\n showTitle: true, title: 'Quarterly Sales'\n});\n\n// Line chart\nslide.addChart(pres.charts.LINE, [{\n name: \"Temp\", labels: [\"Jan\", \"Feb\", \"Mar\"], values: [32, 35, 42]\n}], { x: 0.5, y: 4, w: 6, h: 3, lineSize: 3, lineSmooth: true });\n\n// Pie chart\nslide.addChart(pres.charts.PIE, [{\n name: \"Share\", labels: [\"A\", \"B\", \"Other\"], values: [35, 45, 20]\n}], { x: 7, y: 1, w: 5, h: 4, showPercent: true });\n```\n\n### Better-Looking Charts\n\nDefault charts look dated. Apply these options for a modern, clean appearance:\n\n```javascript\nslide.addChart(pres.charts.BAR, chartData, {\n x: 0.5, y: 1, w: 9, h: 4, barDir: \"col\",\n\n // Custom colors (match your presentation palette)\n chartColors: [\"0D9488\", \"14B8A6\", \"5EEAD4\"],\n\n // Clean background\n chartArea: { fill: { color: \"FFFFFF\" }, roundedCorners: true },\n\n // Muted axis labels\n catAxisLabelColor: \"64748B\",\n valAxisLabelColor: \"64748B\",\n\n // Subtle grid (value axis only)\n valGridLine: { color: \"E2E8F0\", size: 0.5 },\n catGridLine: { style: \"none\" },\n\n // Data labels on bars\n showValue: true,\n dataLabelPosition: \"outEnd\",\n dataLabelColor: \"1E293B\",\n\n // Hide legend for single series\n showLegend: false,\n});\n```\n\n**Key styling options:**\n- `chartColors: [...]` - hex colors for series/segments\n- `chartArea: { fill, border, roundedCorners }` - chart background\n- `catGridLine/valGridLine: { color, style, size }` - grid lines (`style: \"none\"` to hide)\n- `lineSmooth: true` - curved lines (line charts)\n- `legendPos: \"r\"` - legend position: \"b\", \"t\", \"l\", \"r\", \"tr\"\n\n---\n\n## Slide Masters\n\n```javascript\npres.defineSlideMaster({\n title: 'TITLE_SLIDE', background: { color: '283A5E' },\n objects: [{\n placeholder: { options: { name: 'title', type: 'title', x: 1, y: 2, w: 8, h: 2 } }\n }]\n});\n\nlet titleSlide = pres.addSlide({ masterName: \"TITLE_SLIDE\" });\ntitleSlide.addText(\"My Title\", { placeholder: \"title\" });\n```\n\n---\n\n## Common Pitfalls\n\n⚠️ These issues cause file corruption, visual bugs, or broken output. Avoid them.\n\n1. **NEVER use \"#\" with hex colors** - causes file corruption\n ```javascript\n color: \"FF0000\" // ✅ CORRECT\n color: \"#FF0000\" // ❌ WRONG\n ```\n\n2. **NEVER encode opacity in hex color strings** - 8-char colors (e.g., `\"00000020\"`) corrupt the file. Use the `opacity` property instead.\n ```javascript\n shadow: { type: \"outer\", blur: 6, offset: 2, color: \"00000020\" } // ❌ CORRUPTS FILE\n shadow: { type: \"outer\", blur: 6, offset: 2, color: \"000000\", opacity: 0.12 } // ✅ CORRECT\n ```\n\n3. **Use `bullet: true`** - NEVER unicode symbols like \"•\" (creates double bullets)\n\n4. **Use `breakLine: true`** between array items or text runs together\n\n5. **Avoid `lineSpacing` with bullets** - causes excessive gaps; use `paraSpaceAfter` instead\n\n6. **Each presentation needs fresh instance** - don't reuse `pptxgen()` objects\n\n7. **NEVER reuse option objects across calls** - PptxGenJS mutates objects in-place (e.g. converting shadow values to EMU). Sharing one object between multiple calls corrupts the second shape.\n ```javascript\n const shadow = { type: \"outer\", blur: 6, offset: 2, color: \"000000\", opacity: 0.15 };\n slide.addShape(pres.shapes.RECTANGLE, { shadow, ... }); // ❌ second call gets already-converted values\n slide.addShape(pres.shapes.RECTANGLE, { shadow, ... });\n\n const makeShadow = () => ({ type: \"outer\", blur: 6, offset: 2, color: \"000000\", opacity: 0.15 });\n slide.addShape(pres.shapes.RECTANGLE, { shadow: makeShadow(), ... }); // ✅ fresh object each time\n slide.addShape(pres.shapes.RECTANGLE, { shadow: makeShadow(), ... });\n ```\n\n8. **Don't use `ROUNDED_RECTANGLE` with accent borders** - rectangular overlay bars won't cover rounded corners. Use `RECTANGLE` instead.\n ```javascript\n // ❌ WRONG: Accent bar doesn't cover rounded corners\n slide.addShape(pres.shapes.ROUNDED_RECTANGLE, { x: 1, y: 1, w: 3, h: 1.5, fill: { color: \"FFFFFF\" } });\n slide.addShape(pres.shapes.RECTANGLE, { x: 1, y: 1, w: 0.08, h: 1.5, fill: { color: \"0891B2\" } });\n\n // ✅ CORRECT: Use RECTANGLE for clean alignment\n slide.addShape(pres.shapes.RECTANGLE, { x: 1, y: 1, w: 3, h: 1.5, fill: { color: \"FFFFFF\" } });\n slide.addShape(pres.shapes.RECTANGLE, { x: 1, y: 1, w: 0.08, h: 1.5, fill: { color: \"0891B2\" } });\n ```\n\n---\n\n## Quick Reference\n\n- **Shapes**: RECTANGLE, OVAL, LINE, ROUNDED_RECTANGLE\n- **Charts**: BAR, LINE, PIE, DOUGHNUT, SCATTER, BUBBLE, RADAR\n- **Layouts**: LAYOUT_16x9 (10\"×5.625\"), LAYOUT_16x10, LAYOUT_4x3, LAYOUT_WIDE\n- **Alignment**: \"left\", \"center\", \"right\"\n- **Chart data labels**: \"outEnd\", \"inEnd\", \"center\"\n" }, { "path": "src/copaw/agents/skills/pptx/scripts/__init__.py", "content": "" }, { "path": "src/copaw/agents/skills/pptx/scripts/add_slide.py", "content": "\"\"\"Add a new slide to an unpacked PPTX directory.\n\nUsage: python add_slide.py \n\nThe source can be:\n - A slide file (e.g., slide2.xml) - duplicates the slide\n - A layout file (e.g., slideLayout2.xml) - creates from layout\n\nExamples:\n python add_slide.py unpacked/ slide2.xml\n # Duplicates slide2, creates slide5.xml\n\n python add_slide.py unpacked/ slideLayout2.xml\n # Creates slide5.xml from slideLayout2.xml\n\nTo see available layouts: ls unpacked/ppt/slideLayouts/\n\nPrints the element to add to presentation.xml.\n\"\"\"\n\nimport re\nimport shutil\nimport sys\nfrom pathlib import Path\n\n\ndef get_next_slide_number(slides_dir: Path) -> int:\n existing = [int(m.group(1)) for f in slides_dir.glob(\"slide*.xml\")\n if (m := re.match(r\"slide(\\d+)\\.xml\", f.name))]\n return max(existing) + 1 if existing else 1\n\n\ndef create_slide_from_layout(unpacked_dir: Path, layout_file: str) -> None:\n slides_dir = unpacked_dir / \"ppt\" / \"slides\"\n rels_dir = slides_dir / \"_rels\"\n layouts_dir = unpacked_dir / \"ppt\" / \"slideLayouts\"\n\n layout_path = layouts_dir / layout_file\n if not layout_path.exists():\n print(f\"Error: {layout_path} not found\", file=sys.stderr)\n sys.exit(1)\n\n next_num = get_next_slide_number(slides_dir)\n dest = f\"slide{next_num}.xml\"\n dest_slide = slides_dir / dest\n dest_rels = rels_dir / f\"{dest}.rels\"\n\n slide_xml = '''\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n'''\n dest_slide.write_text(slide_xml, encoding=\"utf-8\")\n\n rels_dir.mkdir(exist_ok=True)\n rels_xml = f'''\n\n \n'''\n dest_rels.write_text(rels_xml, encoding=\"utf-8\")\n\n _add_to_content_types(unpacked_dir, dest)\n\n rid = _add_to_presentation_rels(unpacked_dir, dest)\n\n next_slide_id = _get_next_slide_id(unpacked_dir)\n\n print(f\"Created {dest} from {layout_file}\")\n print(f'Add to presentation.xml : ')\n\n\ndef duplicate_slide(unpacked_dir: Path, source: str) -> None:\n slides_dir = unpacked_dir / \"ppt\" / \"slides\"\n rels_dir = slides_dir / \"_rels\"\n\n source_slide = slides_dir / source\n\n if not source_slide.exists():\n print(f\"Error: {source_slide} not found\", file=sys.stderr)\n sys.exit(1)\n\n next_num = get_next_slide_number(slides_dir)\n dest = f\"slide{next_num}.xml\"\n dest_slide = slides_dir / dest\n\n source_rels = rels_dir / f\"{source}.rels\"\n dest_rels = rels_dir / f\"{dest}.rels\"\n\n shutil.copy2(source_slide, dest_slide)\n\n if source_rels.exists():\n shutil.copy2(source_rels, dest_rels)\n\n rels_content = dest_rels.read_text(encoding=\"utf-8\")\n rels_content = re.sub(\n r'\\s*]*Type=\"[^\"]*notesSlide\"[^>]*/>\\s*',\n \"\\n\",\n rels_content,\n )\n dest_rels.write_text(rels_content, encoding=\"utf-8\")\n\n _add_to_content_types(unpacked_dir, dest)\n\n rid = _add_to_presentation_rels(unpacked_dir, dest)\n\n next_slide_id = _get_next_slide_id(unpacked_dir)\n\n print(f\"Created {dest} from {source}\")\n print(f'Add to presentation.xml : ')\n\n\ndef _add_to_content_types(unpacked_dir: Path, dest: str) -> None:\n content_types_path = unpacked_dir / \"[Content_Types].xml\"\n content_types = content_types_path.read_text(encoding=\"utf-8\")\n\n new_override = f''\n\n if f\"/ppt/slides/{dest}\" not in content_types:\n content_types = content_types.replace(\"\", f\" {new_override}\\n\")\n content_types_path.write_text(content_types, encoding=\"utf-8\")\n\n\ndef _add_to_presentation_rels(unpacked_dir: Path, dest: str) -> str:\n pres_rels_path = unpacked_dir / \"ppt\" / \"_rels\" / \"presentation.xml.rels\"\n pres_rels = pres_rels_path.read_text(encoding=\"utf-8\")\n\n rids = [int(m) for m in re.findall(r'Id=\"rId(\\d+)\"', pres_rels)]\n next_rid = max(rids) + 1 if rids else 1\n rid = f\"rId{next_rid}\"\n\n new_rel = f''\n\n if f\"slides/{dest}\" not in pres_rels:\n pres_rels = pres_rels.replace(\"\", f\" {new_rel}\\n\")\n pres_rels_path.write_text(pres_rels, encoding=\"utf-8\")\n\n return rid\n\n\ndef _get_next_slide_id(unpacked_dir: Path) -> int:\n pres_path = unpacked_dir / \"ppt\" / \"presentation.xml\"\n pres_content = pres_path.read_text(encoding=\"utf-8\")\n slide_ids = [int(m) for m in re.findall(r']*id=\"(\\d+)\"', pres_content)]\n return max(slide_ids) + 1 if slide_ids else 256\n\n\ndef parse_source(source: str) -> tuple[str, str | None]:\n if source.startswith(\"slideLayout\") and source.endswith(\".xml\"):\n return (\"layout\", source)\n\n return (\"slide\", None)\n\n\nif __name__ == \"__main__\":\n if len(sys.argv) != 3:\n print(\"Usage: python add_slide.py \", file=sys.stderr)\n print(\"\", file=sys.stderr)\n print(\"Source can be:\", file=sys.stderr)\n print(\" slide2.xml - duplicate an existing slide\", file=sys.stderr)\n print(\" slideLayout2.xml - create from a layout template\", file=sys.stderr)\n print(\"\", file=sys.stderr)\n print(\"To see available layouts: ls /ppt/slideLayouts/\", file=sys.stderr)\n sys.exit(1)\n\n unpacked_dir = Path(sys.argv[1])\n source = sys.argv[2]\n\n if not unpacked_dir.exists():\n print(f\"Error: {unpacked_dir} not found\", file=sys.stderr)\n sys.exit(1)\n\n source_type, layout_file = parse_source(source)\n\n if source_type == \"layout\" and layout_file is not None:\n create_slide_from_layout(unpacked_dir, layout_file)\n else:\n duplicate_slide(unpacked_dir, source)\n" }, { "path": "src/copaw/agents/skills/pptx/scripts/clean.py", "content": "\"\"\"Remove unreferenced files from an unpacked PPTX directory.\n\nUsage: python clean.py \n\nExample:\n python clean.py unpacked/\n\nThis script removes:\n- Orphaned slides (not in sldIdLst) and their relationships\n- [trash] directory (unreferenced files)\n- Orphaned .rels files for deleted resources\n- Unreferenced media, embeddings, charts, diagrams, drawings, ink files\n- Unreferenced theme files\n- Unreferenced notes slides\n- Content-Type overrides for deleted files\n\"\"\"\n\nimport sys\nfrom pathlib import Path\n\nimport defusedxml.minidom\n\n\nimport re\n\n\ndef get_slides_in_sldidlst(unpacked_dir: Path) -> set[str]:\n pres_path = unpacked_dir / \"ppt\" / \"presentation.xml\"\n pres_rels_path = unpacked_dir / \"ppt\" / \"_rels\" / \"presentation.xml.rels\"\n\n if not pres_path.exists() or not pres_rels_path.exists():\n return set()\n\n rels_dom = defusedxml.minidom.parse(str(pres_rels_path))\n rid_to_slide = {}\n for rel in rels_dom.getElementsByTagName(\"Relationship\"):\n rid = rel.getAttribute(\"Id\")\n target = rel.getAttribute(\"Target\")\n rel_type = rel.getAttribute(\"Type\")\n if \"slide\" in rel_type and target.startswith(\"slides/\"):\n rid_to_slide[rid] = target.replace(\"slides/\", \"\")\n\n pres_content = pres_path.read_text(encoding=\"utf-8\")\n referenced_rids = set(re.findall(r']*r:id=\"([^\"]+)\"', pres_content))\n\n return {rid_to_slide[rid] for rid in referenced_rids if rid in rid_to_slide}\n\n\ndef remove_orphaned_slides(unpacked_dir: Path) -> list[str]:\n slides_dir = unpacked_dir / \"ppt\" / \"slides\"\n slides_rels_dir = slides_dir / \"_rels\"\n pres_rels_path = unpacked_dir / \"ppt\" / \"_rels\" / \"presentation.xml.rels\"\n\n if not slides_dir.exists():\n return []\n\n referenced_slides = get_slides_in_sldidlst(unpacked_dir)\n removed = []\n\n for slide_file in slides_dir.glob(\"slide*.xml\"):\n if slide_file.name not in referenced_slides:\n rel_path = slide_file.relative_to(unpacked_dir)\n slide_file.unlink()\n removed.append(str(rel_path))\n\n rels_file = slides_rels_dir / f\"{slide_file.name}.rels\"\n if rels_file.exists():\n rels_file.unlink()\n removed.append(str(rels_file.relative_to(unpacked_dir)))\n\n if removed and pres_rels_path.exists():\n rels_dom = defusedxml.minidom.parse(str(pres_rels_path))\n changed = False\n\n for rel in list(rels_dom.getElementsByTagName(\"Relationship\")):\n target = rel.getAttribute(\"Target\")\n if target.startswith(\"slides/\"):\n slide_name = target.replace(\"slides/\", \"\")\n if slide_name not in referenced_slides:\n if rel.parentNode:\n rel.parentNode.removeChild(rel)\n changed = True\n\n if changed:\n with open(pres_rels_path, \"wb\") as f:\n f.write(rels_dom.toxml(encoding=\"utf-8\"))\n\n return removed\n\n\ndef remove_trash_directory(unpacked_dir: Path) -> list[str]:\n trash_dir = unpacked_dir / \"[trash]\"\n removed = []\n\n if trash_dir.exists() and trash_dir.is_dir():\n for file_path in trash_dir.iterdir():\n if file_path.is_file():\n rel_path = file_path.relative_to(unpacked_dir)\n removed.append(str(rel_path))\n file_path.unlink()\n trash_dir.rmdir()\n\n return removed\n\n\ndef get_slide_referenced_files(unpacked_dir: Path) -> set:\n referenced = set()\n slides_rels_dir = unpacked_dir / \"ppt\" / \"slides\" / \"_rels\"\n\n if not slides_rels_dir.exists():\n return referenced\n\n for rels_file in slides_rels_dir.glob(\"*.rels\"):\n dom = defusedxml.minidom.parse(str(rels_file))\n for rel in dom.getElementsByTagName(\"Relationship\"):\n target = rel.getAttribute(\"Target\")\n if not target:\n continue\n target_path = (rels_file.parent.parent / target).resolve()\n try:\n referenced.add(target_path.relative_to(unpacked_dir.resolve()))\n except ValueError:\n pass\n\n return referenced\n\n\ndef remove_orphaned_rels_files(unpacked_dir: Path) -> list[str]:\n resource_dirs = [\"charts\", \"diagrams\", \"drawings\"]\n removed = []\n slide_referenced = get_slide_referenced_files(unpacked_dir)\n\n for dir_name in resource_dirs:\n rels_dir = unpacked_dir / \"ppt\" / dir_name / \"_rels\"\n if not rels_dir.exists():\n continue\n\n for rels_file in rels_dir.glob(\"*.rels\"):\n resource_file = rels_dir.parent / rels_file.name.replace(\".rels\", \"\")\n try:\n resource_rel_path = resource_file.resolve().relative_to(unpacked_dir.resolve())\n except ValueError:\n continue\n\n if not resource_file.exists() or resource_rel_path not in slide_referenced:\n rels_file.unlink()\n rel_path = rels_file.relative_to(unpacked_dir)\n removed.append(str(rel_path))\n\n return removed\n\n\ndef get_referenced_files(unpacked_dir: Path) -> set:\n referenced = set()\n\n for rels_file in unpacked_dir.rglob(\"*.rels\"):\n dom = defusedxml.minidom.parse(str(rels_file))\n for rel in dom.getElementsByTagName(\"Relationship\"):\n target = rel.getAttribute(\"Target\")\n if not target:\n continue\n target_path = (rels_file.parent.parent / target).resolve()\n try:\n referenced.add(target_path.relative_to(unpacked_dir.resolve()))\n except ValueError:\n pass\n\n return referenced\n\n\ndef remove_orphaned_files(unpacked_dir: Path, referenced: set) -> list[str]:\n resource_dirs = [\"media\", \"embeddings\", \"charts\", \"diagrams\", \"tags\", \"drawings\", \"ink\"]\n removed = []\n\n for dir_name in resource_dirs:\n dir_path = unpacked_dir / \"ppt\" / dir_name\n if not dir_path.exists():\n continue\n\n for file_path in dir_path.glob(\"*\"):\n if not file_path.is_file():\n continue\n rel_path = file_path.relative_to(unpacked_dir)\n if rel_path not in referenced:\n file_path.unlink()\n removed.append(str(rel_path))\n\n theme_dir = unpacked_dir / \"ppt\" / \"theme\"\n if theme_dir.exists():\n for file_path in theme_dir.glob(\"theme*.xml\"):\n rel_path = file_path.relative_to(unpacked_dir)\n if rel_path not in referenced:\n file_path.unlink()\n removed.append(str(rel_path))\n theme_rels = theme_dir / \"_rels\" / f\"{file_path.name}.rels\"\n if theme_rels.exists():\n theme_rels.unlink()\n removed.append(str(theme_rels.relative_to(unpacked_dir)))\n\n notes_dir = unpacked_dir / \"ppt\" / \"notesSlides\"\n if notes_dir.exists():\n for file_path in notes_dir.glob(\"*.xml\"):\n if not file_path.is_file():\n continue\n rel_path = file_path.relative_to(unpacked_dir)\n if rel_path not in referenced:\n file_path.unlink()\n removed.append(str(rel_path))\n\n notes_rels_dir = notes_dir / \"_rels\"\n if notes_rels_dir.exists():\n for file_path in notes_rels_dir.glob(\"*.rels\"):\n notes_file = notes_dir / file_path.name.replace(\".rels\", \"\")\n if not notes_file.exists():\n file_path.unlink()\n removed.append(str(file_path.relative_to(unpacked_dir)))\n\n return removed\n\n\ndef update_content_types(unpacked_dir: Path, removed_files: list[str]) -> None:\n ct_path = unpacked_dir / \"[Content_Types].xml\"\n if not ct_path.exists():\n return\n\n dom = defusedxml.minidom.parse(str(ct_path))\n changed = False\n\n for override in list(dom.getElementsByTagName(\"Override\")):\n part_name = override.getAttribute(\"PartName\").lstrip(\"/\")\n if part_name in removed_files:\n if override.parentNode:\n override.parentNode.removeChild(override)\n changed = True\n\n if changed:\n with open(ct_path, \"wb\") as f:\n f.write(dom.toxml(encoding=\"utf-8\"))\n\n\ndef clean_unused_files(unpacked_dir: Path) -> list[str]:\n all_removed = []\n\n slides_removed = remove_orphaned_slides(unpacked_dir)\n all_removed.extend(slides_removed)\n\n trash_removed = remove_trash_directory(unpacked_dir)\n all_removed.extend(trash_removed)\n\n while True:\n removed_rels = remove_orphaned_rels_files(unpacked_dir)\n referenced = get_referenced_files(unpacked_dir)\n removed_files = remove_orphaned_files(unpacked_dir, referenced)\n\n total_removed = removed_rels + removed_files\n if not total_removed:\n break\n\n all_removed.extend(total_removed)\n\n if all_removed:\n update_content_types(unpacked_dir, all_removed)\n\n return all_removed\n\n\nif __name__ == \"__main__\":\n if len(sys.argv) != 2:\n print(\"Usage: python clean.py \", file=sys.stderr)\n print(\"Example: python clean.py unpacked/\", file=sys.stderr)\n sys.exit(1)\n\n unpacked_dir = Path(sys.argv[1])\n\n if not unpacked_dir.exists():\n print(f\"Error: {unpacked_dir} not found\", file=sys.stderr)\n sys.exit(1)\n\n removed = clean_unused_files(unpacked_dir)\n\n if removed:\n print(f\"Removed {len(removed)} unreferenced files:\")\n for f in removed:\n print(f\" {f}\")\n else:\n print(\"No unreferenced files found\")\n" }, { "path": "src/copaw/agents/skills/pptx/scripts/office/helpers/__init__.py", "content": "" }, { "path": "src/copaw/agents/skills/pptx/scripts/office/helpers/merge_runs.py", "content": "\"\"\"Merge adjacent runs with identical formatting in DOCX.\n\nMerges adjacent elements that have identical properties.\nWorks on runs in paragraphs and inside tracked changes (, ).\n\nAlso:\n- Removes rsid attributes from runs (revision metadata that doesn't affect rendering)\n- Removes proofErr elements (spell/grammar markers that block merging)\n\"\"\"\n\nfrom pathlib import Path\n\nimport defusedxml.minidom\n\n\ndef merge_runs(input_dir: str) -> tuple[int, str]:\n doc_xml = Path(input_dir) / \"word\" / \"document.xml\"\n\n if not doc_xml.exists():\n return 0, f\"Error: {doc_xml} not found\"\n\n try:\n dom = defusedxml.minidom.parseString(doc_xml.read_text(encoding=\"utf-8\"))\n root = dom.documentElement\n\n _remove_elements(root, \"proofErr\")\n _strip_run_rsid_attrs(root)\n\n containers = {run.parentNode for run in _find_elements(root, \"r\")}\n\n merge_count = 0\n for container in containers:\n merge_count += _merge_runs_in(container)\n\n doc_xml.write_bytes(dom.toxml(encoding=\"UTF-8\"))\n return merge_count, f\"Merged {merge_count} runs\"\n\n except Exception as e:\n return 0, f\"Error: {e}\"\n\n\n\n\ndef _find_elements(root, tag: str) -> list:\n results = []\n\n def traverse(node):\n if node.nodeType == node.ELEMENT_NODE:\n name = node.localName or node.tagName\n if name == tag or name.endswith(f\":{tag}\"):\n results.append(node)\n for child in node.childNodes:\n traverse(child)\n\n traverse(root)\n return results\n\n\ndef _get_child(parent, tag: str):\n for child in parent.childNodes:\n if child.nodeType == child.ELEMENT_NODE:\n name = child.localName or child.tagName\n if name == tag or name.endswith(f\":{tag}\"):\n return child\n return None\n\n\ndef _get_children(parent, tag: str) -> list:\n results = []\n for child in parent.childNodes:\n if child.nodeType == child.ELEMENT_NODE:\n name = child.localName or child.tagName\n if name == tag or name.endswith(f\":{tag}\"):\n results.append(child)\n return results\n\n\ndef _is_adjacent(elem1, elem2) -> bool:\n node = elem1.nextSibling\n while node:\n if node == elem2:\n return True\n if node.nodeType == node.ELEMENT_NODE:\n return False\n if node.nodeType == node.TEXT_NODE and node.data.strip():\n return False\n node = node.nextSibling\n return False\n\n\n\n\ndef _remove_elements(root, tag: str):\n for elem in _find_elements(root, tag):\n if elem.parentNode:\n elem.parentNode.removeChild(elem)\n\n\ndef _strip_run_rsid_attrs(root):\n for run in _find_elements(root, \"r\"):\n for attr in list(run.attributes.values()):\n if \"rsid\" in attr.name.lower():\n run.removeAttribute(attr.name)\n\n\n\n\ndef _merge_runs_in(container) -> int:\n merge_count = 0\n run = _first_child_run(container)\n\n while run:\n while True:\n next_elem = _next_element_sibling(run)\n if next_elem and _is_run(next_elem) and _can_merge(run, next_elem):\n _merge_run_content(run, next_elem)\n container.removeChild(next_elem)\n merge_count += 1\n else:\n break\n\n _consolidate_text(run)\n run = _next_sibling_run(run)\n\n return merge_count\n\n\ndef _first_child_run(container):\n for child in container.childNodes:\n if child.nodeType == child.ELEMENT_NODE and _is_run(child):\n return child\n return None\n\n\ndef _next_element_sibling(node):\n sibling = node.nextSibling\n while sibling:\n if sibling.nodeType == sibling.ELEMENT_NODE:\n return sibling\n sibling = sibling.nextSibling\n return None\n\n\ndef _next_sibling_run(node):\n sibling = node.nextSibling\n while sibling:\n if sibling.nodeType == sibling.ELEMENT_NODE:\n if _is_run(sibling):\n return sibling\n sibling = sibling.nextSibling\n return None\n\n\ndef _is_run(node) -> bool:\n name = node.localName or node.tagName\n return name == \"r\" or name.endswith(\":r\")\n\n\ndef _can_merge(run1, run2) -> bool:\n rpr1 = _get_child(run1, \"rPr\")\n rpr2 = _get_child(run2, \"rPr\")\n\n if (rpr1 is None) != (rpr2 is None):\n return False\n if rpr1 is None:\n return True\n return rpr1.toxml() == rpr2.toxml() \n\n\ndef _merge_run_content(target, source):\n for child in list(source.childNodes):\n if child.nodeType == child.ELEMENT_NODE:\n name = child.localName or child.tagName\n if name != \"rPr\" and not name.endswith(\":rPr\"):\n target.appendChild(child)\n\n\ndef _consolidate_text(run):\n t_elements = _get_children(run, \"t\")\n\n for i in range(len(t_elements) - 1, 0, -1):\n curr, prev = t_elements[i], t_elements[i - 1]\n\n if _is_adjacent(prev, curr):\n prev_text = prev.firstChild.data if prev.firstChild else \"\"\n curr_text = curr.firstChild.data if curr.firstChild else \"\"\n merged = prev_text + curr_text\n\n if prev.firstChild:\n prev.firstChild.data = merged\n else:\n prev.appendChild(run.ownerDocument.createTextNode(merged))\n\n if merged.startswith(\" \") or merged.endswith(\" \"):\n prev.setAttribute(\"xml:space\", \"preserve\")\n elif prev.hasAttribute(\"xml:space\"):\n prev.removeAttribute(\"xml:space\")\n\n run.removeChild(curr)\n" }, { "path": "src/copaw/agents/skills/pptx/scripts/office/helpers/simplify_redlines.py", "content": "\"\"\"Simplify tracked changes by merging adjacent w:ins or w:del elements.\n\nMerges adjacent elements from the same author into a single element.\nSame for elements. This makes heavily-redlined documents easier to\nwork with by reducing the number of tracked change wrappers.\n\nRules:\n- Only merges w:ins with w:ins, w:del with w:del (same element type)\n- Only merges if same author (ignores timestamp differences)\n- Only merges if truly adjacent (only whitespace between them)\n\"\"\"\n\nimport xml.etree.ElementTree as ET\nimport zipfile\nfrom pathlib import Path\n\nimport defusedxml.minidom\n\nWORD_NS = \"http://schemas.openxmlformats.org/wordprocessingml/2006/main\"\n\n\ndef simplify_redlines(input_dir: str) -> tuple[int, str]:\n doc_xml = Path(input_dir) / \"word\" / \"document.xml\"\n\n if not doc_xml.exists():\n return 0, f\"Error: {doc_xml} not found\"\n\n try:\n dom = defusedxml.minidom.parseString(doc_xml.read_text(encoding=\"utf-8\"))\n root = dom.documentElement\n\n merge_count = 0\n\n containers = _find_elements(root, \"p\") + _find_elements(root, \"tc\")\n\n for container in containers:\n merge_count += _merge_tracked_changes_in(container, \"ins\")\n merge_count += _merge_tracked_changes_in(container, \"del\")\n\n doc_xml.write_bytes(dom.toxml(encoding=\"UTF-8\"))\n return merge_count, f\"Simplified {merge_count} tracked changes\"\n\n except Exception as e:\n return 0, f\"Error: {e}\"\n\n\ndef _merge_tracked_changes_in(container, tag: str) -> int:\n merge_count = 0\n\n tracked = [\n child\n for child in container.childNodes\n if child.nodeType == child.ELEMENT_NODE and _is_element(child, tag)\n ]\n\n if len(tracked) < 2:\n return 0\n\n i = 0\n while i < len(tracked) - 1:\n curr = tracked[i]\n next_elem = tracked[i + 1]\n\n if _can_merge_tracked(curr, next_elem):\n _merge_tracked_content(curr, next_elem)\n container.removeChild(next_elem)\n tracked.pop(i + 1)\n merge_count += 1\n else:\n i += 1\n\n return merge_count\n\n\ndef _is_element(node, tag: str) -> bool:\n name = node.localName or node.tagName\n return name == tag or name.endswith(f\":{tag}\")\n\n\ndef _get_author(elem) -> str:\n author = elem.getAttribute(\"w:author\")\n if not author:\n for attr in elem.attributes.values():\n if attr.localName == \"author\" or attr.name.endswith(\":author\"):\n return attr.value\n return author\n\n\ndef _can_merge_tracked(elem1, elem2) -> bool:\n if _get_author(elem1) != _get_author(elem2):\n return False\n\n node = elem1.nextSibling\n while node and node != elem2:\n if node.nodeType == node.ELEMENT_NODE:\n return False\n if node.nodeType == node.TEXT_NODE and node.data.strip():\n return False\n node = node.nextSibling\n\n return True\n\n\ndef _merge_tracked_content(target, source):\n while source.firstChild:\n child = source.firstChild\n source.removeChild(child)\n target.appendChild(child)\n\n\ndef _find_elements(root, tag: str) -> list:\n results = []\n\n def traverse(node):\n if node.nodeType == node.ELEMENT_NODE:\n name = node.localName or node.tagName\n if name == tag or name.endswith(f\":{tag}\"):\n results.append(node)\n for child in node.childNodes:\n traverse(child)\n\n traverse(root)\n return results\n\n\ndef get_tracked_change_authors(doc_xml_path: Path) -> dict[str, int]:\n if not doc_xml_path.exists():\n return {}\n\n try:\n tree = ET.parse(doc_xml_path)\n root = tree.getroot()\n except ET.ParseError:\n return {}\n\n namespaces = {\"w\": WORD_NS}\n author_attr = f\"{{{WORD_NS}}}author\"\n\n authors: dict[str, int] = {}\n for tag in [\"ins\", \"del\"]:\n for elem in root.findall(f\".//w:{tag}\", namespaces):\n author = elem.get(author_attr)\n if author:\n authors[author] = authors.get(author, 0) + 1\n\n return authors\n\n\ndef _get_authors_from_docx(docx_path: Path) -> dict[str, int]:\n try:\n with zipfile.ZipFile(docx_path, \"r\") as zf:\n if \"word/document.xml\" not in zf.namelist():\n return {}\n with zf.open(\"word/document.xml\") as f:\n tree = ET.parse(f)\n root = tree.getroot()\n\n namespaces = {\"w\": WORD_NS}\n author_attr = f\"{{{WORD_NS}}}author\"\n\n authors: dict[str, int] = {}\n for tag in [\"ins\", \"del\"]:\n for elem in root.findall(f\".//w:{tag}\", namespaces):\n author = elem.get(author_attr)\n if author:\n authors[author] = authors.get(author, 0) + 1\n return authors\n except (zipfile.BadZipFile, ET.ParseError):\n return {}\n\n\ndef infer_author(modified_dir: Path, original_docx: Path, default: str = \"Claude\") -> str:\n modified_xml = modified_dir / \"word\" / \"document.xml\"\n modified_authors = get_tracked_change_authors(modified_xml)\n\n if not modified_authors:\n return default\n\n original_authors = _get_authors_from_docx(original_docx)\n\n new_changes: dict[str, int] = {}\n for author, count in modified_authors.items():\n original_count = original_authors.get(author, 0)\n diff = count - original_count\n if diff > 0:\n new_changes[author] = diff\n\n if not new_changes:\n return default\n\n if len(new_changes) == 1:\n return next(iter(new_changes))\n\n raise ValueError(\n f\"Multiple authors added new changes: {new_changes}. \"\n \"Cannot infer which author to validate.\"\n )\n" }, { "path": "src/copaw/agents/skills/pptx/scripts/office/pack.py", "content": "\"\"\"Pack a directory into a DOCX, PPTX, or XLSX file.\n\nValidates with auto-repair, condenses XML formatting, and creates the Office file.\n\nUsage:\n python pack.py [--original ] [--validate true|false]\n\nExamples:\n python pack.py unpacked/ output.docx --original input.docx\n python pack.py unpacked/ output.pptx --validate false\n\"\"\"\n\nimport argparse\nimport sys\nimport shutil\nimport tempfile\nimport zipfile\nfrom pathlib import Path\n\nimport defusedxml.minidom\n\nfrom validators import DOCXSchemaValidator, PPTXSchemaValidator, RedliningValidator\n\ndef pack(\n input_directory: str,\n output_file: str,\n original_file: str | None = None,\n validate: bool = True,\n infer_author_func=None,\n) -> tuple[None, str]:\n input_dir = Path(input_directory)\n output_path = Path(output_file)\n suffix = output_path.suffix.lower()\n\n if not input_dir.is_dir():\n return None, f\"Error: {input_dir} is not a directory\"\n\n if suffix not in {\".docx\", \".pptx\", \".xlsx\"}:\n return None, f\"Error: {output_file} must be a .docx, .pptx, or .xlsx file\"\n\n if validate and original_file:\n original_path = Path(original_file)\n if original_path.exists():\n success, output = _run_validation(\n input_dir, original_path, suffix, infer_author_func\n )\n if output:\n print(output)\n if not success:\n return None, f\"Error: Validation failed for {input_dir}\"\n\n with tempfile.TemporaryDirectory() as temp_dir:\n temp_content_dir = Path(temp_dir) / \"content\"\n shutil.copytree(input_dir, temp_content_dir)\n\n for pattern in [\"*.xml\", \"*.rels\"]:\n for xml_file in temp_content_dir.rglob(pattern):\n _condense_xml(xml_file)\n\n output_path.parent.mkdir(parents=True, exist_ok=True)\n with zipfile.ZipFile(output_path, \"w\", zipfile.ZIP_DEFLATED) as zf:\n for f in temp_content_dir.rglob(\"*\"):\n if f.is_file():\n zf.write(f, f.relative_to(temp_content_dir))\n\n return None, f\"Successfully packed {input_dir} to {output_file}\"\n\n\ndef _run_validation(\n unpacked_dir: Path,\n original_file: Path,\n suffix: str,\n infer_author_func=None,\n) -> tuple[bool, str | None]:\n output_lines = []\n validators = []\n\n if suffix == \".docx\":\n author = \"Claude\"\n if infer_author_func:\n try:\n author = infer_author_func(unpacked_dir, original_file)\n except ValueError as e:\n print(f\"Warning: {e} Using default author 'Claude'.\", file=sys.stderr)\n\n validators = [\n DOCXSchemaValidator(unpacked_dir, original_file),\n RedliningValidator(unpacked_dir, original_file, author=author),\n ]\n elif suffix == \".pptx\":\n validators = [PPTXSchemaValidator(unpacked_dir, original_file)]\n\n if not validators:\n return True, None\n\n total_repairs = sum(v.repair() for v in validators)\n if total_repairs:\n output_lines.append(f\"Auto-repaired {total_repairs} issue(s)\")\n\n success = all(v.validate() for v in validators)\n\n if success:\n output_lines.append(\"All validations PASSED!\")\n\n return success, \"\\n\".join(output_lines) if output_lines else None\n\n\ndef _condense_xml(xml_file: Path) -> None:\n try:\n with open(xml_file, encoding=\"utf-8\") as f:\n dom = defusedxml.minidom.parse(f)\n\n for element in dom.getElementsByTagName(\"*\"):\n if element.tagName.endswith(\":t\"):\n continue\n\n for child in list(element.childNodes):\n if (\n child.nodeType == child.TEXT_NODE\n and child.nodeValue\n and child.nodeValue.strip() == \"\"\n ) or child.nodeType == child.COMMENT_NODE:\n element.removeChild(child)\n\n xml_file.write_bytes(dom.toxml(encoding=\"UTF-8\"))\n except Exception as e:\n print(f\"ERROR: Failed to parse {xml_file.name}: {e}\", file=sys.stderr)\n raise\n\n\nif __name__ == \"__main__\":\n parser = argparse.ArgumentParser(\n description=\"Pack a directory into a DOCX, PPTX, or XLSX file\"\n )\n parser.add_argument(\"input_directory\", help=\"Unpacked Office document directory\")\n parser.add_argument(\"output_file\", help=\"Output Office file (.docx/.pptx/.xlsx)\")\n parser.add_argument(\n \"--original\",\n help=\"Original file for validation comparison\",\n )\n parser.add_argument(\n \"--validate\",\n type=lambda x: x.lower() == \"true\",\n default=True,\n metavar=\"true|false\",\n help=\"Run validation with auto-repair (default: true)\",\n )\n args = parser.parse_args()\n\n _, message = pack(\n args.input_directory,\n args.output_file,\n original_file=args.original,\n validate=args.validate,\n )\n print(message)\n\n if \"Error\" in message:\n sys.exit(1)\n" }, { "path": "src/copaw/agents/skills/pptx/scripts/office/schemas/ISO-IEC29500-4_2016/dml-chart.xsd", "content": "\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n\n" }, { "path": "src/copaw/agents/skills/pptx/scripts/office/schemas/ISO-IEC29500-4_2016/dml-chartDrawing.xsd", "content": "\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n\n" }, { "path": "src/copaw/agents/skills/pptx/scripts/office/schemas/ISO-IEC29500-4_2016/dml-diagram.xsd", "content": "\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n\n" }, { "path": "src/copaw/agents/skills/pptx/scripts/office/schemas/ISO-IEC29500-4_2016/dml-lockedCanvas.xsd", "content": "\n\n \n \n\n" }, { "path": "src/copaw/agents/skills/pptx/scripts/office/schemas/ISO-IEC29500-4_2016/dml-main.xsd", "content": "\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n\n" }, { "path": "src/copaw/agents/skills/pptx/scripts/office/schemas/ISO-IEC29500-4_2016/dml-picture.xsd", "content": "\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n\n" }, { "path": "src/copaw/agents/skills/pptx/scripts/office/schemas/ISO-IEC29500-4_2016/dml-spreadsheetDrawing.xsd", "content": "\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n\n" }, { "path": "src/copaw/agents/skills/pptx/scripts/office/schemas/ISO-IEC29500-4_2016/dml-wordprocessingDrawing.xsd", "content": "\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n\n" }, { "path": "src/copaw/agents/skills/pptx/scripts/office/schemas/ISO-IEC29500-4_2016/pml.xsd", "content": "\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n\n" }, { "path": "src/copaw/agents/skills/pptx/scripts/office/schemas/ISO-IEC29500-4_2016/shared-additionalCharacteristics.xsd", "content": "\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n\n" }, { "path": "src/copaw/agents/skills/pptx/scripts/office/schemas/ISO-IEC29500-4_2016/shared-bibliography.xsd", "content": "\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n\n" }, { "path": "src/copaw/agents/skills/pptx/scripts/office/schemas/ISO-IEC29500-4_2016/shared-commonSimpleTypes.xsd", "content": "\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n\n" }, { "path": "src/copaw/agents/skills/pptx/scripts/office/schemas/ISO-IEC29500-4_2016/shared-customXmlDataProperties.xsd", "content": "\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n\n" }, { "path": "src/copaw/agents/skills/pptx/scripts/office/schemas/ISO-IEC29500-4_2016/shared-customXmlSchemaProperties.xsd", "content": "\n\n \n \n \n \n \n \n \n \n \n \n \n \n\n" }, { "path": "src/copaw/agents/skills/pptx/scripts/office/schemas/ISO-IEC29500-4_2016/shared-documentPropertiesCustom.xsd", "content": "\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n\n" }, { "path": "src/copaw/agents/skills/pptx/scripts/office/schemas/ISO-IEC29500-4_2016/shared-documentPropertiesExtended.xsd", "content": "\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n\n" }, { "path": "src/copaw/agents/skills/pptx/scripts/office/schemas/ISO-IEC29500-4_2016/shared-documentPropertiesVariantTypes.xsd", "content": "\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n\n" }, { "path": "src/copaw/agents/skills/pptx/scripts/office/schemas/ISO-IEC29500-4_2016/shared-math.xsd", "content": "\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n\n" }, { "path": "src/copaw/agents/skills/pptx/scripts/office/schemas/ISO-IEC29500-4_2016/shared-relationshipReference.xsd", "content": "\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n\n" }, { "path": "src/copaw/agents/skills/pptx/scripts/office/schemas/ISO-IEC29500-4_2016/sml.xsd", "content": "\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n\n" }, { "path": "src/copaw/agents/skills/pptx/scripts/office/schemas/ISO-IEC29500-4_2016/vml-main.xsd", "content": "\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n\n" }, { "path": "src/copaw/agents/skills/pptx/scripts/office/schemas/ISO-IEC29500-4_2016/vml-officeDrawing.xsd", "content": "\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n\n" }, { "path": "src/copaw/agents/skills/pptx/scripts/office/schemas/ISO-IEC29500-4_2016/vml-presentationDrawing.xsd", "content": "\n\n \n \n \n \n \n \n\n" }, { "path": "src/copaw/agents/skills/pptx/scripts/office/schemas/ISO-IEC29500-4_2016/vml-spreadsheetDrawing.xsd", "content": "\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n\n" }, { "path": "src/copaw/agents/skills/pptx/scripts/office/schemas/ISO-IEC29500-4_2016/vml-wordprocessingDrawing.xsd", "content": "\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n\n" }, { "path": "src/copaw/agents/skills/pptx/scripts/office/schemas/ISO-IEC29500-4_2016/wml.xsd", "content": "\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n\n" }, { "path": "src/copaw/agents/skills/pptx/scripts/office/schemas/ISO-IEC29500-4_2016/xml.xsd", "content": "\n\n\n \n \n See http://www.w3.org/XML/1998/namespace.html and\n http://www.w3.org/TR/REC-xml for information about this namespace.\n\n This schema document describes the XML namespace, in a form\n suitable for import by other schema documents. \n\n Note that local names in this namespace are intended to be defined\n only by the World Wide Web Consortium or its subgroups. The\n following names are currently defined in this namespace and should\n not be used with conflicting semantics by any Working Group,\n specification, or document instance:\n\n base (as an attribute name): denotes an attribute whose value\n provides a URI to be used as the base for interpreting any\n relative URIs in the scope of the element on which it\n appears; its value is inherited. This name is reserved\n by virtue of its definition in the XML Base specification.\n\n lang (as an attribute name): denotes an attribute whose value\n is a language code for the natural language of the content of\n any element; its value is inherited. This name is reserved\n by virtue of its definition in the XML specification.\n \n space (as an attribute name): denotes an attribute whose\n value is a keyword indicating what whitespace processing\n discipline is intended for the content of the element; its\n value is inherited. This name is reserved by virtue of its\n definition in the XML specification.\n\n Father (in any context at all): denotes Jon Bosak, the chair of \n the original XML Working Group. This name is reserved by \n the following decision of the W3C XML Plenary and \n XML Coordination groups:\n\n In appreciation for his vision, leadership and dedication\n the W3C XML Plenary on this 10th day of February, 2000\n reserves for Jon Bosak in perpetuity the XML name\n xml:Father\n \n \n\n \n This schema defines attributes and an attribute group\n suitable for use by\n schemas wishing to allow xml:base, xml:lang or xml:space attributes\n on elements they define.\n\n To enable this, such a schema must import this schema\n for the XML namespace, e.g. as follows:\n <schema . . .>\n . . .\n <import namespace=\"http://www.w3.org/XML/1998/namespace\"\n schemaLocation=\"http://www.w3.org/2001/03/xml.xsd\"/>\n\n Subsequently, qualified reference to any of the attributes\n or the group defined below will have the desired effect, e.g.\n\n <type . . .>\n . . .\n <attributeGroup ref=\"xml:specialAttrs\"/>\n \n will define a type which will schema-validate an instance\n element with any of those attributes\n \n\n \n In keeping with the XML Schema WG's standard versioning\n policy, this schema document will persist at\n http://www.w3.org/2001/03/xml.xsd.\n At the date of issue it can also be found at\n http://www.w3.org/2001/xml.xsd.\n The schema document at that URI may however change in the future,\n in order to remain compatible with the latest version of XML Schema\n itself. In other words, if the XML Schema namespace changes, the version\n of this document at\n http://www.w3.org/2001/xml.xsd will change\n accordingly; the version at\n http://www.w3.org/2001/03/xml.xsd will not change.\n \n \n\n \n \n In due course, we should install the relevant ISO 2- and 3-letter\n codes as the enumerated possible values . . .\n \n \n\n \n \n \n \n \n \n \n \n\n \n \n See http://www.w3.org/TR/xmlbase/ for\n information about this attribute.\n \n \n\n \n \n \n \n \n\n\n" }, { "path": "src/copaw/agents/skills/pptx/scripts/office/schemas/ecma/fouth-edition/opc-contentTypes.xsd", "content": "\n\n\n \n \n \n\n \n \n \n \n \n \n\n \n \n \n \n\n \n \n \n \n\n \n \n \n \n \n\n \n \n \n \n \n\n" }, { "path": "src/copaw/agents/skills/pptx/scripts/office/schemas/ecma/fouth-edition/opc-coreProperties.xsd", "content": "\n\n\n \n \n \n\n \n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n\n \n \n \n \n \n \n\n \n \n \n \n \n \n \n\n\n" }, { "path": "src/copaw/agents/skills/pptx/scripts/office/schemas/ecma/fouth-edition/opc-digSig.xsd", "content": "\n\n\n \n \n \n\n \n \n \n \n \n \n\n \n \n \n \n \n \n \n\n \n \n \n \n \n \n \n\n \n \n \n \n \n\n \n \n \n \n \n\n" }, { "path": "src/copaw/agents/skills/pptx/scripts/office/schemas/ecma/fouth-edition/opc-relationships.xsd", "content": "\n\n\n \n \n\n \n \n \n \n \n\n \n \n \n \n \n \n \n \n \n \n\n \n \n \n \n \n \n\n" }, { "path": "src/copaw/agents/skills/pptx/scripts/office/schemas/mce/mc.xsd", "content": "\n\n\n \n\n \n \n\n \n\t\n\t\n\n\n\t\n\t\t\n\t\t\t\n\t\t\t\t\n\t\t\t\t\t\n\t\t\t\t\t\t\n\t\t\t\t\t\t\t\n\t\t\t\t\t\t\t\n\t\t\t\t\t\t\n\t\t\t\t\t\t\n\t\t\t\t\t\t\n\t\t\t\t\t\t\n\t\t\t\t\t\t\n\t\t\t\t\t\n\t\t\t\t\n\t\t\t\t\n\t\t\t\t\t\n\t\t\t\t\t\t\n\t\t\t\t\t\t\t\n\t\t\t\t\t\t\t\n\t\t\t\t\t\t\n\t\t\t\t\t\t\n\t\t\t\t\t\t\n\t\t\t\t\t\t\n\t\t\t\t\t\n\t\t\t\t\n\t\t\t\n\t\t\t\n\t\t\t\n\t\t\t\n\t\t\t\n\t\t\n\t\n\n" }, { "path": "src/copaw/agents/skills/pptx/scripts/office/schemas/microsoft/wml-2010.xsd", "content": " \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n" }, { "path": "src/copaw/agents/skills/pptx/scripts/office/schemas/microsoft/wml-2012.xsd", "content": " \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n" }, { "path": "src/copaw/agents/skills/pptx/scripts/office/schemas/microsoft/wml-2018.xsd", "content": " \n \n \n \n \n \n \n \n \n \n \n \n \n \n" }, { "path": "src/copaw/agents/skills/pptx/scripts/office/schemas/microsoft/wml-cex-2018.xsd", "content": " \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n" }, { "path": "src/copaw/agents/skills/pptx/scripts/office/schemas/microsoft/wml-cid-2016.xsd", "content": " \n \n \n \n \n \n \n \n \n \n \n \n \n" }, { "path": "src/copaw/agents/skills/pptx/scripts/office/schemas/microsoft/wml-sdtdatahash-2020.xsd", "content": " \n \n \n \n" }, { "path": "src/copaw/agents/skills/pptx/scripts/office/schemas/microsoft/wml-symex-2015.xsd", "content": " \n \n \n \n \n \n \n \n" }, { "path": "src/copaw/agents/skills/pptx/scripts/office/soffice.py", "content": "\"\"\"\nHelper for running LibreOffice (soffice) in environments where AF_UNIX\nsockets may be blocked (e.g., sandboxed VMs). Detects the restriction\nat runtime and applies an LD_PRELOAD shim if needed.\n\nUsage:\n from office.soffice import run_soffice, get_soffice_cmd, get_soffice_env\n\n # Option 1 – run soffice directly\n result = run_soffice([\"--headless\", \"--convert-to\", \"pdf\", \"input.docx\"])\n\n # Option 2 – get env dict for your own subprocess calls\n env = get_soffice_env()\n subprocess.run([get_soffice_cmd(), ...], env=env)\n\"\"\"\n\nimport os\nimport platform\nimport shutil\nimport socket\nimport subprocess\nimport tempfile\nfrom pathlib import Path\n\n\ndef get_soffice_cmd() -> str:\n \"\"\"Return the soffice command name for the current platform.\"\"\"\n # Prefer PATH first on all platforms.\n path_cmd = shutil.which(\"soffice\")\n if path_cmd:\n return path_cmd\n\n if platform.system() == \"Windows\":\n # Windows can expose soffice as .com or .exe; try both on PATH first.\n for candidate_name in (\"soffice.com\", \"soffice.exe\"):\n path_candidate = shutil.which(candidate_name)\n if path_candidate:\n return path_candidate\n\n for prog_dir in (\n os.environ.get(\"PROGRAMFILES\", r\"C:\\Program Files\"),\n os.environ.get(\"PROGRAMFILES(X86)\", r\"C:\\Program Files (x86)\"),\n ):\n if not prog_dir:\n continue\n program_dir = Path(prog_dir) / \"LibreOffice\" / \"program\"\n for exe_name in (\"soffice.com\", \"soffice.exe\"):\n candidate = program_dir / exe_name\n if candidate.exists():\n return str(candidate)\n return \"soffice\"\n return \"soffice\"\n\n\ndef get_soffice_env() -> dict:\n env = os.environ.copy()\n if platform.system() == \"Linux\":\n env[\"SAL_USE_VCLPLUGIN\"] = \"svp\"\n\n if _needs_shim():\n shim = _ensure_shim()\n env[\"LD_PRELOAD\"] = str(shim)\n\n return env\n\n\ndef run_soffice(args: list[str], **kwargs) -> subprocess.CompletedProcess:\n env = get_soffice_env()\n return subprocess.run([get_soffice_cmd()] + args, env=env, **kwargs)\n\n\n\n_SHIM_SO = Path(tempfile.gettempdir()) / \"lo_socket_shim.so\"\n\n\ndef _needs_shim() -> bool:\n # AF_UNIX / LD_PRELOAD shim is Linux-only; skip on Windows and macOS\n if not hasattr(socket, \"AF_UNIX\"):\n return False\n try:\n s = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)\n s.close()\n return False\n except OSError:\n return True\n\n\ndef _ensure_shim() -> Path:\n if _SHIM_SO.exists():\n return _SHIM_SO\n\n src = Path(tempfile.gettempdir()) / \"lo_socket_shim.c\"\n src.write_text(_SHIM_SOURCE)\n subprocess.run(\n [\"gcc\", \"-shared\", \"-fPIC\", \"-o\", str(_SHIM_SO), str(src), \"-ldl\"],\n check=True,\n capture_output=True,\n )\n src.unlink()\n return _SHIM_SO\n\n\n\n_SHIM_SOURCE = r\"\"\"\n#define _GNU_SOURCE\n#include \n#include \n#include \n#include \n#include \n#include \n#include \n\nstatic int (*real_socket)(int, int, int);\nstatic int (*real_socketpair)(int, int, int, int[2]);\nstatic int (*real_listen)(int, int);\nstatic int (*real_accept)(int, struct sockaddr *, socklen_t *);\nstatic int (*real_close)(int);\nstatic int (*real_read)(int, void *, size_t);\n\n/* Per-FD bookkeeping (FDs >= 1024 are passed through unshimmed). */\nstatic int is_shimmed[1024];\nstatic int peer_of[1024];\nstatic int wake_r[1024]; /* accept() blocks reading this */\nstatic int wake_w[1024]; /* close() writes to this */\nstatic int listener_fd = -1; /* FD that received listen() */\n\n__attribute__((constructor))\nstatic void init(void) {\n real_socket = dlsym(RTLD_NEXT, \"socket\");\n real_socketpair = dlsym(RTLD_NEXT, \"socketpair\");\n real_listen = dlsym(RTLD_NEXT, \"listen\");\n real_accept = dlsym(RTLD_NEXT, \"accept\");\n real_close = dlsym(RTLD_NEXT, \"close\");\n real_read = dlsym(RTLD_NEXT, \"read\");\n for (int i = 0; i < 1024; i++) {\n peer_of[i] = -1;\n wake_r[i] = -1;\n wake_w[i] = -1;\n }\n}\n\n/* ---- socket ---------------------------------------------------------- */\nint socket(int domain, int type, int protocol) {\n if (domain == AF_UNIX) {\n int fd = real_socket(domain, type, protocol);\n if (fd >= 0) return fd;\n /* socket(AF_UNIX) blocked – fall back to socketpair(). */\n int sv[2];\n if (real_socketpair(domain, type, protocol, sv) == 0) {\n if (sv[0] >= 0 && sv[0] < 1024) {\n is_shimmed[sv[0]] = 1;\n peer_of[sv[0]] = sv[1];\n int wp[2];\n if (pipe(wp) == 0) {\n wake_r[sv[0]] = wp[0];\n wake_w[sv[0]] = wp[1];\n }\n }\n return sv[0];\n }\n errno = EPERM;\n return -1;\n }\n return real_socket(domain, type, protocol);\n}\n\n/* ---- listen ---------------------------------------------------------- */\nint listen(int sockfd, int backlog) {\n if (sockfd >= 0 && sockfd < 1024 && is_shimmed[sockfd]) {\n listener_fd = sockfd;\n return 0;\n }\n return real_listen(sockfd, backlog);\n}\n\n/* ---- accept ---------------------------------------------------------- */\nint accept(int sockfd, struct sockaddr *addr, socklen_t *addrlen) {\n if (sockfd >= 0 && sockfd < 1024 && is_shimmed[sockfd]) {\n /* Block until close() writes to the wake pipe. */\n if (wake_r[sockfd] >= 0) {\n char buf;\n real_read(wake_r[sockfd], &buf, 1);\n }\n errno = ECONNABORTED;\n return -1;\n }\n return real_accept(sockfd, addr, addrlen);\n}\n\n/* ---- close ----------------------------------------------------------- */\nint close(int fd) {\n if (fd >= 0 && fd < 1024 && is_shimmed[fd]) {\n int was_listener = (fd == listener_fd);\n is_shimmed[fd] = 0;\n\n if (wake_w[fd] >= 0) { /* unblock accept() */\n char c = 0;\n write(wake_w[fd], &c, 1);\n real_close(wake_w[fd]);\n wake_w[fd] = -1;\n }\n if (wake_r[fd] >= 0) { real_close(wake_r[fd]); wake_r[fd] = -1; }\n if (peer_of[fd] >= 0) { real_close(peer_of[fd]); peer_of[fd] = -1; }\n\n if (was_listener)\n _exit(0); /* conversion done – exit */\n }\n return real_close(fd);\n}\n\"\"\"\n\n\n\nif __name__ == \"__main__\":\n import sys\n result = run_soffice(sys.argv[1:])\n sys.exit(result.returncode)\n" }, { "path": "src/copaw/agents/skills/pptx/scripts/office/unpack.py", "content": "\"\"\"Unpack Office files (DOCX, PPTX, XLSX) for editing.\n\nExtracts the ZIP archive, pretty-prints XML files, and optionally:\n- Merges adjacent runs with identical formatting (DOCX only)\n- Simplifies adjacent tracked changes from same author (DOCX only)\n\nUsage:\n python unpack.py [options]\n\nExamples:\n python unpack.py document.docx unpacked/\n python unpack.py presentation.pptx unpacked/\n python unpack.py document.docx unpacked/ --merge-runs false\n\"\"\"\n\nimport argparse\nimport sys\nimport zipfile\nfrom pathlib import Path\n\nimport defusedxml.minidom\n\nfrom helpers.merge_runs import merge_runs as do_merge_runs\nfrom helpers.simplify_redlines import simplify_redlines as do_simplify_redlines\n\nSMART_QUOTE_REPLACEMENTS = {\n \"\\u201c\": \"“\", \n \"\\u201d\": \"”\", \n \"\\u2018\": \"‘\", \n \"\\u2019\": \"’\", \n}\n\n\ndef unpack(\n input_file: str,\n output_directory: str,\n merge_runs: bool = True,\n simplify_redlines: bool = True,\n) -> tuple[None, str]:\n input_path = Path(input_file)\n output_path = Path(output_directory)\n suffix = input_path.suffix.lower()\n\n if not input_path.exists():\n return None, f\"Error: {input_file} does not exist\"\n\n if suffix not in {\".docx\", \".pptx\", \".xlsx\"}:\n return None, f\"Error: {input_file} must be a .docx, .pptx, or .xlsx file\"\n\n try:\n output_path.mkdir(parents=True, exist_ok=True)\n\n with zipfile.ZipFile(input_path, \"r\") as zf:\n zf.extractall(output_path)\n\n xml_files = list(output_path.rglob(\"*.xml\")) + list(output_path.rglob(\"*.rels\"))\n for xml_file in xml_files:\n _pretty_print_xml(xml_file)\n\n message = f\"Unpacked {input_file} ({len(xml_files)} XML files)\"\n\n if suffix == \".docx\":\n if simplify_redlines:\n simplify_count, _ = do_simplify_redlines(str(output_path))\n message += f\", simplified {simplify_count} tracked changes\"\n\n if merge_runs:\n merge_count, _ = do_merge_runs(str(output_path))\n message += f\", merged {merge_count} runs\"\n\n for xml_file in xml_files:\n _escape_smart_quotes(xml_file)\n\n return None, message\n\n except zipfile.BadZipFile:\n return None, f\"Error: {input_file} is not a valid Office file\"\n except Exception as e:\n return None, f\"Error unpacking: {e}\"\n\n\ndef _pretty_print_xml(xml_file: Path) -> None:\n try:\n content = xml_file.read_text(encoding=\"utf-8\")\n dom = defusedxml.minidom.parseString(content)\n xml_file.write_bytes(dom.toprettyxml(indent=\" \", encoding=\"utf-8\"))\n except Exception:\n pass \n\n\ndef _escape_smart_quotes(xml_file: Path) -> None:\n try:\n content = xml_file.read_text(encoding=\"utf-8\")\n for char, entity in SMART_QUOTE_REPLACEMENTS.items():\n content = content.replace(char, entity)\n xml_file.write_text(content, encoding=\"utf-8\")\n except Exception:\n pass\n\n\nif __name__ == \"__main__\":\n parser = argparse.ArgumentParser(\n description=\"Unpack an Office file (DOCX, PPTX, XLSX) for editing\"\n )\n parser.add_argument(\"input_file\", help=\"Office file to unpack\")\n parser.add_argument(\"output_directory\", help=\"Output directory\")\n parser.add_argument(\n \"--merge-runs\",\n type=lambda x: x.lower() == \"true\",\n default=True,\n metavar=\"true|false\",\n help=\"Merge adjacent runs with identical formatting (DOCX only, default: true)\",\n )\n parser.add_argument(\n \"--simplify-redlines\",\n type=lambda x: x.lower() == \"true\",\n default=True,\n metavar=\"true|false\",\n help=\"Merge adjacent tracked changes from same author (DOCX only, default: true)\",\n )\n args = parser.parse_args()\n\n _, message = unpack(\n args.input_file,\n args.output_directory,\n merge_runs=args.merge_runs,\n simplify_redlines=args.simplify_redlines,\n )\n print(message)\n\n if \"Error\" in message:\n sys.exit(1)\n" }, { "path": "src/copaw/agents/skills/pptx/scripts/office/validate.py", "content": "\"\"\"\nCommand line tool to validate Office document XML files against XSD schemas and tracked changes.\n\nUsage:\n python validate.py [--original ] [--auto-repair] [--author NAME]\n\nThe first argument can be either:\n- An unpacked directory containing the Office document XML files\n- A packed Office file (.docx/.pptx/.xlsx) which will be unpacked to a temp directory\n\nAuto-repair fixes:\n- paraId/durableId values that exceed OOXML limits\n- Missing xml:space=\"preserve\" on w:t elements with whitespace\n\"\"\"\n\nimport argparse\nimport sys\nimport tempfile\nimport zipfile\nfrom pathlib import Path\n\nfrom validators import DOCXSchemaValidator, PPTXSchemaValidator, RedliningValidator\n\n\ndef main():\n parser = argparse.ArgumentParser(description=\"Validate Office document XML files\")\n parser.add_argument(\n \"path\",\n help=\"Path to unpacked directory or packed Office file (.docx/.pptx/.xlsx)\",\n )\n parser.add_argument(\n \"--original\",\n required=False,\n default=None,\n help=\"Path to original file (.docx/.pptx/.xlsx). If omitted, all XSD errors are reported and redlining validation is skipped.\",\n )\n parser.add_argument(\n \"-v\",\n \"--verbose\",\n action=\"store_true\",\n help=\"Enable verbose output\",\n )\n parser.add_argument(\n \"--auto-repair\",\n action=\"store_true\",\n help=\"Automatically repair common issues (hex IDs, whitespace preservation)\",\n )\n parser.add_argument(\n \"--author\",\n default=\"Claude\",\n help=\"Author name for redlining validation (default: Claude)\",\n )\n args = parser.parse_args()\n\n path = Path(args.path)\n assert path.exists(), f\"Error: {path} does not exist\"\n\n original_file = None\n if args.original:\n original_file = Path(args.original)\n assert original_file.is_file(), f\"Error: {original_file} is not a file\"\n assert original_file.suffix.lower() in [\".docx\", \".pptx\", \".xlsx\"], (\n f\"Error: {original_file} must be a .docx, .pptx, or .xlsx file\"\n )\n\n file_extension = (original_file or path).suffix.lower()\n assert file_extension in [\".docx\", \".pptx\", \".xlsx\"], (\n f\"Error: Cannot determine file type from {path}. Use --original or provide a .docx/.pptx/.xlsx file.\"\n )\n\n if path.is_file() and path.suffix.lower() in [\".docx\", \".pptx\", \".xlsx\"]:\n temp_dir = tempfile.mkdtemp()\n with zipfile.ZipFile(path, \"r\") as zf:\n zf.extractall(temp_dir)\n unpacked_dir = Path(temp_dir)\n else:\n assert path.is_dir(), f\"Error: {path} is not a directory or Office file\"\n unpacked_dir = path\n\n match file_extension:\n case \".docx\":\n validators = [\n DOCXSchemaValidator(unpacked_dir, original_file, verbose=args.verbose),\n ]\n if original_file:\n validators.append(\n RedliningValidator(unpacked_dir, original_file, verbose=args.verbose, author=args.author) \n )\n case \".pptx\":\n validators = [\n PPTXSchemaValidator(unpacked_dir, original_file, verbose=args.verbose),\n ]\n case _:\n print(f\"Error: Validation not supported for file type {file_extension}\")\n sys.exit(1)\n\n if args.auto_repair:\n total_repairs = sum(v.repair() for v in validators)\n if total_repairs:\n print(f\"Auto-repaired {total_repairs} issue(s)\")\n\n success = all(v.validate() for v in validators)\n\n if success:\n print(\"All validations PASSED!\")\n\n sys.exit(0 if success else 1)\n\n\nif __name__ == \"__main__\":\n main()\n" }, { "path": "src/copaw/agents/skills/pptx/scripts/office/validators/__init__.py", "content": "\"\"\"\nValidation modules for Word document processing.\n\"\"\"\n\nfrom .base import BaseSchemaValidator\nfrom .docx import DOCXSchemaValidator\nfrom .pptx import PPTXSchemaValidator\nfrom .redlining import RedliningValidator\n\n__all__ = [\n \"BaseSchemaValidator\",\n \"DOCXSchemaValidator\",\n \"PPTXSchemaValidator\",\n \"RedliningValidator\",\n]\n" }, { "path": "src/copaw/agents/skills/pptx/scripts/office/validators/base.py", "content": "\"\"\"\nBase validator with common validation logic for document files.\n\"\"\"\n\nimport re\nfrom pathlib import Path\n\nimport defusedxml.minidom\nimport lxml.etree\n\n\nclass BaseSchemaValidator:\n\n IGNORED_VALIDATION_ERRORS = [\n \"hyphenationZone\",\n \"purl.org/dc/terms\",\n ]\n\n UNIQUE_ID_REQUIREMENTS = {\n \"comment\": (\"id\", \"file\"), \n \"commentrangestart\": (\"id\", \"file\"), \n \"commentrangeend\": (\"id\", \"file\"), \n \"bookmarkstart\": (\"id\", \"file\"), \n \"bookmarkend\": (\"id\", \"file\"), \n \"sldid\": (\"id\", \"file\"), \n \"sldmasterid\": (\"id\", \"global\"), \n \"sldlayoutid\": (\"id\", \"global\"), \n \"cm\": (\"authorid\", \"file\"), \n \"sheet\": (\"sheetid\", \"file\"), \n \"definedname\": (\"id\", \"file\"), \n \"cxnsp\": (\"id\", \"file\"), \n \"sp\": (\"id\", \"file\"), \n \"pic\": (\"id\", \"file\"), \n \"grpsp\": (\"id\", \"file\"), \n }\n\n EXCLUDED_ID_CONTAINERS = {\n \"sectionlst\", \n }\n\n ELEMENT_RELATIONSHIP_TYPES = {}\n\n SCHEMA_MAPPINGS = {\n \"word\": \"ISO-IEC29500-4_2016/wml.xsd\", \n \"ppt\": \"ISO-IEC29500-4_2016/pml.xsd\", \n \"xl\": \"ISO-IEC29500-4_2016/sml.xsd\", \n \"[Content_Types].xml\": \"ecma/fouth-edition/opc-contentTypes.xsd\",\n \"app.xml\": \"ISO-IEC29500-4_2016/shared-documentPropertiesExtended.xsd\",\n \"core.xml\": \"ecma/fouth-edition/opc-coreProperties.xsd\",\n \"custom.xml\": \"ISO-IEC29500-4_2016/shared-documentPropertiesCustom.xsd\",\n \".rels\": \"ecma/fouth-edition/opc-relationships.xsd\",\n \"people.xml\": \"microsoft/wml-2012.xsd\",\n \"commentsIds.xml\": \"microsoft/wml-cid-2016.xsd\",\n \"commentsExtensible.xml\": \"microsoft/wml-cex-2018.xsd\",\n \"commentsExtended.xml\": \"microsoft/wml-2012.xsd\",\n \"chart\": \"ISO-IEC29500-4_2016/dml-chart.xsd\",\n \"theme\": \"ISO-IEC29500-4_2016/dml-main.xsd\",\n \"drawing\": \"ISO-IEC29500-4_2016/dml-main.xsd\",\n }\n\n MC_NAMESPACE = \"http://schemas.openxmlformats.org/markup-compatibility/2006\"\n XML_NAMESPACE = \"http://www.w3.org/XML/1998/namespace\"\n\n PACKAGE_RELATIONSHIPS_NAMESPACE = (\n \"http://schemas.openxmlformats.org/package/2006/relationships\"\n )\n OFFICE_RELATIONSHIPS_NAMESPACE = (\n \"http://schemas.openxmlformats.org/officeDocument/2006/relationships\"\n )\n CONTENT_TYPES_NAMESPACE = (\n \"http://schemas.openxmlformats.org/package/2006/content-types\"\n )\n\n MAIN_CONTENT_FOLDERS = {\"word\", \"ppt\", \"xl\"}\n\n OOXML_NAMESPACES = {\n \"http://schemas.openxmlformats.org/officeDocument/2006/math\",\n \"http://schemas.openxmlformats.org/officeDocument/2006/relationships\",\n \"http://schemas.openxmlformats.org/schemaLibrary/2006/main\",\n \"http://schemas.openxmlformats.org/drawingml/2006/main\",\n \"http://schemas.openxmlformats.org/drawingml/2006/chart\",\n \"http://schemas.openxmlformats.org/drawingml/2006/chartDrawing\",\n \"http://schemas.openxmlformats.org/drawingml/2006/diagram\",\n \"http://schemas.openxmlformats.org/drawingml/2006/picture\",\n \"http://schemas.openxmlformats.org/drawingml/2006/spreadsheetDrawing\",\n \"http://schemas.openxmlformats.org/drawingml/2006/wordprocessingDrawing\",\n \"http://schemas.openxmlformats.org/wordprocessingml/2006/main\",\n \"http://schemas.openxmlformats.org/presentationml/2006/main\",\n \"http://schemas.openxmlformats.org/spreadsheetml/2006/main\",\n \"http://schemas.openxmlformats.org/officeDocument/2006/sharedTypes\",\n \"http://www.w3.org/XML/1998/namespace\",\n }\n\n def __init__(self, unpacked_dir, original_file=None, verbose=False):\n self.unpacked_dir = Path(unpacked_dir).resolve()\n self.original_file = Path(original_file) if original_file else None\n self.verbose = verbose\n\n self.schemas_dir = Path(__file__).parent.parent / \"schemas\"\n\n patterns = [\"*.xml\", \"*.rels\"]\n self.xml_files = [\n f for pattern in patterns for f in self.unpacked_dir.rglob(pattern)\n ]\n\n if not self.xml_files:\n print(f\"Warning: No XML files found in {self.unpacked_dir}\")\n\n def validate(self):\n raise NotImplementedError(\"Subclasses must implement the validate method\")\n\n def repair(self) -> int:\n return self.repair_whitespace_preservation()\n\n def repair_whitespace_preservation(self) -> int:\n repairs = 0\n\n for xml_file in self.xml_files:\n try:\n content = xml_file.read_text(encoding=\"utf-8\")\n dom = defusedxml.minidom.parseString(content)\n modified = False\n\n for elem in dom.getElementsByTagName(\"*\"):\n if elem.tagName.endswith(\":t\") and elem.firstChild:\n text = elem.firstChild.nodeValue\n if text and (text.startswith((' ', '\\t')) or text.endswith((' ', '\\t'))):\n if elem.getAttribute(\"xml:space\") != \"preserve\":\n elem.setAttribute(\"xml:space\", \"preserve\")\n text_preview = repr(text[:30]) + \"...\" if len(text) > 30 else repr(text)\n print(f\" Repaired: {xml_file.name}: Added xml:space='preserve' to {elem.tagName}: {text_preview}\")\n repairs += 1\n modified = True\n\n if modified:\n xml_file.write_bytes(dom.toxml(encoding=\"UTF-8\"))\n\n except Exception:\n pass\n\n return repairs\n\n def validate_xml(self):\n errors = []\n\n for xml_file in self.xml_files:\n try:\n lxml.etree.parse(str(xml_file))\n except lxml.etree.XMLSyntaxError as e:\n errors.append(\n f\" {xml_file.relative_to(self.unpacked_dir)}: \"\n f\"Line {e.lineno}: {e.msg}\"\n )\n except Exception as e:\n errors.append(\n f\" {xml_file.relative_to(self.unpacked_dir)}: \"\n f\"Unexpected error: {str(e)}\"\n )\n\n if errors:\n print(f\"FAILED - Found {len(errors)} XML violations:\")\n for error in errors:\n print(error)\n return False\n else:\n if self.verbose:\n print(\"PASSED - All XML files are well-formed\")\n return True\n\n def validate_namespaces(self):\n errors = []\n\n for xml_file in self.xml_files:\n try:\n root = lxml.etree.parse(str(xml_file)).getroot()\n declared = set(root.nsmap.keys()) - {None} \n\n for attr_val in [\n v for k, v in root.attrib.items() if k.endswith(\"Ignorable\")\n ]:\n undeclared = set(attr_val.split()) - declared\n errors.extend(\n f\" {xml_file.relative_to(self.unpacked_dir)}: \"\n f\"Namespace '{ns}' in Ignorable but not declared\"\n for ns in undeclared\n )\n except lxml.etree.XMLSyntaxError:\n continue\n\n if errors:\n print(f\"FAILED - {len(errors)} namespace issues:\")\n for error in errors:\n print(error)\n return False\n if self.verbose:\n print(\"PASSED - All namespace prefixes properly declared\")\n return True\n\n def validate_unique_ids(self):\n errors = []\n global_ids = {} \n\n for xml_file in self.xml_files:\n try:\n root = lxml.etree.parse(str(xml_file)).getroot()\n file_ids = {} \n\n mc_elements = root.xpath(\n \".//mc:AlternateContent\", namespaces={\"mc\": self.MC_NAMESPACE}\n )\n for elem in mc_elements:\n elem.getparent().remove(elem)\n\n for elem in root.iter():\n tag = (\n elem.tag.split(\"}\")[-1].lower()\n if \"}\" in elem.tag\n else elem.tag.lower()\n )\n\n if tag in self.UNIQUE_ID_REQUIREMENTS:\n in_excluded_container = any(\n ancestor.tag.split(\"}\")[-1].lower() in self.EXCLUDED_ID_CONTAINERS\n for ancestor in elem.iterancestors()\n )\n if in_excluded_container:\n continue\n\n attr_name, scope = self.UNIQUE_ID_REQUIREMENTS[tag]\n\n id_value = None\n for attr, value in elem.attrib.items():\n attr_local = (\n attr.split(\"}\")[-1].lower()\n if \"}\" in attr\n else attr.lower()\n )\n if attr_local == attr_name:\n id_value = value\n break\n\n if id_value is not None:\n if scope == \"global\":\n if id_value in global_ids:\n prev_file, prev_line, prev_tag = global_ids[\n id_value\n ]\n errors.append(\n f\" {xml_file.relative_to(self.unpacked_dir)}: \"\n f\"Line {elem.sourceline}: Global ID '{id_value}' in <{tag}> \"\n f\"already used in {prev_file} at line {prev_line} in <{prev_tag}>\"\n )\n else:\n global_ids[id_value] = (\n xml_file.relative_to(self.unpacked_dir),\n elem.sourceline,\n tag,\n )\n elif scope == \"file\":\n key = (tag, attr_name)\n if key not in file_ids:\n file_ids[key] = {}\n\n if id_value in file_ids[key]:\n prev_line = file_ids[key][id_value]\n errors.append(\n f\" {xml_file.relative_to(self.unpacked_dir)}: \"\n f\"Line {elem.sourceline}: Duplicate {attr_name}='{id_value}' in <{tag}> \"\n f\"(first occurrence at line {prev_line})\"\n )\n else:\n file_ids[key][id_value] = elem.sourceline\n\n except (lxml.etree.XMLSyntaxError, Exception) as e:\n errors.append(\n f\" {xml_file.relative_to(self.unpacked_dir)}: Error: {e}\"\n )\n\n if errors:\n print(f\"FAILED - Found {len(errors)} ID uniqueness violations:\")\n for error in errors:\n print(error)\n return False\n else:\n if self.verbose:\n print(\"PASSED - All required IDs are unique\")\n return True\n\n def validate_file_references(self):\n errors = []\n\n rels_files = list(self.unpacked_dir.rglob(\"*.rels\"))\n\n if not rels_files:\n if self.verbose:\n print(\"PASSED - No .rels files found\")\n return True\n\n all_files = []\n for file_path in self.unpacked_dir.rglob(\"*\"):\n if (\n file_path.is_file()\n and file_path.name != \"[Content_Types].xml\"\n and not file_path.name.endswith(\".rels\")\n ): \n all_files.append(file_path.resolve())\n\n all_referenced_files = set()\n\n if self.verbose:\n print(\n f\"Found {len(rels_files)} .rels files and {len(all_files)} target files\"\n )\n\n for rels_file in rels_files:\n try:\n rels_root = lxml.etree.parse(str(rels_file)).getroot()\n\n rels_dir = rels_file.parent\n\n referenced_files = set()\n broken_refs = []\n\n for rel in rels_root.findall(\n \".//ns:Relationship\",\n namespaces={\"ns\": self.PACKAGE_RELATIONSHIPS_NAMESPACE},\n ):\n target = rel.get(\"Target\")\n if target and not target.startswith(\n (\"http\", \"mailto:\")\n ): \n if target.startswith(\"/\"):\n target_path = self.unpacked_dir / target.lstrip(\"/\")\n elif rels_file.name == \".rels\":\n target_path = self.unpacked_dir / target\n else:\n base_dir = rels_dir.parent\n target_path = base_dir / target\n\n try:\n target_path = target_path.resolve()\n if target_path.exists() and target_path.is_file():\n referenced_files.add(target_path)\n all_referenced_files.add(target_path)\n else:\n broken_refs.append((target, rel.sourceline))\n except (OSError, ValueError):\n broken_refs.append((target, rel.sourceline))\n\n if broken_refs:\n rel_path = rels_file.relative_to(self.unpacked_dir)\n for broken_ref, line_num in broken_refs:\n errors.append(\n f\" {rel_path}: Line {line_num}: Broken reference to {broken_ref}\"\n )\n\n except Exception as e:\n rel_path = rels_file.relative_to(self.unpacked_dir)\n errors.append(f\" Error parsing {rel_path}: {e}\")\n\n unreferenced_files = set(all_files) - all_referenced_files\n\n if unreferenced_files:\n for unref_file in sorted(unreferenced_files):\n unref_rel_path = unref_file.relative_to(self.unpacked_dir)\n errors.append(f\" Unreferenced file: {unref_rel_path}\")\n\n if errors:\n print(f\"FAILED - Found {len(errors)} relationship validation errors:\")\n for error in errors:\n print(error)\n print(\n \"CRITICAL: These errors will cause the document to appear corrupt. \"\n + \"Broken references MUST be fixed, \"\n + \"and unreferenced files MUST be referenced or removed.\"\n )\n return False\n else:\n if self.verbose:\n print(\n \"PASSED - All references are valid and all files are properly referenced\"\n )\n return True\n\n def validate_all_relationship_ids(self):\n import lxml.etree\n\n errors = []\n\n for xml_file in self.xml_files:\n if xml_file.suffix == \".rels\":\n continue\n\n rels_dir = xml_file.parent / \"_rels\"\n rels_file = rels_dir / f\"{xml_file.name}.rels\"\n\n if not rels_file.exists():\n continue\n\n try:\n rels_root = lxml.etree.parse(str(rels_file)).getroot()\n rid_to_type = {}\n\n for rel in rels_root.findall(\n f\".//{{{self.PACKAGE_RELATIONSHIPS_NAMESPACE}}}Relationship\"\n ):\n rid = rel.get(\"Id\")\n rel_type = rel.get(\"Type\", \"\")\n if rid:\n if rid in rid_to_type:\n rels_rel_path = rels_file.relative_to(self.unpacked_dir)\n errors.append(\n f\" {rels_rel_path}: Line {rel.sourceline}: \"\n f\"Duplicate relationship ID '{rid}' (IDs must be unique)\"\n )\n type_name = (\n rel_type.split(\"/\")[-1] if \"/\" in rel_type else rel_type\n )\n rid_to_type[rid] = type_name\n\n xml_root = lxml.etree.parse(str(xml_file)).getroot()\n\n r_ns = self.OFFICE_RELATIONSHIPS_NAMESPACE\n rid_attrs_to_check = [\"id\", \"embed\", \"link\"]\n for elem in xml_root.iter():\n for attr_name in rid_attrs_to_check:\n rid_attr = elem.get(f\"{{{r_ns}}}{attr_name}\")\n if not rid_attr:\n continue\n xml_rel_path = xml_file.relative_to(self.unpacked_dir)\n elem_name = (\n elem.tag.split(\"}\")[-1] if \"}\" in elem.tag else elem.tag\n )\n\n if rid_attr not in rid_to_type:\n errors.append(\n f\" {xml_rel_path}: Line {elem.sourceline}: \"\n f\"<{elem_name}> r:{attr_name} references non-existent relationship '{rid_attr}' \"\n f\"(valid IDs: {', '.join(sorted(rid_to_type.keys())[:5])}{'...' if len(rid_to_type) > 5 else ''})\"\n )\n elif attr_name == \"id\" and self.ELEMENT_RELATIONSHIP_TYPES:\n expected_type = self._get_expected_relationship_type(\n elem_name\n )\n if expected_type:\n actual_type = rid_to_type[rid_attr]\n if expected_type not in actual_type.lower():\n errors.append(\n f\" {xml_rel_path}: Line {elem.sourceline}: \"\n f\"<{elem_name}> references '{rid_attr}' which points to '{actual_type}' \"\n f\"but should point to a '{expected_type}' relationship\"\n )\n\n except Exception as e:\n xml_rel_path = xml_file.relative_to(self.unpacked_dir)\n errors.append(f\" Error processing {xml_rel_path}: {e}\")\n\n if errors:\n print(f\"FAILED - Found {len(errors)} relationship ID reference errors:\")\n for error in errors:\n print(error)\n print(\"\\nThese ID mismatches will cause the document to appear corrupt!\")\n return False\n else:\n if self.verbose:\n print(\"PASSED - All relationship ID references are valid\")\n return True\n\n def _get_expected_relationship_type(self, element_name):\n elem_lower = element_name.lower()\n\n if elem_lower in self.ELEMENT_RELATIONSHIP_TYPES:\n return self.ELEMENT_RELATIONSHIP_TYPES[elem_lower]\n\n if elem_lower.endswith(\"id\") and len(elem_lower) > 2:\n prefix = elem_lower[:-2] \n if prefix.endswith(\"master\"):\n return prefix.lower()\n elif prefix.endswith(\"layout\"):\n return prefix.lower()\n else:\n if prefix == \"sld\":\n return \"slide\"\n return prefix.lower()\n\n if elem_lower.endswith(\"reference\") and len(elem_lower) > 9:\n prefix = elem_lower[:-9] \n return prefix.lower()\n\n return None\n\n def validate_content_types(self):\n errors = []\n\n content_types_file = self.unpacked_dir / \"[Content_Types].xml\"\n if not content_types_file.exists():\n print(\"FAILED - [Content_Types].xml file not found\")\n return False\n\n try:\n root = lxml.etree.parse(str(content_types_file)).getroot()\n declared_parts = set()\n declared_extensions = set()\n\n for override in root.findall(\n f\".//{{{self.CONTENT_TYPES_NAMESPACE}}}Override\"\n ):\n part_name = override.get(\"PartName\")\n if part_name is not None:\n declared_parts.add(part_name.lstrip(\"/\"))\n\n for default in root.findall(\n f\".//{{{self.CONTENT_TYPES_NAMESPACE}}}Default\"\n ):\n extension = default.get(\"Extension\")\n if extension is not None:\n declared_extensions.add(extension.lower())\n\n declarable_roots = {\n \"sld\",\n \"sldLayout\",\n \"sldMaster\",\n \"presentation\", \n \"document\", \n \"workbook\",\n \"worksheet\", \n \"theme\", \n }\n\n media_extensions = {\n \"png\": \"image/png\",\n \"jpg\": \"image/jpeg\",\n \"jpeg\": \"image/jpeg\",\n \"gif\": \"image/gif\",\n \"bmp\": \"image/bmp\",\n \"tiff\": \"image/tiff\",\n \"wmf\": \"image/x-wmf\",\n \"emf\": \"image/x-emf\",\n }\n\n all_files = list(self.unpacked_dir.rglob(\"*\"))\n all_files = [f for f in all_files if f.is_file()]\n\n for xml_file in self.xml_files:\n path_str = str(xml_file.relative_to(self.unpacked_dir)).replace(\n \"\\\\\", \"/\"\n )\n\n if any(\n skip in path_str\n for skip in [\".rels\", \"[Content_Types]\", \"docProps/\", \"_rels/\"]\n ):\n continue\n\n try:\n root_tag = lxml.etree.parse(str(xml_file)).getroot().tag\n root_name = root_tag.split(\"}\")[-1] if \"}\" in root_tag else root_tag\n\n if root_name in declarable_roots and path_str not in declared_parts:\n errors.append(\n f\" {path_str}: File with <{root_name}> root not declared in [Content_Types].xml\"\n )\n\n except Exception:\n continue \n\n for file_path in all_files:\n if file_path.suffix.lower() in {\".xml\", \".rels\"}:\n continue\n if file_path.name == \"[Content_Types].xml\":\n continue\n if \"_rels\" in file_path.parts or \"docProps\" in file_path.parts:\n continue\n\n extension = file_path.suffix.lstrip(\".\").lower()\n if extension and extension not in declared_extensions:\n if extension in media_extensions:\n relative_path = file_path.relative_to(self.unpacked_dir)\n errors.append(\n f' {relative_path}: File with extension \\'{extension}\\' not declared in [Content_Types].xml - should add: '\n )\n\n except Exception as e:\n errors.append(f\" Error parsing [Content_Types].xml: {e}\")\n\n if errors:\n print(f\"FAILED - Found {len(errors)} content type declaration errors:\")\n for error in errors:\n print(error)\n return False\n else:\n if self.verbose:\n print(\n \"PASSED - All content files are properly declared in [Content_Types].xml\"\n )\n return True\n\n def validate_file_against_xsd(self, xml_file, verbose=False):\n xml_file = Path(xml_file).resolve()\n unpacked_dir = self.unpacked_dir.resolve()\n\n is_valid, current_errors = self._validate_single_file_xsd(\n xml_file, unpacked_dir\n )\n\n if is_valid is None:\n return None, set() \n elif is_valid:\n return True, set() \n\n original_errors = self._get_original_file_errors(xml_file)\n\n assert current_errors is not None\n new_errors = current_errors - original_errors\n\n new_errors = {\n e for e in new_errors\n if not any(pattern in e for pattern in self.IGNORED_VALIDATION_ERRORS)\n }\n\n if new_errors:\n if verbose:\n relative_path = xml_file.relative_to(unpacked_dir)\n print(f\"FAILED - {relative_path}: {len(new_errors)} new error(s)\")\n for error in list(new_errors)[:3]:\n truncated = error[:250] + \"...\" if len(error) > 250 else error\n print(f\" - {truncated}\")\n return False, new_errors\n else:\n if verbose:\n print(\n f\"PASSED - No new errors (original had {len(current_errors)} errors)\"\n )\n return True, set()\n\n def validate_against_xsd(self):\n new_errors = []\n original_error_count = 0\n valid_count = 0\n skipped_count = 0\n\n for xml_file in self.xml_files:\n relative_path = str(xml_file.relative_to(self.unpacked_dir))\n is_valid, new_file_errors = self.validate_file_against_xsd(\n xml_file, verbose=False\n )\n\n if is_valid is None:\n skipped_count += 1\n continue\n elif is_valid and not new_file_errors:\n valid_count += 1\n continue\n elif is_valid:\n original_error_count += 1\n valid_count += 1\n continue\n\n new_errors.append(f\" {relative_path}: {len(new_file_errors)} new error(s)\")\n for error in list(new_file_errors)[:3]: \n new_errors.append(\n f\" - {error[:250]}...\" if len(error) > 250 else f\" - {error}\"\n )\n\n if self.verbose:\n print(f\"Validated {len(self.xml_files)} files:\")\n print(f\" - Valid: {valid_count}\")\n print(f\" - Skipped (no schema): {skipped_count}\")\n if original_error_count:\n print(f\" - With original errors (ignored): {original_error_count}\")\n print(\n f\" - With NEW errors: {len(new_errors) > 0 and len([e for e in new_errors if not e.startswith(' ')]) or 0}\"\n )\n\n if new_errors:\n print(\"\\nFAILED - Found NEW validation errors:\")\n for error in new_errors:\n print(error)\n return False\n else:\n if self.verbose:\n print(\"\\nPASSED - No new XSD validation errors introduced\")\n return True\n\n def _get_schema_path(self, xml_file):\n if xml_file.name in self.SCHEMA_MAPPINGS:\n return self.schemas_dir / self.SCHEMA_MAPPINGS[xml_file.name]\n\n if xml_file.suffix == \".rels\":\n return self.schemas_dir / self.SCHEMA_MAPPINGS[\".rels\"]\n\n if \"charts/\" in str(xml_file) and xml_file.name.startswith(\"chart\"):\n return self.schemas_dir / self.SCHEMA_MAPPINGS[\"chart\"]\n\n if \"theme/\" in str(xml_file) and xml_file.name.startswith(\"theme\"):\n return self.schemas_dir / self.SCHEMA_MAPPINGS[\"theme\"]\n\n if xml_file.parent.name in self.MAIN_CONTENT_FOLDERS:\n return self.schemas_dir / self.SCHEMA_MAPPINGS[xml_file.parent.name]\n\n return None\n\n def _clean_ignorable_namespaces(self, xml_doc):\n xml_string = lxml.etree.tostring(xml_doc, encoding=\"unicode\")\n xml_copy = lxml.etree.fromstring(xml_string)\n\n for elem in xml_copy.iter():\n attrs_to_remove = []\n\n for attr in elem.attrib:\n if \"{\" in attr:\n ns = attr.split(\"}\")[0][1:]\n if ns not in self.OOXML_NAMESPACES:\n attrs_to_remove.append(attr)\n\n for attr in attrs_to_remove:\n del elem.attrib[attr]\n\n self._remove_ignorable_elements(xml_copy)\n\n return lxml.etree.ElementTree(xml_copy)\n\n def _remove_ignorable_elements(self, root):\n elements_to_remove = []\n\n for elem in list(root):\n if not hasattr(elem, \"tag\") or callable(elem.tag):\n continue\n\n tag_str = str(elem.tag)\n if tag_str.startswith(\"{\"):\n ns = tag_str.split(\"}\")[0][1:]\n if ns not in self.OOXML_NAMESPACES:\n elements_to_remove.append(elem)\n continue\n\n self._remove_ignorable_elements(elem)\n\n for elem in elements_to_remove:\n root.remove(elem)\n\n def _preprocess_for_mc_ignorable(self, xml_doc):\n root = xml_doc.getroot()\n\n if f\"{{{self.MC_NAMESPACE}}}Ignorable\" in root.attrib:\n del root.attrib[f\"{{{self.MC_NAMESPACE}}}Ignorable\"]\n\n return xml_doc\n\n def _validate_single_file_xsd(self, xml_file, base_path):\n schema_path = self._get_schema_path(xml_file)\n if not schema_path:\n return None, None \n\n try:\n with open(schema_path, \"rb\") as xsd_file:\n parser = lxml.etree.XMLParser()\n xsd_doc = lxml.etree.parse(\n xsd_file, parser=parser, base_url=str(schema_path)\n )\n schema = lxml.etree.XMLSchema(xsd_doc)\n\n with open(xml_file, \"r\") as f:\n xml_doc = lxml.etree.parse(f)\n\n xml_doc, _ = self._remove_template_tags_from_text_nodes(xml_doc)\n xml_doc = self._preprocess_for_mc_ignorable(xml_doc)\n\n relative_path = xml_file.relative_to(base_path)\n if (\n relative_path.parts\n and relative_path.parts[0] in self.MAIN_CONTENT_FOLDERS\n ):\n xml_doc = self._clean_ignorable_namespaces(xml_doc)\n\n if schema.validate(xml_doc):\n return True, set()\n else:\n errors = set()\n for error in schema.error_log:\n errors.add(error.message)\n return False, errors\n\n except Exception as e:\n return False, {str(e)}\n\n def _get_original_file_errors(self, xml_file):\n if self.original_file is None:\n return set()\n\n import tempfile\n import zipfile\n\n xml_file = Path(xml_file).resolve()\n unpacked_dir = self.unpacked_dir.resolve()\n relative_path = xml_file.relative_to(unpacked_dir)\n\n with tempfile.TemporaryDirectory() as temp_dir:\n temp_path = Path(temp_dir)\n\n with zipfile.ZipFile(self.original_file, \"r\") as zip_ref:\n zip_ref.extractall(temp_path)\n\n original_xml_file = temp_path / relative_path\n\n if not original_xml_file.exists():\n return set()\n\n is_valid, errors = self._validate_single_file_xsd(\n original_xml_file, temp_path\n )\n return errors if errors else set()\n\n def _remove_template_tags_from_text_nodes(self, xml_doc):\n warnings = []\n template_pattern = re.compile(r\"\\{\\{[^}]*\\}\\}\")\n\n xml_string = lxml.etree.tostring(xml_doc, encoding=\"unicode\")\n xml_copy = lxml.etree.fromstring(xml_string)\n\n def process_text_content(text, content_type):\n if not text:\n return text\n matches = list(template_pattern.finditer(text))\n if matches:\n for match in matches:\n warnings.append(\n f\"Found template tag in {content_type}: {match.group()}\"\n )\n return template_pattern.sub(\"\", text)\n return text\n\n for elem in xml_copy.iter():\n if not hasattr(elem, \"tag\") or callable(elem.tag):\n continue\n tag_str = str(elem.tag)\n if tag_str.endswith(\"}t\") or tag_str == \"t\":\n continue\n\n elem.text = process_text_content(elem.text, \"text content\")\n elem.tail = process_text_content(elem.tail, \"tail content\")\n\n return lxml.etree.ElementTree(xml_copy), warnings\n\n\nif __name__ == \"__main__\":\n raise RuntimeError(\"This module should not be run directly.\")\n" }, { "path": "src/copaw/agents/skills/pptx/scripts/office/validators/docx.py", "content": "\"\"\"\nValidator for Word document XML files against XSD schemas.\n\"\"\"\n\nimport os\nimport random\nimport re\nimport tempfile\nimport zipfile\n\nimport defusedxml.minidom\nimport lxml.etree\n\nfrom .base import BaseSchemaValidator\n\n\nclass DOCXSchemaValidator(BaseSchemaValidator):\n\n WORD_2006_NAMESPACE = \"http://schemas.openxmlformats.org/wordprocessingml/2006/main\"\n W14_NAMESPACE = \"http://schemas.microsoft.com/office/word/2010/wordml\"\n W16CID_NAMESPACE = \"http://schemas.microsoft.com/office/word/2016/wordml/cid\"\n\n ELEMENT_RELATIONSHIP_TYPES = {}\n\n def validate(self):\n if not self.validate_xml():\n return False\n\n all_valid = True\n if not self.validate_namespaces():\n all_valid = False\n\n if not self.validate_unique_ids():\n all_valid = False\n\n if not self.validate_file_references():\n all_valid = False\n\n if not self.validate_content_types():\n all_valid = False\n\n if not self.validate_against_xsd():\n all_valid = False\n\n if not self.validate_whitespace_preservation():\n all_valid = False\n\n if not self.validate_deletions():\n all_valid = False\n\n if not self.validate_insertions():\n all_valid = False\n\n if not self.validate_all_relationship_ids():\n all_valid = False\n\n if not self.validate_id_constraints():\n all_valid = False\n\n if not self.validate_comment_markers():\n all_valid = False\n\n self.compare_paragraph_counts()\n\n return all_valid\n\n def validate_whitespace_preservation(self):\n errors = []\n\n for xml_file in self.xml_files:\n if xml_file.name != \"document.xml\":\n continue\n\n try:\n root = lxml.etree.parse(str(xml_file)).getroot()\n\n for elem in root.iter(f\"{{{self.WORD_2006_NAMESPACE}}}t\"):\n if elem.text:\n text = elem.text\n if re.search(r\"^[ \\t\\n\\r]\", text) or re.search(\n r\"[ \\t\\n\\r]$\", text\n ):\n xml_space_attr = f\"{{{self.XML_NAMESPACE}}}space\"\n if (\n xml_space_attr not in elem.attrib\n or elem.attrib[xml_space_attr] != \"preserve\"\n ):\n text_preview = (\n repr(text)[:50] + \"...\"\n if len(repr(text)) > 50\n else repr(text)\n )\n errors.append(\n f\" {xml_file.relative_to(self.unpacked_dir)}: \"\n f\"Line {elem.sourceline}: w:t element with whitespace missing xml:space='preserve': {text_preview}\"\n )\n\n except (lxml.etree.XMLSyntaxError, Exception) as e:\n errors.append(\n f\" {xml_file.relative_to(self.unpacked_dir)}: Error: {e}\"\n )\n\n if errors:\n print(f\"FAILED - Found {len(errors)} whitespace preservation violations:\")\n for error in errors:\n print(error)\n return False\n else:\n if self.verbose:\n print(\"PASSED - All whitespace is properly preserved\")\n return True\n\n def validate_deletions(self):\n errors = []\n\n for xml_file in self.xml_files:\n if xml_file.name != \"document.xml\":\n continue\n\n try:\n root = lxml.etree.parse(str(xml_file)).getroot()\n namespaces = {\"w\": self.WORD_2006_NAMESPACE}\n\n for t_elem in root.xpath(\".//w:del//w:t\", namespaces=namespaces):\n if t_elem.text:\n text_preview = (\n repr(t_elem.text)[:50] + \"...\"\n if len(repr(t_elem.text)) > 50\n else repr(t_elem.text)\n )\n errors.append(\n f\" {xml_file.relative_to(self.unpacked_dir)}: \"\n f\"Line {t_elem.sourceline}: found within : {text_preview}\"\n )\n\n for instr_elem in root.xpath(\n \".//w:del//w:instrText\", namespaces=namespaces\n ):\n text_preview = (\n repr(instr_elem.text or \"\")[:50] + \"...\"\n if len(repr(instr_elem.text or \"\")) > 50\n else repr(instr_elem.text or \"\")\n )\n errors.append(\n f\" {xml_file.relative_to(self.unpacked_dir)}: \"\n f\"Line {instr_elem.sourceline}: found within (use ): {text_preview}\"\n )\n\n except (lxml.etree.XMLSyntaxError, Exception) as e:\n errors.append(\n f\" {xml_file.relative_to(self.unpacked_dir)}: Error: {e}\"\n )\n\n if errors:\n print(f\"FAILED - Found {len(errors)} deletion validation violations:\")\n for error in errors:\n print(error)\n return False\n else:\n if self.verbose:\n print(\"PASSED - No w:t elements found within w:del elements\")\n return True\n\n def count_paragraphs_in_unpacked(self):\n count = 0\n\n for xml_file in self.xml_files:\n if xml_file.name != \"document.xml\":\n continue\n\n try:\n root = lxml.etree.parse(str(xml_file)).getroot()\n paragraphs = root.findall(f\".//{{{self.WORD_2006_NAMESPACE}}}p\")\n count = len(paragraphs)\n except Exception as e:\n print(f\"Error counting paragraphs in unpacked document: {e}\")\n\n return count\n\n def count_paragraphs_in_original(self):\n original = self.original_file\n if original is None:\n return 0\n\n count = 0\n\n try:\n with tempfile.TemporaryDirectory() as temp_dir:\n with zipfile.ZipFile(original, \"r\") as zip_ref:\n zip_ref.extractall(temp_dir)\n\n doc_xml_path = os.path.join(temp_dir, \"word\", \"document.xml\")\n root = lxml.etree.parse(doc_xml_path).getroot()\n\n paragraphs = root.findall(f\".//{{{self.WORD_2006_NAMESPACE}}}p\")\n count = len(paragraphs)\n\n except Exception as e:\n print(f\"Error counting paragraphs in original document: {e}\")\n\n return count\n\n def validate_insertions(self):\n errors = []\n\n for xml_file in self.xml_files:\n if xml_file.name != \"document.xml\":\n continue\n\n try:\n root = lxml.etree.parse(str(xml_file)).getroot()\n namespaces = {\"w\": self.WORD_2006_NAMESPACE}\n\n invalid_elements = root.xpath(\n \".//w:ins//w:delText[not(ancestor::w:del)]\", namespaces=namespaces\n )\n\n for elem in invalid_elements:\n text_preview = (\n repr(elem.text or \"\")[:50] + \"...\"\n if len(repr(elem.text or \"\")) > 50\n else repr(elem.text or \"\")\n )\n errors.append(\n f\" {xml_file.relative_to(self.unpacked_dir)}: \"\n f\"Line {elem.sourceline}: within : {text_preview}\"\n )\n\n except (lxml.etree.XMLSyntaxError, Exception) as e:\n errors.append(\n f\" {xml_file.relative_to(self.unpacked_dir)}: Error: {e}\"\n )\n\n if errors:\n print(f\"FAILED - Found {len(errors)} insertion validation violations:\")\n for error in errors:\n print(error)\n return False\n else:\n if self.verbose:\n print(\"PASSED - No w:delText elements within w:ins elements\")\n return True\n\n def compare_paragraph_counts(self):\n original_count = self.count_paragraphs_in_original()\n new_count = self.count_paragraphs_in_unpacked()\n\n diff = new_count - original_count\n diff_str = f\"+{diff}\" if diff > 0 else str(diff)\n print(f\"\\nParagraphs: {original_count} → {new_count} ({diff_str})\")\n\n def _parse_id_value(self, val: str, base: int = 16) -> int:\n return int(val, base)\n\n def validate_id_constraints(self):\n errors = []\n para_id_attr = f\"{{{self.W14_NAMESPACE}}}paraId\"\n durable_id_attr = f\"{{{self.W16CID_NAMESPACE}}}durableId\"\n\n for xml_file in self.xml_files:\n try:\n for elem in lxml.etree.parse(str(xml_file)).iter():\n if val := elem.get(para_id_attr):\n if self._parse_id_value(val, base=16) >= 0x80000000:\n errors.append(\n f\" {xml_file.name}:{elem.sourceline}: paraId={val} >= 0x80000000\"\n )\n\n if val := elem.get(durable_id_attr):\n if xml_file.name == \"numbering.xml\":\n try:\n if self._parse_id_value(val, base=10) >= 0x7FFFFFFF:\n errors.append(\n f\" {xml_file.name}:{elem.sourceline}: \"\n f\"durableId={val} >= 0x7FFFFFFF\"\n )\n except ValueError:\n errors.append(\n f\" {xml_file.name}:{elem.sourceline}: \"\n f\"durableId={val} must be decimal in numbering.xml\"\n )\n else:\n if self._parse_id_value(val, base=16) >= 0x7FFFFFFF:\n errors.append(\n f\" {xml_file.name}:{elem.sourceline}: \"\n f\"durableId={val} >= 0x7FFFFFFF\"\n )\n except Exception:\n pass\n\n if errors:\n print(f\"FAILED - {len(errors)} ID constraint violations:\")\n for e in errors:\n print(e)\n elif self.verbose:\n print(\"PASSED - All paraId/durableId values within constraints\")\n return not errors\n\n def validate_comment_markers(self):\n errors = []\n\n document_xml = None\n comments_xml = None\n for xml_file in self.xml_files:\n if xml_file.name == \"document.xml\" and \"word\" in str(xml_file):\n document_xml = xml_file\n elif xml_file.name == \"comments.xml\":\n comments_xml = xml_file\n\n if not document_xml:\n if self.verbose:\n print(\"PASSED - No document.xml found (skipping comment validation)\")\n return True\n\n try:\n doc_root = lxml.etree.parse(str(document_xml)).getroot()\n namespaces = {\"w\": self.WORD_2006_NAMESPACE}\n\n range_starts = {\n elem.get(f\"{{{self.WORD_2006_NAMESPACE}}}id\")\n for elem in doc_root.xpath(\n \".//w:commentRangeStart\", namespaces=namespaces\n )\n }\n range_ends = {\n elem.get(f\"{{{self.WORD_2006_NAMESPACE}}}id\")\n for elem in doc_root.xpath(\n \".//w:commentRangeEnd\", namespaces=namespaces\n )\n }\n references = {\n elem.get(f\"{{{self.WORD_2006_NAMESPACE}}}id\")\n for elem in doc_root.xpath(\n \".//w:commentReference\", namespaces=namespaces\n )\n }\n\n orphaned_ends = range_ends - range_starts\n for comment_id in sorted(\n orphaned_ends, key=lambda x: int(x) if x and x.isdigit() else 0\n ):\n errors.append(\n f' document.xml: commentRangeEnd id=\"{comment_id}\" has no matching commentRangeStart'\n )\n\n orphaned_starts = range_starts - range_ends\n for comment_id in sorted(\n orphaned_starts, key=lambda x: int(x) if x and x.isdigit() else 0\n ):\n errors.append(\n f' document.xml: commentRangeStart id=\"{comment_id}\" has no matching commentRangeEnd'\n )\n\n comment_ids = set()\n if comments_xml and comments_xml.exists():\n comments_root = lxml.etree.parse(str(comments_xml)).getroot()\n comment_ids = {\n elem.get(f\"{{{self.WORD_2006_NAMESPACE}}}id\")\n for elem in comments_root.xpath(\n \".//w:comment\", namespaces=namespaces\n )\n }\n\n marker_ids = range_starts | range_ends | references\n invalid_refs = marker_ids - comment_ids\n for comment_id in sorted(\n invalid_refs, key=lambda x: int(x) if x and x.isdigit() else 0\n ):\n if comment_id: \n errors.append(\n f' document.xml: marker id=\"{comment_id}\" references non-existent comment'\n )\n\n except (lxml.etree.XMLSyntaxError, Exception) as e:\n errors.append(f\" Error parsing XML: {e}\")\n\n if errors:\n print(f\"FAILED - {len(errors)} comment marker violations:\")\n for error in errors:\n print(error)\n return False\n else:\n if self.verbose:\n print(\"PASSED - All comment markers properly paired\")\n return True\n\n def repair(self) -> int:\n repairs = super().repair()\n repairs += self.repair_durableId()\n return repairs\n\n def repair_durableId(self) -> int:\n repairs = 0\n\n for xml_file in self.xml_files:\n try:\n content = xml_file.read_text(encoding=\"utf-8\")\n dom = defusedxml.minidom.parseString(content)\n modified = False\n\n for elem in dom.getElementsByTagName(\"*\"):\n if not elem.hasAttribute(\"w16cid:durableId\"):\n continue\n\n durable_id = elem.getAttribute(\"w16cid:durableId\")\n needs_repair = False\n\n if xml_file.name == \"numbering.xml\":\n try:\n needs_repair = (\n self._parse_id_value(durable_id, base=10) >= 0x7FFFFFFF\n )\n except ValueError:\n needs_repair = True\n else:\n try:\n needs_repair = (\n self._parse_id_value(durable_id, base=16) >= 0x7FFFFFFF\n )\n except ValueError:\n needs_repair = True\n\n if needs_repair:\n value = random.randint(1, 0x7FFFFFFE)\n if xml_file.name == \"numbering.xml\":\n new_id = str(value) \n else:\n new_id = f\"{value:08X}\" \n\n elem.setAttribute(\"w16cid:durableId\", new_id)\n print(\n f\" Repaired: {xml_file.name}: durableId {durable_id} → {new_id}\"\n )\n repairs += 1\n modified = True\n\n if modified:\n xml_file.write_bytes(dom.toxml(encoding=\"UTF-8\"))\n\n except Exception:\n pass\n\n return repairs\n\n\nif __name__ == \"__main__\":\n raise RuntimeError(\"This module should not be run directly.\")\n" }, { "path": "src/copaw/agents/skills/pptx/scripts/office/validators/pptx.py", "content": "\"\"\"\nValidator for PowerPoint presentation XML files against XSD schemas.\n\"\"\"\n\nimport re\n\nfrom .base import BaseSchemaValidator\n\n\nclass PPTXSchemaValidator(BaseSchemaValidator):\n\n PRESENTATIONML_NAMESPACE = (\n \"http://schemas.openxmlformats.org/presentationml/2006/main\"\n )\n\n ELEMENT_RELATIONSHIP_TYPES = {\n \"sldid\": \"slide\",\n \"sldmasterid\": \"slidemaster\",\n \"notesmasterid\": \"notesmaster\",\n \"sldlayoutid\": \"slidelayout\",\n \"themeid\": \"theme\",\n \"tablestyleid\": \"tablestyles\",\n }\n\n def validate(self):\n if not self.validate_xml():\n return False\n\n all_valid = True\n if not self.validate_namespaces():\n all_valid = False\n\n if not self.validate_unique_ids():\n all_valid = False\n\n if not self.validate_uuid_ids():\n all_valid = False\n\n if not self.validate_file_references():\n all_valid = False\n\n if not self.validate_slide_layout_ids():\n all_valid = False\n\n if not self.validate_content_types():\n all_valid = False\n\n if not self.validate_against_xsd():\n all_valid = False\n\n if not self.validate_notes_slide_references():\n all_valid = False\n\n if not self.validate_all_relationship_ids():\n all_valid = False\n\n if not self.validate_no_duplicate_slide_layouts():\n all_valid = False\n\n return all_valid\n\n def validate_uuid_ids(self):\n import lxml.etree\n\n errors = []\n uuid_pattern = re.compile(\n r\"^[\\{\\(]?[0-9A-Fa-f]{8}-?[0-9A-Fa-f]{4}-?[0-9A-Fa-f]{4}-?[0-9A-Fa-f]{4}-?[0-9A-Fa-f]{12}[\\}\\)]?$\"\n )\n\n for xml_file in self.xml_files:\n try:\n root = lxml.etree.parse(str(xml_file)).getroot()\n\n for elem in root.iter():\n for attr, value in elem.attrib.items():\n attr_name = attr.split(\"}\")[-1].lower()\n if attr_name == \"id\" or attr_name.endswith(\"id\"):\n if self._looks_like_uuid(value):\n if not uuid_pattern.match(value):\n errors.append(\n f\" {xml_file.relative_to(self.unpacked_dir)}: \"\n f\"Line {elem.sourceline}: ID '{value}' appears to be a UUID but contains invalid hex characters\"\n )\n\n except (lxml.etree.XMLSyntaxError, Exception) as e:\n errors.append(\n f\" {xml_file.relative_to(self.unpacked_dir)}: Error: {e}\"\n )\n\n if errors:\n print(f\"FAILED - Found {len(errors)} UUID ID validation errors:\")\n for error in errors:\n print(error)\n return False\n else:\n if self.verbose:\n print(\"PASSED - All UUID-like IDs contain valid hex values\")\n return True\n\n def _looks_like_uuid(self, value):\n clean_value = value.strip(\"{}()\").replace(\"-\", \"\")\n return len(clean_value) == 32 and all(c.isalnum() for c in clean_value)\n\n def validate_slide_layout_ids(self):\n import lxml.etree\n\n errors = []\n\n slide_masters = list(self.unpacked_dir.glob(\"ppt/slideMasters/*.xml\"))\n\n if not slide_masters:\n if self.verbose:\n print(\"PASSED - No slide masters found\")\n return True\n\n for slide_master in slide_masters:\n try:\n root = lxml.etree.parse(str(slide_master)).getroot()\n\n rels_file = slide_master.parent / \"_rels\" / f\"{slide_master.name}.rels\"\n\n if not rels_file.exists():\n errors.append(\n f\" {slide_master.relative_to(self.unpacked_dir)}: \"\n f\"Missing relationships file: {rels_file.relative_to(self.unpacked_dir)}\"\n )\n continue\n\n rels_root = lxml.etree.parse(str(rels_file)).getroot()\n\n valid_layout_rids = set()\n for rel in rels_root.findall(\n f\".//{{{self.PACKAGE_RELATIONSHIPS_NAMESPACE}}}Relationship\"\n ):\n rel_type = rel.get(\"Type\", \"\")\n if \"slideLayout\" in rel_type:\n valid_layout_rids.add(rel.get(\"Id\"))\n\n for sld_layout_id in root.findall(\n f\".//{{{self.PRESENTATIONML_NAMESPACE}}}sldLayoutId\"\n ):\n r_id = sld_layout_id.get(\n f\"{{{self.OFFICE_RELATIONSHIPS_NAMESPACE}}}id\"\n )\n layout_id = sld_layout_id.get(\"id\")\n\n if r_id and r_id not in valid_layout_rids:\n errors.append(\n f\" {slide_master.relative_to(self.unpacked_dir)}: \"\n f\"Line {sld_layout_id.sourceline}: sldLayoutId with id='{layout_id}' \"\n f\"references r:id='{r_id}' which is not found in slide layout relationships\"\n )\n\n except (lxml.etree.XMLSyntaxError, Exception) as e:\n errors.append(\n f\" {slide_master.relative_to(self.unpacked_dir)}: Error: {e}\"\n )\n\n if errors:\n print(f\"FAILED - Found {len(errors)} slide layout ID validation errors:\")\n for error in errors:\n print(error)\n print(\n \"Remove invalid references or add missing slide layouts to the relationships file.\"\n )\n return False\n else:\n if self.verbose:\n print(\"PASSED - All slide layout IDs reference valid slide layouts\")\n return True\n\n def validate_no_duplicate_slide_layouts(self):\n import lxml.etree\n\n errors = []\n slide_rels_files = list(self.unpacked_dir.glob(\"ppt/slides/_rels/*.xml.rels\"))\n\n for rels_file in slide_rels_files:\n try:\n root = lxml.etree.parse(str(rels_file)).getroot()\n\n layout_rels = [\n rel\n for rel in root.findall(\n f\".//{{{self.PACKAGE_RELATIONSHIPS_NAMESPACE}}}Relationship\"\n )\n if \"slideLayout\" in rel.get(\"Type\", \"\")\n ]\n\n if len(layout_rels) > 1:\n errors.append(\n f\" {rels_file.relative_to(self.unpacked_dir)}: has {len(layout_rels)} slideLayout references\"\n )\n\n except Exception as e:\n errors.append(\n f\" {rels_file.relative_to(self.unpacked_dir)}: Error: {e}\"\n )\n\n if errors:\n print(\"FAILED - Found slides with duplicate slideLayout references:\")\n for error in errors:\n print(error)\n return False\n else:\n if self.verbose:\n print(\"PASSED - All slides have exactly one slideLayout reference\")\n return True\n\n def validate_notes_slide_references(self):\n import lxml.etree\n\n errors = []\n notes_slide_references = {} \n\n slide_rels_files = list(self.unpacked_dir.glob(\"ppt/slides/_rels/*.xml.rels\"))\n\n if not slide_rels_files:\n if self.verbose:\n print(\"PASSED - No slide relationship files found\")\n return True\n\n for rels_file in slide_rels_files:\n try:\n root = lxml.etree.parse(str(rels_file)).getroot()\n\n for rel in root.findall(\n f\".//{{{self.PACKAGE_RELATIONSHIPS_NAMESPACE}}}Relationship\"\n ):\n rel_type = rel.get(\"Type\", \"\")\n if \"notesSlide\" in rel_type:\n target = rel.get(\"Target\", \"\")\n if target:\n normalized_target = target.replace(\"../\", \"\")\n\n slide_name = rels_file.stem.replace(\n \".xml\", \"\"\n ) \n\n if normalized_target not in notes_slide_references:\n notes_slide_references[normalized_target] = []\n notes_slide_references[normalized_target].append(\n (slide_name, rels_file)\n )\n\n except (lxml.etree.XMLSyntaxError, Exception) as e:\n errors.append(\n f\" {rels_file.relative_to(self.unpacked_dir)}: Error: {e}\"\n )\n\n for target, references in notes_slide_references.items():\n if len(references) > 1:\n slide_names = [ref[0] for ref in references]\n errors.append(\n f\" Notes slide '{target}' is referenced by multiple slides: {', '.join(slide_names)}\"\n )\n for slide_name, rels_file in references:\n errors.append(f\" - {rels_file.relative_to(self.unpacked_dir)}\")\n\n if errors:\n print(\n f\"FAILED - Found {len([e for e in errors if not e.startswith(' ')])} notes slide reference validation errors:\"\n )\n for error in errors:\n print(error)\n print(\"Each slide may optionally have its own slide file.\")\n return False\n else:\n if self.verbose:\n print(\"PASSED - All notes slide references are unique\")\n return True\n\n\nif __name__ == \"__main__\":\n raise RuntimeError(\"This module should not be run directly.\")\n" }, { "path": "src/copaw/agents/skills/pptx/scripts/office/validators/redlining.py", "content": "\"\"\"\nValidator for tracked changes in Word documents.\n\"\"\"\n\nimport subprocess\nimport tempfile\nimport zipfile\nfrom pathlib import Path\n\n\nclass RedliningValidator:\n\n def __init__(self, unpacked_dir, original_docx, verbose=False, author=\"Claude\"):\n self.unpacked_dir = Path(unpacked_dir)\n self.original_docx = Path(original_docx)\n self.verbose = verbose\n self.author = author\n self.namespaces = {\n \"w\": \"http://schemas.openxmlformats.org/wordprocessingml/2006/main\"\n }\n\n def repair(self) -> int:\n return 0\n\n def validate(self):\n modified_file = self.unpacked_dir / \"word\" / \"document.xml\"\n if not modified_file.exists():\n print(f\"FAILED - Modified document.xml not found at {modified_file}\")\n return False\n\n try:\n import xml.etree.ElementTree as ET\n\n tree = ET.parse(modified_file)\n root = tree.getroot()\n\n del_elements = root.findall(\".//w:del\", self.namespaces)\n ins_elements = root.findall(\".//w:ins\", self.namespaces)\n\n author_del_elements = [\n elem\n for elem in del_elements\n if elem.get(f\"{{{self.namespaces['w']}}}author\") == self.author\n ]\n author_ins_elements = [\n elem\n for elem in ins_elements\n if elem.get(f\"{{{self.namespaces['w']}}}author\") == self.author\n ]\n\n if not author_del_elements and not author_ins_elements:\n if self.verbose:\n print(f\"PASSED - No tracked changes by {self.author} found.\")\n return True\n\n except Exception:\n pass\n\n with tempfile.TemporaryDirectory() as temp_dir:\n temp_path = Path(temp_dir)\n\n try:\n with zipfile.ZipFile(self.original_docx, \"r\") as zip_ref:\n zip_ref.extractall(temp_path)\n except Exception as e:\n print(f\"FAILED - Error unpacking original docx: {e}\")\n return False\n\n original_file = temp_path / \"word\" / \"document.xml\"\n if not original_file.exists():\n print(\n f\"FAILED - Original document.xml not found in {self.original_docx}\"\n )\n return False\n\n try:\n import xml.etree.ElementTree as ET\n\n modified_tree = ET.parse(modified_file)\n modified_root = modified_tree.getroot()\n original_tree = ET.parse(original_file)\n original_root = original_tree.getroot()\n except ET.ParseError as e:\n print(f\"FAILED - Error parsing XML files: {e}\")\n return False\n\n self._remove_author_tracked_changes(original_root)\n self._remove_author_tracked_changes(modified_root)\n\n modified_text = self._extract_text_content(modified_root)\n original_text = self._extract_text_content(original_root)\n\n if modified_text != original_text:\n error_message = self._generate_detailed_diff(\n original_text, modified_text\n )\n print(error_message)\n return False\n\n if self.verbose:\n print(f\"PASSED - All changes by {self.author} are properly tracked\")\n return True\n\n def _generate_detailed_diff(self, original_text, modified_text):\n error_parts = [\n f\"FAILED - Document text doesn't match after removing {self.author}'s tracked changes\",\n \"\",\n \"Likely causes:\",\n \" 1. Modified text inside another author's or tags\",\n \" 2. Made edits without proper tracked changes\",\n \" 3. Didn't nest inside when deleting another's insertion\",\n \"\",\n \"For pre-redlined documents, use correct patterns:\",\n \" - To reject another's INSERTION: Nest inside their \",\n \" - To restore another's DELETION: Add new AFTER their \",\n \"\",\n ]\n\n git_diff = self._get_git_word_diff(original_text, modified_text)\n if git_diff:\n error_parts.extend([\"Differences:\", \"============\", git_diff])\n else:\n error_parts.append(\"Unable to generate word diff (git not available)\")\n\n return \"\\n\".join(error_parts)\n\n def _get_git_word_diff(self, original_text, modified_text):\n try:\n with tempfile.TemporaryDirectory() as temp_dir:\n temp_path = Path(temp_dir)\n\n original_file = temp_path / \"original.txt\"\n modified_file = temp_path / \"modified.txt\"\n\n original_file.write_text(original_text, encoding=\"utf-8\")\n modified_file.write_text(modified_text, encoding=\"utf-8\")\n\n result = subprocess.run(\n [\n \"git\",\n \"diff\",\n \"--word-diff=plain\",\n \"--word-diff-regex=.\", \n \"-U0\", \n \"--no-index\",\n str(original_file),\n str(modified_file),\n ],\n capture_output=True,\n text=True,\n )\n\n if result.stdout.strip():\n lines = result.stdout.split(\"\\n\")\n content_lines = []\n in_content = False\n for line in lines:\n if line.startswith(\"@@\"):\n in_content = True\n continue\n if in_content and line.strip():\n content_lines.append(line)\n\n if content_lines:\n return \"\\n\".join(content_lines)\n\n result = subprocess.run(\n [\n \"git\",\n \"diff\",\n \"--word-diff=plain\",\n \"-U0\", \n \"--no-index\",\n str(original_file),\n str(modified_file),\n ],\n capture_output=True,\n text=True,\n )\n\n if result.stdout.strip():\n lines = result.stdout.split(\"\\n\")\n content_lines = []\n in_content = False\n for line in lines:\n if line.startswith(\"@@\"):\n in_content = True\n continue\n if in_content and line.strip():\n content_lines.append(line)\n return \"\\n\".join(content_lines)\n\n except (subprocess.CalledProcessError, FileNotFoundError, Exception):\n pass\n\n return None\n\n def _remove_author_tracked_changes(self, root):\n ins_tag = f\"{{{self.namespaces['w']}}}ins\"\n del_tag = f\"{{{self.namespaces['w']}}}del\"\n author_attr = f\"{{{self.namespaces['w']}}}author\"\n\n for parent in root.iter():\n to_remove = []\n for child in parent:\n if child.tag == ins_tag and child.get(author_attr) == self.author:\n to_remove.append(child)\n for elem in to_remove:\n parent.remove(elem)\n\n deltext_tag = f\"{{{self.namespaces['w']}}}delText\"\n t_tag = f\"{{{self.namespaces['w']}}}t\"\n\n for parent in root.iter():\n to_process = []\n for child in parent:\n if child.tag == del_tag and child.get(author_attr) == self.author:\n to_process.append((child, list(parent).index(child)))\n\n for del_elem, del_index in reversed(to_process):\n for elem in del_elem.iter():\n if elem.tag == deltext_tag:\n elem.tag = t_tag\n\n for child in reversed(list(del_elem)):\n parent.insert(del_index, child)\n parent.remove(del_elem)\n\n def _extract_text_content(self, root):\n p_tag = f\"{{{self.namespaces['w']}}}p\"\n t_tag = f\"{{{self.namespaces['w']}}}t\"\n\n paragraphs = []\n for p_elem in root.findall(f\".//{p_tag}\"):\n text_parts = []\n for t_elem in p_elem.findall(f\".//{t_tag}\"):\n if t_elem.text:\n text_parts.append(t_elem.text)\n paragraph_text = \"\".join(text_parts)\n if paragraph_text:\n paragraphs.append(paragraph_text)\n\n return \"\\n\".join(paragraphs)\n\n\nif __name__ == \"__main__\":\n raise RuntimeError(\"This module should not be run directly.\")\n" }, { "path": "src/copaw/agents/skills/pptx/scripts/thumbnail.py", "content": "\"\"\"Create thumbnail grids from PowerPoint presentation slides.\n\nCreates a grid layout of slide thumbnails for quick visual analysis.\nLabels each thumbnail with its XML filename (e.g., slide1.xml).\nHidden slides are shown with a placeholder pattern.\n\nUsage:\n python thumbnail.py input.pptx [output_prefix] [--cols N]\n\nExamples:\n python thumbnail.py presentation.pptx\n # Creates: thumbnails.jpg\n\n python thumbnail.py template.pptx grid --cols 4\n # Creates: grid.jpg (or grid-1.jpg, grid-2.jpg for large decks)\n\"\"\"\n\nimport argparse\nimport subprocess\nimport sys\nimport tempfile\nimport zipfile\nfrom pathlib import Path\n\nimport defusedxml.minidom\nfrom office.soffice import run_soffice\nfrom PIL import Image, ImageDraw, ImageFont\n\nTHUMBNAIL_WIDTH = 300\nCONVERSION_DPI = 100\nMAX_COLS = 6\nDEFAULT_COLS = 3\nJPEG_QUALITY = 95\nGRID_PADDING = 20\nBORDER_WIDTH = 2\nFONT_SIZE_RATIO = 0.10\nLABEL_PADDING_RATIO = 0.4\n\n\ndef main():\n parser = argparse.ArgumentParser(\n description=\"Create thumbnail grids from PowerPoint slides.\"\n )\n parser.add_argument(\"input\", help=\"Input PowerPoint file (.pptx)\")\n parser.add_argument(\n \"output_prefix\",\n nargs=\"?\",\n default=\"thumbnails\",\n help=\"Output prefix for image files (default: thumbnails)\",\n )\n parser.add_argument(\n \"--cols\",\n type=int,\n default=DEFAULT_COLS,\n help=f\"Number of columns (default: {DEFAULT_COLS}, max: {MAX_COLS})\",\n )\n\n args = parser.parse_args()\n\n cols = min(args.cols, MAX_COLS)\n if args.cols > MAX_COLS:\n print(f\"Warning: Columns limited to {MAX_COLS}\")\n\n input_path = Path(args.input)\n if not input_path.exists() or input_path.suffix.lower() != \".pptx\":\n print(f\"Error: Invalid PowerPoint file: {args.input}\", file=sys.stderr)\n sys.exit(1)\n\n output_path = Path(f\"{args.output_prefix}.jpg\")\n\n try:\n slide_info = get_slide_info(input_path)\n\n with tempfile.TemporaryDirectory() as temp_dir:\n temp_path = Path(temp_dir)\n visible_images = convert_to_images(input_path, temp_path)\n\n if not visible_images and not any(s[\"hidden\"] for s in slide_info):\n print(\"Error: No slides found\", file=sys.stderr)\n sys.exit(1)\n\n slides = build_slide_list(slide_info, visible_images, temp_path)\n\n grid_files = create_grids(slides, cols, THUMBNAIL_WIDTH, output_path)\n\n print(f\"Created {len(grid_files)} grid(s):\")\n for grid_file in grid_files:\n print(f\" {grid_file}\")\n\n except Exception as e:\n print(f\"Error: {e}\", file=sys.stderr)\n sys.exit(1)\n\n\ndef get_slide_info(pptx_path: Path) -> list[dict]:\n with zipfile.ZipFile(pptx_path, \"r\") as zf:\n rels_content = zf.read(\"ppt/_rels/presentation.xml.rels\").decode(\"utf-8\")\n rels_dom = defusedxml.minidom.parseString(rels_content)\n\n rid_to_slide = {}\n for rel in rels_dom.getElementsByTagName(\"Relationship\"):\n rid = rel.getAttribute(\"Id\")\n target = rel.getAttribute(\"Target\")\n rel_type = rel.getAttribute(\"Type\")\n if \"slide\" in rel_type and target.startswith(\"slides/\"):\n rid_to_slide[rid] = target.replace(\"slides/\", \"\")\n\n pres_content = zf.read(\"ppt/presentation.xml\").decode(\"utf-8\")\n pres_dom = defusedxml.minidom.parseString(pres_content)\n\n slides = []\n for sld_id in pres_dom.getElementsByTagName(\"p:sldId\"):\n rid = sld_id.getAttribute(\"r:id\")\n if rid in rid_to_slide:\n hidden = sld_id.getAttribute(\"show\") == \"0\"\n slides.append({\"name\": rid_to_slide[rid], \"hidden\": hidden})\n\n return slides\n\n\ndef build_slide_list(\n slide_info: list[dict],\n visible_images: list[Path],\n temp_dir: Path,\n) -> list[tuple[Path, str]]:\n if visible_images:\n with Image.open(visible_images[0]) as img:\n placeholder_size = img.size\n else:\n placeholder_size = (1920, 1080)\n\n slides = []\n visible_idx = 0\n\n for info in slide_info:\n if info[\"hidden\"]:\n placeholder_path = temp_dir / f\"hidden-{info['name']}.jpg\"\n placeholder_img = create_hidden_placeholder(placeholder_size)\n placeholder_img.save(placeholder_path, \"JPEG\")\n slides.append((placeholder_path, f\"{info['name']} (hidden)\"))\n else:\n if visible_idx < len(visible_images):\n slides.append((visible_images[visible_idx], info[\"name\"]))\n visible_idx += 1\n\n return slides\n\n\ndef create_hidden_placeholder(size: tuple[int, int]) -> Image.Image:\n img = Image.new(\"RGB\", size, color=\"#F0F0F0\")\n draw = ImageDraw.Draw(img)\n line_width = max(5, min(size) // 100)\n draw.line([(0, 0), size], fill=\"#CCCCCC\", width=line_width)\n draw.line([(size[0], 0), (0, size[1])], fill=\"#CCCCCC\", width=line_width)\n return img\n\n\ndef convert_to_images(pptx_path: Path, temp_dir: Path) -> list[Path]:\n pdf_path = temp_dir / f\"{pptx_path.stem}.pdf\"\n\n result = run_soffice(\n [\n \"--headless\",\n \"--convert-to\",\n \"pdf\",\n \"--outdir\",\n str(temp_dir),\n str(pptx_path),\n ],\n capture_output=True,\n text=True,\n )\n if result.returncode != 0 or not pdf_path.exists():\n raise RuntimeError(\"PDF conversion failed\")\n\n # Try pdftoppm first, fall back to pdf2image (cross-platform)\n try:\n result = subprocess.run(\n [\n \"pdftoppm\",\n \"-jpeg\",\n \"-r\",\n str(CONVERSION_DPI),\n str(pdf_path),\n str(temp_dir / \"slide\"),\n ],\n capture_output=True,\n text=True,\n )\n except FileNotFoundError:\n # pdftoppm not available (e.g. Windows without Poppler); use pdf2image\n try:\n from pdf2image import convert_from_path as _pdf_convert\n\n images = _pdf_convert(str(pdf_path), dpi=CONVERSION_DPI)\n for idx, img in enumerate(images, start=1):\n out = temp_dir / f\"slide-{idx:02d}.jpg\"\n img.save(str(out), \"JPEG\")\n except ImportError:\n raise RuntimeError(\n \"Image conversion failed: pdftoppm not found and \"\n \"pdf2image package is not installed. \"\n \"Install poppler or run: pip install pdf2image\"\n )\n else:\n if result.returncode != 0:\n stderr = (result.stderr or \"\").strip() or \"unknown pdftoppm error\"\n raise RuntimeError(f\"Image conversion failed: {stderr}\")\n\n return sorted(temp_dir.glob(\"slide-*.jpg\"))\n\n\ndef create_grids(\n slides: list[tuple[Path, str]],\n cols: int,\n width: int,\n output_path: Path,\n) -> list[str]:\n max_per_grid = cols * (cols + 1)\n grid_files = []\n\n for chunk_idx, start_idx in enumerate(range(0, len(slides), max_per_grid)):\n end_idx = min(start_idx + max_per_grid, len(slides))\n chunk_slides = slides[start_idx:end_idx]\n\n grid = create_grid(chunk_slides, cols, width)\n\n if len(slides) <= max_per_grid:\n grid_filename = output_path\n else:\n stem = output_path.stem\n suffix = output_path.suffix\n grid_filename = output_path.parent / f\"{stem}-{chunk_idx + 1}{suffix}\"\n\n grid_filename.parent.mkdir(parents=True, exist_ok=True)\n grid.save(str(grid_filename), quality=JPEG_QUALITY)\n grid_files.append(str(grid_filename))\n\n return grid_files\n\n\ndef create_grid(\n slides: list[tuple[Path, str]],\n cols: int,\n width: int,\n) -> Image.Image:\n font_size = int(width * FONT_SIZE_RATIO)\n label_padding = int(font_size * LABEL_PADDING_RATIO)\n\n with Image.open(slides[0][0]) as img:\n aspect = img.height / img.width\n height = int(width * aspect)\n\n rows = (len(slides) + cols - 1) // cols\n grid_w = cols * width + (cols + 1) * GRID_PADDING\n grid_h = rows * (height + font_size + label_padding * 2) + (rows + 1) * GRID_PADDING\n\n grid = Image.new(\"RGB\", (grid_w, grid_h), \"white\")\n draw = ImageDraw.Draw(grid)\n\n try:\n font = ImageFont.load_default(size=font_size)\n except Exception:\n font = ImageFont.load_default()\n\n for i, (img_path, slide_name) in enumerate(slides):\n row, col = i // cols, i % cols\n x = col * width + (col + 1) * GRID_PADDING\n y_base = (\n row * (height + font_size + label_padding * 2) + (row + 1) * GRID_PADDING\n )\n\n label = slide_name\n bbox = draw.textbbox((0, 0), label, font=font)\n text_w = bbox[2] - bbox[0]\n draw.text(\n (x + (width - text_w) // 2, y_base + label_padding),\n label,\n fill=\"black\",\n font=font,\n )\n\n y_thumbnail = y_base + label_padding + font_size + label_padding\n\n with Image.open(img_path) as img:\n img.thumbnail((width, height), Image.Resampling.LANCZOS)\n w, h = img.size\n tx = x + (width - w) // 2\n ty = y_thumbnail + (height - h) // 2\n grid.paste(img, (tx, ty))\n\n if BORDER_WIDTH > 0:\n draw.rectangle(\n [\n (tx - BORDER_WIDTH, ty - BORDER_WIDTH),\n (tx + w + BORDER_WIDTH - 1, ty + h + BORDER_WIDTH - 1),\n ],\n outline=\"gray\",\n width=BORDER_WIDTH,\n )\n\n return grid\n\n\nif __name__ == \"__main__\":\n main()\n" }, { "path": "src/copaw/agents/skills/xlsx/LICENSE.txt", "content": "© 2025 Anthropic, PBC. All rights reserved.\n\nLICENSE: Use of these materials (including all code, prompts, assets, files,\nand other components of this Skill) is governed by your agreement with\nAnthropic regarding use of Anthropic's services. If no separate agreement\nexists, use is governed by Anthropic's Consumer Terms of Service or\nCommercial Terms of Service, as applicable:\nhttps://www.anthropic.com/legal/consumer-terms\nhttps://www.anthropic.com/legal/commercial-terms\nYour applicable agreement is referred to as the \"Agreement.\" \"Services\" are\nas defined in the Agreement.\n\nADDITIONAL RESTRICTIONS: Notwithstanding anything in the Agreement to the\ncontrary, users may not:\n\n- Extract these materials from the Services or retain copies of these\n materials outside the Services\n- Reproduce or copy these materials, except for temporary copies created\n automatically during authorized use of the Services\n- Create derivative works based on these materials\n- Distribute, sublicense, or transfer these materials to any third party\n- Make, offer to sell, sell, or import any inventions embodied in these\n materials\n- Reverse engineer, decompile, or disassemble these materials\n\nThe receipt, viewing, or possession of these materials does not convey or\nimply any license or right beyond those expressly granted above.\n\nAnthropic retains all right, title, and interest in these materials,\nincluding all copyrights, patents, and other intellectual property rights.\n" }, { "path": "src/copaw/agents/skills/xlsx/SKILL.md", "content": "---\nname: xlsx\ndescription: \"Use this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path — even casually (like \\\"the xlsx in my downloads\\\") — and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper spreadsheets. The deliverable must be a spreadsheet file. Do NOT trigger when the primary deliverable is a Word document, HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved.\"\nlicense: Proprietary. LICENSE.txt has complete terms\nmetadata: { \"builtin_skill_version\": \"1.0\" }\n---\n\n> **Important:** All `scripts/` paths are relative to this skill directory.\n> Run with: `cd {this_skill_dir} && python scripts/...`\n> Or use the `cwd` parameter of `execute_shell_command`.\n\n# Requirements for Outputs\n\n## All Excel files\n\n### Professional Font\n- Use a consistent, professional font (e.g., Arial, Times New Roman) for all deliverables unless otherwise instructed by the user\n\n### Zero Formula Errors\n- Every Excel model MUST be delivered with ZERO formula errors (#REF!, #DIV/0!, #VALUE!, #N/A, #NAME?)\n\n### Preserve Existing Templates (when updating templates)\n- Study and EXACTLY match existing format, style, and conventions when modifying files\n- Never impose standardized formatting on files with established patterns\n- Existing template conventions ALWAYS override these guidelines\n\n## Financial models\n\n### Color Coding Standards\nUnless otherwise stated by the user or existing template\n\n#### Industry-Standard Color Conventions\n- **Blue text (RGB: 0,0,255)**: Hardcoded inputs, and numbers users will change for scenarios\n- **Black text (RGB: 0,0,0)**: ALL formulas and calculations\n- **Green text (RGB: 0,128,0)**: Links pulling from other worksheets within same workbook\n- **Red text (RGB: 255,0,0)**: External links to other files\n- **Yellow background (RGB: 255,255,0)**: Key assumptions needing attention or cells that need to be updated\n\n### Number Formatting Standards\n\n#### Required Format Rules\n- **Years**: Format as text strings (e.g., \"2024\" not \"2,024\")\n- **Currency**: Use $#,##0 format; ALWAYS specify units in headers (\"Revenue ($mm)\")\n- **Zeros**: Use number formatting to make all zeros \"-\", including percentages (e.g., \"$#,##0;($#,##0);-\")\n- **Percentages**: Default to 0.0% format (one decimal)\n- **Multiples**: Format as 0.0x for valuation multiples (EV/EBITDA, P/E)\n- **Negative numbers**: Use parentheses (123) not minus -123\n\n### Formula Construction Rules\n\n#### Assumptions Placement\n- Place ALL assumptions (growth rates, margins, multiples, etc.) in separate assumption cells\n- Use cell references instead of hardcoded values in formulas\n- Example: Use =B5*(1+$B$6) instead of =B5*1.05\n\n#### Formula Error Prevention\n- Verify all cell references are correct\n- Check for off-by-one errors in ranges\n- Ensure consistent formulas across all projection periods\n- Test with edge cases (zero values, negative numbers)\n- Verify no unintended circular references\n\n#### Documentation Requirements for Hardcodes\n- Comment or in cells beside (if end of table). Format: \"Source: [System/Document], [Date], [Specific Reference], [URL if applicable]\"\n- Examples:\n - \"Source: Company 10-K, FY2024, Page 45, Revenue Note, [SEC EDGAR URL]\"\n - \"Source: Company 10-Q, Q2 2025, Exhibit 99.1, [SEC EDGAR URL]\"\n - \"Source: Bloomberg Terminal, 8/15/2025, AAPL US Equity\"\n - \"Source: FactSet, 8/20/2025, Consensus Estimates Screen\"\n\n# XLSX creation, editing, and analysis\n\n## Overview\n\nA user may ask you to create, edit, or analyze the contents of an .xlsx file. You have different tools and workflows available for different tasks.\n\n## Prerequisites\n\n- **openpyxl**: Excel file creation and editing\n- **pandas**: data analysis and bulk operations\n- **LibreOffice** (`soffice`): formula recalculation via `scripts/recalc.py`\n- `git` is optional but improves redlining diff output in validation workflows.\n- On Windows, dependencies must be installed and available in `PATH`; if missing, report the dependency issue and stop (do not keep retrying).\n\n## Important Requirements\n\n**LibreOffice Required for Formula Recalculation**: Use `scripts/recalc.py` to recalculate formula values. The script auto-configures LibreOffice on first run and handles sandboxed environments where Unix sockets are restricted (via `scripts/office/soffice.py`).\n\n## Reading and analyzing data\n\n### Data analysis with pandas\nFor data analysis, visualization, and basic operations, use **pandas** which provides powerful data manipulation capabilities:\n\n```python\nimport pandas as pd\n\n# Read Excel\ndf = pd.read_excel('file.xlsx') # Default: first sheet\nall_sheets = pd.read_excel('file.xlsx', sheet_name=None) # All sheets as dict\n\n# Analyze\ndf.head() # Preview data\ndf.info() # Column info\ndf.describe() # Statistics\n\n# Write Excel\ndf.to_excel('output.xlsx', index=False)\n```\n\n## Excel File Workflows\n\n## CRITICAL: Use Formulas, Not Hardcoded Values\n\n**Always use Excel formulas instead of calculating values in Python and hardcoding them.** This ensures the spreadsheet remains dynamic and updateable.\n\n### ❌ WRONG - Hardcoding Calculated Values\n```python\n# Bad: Calculating in Python and hardcoding result\ntotal = df['Sales'].sum()\nsheet['B10'] = total # Hardcodes 5000\n\n# Bad: Computing growth rate in Python\ngrowth = (df.iloc[-1]['Revenue'] - df.iloc[0]['Revenue']) / df.iloc[0]['Revenue']\nsheet['C5'] = growth # Hardcodes 0.15\n\n# Bad: Python calculation for average\navg = sum(values) / len(values)\nsheet['D20'] = avg # Hardcodes 42.5\n```\n\n### ✅ CORRECT - Using Excel Formulas\n```python\n# Good: Let Excel calculate the sum\nsheet['B10'] = '=SUM(B2:B9)'\n\n# Good: Growth rate as Excel formula\nsheet['C5'] = '=(C4-C2)/C2'\n\n# Good: Average using Excel function\nsheet['D20'] = '=AVERAGE(D2:D19)'\n```\n\nThis applies to ALL calculations - totals, percentages, ratios, differences, etc. The spreadsheet should be able to recalculate when source data changes.\n\n## Common Workflow\n1. **Choose tool**: pandas for data, openpyxl for formulas/formatting\n2. **Create/Load**: Create new workbook or load existing file\n3. **Modify**: Add/edit data, formulas, and formatting\n4. **Save**: Write to file\n5. **Recalculate formulas (MANDATORY IF USING FORMULAS)**: Use the scripts/recalc.py script\n ```bash\n python scripts/recalc.py output.xlsx\n ```\n6. **Verify and fix any errors**: \n - The script returns JSON with error details\n - If `status` is `errors_found`, check `error_summary` for specific error types and locations\n - Fix the identified errors and recalculate again\n - Common errors to fix:\n - `#REF!`: Invalid cell references\n - `#DIV/0!`: Division by zero\n - `#VALUE!`: Wrong data type in formula\n - `#NAME?`: Unrecognized formula name\n\n### Creating new Excel files\n\n```python\n# Using openpyxl for formulas and formatting\nfrom openpyxl import Workbook\nfrom openpyxl.styles import Font, PatternFill, Alignment\n\nwb = Workbook()\nsheet = wb.active\n\n# Add data\nsheet['A1'] = 'Hello'\nsheet['B1'] = 'World'\nsheet.append(['Row', 'of', 'data'])\n\n# Add formula\nsheet['B2'] = '=SUM(A1:A10)'\n\n# Formatting\nsheet['A1'].font = Font(bold=True, color='FF0000')\nsheet['A1'].fill = PatternFill('solid', start_color='FFFF00')\nsheet['A1'].alignment = Alignment(horizontal='center')\n\n# Column width\nsheet.column_dimensions['A'].width = 20\n\nwb.save('output.xlsx')\n```\n\n### Editing existing Excel files\n\n```python\n# Using openpyxl to preserve formulas and formatting\nfrom openpyxl import load_workbook\n\n# Load existing file\nwb = load_workbook('existing.xlsx')\nsheet = wb.active # or wb['SheetName'] for specific sheet\n\n# Working with multiple sheets\nfor sheet_name in wb.sheetnames:\n sheet = wb[sheet_name]\n print(f\"Sheet: {sheet_name}\")\n\n# Modify cells\nsheet['A1'] = 'New Value'\nsheet.insert_rows(2) # Insert row at position 2\nsheet.delete_cols(3) # Delete column 3\n\n# Add new sheet\nnew_sheet = wb.create_sheet('NewSheet')\nnew_sheet['A1'] = 'Data'\n\nwb.save('modified.xlsx')\n```\n\n## Recalculating formulas\n\nExcel files created or modified by openpyxl contain formulas as strings but not calculated values. Use the provided `scripts/recalc.py` script to recalculate formulas:\n\n```bash\npython scripts/recalc.py [timeout_seconds]\n```\n\nExample:\n```bash\npython scripts/recalc.py output.xlsx 30\n```\n\nThe script:\n- Automatically sets up LibreOffice macro on first run\n- Recalculates all formulas in all sheets\n- Scans ALL cells for Excel errors (#REF!, #DIV/0!, etc.)\n- Returns JSON with detailed error locations and counts\n- Works on Linux, macOS, and Windows\n\n## Formula Verification Checklist\n\nQuick checks to ensure formulas work correctly:\n\n### Essential Verification\n- [ ] **Test 2-3 sample references**: Verify they pull correct values before building full model\n- [ ] **Column mapping**: Confirm Excel columns match (e.g., column 64 = BL, not BK)\n- [ ] **Row offset**: Remember Excel rows are 1-indexed (DataFrame row 5 = Excel row 6)\n\n### Common Pitfalls\n- [ ] **NaN handling**: Check for null values with `pd.notna()`\n- [ ] **Far-right columns**: FY data often in columns 50+ \n- [ ] **Multiple matches**: Search all occurrences, not just first\n- [ ] **Division by zero**: Check denominators before using `/` in formulas (#DIV/0!)\n- [ ] **Wrong references**: Verify all cell references point to intended cells (#REF!)\n- [ ] **Cross-sheet references**: Use correct format (Sheet1!A1) for linking sheets\n\n### Formula Testing Strategy\n- [ ] **Start small**: Test formulas on 2-3 cells before applying broadly\n- [ ] **Verify dependencies**: Check all cells referenced in formulas exist\n- [ ] **Test edge cases**: Include zero, negative, and very large values\n\n### Interpreting scripts/recalc.py Output\nThe script returns JSON with error details:\n```json\n{\n \"status\": \"success\", // or \"errors_found\"\n \"total_errors\": 0, // Total error count\n \"total_formulas\": 42, // Number of formulas in file\n \"error_summary\": { // Only present if errors found\n \"#REF!\": {\n \"count\": 2,\n \"locations\": [\"Sheet1!B5\", \"Sheet1!C10\"]\n }\n }\n}\n```\n\n## Best Practices\n\n### Library Selection\n- **pandas**: Best for data analysis, bulk operations, and simple data export\n- **openpyxl**: Best for complex formatting, formulas, and Excel-specific features\n\n### Working with openpyxl\n- Cell indices are 1-based (row=1, column=1 refers to cell A1)\n- Use `data_only=True` to read calculated values: `load_workbook('file.xlsx', data_only=True)`\n- **Warning**: If opened with `data_only=True` and saved, formulas are replaced with values and permanently lost\n- For large files: Use `read_only=True` for reading or `write_only=True` for writing\n- Formulas are preserved but not evaluated - use scripts/recalc.py to update values\n\n### Working with pandas\n- Specify data types to avoid inference issues: `pd.read_excel('file.xlsx', dtype={'id': str})`\n- For large files, read specific columns: `pd.read_excel('file.xlsx', usecols=['A', 'C', 'E'])`\n- Handle dates properly: `pd.read_excel('file.xlsx', parse_dates=['date_column'])`\n\n## Code Style Guidelines\n**IMPORTANT**: When generating Python code for Excel operations:\n- Write minimal, concise Python code without unnecessary comments\n- Avoid verbose variable names and redundant operations\n- Avoid unnecessary print statements\n\n**For Excel files themselves**:\n- Add comments to cells with complex formulas or important assumptions\n- Document data sources for hardcoded values\n- Include notes for key calculations and model sections" }, { "path": "src/copaw/agents/skills/xlsx/scripts/office/helpers/__init__.py", "content": "" }, { "path": "src/copaw/agents/skills/xlsx/scripts/office/helpers/merge_runs.py", "content": "\"\"\"Merge adjacent runs with identical formatting in DOCX.\n\nMerges adjacent elements that have identical properties.\nWorks on runs in paragraphs and inside tracked changes (, ).\n\nAlso:\n- Removes rsid attributes from runs (revision metadata that doesn't affect rendering)\n- Removes proofErr elements (spell/grammar markers that block merging)\n\"\"\"\n\nfrom pathlib import Path\n\nimport defusedxml.minidom\n\n\ndef merge_runs(input_dir: str) -> tuple[int, str]:\n doc_xml = Path(input_dir) / \"word\" / \"document.xml\"\n\n if not doc_xml.exists():\n return 0, f\"Error: {doc_xml} not found\"\n\n try:\n dom = defusedxml.minidom.parseString(doc_xml.read_text(encoding=\"utf-8\"))\n root = dom.documentElement\n\n _remove_elements(root, \"proofErr\")\n _strip_run_rsid_attrs(root)\n\n containers = {run.parentNode for run in _find_elements(root, \"r\")}\n\n merge_count = 0\n for container in containers:\n merge_count += _merge_runs_in(container)\n\n doc_xml.write_bytes(dom.toxml(encoding=\"UTF-8\"))\n return merge_count, f\"Merged {merge_count} runs\"\n\n except Exception as e:\n return 0, f\"Error: {e}\"\n\n\n\n\ndef _find_elements(root, tag: str) -> list:\n results = []\n\n def traverse(node):\n if node.nodeType == node.ELEMENT_NODE:\n name = node.localName or node.tagName\n if name == tag or name.endswith(f\":{tag}\"):\n results.append(node)\n for child in node.childNodes:\n traverse(child)\n\n traverse(root)\n return results\n\n\ndef _get_child(parent, tag: str):\n for child in parent.childNodes:\n if child.nodeType == child.ELEMENT_NODE:\n name = child.localName or child.tagName\n if name == tag or name.endswith(f\":{tag}\"):\n return child\n return None\n\n\ndef _get_children(parent, tag: str) -> list:\n results = []\n for child in parent.childNodes:\n if child.nodeType == child.ELEMENT_NODE:\n name = child.localName or child.tagName\n if name == tag or name.endswith(f\":{tag}\"):\n results.append(child)\n return results\n\n\ndef _is_adjacent(elem1, elem2) -> bool:\n node = elem1.nextSibling\n while node:\n if node == elem2:\n return True\n if node.nodeType == node.ELEMENT_NODE:\n return False\n if node.nodeType == node.TEXT_NODE and node.data.strip():\n return False\n node = node.nextSibling\n return False\n\n\n\n\ndef _remove_elements(root, tag: str):\n for elem in _find_elements(root, tag):\n if elem.parentNode:\n elem.parentNode.removeChild(elem)\n\n\ndef _strip_run_rsid_attrs(root):\n for run in _find_elements(root, \"r\"):\n for attr in list(run.attributes.values()):\n if \"rsid\" in attr.name.lower():\n run.removeAttribute(attr.name)\n\n\n\n\ndef _merge_runs_in(container) -> int:\n merge_count = 0\n run = _first_child_run(container)\n\n while run:\n while True:\n next_elem = _next_element_sibling(run)\n if next_elem and _is_run(next_elem) and _can_merge(run, next_elem):\n _merge_run_content(run, next_elem)\n container.removeChild(next_elem)\n merge_count += 1\n else:\n break\n\n _consolidate_text(run)\n run = _next_sibling_run(run)\n\n return merge_count\n\n\ndef _first_child_run(container):\n for child in container.childNodes:\n if child.nodeType == child.ELEMENT_NODE and _is_run(child):\n return child\n return None\n\n\ndef _next_element_sibling(node):\n sibling = node.nextSibling\n while sibling:\n if sibling.nodeType == sibling.ELEMENT_NODE:\n return sibling\n sibling = sibling.nextSibling\n return None\n\n\ndef _next_sibling_run(node):\n sibling = node.nextSibling\n while sibling:\n if sibling.nodeType == sibling.ELEMENT_NODE:\n if _is_run(sibling):\n return sibling\n sibling = sibling.nextSibling\n return None\n\n\ndef _is_run(node) -> bool:\n name = node.localName or node.tagName\n return name == \"r\" or name.endswith(\":r\")\n\n\ndef _can_merge(run1, run2) -> bool:\n rpr1 = _get_child(run1, \"rPr\")\n rpr2 = _get_child(run2, \"rPr\")\n\n if (rpr1 is None) != (rpr2 is None):\n return False\n if rpr1 is None:\n return True\n return rpr1.toxml() == rpr2.toxml() \n\n\ndef _merge_run_content(target, source):\n for child in list(source.childNodes):\n if child.nodeType == child.ELEMENT_NODE:\n name = child.localName or child.tagName\n if name != \"rPr\" and not name.endswith(\":rPr\"):\n target.appendChild(child)\n\n\ndef _consolidate_text(run):\n t_elements = _get_children(run, \"t\")\n\n for i in range(len(t_elements) - 1, 0, -1):\n curr, prev = t_elements[i], t_elements[i - 1]\n\n if _is_adjacent(prev, curr):\n prev_text = prev.firstChild.data if prev.firstChild else \"\"\n curr_text = curr.firstChild.data if curr.firstChild else \"\"\n merged = prev_text + curr_text\n\n if prev.firstChild:\n prev.firstChild.data = merged\n else:\n prev.appendChild(run.ownerDocument.createTextNode(merged))\n\n if merged.startswith(\" \") or merged.endswith(\" \"):\n prev.setAttribute(\"xml:space\", \"preserve\")\n elif prev.hasAttribute(\"xml:space\"):\n prev.removeAttribute(\"xml:space\")\n\n run.removeChild(curr)\n" }, { "path": "src/copaw/agents/skills/xlsx/scripts/office/helpers/simplify_redlines.py", "content": "\"\"\"Simplify tracked changes by merging adjacent w:ins or w:del elements.\n\nMerges adjacent elements from the same author into a single element.\nSame for elements. This makes heavily-redlined documents easier to\nwork with by reducing the number of tracked change wrappers.\n\nRules:\n- Only merges w:ins with w:ins, w:del with w:del (same element type)\n- Only merges if same author (ignores timestamp differences)\n- Only merges if truly adjacent (only whitespace between them)\n\"\"\"\n\nimport xml.etree.ElementTree as ET\nimport zipfile\nfrom pathlib import Path\n\nimport defusedxml.minidom\n\nWORD_NS = \"http://schemas.openxmlformats.org/wordprocessingml/2006/main\"\n\n\ndef simplify_redlines(input_dir: str) -> tuple[int, str]:\n doc_xml = Path(input_dir) / \"word\" / \"document.xml\"\n\n if not doc_xml.exists():\n return 0, f\"Error: {doc_xml} not found\"\n\n try:\n dom = defusedxml.minidom.parseString(doc_xml.read_text(encoding=\"utf-8\"))\n root = dom.documentElement\n\n merge_count = 0\n\n containers = _find_elements(root, \"p\") + _find_elements(root, \"tc\")\n\n for container in containers:\n merge_count += _merge_tracked_changes_in(container, \"ins\")\n merge_count += _merge_tracked_changes_in(container, \"del\")\n\n doc_xml.write_bytes(dom.toxml(encoding=\"UTF-8\"))\n return merge_count, f\"Simplified {merge_count} tracked changes\"\n\n except Exception as e:\n return 0, f\"Error: {e}\"\n\n\ndef _merge_tracked_changes_in(container, tag: str) -> int:\n merge_count = 0\n\n tracked = [\n child\n for child in container.childNodes\n if child.nodeType == child.ELEMENT_NODE and _is_element(child, tag)\n ]\n\n if len(tracked) < 2:\n return 0\n\n i = 0\n while i < len(tracked) - 1:\n curr = tracked[i]\n next_elem = tracked[i + 1]\n\n if _can_merge_tracked(curr, next_elem):\n _merge_tracked_content(curr, next_elem)\n container.removeChild(next_elem)\n tracked.pop(i + 1)\n merge_count += 1\n else:\n i += 1\n\n return merge_count\n\n\ndef _is_element(node, tag: str) -> bool:\n name = node.localName or node.tagName\n return name == tag or name.endswith(f\":{tag}\")\n\n\ndef _get_author(elem) -> str:\n author = elem.getAttribute(\"w:author\")\n if not author:\n for attr in elem.attributes.values():\n if attr.localName == \"author\" or attr.name.endswith(\":author\"):\n return attr.value\n return author\n\n\ndef _can_merge_tracked(elem1, elem2) -> bool:\n if _get_author(elem1) != _get_author(elem2):\n return False\n\n node = elem1.nextSibling\n while node and node != elem2:\n if node.nodeType == node.ELEMENT_NODE:\n return False\n if node.nodeType == node.TEXT_NODE and node.data.strip():\n return False\n node = node.nextSibling\n\n return True\n\n\ndef _merge_tracked_content(target, source):\n while source.firstChild:\n child = source.firstChild\n source.removeChild(child)\n target.appendChild(child)\n\n\ndef _find_elements(root, tag: str) -> list:\n results = []\n\n def traverse(node):\n if node.nodeType == node.ELEMENT_NODE:\n name = node.localName or node.tagName\n if name == tag or name.endswith(f\":{tag}\"):\n results.append(node)\n for child in node.childNodes:\n traverse(child)\n\n traverse(root)\n return results\n\n\ndef get_tracked_change_authors(doc_xml_path: Path) -> dict[str, int]:\n if not doc_xml_path.exists():\n return {}\n\n try:\n tree = ET.parse(doc_xml_path)\n root = tree.getroot()\n except ET.ParseError:\n return {}\n\n namespaces = {\"w\": WORD_NS}\n author_attr = f\"{{{WORD_NS}}}author\"\n\n authors: dict[str, int] = {}\n for tag in [\"ins\", \"del\"]:\n for elem in root.findall(f\".//w:{tag}\", namespaces):\n author = elem.get(author_attr)\n if author:\n authors[author] = authors.get(author, 0) + 1\n\n return authors\n\n\ndef _get_authors_from_docx(docx_path: Path) -> dict[str, int]:\n try:\n with zipfile.ZipFile(docx_path, \"r\") as zf:\n if \"word/document.xml\" not in zf.namelist():\n return {}\n with zf.open(\"word/document.xml\") as f:\n tree = ET.parse(f)\n root = tree.getroot()\n\n namespaces = {\"w\": WORD_NS}\n author_attr = f\"{{{WORD_NS}}}author\"\n\n authors: dict[str, int] = {}\n for tag in [\"ins\", \"del\"]:\n for elem in root.findall(f\".//w:{tag}\", namespaces):\n author = elem.get(author_attr)\n if author:\n authors[author] = authors.get(author, 0) + 1\n return authors\n except (zipfile.BadZipFile, ET.ParseError):\n return {}\n\n\ndef infer_author(modified_dir: Path, original_docx: Path, default: str = \"Claude\") -> str:\n modified_xml = modified_dir / \"word\" / \"document.xml\"\n modified_authors = get_tracked_change_authors(modified_xml)\n\n if not modified_authors:\n return default\n\n original_authors = _get_authors_from_docx(original_docx)\n\n new_changes: dict[str, int] = {}\n for author, count in modified_authors.items():\n original_count = original_authors.get(author, 0)\n diff = count - original_count\n if diff > 0:\n new_changes[author] = diff\n\n if not new_changes:\n return default\n\n if len(new_changes) == 1:\n return next(iter(new_changes))\n\n raise ValueError(\n f\"Multiple authors added new changes: {new_changes}. \"\n \"Cannot infer which author to validate.\"\n )\n" }, { "path": "src/copaw/agents/skills/xlsx/scripts/office/pack.py", "content": "\"\"\"Pack a directory into a DOCX, PPTX, or XLSX file.\n\nValidates with auto-repair, condenses XML formatting, and creates the Office file.\n\nUsage:\n python pack.py [--original ] [--validate true|false]\n\nExamples:\n python pack.py unpacked/ output.docx --original input.docx\n python pack.py unpacked/ output.pptx --validate false\n\"\"\"\n\nimport argparse\nimport sys\nimport shutil\nimport tempfile\nimport zipfile\nfrom pathlib import Path\n\nimport defusedxml.minidom\n\nfrom validators import DOCXSchemaValidator, PPTXSchemaValidator, RedliningValidator\n\ndef pack(\n input_directory: str,\n output_file: str,\n original_file: str | None = None,\n validate: bool = True,\n infer_author_func=None,\n) -> tuple[None, str]:\n input_dir = Path(input_directory)\n output_path = Path(output_file)\n suffix = output_path.suffix.lower()\n\n if not input_dir.is_dir():\n return None, f\"Error: {input_dir} is not a directory\"\n\n if suffix not in {\".docx\", \".pptx\", \".xlsx\"}:\n return None, f\"Error: {output_file} must be a .docx, .pptx, or .xlsx file\"\n\n if validate and original_file:\n original_path = Path(original_file)\n if original_path.exists():\n success, output = _run_validation(\n input_dir, original_path, suffix, infer_author_func\n )\n if output:\n print(output)\n if not success:\n return None, f\"Error: Validation failed for {input_dir}\"\n\n with tempfile.TemporaryDirectory() as temp_dir:\n temp_content_dir = Path(temp_dir) / \"content\"\n shutil.copytree(input_dir, temp_content_dir)\n\n for pattern in [\"*.xml\", \"*.rels\"]:\n for xml_file in temp_content_dir.rglob(pattern):\n _condense_xml(xml_file)\n\n output_path.parent.mkdir(parents=True, exist_ok=True)\n with zipfile.ZipFile(output_path, \"w\", zipfile.ZIP_DEFLATED) as zf:\n for f in temp_content_dir.rglob(\"*\"):\n if f.is_file():\n zf.write(f, f.relative_to(temp_content_dir))\n\n return None, f\"Successfully packed {input_dir} to {output_file}\"\n\n\ndef _run_validation(\n unpacked_dir: Path,\n original_file: Path,\n suffix: str,\n infer_author_func=None,\n) -> tuple[bool, str | None]:\n output_lines = []\n validators = []\n\n if suffix == \".docx\":\n author = \"Claude\"\n if infer_author_func:\n try:\n author = infer_author_func(unpacked_dir, original_file)\n except ValueError as e:\n print(f\"Warning: {e} Using default author 'Claude'.\", file=sys.stderr)\n\n validators = [\n DOCXSchemaValidator(unpacked_dir, original_file),\n RedliningValidator(unpacked_dir, original_file, author=author),\n ]\n elif suffix == \".pptx\":\n validators = [PPTXSchemaValidator(unpacked_dir, original_file)]\n\n if not validators:\n return True, None\n\n total_repairs = sum(v.repair() for v in validators)\n if total_repairs:\n output_lines.append(f\"Auto-repaired {total_repairs} issue(s)\")\n\n success = all(v.validate() for v in validators)\n\n if success:\n output_lines.append(\"All validations PASSED!\")\n\n return success, \"\\n\".join(output_lines) if output_lines else None\n\n\ndef _condense_xml(xml_file: Path) -> None:\n try:\n with open(xml_file, encoding=\"utf-8\") as f:\n dom = defusedxml.minidom.parse(f)\n\n for element in dom.getElementsByTagName(\"*\"):\n if element.tagName.endswith(\":t\"):\n continue\n\n for child in list(element.childNodes):\n if (\n child.nodeType == child.TEXT_NODE\n and child.nodeValue\n and child.nodeValue.strip() == \"\"\n ) or child.nodeType == child.COMMENT_NODE:\n element.removeChild(child)\n\n xml_file.write_bytes(dom.toxml(encoding=\"UTF-8\"))\n except Exception as e:\n print(f\"ERROR: Failed to parse {xml_file.name}: {e}\", file=sys.stderr)\n raise\n\n\nif __name__ == \"__main__\":\n parser = argparse.ArgumentParser(\n description=\"Pack a directory into a DOCX, PPTX, or XLSX file\"\n )\n parser.add_argument(\"input_directory\", help=\"Unpacked Office document directory\")\n parser.add_argument(\"output_file\", help=\"Output Office file (.docx/.pptx/.xlsx)\")\n parser.add_argument(\n \"--original\",\n help=\"Original file for validation comparison\",\n )\n parser.add_argument(\n \"--validate\",\n type=lambda x: x.lower() == \"true\",\n default=True,\n metavar=\"true|false\",\n help=\"Run validation with auto-repair (default: true)\",\n )\n args = parser.parse_args()\n\n _, message = pack(\n args.input_directory,\n args.output_file,\n original_file=args.original,\n validate=args.validate,\n )\n print(message)\n\n if \"Error\" in message:\n sys.exit(1)\n" }, { "path": "src/copaw/agents/skills/xlsx/scripts/office/schemas/ISO-IEC29500-4_2016/dml-chart.xsd", "content": "\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n\n" }, { "path": "src/copaw/agents/skills/xlsx/scripts/office/schemas/ISO-IEC29500-4_2016/dml-chartDrawing.xsd", "content": "\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n\n" }, { "path": "src/copaw/agents/skills/xlsx/scripts/office/schemas/ISO-IEC29500-4_2016/dml-diagram.xsd", "content": "\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n\n" }, { "path": "src/copaw/agents/skills/xlsx/scripts/office/schemas/ISO-IEC29500-4_2016/dml-lockedCanvas.xsd", "content": "\n\n \n \n\n" }, { "path": "src/copaw/agents/skills/xlsx/scripts/office/schemas/ISO-IEC29500-4_2016/dml-main.xsd", "content": "\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n\n" }, { "path": "src/copaw/agents/skills/xlsx/scripts/office/schemas/ISO-IEC29500-4_2016/dml-picture.xsd", "content": "\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n\n" }, { "path": "src/copaw/agents/skills/xlsx/scripts/office/schemas/ISO-IEC29500-4_2016/dml-spreadsheetDrawing.xsd", "content": "\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n\n" }, { "path": "src/copaw/agents/skills/xlsx/scripts/office/schemas/ISO-IEC29500-4_2016/dml-wordprocessingDrawing.xsd", "content": "\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n\n" }, { "path": "src/copaw/agents/skills/xlsx/scripts/office/schemas/ISO-IEC29500-4_2016/pml.xsd", "content": "\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n\n" }, { "path": "src/copaw/agents/skills/xlsx/scripts/office/schemas/ISO-IEC29500-4_2016/shared-additionalCharacteristics.xsd", "content": "\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n\n" }, { "path": "src/copaw/agents/skills/xlsx/scripts/office/schemas/ISO-IEC29500-4_2016/shared-bibliography.xsd", "content": "\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n\n" }, { "path": "src/copaw/agents/skills/xlsx/scripts/office/schemas/ISO-IEC29500-4_2016/shared-commonSimpleTypes.xsd", "content": "\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n\n" }, { "path": "src/copaw/agents/skills/xlsx/scripts/office/schemas/ISO-IEC29500-4_2016/shared-customXmlDataProperties.xsd", "content": "\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n\n" }, { "path": "src/copaw/agents/skills/xlsx/scripts/office/schemas/ISO-IEC29500-4_2016/shared-customXmlSchemaProperties.xsd", "content": "\n\n \n \n \n \n \n \n \n \n \n \n \n \n\n" }, { "path": "src/copaw/agents/skills/xlsx/scripts/office/schemas/ISO-IEC29500-4_2016/shared-documentPropertiesCustom.xsd", "content": "\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n\n" }, { "path": "src/copaw/agents/skills/xlsx/scripts/office/schemas/ISO-IEC29500-4_2016/shared-documentPropertiesExtended.xsd", "content": "\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n\n" }, { "path": "src/copaw/agents/skills/xlsx/scripts/office/schemas/ISO-IEC29500-4_2016/shared-documentPropertiesVariantTypes.xsd", "content": "\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n\n" }, { "path": "src/copaw/agents/skills/xlsx/scripts/office/schemas/ISO-IEC29500-4_2016/shared-math.xsd", "content": "\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n\n" }, { "path": "src/copaw/agents/skills/xlsx/scripts/office/schemas/ISO-IEC29500-4_2016/shared-relationshipReference.xsd", "content": "\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n\n" }, { "path": "src/copaw/agents/skills/xlsx/scripts/office/schemas/ISO-IEC29500-4_2016/sml.xsd", "content": "\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n\n" }, { "path": "src/copaw/agents/skills/xlsx/scripts/office/schemas/ISO-IEC29500-4_2016/vml-main.xsd", "content": "\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n\n" }, { "path": "src/copaw/agents/skills/xlsx/scripts/office/schemas/ISO-IEC29500-4_2016/vml-officeDrawing.xsd", "content": "\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n\n" }, { "path": "src/copaw/agents/skills/xlsx/scripts/office/schemas/ISO-IEC29500-4_2016/vml-presentationDrawing.xsd", "content": "\n\n \n \n \n \n \n \n\n" }, { "path": "src/copaw/agents/skills/xlsx/scripts/office/schemas/ISO-IEC29500-4_2016/vml-spreadsheetDrawing.xsd", "content": "\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n\n" }, { "path": "src/copaw/agents/skills/xlsx/scripts/office/schemas/ISO-IEC29500-4_2016/vml-wordprocessingDrawing.xsd", "content": "\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n\n" }, { "path": "src/copaw/agents/skills/xlsx/scripts/office/schemas/ISO-IEC29500-4_2016/wml.xsd", "content": "\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n\n" }, { "path": "src/copaw/agents/skills/xlsx/scripts/office/schemas/ISO-IEC29500-4_2016/xml.xsd", "content": "\n\n\n \n \n See http://www.w3.org/XML/1998/namespace.html and\n http://www.w3.org/TR/REC-xml for information about this namespace.\n\n This schema document describes the XML namespace, in a form\n suitable for import by other schema documents. \n\n Note that local names in this namespace are intended to be defined\n only by the World Wide Web Consortium or its subgroups. The\n following names are currently defined in this namespace and should\n not be used with conflicting semantics by any Working Group,\n specification, or document instance:\n\n base (as an attribute name): denotes an attribute whose value\n provides a URI to be used as the base for interpreting any\n relative URIs in the scope of the element on which it\n appears; its value is inherited. This name is reserved\n by virtue of its definition in the XML Base specification.\n\n lang (as an attribute name): denotes an attribute whose value\n is a language code for the natural language of the content of\n any element; its value is inherited. This name is reserved\n by virtue of its definition in the XML specification.\n \n space (as an attribute name): denotes an attribute whose\n value is a keyword indicating what whitespace processing\n discipline is intended for the content of the element; its\n value is inherited. This name is reserved by virtue of its\n definition in the XML specification.\n\n Father (in any context at all): denotes Jon Bosak, the chair of \n the original XML Working Group. This name is reserved by \n the following decision of the W3C XML Plenary and \n XML Coordination groups:\n\n In appreciation for his vision, leadership and dedication\n the W3C XML Plenary on this 10th day of February, 2000\n reserves for Jon Bosak in perpetuity the XML name\n xml:Father\n \n \n\n \n This schema defines attributes and an attribute group\n suitable for use by\n schemas wishing to allow xml:base, xml:lang or xml:space attributes\n on elements they define.\n\n To enable this, such a schema must import this schema\n for the XML namespace, e.g. as follows:\n <schema . . .>\n . . .\n <import namespace=\"http://www.w3.org/XML/1998/namespace\"\n schemaLocation=\"http://www.w3.org/2001/03/xml.xsd\"/>\n\n Subsequently, qualified reference to any of the attributes\n or the group defined below will have the desired effect, e.g.\n\n <type . . .>\n . . .\n <attributeGroup ref=\"xml:specialAttrs\"/>\n \n will define a type which will schema-validate an instance\n element with any of those attributes\n \n\n \n In keeping with the XML Schema WG's standard versioning\n policy, this schema document will persist at\n http://www.w3.org/2001/03/xml.xsd.\n At the date of issue it can also be found at\n http://www.w3.org/2001/xml.xsd.\n The schema document at that URI may however change in the future,\n in order to remain compatible with the latest version of XML Schema\n itself. In other words, if the XML Schema namespace changes, the version\n of this document at\n http://www.w3.org/2001/xml.xsd will change\n accordingly; the version at\n http://www.w3.org/2001/03/xml.xsd will not change.\n \n \n\n \n \n In due course, we should install the relevant ISO 2- and 3-letter\n codes as the enumerated possible values . . .\n \n \n\n \n \n \n \n \n \n \n \n\n \n \n See http://www.w3.org/TR/xmlbase/ for\n information about this attribute.\n \n \n\n \n \n \n \n \n\n\n" }, { "path": "src/copaw/agents/skills/xlsx/scripts/office/schemas/ecma/fouth-edition/opc-contentTypes.xsd", "content": "\n\n\n \n \n \n\n \n \n \n \n \n \n\n \n \n \n \n\n \n \n \n \n\n \n \n \n \n \n\n \n \n \n \n \n\n" }, { "path": "src/copaw/agents/skills/xlsx/scripts/office/schemas/ecma/fouth-edition/opc-coreProperties.xsd", "content": "\n\n\n \n \n \n\n \n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n\n \n \n \n \n \n \n\n \n \n \n \n \n \n \n\n\n" }, { "path": "src/copaw/agents/skills/xlsx/scripts/office/schemas/ecma/fouth-edition/opc-digSig.xsd", "content": "\n\n\n \n \n \n\n \n \n \n \n \n \n\n \n \n \n \n \n \n \n\n \n \n \n \n \n \n \n\n \n \n \n \n \n\n \n \n \n \n \n\n" }, { "path": "src/copaw/agents/skills/xlsx/scripts/office/schemas/ecma/fouth-edition/opc-relationships.xsd", "content": "\n\n\n \n \n\n \n \n \n \n \n\n \n \n \n \n \n \n \n \n \n \n\n \n \n \n \n \n \n\n" }, { "path": "src/copaw/agents/skills/xlsx/scripts/office/schemas/mce/mc.xsd", "content": "\n\n\n \n\n \n \n\n \n\t\n\t\n\n\n\t\n\t\t\n\t\t\t\n\t\t\t\t\n\t\t\t\t\t\n\t\t\t\t\t\t\n\t\t\t\t\t\t\t\n\t\t\t\t\t\t\t\n\t\t\t\t\t\t\n\t\t\t\t\t\t\n\t\t\t\t\t\t\n\t\t\t\t\t\t\n\t\t\t\t\t\t\n\t\t\t\t\t\n\t\t\t\t\n\t\t\t\t\n\t\t\t\t\t\n\t\t\t\t\t\t\n\t\t\t\t\t\t\t\n\t\t\t\t\t\t\t\n\t\t\t\t\t\t\n\t\t\t\t\t\t\n\t\t\t\t\t\t\n\t\t\t\t\t\t\n\t\t\t\t\t\n\t\t\t\t\n\t\t\t\n\t\t\t\n\t\t\t\n\t\t\t\n\t\t\t\n\t\t\n\t\n\n" }, { "path": "src/copaw/agents/skills/xlsx/scripts/office/schemas/microsoft/wml-2010.xsd", "content": " \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n" }, { "path": "src/copaw/agents/skills/xlsx/scripts/office/schemas/microsoft/wml-2012.xsd", "content": " \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n" }, { "path": "src/copaw/agents/skills/xlsx/scripts/office/schemas/microsoft/wml-2018.xsd", "content": " \n \n \n \n \n \n \n \n \n \n \n \n \n \n" }, { "path": "src/copaw/agents/skills/xlsx/scripts/office/schemas/microsoft/wml-cex-2018.xsd", "content": " \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n" }, { "path": "src/copaw/agents/skills/xlsx/scripts/office/schemas/microsoft/wml-cid-2016.xsd", "content": " \n \n \n \n \n \n \n \n \n \n \n \n \n" }, { "path": "src/copaw/agents/skills/xlsx/scripts/office/schemas/microsoft/wml-sdtdatahash-2020.xsd", "content": " \n \n \n \n" }, { "path": "src/copaw/agents/skills/xlsx/scripts/office/schemas/microsoft/wml-symex-2015.xsd", "content": " \n \n \n \n \n \n \n \n" }, { "path": "src/copaw/agents/skills/xlsx/scripts/office/soffice.py", "content": "\"\"\"\nHelper for running LibreOffice (soffice) in environments where AF_UNIX\nsockets may be blocked (e.g., sandboxed VMs). Detects the restriction\nat runtime and applies an LD_PRELOAD shim if needed.\n\nUsage:\n from office.soffice import run_soffice, get_soffice_cmd, get_soffice_env\n\n # Option 1 – run soffice directly\n result = run_soffice([\"--headless\", \"--convert-to\", \"pdf\", \"input.docx\"])\n\n # Option 2 – get env dict for your own subprocess calls\n env = get_soffice_env()\n subprocess.run([get_soffice_cmd(), ...], env=env)\n\"\"\"\n\nimport os\nimport platform\nimport shutil\nimport socket\nimport subprocess\nimport tempfile\nfrom pathlib import Path\n\n\ndef get_soffice_cmd() -> str:\n \"\"\"Return the soffice command name for the current platform.\"\"\"\n # Prefer PATH first on all platforms.\n path_cmd = shutil.which(\"soffice\")\n if path_cmd:\n return path_cmd\n\n if platform.system() == \"Windows\":\n # Windows can expose soffice as .com or .exe; try both on PATH first.\n for candidate_name in (\"soffice.com\", \"soffice.exe\"):\n path_candidate = shutil.which(candidate_name)\n if path_candidate:\n return path_candidate\n\n for prog_dir in (\n os.environ.get(\"PROGRAMFILES\", r\"C:\\Program Files\"),\n os.environ.get(\"PROGRAMFILES(X86)\", r\"C:\\Program Files (x86)\"),\n ):\n if not prog_dir:\n continue\n program_dir = Path(prog_dir) / \"LibreOffice\" / \"program\"\n for exe_name in (\"soffice.com\", \"soffice.exe\"):\n candidate = program_dir / exe_name\n if candidate.exists():\n return str(candidate)\n return \"soffice\"\n return \"soffice\"\n\n\ndef get_soffice_env() -> dict:\n env = os.environ.copy()\n if platform.system() == \"Linux\":\n env[\"SAL_USE_VCLPLUGIN\"] = \"svp\"\n\n if _needs_shim():\n shim = _ensure_shim()\n env[\"LD_PRELOAD\"] = str(shim)\n\n return env\n\n\ndef run_soffice(args: list[str], **kwargs) -> subprocess.CompletedProcess:\n env = get_soffice_env()\n return subprocess.run([get_soffice_cmd()] + args, env=env, **kwargs)\n\n\n\n_SHIM_SO = Path(tempfile.gettempdir()) / \"lo_socket_shim.so\"\n\n\ndef _needs_shim() -> bool:\n # AF_UNIX / LD_PRELOAD shim is Linux-only; skip on Windows and macOS\n if not hasattr(socket, \"AF_UNIX\"):\n return False\n try:\n s = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)\n s.close()\n return False\n except OSError:\n return True\n\n\ndef _ensure_shim() -> Path:\n if _SHIM_SO.exists():\n return _SHIM_SO\n\n src = Path(tempfile.gettempdir()) / \"lo_socket_shim.c\"\n src.write_text(_SHIM_SOURCE)\n subprocess.run(\n [\"gcc\", \"-shared\", \"-fPIC\", \"-o\", str(_SHIM_SO), str(src), \"-ldl\"],\n check=True,\n capture_output=True,\n )\n src.unlink()\n return _SHIM_SO\n\n\n\n_SHIM_SOURCE = r\"\"\"\n#define _GNU_SOURCE\n#include \n#include \n#include \n#include \n#include \n#include \n#include \n\nstatic int (*real_socket)(int, int, int);\nstatic int (*real_socketpair)(int, int, int, int[2]);\nstatic int (*real_listen)(int, int);\nstatic int (*real_accept)(int, struct sockaddr *, socklen_t *);\nstatic int (*real_close)(int);\nstatic int (*real_read)(int, void *, size_t);\n\n/* Per-FD bookkeeping (FDs >= 1024 are passed through unshimmed). */\nstatic int is_shimmed[1024];\nstatic int peer_of[1024];\nstatic int wake_r[1024]; /* accept() blocks reading this */\nstatic int wake_w[1024]; /* close() writes to this */\nstatic int listener_fd = -1; /* FD that received listen() */\n\n__attribute__((constructor))\nstatic void init(void) {\n real_socket = dlsym(RTLD_NEXT, \"socket\");\n real_socketpair = dlsym(RTLD_NEXT, \"socketpair\");\n real_listen = dlsym(RTLD_NEXT, \"listen\");\n real_accept = dlsym(RTLD_NEXT, \"accept\");\n real_close = dlsym(RTLD_NEXT, \"close\");\n real_read = dlsym(RTLD_NEXT, \"read\");\n for (int i = 0; i < 1024; i++) {\n peer_of[i] = -1;\n wake_r[i] = -1;\n wake_w[i] = -1;\n }\n}\n\n/* ---- socket ---------------------------------------------------------- */\nint socket(int domain, int type, int protocol) {\n if (domain == AF_UNIX) {\n int fd = real_socket(domain, type, protocol);\n if (fd >= 0) return fd;\n /* socket(AF_UNIX) blocked – fall back to socketpair(). */\n int sv[2];\n if (real_socketpair(domain, type, protocol, sv) == 0) {\n if (sv[0] >= 0 && sv[0] < 1024) {\n is_shimmed[sv[0]] = 1;\n peer_of[sv[0]] = sv[1];\n int wp[2];\n if (pipe(wp) == 0) {\n wake_r[sv[0]] = wp[0];\n wake_w[sv[0]] = wp[1];\n }\n }\n return sv[0];\n }\n errno = EPERM;\n return -1;\n }\n return real_socket(domain, type, protocol);\n}\n\n/* ---- listen ---------------------------------------------------------- */\nint listen(int sockfd, int backlog) {\n if (sockfd >= 0 && sockfd < 1024 && is_shimmed[sockfd]) {\n listener_fd = sockfd;\n return 0;\n }\n return real_listen(sockfd, backlog);\n}\n\n/* ---- accept ---------------------------------------------------------- */\nint accept(int sockfd, struct sockaddr *addr, socklen_t *addrlen) {\n if (sockfd >= 0 && sockfd < 1024 && is_shimmed[sockfd]) {\n /* Block until close() writes to the wake pipe. */\n if (wake_r[sockfd] >= 0) {\n char buf;\n real_read(wake_r[sockfd], &buf, 1);\n }\n errno = ECONNABORTED;\n return -1;\n }\n return real_accept(sockfd, addr, addrlen);\n}\n\n/* ---- close ----------------------------------------------------------- */\nint close(int fd) {\n if (fd >= 0 && fd < 1024 && is_shimmed[fd]) {\n int was_listener = (fd == listener_fd);\n is_shimmed[fd] = 0;\n\n if (wake_w[fd] >= 0) { /* unblock accept() */\n char c = 0;\n write(wake_w[fd], &c, 1);\n real_close(wake_w[fd]);\n wake_w[fd] = -1;\n }\n if (wake_r[fd] >= 0) { real_close(wake_r[fd]); wake_r[fd] = -1; }\n if (peer_of[fd] >= 0) { real_close(peer_of[fd]); peer_of[fd] = -1; }\n\n if (was_listener)\n _exit(0); /* conversion done – exit */\n }\n return real_close(fd);\n}\n\"\"\"\n\n\n\nif __name__ == \"__main__\":\n import sys\n result = run_soffice(sys.argv[1:])\n sys.exit(result.returncode)\n" }, { "path": "src/copaw/agents/skills/xlsx/scripts/office/unpack.py", "content": "\"\"\"Unpack Office files (DOCX, PPTX, XLSX) for editing.\n\nExtracts the ZIP archive, pretty-prints XML files, and optionally:\n- Merges adjacent runs with identical formatting (DOCX only)\n- Simplifies adjacent tracked changes from same author (DOCX only)\n\nUsage:\n python unpack.py [options]\n\nExamples:\n python unpack.py document.docx unpacked/\n python unpack.py presentation.pptx unpacked/\n python unpack.py document.docx unpacked/ --merge-runs false\n\"\"\"\n\nimport argparse\nimport sys\nimport zipfile\nfrom pathlib import Path\n\nimport defusedxml.minidom\n\nfrom helpers.merge_runs import merge_runs as do_merge_runs\nfrom helpers.simplify_redlines import simplify_redlines as do_simplify_redlines\n\nSMART_QUOTE_REPLACEMENTS = {\n \"\\u201c\": \"“\", \n \"\\u201d\": \"”\", \n \"\\u2018\": \"‘\", \n \"\\u2019\": \"’\", \n}\n\n\ndef unpack(\n input_file: str,\n output_directory: str,\n merge_runs: bool = True,\n simplify_redlines: bool = True,\n) -> tuple[None, str]:\n input_path = Path(input_file)\n output_path = Path(output_directory)\n suffix = input_path.suffix.lower()\n\n if not input_path.exists():\n return None, f\"Error: {input_file} does not exist\"\n\n if suffix not in {\".docx\", \".pptx\", \".xlsx\"}:\n return None, f\"Error: {input_file} must be a .docx, .pptx, or .xlsx file\"\n\n try:\n output_path.mkdir(parents=True, exist_ok=True)\n\n with zipfile.ZipFile(input_path, \"r\") as zf:\n zf.extractall(output_path)\n\n xml_files = list(output_path.rglob(\"*.xml\")) + list(output_path.rglob(\"*.rels\"))\n for xml_file in xml_files:\n _pretty_print_xml(xml_file)\n\n message = f\"Unpacked {input_file} ({len(xml_files)} XML files)\"\n\n if suffix == \".docx\":\n if simplify_redlines:\n simplify_count, _ = do_simplify_redlines(str(output_path))\n message += f\", simplified {simplify_count} tracked changes\"\n\n if merge_runs:\n merge_count, _ = do_merge_runs(str(output_path))\n message += f\", merged {merge_count} runs\"\n\n for xml_file in xml_files:\n _escape_smart_quotes(xml_file)\n\n return None, message\n\n except zipfile.BadZipFile:\n return None, f\"Error: {input_file} is not a valid Office file\"\n except Exception as e:\n return None, f\"Error unpacking: {e}\"\n\n\ndef _pretty_print_xml(xml_file: Path) -> None:\n try:\n content = xml_file.read_text(encoding=\"utf-8\")\n dom = defusedxml.minidom.parseString(content)\n xml_file.write_bytes(dom.toprettyxml(indent=\" \", encoding=\"utf-8\"))\n except Exception:\n pass \n\n\ndef _escape_smart_quotes(xml_file: Path) -> None:\n try:\n content = xml_file.read_text(encoding=\"utf-8\")\n for char, entity in SMART_QUOTE_REPLACEMENTS.items():\n content = content.replace(char, entity)\n xml_file.write_text(content, encoding=\"utf-8\")\n except Exception:\n pass\n\n\nif __name__ == \"__main__\":\n parser = argparse.ArgumentParser(\n description=\"Unpack an Office file (DOCX, PPTX, XLSX) for editing\"\n )\n parser.add_argument(\"input_file\", help=\"Office file to unpack\")\n parser.add_argument(\"output_directory\", help=\"Output directory\")\n parser.add_argument(\n \"--merge-runs\",\n type=lambda x: x.lower() == \"true\",\n default=True,\n metavar=\"true|false\",\n help=\"Merge adjacent runs with identical formatting (DOCX only, default: true)\",\n )\n parser.add_argument(\n \"--simplify-redlines\",\n type=lambda x: x.lower() == \"true\",\n default=True,\n metavar=\"true|false\",\n help=\"Merge adjacent tracked changes from same author (DOCX only, default: true)\",\n )\n args = parser.parse_args()\n\n _, message = unpack(\n args.input_file,\n args.output_directory,\n merge_runs=args.merge_runs,\n simplify_redlines=args.simplify_redlines,\n )\n print(message)\n\n if \"Error\" in message:\n sys.exit(1)\n" }, { "path": "src/copaw/agents/skills/xlsx/scripts/office/validate.py", "content": "\"\"\"\nCommand line tool to validate Office document XML files against XSD schemas and tracked changes.\n\nUsage:\n python validate.py [--original ] [--auto-repair] [--author NAME]\n\nThe first argument can be either:\n- An unpacked directory containing the Office document XML files\n- A packed Office file (.docx/.pptx/.xlsx) which will be unpacked to a temp directory\n\nAuto-repair fixes:\n- paraId/durableId values that exceed OOXML limits\n- Missing xml:space=\"preserve\" on w:t elements with whitespace\n\"\"\"\n\nimport argparse\nimport sys\nimport tempfile\nimport zipfile\nfrom pathlib import Path\n\nfrom validators import DOCXSchemaValidator, PPTXSchemaValidator, RedliningValidator\n\n\ndef main():\n parser = argparse.ArgumentParser(description=\"Validate Office document XML files\")\n parser.add_argument(\n \"path\",\n help=\"Path to unpacked directory or packed Office file (.docx/.pptx/.xlsx)\",\n )\n parser.add_argument(\n \"--original\",\n required=False,\n default=None,\n help=\"Path to original file (.docx/.pptx/.xlsx). If omitted, all XSD errors are reported and redlining validation is skipped.\",\n )\n parser.add_argument(\n \"-v\",\n \"--verbose\",\n action=\"store_true\",\n help=\"Enable verbose output\",\n )\n parser.add_argument(\n \"--auto-repair\",\n action=\"store_true\",\n help=\"Automatically repair common issues (hex IDs, whitespace preservation)\",\n )\n parser.add_argument(\n \"--author\",\n default=\"Claude\",\n help=\"Author name for redlining validation (default: Claude)\",\n )\n args = parser.parse_args()\n\n path = Path(args.path)\n assert path.exists(), f\"Error: {path} does not exist\"\n\n original_file = None\n if args.original:\n original_file = Path(args.original)\n assert original_file.is_file(), f\"Error: {original_file} is not a file\"\n assert original_file.suffix.lower() in [\".docx\", \".pptx\", \".xlsx\"], (\n f\"Error: {original_file} must be a .docx, .pptx, or .xlsx file\"\n )\n\n file_extension = (original_file or path).suffix.lower()\n assert file_extension in [\".docx\", \".pptx\", \".xlsx\"], (\n f\"Error: Cannot determine file type from {path}. Use --original or provide a .docx/.pptx/.xlsx file.\"\n )\n\n if path.is_file() and path.suffix.lower() in [\".docx\", \".pptx\", \".xlsx\"]:\n temp_dir = tempfile.mkdtemp()\n with zipfile.ZipFile(path, \"r\") as zf:\n zf.extractall(temp_dir)\n unpacked_dir = Path(temp_dir)\n else:\n assert path.is_dir(), f\"Error: {path} is not a directory or Office file\"\n unpacked_dir = path\n\n match file_extension:\n case \".docx\":\n validators = [\n DOCXSchemaValidator(unpacked_dir, original_file, verbose=args.verbose),\n ]\n if original_file:\n validators.append(\n RedliningValidator(unpacked_dir, original_file, verbose=args.verbose, author=args.author) \n )\n case \".pptx\":\n validators = [\n PPTXSchemaValidator(unpacked_dir, original_file, verbose=args.verbose),\n ]\n case _:\n print(f\"Error: Validation not supported for file type {file_extension}\")\n sys.exit(1)\n\n if args.auto_repair:\n total_repairs = sum(v.repair() for v in validators)\n if total_repairs:\n print(f\"Auto-repaired {total_repairs} issue(s)\")\n\n success = all(v.validate() for v in validators)\n\n if success:\n print(\"All validations PASSED!\")\n\n sys.exit(0 if success else 1)\n\n\nif __name__ == \"__main__\":\n main()\n" }, { "path": "src/copaw/agents/skills/xlsx/scripts/office/validators/__init__.py", "content": "\"\"\"\nValidation modules for Word document processing.\n\"\"\"\n\nfrom .base import BaseSchemaValidator\nfrom .docx import DOCXSchemaValidator\nfrom .pptx import PPTXSchemaValidator\nfrom .redlining import RedliningValidator\n\n__all__ = [\n \"BaseSchemaValidator\",\n \"DOCXSchemaValidator\",\n \"PPTXSchemaValidator\",\n \"RedliningValidator\",\n]\n" }, { "path": "src/copaw/agents/skills/xlsx/scripts/office/validators/base.py", "content": "\"\"\"\nBase validator with common validation logic for document files.\n\"\"\"\n\nimport re\nfrom pathlib import Path\n\nimport defusedxml.minidom\nimport lxml.etree\n\n\nclass BaseSchemaValidator:\n\n IGNORED_VALIDATION_ERRORS = [\n \"hyphenationZone\",\n \"purl.org/dc/terms\",\n ]\n\n UNIQUE_ID_REQUIREMENTS = {\n \"comment\": (\"id\", \"file\"), \n \"commentrangestart\": (\"id\", \"file\"), \n \"commentrangeend\": (\"id\", \"file\"), \n \"bookmarkstart\": (\"id\", \"file\"), \n \"bookmarkend\": (\"id\", \"file\"), \n \"sldid\": (\"id\", \"file\"), \n \"sldmasterid\": (\"id\", \"global\"), \n \"sldlayoutid\": (\"id\", \"global\"), \n \"cm\": (\"authorid\", \"file\"), \n \"sheet\": (\"sheetid\", \"file\"), \n \"definedname\": (\"id\", \"file\"), \n \"cxnsp\": (\"id\", \"file\"), \n \"sp\": (\"id\", \"file\"), \n \"pic\": (\"id\", \"file\"), \n \"grpsp\": (\"id\", \"file\"), \n }\n\n EXCLUDED_ID_CONTAINERS = {\n \"sectionlst\", \n }\n\n ELEMENT_RELATIONSHIP_TYPES = {}\n\n SCHEMA_MAPPINGS = {\n \"word\": \"ISO-IEC29500-4_2016/wml.xsd\", \n \"ppt\": \"ISO-IEC29500-4_2016/pml.xsd\", \n \"xl\": \"ISO-IEC29500-4_2016/sml.xsd\", \n \"[Content_Types].xml\": \"ecma/fouth-edition/opc-contentTypes.xsd\",\n \"app.xml\": \"ISO-IEC29500-4_2016/shared-documentPropertiesExtended.xsd\",\n \"core.xml\": \"ecma/fouth-edition/opc-coreProperties.xsd\",\n \"custom.xml\": \"ISO-IEC29500-4_2016/shared-documentPropertiesCustom.xsd\",\n \".rels\": \"ecma/fouth-edition/opc-relationships.xsd\",\n \"people.xml\": \"microsoft/wml-2012.xsd\",\n \"commentsIds.xml\": \"microsoft/wml-cid-2016.xsd\",\n \"commentsExtensible.xml\": \"microsoft/wml-cex-2018.xsd\",\n \"commentsExtended.xml\": \"microsoft/wml-2012.xsd\",\n \"chart\": \"ISO-IEC29500-4_2016/dml-chart.xsd\",\n \"theme\": \"ISO-IEC29500-4_2016/dml-main.xsd\",\n \"drawing\": \"ISO-IEC29500-4_2016/dml-main.xsd\",\n }\n\n MC_NAMESPACE = \"http://schemas.openxmlformats.org/markup-compatibility/2006\"\n XML_NAMESPACE = \"http://www.w3.org/XML/1998/namespace\"\n\n PACKAGE_RELATIONSHIPS_NAMESPACE = (\n \"http://schemas.openxmlformats.org/package/2006/relationships\"\n )\n OFFICE_RELATIONSHIPS_NAMESPACE = (\n \"http://schemas.openxmlformats.org/officeDocument/2006/relationships\"\n )\n CONTENT_TYPES_NAMESPACE = (\n \"http://schemas.openxmlformats.org/package/2006/content-types\"\n )\n\n MAIN_CONTENT_FOLDERS = {\"word\", \"ppt\", \"xl\"}\n\n OOXML_NAMESPACES = {\n \"http://schemas.openxmlformats.org/officeDocument/2006/math\",\n \"http://schemas.openxmlformats.org/officeDocument/2006/relationships\",\n \"http://schemas.openxmlformats.org/schemaLibrary/2006/main\",\n \"http://schemas.openxmlformats.org/drawingml/2006/main\",\n \"http://schemas.openxmlformats.org/drawingml/2006/chart\",\n \"http://schemas.openxmlformats.org/drawingml/2006/chartDrawing\",\n \"http://schemas.openxmlformats.org/drawingml/2006/diagram\",\n \"http://schemas.openxmlformats.org/drawingml/2006/picture\",\n \"http://schemas.openxmlformats.org/drawingml/2006/spreadsheetDrawing\",\n \"http://schemas.openxmlformats.org/drawingml/2006/wordprocessingDrawing\",\n \"http://schemas.openxmlformats.org/wordprocessingml/2006/main\",\n \"http://schemas.openxmlformats.org/presentationml/2006/main\",\n \"http://schemas.openxmlformats.org/spreadsheetml/2006/main\",\n \"http://schemas.openxmlformats.org/officeDocument/2006/sharedTypes\",\n \"http://www.w3.org/XML/1998/namespace\",\n }\n\n def __init__(self, unpacked_dir, original_file=None, verbose=False):\n self.unpacked_dir = Path(unpacked_dir).resolve()\n self.original_file = Path(original_file) if original_file else None\n self.verbose = verbose\n\n self.schemas_dir = Path(__file__).parent.parent / \"schemas\"\n\n patterns = [\"*.xml\", \"*.rels\"]\n self.xml_files = [\n f for pattern in patterns for f in self.unpacked_dir.rglob(pattern)\n ]\n\n if not self.xml_files:\n print(f\"Warning: No XML files found in {self.unpacked_dir}\")\n\n def validate(self):\n raise NotImplementedError(\"Subclasses must implement the validate method\")\n\n def repair(self) -> int:\n return self.repair_whitespace_preservation()\n\n def repair_whitespace_preservation(self) -> int:\n repairs = 0\n\n for xml_file in self.xml_files:\n try:\n content = xml_file.read_text(encoding=\"utf-8\")\n dom = defusedxml.minidom.parseString(content)\n modified = False\n\n for elem in dom.getElementsByTagName(\"*\"):\n if elem.tagName.endswith(\":t\") and elem.firstChild:\n text = elem.firstChild.nodeValue\n if text and (text.startswith((' ', '\\t')) or text.endswith((' ', '\\t'))):\n if elem.getAttribute(\"xml:space\") != \"preserve\":\n elem.setAttribute(\"xml:space\", \"preserve\")\n text_preview = repr(text[:30]) + \"...\" if len(text) > 30 else repr(text)\n print(f\" Repaired: {xml_file.name}: Added xml:space='preserve' to {elem.tagName}: {text_preview}\")\n repairs += 1\n modified = True\n\n if modified:\n xml_file.write_bytes(dom.toxml(encoding=\"UTF-8\"))\n\n except Exception:\n pass\n\n return repairs\n\n def validate_xml(self):\n errors = []\n\n for xml_file in self.xml_files:\n try:\n lxml.etree.parse(str(xml_file))\n except lxml.etree.XMLSyntaxError as e:\n errors.append(\n f\" {xml_file.relative_to(self.unpacked_dir)}: \"\n f\"Line {e.lineno}: {e.msg}\"\n )\n except Exception as e:\n errors.append(\n f\" {xml_file.relative_to(self.unpacked_dir)}: \"\n f\"Unexpected error: {str(e)}\"\n )\n\n if errors:\n print(f\"FAILED - Found {len(errors)} XML violations:\")\n for error in errors:\n print(error)\n return False\n else:\n if self.verbose:\n print(\"PASSED - All XML files are well-formed\")\n return True\n\n def validate_namespaces(self):\n errors = []\n\n for xml_file in self.xml_files:\n try:\n root = lxml.etree.parse(str(xml_file)).getroot()\n declared = set(root.nsmap.keys()) - {None} \n\n for attr_val in [\n v for k, v in root.attrib.items() if k.endswith(\"Ignorable\")\n ]:\n undeclared = set(attr_val.split()) - declared\n errors.extend(\n f\" {xml_file.relative_to(self.unpacked_dir)}: \"\n f\"Namespace '{ns}' in Ignorable but not declared\"\n for ns in undeclared\n )\n except lxml.etree.XMLSyntaxError:\n continue\n\n if errors:\n print(f\"FAILED - {len(errors)} namespace issues:\")\n for error in errors:\n print(error)\n return False\n if self.verbose:\n print(\"PASSED - All namespace prefixes properly declared\")\n return True\n\n def validate_unique_ids(self):\n errors = []\n global_ids = {} \n\n for xml_file in self.xml_files:\n try:\n root = lxml.etree.parse(str(xml_file)).getroot()\n file_ids = {} \n\n mc_elements = root.xpath(\n \".//mc:AlternateContent\", namespaces={\"mc\": self.MC_NAMESPACE}\n )\n for elem in mc_elements:\n elem.getparent().remove(elem)\n\n for elem in root.iter():\n tag = (\n elem.tag.split(\"}\")[-1].lower()\n if \"}\" in elem.tag\n else elem.tag.lower()\n )\n\n if tag in self.UNIQUE_ID_REQUIREMENTS:\n in_excluded_container = any(\n ancestor.tag.split(\"}\")[-1].lower() in self.EXCLUDED_ID_CONTAINERS\n for ancestor in elem.iterancestors()\n )\n if in_excluded_container:\n continue\n\n attr_name, scope = self.UNIQUE_ID_REQUIREMENTS[tag]\n\n id_value = None\n for attr, value in elem.attrib.items():\n attr_local = (\n attr.split(\"}\")[-1].lower()\n if \"}\" in attr\n else attr.lower()\n )\n if attr_local == attr_name:\n id_value = value\n break\n\n if id_value is not None:\n if scope == \"global\":\n if id_value in global_ids:\n prev_file, prev_line, prev_tag = global_ids[\n id_value\n ]\n errors.append(\n f\" {xml_file.relative_to(self.unpacked_dir)}: \"\n f\"Line {elem.sourceline}: Global ID '{id_value}' in <{tag}> \"\n f\"already used in {prev_file} at line {prev_line} in <{prev_tag}>\"\n )\n else:\n global_ids[id_value] = (\n xml_file.relative_to(self.unpacked_dir),\n elem.sourceline,\n tag,\n )\n elif scope == \"file\":\n key = (tag, attr_name)\n if key not in file_ids:\n file_ids[key] = {}\n\n if id_value in file_ids[key]:\n prev_line = file_ids[key][id_value]\n errors.append(\n f\" {xml_file.relative_to(self.unpacked_dir)}: \"\n f\"Line {elem.sourceline}: Duplicate {attr_name}='{id_value}' in <{tag}> \"\n f\"(first occurrence at line {prev_line})\"\n )\n else:\n file_ids[key][id_value] = elem.sourceline\n\n except (lxml.etree.XMLSyntaxError, Exception) as e:\n errors.append(\n f\" {xml_file.relative_to(self.unpacked_dir)}: Error: {e}\"\n )\n\n if errors:\n print(f\"FAILED - Found {len(errors)} ID uniqueness violations:\")\n for error in errors:\n print(error)\n return False\n else:\n if self.verbose:\n print(\"PASSED - All required IDs are unique\")\n return True\n\n def validate_file_references(self):\n errors = []\n\n rels_files = list(self.unpacked_dir.rglob(\"*.rels\"))\n\n if not rels_files:\n if self.verbose:\n print(\"PASSED - No .rels files found\")\n return True\n\n all_files = []\n for file_path in self.unpacked_dir.rglob(\"*\"):\n if (\n file_path.is_file()\n and file_path.name != \"[Content_Types].xml\"\n and not file_path.name.endswith(\".rels\")\n ): \n all_files.append(file_path.resolve())\n\n all_referenced_files = set()\n\n if self.verbose:\n print(\n f\"Found {len(rels_files)} .rels files and {len(all_files)} target files\"\n )\n\n for rels_file in rels_files:\n try:\n rels_root = lxml.etree.parse(str(rels_file)).getroot()\n\n rels_dir = rels_file.parent\n\n referenced_files = set()\n broken_refs = []\n\n for rel in rels_root.findall(\n \".//ns:Relationship\",\n namespaces={\"ns\": self.PACKAGE_RELATIONSHIPS_NAMESPACE},\n ):\n target = rel.get(\"Target\")\n if target and not target.startswith(\n (\"http\", \"mailto:\")\n ): \n if target.startswith(\"/\"):\n target_path = self.unpacked_dir / target.lstrip(\"/\")\n elif rels_file.name == \".rels\":\n target_path = self.unpacked_dir / target\n else:\n base_dir = rels_dir.parent\n target_path = base_dir / target\n\n try:\n target_path = target_path.resolve()\n if target_path.exists() and target_path.is_file():\n referenced_files.add(target_path)\n all_referenced_files.add(target_path)\n else:\n broken_refs.append((target, rel.sourceline))\n except (OSError, ValueError):\n broken_refs.append((target, rel.sourceline))\n\n if broken_refs:\n rel_path = rels_file.relative_to(self.unpacked_dir)\n for broken_ref, line_num in broken_refs:\n errors.append(\n f\" {rel_path}: Line {line_num}: Broken reference to {broken_ref}\"\n )\n\n except Exception as e:\n rel_path = rels_file.relative_to(self.unpacked_dir)\n errors.append(f\" Error parsing {rel_path}: {e}\")\n\n unreferenced_files = set(all_files) - all_referenced_files\n\n if unreferenced_files:\n for unref_file in sorted(unreferenced_files):\n unref_rel_path = unref_file.relative_to(self.unpacked_dir)\n errors.append(f\" Unreferenced file: {unref_rel_path}\")\n\n if errors:\n print(f\"FAILED - Found {len(errors)} relationship validation errors:\")\n for error in errors:\n print(error)\n print(\n \"CRITICAL: These errors will cause the document to appear corrupt. \"\n + \"Broken references MUST be fixed, \"\n + \"and unreferenced files MUST be referenced or removed.\"\n )\n return False\n else:\n if self.verbose:\n print(\n \"PASSED - All references are valid and all files are properly referenced\"\n )\n return True\n\n def validate_all_relationship_ids(self):\n import lxml.etree\n\n errors = []\n\n for xml_file in self.xml_files:\n if xml_file.suffix == \".rels\":\n continue\n\n rels_dir = xml_file.parent / \"_rels\"\n rels_file = rels_dir / f\"{xml_file.name}.rels\"\n\n if not rels_file.exists():\n continue\n\n try:\n rels_root = lxml.etree.parse(str(rels_file)).getroot()\n rid_to_type = {}\n\n for rel in rels_root.findall(\n f\".//{{{self.PACKAGE_RELATIONSHIPS_NAMESPACE}}}Relationship\"\n ):\n rid = rel.get(\"Id\")\n rel_type = rel.get(\"Type\", \"\")\n if rid:\n if rid in rid_to_type:\n rels_rel_path = rels_file.relative_to(self.unpacked_dir)\n errors.append(\n f\" {rels_rel_path}: Line {rel.sourceline}: \"\n f\"Duplicate relationship ID '{rid}' (IDs must be unique)\"\n )\n type_name = (\n rel_type.split(\"/\")[-1] if \"/\" in rel_type else rel_type\n )\n rid_to_type[rid] = type_name\n\n xml_root = lxml.etree.parse(str(xml_file)).getroot()\n\n r_ns = self.OFFICE_RELATIONSHIPS_NAMESPACE\n rid_attrs_to_check = [\"id\", \"embed\", \"link\"]\n for elem in xml_root.iter():\n for attr_name in rid_attrs_to_check:\n rid_attr = elem.get(f\"{{{r_ns}}}{attr_name}\")\n if not rid_attr:\n continue\n xml_rel_path = xml_file.relative_to(self.unpacked_dir)\n elem_name = (\n elem.tag.split(\"}\")[-1] if \"}\" in elem.tag else elem.tag\n )\n\n if rid_attr not in rid_to_type:\n errors.append(\n f\" {xml_rel_path}: Line {elem.sourceline}: \"\n f\"<{elem_name}> r:{attr_name} references non-existent relationship '{rid_attr}' \"\n f\"(valid IDs: {', '.join(sorted(rid_to_type.keys())[:5])}{'...' if len(rid_to_type) > 5 else ''})\"\n )\n elif attr_name == \"id\" and self.ELEMENT_RELATIONSHIP_TYPES:\n expected_type = self._get_expected_relationship_type(\n elem_name\n )\n if expected_type:\n actual_type = rid_to_type[rid_attr]\n if expected_type not in actual_type.lower():\n errors.append(\n f\" {xml_rel_path}: Line {elem.sourceline}: \"\n f\"<{elem_name}> references '{rid_attr}' which points to '{actual_type}' \"\n f\"but should point to a '{expected_type}' relationship\"\n )\n\n except Exception as e:\n xml_rel_path = xml_file.relative_to(self.unpacked_dir)\n errors.append(f\" Error processing {xml_rel_path}: {e}\")\n\n if errors:\n print(f\"FAILED - Found {len(errors)} relationship ID reference errors:\")\n for error in errors:\n print(error)\n print(\"\\nThese ID mismatches will cause the document to appear corrupt!\")\n return False\n else:\n if self.verbose:\n print(\"PASSED - All relationship ID references are valid\")\n return True\n\n def _get_expected_relationship_type(self, element_name):\n elem_lower = element_name.lower()\n\n if elem_lower in self.ELEMENT_RELATIONSHIP_TYPES:\n return self.ELEMENT_RELATIONSHIP_TYPES[elem_lower]\n\n if elem_lower.endswith(\"id\") and len(elem_lower) > 2:\n prefix = elem_lower[:-2] \n if prefix.endswith(\"master\"):\n return prefix.lower()\n elif prefix.endswith(\"layout\"):\n return prefix.lower()\n else:\n if prefix == \"sld\":\n return \"slide\"\n return prefix.lower()\n\n if elem_lower.endswith(\"reference\") and len(elem_lower) > 9:\n prefix = elem_lower[:-9] \n return prefix.lower()\n\n return None\n\n def validate_content_types(self):\n errors = []\n\n content_types_file = self.unpacked_dir / \"[Content_Types].xml\"\n if not content_types_file.exists():\n print(\"FAILED - [Content_Types].xml file not found\")\n return False\n\n try:\n root = lxml.etree.parse(str(content_types_file)).getroot()\n declared_parts = set()\n declared_extensions = set()\n\n for override in root.findall(\n f\".//{{{self.CONTENT_TYPES_NAMESPACE}}}Override\"\n ):\n part_name = override.get(\"PartName\")\n if part_name is not None:\n declared_parts.add(part_name.lstrip(\"/\"))\n\n for default in root.findall(\n f\".//{{{self.CONTENT_TYPES_NAMESPACE}}}Default\"\n ):\n extension = default.get(\"Extension\")\n if extension is not None:\n declared_extensions.add(extension.lower())\n\n declarable_roots = {\n \"sld\",\n \"sldLayout\",\n \"sldMaster\",\n \"presentation\", \n \"document\", \n \"workbook\",\n \"worksheet\", \n \"theme\", \n }\n\n media_extensions = {\n \"png\": \"image/png\",\n \"jpg\": \"image/jpeg\",\n \"jpeg\": \"image/jpeg\",\n \"gif\": \"image/gif\",\n \"bmp\": \"image/bmp\",\n \"tiff\": \"image/tiff\",\n \"wmf\": \"image/x-wmf\",\n \"emf\": \"image/x-emf\",\n }\n\n all_files = list(self.unpacked_dir.rglob(\"*\"))\n all_files = [f for f in all_files if f.is_file()]\n\n for xml_file in self.xml_files:\n path_str = str(xml_file.relative_to(self.unpacked_dir)).replace(\n \"\\\\\", \"/\"\n )\n\n if any(\n skip in path_str\n for skip in [\".rels\", \"[Content_Types]\", \"docProps/\", \"_rels/\"]\n ):\n continue\n\n try:\n root_tag = lxml.etree.parse(str(xml_file)).getroot().tag\n root_name = root_tag.split(\"}\")[-1] if \"}\" in root_tag else root_tag\n\n if root_name in declarable_roots and path_str not in declared_parts:\n errors.append(\n f\" {path_str}: File with <{root_name}> root not declared in [Content_Types].xml\"\n )\n\n except Exception:\n continue \n\n for file_path in all_files:\n if file_path.suffix.lower() in {\".xml\", \".rels\"}:\n continue\n if file_path.name == \"[Content_Types].xml\":\n continue\n if \"_rels\" in file_path.parts or \"docProps\" in file_path.parts:\n continue\n\n extension = file_path.suffix.lstrip(\".\").lower()\n if extension and extension not in declared_extensions:\n if extension in media_extensions:\n relative_path = file_path.relative_to(self.unpacked_dir)\n errors.append(\n f' {relative_path}: File with extension \\'{extension}\\' not declared in [Content_Types].xml - should add: '\n )\n\n except Exception as e:\n errors.append(f\" Error parsing [Content_Types].xml: {e}\")\n\n if errors:\n print(f\"FAILED - Found {len(errors)} content type declaration errors:\")\n for error in errors:\n print(error)\n return False\n else:\n if self.verbose:\n print(\n \"PASSED - All content files are properly declared in [Content_Types].xml\"\n )\n return True\n\n def validate_file_against_xsd(self, xml_file, verbose=False):\n xml_file = Path(xml_file).resolve()\n unpacked_dir = self.unpacked_dir.resolve()\n\n is_valid, current_errors = self._validate_single_file_xsd(\n xml_file, unpacked_dir\n )\n\n if is_valid is None:\n return None, set() \n elif is_valid:\n return True, set() \n\n original_errors = self._get_original_file_errors(xml_file)\n\n assert current_errors is not None\n new_errors = current_errors - original_errors\n\n new_errors = {\n e for e in new_errors\n if not any(pattern in e for pattern in self.IGNORED_VALIDATION_ERRORS)\n }\n\n if new_errors:\n if verbose:\n relative_path = xml_file.relative_to(unpacked_dir)\n print(f\"FAILED - {relative_path}: {len(new_errors)} new error(s)\")\n for error in list(new_errors)[:3]:\n truncated = error[:250] + \"...\" if len(error) > 250 else error\n print(f\" - {truncated}\")\n return False, new_errors\n else:\n if verbose:\n print(\n f\"PASSED - No new errors (original had {len(current_errors)} errors)\"\n )\n return True, set()\n\n def validate_against_xsd(self):\n new_errors = []\n original_error_count = 0\n valid_count = 0\n skipped_count = 0\n\n for xml_file in self.xml_files:\n relative_path = str(xml_file.relative_to(self.unpacked_dir))\n is_valid, new_file_errors = self.validate_file_against_xsd(\n xml_file, verbose=False\n )\n\n if is_valid is None:\n skipped_count += 1\n continue\n elif is_valid and not new_file_errors:\n valid_count += 1\n continue\n elif is_valid:\n original_error_count += 1\n valid_count += 1\n continue\n\n new_errors.append(f\" {relative_path}: {len(new_file_errors)} new error(s)\")\n for error in list(new_file_errors)[:3]: \n new_errors.append(\n f\" - {error[:250]}...\" if len(error) > 250 else f\" - {error}\"\n )\n\n if self.verbose:\n print(f\"Validated {len(self.xml_files)} files:\")\n print(f\" - Valid: {valid_count}\")\n print(f\" - Skipped (no schema): {skipped_count}\")\n if original_error_count:\n print(f\" - With original errors (ignored): {original_error_count}\")\n print(\n f\" - With NEW errors: {len(new_errors) > 0 and len([e for e in new_errors if not e.startswith(' ')]) or 0}\"\n )\n\n if new_errors:\n print(\"\\nFAILED - Found NEW validation errors:\")\n for error in new_errors:\n print(error)\n return False\n else:\n if self.verbose:\n print(\"\\nPASSED - No new XSD validation errors introduced\")\n return True\n\n def _get_schema_path(self, xml_file):\n if xml_file.name in self.SCHEMA_MAPPINGS:\n return self.schemas_dir / self.SCHEMA_MAPPINGS[xml_file.name]\n\n if xml_file.suffix == \".rels\":\n return self.schemas_dir / self.SCHEMA_MAPPINGS[\".rels\"]\n\n if \"charts/\" in str(xml_file) and xml_file.name.startswith(\"chart\"):\n return self.schemas_dir / self.SCHEMA_MAPPINGS[\"chart\"]\n\n if \"theme/\" in str(xml_file) and xml_file.name.startswith(\"theme\"):\n return self.schemas_dir / self.SCHEMA_MAPPINGS[\"theme\"]\n\n if xml_file.parent.name in self.MAIN_CONTENT_FOLDERS:\n return self.schemas_dir / self.SCHEMA_MAPPINGS[xml_file.parent.name]\n\n return None\n\n def _clean_ignorable_namespaces(self, xml_doc):\n xml_string = lxml.etree.tostring(xml_doc, encoding=\"unicode\")\n xml_copy = lxml.etree.fromstring(xml_string)\n\n for elem in xml_copy.iter():\n attrs_to_remove = []\n\n for attr in elem.attrib:\n if \"{\" in attr:\n ns = attr.split(\"}\")[0][1:]\n if ns not in self.OOXML_NAMESPACES:\n attrs_to_remove.append(attr)\n\n for attr in attrs_to_remove:\n del elem.attrib[attr]\n\n self._remove_ignorable_elements(xml_copy)\n\n return lxml.etree.ElementTree(xml_copy)\n\n def _remove_ignorable_elements(self, root):\n elements_to_remove = []\n\n for elem in list(root):\n if not hasattr(elem, \"tag\") or callable(elem.tag):\n continue\n\n tag_str = str(elem.tag)\n if tag_str.startswith(\"{\"):\n ns = tag_str.split(\"}\")[0][1:]\n if ns not in self.OOXML_NAMESPACES:\n elements_to_remove.append(elem)\n continue\n\n self._remove_ignorable_elements(elem)\n\n for elem in elements_to_remove:\n root.remove(elem)\n\n def _preprocess_for_mc_ignorable(self, xml_doc):\n root = xml_doc.getroot()\n\n if f\"{{{self.MC_NAMESPACE}}}Ignorable\" in root.attrib:\n del root.attrib[f\"{{{self.MC_NAMESPACE}}}Ignorable\"]\n\n return xml_doc\n\n def _validate_single_file_xsd(self, xml_file, base_path):\n schema_path = self._get_schema_path(xml_file)\n if not schema_path:\n return None, None \n\n try:\n with open(schema_path, \"rb\") as xsd_file:\n parser = lxml.etree.XMLParser()\n xsd_doc = lxml.etree.parse(\n xsd_file, parser=parser, base_url=str(schema_path)\n )\n schema = lxml.etree.XMLSchema(xsd_doc)\n\n with open(xml_file, \"r\") as f:\n xml_doc = lxml.etree.parse(f)\n\n xml_doc, _ = self._remove_template_tags_from_text_nodes(xml_doc)\n xml_doc = self._preprocess_for_mc_ignorable(xml_doc)\n\n relative_path = xml_file.relative_to(base_path)\n if (\n relative_path.parts\n and relative_path.parts[0] in self.MAIN_CONTENT_FOLDERS\n ):\n xml_doc = self._clean_ignorable_namespaces(xml_doc)\n\n if schema.validate(xml_doc):\n return True, set()\n else:\n errors = set()\n for error in schema.error_log:\n errors.add(error.message)\n return False, errors\n\n except Exception as e:\n return False, {str(e)}\n\n def _get_original_file_errors(self, xml_file):\n if self.original_file is None:\n return set()\n\n import tempfile\n import zipfile\n\n xml_file = Path(xml_file).resolve()\n unpacked_dir = self.unpacked_dir.resolve()\n relative_path = xml_file.relative_to(unpacked_dir)\n\n with tempfile.TemporaryDirectory() as temp_dir:\n temp_path = Path(temp_dir)\n\n with zipfile.ZipFile(self.original_file, \"r\") as zip_ref:\n zip_ref.extractall(temp_path)\n\n original_xml_file = temp_path / relative_path\n\n if not original_xml_file.exists():\n return set()\n\n is_valid, errors = self._validate_single_file_xsd(\n original_xml_file, temp_path\n )\n return errors if errors else set()\n\n def _remove_template_tags_from_text_nodes(self, xml_doc):\n warnings = []\n template_pattern = re.compile(r\"\\{\\{[^}]*\\}\\}\")\n\n xml_string = lxml.etree.tostring(xml_doc, encoding=\"unicode\")\n xml_copy = lxml.etree.fromstring(xml_string)\n\n def process_text_content(text, content_type):\n if not text:\n return text\n matches = list(template_pattern.finditer(text))\n if matches:\n for match in matches:\n warnings.append(\n f\"Found template tag in {content_type}: {match.group()}\"\n )\n return template_pattern.sub(\"\", text)\n return text\n\n for elem in xml_copy.iter():\n if not hasattr(elem, \"tag\") or callable(elem.tag):\n continue\n tag_str = str(elem.tag)\n if tag_str.endswith(\"}t\") or tag_str == \"t\":\n continue\n\n elem.text = process_text_content(elem.text, \"text content\")\n elem.tail = process_text_content(elem.tail, \"tail content\")\n\n return lxml.etree.ElementTree(xml_copy), warnings\n\n\nif __name__ == \"__main__\":\n raise RuntimeError(\"This module should not be run directly.\")\n" }, { "path": "src/copaw/agents/skills/xlsx/scripts/office/validators/docx.py", "content": "\"\"\"\nValidator for Word document XML files against XSD schemas.\n\"\"\"\n\nimport os\nimport random\nimport re\nimport tempfile\nimport zipfile\n\nimport defusedxml.minidom\nimport lxml.etree\n\nfrom .base import BaseSchemaValidator\n\n\nclass DOCXSchemaValidator(BaseSchemaValidator):\n\n WORD_2006_NAMESPACE = \"http://schemas.openxmlformats.org/wordprocessingml/2006/main\"\n W14_NAMESPACE = \"http://schemas.microsoft.com/office/word/2010/wordml\"\n W16CID_NAMESPACE = \"http://schemas.microsoft.com/office/word/2016/wordml/cid\"\n\n ELEMENT_RELATIONSHIP_TYPES = {}\n\n def validate(self):\n if not self.validate_xml():\n return False\n\n all_valid = True\n if not self.validate_namespaces():\n all_valid = False\n\n if not self.validate_unique_ids():\n all_valid = False\n\n if not self.validate_file_references():\n all_valid = False\n\n if not self.validate_content_types():\n all_valid = False\n\n if not self.validate_against_xsd():\n all_valid = False\n\n if not self.validate_whitespace_preservation():\n all_valid = False\n\n if not self.validate_deletions():\n all_valid = False\n\n if not self.validate_insertions():\n all_valid = False\n\n if not self.validate_all_relationship_ids():\n all_valid = False\n\n if not self.validate_id_constraints():\n all_valid = False\n\n if not self.validate_comment_markers():\n all_valid = False\n\n self.compare_paragraph_counts()\n\n return all_valid\n\n def validate_whitespace_preservation(self):\n errors = []\n\n for xml_file in self.xml_files:\n if xml_file.name != \"document.xml\":\n continue\n\n try:\n root = lxml.etree.parse(str(xml_file)).getroot()\n\n for elem in root.iter(f\"{{{self.WORD_2006_NAMESPACE}}}t\"):\n if elem.text:\n text = elem.text\n if re.search(r\"^[ \\t\\n\\r]\", text) or re.search(\n r\"[ \\t\\n\\r]$\", text\n ):\n xml_space_attr = f\"{{{self.XML_NAMESPACE}}}space\"\n if (\n xml_space_attr not in elem.attrib\n or elem.attrib[xml_space_attr] != \"preserve\"\n ):\n text_preview = (\n repr(text)[:50] + \"...\"\n if len(repr(text)) > 50\n else repr(text)\n )\n errors.append(\n f\" {xml_file.relative_to(self.unpacked_dir)}: \"\n f\"Line {elem.sourceline}: w:t element with whitespace missing xml:space='preserve': {text_preview}\"\n )\n\n except (lxml.etree.XMLSyntaxError, Exception) as e:\n errors.append(\n f\" {xml_file.relative_to(self.unpacked_dir)}: Error: {e}\"\n )\n\n if errors:\n print(f\"FAILED - Found {len(errors)} whitespace preservation violations:\")\n for error in errors:\n print(error)\n return False\n else:\n if self.verbose:\n print(\"PASSED - All whitespace is properly preserved\")\n return True\n\n def validate_deletions(self):\n errors = []\n\n for xml_file in self.xml_files:\n if xml_file.name != \"document.xml\":\n continue\n\n try:\n root = lxml.etree.parse(str(xml_file)).getroot()\n namespaces = {\"w\": self.WORD_2006_NAMESPACE}\n\n for t_elem in root.xpath(\".//w:del//w:t\", namespaces=namespaces):\n if t_elem.text:\n text_preview = (\n repr(t_elem.text)[:50] + \"...\"\n if len(repr(t_elem.text)) > 50\n else repr(t_elem.text)\n )\n errors.append(\n f\" {xml_file.relative_to(self.unpacked_dir)}: \"\n f\"Line {t_elem.sourceline}: found within : {text_preview}\"\n )\n\n for instr_elem in root.xpath(\n \".//w:del//w:instrText\", namespaces=namespaces\n ):\n text_preview = (\n repr(instr_elem.text or \"\")[:50] + \"...\"\n if len(repr(instr_elem.text or \"\")) > 50\n else repr(instr_elem.text or \"\")\n )\n errors.append(\n f\" {xml_file.relative_to(self.unpacked_dir)}: \"\n f\"Line {instr_elem.sourceline}: found within (use ): {text_preview}\"\n )\n\n except (lxml.etree.XMLSyntaxError, Exception) as e:\n errors.append(\n f\" {xml_file.relative_to(self.unpacked_dir)}: Error: {e}\"\n )\n\n if errors:\n print(f\"FAILED - Found {len(errors)} deletion validation violations:\")\n for error in errors:\n print(error)\n return False\n else:\n if self.verbose:\n print(\"PASSED - No w:t elements found within w:del elements\")\n return True\n\n def count_paragraphs_in_unpacked(self):\n count = 0\n\n for xml_file in self.xml_files:\n if xml_file.name != \"document.xml\":\n continue\n\n try:\n root = lxml.etree.parse(str(xml_file)).getroot()\n paragraphs = root.findall(f\".//{{{self.WORD_2006_NAMESPACE}}}p\")\n count = len(paragraphs)\n except Exception as e:\n print(f\"Error counting paragraphs in unpacked document: {e}\")\n\n return count\n\n def count_paragraphs_in_original(self):\n original = self.original_file\n if original is None:\n return 0\n\n count = 0\n\n try:\n with tempfile.TemporaryDirectory() as temp_dir:\n with zipfile.ZipFile(original, \"r\") as zip_ref:\n zip_ref.extractall(temp_dir)\n\n doc_xml_path = os.path.join(temp_dir, \"word\", \"document.xml\")\n root = lxml.etree.parse(doc_xml_path).getroot()\n\n paragraphs = root.findall(f\".//{{{self.WORD_2006_NAMESPACE}}}p\")\n count = len(paragraphs)\n\n except Exception as e:\n print(f\"Error counting paragraphs in original document: {e}\")\n\n return count\n\n def validate_insertions(self):\n errors = []\n\n for xml_file in self.xml_files:\n if xml_file.name != \"document.xml\":\n continue\n\n try:\n root = lxml.etree.parse(str(xml_file)).getroot()\n namespaces = {\"w\": self.WORD_2006_NAMESPACE}\n\n invalid_elements = root.xpath(\n \".//w:ins//w:delText[not(ancestor::w:del)]\", namespaces=namespaces\n )\n\n for elem in invalid_elements:\n text_preview = (\n repr(elem.text or \"\")[:50] + \"...\"\n if len(repr(elem.text or \"\")) > 50\n else repr(elem.text or \"\")\n )\n errors.append(\n f\" {xml_file.relative_to(self.unpacked_dir)}: \"\n f\"Line {elem.sourceline}: within : {text_preview}\"\n )\n\n except (lxml.etree.XMLSyntaxError, Exception) as e:\n errors.append(\n f\" {xml_file.relative_to(self.unpacked_dir)}: Error: {e}\"\n )\n\n if errors:\n print(f\"FAILED - Found {len(errors)} insertion validation violations:\")\n for error in errors:\n print(error)\n return False\n else:\n if self.verbose:\n print(\"PASSED - No w:delText elements within w:ins elements\")\n return True\n\n def compare_paragraph_counts(self):\n original_count = self.count_paragraphs_in_original()\n new_count = self.count_paragraphs_in_unpacked()\n\n diff = new_count - original_count\n diff_str = f\"+{diff}\" if diff > 0 else str(diff)\n print(f\"\\nParagraphs: {original_count} → {new_count} ({diff_str})\")\n\n def _parse_id_value(self, val: str, base: int = 16) -> int:\n return int(val, base)\n\n def validate_id_constraints(self):\n errors = []\n para_id_attr = f\"{{{self.W14_NAMESPACE}}}paraId\"\n durable_id_attr = f\"{{{self.W16CID_NAMESPACE}}}durableId\"\n\n for xml_file in self.xml_files:\n try:\n for elem in lxml.etree.parse(str(xml_file)).iter():\n if val := elem.get(para_id_attr):\n if self._parse_id_value(val, base=16) >= 0x80000000:\n errors.append(\n f\" {xml_file.name}:{elem.sourceline}: paraId={val} >= 0x80000000\"\n )\n\n if val := elem.get(durable_id_attr):\n if xml_file.name == \"numbering.xml\":\n try:\n if self._parse_id_value(val, base=10) >= 0x7FFFFFFF:\n errors.append(\n f\" {xml_file.name}:{elem.sourceline}: \"\n f\"durableId={val} >= 0x7FFFFFFF\"\n )\n except ValueError:\n errors.append(\n f\" {xml_file.name}:{elem.sourceline}: \"\n f\"durableId={val} must be decimal in numbering.xml\"\n )\n else:\n if self._parse_id_value(val, base=16) >= 0x7FFFFFFF:\n errors.append(\n f\" {xml_file.name}:{elem.sourceline}: \"\n f\"durableId={val} >= 0x7FFFFFFF\"\n )\n except Exception:\n pass\n\n if errors:\n print(f\"FAILED - {len(errors)} ID constraint violations:\")\n for e in errors:\n print(e)\n elif self.verbose:\n print(\"PASSED - All paraId/durableId values within constraints\")\n return not errors\n\n def validate_comment_markers(self):\n errors = []\n\n document_xml = None\n comments_xml = None\n for xml_file in self.xml_files:\n if xml_file.name == \"document.xml\" and \"word\" in str(xml_file):\n document_xml = xml_file\n elif xml_file.name == \"comments.xml\":\n comments_xml = xml_file\n\n if not document_xml:\n if self.verbose:\n print(\"PASSED - No document.xml found (skipping comment validation)\")\n return True\n\n try:\n doc_root = lxml.etree.parse(str(document_xml)).getroot()\n namespaces = {\"w\": self.WORD_2006_NAMESPACE}\n\n range_starts = {\n elem.get(f\"{{{self.WORD_2006_NAMESPACE}}}id\")\n for elem in doc_root.xpath(\n \".//w:commentRangeStart\", namespaces=namespaces\n )\n }\n range_ends = {\n elem.get(f\"{{{self.WORD_2006_NAMESPACE}}}id\")\n for elem in doc_root.xpath(\n \".//w:commentRangeEnd\", namespaces=namespaces\n )\n }\n references = {\n elem.get(f\"{{{self.WORD_2006_NAMESPACE}}}id\")\n for elem in doc_root.xpath(\n \".//w:commentReference\", namespaces=namespaces\n )\n }\n\n orphaned_ends = range_ends - range_starts\n for comment_id in sorted(\n orphaned_ends, key=lambda x: int(x) if x and x.isdigit() else 0\n ):\n errors.append(\n f' document.xml: commentRangeEnd id=\"{comment_id}\" has no matching commentRangeStart'\n )\n\n orphaned_starts = range_starts - range_ends\n for comment_id in sorted(\n orphaned_starts, key=lambda x: int(x) if x and x.isdigit() else 0\n ):\n errors.append(\n f' document.xml: commentRangeStart id=\"{comment_id}\" has no matching commentRangeEnd'\n )\n\n comment_ids = set()\n if comments_xml and comments_xml.exists():\n comments_root = lxml.etree.parse(str(comments_xml)).getroot()\n comment_ids = {\n elem.get(f\"{{{self.WORD_2006_NAMESPACE}}}id\")\n for elem in comments_root.xpath(\n \".//w:comment\", namespaces=namespaces\n )\n }\n\n marker_ids = range_starts | range_ends | references\n invalid_refs = marker_ids - comment_ids\n for comment_id in sorted(\n invalid_refs, key=lambda x: int(x) if x and x.isdigit() else 0\n ):\n if comment_id: \n errors.append(\n f' document.xml: marker id=\"{comment_id}\" references non-existent comment'\n )\n\n except (lxml.etree.XMLSyntaxError, Exception) as e:\n errors.append(f\" Error parsing XML: {e}\")\n\n if errors:\n print(f\"FAILED - {len(errors)} comment marker violations:\")\n for error in errors:\n print(error)\n return False\n else:\n if self.verbose:\n print(\"PASSED - All comment markers properly paired\")\n return True\n\n def repair(self) -> int:\n repairs = super().repair()\n repairs += self.repair_durableId()\n return repairs\n\n def repair_durableId(self) -> int:\n repairs = 0\n\n for xml_file in self.xml_files:\n try:\n content = xml_file.read_text(encoding=\"utf-8\")\n dom = defusedxml.minidom.parseString(content)\n modified = False\n\n for elem in dom.getElementsByTagName(\"*\"):\n if not elem.hasAttribute(\"w16cid:durableId\"):\n continue\n\n durable_id = elem.getAttribute(\"w16cid:durableId\")\n needs_repair = False\n\n if xml_file.name == \"numbering.xml\":\n try:\n needs_repair = (\n self._parse_id_value(durable_id, base=10) >= 0x7FFFFFFF\n )\n except ValueError:\n needs_repair = True\n else:\n try:\n needs_repair = (\n self._parse_id_value(durable_id, base=16) >= 0x7FFFFFFF\n )\n except ValueError:\n needs_repair = True\n\n if needs_repair:\n value = random.randint(1, 0x7FFFFFFE)\n if xml_file.name == \"numbering.xml\":\n new_id = str(value) \n else:\n new_id = f\"{value:08X}\" \n\n elem.setAttribute(\"w16cid:durableId\", new_id)\n print(\n f\" Repaired: {xml_file.name}: durableId {durable_id} → {new_id}\"\n )\n repairs += 1\n modified = True\n\n if modified:\n xml_file.write_bytes(dom.toxml(encoding=\"UTF-8\"))\n\n except Exception:\n pass\n\n return repairs\n\n\nif __name__ == \"__main__\":\n raise RuntimeError(\"This module should not be run directly.\")\n" }, { "path": "src/copaw/agents/skills/xlsx/scripts/office/validators/pptx.py", "content": "\"\"\"\nValidator for PowerPoint presentation XML files against XSD schemas.\n\"\"\"\n\nimport re\n\nfrom .base import BaseSchemaValidator\n\n\nclass PPTXSchemaValidator(BaseSchemaValidator):\n\n PRESENTATIONML_NAMESPACE = (\n \"http://schemas.openxmlformats.org/presentationml/2006/main\"\n )\n\n ELEMENT_RELATIONSHIP_TYPES = {\n \"sldid\": \"slide\",\n \"sldmasterid\": \"slidemaster\",\n \"notesmasterid\": \"notesmaster\",\n \"sldlayoutid\": \"slidelayout\",\n \"themeid\": \"theme\",\n \"tablestyleid\": \"tablestyles\",\n }\n\n def validate(self):\n if not self.validate_xml():\n return False\n\n all_valid = True\n if not self.validate_namespaces():\n all_valid = False\n\n if not self.validate_unique_ids():\n all_valid = False\n\n if not self.validate_uuid_ids():\n all_valid = False\n\n if not self.validate_file_references():\n all_valid = False\n\n if not self.validate_slide_layout_ids():\n all_valid = False\n\n if not self.validate_content_types():\n all_valid = False\n\n if not self.validate_against_xsd():\n all_valid = False\n\n if not self.validate_notes_slide_references():\n all_valid = False\n\n if not self.validate_all_relationship_ids():\n all_valid = False\n\n if not self.validate_no_duplicate_slide_layouts():\n all_valid = False\n\n return all_valid\n\n def validate_uuid_ids(self):\n import lxml.etree\n\n errors = []\n uuid_pattern = re.compile(\n r\"^[\\{\\(]?[0-9A-Fa-f]{8}-?[0-9A-Fa-f]{4}-?[0-9A-Fa-f]{4}-?[0-9A-Fa-f]{4}-?[0-9A-Fa-f]{12}[\\}\\)]?$\"\n )\n\n for xml_file in self.xml_files:\n try:\n root = lxml.etree.parse(str(xml_file)).getroot()\n\n for elem in root.iter():\n for attr, value in elem.attrib.items():\n attr_name = attr.split(\"}\")[-1].lower()\n if attr_name == \"id\" or attr_name.endswith(\"id\"):\n if self._looks_like_uuid(value):\n if not uuid_pattern.match(value):\n errors.append(\n f\" {xml_file.relative_to(self.unpacked_dir)}: \"\n f\"Line {elem.sourceline}: ID '{value}' appears to be a UUID but contains invalid hex characters\"\n )\n\n except (lxml.etree.XMLSyntaxError, Exception) as e:\n errors.append(\n f\" {xml_file.relative_to(self.unpacked_dir)}: Error: {e}\"\n )\n\n if errors:\n print(f\"FAILED - Found {len(errors)} UUID ID validation errors:\")\n for error in errors:\n print(error)\n return False\n else:\n if self.verbose:\n print(\"PASSED - All UUID-like IDs contain valid hex values\")\n return True\n\n def _looks_like_uuid(self, value):\n clean_value = value.strip(\"{}()\").replace(\"-\", \"\")\n return len(clean_value) == 32 and all(c.isalnum() for c in clean_value)\n\n def validate_slide_layout_ids(self):\n import lxml.etree\n\n errors = []\n\n slide_masters = list(self.unpacked_dir.glob(\"ppt/slideMasters/*.xml\"))\n\n if not slide_masters:\n if self.verbose:\n print(\"PASSED - No slide masters found\")\n return True\n\n for slide_master in slide_masters:\n try:\n root = lxml.etree.parse(str(slide_master)).getroot()\n\n rels_file = slide_master.parent / \"_rels\" / f\"{slide_master.name}.rels\"\n\n if not rels_file.exists():\n errors.append(\n f\" {slide_master.relative_to(self.unpacked_dir)}: \"\n f\"Missing relationships file: {rels_file.relative_to(self.unpacked_dir)}\"\n )\n continue\n\n rels_root = lxml.etree.parse(str(rels_file)).getroot()\n\n valid_layout_rids = set()\n for rel in rels_root.findall(\n f\".//{{{self.PACKAGE_RELATIONSHIPS_NAMESPACE}}}Relationship\"\n ):\n rel_type = rel.get(\"Type\", \"\")\n if \"slideLayout\" in rel_type:\n valid_layout_rids.add(rel.get(\"Id\"))\n\n for sld_layout_id in root.findall(\n f\".//{{{self.PRESENTATIONML_NAMESPACE}}}sldLayoutId\"\n ):\n r_id = sld_layout_id.get(\n f\"{{{self.OFFICE_RELATIONSHIPS_NAMESPACE}}}id\"\n )\n layout_id = sld_layout_id.get(\"id\")\n\n if r_id and r_id not in valid_layout_rids:\n errors.append(\n f\" {slide_master.relative_to(self.unpacked_dir)}: \"\n f\"Line {sld_layout_id.sourceline}: sldLayoutId with id='{layout_id}' \"\n f\"references r:id='{r_id}' which is not found in slide layout relationships\"\n )\n\n except (lxml.etree.XMLSyntaxError, Exception) as e:\n errors.append(\n f\" {slide_master.relative_to(self.unpacked_dir)}: Error: {e}\"\n )\n\n if errors:\n print(f\"FAILED - Found {len(errors)} slide layout ID validation errors:\")\n for error in errors:\n print(error)\n print(\n \"Remove invalid references or add missing slide layouts to the relationships file.\"\n )\n return False\n else:\n if self.verbose:\n print(\"PASSED - All slide layout IDs reference valid slide layouts\")\n return True\n\n def validate_no_duplicate_slide_layouts(self):\n import lxml.etree\n\n errors = []\n slide_rels_files = list(self.unpacked_dir.glob(\"ppt/slides/_rels/*.xml.rels\"))\n\n for rels_file in slide_rels_files:\n try:\n root = lxml.etree.parse(str(rels_file)).getroot()\n\n layout_rels = [\n rel\n for rel in root.findall(\n f\".//{{{self.PACKAGE_RELATIONSHIPS_NAMESPACE}}}Relationship\"\n )\n if \"slideLayout\" in rel.get(\"Type\", \"\")\n ]\n\n if len(layout_rels) > 1:\n errors.append(\n f\" {rels_file.relative_to(self.unpacked_dir)}: has {len(layout_rels)} slideLayout references\"\n )\n\n except Exception as e:\n errors.append(\n f\" {rels_file.relative_to(self.unpacked_dir)}: Error: {e}\"\n )\n\n if errors:\n print(\"FAILED - Found slides with duplicate slideLayout references:\")\n for error in errors:\n print(error)\n return False\n else:\n if self.verbose:\n print(\"PASSED - All slides have exactly one slideLayout reference\")\n return True\n\n def validate_notes_slide_references(self):\n import lxml.etree\n\n errors = []\n notes_slide_references = {} \n\n slide_rels_files = list(self.unpacked_dir.glob(\"ppt/slides/_rels/*.xml.rels\"))\n\n if not slide_rels_files:\n if self.verbose:\n print(\"PASSED - No slide relationship files found\")\n return True\n\n for rels_file in slide_rels_files:\n try:\n root = lxml.etree.parse(str(rels_file)).getroot()\n\n for rel in root.findall(\n f\".//{{{self.PACKAGE_RELATIONSHIPS_NAMESPACE}}}Relationship\"\n ):\n rel_type = rel.get(\"Type\", \"\")\n if \"notesSlide\" in rel_type:\n target = rel.get(\"Target\", \"\")\n if target:\n normalized_target = target.replace(\"../\", \"\")\n\n slide_name = rels_file.stem.replace(\n \".xml\", \"\"\n ) \n\n if normalized_target not in notes_slide_references:\n notes_slide_references[normalized_target] = []\n notes_slide_references[normalized_target].append(\n (slide_name, rels_file)\n )\n\n except (lxml.etree.XMLSyntaxError, Exception) as e:\n errors.append(\n f\" {rels_file.relative_to(self.unpacked_dir)}: Error: {e}\"\n )\n\n for target, references in notes_slide_references.items():\n if len(references) > 1:\n slide_names = [ref[0] for ref in references]\n errors.append(\n f\" Notes slide '{target}' is referenced by multiple slides: {', '.join(slide_names)}\"\n )\n for slide_name, rels_file in references:\n errors.append(f\" - {rels_file.relative_to(self.unpacked_dir)}\")\n\n if errors:\n print(\n f\"FAILED - Found {len([e for e in errors if not e.startswith(' ')])} notes slide reference validation errors:\"\n )\n for error in errors:\n print(error)\n print(\"Each slide may optionally have its own slide file.\")\n return False\n else:\n if self.verbose:\n print(\"PASSED - All notes slide references are unique\")\n return True\n\n\nif __name__ == \"__main__\":\n raise RuntimeError(\"This module should not be run directly.\")\n" }, { "path": "src/copaw/agents/skills/xlsx/scripts/office/validators/redlining.py", "content": "\"\"\"\nValidator for tracked changes in Word documents.\n\"\"\"\n\nimport subprocess\nimport tempfile\nimport zipfile\nfrom pathlib import Path\n\n\nclass RedliningValidator:\n\n def __init__(self, unpacked_dir, original_docx, verbose=False, author=\"Claude\"):\n self.unpacked_dir = Path(unpacked_dir)\n self.original_docx = Path(original_docx)\n self.verbose = verbose\n self.author = author\n self.namespaces = {\n \"w\": \"http://schemas.openxmlformats.org/wordprocessingml/2006/main\"\n }\n\n def repair(self) -> int:\n return 0\n\n def validate(self):\n modified_file = self.unpacked_dir / \"word\" / \"document.xml\"\n if not modified_file.exists():\n print(f\"FAILED - Modified document.xml not found at {modified_file}\")\n return False\n\n try:\n import xml.etree.ElementTree as ET\n\n tree = ET.parse(modified_file)\n root = tree.getroot()\n\n del_elements = root.findall(\".//w:del\", self.namespaces)\n ins_elements = root.findall(\".//w:ins\", self.namespaces)\n\n author_del_elements = [\n elem\n for elem in del_elements\n if elem.get(f\"{{{self.namespaces['w']}}}author\") == self.author\n ]\n author_ins_elements = [\n elem\n for elem in ins_elements\n if elem.get(f\"{{{self.namespaces['w']}}}author\") == self.author\n ]\n\n if not author_del_elements and not author_ins_elements:\n if self.verbose:\n print(f\"PASSED - No tracked changes by {self.author} found.\")\n return True\n\n except Exception:\n pass\n\n with tempfile.TemporaryDirectory() as temp_dir:\n temp_path = Path(temp_dir)\n\n try:\n with zipfile.ZipFile(self.original_docx, \"r\") as zip_ref:\n zip_ref.extractall(temp_path)\n except Exception as e:\n print(f\"FAILED - Error unpacking original docx: {e}\")\n return False\n\n original_file = temp_path / \"word\" / \"document.xml\"\n if not original_file.exists():\n print(\n f\"FAILED - Original document.xml not found in {self.original_docx}\"\n )\n return False\n\n try:\n import xml.etree.ElementTree as ET\n\n modified_tree = ET.parse(modified_file)\n modified_root = modified_tree.getroot()\n original_tree = ET.parse(original_file)\n original_root = original_tree.getroot()\n except ET.ParseError as e:\n print(f\"FAILED - Error parsing XML files: {e}\")\n return False\n\n self._remove_author_tracked_changes(original_root)\n self._remove_author_tracked_changes(modified_root)\n\n modified_text = self._extract_text_content(modified_root)\n original_text = self._extract_text_content(original_root)\n\n if modified_text != original_text:\n error_message = self._generate_detailed_diff(\n original_text, modified_text\n )\n print(error_message)\n return False\n\n if self.verbose:\n print(f\"PASSED - All changes by {self.author} are properly tracked\")\n return True\n\n def _generate_detailed_diff(self, original_text, modified_text):\n error_parts = [\n f\"FAILED - Document text doesn't match after removing {self.author}'s tracked changes\",\n \"\",\n \"Likely causes:\",\n \" 1. Modified text inside another author's or tags\",\n \" 2. Made edits without proper tracked changes\",\n \" 3. Didn't nest inside when deleting another's insertion\",\n \"\",\n \"For pre-redlined documents, use correct patterns:\",\n \" - To reject another's INSERTION: Nest inside their \",\n \" - To restore another's DELETION: Add new AFTER their \",\n \"\",\n ]\n\n git_diff = self._get_git_word_diff(original_text, modified_text)\n if git_diff:\n error_parts.extend([\"Differences:\", \"============\", git_diff])\n else:\n error_parts.append(\"Unable to generate word diff (git not available)\")\n\n return \"\\n\".join(error_parts)\n\n def _get_git_word_diff(self, original_text, modified_text):\n try:\n with tempfile.TemporaryDirectory() as temp_dir:\n temp_path = Path(temp_dir)\n\n original_file = temp_path / \"original.txt\"\n modified_file = temp_path / \"modified.txt\"\n\n original_file.write_text(original_text, encoding=\"utf-8\")\n modified_file.write_text(modified_text, encoding=\"utf-8\")\n\n result = subprocess.run(\n [\n \"git\",\n \"diff\",\n \"--word-diff=plain\",\n \"--word-diff-regex=.\", \n \"-U0\", \n \"--no-index\",\n str(original_file),\n str(modified_file),\n ],\n capture_output=True,\n text=True,\n )\n\n if result.stdout.strip():\n lines = result.stdout.split(\"\\n\")\n content_lines = []\n in_content = False\n for line in lines:\n if line.startswith(\"@@\"):\n in_content = True\n continue\n if in_content and line.strip():\n content_lines.append(line)\n\n if content_lines:\n return \"\\n\".join(content_lines)\n\n result = subprocess.run(\n [\n \"git\",\n \"diff\",\n \"--word-diff=plain\",\n \"-U0\", \n \"--no-index\",\n str(original_file),\n str(modified_file),\n ],\n capture_output=True,\n text=True,\n )\n\n if result.stdout.strip():\n lines = result.stdout.split(\"\\n\")\n content_lines = []\n in_content = False\n for line in lines:\n if line.startswith(\"@@\"):\n in_content = True\n continue\n if in_content and line.strip():\n content_lines.append(line)\n return \"\\n\".join(content_lines)\n\n except (subprocess.CalledProcessError, FileNotFoundError, Exception):\n pass\n\n return None\n\n def _remove_author_tracked_changes(self, root):\n ins_tag = f\"{{{self.namespaces['w']}}}ins\"\n del_tag = f\"{{{self.namespaces['w']}}}del\"\n author_attr = f\"{{{self.namespaces['w']}}}author\"\n\n for parent in root.iter():\n to_remove = []\n for child in parent:\n if child.tag == ins_tag and child.get(author_attr) == self.author:\n to_remove.append(child)\n for elem in to_remove:\n parent.remove(elem)\n\n deltext_tag = f\"{{{self.namespaces['w']}}}delText\"\n t_tag = f\"{{{self.namespaces['w']}}}t\"\n\n for parent in root.iter():\n to_process = []\n for child in parent:\n if child.tag == del_tag and child.get(author_attr) == self.author:\n to_process.append((child, list(parent).index(child)))\n\n for del_elem, del_index in reversed(to_process):\n for elem in del_elem.iter():\n if elem.tag == deltext_tag:\n elem.tag = t_tag\n\n for child in reversed(list(del_elem)):\n parent.insert(del_index, child)\n parent.remove(del_elem)\n\n def _extract_text_content(self, root):\n p_tag = f\"{{{self.namespaces['w']}}}p\"\n t_tag = f\"{{{self.namespaces['w']}}}t\"\n\n paragraphs = []\n for p_elem in root.findall(f\".//{p_tag}\"):\n text_parts = []\n for t_elem in p_elem.findall(f\".//{t_tag}\"):\n if t_elem.text:\n text_parts.append(t_elem.text)\n paragraph_text = \"\".join(text_parts)\n if paragraph_text:\n paragraphs.append(paragraph_text)\n\n return \"\\n\".join(paragraphs)\n\n\nif __name__ == \"__main__\":\n raise RuntimeError(\"This module should not be run directly.\")\n" }, { "path": "src/copaw/agents/skills/xlsx/scripts/recalc.py", "content": "\"\"\"\nExcel Formula Recalculation Script\nRecalculates all formulas in an Excel file using LibreOffice\n\"\"\"\n\nimport json\nimport os\nimport platform\nimport subprocess\nimport sys\nfrom pathlib import Path\n\nfrom office.soffice import get_soffice_cmd, get_soffice_env\n\nfrom openpyxl import load_workbook\n\nMACRO_DIR_MACOS = \"~/Library/Application Support/LibreOffice/4/user/basic/Standard\"\nMACRO_DIR_LINUX = \"~/.config/libreoffice/4/user/basic/Standard\"\nMACRO_DIR_WINDOWS = \"~/AppData/Roaming/LibreOffice/4/user/basic/Standard\"\nMACRO_FILENAME = \"Module1.xba\"\n\nRECALCULATE_MACRO = \"\"\"\n\n\n Sub RecalculateAndSave()\n ThisComponent.calculateAll()\n ThisComponent.store()\n ThisComponent.close(True)\n End Sub\n\"\"\"\n\n\ndef has_gtimeout():\n try:\n subprocess.run(\n [\"gtimeout\", \"--version\"], capture_output=True, timeout=1, check=False\n )\n return True\n except (FileNotFoundError, subprocess.TimeoutExpired):\n return False\n\n\ndef _get_macro_dir() -> str:\n \"\"\"Return the LibreOffice macro directory for the current platform.\"\"\"\n system = platform.system()\n if system == \"Darwin\":\n return MACRO_DIR_MACOS\n elif system == \"Windows\":\n return MACRO_DIR_WINDOWS\n else:\n return MACRO_DIR_LINUX\n\n\ndef setup_libreoffice_macro():\n macro_dir = os.path.expanduser(_get_macro_dir())\n macro_file = os.path.join(macro_dir, MACRO_FILENAME)\n\n if (\n os.path.exists(macro_file)\n and \"RecalculateAndSave\" in Path(macro_file).read_text()\n ):\n return True\n\n if not os.path.exists(macro_dir):\n subprocess.run(\n [get_soffice_cmd(), \"--headless\", \"--terminate_after_init\"],\n capture_output=True,\n timeout=10,\n env=get_soffice_env(),\n )\n os.makedirs(macro_dir, exist_ok=True)\n\n try:\n Path(macro_file).write_text(RECALCULATE_MACRO)\n return True\n except Exception:\n return False\n\n\ndef recalc(filename, timeout=30):\n if not Path(filename).exists():\n return {\"error\": f\"File {filename} does not exist\"}\n\n abs_path = str(Path(filename).absolute())\n\n if not setup_libreoffice_macro():\n return {\"error\": \"Failed to setup LibreOffice macro\"}\n\n cmd = [\n get_soffice_cmd(),\n \"--headless\",\n \"--norestore\",\n \"vnd.sun.star.script:Standard.Module1.RecalculateAndSave?language=Basic&location=application\",\n abs_path,\n ]\n\n system = platform.system()\n if system == \"Linux\":\n cmd = [\"timeout\", str(timeout)] + cmd\n elif system == \"Darwin\" and has_gtimeout():\n cmd = [\"gtimeout\", str(timeout)] + cmd\n # On Windows, rely on subprocess timeout parameter instead of external tool\n\n try:\n result = subprocess.run(\n cmd,\n capture_output=True,\n text=True,\n env=get_soffice_env(),\n timeout=timeout if system == \"Windows\" else None,\n )\n except subprocess.TimeoutExpired:\n return {\n \"error\": (\n f\"LibreOffice recalculation timed out after {timeout} seconds\"\n ),\n }\n\n if result.returncode != 0 and result.returncode != 124: \n error_msg = result.stderr or \"Unknown error during recalculation\"\n if \"Module1\" in error_msg or \"RecalculateAndSave\" not in error_msg:\n return {\"error\": \"LibreOffice macro not configured properly\"}\n return {\"error\": error_msg}\n\n try:\n wb = load_workbook(filename, data_only=True)\n\n excel_errors = [\n \"#VALUE!\",\n \"#DIV/0!\",\n \"#REF!\",\n \"#NAME?\",\n \"#NULL!\",\n \"#NUM!\",\n \"#N/A\",\n ]\n error_details = {err: [] for err in excel_errors}\n total_errors = 0\n\n for sheet_name in wb.sheetnames:\n ws = wb[sheet_name]\n for row in ws.iter_rows():\n for cell in row:\n if cell.value is not None and isinstance(cell.value, str):\n for err in excel_errors:\n if err in cell.value:\n location = f\"{sheet_name}!{cell.coordinate}\"\n error_details[err].append(location)\n total_errors += 1\n break\n\n wb.close()\n\n result = {\n \"status\": \"success\" if total_errors == 0 else \"errors_found\",\n \"total_errors\": total_errors,\n \"error_summary\": {},\n }\n\n for err_type, locations in error_details.items():\n if locations:\n result[\"error_summary\"][err_type] = {\n \"count\": len(locations),\n \"locations\": locations[:20], \n }\n\n wb_formulas = load_workbook(filename, data_only=False)\n formula_count = 0\n for sheet_name in wb_formulas.sheetnames:\n ws = wb_formulas[sheet_name]\n for row in ws.iter_rows():\n for cell in row:\n if (\n cell.value\n and isinstance(cell.value, str)\n and cell.value.startswith(\"=\")\n ):\n formula_count += 1\n wb_formulas.close()\n\n result[\"total_formulas\"] = formula_count\n\n return result\n\n except Exception as e:\n return {\"error\": str(e)}\n\n\ndef main():\n if len(sys.argv) < 2:\n print(\"Usage: python recalc.py [timeout_seconds]\")\n print(\"\\nRecalculates all formulas in an Excel file using LibreOffice\")\n print(\"\\nReturns JSON with error details:\")\n print(\" - status: 'success' or 'errors_found'\")\n print(\" - total_errors: Total number of Excel errors found\")\n print(\" - total_formulas: Number of formulas in the file\")\n print(\" - error_summary: Breakdown by error type with locations\")\n print(\" - #VALUE!, #DIV/0!, #REF!, #NAME?, #NULL!, #NUM!, #N/A\")\n sys.exit(1)\n\n filename = sys.argv[1]\n timeout = int(sys.argv[2]) if len(sys.argv) > 2 else 30\n\n result = recalc(filename, timeout)\n print(json.dumps(result, indent=2))\n\n\nif __name__ == \"__main__\":\n main()\n" }, { "path": "src/copaw/agents/skills_hub.py", "content": "# -*- coding: utf-8 -*-\n\"\"\"Skills hub client and install helpers.\"\"\"\nfrom __future__ import annotations\n\nimport json\nimport logging\nimport os\nimport re\nimport time\nimport contextvars\nimport base64\nimport io\nimport zipfile\nfrom dataclasses import dataclass\nfrom pathlib import Path\nfrom typing import Any\nfrom urllib.parse import quote, urlencode, urlparse, unquote\nfrom urllib.error import HTTPError, URLError\nfrom urllib.request import Request, urlopen\nfrom contextlib import contextmanager\n\nimport frontmatter\nimport yaml\n\nfrom .skills_manager import SkillService\n\nlogger = logging.getLogger(__name__)\n\n_cancel_checker_ctx: contextvars.ContextVar[\n Any | None\n] = contextvars.ContextVar(\"skills_hub_cancel_checker\", default=None)\n\n\n@dataclass\nclass HubSkillResult:\n slug: str\n name: str\n description: str = \"\"\n version: str = \"\"\n source_url: str = \"\"\n\n\n@dataclass\nclass HubInstallResult:\n name: str\n enabled: bool\n source_url: str\n\n\nclass SkillImportCancelled(RuntimeError):\n \"\"\"Raised when a skill import task is cancelled by user.\"\"\"\n\n\nRETRYABLE_HTTP_STATUS = {\n 408,\n 409,\n 425,\n 429,\n 500,\n 502,\n 503,\n 504,\n}\n\nLOBEHUB_MAX_ZIP_ENTRIES = 256\nLOBEHUB_MAX_ZIP_BYTES = 5 * 1024 * 1024\nHTTP_READ_CHUNK_BYTES = 64 * 1024\n\n\ndef _hub_http_timeout() -> float:\n raw = os.environ.get(\"COPAW_SKILLS_HUB_HTTP_TIMEOUT\", \"15\")\n try:\n return max(3.0, float(raw))\n except Exception:\n return 15.0\n\n\ndef _hub_http_retries() -> int:\n raw = os.environ.get(\"COPAW_SKILLS_HUB_HTTP_RETRIES\", \"3\")\n try:\n return max(0, int(raw))\n except Exception:\n return 3\n\n\ndef _hub_http_backoff_base() -> float:\n raw = os.environ.get(\"COPAW_SKILLS_HUB_HTTP_BACKOFF_BASE\", \"0.8\")\n try:\n return max(0.1, float(raw))\n except Exception:\n return 0.8\n\n\ndef _hub_http_backoff_cap() -> float:\n raw = os.environ.get(\"COPAW_SKILLS_HUB_HTTP_BACKOFF_CAP\", \"6\")\n try:\n return max(0.5, float(raw))\n except Exception:\n return 6.0\n\n\ndef _compute_backoff_seconds(attempt: int) -> float:\n base = _hub_http_backoff_base()\n cap = _hub_http_backoff_cap()\n return min(cap, base * (2 ** max(0, attempt - 1)))\n\n\ndef _ensure_not_cancelled() -> None:\n checker = _cancel_checker_ctx.get()\n if checker is None:\n return\n try:\n if bool(checker()):\n raise SkillImportCancelled(\"Skill import cancelled by user\")\n except SkillImportCancelled:\n raise\n except Exception:\n # Ignore checker failures and continue.\n return\n\n\n@contextmanager\ndef _with_cancel_checker(checker: Any | None):\n token = _cancel_checker_ctx.set(checker)\n try:\n yield\n finally:\n _cancel_checker_ctx.reset(token)\n\n\ndef _hub_base_url() -> str:\n return os.environ.get(\"COPAW_SKILLS_HUB_BASE_URL\", \"https://clawhub.ai\")\n\n\ndef _hub_search_path() -> str:\n return os.environ.get(\n \"COPAW_SKILLS_HUB_SEARCH_PATH\",\n \"/api/v1/search\",\n )\n\n\ndef _hub_version_path() -> str:\n return os.environ.get(\n \"COPAW_SKILLS_HUB_VERSION_PATH\",\n \"/api/v1/skills/{slug}/versions/{version}\",\n )\n\n\ndef _hub_detail_path() -> str:\n return os.environ.get(\n \"COPAW_SKILLS_HUB_DETAIL_PATH\",\n \"/api/v1/skills/{slug}\",\n )\n\n\ndef _hub_file_path() -> str:\n return os.environ.get(\n \"COPAW_SKILLS_HUB_FILE_PATH\",\n \"/api/v1/skills/{slug}/file\",\n )\n\n\ndef _join_url(base: str, path: str) -> str:\n return f\"{base.rstrip('/')}/{path.lstrip('/')}\"\n\n\ndef _build_request(full_url: str, accept: str) -> Request:\n req = Request(\n full_url,\n headers={\n \"Accept\": accept,\n \"User-Agent\": \"copaw-skills-hub/1.0\",\n },\n )\n parsed = urlparse(full_url)\n host = (parsed.netloc or \"\").lower()\n github_token = os.environ.get(\"GITHUB_TOKEN\") or os.environ.get(\"GH_TOKEN\")\n if github_token and \"api.github.com\" in host:\n req.add_header(\"Authorization\", f\"Bearer {github_token}\")\n return req\n\n\ndef _read_response_bytes(\n resp: Any,\n *,\n full_url: str,\n max_bytes: int | None = None,\n) -> bytes:\n _ensure_not_cancelled()\n if max_bytes is not None and max_bytes <= 0:\n raise ValueError(\"max_bytes must be greater than 0\")\n\n content_length = None\n headers = getattr(resp, \"headers\", None)\n if headers is not None:\n raw_content_length = headers.get(\"Content-Length\")\n try:\n content_length = int(raw_content_length)\n except (TypeError, ValueError):\n content_length = None\n if (\n max_bytes is not None\n and content_length is not None\n and content_length > max_bytes\n ):\n raise ValueError(\n f\"Response body too large from {full_url}: \"\n f\"{content_length} bytes exceeds limit {max_bytes}\",\n )\n\n body = bytearray()\n while True:\n _ensure_not_cancelled()\n chunk = resp.read(HTTP_READ_CHUNK_BYTES)\n if not chunk:\n return bytes(body)\n body.extend(chunk)\n if max_bytes is not None and len(body) > max_bytes:\n raise ValueError(\n f\"Response body too large from {full_url}: \"\n f\"download exceeded limit {max_bytes}\",\n )\n\n\n# pylint: disable-next=too-many-branches,too-many-statements\ndef _http_fetch(\n url: str,\n params: dict[str, Any] | None = None,\n accept: str = \"application/json\",\n max_bytes: int | None = None,\n) -> bytes:\n _ensure_not_cancelled()\n full_url = url\n if params:\n full_url = f\"{url}?{urlencode(params)}\"\n req = _build_request(full_url, accept)\n host = (urlparse(full_url).netloc or \"\").lower()\n retries = _hub_http_retries()\n timeout = _hub_http_timeout()\n attempts = retries + 1\n last_error: Exception | None = None\n for attempt in range(1, attempts + 1):\n _ensure_not_cancelled()\n try:\n with urlopen(req, timeout=timeout) as resp:\n return _read_response_bytes(\n resp,\n full_url=full_url,\n max_bytes=max_bytes,\n )\n except HTTPError as e:\n last_error = e\n status = getattr(e, \"code\", 0) or 0\n if status == 403 and \"api.github.com\" in host:\n body = \"\"\n try:\n body = e.read().decode(\"utf-8\", errors=\"ignore\")\n except Exception:\n body = \"\"\n if (\n \"rate limit\" in body.lower()\n or \"rate limit\" in str(e).lower()\n ):\n raise RuntimeError(\n \"GitHub API rate limit exceeded\"\n \". Set GITHUB_TOKEN \"\n \"to increase the limit, then retry.\",\n ) from e\n # Retry only temporary/rate-limit server failures.\n if attempt < attempts and status in RETRYABLE_HTTP_STATUS:\n delay = _compute_backoff_seconds(attempt)\n logger.warning(\n \"Hub HTTP %s on %s (attempt %d/%d), retrying in %.2fs\",\n status,\n full_url,\n attempt,\n attempts,\n delay,\n )\n _ensure_not_cancelled()\n time.sleep(delay)\n continue\n # User-facing message when retries exhausted (429, 5xx).\n retries = attempts - 1\n if status == 429:\n hint = \"\"\n if \"api.github.com\" in host or \"github\" in full_url.lower():\n hint = (\n \" For GitHub sources, set GITHUB_TOKEN to avoid \"\n \"rate limits.\"\n )\n raise RuntimeError(\n f\"Hub returned 429 (Too Many Requests) after {retries} \"\n f\"retries. Try again later.{hint}\",\n ) from e\n if status >= 500:\n raise RuntimeError(\n f\"Hub returned {status} after {retries} retries. \"\n \"Try again later.\",\n ) from e\n raise\n except URLError as e:\n last_error = e\n if attempt < attempts:\n delay = _compute_backoff_seconds(attempt)\n logger.warning(\n \"Hub URL error on %s (attempt %d/%d), \"\n \"retrying in %.2fs: %s\",\n full_url,\n attempt,\n attempts,\n delay,\n e,\n )\n _ensure_not_cancelled()\n time.sleep(delay)\n continue\n raise\n except TimeoutError as e:\n last_error = e\n if attempt < attempts:\n delay = _compute_backoff_seconds(attempt)\n logger.warning(\n \"Hub timeout on %s (attempt %d/%d), retrying in %.2fs\",\n full_url,\n attempt,\n attempts,\n delay,\n )\n time.sleep(delay)\n continue\n raise\n if last_error is not None:\n raise last_error\n raise RuntimeError(f\"Failed to request hub URL: {full_url}\")\n\n\ndef _http_get(\n url: str,\n params: dict[str, Any] | None = None,\n accept: str = \"application/json\",\n) -> str:\n return _http_fetch(\n url,\n params=params,\n accept=accept,\n ).decode(\"utf-8\", errors=\"replace\")\n\n\ndef _http_bytes_get(\n url: str,\n params: dict[str, Any] | None = None,\n accept: str = \"application/octet-stream, */*\",\n max_bytes: int | None = None,\n) -> bytes:\n return _http_fetch(\n url,\n params=params,\n accept=accept,\n max_bytes=max_bytes,\n )\n\n\ndef _http_json_get(url: str, params: dict[str, Any] | None = None) -> Any:\n body = _http_get(url, params=params, accept=\"application/json\")\n return json.loads(body)\n\n\ndef _http_text_get(url: str, params: dict[str, Any] | None = None) -> str:\n return _http_get(\n url,\n params=params,\n accept=\"text/plain, text/markdown, */*\",\n )\n\n\ndef _norm_search_items(data: Any) -> list[dict[str, Any]]:\n if isinstance(data, list):\n return [x for x in data if isinstance(x, dict)]\n if isinstance(data, dict):\n for key in (\"items\", \"skills\", \"results\", \"data\"):\n value = data.get(key)\n if isinstance(value, list):\n return [x for x in value if isinstance(x, dict)]\n if all(k in data for k in (\"name\", \"slug\")):\n return [data]\n return []\n\n\ndef _safe_path_parts(path: str) -> list[str] | None:\n if not path or path.startswith(\"/\"):\n return None\n parts = [p for p in path.split(\"/\") if p]\n if not parts:\n return None\n for part in parts:\n if part in (\".\", \"..\"):\n return None\n return parts\n\n\ndef _tree_insert(\n tree: dict[str, Any],\n parts: list[str],\n content: str,\n) -> None:\n node = tree\n for part in parts[:-1]:\n child = node.get(part)\n if not isinstance(child, dict):\n child = {}\n node[part] = child\n node = child\n node[parts[-1]] = content\n\n\ndef _files_to_tree(\n files: dict[str, str],\n) -> tuple[dict[str, Any], dict[str, Any]]:\n references: dict[str, Any] = {}\n scripts: dict[str, Any] = {}\n for rel, content in files.items():\n if not isinstance(rel, str) or not isinstance(content, str):\n continue\n parts = _safe_path_parts(rel)\n if not parts:\n continue\n if parts[0] == \"references\" and len(parts) > 1:\n _tree_insert(references, parts[1:], content)\n elif parts[0] == \"scripts\" and len(parts) > 1:\n _tree_insert(scripts, parts[1:], content)\n return references, scripts\n\n\ndef _sanitize_tree(tree: Any) -> dict[str, Any]:\n if not isinstance(tree, dict):\n return {}\n out: dict[str, Any] = {}\n for key, value in tree.items():\n if not isinstance(key, str):\n continue\n if key in (\".\", \"..\") or \"/\" in key or \"\\\\\" in key:\n continue\n if isinstance(value, dict):\n out[key] = _sanitize_tree(value)\n elif isinstance(value, str):\n out[key] = value\n return out\n\n\ndef _bundle_has_content(payload: Any) -> bool:\n if not isinstance(payload, dict):\n return False\n content = (\n payload.get(\"content\")\n or payload.get(\"skill_md\")\n or payload.get(\"skillMd\")\n )\n if isinstance(content, str) and content.strip():\n return True\n files = payload.get(\"files\")\n if isinstance(files, dict) and isinstance(files.get(\"SKILL.md\"), str):\n return True\n return False\n\n\ndef _extract_version_hint(\n detail: dict[str, Any],\n requested_version: str,\n) -> str:\n if requested_version:\n return requested_version\n latest = detail.get(\"latestVersion\")\n if isinstance(latest, dict):\n ver = latest.get(\"version\")\n if isinstance(ver, str) and ver:\n return ver\n skill = detail.get(\"skill\")\n if isinstance(skill, dict):\n tags = skill.get(\"tags\")\n if isinstance(tags, dict):\n latest_tag = tags.get(\"latest\")\n if isinstance(latest_tag, str) and latest_tag:\n return latest_tag\n return \"\"\n\n\n# pylint: disable-next=too-many-return-statements,too-many-branches\ndef _hydrate_clawhub_payload(\n data: Any,\n *,\n slug: str,\n requested_version: str,\n) -> Any:\n \"\"\"\n Convert ClawHub metadata responses into\n bundle-like payload with file contents.\n \"\"\"\n if _bundle_has_content(data):\n return data\n if not isinstance(data, dict):\n return data\n skill = data.get(\"skill\")\n if not isinstance(skill, dict):\n return data\n\n skill_slug = str(skill.get(\"slug\") or slug or \"\").strip()\n if not skill_slug:\n return data\n\n version_data = data\n version_obj = data.get(\"version\")\n if not isinstance(version_obj, dict) or not isinstance(\n version_obj.get(\"files\"),\n list,\n ):\n version_hint = _extract_version_hint(data, requested_version)\n if not version_hint:\n return data\n base = _hub_base_url()\n version_url = _join_url(\n base,\n _hub_version_path().format(slug=skill_slug, version=version_hint),\n )\n version_data = _http_json_get(version_url)\n version_obj = (\n version_data.get(\"version\")\n if isinstance(version_data, dict)\n else None\n )\n\n if not isinstance(version_obj, dict):\n return data\n files_meta = version_obj.get(\"files\")\n if not isinstance(files_meta, list):\n return data\n\n version_str = str(\n version_obj.get(\"version\") or requested_version or \"\",\n ).strip()\n base = _hub_base_url()\n file_url = _join_url(base, _hub_file_path().format(slug=skill_slug))\n files: dict[str, str] = {}\n last_fetch_error: Exception | None = None\n for item in files_meta:\n if not isinstance(item, dict):\n continue\n path = item.get(\"path\")\n if not isinstance(path, str) or not path:\n continue\n params = {\"path\": path}\n if version_str:\n params[\"version\"] = version_str\n try:\n files[path] = _http_text_get(file_url, params=params)\n except Exception as e:\n last_fetch_error = e\n logger.warning(\"Failed to fetch hub file %s: %s\", path, e)\n\n if not files.get(\"SKILL.md\"):\n if last_fetch_error is not None:\n raise RuntimeError(\n \"Failed to fetch SKILL.md from hub: \" + str(last_fetch_error),\n ) from last_fetch_error\n return data\n\n return {\n \"name\": skill.get(\"displayName\") or skill_slug,\n \"files\": files,\n }\n\n\n# pylint: disable-next=too-many-branches\ndef _normalize_bundle(\n data: Any,\n) -> tuple[str, str, dict[str, Any], dict[str, Any], dict[str, Any]]:\n payload = data\n if isinstance(data, dict) and isinstance(data.get(\"skill\"), dict):\n payload = data[\"skill\"]\n if not isinstance(payload, dict):\n raise ValueError(\"Hub bundle is not a valid JSON object\")\n\n content = (\n payload.get(\"content\")\n or payload.get(\"skill_md\")\n or payload.get(\"skillMd\")\n or \"\"\n )\n if not isinstance(content, str):\n content = \"\"\n\n references = _sanitize_tree(payload.get(\"references\"))\n scripts = _sanitize_tree(payload.get(\"scripts\"))\n extra_files: dict[str, Any] = {}\n\n # Fallback: parse from a flat files mapping\n files = payload.get(\"files\")\n if isinstance(files, dict):\n ref2, scr2 = _files_to_tree(files)\n if not references:\n references = ref2\n if not scripts:\n scripts = scr2\n for rel, file_content in files.items():\n if not isinstance(rel, str) or not isinstance(file_content, str):\n continue\n if rel == \"SKILL.md\":\n continue\n parts = _safe_path_parts(rel)\n if not parts:\n continue\n if parts[0] in (\"references\", \"scripts\"):\n continue\n _tree_insert(extra_files, parts, file_content)\n if not content and isinstance(files.get(\"SKILL.md\"), str):\n content = files[\"SKILL.md\"]\n\n if not content:\n raise ValueError(\"Hub bundle missing SKILL.md content\")\n\n name = payload.get(\"name\", \"\")\n if not isinstance(name, str):\n name = \"\"\n if not name:\n try:\n post = frontmatter.loads(content)\n name = post.get(\"name\", \"\")\n except yaml.YAMLError:\n name = \"\"\n if not name:\n raise ValueError(\"Hub bundle missing skill name\")\n\n return name, content, references, scripts, extra_files\n\n\ndef _safe_fallback_name(raw: str) -> str:\n out = re.sub(r\"[^a-zA-Z0-9_-]\", \"-\", raw).strip(\"-_\")\n return out or \"imported-skill\"\n\n\ndef _extract_error_message_from_payload(payload: bytes) -> str:\n text = payload.decode(\"utf-8\", errors=\"ignore\").strip()\n if not text:\n return \"\"\n try:\n data = json.loads(text)\n except json.JSONDecodeError:\n return text\n if isinstance(data, dict):\n for key in (\"error\", \"message\"):\n value = data.get(key)\n if isinstance(value, str) and value.strip():\n return value.strip()\n return text\n\n\ndef _lobehub_http_error_message(error: HTTPError) -> str:\n body_bytes: bytes | None = None\n try:\n body_bytes = error.read()\n except Exception:\n body_bytes = None\n if isinstance(body_bytes, (bytes, bytearray)):\n message = _extract_error_message_from_payload(bytes(body_bytes))\n if message:\n return message\n return str(error)\n\n\ndef _is_probably_text_blob(payload: bytes) -> bool:\n if not payload:\n return True\n if b\"\\x00\" in payload:\n return False\n sample = payload[:1024]\n text_chars = bytearray({7, 8, 9, 10, 12, 13, 27})\n text_chars.extend(range(0x20, 0x100))\n non_text = sample.translate(None, bytes(text_chars))\n return len(non_text) <= max(1, len(sample) // 10)\n\n\ndef _should_keep_lobehub_file(parts: list[str]) -> bool:\n if not parts:\n return False\n if parts == [\"SKILL.md\"]:\n return True\n if parts[0] in {\"references\", \"scripts\"} and len(parts) > 1:\n return True\n return len(parts) == 1\n\n\ndef _sanitize_skill_dir_name(name: str) -> str:\n \"\"\"\n Sanitize skill name for use as directory name.\n Display names like \"Excel / XLSX\" must not be used as-is because \"/\"\n can be misinterpreted as a path separator.\n \"\"\"\n if not name or not isinstance(name, str):\n return \"imported-skill\"\n if \"/\" in name or \"\\\\\" in name:\n sanitized = _normalize_skill_key(name)\n return sanitized or _safe_fallback_name(name)\n return name\n\n\ndef _is_http_url(text: str) -> bool:\n parsed = urlparse(text.strip())\n return parsed.scheme in {\"http\", \"https\"} and bool(parsed.netloc)\n\n\ndef _extract_clawhub_slug_from_url(url: str) -> str:\n parsed = urlparse(url)\n host = (parsed.netloc or \"\").lower()\n if \"clawhub.ai\" not in host:\n return \"\"\n parts = [p for p in parsed.path.split(\"/\") if p]\n if not parts:\n return \"\"\n # clawhub pages can be /owner/skill or /skill\n return parts[-1].strip()\n\n\ndef _extract_skills_sh_spec(url: str) -> tuple[str, str, str] | None:\n parsed = urlparse(url)\n host = (parsed.netloc or \"\").lower()\n if host not in {\"skills.sh\", \"www.skills.sh\"}:\n return None\n parts = [p for p in parsed.path.split(\"/\") if p]\n if len(parts) < 3:\n return None\n owner, repo, skill = parts[0], parts[1], parts[2]\n if not owner or not repo or not skill:\n return None\n return owner, repo, skill\n\n\ndef _extract_skillsmp_slug(url: str) -> str:\n parsed = urlparse(url)\n host = (parsed.netloc or \"\").lower()\n if host not in {\"skillsmp.com\", \"www.skillsmp.com\"}:\n return \"\"\n parts = [p for p in parsed.path.split(\"/\") if p]\n if not parts:\n return \"\"\n if \"skills\" in parts:\n idx = parts.index(\"skills\")\n if idx + 1 < len(parts):\n return parts[idx + 1].strip()\n return \"\"\n\n\ndef _extract_lobehub_identifier(url: str) -> str:\n parsed = urlparse(url)\n host = (parsed.netloc or \"\").lower()\n parts = [unquote(p) for p in parsed.path.split(\"/\") if p]\n if not parts:\n return \"\"\n if host in {\"lobehub.com\", \"www.lobehub.com\"}:\n if \"skills\" not in parts:\n return \"\"\n idx = parts.index(\"skills\")\n if idx + 1 < len(parts):\n return parts[idx + 1].strip()\n return \"\"\n if host == \"market.lobehub.com\":\n marker = [\"api\", \"v1\", \"skills\"]\n if len(parts) >= 5 and parts[:3] == marker and parts[4] == \"download\":\n return parts[3].strip()\n return \"\"\n\n\ndef _extract_modelscope_skill_spec(\n url: str,\n) -> tuple[str, str, str] | None:\n \"\"\"\n Parse ModelScope skills URL into (owner, skill_name, version_hint).\n \"\"\"\n parsed = urlparse(url)\n host = (parsed.netloc or \"\").lower()\n if host not in {\"modelscope.cn\", \"www.modelscope.cn\"}:\n return None\n parts = [unquote(p) for p in parsed.path.split(\"/\") if p]\n if len(parts) < 3 or parts[0] != \"skills\":\n return None\n\n owner_part = parts[1].strip()\n skill_name = parts[2].strip()\n if not owner_part or not skill_name:\n return None\n owner = owner_part[1:] if owner_part.startswith(\"@\") else owner_part\n owner = owner.strip()\n if not owner:\n return None\n\n version_hint = \"\"\n if len(parts) >= 6 and parts[3] == \"archive\" and parts[4] == \"zip\":\n archive_name = parts[5].strip()\n if archive_name.endswith(\".zip\"):\n archive_name = archive_name[: -len(\".zip\")]\n version_hint = archive_name\n return owner, skill_name, version_hint\n\n\ndef _extract_github_spec(\n url: str,\n) -> tuple[str, str, str, str] | None:\n \"\"\"\n Parse GitHub repo/tree/blob URL into (owner, repo, branch, path_hint).\n \"\"\"\n parsed = urlparse(url)\n host = (parsed.netloc or \"\").lower()\n if host not in {\"github.com\", \"www.github.com\"}:\n return None\n parts = [unquote(p) for p in parsed.path.split(\"/\") if p]\n if len(parts) < 2:\n return None\n owner, repo = parts[0], parts[1]\n branch = \"\"\n path_hint = \"\"\n # /owner/repo/tree//\n if len(parts) >= 4 and parts[2] in {\"tree\", \"blob\"}:\n branch = parts[3]\n if len(parts) > 4:\n path_hint = \"/\".join(parts[4:])\n elif len(parts) > 2:\n # e.g. /owner/repo/, treat as path hint\n path_hint = \"/\".join(parts[2:])\n return owner, repo, branch, path_hint\n\n\ndef _github_repo_exists(owner: str, repo: str) -> bool:\n if not owner or not repo:\n return False\n try:\n data = _http_json_get(_github_api_url(owner, repo, \"\"))\n return isinstance(data, dict) and data.get(\"full_name\") is not None\n except Exception:\n return False\n\n\n# pylint: disable-next=too-many-return-statements,too-many-branches\ndef _extract_skillsmp_spec(\n url: str,\n) -> tuple[str, str, str] | None:\n \"\"\"\n Parse SkillsMP URL slug into (owner, repo, skill_hint).\n\n Example:\n openclaw-openclaw-skills-himalaya-skill-md\n -> owner=openclaw, repo=openclaw-skills, skill_hint=himalaya\n \"\"\"\n slug = _extract_skillsmp_slug(url)\n if not slug:\n return None\n if slug.endswith(\"-skill-md\"):\n slug = slug[: -len(\"-skill-md\")]\n tokens = [t for t in slug.split(\"-\") if t]\n if len(tokens) < 3:\n return None\n\n owner = tokens[0]\n tail_tokens = tokens[1:]\n # Try repo split points and pick the first repo that exists on GitHub.\n # Keep requests bounded to avoid rate-limit pressure.\n max_split = min(len(tail_tokens), 6)\n for i in range(max_split, 0, -1):\n repo = \"-\".join(tail_tokens[:i]).strip()\n if not repo:\n continue\n if not _github_repo_exists(owner, repo):\n continue\n remainder = tail_tokens[i:]\n skill_hint = \"-\".join(remainder).strip() if remainder else \"\"\n return owner, repo, skill_hint\n\n # Conservative fallback when repo existence checks fail\n repo = tail_tokens[0]\n skill_hint = \"-\".join(tail_tokens[1:]).strip()\n return owner, repo, skill_hint\n\n\ndef _resolve_clawhub_slug(bundle_url: str) -> str:\n from_url = _extract_clawhub_slug_from_url(bundle_url)\n if from_url:\n return from_url\n return \"\"\n\n\ndef _github_api_url(owner: str, repo: str, suffix: str) -> str:\n base = f\"https://api.github.com/repos/{owner}/{repo}\"\n cleaned = suffix.lstrip(\"/\")\n return f\"{base}/{cleaned}\" if cleaned else base\n\n\ndef _github_encode_path(path: str) -> str:\n cleaned = path.strip(\"/\")\n if not cleaned:\n return \"\"\n return quote(cleaned, safe=\"/\")\n\n\ndef _github_get_default_branch(owner: str, repo: str) -> str:\n repo_meta = _http_json_get(_github_api_url(owner, repo, \"\"))\n if isinstance(repo_meta, dict):\n branch = repo_meta.get(\"default_branch\")\n if isinstance(branch, str) and branch.strip():\n return branch.strip()\n return \"main\"\n\n\ndef _normalize_skill_key(text: str) -> str:\n return re.sub(r\"[^a-z0-9]+\", \"-\", text.lower()).strip(\"-\")\n\n\ndef _github_list_skill_md_roots(\n owner: str,\n repo: str,\n ref: str,\n) -> list[str]:\n tree_url = _github_api_url(owner, repo, f\"git/trees/{ref}\")\n try:\n data = _http_json_get(tree_url, {\"recursive\": \"1\"})\n except HTTPError as e:\n if getattr(e, \"code\", 0) == 404:\n return []\n raise\n if not isinstance(data, dict):\n return []\n tree = data.get(\"tree\")\n if not isinstance(tree, list):\n return []\n roots: list[str] = []\n for item in tree:\n if not isinstance(item, dict):\n continue\n path = item.get(\"path\")\n if not isinstance(path, str):\n continue\n if path == \"SKILL.md\":\n roots.append(\"\")\n continue\n if path.endswith(\"/SKILL.md\"):\n roots.append(path[: -len(\"/SKILL.md\")])\n # Keep order stable and unique\n seen: set[str] = set()\n unique: list[str] = []\n for root in roots:\n if root in seen:\n continue\n seen.add(root)\n unique.append(root)\n return unique\n\n\ndef _github_get_content_entry(\n owner: str,\n repo: str,\n path: str,\n ref: str,\n) -> dict[str, Any]:\n encoded_path = _github_encode_path(path)\n content_url = _github_api_url(owner, repo, f\"contents/{encoded_path}\")\n data = _http_json_get(content_url, {\"ref\": ref})\n if not isinstance(data, dict):\n raise ValueError(f\"Unexpected GitHub response for path: {path}\")\n return data\n\n\ndef _github_get_dir_entries(\n owner: str,\n repo: str,\n path: str,\n ref: str,\n) -> list[dict[str, Any]]:\n encoded_path = _github_encode_path(path)\n suffix = \"contents\" if not encoded_path else f\"contents/{encoded_path}\"\n content_url = _github_api_url(owner, repo, suffix)\n data = _http_json_get(content_url, {\"ref\": ref})\n if isinstance(data, list):\n return [x for x in data if isinstance(x, dict)]\n return []\n\n\ndef _github_read_file(entry: dict[str, Any]) -> str:\n download_url = entry.get(\"download_url\")\n if isinstance(download_url, str) and download_url:\n return _http_text_get(download_url)\n\n content = entry.get(\"content\")\n if isinstance(content, str) and content:\n try:\n normalized = content.replace(\"\\n\", \"\")\n return base64.b64decode(normalized).decode(\n \"utf-8\",\n errors=\"replace\",\n )\n except Exception:\n pass\n\n raise ValueError(\"Unable to read file content from GitHub entry\")\n\n\ndef _join_repo_path(root: str, leaf: str) -> str:\n if not root:\n return leaf\n return f\"{root.rstrip('/')}/{leaf.lstrip('/')}\"\n\n\ndef _relative_from_root(full_path: str, root: str) -> str:\n if not root:\n return full_path.lstrip(\"/\")\n prefix = f\"{root.rstrip('/')}/\"\n if full_path.startswith(prefix):\n return full_path[len(prefix) :]\n return full_path\n\n\ndef _github_collect_tree_files(\n owner: str,\n repo: str,\n ref: str,\n root: str,\n max_files: int = 200,\n) -> dict[str, str]:\n files: dict[str, str] = {}\n pending = [root] if root else [\"\"]\n visited = 0\n while pending:\n _ensure_not_cancelled()\n current_dir = pending.pop()\n target_dir = current_dir or \"\"\n entries = _github_get_dir_entries(owner, repo, target_dir, ref)\n for entry in entries:\n _ensure_not_cancelled()\n entry_type = str(entry.get(\"type\") or \"\")\n entry_path = str(entry.get(\"path\") or \"\")\n if not entry_path:\n continue\n if entry_type == \"dir\":\n pending.append(entry_path)\n continue\n if entry_type != \"file\":\n continue\n rel = _relative_from_root(entry_path, root)\n files[rel] = _github_read_file(entry)\n visited += 1\n if visited >= max_files:\n logger.warning(\n \"Hub file collection capped at %d files\",\n max_files,\n )\n return files\n return files\n\n\n# pylint: disable-next=too-many-branches,too-many-statements\ndef _fetch_bundle_from_skills_sh_url(\n bundle_url: str,\n requested_version: str,\n) -> tuple[Any, str]:\n spec = _extract_skills_sh_spec(bundle_url)\n if spec is None:\n raise ValueError(\"Invalid skills.sh URL format\")\n owner, repo, skill = spec\n if requested_version.strip():\n branch_candidates = [requested_version.strip()]\n else:\n # Prefer repo default branch (e.g. master).\n default_branch = _github_get_default_branch(owner, repo)\n branch_candidates = [default_branch] if default_branch else []\n for b in (\"main\", \"master\"):\n if b and b not in branch_candidates:\n branch_candidates.append(b)\n\n selected_root = \"\"\n skill_md_entry: dict[str, Any] | None = None\n branch = branch_candidates[0]\n for candidate_branch in branch_candidates:\n branch = candidate_branch\n roots = [\n _join_repo_path(\"skills\", skill),\n skill,\n \"\",\n ]\n for root in roots:\n skill_md_path = _join_repo_path(root, \"SKILL.md\")\n try:\n entry = _github_get_content_entry(\n owner,\n repo,\n skill_md_path,\n branch,\n )\n except HTTPError as e:\n if getattr(e, \"code\", 0) == 404:\n continue\n raise\n if str(entry.get(\"type\") or \"\") == \"file\":\n selected_root = root\n skill_md_entry = entry\n break\n if skill_md_entry is not None:\n break\n\n if skill_md_entry is None:\n # Fallback: discover skill roots from repo tree and fuzzy-match.\n skill_norm = _normalize_skill_key(skill)\n for candidate_branch in branch_candidates:\n branch = candidate_branch\n for root in _github_list_skill_md_roots(owner, repo, branch):\n leaf = root.split(\"/\")[-1] if root else root\n leaf_norm = _normalize_skill_key(leaf)\n if not leaf_norm:\n continue\n if (\n leaf_norm == skill_norm\n or leaf_norm in skill_norm\n or skill_norm in leaf_norm\n or skill_norm.endswith(f\"-{leaf_norm}\")\n ):\n selected_root = root\n skill_md_path = _join_repo_path(root, \"SKILL.md\")\n try:\n entry = _github_get_content_entry(\n owner,\n repo,\n skill_md_path,\n branch,\n )\n except HTTPError:\n continue\n if str(entry.get(\"type\") or \"\") == \"file\":\n skill_md_entry = entry\n break\n if skill_md_entry is not None:\n break\n\n if skill_md_entry is None:\n raise ValueError(\n \"Could not find SKILL.md from skills.sh source. \"\n \"This skill may not expose SKILL.md in the repository.\",\n )\n\n files: dict[str, str] = {\"SKILL.md\": _github_read_file(skill_md_entry)}\n files.update(\n _github_collect_tree_files(\n owner=owner,\n repo=repo,\n ref=branch,\n root=selected_root,\n ),\n )\n\n source_url = f\"https://github.com/{owner}/{repo}\"\n return {\"name\": skill, \"files\": files}, source_url\n\n\n# pylint: disable-next=too-many-branches,too-many-statements\ndef _fetch_bundle_from_repo_and_skill_hint(\n *,\n owner: str,\n repo: str,\n skill_hint: str,\n requested_version: str,\n default_branch: str = \"main\",\n) -> tuple[Any, str]:\n branch_candidates = (\n [requested_version.strip()]\n if requested_version.strip()\n else [\"main\", \"master\"]\n )\n if default_branch and default_branch not in branch_candidates:\n branch_candidates.append(default_branch)\n skill = skill_hint.strip()\n\n selected_root = \"\"\n skill_md_entry: dict[str, Any] | None = None\n branch = branch_candidates[0]\n for candidate_branch in branch_candidates:\n branch = candidate_branch\n roots = [\n _join_repo_path(\"skills\", skill) if skill else \"\",\n skill,\n \"\",\n ]\n roots = [r for r in roots if r or r == \"\"]\n for root in roots:\n skill_md_path = _join_repo_path(root, \"SKILL.md\")\n try:\n entry = _github_get_content_entry(\n owner,\n repo,\n skill_md_path,\n branch,\n )\n except HTTPError as e:\n if getattr(e, \"code\", 0) == 404:\n continue\n raise\n if str(entry.get(\"type\") or \"\") == \"file\":\n selected_root = root\n skill_md_entry = entry\n break\n if skill_md_entry is not None:\n break\n\n if skill_md_entry is None:\n skill_norm = _normalize_skill_key(skill)\n for candidate_branch in branch_candidates:\n branch = candidate_branch\n for root in _github_list_skill_md_roots(owner, repo, branch):\n leaf = root.split(\"/\")[-1] if root else root\n leaf_norm = _normalize_skill_key(leaf)\n if not leaf_norm:\n continue\n if not skill_norm or (\n leaf_norm == skill_norm\n or leaf_norm in skill_norm\n or skill_norm in leaf_norm\n or skill_norm.endswith(f\"-{leaf_norm}\")\n ):\n selected_root = root\n skill_md_path = _join_repo_path(root, \"SKILL.md\")\n try:\n entry = _github_get_content_entry(\n owner,\n repo,\n skill_md_path,\n branch,\n )\n except HTTPError:\n continue\n if str(entry.get(\"type\") or \"\") == \"file\":\n skill_md_entry = entry\n break\n if skill_md_entry is not None:\n break\n\n if skill_md_entry is None:\n raise ValueError(\n f\"Could not find SKILL.md in source repository \"\n f\"https://github.com/{owner}/{repo}. \"\n f\"Path hint: {skill_hint!r}; tried branches: {branch_candidates}. \"\n \"Ensure the URL points to a folder containing SKILL.md, e.g. \"\n \"https://github.com/owner/repo/tree/master/skills/skill-name\",\n )\n\n files: dict[str, str] = {\"SKILL.md\": _github_read_file(skill_md_entry)}\n files.update(\n _github_collect_tree_files(\n owner=owner,\n repo=repo,\n ref=branch,\n root=selected_root,\n ),\n )\n source_url = f\"https://github.com/{owner}/{repo}\"\n skill_name = skill.split(\"/\")[-1].strip() if skill else repo\n return {\"name\": skill_name or repo, \"files\": files}, source_url\n\n\ndef _fetch_bundle_from_github_url(\n bundle_url: str,\n requested_version: str,\n) -> tuple[Any, str]:\n spec = _extract_github_spec(bundle_url)\n if spec is None:\n raise ValueError(\n \"Invalid GitHub URL format. Use a repo or path URL, e.g. \"\n \"https://github.com/owner/repo or \"\n \"https://github.com/owner/repo/tree/branch/path/to/skill\",\n )\n owner, repo, branch_in_url, path_hint = spec\n path_hint = path_hint.strip(\"/\")\n # If path points directly to SKILL.md, normalize to its parent directory.\n if path_hint.endswith(\"/SKILL.md\"):\n path_hint = path_hint[: -len(\"/SKILL.md\")]\n elif path_hint == \"SKILL.md\":\n path_hint = \"\"\n branch = requested_version.strip() or branch_in_url.strip()\n default_branch = \"\"\n try:\n default_branch = _github_get_default_branch(owner, repo)\n except Exception:\n pass\n return _fetch_bundle_from_repo_and_skill_hint(\n owner=owner,\n repo=repo,\n skill_hint=path_hint,\n requested_version=branch,\n default_branch=default_branch or \"main\",\n )\n\n\ndef _fetch_bundle_from_skillsmp_url(\n bundle_url: str,\n requested_version: str,\n) -> tuple[Any, str]:\n spec = _extract_skillsmp_spec(bundle_url)\n if spec is None:\n raise ValueError(\"Invalid skillsmp URL format\")\n owner, repo, skill_hint = spec\n return _fetch_bundle_from_repo_and_skill_hint(\n owner=owner,\n repo=repo,\n skill_hint=skill_hint,\n requested_version=requested_version,\n )\n\n\ndef _lobehub_download_url(identifier: str) -> str:\n return \"https://market.lobehub.com/api/v1/skills/\" f\"{identifier}/download\"\n\n\ndef _lobehub_zip_to_bundle(identifier: str, payload: bytes) -> dict[str, Any]:\n try:\n with zipfile.ZipFile(io.BytesIO(payload)) as zf:\n files: dict[str, str] = {}\n entry_count = 0\n total_bytes = 0\n for info in zf.infolist():\n if info.is_dir():\n continue\n entry_count += 1\n if entry_count > LOBEHUB_MAX_ZIP_ENTRIES:\n raise ValueError(\n \"LobeHub skill package has too many files\",\n )\n total_bytes += max(0, info.file_size)\n if total_bytes > LOBEHUB_MAX_ZIP_BYTES:\n raise ValueError(\n \"LobeHub skill package is too large to import\",\n )\n parts = _safe_path_parts(info.filename.replace(\"\\\\\", \"/\"))\n if not parts:\n continue\n if not _should_keep_lobehub_file(parts):\n continue\n rel_path = \"/\".join(parts)\n raw = zf.read(info)\n if not _is_probably_text_blob(raw):\n logger.warning(\n \"Skipping non-text file from LobeHub package: %s\",\n rel_path,\n )\n continue\n files[rel_path] = raw.decode(\"utf-8\", errors=\"replace\")\n except zipfile.BadZipFile as e:\n message = _extract_error_message_from_payload(payload)\n if message:\n raise ValueError(\n f\"LobeHub skill download failed: {message}\",\n ) from e\n raise ValueError(\n \"LobeHub skill download did not return a valid zip\",\n ) from e\n\n if \"SKILL.md\" not in files:\n raise ValueError(\"LobeHub skill package is missing SKILL.md\")\n try:\n post = frontmatter.loads(files[\"SKILL.md\"])\n except yaml.YAMLError:\n post = None\n skill_name = post.get(\"name\") if post is not None else None\n if not isinstance(skill_name, str) or not skill_name.strip():\n skill_name = identifier\n return {\"name\": skill_name.strip(), \"files\": files}\n\n\ndef _fetch_bundle_from_modelscope_url(\n bundle_url: str,\n requested_version: str,\n) -> tuple[Any, str]:\n spec = _extract_modelscope_skill_spec(bundle_url)\n if spec is None:\n raise ValueError(\n \"Invalid ModelScope URL format. Use URL like \"\n \"https://modelscope.cn/skills/@owner/skill-name\",\n )\n owner, skill_name, version_hint = spec\n detail_url = f\"https://modelscope.cn/api/v1/skills/@{owner}/{skill_name}\"\n try:\n detail = _http_json_get(detail_url)\n except HTTPError as e:\n raise ValueError(\n \"ModelScope skill lookup failed: \"\n f\"{_lobehub_http_error_message(e)}\",\n ) from e\n\n payload = detail.get(\"Data\") if isinstance(detail, dict) else None\n if not isinstance(payload, dict):\n payload = {}\n source_url = payload.get(\"SourceURL\")\n source_url = source_url.strip() if isinstance(source_url, str) else \"\"\n source_lower = source_url.lower()\n preferred_version = requested_version.strip() or version_hint\n\n if source_url and _is_http_url(source_url):\n if \"github.com\" in source_lower:\n bundle, _ = _fetch_bundle_from_github_url(\n source_url,\n preferred_version,\n )\n return bundle, bundle_url\n if \"clawhub.ai\" in source_lower:\n clawhub_slug = _resolve_clawhub_slug(source_url)\n if clawhub_slug:\n try:\n bundle, _ = _fetch_bundle_from_clawhub_slug(\n clawhub_slug,\n preferred_version,\n )\n return bundle, bundle_url\n except Exception as e:\n inner = str(e).strip()\n # Drop ClawHub prefix from inner to avoid showing two URLs.\n if inner.startswith(\"When importing from ClawHub: \"):\n inner = (\n re.sub(\n r\"^When importing from ClawHub:\\s*https?://\\S+\"\n r\"(?:\\s*:\\s*)?\",\n \"\",\n inner,\n count=1,\n ).strip()\n or inner\n )\n msg = (\n f\"When importing from ModelScope ({bundle_url}): \"\n f\"{inner}\"\n )\n raise RuntimeError(msg) from e\n\n readme_content = payload.get(\"ReadMeContent\")\n if isinstance(readme_content, str) and readme_content.strip():\n fallback_name = (\n str(payload.get(\"Name\") or skill_name).strip() or skill_name\n )\n return {\n \"name\": fallback_name,\n \"files\": {\"SKILL.md\": readme_content},\n }, bundle_url\n\n raise ValueError(\n \"ModelScope skill source is unsupported and ReadMeContent is empty. \"\n \"Please import from the original source URL directly.\",\n )\n\n\ndef _fetch_bundle_from_lobehub_url(\n bundle_url: str,\n requested_version: str,\n) -> tuple[Any, str]:\n identifier = _extract_lobehub_identifier(bundle_url)\n if not identifier:\n raise ValueError(\"Invalid LobeHub skill URL format\")\n params = (\n {\"version\": requested_version.strip()}\n if requested_version.strip()\n else None\n )\n try:\n payload = _http_bytes_get(\n _lobehub_download_url(identifier),\n params=params,\n accept=\"application/zip, application/octet-stream, */*\",\n max_bytes=LOBEHUB_MAX_ZIP_BYTES,\n )\n except HTTPError as e:\n raise ValueError(\n \"LobeHub skill download failed: \"\n f\"{_lobehub_http_error_message(e)}\",\n ) from e\n except ValueError as e:\n raise ValueError(f\"LobeHub skill download failed: {e}\") from e\n return _lobehub_zip_to_bundle(identifier, payload), bundle_url\n\n\ndef _fetch_bundle_from_clawhub_slug(\n slug: str,\n version: str,\n) -> tuple[Any, str]:\n if not slug:\n raise ValueError(\"slug is required for clawhub install\")\n base = _hub_base_url()\n errors: list[str] = []\n candidates = [\n _join_url(base, _hub_detail_path().format(slug=slug)),\n ]\n data: Any | None = None\n source_url = \"\"\n for candidate in candidates:\n try:\n data = _http_json_get(candidate)\n source_url = candidate\n break\n except Exception as e:\n errors.append(f\"{candidate}: {e}\")\n if data is None:\n raise RuntimeError(\n \"When importing from ClawHub: \" + \"; \".join(errors),\n )\n return (\n _hydrate_clawhub_payload(\n data,\n slug=slug,\n requested_version=version,\n ),\n source_url,\n )\n\n\ndef search_hub_skills(query: str, limit: int = 20) -> list[HubSkillResult]:\n base = _hub_base_url()\n search_url = _join_url(base, _hub_search_path())\n data = _http_json_get(search_url, {\"q\": query, \"limit\": limit})\n items = _norm_search_items(data)\n results: list[HubSkillResult] = []\n for item in items:\n slug = str(item.get(\"slug\") or item.get(\"name\") or \"\").strip()\n if not slug:\n continue\n results.append(\n HubSkillResult(\n slug=slug,\n name=str(\n item.get(\"name\") or item.get(\"displayName\") or slug,\n ),\n description=str(\n item.get(\"description\") or item.get(\"summary\") or \"\",\n ),\n version=str(item.get(\"version\") or \"\"),\n source_url=str(item.get(\"url\") or \"\"),\n ),\n )\n return results\n\n\ndef _resolve_bundle_from_url(\n bundle_url: str,\n version: str,\n) -> tuple[Any, str]:\n fetcher: Any | None = None\n clawhub_slug = \"\"\n if _extract_skills_sh_spec(bundle_url) is not None:\n fetcher = _fetch_bundle_from_skills_sh_url\n elif _extract_github_spec(bundle_url) is not None:\n fetcher = _fetch_bundle_from_github_url\n elif _extract_lobehub_identifier(bundle_url):\n fetcher = _fetch_bundle_from_lobehub_url\n elif _extract_modelscope_skill_spec(bundle_url) is not None:\n fetcher = _fetch_bundle_from_modelscope_url\n elif _extract_skillsmp_slug(bundle_url):\n fetcher = _fetch_bundle_from_skillsmp_url\n else:\n clawhub_slug = _resolve_clawhub_slug(bundle_url)\n\n if fetcher is not None:\n return fetcher(bundle_url, requested_version=version)\n if clawhub_slug:\n return _fetch_bundle_from_clawhub_slug(clawhub_slug, version)\n # Backward-compatible fallback for direct bundle JSON URLs.\n return _http_json_get(bundle_url), bundle_url\n\n\n# pylint: disable-next=too-many-branches\ndef install_skill_from_hub(\n *,\n workspace_dir: Path,\n bundle_url: str,\n version: str = \"\",\n enable: bool = True,\n overwrite: bool = False,\n cancel_checker: Any | None = None,\n) -> HubInstallResult:\n if not bundle_url or not _is_http_url(bundle_url):\n raise ValueError(\"bundle_url must be a valid http(s) URL\")\n with _with_cancel_checker(cancel_checker):\n _ensure_not_cancelled()\n data, source_url = _resolve_bundle_from_url(bundle_url, version)\n\n name, content, references, scripts, extra_files = _normalize_bundle(\n data,\n )\n if not name:\n fallback = urlparse(bundle_url).path.strip(\"/\").split(\"/\")[-1]\n name = _safe_fallback_name(fallback)\n # Sanitize: \"Excel / XLSX\" etc. must not be used as dir name\n name = _sanitize_skill_dir_name(name)\n\n _ensure_not_cancelled()\n skill_service = SkillService(workspace_dir)\n created = skill_service.create_skill(\n name=name,\n content=content,\n overwrite=overwrite,\n references=references,\n scripts=scripts,\n extra_files=extra_files,\n )\n if not created:\n raise RuntimeError(\n f\"Failed to create skill '{name}'. \"\n \"This skill already exists.\",\n )\n\n _ensure_not_cancelled()\n enabled = False\n if enable:\n enabled = skill_service.enable_skill(name, force=True)\n if not enabled:\n logger.warning(\"Skill '%s' imported but enable failed\", name)\n\n return HubInstallResult(\n name=name,\n enabled=enabled,\n source_url=source_url,\n )\n" }, { "path": "src/copaw/agents/skills_manager.py", "content": "# -*- coding: utf-8 -*-\n\"\"\"Skills management: sync skills from code to working_dir.\"\"\"\n\nimport io\nimport logging\nimport re\nimport shutil\nimport tempfile\nimport zipfile\nfrom pathlib import Path\nfrom typing import Any\nfrom pydantic import BaseModel\nimport frontmatter\nfrom packaging.version import Version\n\n\nlogger = logging.getLogger(__name__)\n\n\ndef _dedupe_skills_by_name(skills: list[\"SkillInfo\"]) -> list[\"SkillInfo\"]:\n \"\"\"Return one skill per name, preferring customized over builtin.\"\"\"\n merged: dict[str, SkillInfo] = {}\n for skill in skills:\n merged[skill.name] = skill\n return list(merged.values())\n\n\nclass SkillInfo(BaseModel):\n \"\"\"Skill information structure.\n\n The references and scripts fields represent directory trees\n as nested dicts.\n\n When reading existing skills:\n - Files are represented as {filename: None}\n - Directories are represented as {dirname: {nested_structure}}\n\n When creating new skills via SkillService.create_skill:\n - Files are represented as {filename: \"content\"}\n - Directories are represented as {dirname: {nested_structure}}\n\n Example (reading):\n {\n \"file.txt\": None,\n \"subdir\": {\n \"nested.py\": None,\n \"deeper\": {\n \"file.sh\": None\n }\n }\n }\n \"\"\"\n\n name: str\n description: str = \"\"\n content: str\n source: str # \"builtin\", \"customized\", or \"active\"\n path: str\n references: dict[str, Any] = {}\n scripts: dict[str, Any] = {}\n\n\ndef get_builtin_skills_dir() -> Path:\n \"\"\"Get the path to built-in skills directory in the code.\"\"\"\n return Path(__file__).parent / \"skills\"\n\n\ndef get_customized_skills_dir(workspace_dir: Path) -> Path:\n \"\"\"Get the path to customized skills directory in workspace_dir.\"\"\"\n return workspace_dir / \"customized_skills\"\n\n\ndef get_active_skills_dir(workspace_dir: Path) -> Path:\n \"\"\"Get the path to active skills directory in workspace_dir.\"\"\"\n return workspace_dir / \"active_skills\"\n\n\ndef get_working_skills_dir(workspace_dir: Path) -> Path:\n \"\"\"\n Get the path to skills directory in workspace_dir.\n\n Deprecated: Use get_active_skills_dir() instead.\n \"\"\"\n return get_active_skills_dir(workspace_dir)\n\n\ndef _build_directory_tree(directory: Path) -> dict[str, Any]:\n \"\"\"\n Recursively build a directory tree structure.\n\n Args:\n directory: Directory to scan.\n\n Returns:\n Dictionary representing the tree structure where:\n - Files are represented as {filename: None}\n - Directories are represented as {dirname: {nested_structure}}\n\n Example:\n {\n \"file1.txt\": None,\n \"subdir\": {\n \"file2.py\": None,\n \"nested\": {\n \"file3.sh\": None\n }\n }\n }\n \"\"\"\n tree: dict[str, Any] = {}\n\n if not directory.exists() or not directory.is_dir():\n return tree\n\n for item in sorted(directory.iterdir()):\n if item.is_file():\n tree[item.name] = None\n elif item.is_dir():\n tree[item.name] = _build_directory_tree(item)\n\n return tree\n\n\ndef _collect_skills_from_dir(directory: Path) -> dict[str, Path]:\n \"\"\"\n Collect skills from a directory.\n\n Args:\n directory: Directory to scan for skills.\n\n Returns:\n Dictionary mapping skill names to their paths.\n \"\"\"\n skills: dict[str, Path] = {}\n if directory.exists():\n for skill_dir in directory.iterdir():\n if skill_dir.is_dir() and (skill_dir / \"SKILL.md\").exists():\n skills[skill_dir.name] = skill_dir\n return skills\n\n\ndef _get_builtin_skill_version(skill_dir: Path) -> Version | None:\n \"\"\"Read ``builtin_skill_version`` from SKILL.md front matter.\"\"\"\n skill_md = skill_dir / \"SKILL.md\"\n if not skill_md.exists():\n return None\n try:\n content = skill_md.read_text(encoding=\"utf-8\")\n post = frontmatter.loads(content)\n metadata = post.get(\"metadata\") or {}\n ver = metadata.get(\"builtin_skill_version\")\n if ver is not None:\n return Version(str(ver))\n except Exception as e:\n logger.warning(\n \"Could not parse version for skill '%s' from '%s': %s\",\n skill_dir.name,\n skill_md,\n e,\n )\n return None\n\n\ndef _replace_skill_dir(source: Path, target: Path) -> None:\n \"\"\"Remove *target* (if it exists) and copy *source* in its place.\"\"\"\n if target.exists():\n shutil.rmtree(target)\n shutil.copytree(source, target)\n\n\ndef _skill_md_differs(dir_a: Path, dir_b: Path) -> bool:\n \"\"\"Return True when the SKILL.md files in two dirs have different\n content (or one side is missing).\"\"\"\n md_a = dir_a / \"SKILL.md\"\n md_b = dir_b / \"SKILL.md\"\n if not md_a.exists() or not md_b.exists():\n return True\n return md_a.read_text(encoding=\"utf-8\") != md_b.read_text(\n encoding=\"utf-8\",\n )\n\n\ndef sync_skills_to_working_dir(\n workspace_dir: Path,\n skill_names: list[str] | None = None,\n force: bool = False,\n) -> tuple[int, int]:\n \"\"\"\n Sync skills from builtin and customized to active_skills directory.\n\n Args:\n workspace_dir: Workspace directory path.\n skill_names: List of skill names to sync. If None, sync all skills.\n force: If True, overwrite existing skills in active_skills.\n\n Returns:\n Tuple of (synced_count, skipped_count).\n \"\"\"\n builtin_skills = get_builtin_skills_dir()\n customized_skills = get_customized_skills_dir(workspace_dir)\n active_skills = get_active_skills_dir(workspace_dir)\n\n # Ensure active skills directory exists\n active_skills.mkdir(parents=True, exist_ok=True)\n\n # Collect skills from both sources (customized overwrites builtin)\n skills_to_sync = _collect_skills_from_dir(builtin_skills)\n if not skills_to_sync and not builtin_skills.exists():\n logger.warning(\n \"Built-in skills directory not found: %s\",\n builtin_skills,\n )\n\n # Customized skills override builtin with same name\n skills_to_sync.update(_collect_skills_from_dir(customized_skills))\n\n # Filter by skill_names if specified\n if skill_names is not None:\n filtered_skills: dict[str, Path] = {}\n for name, path in skills_to_sync.items():\n if name in skill_names:\n filtered_skills[name] = path\n skills_to_sync = filtered_skills\n\n if not skills_to_sync:\n logger.debug(\"No skills to sync.\")\n return 0, 0\n\n synced_count = 0\n skipped_count = 0\n\n for skill_name, skill_dir in skills_to_sync.items():\n target_dir = active_skills / skill_name\n\n if not target_dir.exists() or force:\n _replace_skill_dir(skill_dir, target_dir)\n logger.debug(\n \"Synced skill '%s' to active_skills.\",\n skill_name,\n )\n synced_count += 1\n continue\n\n # Customized override: propagate customized → active\n customized_dir = customized_skills / skill_name\n if customized_dir.exists() and _skill_md_differs(\n customized_dir,\n target_dir,\n ):\n _replace_skill_dir(customized_dir, target_dir)\n logger.debug(\n \"Customized skill '%s' updated in active_skills.\",\n skill_name,\n )\n synced_count += 1\n continue\n\n skipped_count += 1\n\n return synced_count, skipped_count\n\n\ndef sync_skills_from_active_to_customized(\n workspace_dir: Path,\n skill_names: list[str] | None = None,\n) -> tuple[int, int]:\n \"\"\"\n Sync skills from active_skills to customized_skills directory.\n\n Args:\n workspace_dir: Workspace directory path.\n skill_names: List of skill names to sync. If None, sync all skills.\n\n Returns:\n Tuple of (synced_count, skipped_count).\n \"\"\"\n active_skills = get_active_skills_dir(workspace_dir)\n customized_skills = get_customized_skills_dir(workspace_dir)\n builtin_skills = get_builtin_skills_dir()\n\n customized_skills.mkdir(parents=True, exist_ok=True)\n\n active_skills_dict = _collect_skills_from_dir(active_skills)\n if not active_skills_dict:\n logger.debug(\"No skills found in active_skills.\")\n return 0, 0\n\n builtin_skills_dict = _collect_skills_from_dir(builtin_skills)\n\n synced_count = 0\n skipped_count = 0\n\n for skill_name, skill_dir in active_skills_dict.items():\n if skill_names is not None and skill_name not in skill_names:\n continue\n\n # Builtin skill: check version upgrade, skip back-sync\n if skill_name in builtin_skills_dict:\n builtin_dir = builtin_skills_dict[skill_name]\n active_ver = _get_builtin_skill_version(skill_dir)\n builtin_ver = _get_builtin_skill_version(builtin_dir)\n if (\n active_ver is not None\n and builtin_ver is not None\n and builtin_ver > active_ver\n ):\n _replace_skill_dir(builtin_dir, skill_dir)\n logger.debug(\n \"Builtin skill '%s' updated in \"\n \"active_skills (v%s -> v%s).\",\n skill_name,\n active_ver,\n builtin_ver,\n )\n synced_count += 1\n else:\n skipped_count += 1\n continue\n\n # Non-builtin: back-sync to customized (first-time only)\n target_dir = customized_skills / skill_name\n if target_dir.exists():\n skipped_count += 1\n continue\n\n try:\n shutil.copytree(skill_dir, target_dir)\n logger.debug(\n \"Synced skill '%s' from active_skills to \"\n \"customized_skills.\",\n skill_name,\n )\n synced_count += 1\n except Exception as e:\n logger.debug(\n \"Failed to sync skill '%s' to customized_skills: %s\",\n skill_name,\n e,\n )\n\n return synced_count, skipped_count\n\n\ndef list_available_skills(workspace_dir: Path) -> list[str]:\n \"\"\"\n List all available skills in active_skills directory.\n\n Args:\n workspace_dir: Workspace directory path.\n\n Returns:\n List of skill names.\n \"\"\"\n active_skills = get_active_skills_dir(workspace_dir)\n\n if not active_skills.exists():\n return []\n\n return [\n d.name\n for d in active_skills.iterdir()\n if d.is_dir() and (d / \"SKILL.md\").exists()\n ]\n\n\ndef ensure_skills_initialized(workspace_dir: Path) -> None:\n \"\"\"\n Check if skills are initialized in active_skills directory.\n\n Args:\n workspace_dir: Workspace directory path.\n\n Logs a warning if no skills are found, or info about loaded skills.\n Skills should be configured via `copaw init` or\n `copaw skills config`.\n \"\"\"\n active_skills = get_active_skills_dir(workspace_dir)\n available = list_available_skills(workspace_dir)\n\n if not active_skills.exists() or not available:\n logger.warning(\n \"No skills found in active_skills directory. \"\n \"Run 'copaw init' or 'copaw skills config' \"\n \"to configure skills.\",\n )\n else:\n logger.debug(\n \"Loaded %d skill(s) from active_skills: %s\",\n len(available),\n \", \".join(available),\n )\n\n\ndef _read_skills_from_dir(\n directory: Path,\n source: str,\n) -> list[SkillInfo]:\n \"\"\"\n Read skills from a directory and return SkillInfo list.\n\n Args:\n directory: Directory to read skills from.\n source: Source label for the skills.\n\n Returns:\n List of SkillInfo objects.\n \"\"\"\n skills: list[SkillInfo] = []\n\n if not directory.exists():\n return skills\n\n for skill_dir in directory.iterdir():\n if not skill_dir.is_dir():\n continue\n\n skill_md = skill_dir / \"SKILL.md\"\n if not skill_md.exists():\n continue\n\n try:\n content = skill_md.read_text(encoding=\"utf-8\")\n description = \"\"\n try:\n post = frontmatter.loads(content)\n description = str(post.get(\"description\", \"\") or \"\")\n except Exception as e:\n logger.warning(\n \"Failed to parse SKILL.md frontmatter for skill '%s': %s\",\n skill_dir.name,\n e,\n )\n logger.debug(\n \"Invalid SKILL.md frontmatter/content in '%s': %r\",\n skill_md,\n e,\n )\n description = \"\"\n\n # Build references directory tree\n references = {}\n references_dir = skill_dir / \"references\"\n if references_dir.exists() and references_dir.is_dir():\n references = _build_directory_tree(references_dir)\n\n # Build scripts directory tree\n scripts = {}\n scripts_dir = skill_dir / \"scripts\"\n if scripts_dir.exists() and scripts_dir.is_dir():\n scripts = _build_directory_tree(scripts_dir)\n\n skills.append(\n SkillInfo(\n name=skill_dir.name,\n description=description,\n content=content,\n source=source,\n path=str(skill_dir),\n references=references,\n scripts=scripts,\n ),\n )\n except Exception as e:\n logger.error(\n \"Failed to read skill '%s': %s\",\n skill_dir.name,\n e,\n )\n\n return skills\n\n\ndef _create_files_from_tree(\n base_dir: Path,\n tree: dict[str, Any],\n) -> None:\n \"\"\"\n Create files and directories from a tree structure.\n\n Args:\n base_dir: Base directory to create files in.\n tree: Tree structure where:\n - {filename: str_content} creates a file with content\n - {dirname: {nested_tree}} creates a directory recursively\n\n Raises:\n ValueError: If tree contains invalid value types.\n\n Example:\n tree = {\n \"file.txt\": \"content\",\n \"subdir\": {\n \"nested.py\": \"print('hello')\",\n \"deeper\": {\n \"file.sh\": \"#!/bin/bash\"\n }\n }\n }\n \"\"\"\n if not tree:\n return\n\n for name, value in tree.items():\n item_path = base_dir / name\n\n if value is None or isinstance(value, str):\n # It's a file\n content = value if isinstance(value, str) else \"\"\n item_path.write_text(content, encoding=\"utf-8\")\n elif isinstance(value, dict):\n # It's a directory\n item_path.mkdir(parents=True, exist_ok=True)\n _create_files_from_tree(item_path, value)\n else:\n raise ValueError(\n f\"Invalid tree value for '{name}': {type(value)}. \"\n \"Expected None, str, or dict.\",\n )\n\n\n_MAX_ZIP_BYTES = 200 * 1024 * 1024 # 200 MB uncompressed guard\n\n\ndef _is_hidden(name: str) -> bool:\n \"\"\"Return True for __MACOSX dirs and dotfiles/dotdirs.\"\"\"\n return name.startswith(\"__MACOSX\") or name.startswith(\".\")\n\n\ndef _extract_and_validate_zip(data: bytes, tmp_dir: Path) -> None:\n \"\"\"Extract zip to *tmp_dir* after security validation.\"\"\"\n with zipfile.ZipFile(io.BytesIO(data)) as zf:\n total = sum(i.file_size for i in zf.infolist())\n if total > _MAX_ZIP_BYTES:\n mb = _MAX_ZIP_BYTES // 1024 // 1024\n raise ValueError(\n f\"Uncompressed size exceeds {mb}MB limit\",\n )\n root_path = tmp_dir.resolve()\n for info in zf.infolist():\n target = (tmp_dir / info.filename).resolve()\n if not target.is_relative_to(root_path):\n raise ValueError(\n f\"Unsafe path: {info.filename}\",\n )\n if info.external_attr >> 16 & 0o120000 == 0o120000:\n raise ValueError(\n f\"Symlink not allowed: {info.filename}\",\n )\n zf.extractall(tmp_dir)\n\n\ndef _resolve_skill_name(skill_dir: Path) -> str:\n \"\"\"Read name from SKILL.md frontmatter, fallback to dir name.\"\"\"\n try:\n name = frontmatter.loads(\n (skill_dir / \"SKILL.md\").read_text(encoding=\"utf-8\"),\n ).get(\"name\", \"\")\n if name and isinstance(name, str):\n name = name.strip()\n if re.fullmatch(r\"[a-zA-Z0-9_\\-]+\", name):\n return name\n except Exception:\n pass\n fallback = skill_dir.name\n fallback = re.sub(r\"[^a-zA-Z0-9_\\-]\", \"_\", fallback)\n return fallback or \"unnamed_skill\"\n\n\ndef _find_skill_dirs(root: Path) -> list[tuple[Path, str]]:\n \"\"\"Return (skill_dir, skill_name) pairs found under *root*.\"\"\"\n if (root / \"SKILL.md\").exists():\n return [(root, _resolve_skill_name(root))]\n return [\n (c, _resolve_skill_name(c))\n for c in sorted(root.iterdir())\n if not _is_hidden(c.name) and c.is_dir() and (c / \"SKILL.md\").exists()\n ]\n\n\ndef _import_skill_dir(\n src_dir: Path,\n customized_dir: Path,\n skill_name: str,\n overwrite: bool,\n) -> bool:\n \"\"\"Validate SKILL.md and copy *src_dir* into *customized_dir*.\"\"\"\n try:\n post = frontmatter.loads(\n (src_dir / \"SKILL.md\").read_text(encoding=\"utf-8\"),\n )\n if not post.get(\"name\") or not post.get(\"description\"):\n logger.warning(\n \"Skipping '%s': missing name/description.\",\n skill_name,\n )\n return False\n except Exception as e:\n logger.warning(\n \"Skipping '%s': bad SKILL.md: %s\",\n skill_name,\n e,\n )\n return False\n\n target_dir = customized_dir / skill_name\n if target_dir.exists() and not overwrite:\n return False\n try:\n if target_dir.exists():\n shutil.rmtree(target_dir)\n shutil.copytree(\n src_dir,\n target_dir,\n ignore=shutil.ignore_patterns(\"__MACOSX\", \".*\"),\n )\n logger.info(\"Imported skill '%s' from zip.\", skill_name)\n return True\n except Exception as e:\n logger.error(\n \"Failed to import skill '%s': %s\",\n skill_name,\n e,\n )\n return False\n\n\nclass SkillService:\n \"\"\"\n Service for managing skills.\n\n Manages skills across builtin, customized, and active directories\n for a specific workspace.\n \"\"\"\n\n def __init__(self, workspace_dir: Path):\n \"\"\"\n Initialize SkillService for a specific workspace.\n\n Args:\n workspace_dir: Path to the workspace directory.\n \"\"\"\n self.workspace_dir = workspace_dir\n\n def get_customized_skill_dir(self, name: str) -> Path | None:\n \"\"\"Return the Path to a skill inside customized_skills, or None.\"\"\"\n skill_dir = get_customized_skills_dir(self.workspace_dir) / name\n return skill_dir if skill_dir.exists() else None\n\n def list_all_skills(self) -> list[SkillInfo]:\n \"\"\"\n List all skills from builtin and customized directories.\n\n Returns:\n List of SkillInfo with name, content, source, and path.\n \"\"\"\n try:\n synced, _ = sync_skills_from_active_to_customized(\n self.workspace_dir,\n )\n if synced > 0:\n logger.debug(\n \"Back-synced %d skill(s) from active_skills\",\n synced,\n )\n except Exception as e:\n logger.debug(\n \"Failed to back-sync skills: %s\",\n e,\n )\n\n skills: list[SkillInfo] = []\n\n # Collect from builtin and customized skills. Customized skills\n # override built-in skills with the same name in the UI/API listing.\n skills.extend(\n _read_skills_from_dir(get_builtin_skills_dir(), \"builtin\"),\n )\n skills.extend(\n _read_skills_from_dir(\n get_customized_skills_dir(self.workspace_dir),\n \"customized\",\n ),\n )\n\n return _dedupe_skills_by_name(skills)\n\n def list_available_skills(self) -> list[SkillInfo]:\n \"\"\"\n List all available (active) skills in active_skills directory.\n\n Returns:\n List of SkillInfo with name, content, source, and path.\n \"\"\"\n return _read_skills_from_dir(\n get_active_skills_dir(self.workspace_dir),\n \"active\",\n )\n\n def create_skill(\n self,\n name: str,\n content: str,\n overwrite: bool = False,\n references: dict[str, Any] | None = None,\n scripts: dict[str, Any] | None = None,\n extra_files: dict[str, Any] | None = None,\n ) -> bool:\n \"\"\"\n Create a new skill in customized_skills directory.\n\n Args:\n name: Skill name (will be the directory name).\n content: Content of SKILL.md file.\n overwrite: If True, overwrite existing skill.\n references: Optional tree structure for references/ subdirectory.\n Can be flat {filename: content} or nested\n {dirname: {filename: content}}.\n scripts: Optional tree structure for scripts/ subdirectory.\n Can be flat {filename: content} or nested\n {dirname: {filename: content}}.\n extra_files: Optional tree structure for additional files\n written to skill root (excluding SKILL.md), usually used\n by imported hub skills that contain runtime assets.\n\n Returns:\n True if skill was created successfully, False otherwise.\n\n Examples:\n # Simple flat structure\n create_skill(\n name=\"my_skill\",\n content=\"# My Skill\\\\n...\",\n references={\"doc1.md\": \"content1\"},\n scripts={\"script1.py\": \"print('hello')\"}\n )\n\n # Nested structure\n create_skill(\n name=\"my_skill\",\n content=\"# My Skill\\\\n...\",\n references={\n \"readme.md\": \"# Documentation\",\n \"examples\": {\n \"example1.py\": \"print('example')\",\n \"data\": {\n \"sample.json\": '{\"key\": \"value\"}'\n }\n }\n }\n )\n \"\"\"\n # Validate SKILL.md content has required YAML Front Matter\n try:\n post = frontmatter.loads(content)\n skill_name = post.get(\"name\", None)\n skill_description = post.get(\"description\", None)\n\n if not skill_name or not skill_description:\n logger.error(\n \"SKILL.md content must have YAML Front Matter \"\n \"with 'name' and 'description' fields.\",\n )\n return False\n\n logger.debug(\n \"Validated SKILL.md: name='%s', description='%s'\",\n skill_name,\n skill_description,\n )\n except Exception as e:\n logger.error(\n \"Failed to parse SKILL.md YAML Front Matter: %s\",\n e,\n )\n return False\n\n customized_dir = get_customized_skills_dir(self.workspace_dir)\n customized_dir.mkdir(parents=True, exist_ok=True)\n\n skill_dir = customized_dir / name\n skill_md = skill_dir / \"SKILL.md\"\n\n # Check if skill already exists\n if skill_dir.exists() and not overwrite:\n logger.debug(\n \"Skill '%s' already exists in customized_skills. \"\n \"Use overwrite=True to replace.\",\n name,\n )\n return False\n\n # Create skill directory and SKILL.md\n try:\n # Clean up existing directory if overwriting\n if skill_dir.exists() and overwrite:\n shutil.rmtree(skill_dir)\n\n skill_dir.mkdir(parents=True, exist_ok=True)\n skill_md.write_text(content, encoding=\"utf-8\")\n\n # Create extra files in skill root\n if extra_files:\n _create_files_from_tree(skill_dir, extra_files)\n logger.debug(\n \"Created extra root files for skill '%s'.\",\n name,\n )\n\n # Create references subdirectory and files from tree\n if references:\n references_dir = skill_dir / \"references\"\n references_dir.mkdir(parents=True, exist_ok=True)\n _create_files_from_tree(references_dir, references)\n logger.debug(\n \"Created references structure for skill '%s'.\",\n name,\n )\n\n # Create scripts subdirectory and files from tree\n if scripts:\n scripts_dir = skill_dir / \"scripts\"\n scripts_dir.mkdir(parents=True, exist_ok=True)\n _create_files_from_tree(scripts_dir, scripts)\n logger.debug(\n \"Created scripts structure for skill '%s'.\",\n name,\n )\n\n # --- Security scan (post-write) ----------------------------------\n try:\n from ..security.skill_scanner import (\n SkillScanError,\n scan_skill_directory,\n )\n\n scan_skill_directory(skill_dir, skill_name=name)\n except SkillScanError:\n raise\n except Exception as scan_exc:\n logger.warning(\n \"Security scan error for skill '%s' (non-fatal): %s\",\n name,\n scan_exc,\n )\n # ---------------------------------------------------------------\n\n logger.debug(\"Created skill '%s' in customized_skills.\", name)\n return True\n except Exception as e:\n from ..security.skill_scanner import SkillScanError\n\n if isinstance(e, SkillScanError):\n raise\n logger.error(\n \"Failed to create skill '%s': %s\",\n name,\n e,\n )\n return False\n\n def disable_skill(self, name: str) -> bool:\n \"\"\"\n Disable a skill by removing it from active_skills directory.\n\n Args:\n name: Skill name to disable.\n\n Returns:\n True if skill was disabled successfully, False otherwise.\n \"\"\"\n active_dir = get_active_skills_dir(self.workspace_dir)\n skill_dir = active_dir / name\n\n if not skill_dir.exists():\n logger.debug(\n \"Skill '%s' not found in active_skills.\",\n name,\n )\n return False\n\n try:\n shutil.rmtree(skill_dir)\n logger.debug(\"Disabled skill '%s' from active_skills.\", name)\n return True\n except Exception as e:\n logger.error(\n \"Failed to disable skill '%s': %s\",\n name,\n e,\n )\n return False\n\n def enable_skill(self, name: str, force: bool = False) -> bool:\n \"\"\"\n Enable a skill by syncing it to active_skills directory.\n\n Before syncing the skill runs through a security scan.\n Blocking behaviour is controlled by the scanner mode in\n config (``security.skill_scanner.mode``).\n\n Args:\n name: Skill name to enable.\n force: If True, overwrite existing skill in active_skills.\n\n Returns:\n True if skill was enabled successfully, False otherwise.\n \"\"\"\n # --- Security scan (pre-activation) --------------------------------\n try:\n from ..security.skill_scanner import (\n SkillScanError,\n scan_skill_directory,\n )\n\n source_dir = self.get_customized_skill_dir(name)\n if source_dir is None:\n builtin = get_builtin_skills_dir() / name\n if builtin.is_dir():\n source_dir = builtin\n\n if source_dir is not None:\n scan_skill_directory(source_dir, skill_name=name)\n except SkillScanError:\n raise\n except Exception as scan_exc:\n logger.warning(\n \"Security scan error for skill '%s' (non-fatal): %s\",\n name,\n scan_exc,\n )\n # -------------------------------------------------------------------\n\n sync_skills_to_working_dir(\n self.workspace_dir,\n skill_names=[name],\n force=force,\n )\n # Check if skill was actually synced\n active_dir = get_active_skills_dir(self.workspace_dir)\n return (active_dir / name).exists()\n\n def delete_skill(self, name: str) -> bool:\n \"\"\"\n Delete a skill from customized_skills directory permanently.\n\n This only deletes skills from customized_skills directory.\n Built-in skills cannot be deleted.\n If the skill is currently active, it will remain in active_skills\n until manually disabled.\n\n Args:\n name: Skill name to delete.\n\n Returns:\n True if skill was deleted successfully, False otherwise.\n \"\"\"\n customized_dir = get_customized_skills_dir(self.workspace_dir)\n skill_dir = customized_dir / name\n\n if not skill_dir.exists():\n logger.debug(\n \"Skill '%s' not found in customized_skills.\",\n name,\n )\n return False\n\n try:\n shutil.rmtree(skill_dir)\n logger.debug(\n \"Deleted skill '%s' from customized_skills.\",\n name,\n )\n return True\n except Exception as e:\n logger.error(\n \"Failed to delete skill '%s': %s\",\n name,\n e,\n )\n return False\n\n def sync_from_active_to_customized(\n self,\n skill_names: list[str] | None = None,\n ) -> tuple[int, int]:\n \"\"\"\n Sync skills from active_skills to customized_skills directory.\n\n Args:\n skill_names: List of skill names to sync. If None, sync all skills.\n\n Returns:\n Tuple of (synced_count, skipped_count).\n \"\"\"\n return sync_skills_from_active_to_customized(\n self.workspace_dir,\n skill_names=skill_names,\n )\n\n def import_from_zip(\n self,\n data: bytes,\n overwrite: bool = False,\n enable: bool = False,\n ) -> dict:\n \"\"\"Import skill(s) from a zip archive.\n\n Returns dict with ``imported`` (list of names), ``count``,\n and ``enabled`` flag.\n\n Raises ValueError when zip is invalid or contains no skills.\n \"\"\"\n if not zipfile.is_zipfile(io.BytesIO(data)):\n raise ValueError(\n \"Uploaded file is not a valid zip archive\",\n )\n\n customized_dir = get_customized_skills_dir(\n self.workspace_dir,\n )\n customized_dir.mkdir(parents=True, exist_ok=True)\n tmp_dir: Path | None = None\n try:\n tmp_dir = Path(\n tempfile.mkdtemp(prefix=\"copaw_skill_upload_\"),\n )\n _extract_and_validate_zip(data, tmp_dir)\n\n # Unwrap single wrapper directory\n real = [e for e in tmp_dir.iterdir() if not _is_hidden(e.name)]\n extract_root = (\n real[0] if len(real) == 1 and real[0].is_dir() else tmp_dir\n )\n\n found = _find_skill_dirs(extract_root)\n if not found:\n raise ValueError(\n \"No valid skills found in zip. Each skill \"\n \"directory must contain a SKILL.md with \"\n \"valid YAML frontmatter.\",\n )\n imported = [\n name\n for skill_dir, name in found\n if _import_skill_dir(\n skill_dir,\n customized_dir,\n name,\n overwrite,\n )\n ]\n\n # --- Security scan (post-write) --------------------------\n try:\n from ..security.skill_scanner import (\n SkillScanError,\n scan_skill_directory,\n )\n\n for name in imported:\n scan_skill_directory(\n customized_dir / name,\n skill_name=name,\n )\n except SkillScanError:\n raise\n except Exception as scan_exc:\n logger.warning(\n \"Security scan error during zip import (non-fatal): %s\",\n scan_exc,\n )\n # ---------------------------------------------------------\n\n if enable:\n for name in imported:\n self.enable_skill(name, force=True)\n\n return {\n \"imported\": imported,\n \"count\": len(imported),\n \"enabled\": enable and len(imported) > 0,\n }\n finally:\n if tmp_dir and tmp_dir.is_dir():\n shutil.rmtree(tmp_dir, ignore_errors=True)\n\n def load_skill_file( # pylint: disable=too-many-return-statements\n self,\n skill_name: str,\n file_path: str,\n source: str,\n ) -> str | None:\n \"\"\"\n Load a specific file from a skill's references or scripts directory.\n\n Args:\n skill_name: Name of the skill.\n file_path: Relative path to the file within the skill directory.\n Must start with \"references/\" or \"scripts/\".\n Example: \"references/doc.md\" or \"scripts/utils/helper.py\"\n source: Source directory, must be \"builtin\" or \"customized\".\n\n Returns:\n File content as string, or None if failed.\n\n Examples:\n # Load from customized skills\n content = load_skill_file(\n \"my_skill\",\n \"references/doc.md\",\n \"customized\"\n )\n\n # Load nested file from builtin\n content = load_skill_file(\n \"builtin_skill\",\n \"scripts/utils/helper.py\",\n \"builtin\"\n )\n \"\"\"\n # Validate source\n if source not in {\"builtin\", \"customized\"}:\n logger.error(\n \"Invalid source '%s'. Must be 'builtin' or 'customized'.\",\n source,\n )\n return None\n\n # Normalize separators to forward slash for consistent checking\n normalized = file_path.replace(\"\\\\\", \"/\")\n\n # Validate file_path starts with references/ or scripts/\n is_references = normalized.startswith(\"references/\")\n is_scripts = normalized.startswith(\"scripts/\")\n if not (is_references or is_scripts):\n logger.error(\n \"Invalid file_path '%s'. Must start with refs or scripts.\",\n file_path,\n )\n return None\n\n # Prevent path traversal attacks\n if \"..\" in normalized or normalized.startswith(\"/\"):\n logger.error(\n \"Invalid file_path '%s': path traversal not allowed\",\n file_path,\n )\n return None\n\n # Get source directory\n if source == \"customized\":\n base_dir = get_customized_skills_dir(self.workspace_dir)\n else: # builtin\n base_dir = get_builtin_skills_dir()\n\n skill_dir = base_dir / skill_name\n full_path = skill_dir / normalized\n\n # Check if skill exists\n if not skill_dir.exists():\n logger.debug(\n \"Skill '%s' not found in %s\",\n skill_name,\n source,\n )\n return None\n\n # Check if file exists\n if not full_path.exists():\n logger.debug(\n \"File '%s' not found in skill '%s' (%s)\",\n file_path,\n skill_name,\n source,\n )\n return None\n\n # Check if it's actually a file (not a directory)\n if not full_path.is_file():\n logger.debug(\n \"Path '%s' is not a file in skill '%s' (%s)\",\n file_path,\n skill_name,\n source,\n )\n return None\n\n # Read file content\n try:\n content = full_path.read_text(encoding=\"utf-8\")\n logger.debug(\n \"Loaded file '%s' from skill '%s' (%s)\",\n file_path,\n skill_name,\n source,\n )\n return content\n except Exception as e:\n logger.error(\n \"Failed to read file '%s' from skill '%s': %s\",\n file_path,\n skill_name,\n e,\n )\n return None\n" }, { "path": "src/copaw/agents/tool_guard_mixin.py", "content": "# -*- coding: utf-8 -*-\n\"\"\"Tool-guard mixin for CoPawAgent.\n\nProvides ``_acting`` and ``_reasoning`` overrides that intercept\nsensitive tool calls before execution, implementing the deny /\nguard / approve flow.\n\nSeparated from ``react_agent.py`` to keep the main agent class\nfocused on lifecycle management.\n\"\"\"\nfrom __future__ import annotations\n\nimport json as _json\nimport logging\nfrom typing import Any, Literal\n\nfrom agentscope.message import Msg\n\nfrom ..security.tool_guard.models import TOOL_GUARD_DENIED_MARK\n\nlogger = logging.getLogger(__name__)\n\n\nclass ToolGuardMixin:\n \"\"\"Mixin that adds tool-guard interception to a ReActAgent.\n\n At runtime this class is always combined with\n ``agentscope.agent.ReActAgent`` via MRO, so ``super()._acting``\n and ``super()._reasoning`` resolve to the concrete agent methods.\n \"\"\"\n\n # ------------------------------------------------------------------\n # Lazy initialisation\n # ------------------------------------------------------------------\n\n def _init_tool_guard(self) -> None:\n \"\"\"Lazy-init tool-guard components (called once).\"\"\"\n from copaw.security.tool_guard.engine import get_guard_engine\n from copaw.app.approvals import get_approval_service\n\n self._tool_guard_engine = get_guard_engine()\n self._tool_guard_approval_service = get_approval_service()\n self._tool_guard_pending_info: dict | None = None\n\n def _ensure_tool_guard(self) -> None:\n if not hasattr(self, \"_tool_guard_engine\"):\n self._init_tool_guard()\n\n # ------------------------------------------------------------------\n # Helpers\n # ------------------------------------------------------------------\n\n def _should_require_approval(self) -> bool:\n \"\"\"``True`` when a ``session_id`` is available for approval.\"\"\"\n return bool(self._request_context.get(\"session_id\"))\n\n def _last_tool_response_is_denied(self) -> bool:\n \"\"\"Check if the last message is a guard-denied tool result.\"\"\"\n if not self.memory.content:\n return False\n msg, marks = self.memory.content[-1]\n return TOOL_GUARD_DENIED_MARK in marks and msg.role == \"system\"\n\n async def _cleanup_tool_guard_denied_messages(\n self,\n include_denial_response: bool = True,\n ) -> None:\n \"\"\"Remove tool-guard denied messages from memory.\n\n Finds messages marked with ``TOOL_GUARD_DENIED_MARK`` and\n removes them. When *include_denial_response* is ``True``,\n also removes the assistant message immediately following the\n last marked message (the LLM's denial explanation).\n \"\"\"\n ids_to_delete: list[str] = []\n last_marked_idx = -1\n\n for i, (msg, marks) in enumerate(self.memory.content):\n if TOOL_GUARD_DENIED_MARK in marks:\n ids_to_delete.append(msg.id)\n last_marked_idx = i\n\n if (\n include_denial_response\n and last_marked_idx >= 0\n and last_marked_idx + 1 < len(self.memory.content)\n ):\n next_msg, _ = self.memory.content[last_marked_idx + 1]\n if next_msg.role == \"assistant\":\n ids_to_delete.append(next_msg.id)\n\n if ids_to_delete:\n removed = await self.memory.delete(ids_to_delete)\n logger.info(\n \"Tool guard: cleaned up %d denied message(s)\",\n removed,\n )\n\n # ------------------------------------------------------------------\n # _acting override\n # ------------------------------------------------------------------\n\n async def _acting(self, tool_call) -> dict | None: # noqa: C901\n \"\"\"Intercept sensitive tool calls before execution.\n\n 1. If tool is in *denied_tools*, auto-deny unconditionally.\n 2. Check for a one-shot pre-approval.\n 3. If tool is in the guarded scope, run ToolGuardEngine.\n 4. If findings exist, enter the approval flow.\n 5. Otherwise, delegate to ``super()._acting``.\n \"\"\"\n self._ensure_tool_guard()\n\n engine = self._tool_guard_engine\n tool_name: str = tool_call.get(\"name\", \"\")\n tool_input: dict = tool_call.get(\"input\", {})\n\n try:\n if tool_name and engine.enabled:\n if engine.is_denied(tool_name):\n logger.warning(\n \"Tool guard: tool '%s' is in the denied \"\n \"set, auto-denying\",\n tool_name,\n )\n result = engine.guard(tool_name, tool_input)\n return await self._acting_auto_denied(\n tool_call,\n tool_name,\n result,\n )\n\n if engine.is_guarded(tool_name):\n session_id = str(\n self._request_context.get(\"session_id\") or \"\",\n )\n if session_id:\n svc = self._tool_guard_approval_service\n consumed = await svc.consume_approval(\n session_id,\n tool_name,\n tool_params=tool_input,\n )\n if consumed:\n logger.info(\n \"Tool guard: pre-approved '%s' \"\n \"(session %s), skipping\",\n tool_name,\n session_id[:8],\n )\n self._tool_guard_pending_info = None\n cleanup = self._cleanup_tool_guard_denied_messages\n await cleanup(\n include_denial_response=True,\n )\n return await super()._acting( # type: ignore[misc]\n tool_call,\n )\n\n result = engine.guard(tool_name, tool_input)\n if result is not None and result.findings:\n from copaw.security.tool_guard.utils import (\n log_findings,\n )\n\n log_findings(tool_name, result)\n\n if self._should_require_approval():\n return await self._acting_with_approval(\n tool_call,\n tool_name,\n result,\n )\n except Exception as exc:\n logger.warning(\n \"Tool guard check error (non-blocking): %s\",\n exc,\n exc_info=True,\n )\n\n return await super()._acting(tool_call) # type: ignore[misc]\n\n # ------------------------------------------------------------------\n # Denied / Approval responses\n # ------------------------------------------------------------------\n\n async def _acting_auto_denied(\n self,\n tool_call: dict[str, Any],\n tool_name: str,\n guard_result=None,\n ) -> dict | None:\n \"\"\"Auto-deny a tool call without offering approval.\"\"\"\n from agentscope.message import ToolResultBlock\n from copaw.security.tool_guard.approval import (\n format_findings_summary,\n )\n\n if guard_result is not None and guard_result.findings:\n findings_text = format_findings_summary(guard_result)\n severity = guard_result.max_severity.value\n count = str(guard_result.findings_count)\n else:\n findings_text = \"- Tool is in the denied list / 工具在禁止列表中\"\n severity = \"DENIED\"\n count = \"N/A\"\n\n denied_text = (\n f\"⛔ **Tool Blocked / 工具已拦截**\\n\\n\"\n f\"- Tool / 工具: `{tool_name}`\\n\"\n f\"- Severity / 严重性: `{severity}`\\n\"\n f\"- Findings / 发现: `{count}`\\n\\n\"\n f\"{findings_text}\\n\\n\"\n f\"This tool is blocked and cannot be approved.\\n\"\n f\"该工具已被禁止，无法批准执行。\"\n )\n\n tool_res_msg = Msg(\n \"system\",\n [\n ToolResultBlock(\n type=\"tool_result\",\n id=tool_call[\"id\"],\n name=tool_name,\n output=[\n {\"type\": \"text\", \"text\": denied_text},\n ],\n ),\n ],\n \"system\",\n )\n\n await self.print(tool_res_msg, True)\n await self.memory.add(tool_res_msg)\n return None\n\n async def _acting_with_approval(\n self,\n tool_call: dict[str, Any],\n tool_name: str,\n guard_result,\n ) -> dict | None:\n \"\"\"Deny the tool call and record a pending approval.\"\"\"\n from agentscope.message import ToolResultBlock\n from copaw.security.tool_guard.approval import (\n format_findings_summary,\n )\n\n channel = str(self._request_context.get(\"channel\") or \"\")\n\n for msg, marks in reversed(self.memory.content):\n if msg.role == \"assistant\":\n if TOOL_GUARD_DENIED_MARK not in marks:\n marks.append(TOOL_GUARD_DENIED_MARK)\n break\n\n await self._tool_guard_approval_service.create_pending(\n session_id=str(\n self._request_context.get(\"session_id\") or \"\",\n ),\n user_id=str(\n self._request_context.get(\"user_id\") or \"\",\n ),\n channel=channel,\n tool_name=tool_name,\n result=guard_result,\n extra={\"tool_call\": tool_call},\n )\n\n self._tool_guard_pending_info = {\n \"tool_name\": tool_name,\n \"tool_input\": tool_call.get(\"input\", {}),\n }\n\n findings_text = format_findings_summary(guard_result)\n denied_text = (\n f\"⚠️ **Risk Detected / 检测到风险**\\n\\n\"\n f\"- Tool / 工具: `{tool_name}`\\n\"\n f\"- Severity / 严重性: \"\n f\"`{guard_result.max_severity.value}`\\n\"\n f\"- Findings / 发现: \"\n f\"`{guard_result.findings_count}`\\n\\n\"\n f\"{findings_text}\\n\\n\"\n f\"Type `/approve` to approve, \"\n f\"or send any message to deny.\\n\"\n f\"输入 `/approve` 批准执行，或发送任意消息拒绝。\"\n )\n\n tool_res_msg = Msg(\n \"system\",\n [\n ToolResultBlock(\n type=\"tool_result\",\n id=tool_call[\"id\"],\n name=tool_name,\n output=[\n {\"type\": \"text\", \"text\": denied_text},\n ],\n ),\n ],\n \"system\",\n )\n\n await self.print(tool_res_msg, True)\n await self.memory.add(\n tool_res_msg,\n marks=TOOL_GUARD_DENIED_MARK,\n )\n return None\n\n # ------------------------------------------------------------------\n # _reasoning override (guard-aware)\n # ------------------------------------------------------------------\n\n async def _reasoning(\n self,\n tool_choice: (Literal[\"auto\", \"none\", \"required\"] | None) = None,\n ) -> Msg:\n \"\"\"Short-circuit reasoning when awaiting guard approval.\"\"\"\n if self._last_tool_response_is_denied():\n pending = getattr(self, \"_tool_guard_pending_info\", None) or {}\n tool_name = pending.get(\"tool_name\", \"unknown\")\n tool_input = pending.get(\"tool_input\", {})\n\n params_text = _json.dumps(\n tool_input,\n ensure_ascii=False,\n indent=2,\n )\n msg = Msg(\n self.name,\n \"⏳ Waiting for approval / 等待审批\\n\\n\"\n f\"- Tool / 工具: `{tool_name}`\\n\"\n f\"- Parameters / 参数:\\n\"\n f\"```json\\n{params_text}\\n```\\n\\n\"\n \"Type `/approve` to approve, \"\n \"or send any message to deny.\\n\"\n \"输入 `/approve` 批准执行，\"\n \"或发送任意消息拒绝。\",\n \"assistant\",\n )\n await self.print(msg, True)\n await self.memory.add(msg)\n return msg\n\n return await super()._reasoning( # type: ignore[misc]\n tool_choice=tool_choice,\n )\n" }, { "path": "src/copaw/agents/tools/__init__.py", "content": "# -*- coding: utf-8 -*-\nfrom agentscope.tool import (\n execute_python_code,\n view_text_file,\n write_text_file,\n)\n\nfrom .file_io import (\n read_file,\n write_file,\n edit_file,\n append_file,\n)\nfrom .file_search import (\n grep_search,\n glob_search,\n)\nfrom .shell import execute_shell_command\nfrom .send_file import send_file_to_user\nfrom .browser_control import browser_use\nfrom .desktop_screenshot import desktop_screenshot\nfrom .view_image import view_image\nfrom .memory_search import create_memory_search_tool\nfrom .get_current_time import get_current_time, set_user_timezone\nfrom .get_token_usage import get_token_usage\n\n__all__ = [\n \"execute_python_code\",\n \"execute_shell_command\",\n \"view_text_file\",\n \"write_text_file\",\n \"read_file\",\n \"write_file\",\n \"edit_file\",\n \"append_file\",\n \"grep_search\",\n \"glob_search\",\n \"send_file_to_user\",\n \"desktop_screenshot\",\n \"view_image\",\n \"browser_use\",\n \"create_memory_search_tool\",\n \"get_current_time\",\n \"set_user_timezone\",\n \"get_token_usage\",\n]\n" }, { "path": "src/copaw/agents/tools/browser_control.py", "content": "# -*- coding: utf-8 -*-\n# flake8: noqa: E501\n\"\"\"Browser automation tool using Playwright.\n\nSingle tool with action-based API matching browser MCP: start, stop, open,\nnavigate, navigate_back, screenshot, snapshot, click, type, eval, evaluate,\nresize, console_messages, handle_dialog, file_upload, fill_form, install,\npress_key, network_requests, run_code, drag, hover, select_option, tabs,\nwait_for, pdf, close. Uses refs from snapshot for ref-based actions.\n\"\"\"\n\nimport asyncio\nimport atexit\nfrom concurrent import futures\nimport json\nimport logging\nimport os\nimport subprocess\nimport sys\nimport time\nfrom typing import Any, Optional\n\nfrom agentscope.message import TextBlock\nfrom agentscope.tool import ToolResponse\n\nfrom ...config import (\n get_playwright_chromium_executable_path,\n get_system_default_browser,\n is_running_in_container,\n)\n\nfrom .browser_snapshot import build_role_snapshot_from_aria\n\nlogger = logging.getLogger(__name__)\n\n# Hybrid mode detection: Windows + Uvicorn reload mode requires sync Playwright\n# to avoid NotImplementedError with asyncio.create_subprocess_exec.\n# On other platforms or without reload, use async Playwright for better performance.\n_USE_SYNC_PLAYWRIGHT = (\n sys.platform == \"win32\" and os.environ.get(\"COPAW_RELOAD_MODE\") == \"1\"\n)\n\nif _USE_SYNC_PLAYWRIGHT:\n _executor: Optional[futures.ThreadPoolExecutor] = None\n\n def _get_executor() -> futures.ThreadPoolExecutor:\n global _executor\n if _executor is None:\n _executor = futures.ThreadPoolExecutor(\n max_workers=1,\n thread_name_prefix=\"playwright\",\n )\n return _executor\n\n async def _run_sync(func, *args, **kwargs):\n \"\"\"Run a sync function in the thread pool and await the result.\"\"\"\n loop = asyncio.get_event_loop()\n return await loop.run_in_executor(\n _get_executor(),\n lambda: func(*args, **kwargs),\n )\n\nelse:\n\n async def _run_sync(func, *args, **kwargs):\n \"\"\"Fallback: directly call async function (should not be used in async mode).\"\"\"\n return await func(*args, **kwargs)\n\n\n# Process-global browser state (one browser, multiple pages by page_id)\n_state: dict[str, Any] = {\n \"playwright\": None,\n \"browser\": None,\n \"context\": None,\n \"pages\": {},\n \"refs\": {}, # page_id -> ref -> {role, name?, nth?}\n \"refs_frame\": {}, # page_id -> frame for last snapshot\n \"console_logs\": {}, # page_id -> list of {level, text}\n \"network_requests\": {}, # page_id -> list of request dicts\n \"pending_dialogs\": {}, # page_id -> dialog handlers\n \"pending_file_choosers\": {}, # page_id -> FileChooser list\n \"headless\": True,\n \"current_page_id\": None,\n \"page_counter\": 0, # monotonic counter for page_N ids, avoids reuse after close\n \"last_activity_time\": 0.0, # monotonic timestamp of last browser activity\n \"_idle_task\": None, # background asyncio.Task for idle watchdog\n \"_last_browser_error\": None, # message when launch failed (for user-facing error)\n \"_sync_browser\": None, # sync browser handle for hybrid mode\n \"_sync_context\": None, # sync context handle for hybrid mode\n \"_sync_playwright\": None, # sync playwright handle for hybrid mode\n}\n\n# Stop the browser after this many seconds of inactivity (default 30 minutes).\n_BROWSER_IDLE_TIMEOUT = 1800.0\n\n\ndef _touch_activity() -> None:\n \"\"\"Record the current time as the last browser activity timestamp.\"\"\"\n _state[\"last_activity_time\"] = time.monotonic()\n\n\ndef _is_browser_running() -> bool:\n \"\"\"Check if browser is currently running (sync or async mode).\"\"\"\n if _USE_SYNC_PLAYWRIGHT:\n return _state.get(\"_sync_browser\") is not None\n return _state.get(\"browser\") is not None\n\n\ndef _reset_browser_state() -> None:\n \"\"\"Reset all browser-related state variables.\"\"\"\n # Clear sync/async specific state\n _state[\"playwright\"] = None\n _state[\"browser\"] = None\n _state[\"context\"] = None\n _state[\"_sync_playwright\"] = None\n _state[\"_sync_browser\"] = None\n _state[\"_sync_context\"] = None\n # Clear shared state\n _state[\"pages\"].clear()\n _state[\"refs\"].clear()\n _state[\"refs_frame\"].clear()\n _state[\"console_logs\"].clear()\n _state[\"network_requests\"].clear()\n _state[\"pending_dialogs\"].clear()\n _state[\"pending_file_choosers\"].clear()\n _state[\"current_page_id\"] = None\n _state[\"page_counter\"] = 0\n _state[\"last_activity_time\"] = 0.0\n _state[\"headless\"] = True\n\n\nasync def _idle_watchdog(idle_seconds: float = _BROWSER_IDLE_TIMEOUT) -> None:\n \"\"\"Background task: stop the browser after it has been idle for *idle_seconds*.\n\n This reclaims Chrome renderer processes that accumulate when pages are\n opened during agent tasks but never explicitly closed.\n \"\"\"\n try:\n while True:\n await asyncio.sleep(60) # check every minute\n if not _is_browser_running():\n return\n idle = time.monotonic() - _state.get(\"last_activity_time\", 0.0)\n if idle >= idle_seconds:\n logger.info(\n \"Browser idle for %.0fs (limit %.0fs), stopping to release resources\",\n idle,\n idle_seconds,\n )\n await _action_stop()\n return\n except asyncio.CancelledError:\n pass\n\n\ndef _atexit_cleanup() -> None:\n \"\"\"Best-effort browser cleanup registered with :func:`atexit`.\n\n Playwright child processes are cleaned up by the OS when the parent\n exits, but this gives Playwright a chance to flush any pending I/O and\n close Chrome gracefully before the process disappears.\n \"\"\"\n if not _is_browser_running():\n return\n\n try:\n loop = asyncio.get_event_loop()\n if not loop.is_running() and not loop.is_closed():\n loop.run_until_complete(_action_stop())\n except Exception:\n pass\n\n\natexit.register(_atexit_cleanup)\n\n\ndef _tool_response(text: str) -> ToolResponse:\n \"\"\"Wrap text for agentscope Toolkit (return ToolResponse).\"\"\"\n return ToolResponse(\n content=[TextBlock(type=\"text\", text=text)],\n )\n\n\ndef _chromium_launch_args() -> list[str]:\n \"\"\"Extra args for Chromium when running in container.\"\"\"\n if is_running_in_container():\n return [\"--no-sandbox\", \"--disable-dev-shm-usage\"]\n return []\n\n\ndef _chromium_executable_path() -> str | None:\n \"\"\"Chromium executable path when set (e.g. container); else None.\"\"\"\n return get_playwright_chromium_executable_path()\n\n\ndef _use_webkit_fallback() -> bool:\n \"\"\"True only on macOS when no system Chrome/Edge/Chromium found.\n Use WebKit (Safari) to avoid downloading Chromium. Windows has no system\n WebKit, so we never use webkit there.\n \"\"\"\n return sys.platform == \"darwin\" and _chromium_executable_path() is None\n\n\ndef _ensure_playwright_async():\n \"\"\"Import async_playwright; raise ImportError with hint if missing.\"\"\"\n try:\n from playwright.async_api import async_playwright\n\n return async_playwright\n except ImportError as exc:\n raise ImportError(\n \"Playwright not installed. Use the same Python that runs CoPaw (e.g. \"\n \"activate your venv or use 'uv run'): \"\n f\"'{sys.executable}' -m pip install playwright && \"\n f\"'{sys.executable}' -m playwright install\",\n ) from exc\n\n\ndef _ensure_playwright_sync():\n \"\"\"Import sync_playwright; raise ImportError with hint if missing.\"\"\"\n try:\n from playwright.sync_api import sync_playwright\n\n return sync_playwright\n except ImportError as exc:\n raise ImportError(\n \"Playwright not installed. Use the same Python that runs CoPaw (e.g. \"\n \"activate your venv or use 'uv run'): \"\n f\"'{sys.executable}' -m pip install playwright && \"\n f\"'{sys.executable}' -m playwright install\",\n ) from exc\n\n\ndef _sync_browser_launch(headless: bool):\n \"\"\"Launch browser using sync Playwright (for hybrid mode).\"\"\"\n sync_playwright = _ensure_playwright_sync()\n pw = sync_playwright().start() # Start without context manager\n use_default = not is_running_in_container() and os.environ.get(\n \"COPAW_BROWSER_USE_DEFAULT\",\n \"1\",\n ).strip().lower() in (\"1\", \"true\", \"yes\")\n default_kind, default_path = (\n get_system_default_browser() if use_default else (None, None)\n )\n exe: Optional[str] = None\n if default_kind == \"chromium\" and default_path:\n exe = default_path\n elif default_kind != \"webkit\":\n exe = _chromium_executable_path()\n\n if exe:\n launch_kwargs = {\"headless\": headless}\n extra_args = _chromium_launch_args()\n if extra_args:\n launch_kwargs[\"args\"] = extra_args\n launch_kwargs[\"executable_path\"] = exe\n browser = pw.chromium.launch(**launch_kwargs)\n elif default_kind == \"webkit\" or sys.platform == \"darwin\":\n browser = pw.webkit.launch(headless=headless)\n else:\n launch_kwargs = {\"headless\": headless}\n extra_args = _chromium_launch_args()\n if extra_args:\n launch_kwargs[\"args\"] = extra_args\n browser = pw.chromium.launch(**launch_kwargs)\n\n context = browser.new_context()\n _attach_context_listeners(context)\n return pw, browser, context\n\n\ndef _sync_browser_close():\n \"\"\"Close browser using sync Playwright (for hybrid mode).\"\"\"\n if _state[\"_sync_browser\"] is not None:\n try:\n _state[\"_sync_browser\"].close()\n except Exception:\n pass\n if _state[\"_sync_playwright\"] is not None:\n try:\n _state[\"_sync_playwright\"].stop()\n except Exception:\n pass\n\n\ndef _parse_json_param(value: str, default: Any = None):\n \"\"\"Parse optional JSON string param (e.g. fields, paths, values).\"\"\"\n if not value or not isinstance(value, str):\n return default\n value = value.strip()\n if not value:\n return default\n try:\n return json.loads(value)\n except json.JSONDecodeError:\n if \",\" in value:\n return [x.strip() for x in value.split(\",\")]\n return default\n\n\nasync def browser_use( # pylint: disable=R0911,R0912\n action: str,\n url: str = \"\",\n page_id: str = \"default\",\n selector: str = \"\",\n text: str = \"\",\n code: str = \"\",\n path: str = \"\",\n wait: int = 0,\n full_page: bool = False,\n width: int = 0,\n height: int = 0,\n level: str = \"info\",\n filename: str = \"\",\n accept: bool = True,\n prompt_text: str = \"\",\n ref: str = \"\",\n element: str = \"\",\n paths_json: str = \"\",\n fields_json: str = \"\",\n key: str = \"\",\n submit: bool = False,\n slowly: bool = False,\n include_static: bool = False,\n screenshot_type: str = \"png\",\n snapshot_filename: str = \"\",\n double_click: bool = False,\n button: str = \"left\",\n modifiers_json: str = \"\",\n start_ref: str = \"\",\n end_ref: str = \"\",\n start_selector: str = \"\",\n end_selector: str = \"\",\n start_element: str = \"\",\n end_element: str = \"\",\n values_json: str = \"\",\n tab_action: str = \"\",\n index: int = -1,\n wait_time: float = 0,\n text_gone: str = \"\",\n frame_selector: str = \"\",\n headed: bool = False,\n) -> ToolResponse:\n \"\"\"Control browser (Playwright). Default is headless. Use headed=True with\n action=start to open a visible browser window. Flow: start, open(url),\n snapshot to get refs, then click/type etc. with ref or selector. Use\n page_id for multiple tabs.\n\n Args:\n action (str):\n Required. Action type. Values: start, stop, open, navigate,\n navigate_back, snapshot, screenshot, click, type, eval, evaluate,\n resize, console_messages, network_requests, handle_dialog,\n file_upload, fill_form, install, press_key, run_code, drag, hover,\n select_option, tabs, wait_for, pdf, close.\n url (str):\n URL to open. Required for action=open or navigate.\n page_id (str):\n Page/tab identifier, default \"default\". Use different page_id for\n multiple tabs.\n selector (str):\n CSS selector to locate element for click/type/hover etc. Prefer\n ref when available.\n text (str):\n Text to type. Required for action=type.\n code (str):\n JavaScript code. Required for action=eval, evaluate, or run_code.\n path (str):\n File path for screenshot save or PDF export.\n wait (int):\n Milliseconds to wait after click. Used with action=click.\n full_page (bool):\n Whether to capture full page. Used with action=screenshot.\n width (int):\n Viewport width in pixels. Used with action=resize.\n height (int):\n Viewport height in pixels. Used with action=resize.\n level (str):\n Console log level filter, e.g. \"info\" or \"error\". Used with\n action=console_messages.\n filename (str):\n Filename for saving logs or screenshot. Used with\n console_messages, network_requests, screenshot.\n accept (bool):\n Whether to accept dialog (true) or dismiss (false). Used with\n action=handle_dialog.\n prompt_text (str):\n Input for prompt dialog. Used with action=handle_dialog when\n dialog is prompt.\n ref (str):\n Element ref from snapshot output; use for stable targeting. Prefer\n ref for click/type/hover/screenshot/evaluate/select_option.\n element (str):\n Element description for evaluate etc. Prefer ref when available.\n paths_json (str):\n JSON array string of file paths. Used with action=file_upload.\n fields_json (str):\n JSON object string of form field name to value. Used with\n action=fill_form.\n key (str):\n Key name, e.g. \"Enter\", \"Control+a\". Required for\n action=press_key.\n submit (bool):\n Whether to submit (press Enter) after typing. Used with\n action=type.\n slowly (bool):\n Whether to type character by character. Used with action=type.\n include_static (bool):\n Whether to include static resource requests. Used with\n action=network_requests.\n screenshot_type (str):\n Screenshot format, \"png\" or \"jpeg\". Used with action=screenshot.\n snapshot_filename (str):\n File path to save snapshot output. Used with action=snapshot.\n double_click (bool):\n Whether to double-click. Used with action=click.\n button (str):\n Mouse button: \"left\", \"right\", or \"middle\". Used with\n action=click.\n modifiers_json (str):\n JSON array of modifier keys, e.g. [\"Shift\",\"Control\"]. Used with\n action=click.\n start_ref (str):\n Drag start element ref. Used with action=drag.\n end_ref (str):\n Drag end element ref. Used with action=drag.\n start_selector (str):\n Drag start CSS selector. Used with action=drag.\n end_selector (str):\n Drag end CSS selector. Used with action=drag.\n start_element (str):\n Drag start element description. Used with action=drag.\n end_element (str):\n Drag end element description. Used with action=drag.\n values_json (str):\n JSON of option value(s) for select. Used with\n action=select_option.\n tab_action (str):\n Tab action: list, new, close, or select. Required for\n action=tabs.\n index (int):\n Tab index for tabs select, zero-based. Used with action=tabs.\n wait_time (float):\n Seconds to wait. Used with action=wait_for.\n text_gone (str):\n Wait until this text disappears from page. Used with\n action=wait_for.\n frame_selector (str):\n iframe selector, e.g. \"iframe#main\". Set when operating inside\n that iframe in snapshot/click/type etc.\n headed (bool):\n When True with action=start, launch a visible browser window\n (non-headless). User can see the real browser. Default False.\n \"\"\"\n action = (action or \"\").strip().lower()\n if not action:\n return _tool_response(\n json.dumps(\n {\"ok\": False, \"error\": \"action required\"},\n ensure_ascii=False,\n indent=2,\n ),\n )\n\n page_id = (page_id or \"default\").strip() or \"default\"\n current = _state.get(\"current_page_id\")\n pages = _state.get(\"pages\") or {}\n if page_id == \"default\" and current and current in pages:\n page_id = current\n\n try:\n if action == \"start\":\n return await _action_start(headed=headed)\n if action == \"stop\":\n return await _action_stop()\n if action == \"open\":\n return await _action_open(url, page_id)\n if action == \"navigate\":\n return await _action_navigate(url, page_id)\n if action == \"navigate_back\":\n return await _action_navigate_back(page_id)\n if action in (\"screenshot\", \"take_screenshot\"):\n return await _action_screenshot(\n page_id,\n path or filename,\n full_page,\n screenshot_type,\n ref,\n element,\n frame_selector,\n )\n if action == \"snapshot\":\n return await _action_snapshot(\n page_id,\n snapshot_filename or filename,\n frame_selector,\n )\n if action == \"click\":\n return await _action_click(\n page_id,\n selector,\n ref,\n element,\n wait,\n double_click,\n button,\n modifiers_json,\n frame_selector,\n )\n if action == \"type\":\n return await _action_type(\n page_id,\n selector,\n ref,\n element,\n text,\n submit,\n slowly,\n frame_selector,\n )\n if action == \"eval\":\n return await _action_eval(page_id, code)\n if action == \"evaluate\":\n return await _action_evaluate(\n page_id,\n code,\n ref,\n element,\n frame_selector,\n )\n if action == \"resize\":\n return await _action_resize(page_id, width, height)\n if action == \"console_messages\":\n return await _action_console_messages(\n page_id,\n level,\n filename or path,\n )\n if action == \"handle_dialog\":\n return await _action_handle_dialog(page_id, accept, prompt_text)\n if action == \"file_upload\":\n return await _action_file_upload(page_id, paths_json)\n if action == \"fill_form\":\n return await _action_fill_form(page_id, fields_json)\n if action == \"install\":\n return await _action_install()\n if action == \"press_key\":\n return await _action_press_key(page_id, key)\n if action == \"network_requests\":\n return await _action_network_requests(\n page_id,\n include_static,\n filename or path,\n )\n if action == \"run_code\":\n return await _action_run_code(page_id, code)\n if action == \"drag\":\n return await _action_drag(\n page_id,\n start_ref,\n end_ref,\n start_selector,\n end_selector,\n start_element,\n end_element,\n frame_selector,\n )\n if action == \"hover\":\n return await _action_hover(\n page_id,\n ref,\n element,\n selector,\n frame_selector,\n )\n if action == \"select_option\":\n return await _action_select_option(\n page_id,\n ref,\n element,\n values_json,\n frame_selector,\n )\n if action == \"tabs\":\n return await _action_tabs(page_id, tab_action, index)\n if action == \"wait_for\":\n return await _action_wait_for(page_id, wait_time, text, text_gone)\n if action == \"pdf\":\n return await _action_pdf(page_id, path)\n if action == \"close\":\n return await _action_close(page_id)\n return _tool_response(\n json.dumps(\n {\"ok\": False, \"error\": f\"Unknown action: {action}\"},\n ensure_ascii=False,\n indent=2,\n ),\n )\n except Exception as e:\n logger.error(\"Browser tool error: %s\", e, exc_info=True)\n return _tool_response(\n json.dumps(\n {\"ok\": False, \"error\": str(e)},\n ensure_ascii=False,\n indent=2,\n ),\n )\n\n\ndef _get_page(page_id: str):\n \"\"\"Return page for page_id or None if not found.\"\"\"\n return _state[\"pages\"].get(page_id)\n\n\ndef _get_refs(page_id: str) -> dict[str, dict]:\n \"\"\"Return refs map for page_id (ref -> {role, name?, nth?}).\"\"\"\n return _state[\"refs\"].setdefault(page_id, {})\n\n\ndef _get_root(page, _page_id: str, frame_selector: str = \"\"):\n \"\"\"Return page or frame for frame_selector (ref/selector).\"\"\"\n if not (frame_selector and frame_selector.strip()):\n return page\n return page.frame_locator(frame_selector.strip())\n\n\ndef _get_locator_by_ref(\n page,\n page_id: str,\n ref: str,\n frame_selector: str = \"\",\n):\n \"\"\"Resolve snapshot ref to locator; frame_selector for iframe.\"\"\"\n refs = _get_refs(page_id)\n info = refs.get(ref)\n if not info:\n return None\n role = info.get(\"role\", \"generic\")\n name = info.get(\"name\")\n nth = info.get(\"nth\", 0)\n root = _get_root(page, page_id, frame_selector)\n locator = root.get_by_role(role, name=name or None)\n if nth is not None and nth > 0:\n locator = locator.nth(nth)\n return locator\n\n\ndef _attach_page_listeners(page, page_id: str) -> None:\n \"\"\"Attach console and request listeners for a page.\"\"\"\n logs = _state[\"console_logs\"].setdefault(page_id, [])\n\n def on_console(msg):\n logs.append({\"level\": msg.type, \"text\": msg.text})\n\n page.on(\"console\", on_console)\n requests_list = _state[\"network_requests\"].setdefault(page_id, [])\n\n def on_request(req):\n requests_list.append(\n {\n \"url\": req.url,\n \"method\": req.method,\n \"resourceType\": getattr(req, \"resource_type\", None),\n },\n )\n\n def on_response(res):\n for r in requests_list:\n if r.get(\"url\") == res.url and \"status\" not in r:\n r[\"status\"] = res.status\n break\n\n page.on(\"request\", on_request)\n page.on(\"response\", on_response)\n dialogs = _state[\"pending_dialogs\"].setdefault(page_id, [])\n\n def on_dialog(dialog):\n dialogs.append(dialog)\n\n page.on(\"dialog\", on_dialog)\n choosers = _state[\"pending_file_choosers\"].setdefault(page_id, [])\n\n def on_filechooser(chooser):\n choosers.append(chooser)\n\n page.on(\"filechooser\", on_filechooser)\n\n\ndef _next_page_id() -> str:\n \"\"\"Return a unique page_id (page_N).\n Uses monotonic counter so IDs are not reused after close.\"\"\"\n _state[\"page_counter\"] = _state.get(\"page_counter\", 0) + 1\n return f\"page_{_state['page_counter']}\"\n\n\ndef _attach_context_listeners(context) -> None:\n \"\"\"When the page opens a new tab (e.g. target=_blank, window.open),\n register it and set as current.\"\"\"\n\n def on_page(page):\n new_id = _next_page_id()\n _state[\"refs\"][new_id] = {}\n _state[\"console_logs\"][new_id] = []\n _state[\"network_requests\"][new_id] = []\n _state[\"pending_dialogs\"][new_id] = []\n _state[\"pending_file_choosers\"][new_id] = []\n _attach_page_listeners(page, new_id)\n _state[\"pages\"][new_id] = page\n _state[\"current_page_id\"] = new_id\n logger.debug(\n \"New tab opened by page, registered as page_id=%s\",\n new_id,\n )\n\n context.on(\"page\", on_page)\n\n\nasync def _ensure_browser() -> bool: # pylint: disable=too-many-branches\n \"\"\"Start browser if not running. Return True if ready, False on failure.\"\"\"\n # Check browser state based on mode\n if _USE_SYNC_PLAYWRIGHT:\n if (\n _state[\"_sync_browser\"] is not None\n and _state[\"_sync_context\"] is not None\n ):\n _touch_activity()\n return True\n else:\n if _state[\"browser\"] is not None and _state[\"context\"] is not None:\n _touch_activity()\n return True\n\n try:\n if _USE_SYNC_PLAYWRIGHT:\n # Hybrid mode: use sync Playwright in thread pool\n loop = asyncio.get_event_loop()\n pw, browser, context = await loop.run_in_executor(\n _get_executor(),\n lambda: _sync_browser_launch(_state[\"headless\"]),\n )\n _state[\"_sync_playwright\"] = pw\n _state[\"_sync_browser\"] = browser\n _state[\"_sync_context\"] = context\n else:\n # Standard mode: use async Playwright\n async_playwright = _ensure_playwright_async()\n pw = await async_playwright().start()\n # Prefer OS default browser when available (e.g. user's default Chrome/Safari).\n use_default = not is_running_in_container() and os.environ.get(\n \"COPAW_BROWSER_USE_DEFAULT\",\n \"1\",\n ).strip().lower() in (\"1\", \"true\", \"yes\")\n default_kind, default_path = (\n get_system_default_browser() if use_default else (None, None)\n )\n exe: Optional[str] = None\n if default_kind == \"chromium\" and default_path:\n exe = default_path\n elif default_kind != \"webkit\":\n exe = _chromium_executable_path()\n if exe:\n # System Chrome/Edge/Chromium (default or discovered)\n launch_kwargs: dict[str, Any] = {\n \"headless\": _state[\"headless\"],\n }\n extra_args = _chromium_launch_args()\n if extra_args:\n launch_kwargs[\"args\"] = extra_args\n launch_kwargs[\"executable_path\"] = exe\n pw_browser = await pw.chromium.launch(**launch_kwargs)\n elif default_kind == \"webkit\" or sys.platform == \"darwin\":\n # macOS: default Safari or no Chromium → use WebKit (Safari)\n pw_browser = await pw.webkit.launch(\n headless=_state[\"headless\"],\n )\n else:\n # Windows/Linux without system Chromium → Playwright's Chromium\n launch_kwargs = {\"headless\": _state[\"headless\"]}\n extra_args = _chromium_launch_args()\n if extra_args:\n launch_kwargs[\"args\"] = extra_args\n pw_browser = await pw.chromium.launch(**launch_kwargs)\n context = await pw_browser.new_context()\n _attach_context_listeners(context)\n _state[\"playwright\"] = pw\n _state[\"browser\"] = pw_browser\n _state[\"context\"] = context\n _state[\"_last_browser_error\"] = None\n _touch_activity()\n _start_idle_watchdog()\n return True\n except Exception as e:\n _state[\"_last_browser_error\"] = str(e)\n return False\n\n\ndef _start_idle_watchdog() -> None:\n \"\"\"Cancel any existing idle watchdog and start a fresh one.\"\"\"\n old_task = _state.get(\"_idle_task\")\n if old_task and not old_task.done():\n old_task.cancel()\n _state[\"_idle_task\"] = asyncio.ensure_future(_idle_watchdog())\n\n\ndef _cancel_idle_watchdog() -> None:\n \"\"\"Cancel the idle watchdog, if running.\"\"\"\n task = _state.get(\"_idle_task\")\n if task and not task.done():\n task.cancel()\n _state[\"_idle_task\"] = None\n\n\n# pylint: disable=R0912,R0915\nasync def _action_start(\n headed: bool = False,\n) -> ToolResponse:\n # Check browser state based on mode\n if _USE_SYNC_PLAYWRIGHT:\n browser_exists = _state[\"_sync_browser\"] is not None\n current_headless = not _state.get(\"_sync_headless\", True)\n else:\n browser_exists = _state[\"browser\"] is not None\n current_headless = _state[\"headless\"]\n\n # If user asks for visible window (headed=True)\n # but browser is already running headless, restart with headed\n if browser_exists:\n if headed and current_headless:\n _cancel_idle_watchdog()\n try:\n await _action_stop()\n except Exception:\n pass\n else:\n return _tool_response(\n json.dumps(\n {\"ok\": True, \"message\": \"Browser already running\"},\n ensure_ascii=False,\n indent=2,\n ),\n )\n # Default: headless (background). Only headed=True (e.g. browser_visible skill) shows window.\n _state[\"headless\"] = not headed\n\n try:\n if _USE_SYNC_PLAYWRIGHT:\n loop = asyncio.get_event_loop()\n pw, browser, context = await loop.run_in_executor(\n _get_executor(),\n lambda: _sync_browser_launch(_state[\"headless\"]),\n )\n _state[\"_sync_playwright\"] = pw\n _state[\"_sync_browser\"] = browser\n _state[\"_sync_context\"] = context\n _state[\"_sync_headless\"] = not headed\n else:\n async_playwright = _ensure_playwright_async()\n pw = await async_playwright().start()\n use_default = not is_running_in_container() and os.environ.get(\n \"COPAW_BROWSER_USE_DEFAULT\",\n \"1\",\n ).strip().lower() in (\"1\", \"true\", \"yes\")\n default_kind, default_path = (\n get_system_default_browser() if use_default else (None, None)\n )\n exe: Optional[str] = None\n if default_kind == \"chromium\" and default_path:\n exe = default_path\n elif default_kind != \"webkit\":\n exe = _chromium_executable_path()\n if exe:\n launch_kwargs = {\"headless\": _state[\"headless\"]}\n extra_args = _chromium_launch_args()\n if extra_args:\n launch_kwargs[\"args\"] = extra_args\n launch_kwargs[\"executable_path\"] = exe\n pw_browser = await pw.chromium.launch(**launch_kwargs)\n elif default_kind == \"webkit\" or sys.platform == \"darwin\":\n pw_browser = await pw.webkit.launch(\n headless=_state[\"headless\"],\n )\n else:\n launch_kwargs = {\"headless\": _state[\"headless\"]}\n extra_args = _chromium_launch_args()\n if extra_args:\n launch_kwargs[\"args\"] = extra_args\n pw_browser = await pw.chromium.launch(**launch_kwargs)\n context = await pw_browser.new_context()\n _attach_context_listeners(context)\n _state[\"playwright\"] = pw\n _state[\"browser\"] = pw_browser\n _state[\"context\"] = context\n _touch_activity()\n _start_idle_watchdog()\n msg = (\n \"Browser started (visible window)\"\n if not _state[\"headless\"]\n else \"Browser started\"\n )\n return _tool_response(\n json.dumps(\n {\"ok\": True, \"message\": msg},\n ensure_ascii=False,\n indent=2,\n ),\n )\n except Exception as e:\n return _tool_response(\n json.dumps(\n {\"ok\": False, \"error\": f\"Browser start failed: {e!s}\"},\n ensure_ascii=False,\n indent=2,\n ),\n )\n\n\nasync def _action_stop() -> ToolResponse:\n _cancel_idle_watchdog()\n\n # Check browser state based on mode\n if not _is_browser_running():\n return _tool_response(\n json.dumps(\n {\"ok\": True, \"message\": \"Browser not running\"},\n ensure_ascii=False,\n indent=2,\n ),\n )\n\n if _USE_SYNC_PLAYWRIGHT:\n # Close sync browser in thread pool\n loop = asyncio.get_event_loop()\n try:\n await loop.run_in_executor(\n _get_executor(),\n _sync_browser_close,\n )\n except Exception as e:\n return _tool_response(\n json.dumps(\n {\"ok\": False, \"error\": f\"Browser stop failed: {e!s}\"},\n ensure_ascii=False,\n indent=2,\n ),\n )\n finally:\n _reset_browser_state()\n else:\n # Standard async mode\n try:\n await _state[\"browser\"].close()\n if _state[\"playwright\"] is not None:\n await _state[\"playwright\"].stop()\n except Exception as e:\n return _tool_response(\n json.dumps(\n {\"ok\": False, \"error\": f\"Browser stop failed: {e!s}\"},\n ensure_ascii=False,\n indent=2,\n ),\n )\n finally:\n _reset_browser_state()\n\n return _tool_response(\n json.dumps(\n {\"ok\": True, \"message\": \"Browser stopped\"},\n ensure_ascii=False,\n indent=2,\n ),\n )\n\n\nasync def _action_open(url: str, page_id: str) -> ToolResponse:\n url = (url or \"\").strip()\n if not url:\n return _tool_response(\n json.dumps(\n {\"ok\": False, \"error\": \"url required for open\"},\n ensure_ascii=False,\n indent=2,\n ),\n )\n if not await _ensure_browser():\n err = _state.get(\"_last_browser_error\") or \"Browser not started\"\n return _tool_response(\n json.dumps(\n {\"ok\": False, \"error\": err},\n ensure_ascii=False,\n indent=2,\n ),\n )\n try:\n if _USE_SYNC_PLAYWRIGHT:\n # Hybrid mode: create page in thread pool\n loop = asyncio.get_event_loop()\n # pylint: disable=unnecessary-lambda\n page = await loop.run_in_executor(\n _get_executor(),\n lambda: _state[\"_sync_context\"].new_page(),\n )\n else:\n # Standard async mode\n page = await _state[\"context\"].new_page()\n\n _state[\"refs\"][page_id] = {}\n _state[\"console_logs\"][page_id] = []\n _state[\"network_requests\"][page_id] = []\n _state[\"pending_dialogs\"][page_id] = []\n _state[\"pending_file_choosers\"][page_id] = []\n _attach_page_listeners(page, page_id)\n\n if _USE_SYNC_PLAYWRIGHT:\n loop = asyncio.get_event_loop()\n await loop.run_in_executor(\n _get_executor(),\n lambda: page.goto(url),\n )\n else:\n await page.goto(url)\n\n _state[\"pages\"][page_id] = page\n _state[\"current_page_id\"] = page_id\n return _tool_response(\n json.dumps(\n {\n \"ok\": True,\n \"message\": f\"Opened {url}\",\n \"page_id\": page_id,\n \"url\": url,\n },\n ensure_ascii=False,\n indent=2,\n ),\n )\n except Exception as e:\n return _tool_response(\n json.dumps(\n {\"ok\": False, \"error\": f\"Open failed: {e!s}\"},\n ensure_ascii=False,\n indent=2,\n ),\n )\n\n\nasync def _action_navigate(url: str, page_id: str) -> ToolResponse:\n url = (url or \"\").strip()\n if not url:\n return _tool_response(\n json.dumps(\n {\"ok\": False, \"error\": \"url required for navigate\"},\n ensure_ascii=False,\n indent=2,\n ),\n )\n page = _get_page(page_id)\n if not page:\n return _tool_response(\n json.dumps(\n {\"ok\": False, \"error\": f\"Page '{page_id}' not found\"},\n ensure_ascii=False,\n indent=2,\n ),\n )\n try:\n if _USE_SYNC_PLAYWRIGHT:\n loop = asyncio.get_event_loop()\n await loop.run_in_executor(\n _get_executor(),\n lambda: page.goto(url),\n )\n else:\n await page.goto(url)\n _state[\"current_page_id\"] = page_id\n return _tool_response(\n json.dumps(\n {\n \"ok\": True,\n \"message\": f\"Navigated to {url}\",\n \"url\": page.url,\n },\n ensure_ascii=False,\n indent=2,\n ),\n )\n except Exception as e:\n return _tool_response(\n json.dumps(\n {\"ok\": False, \"error\": f\"Navigate failed: {e!s}\"},\n ensure_ascii=False,\n indent=2,\n ),\n )\n\n\nasync def _action_screenshot(\n page_id: str,\n path: str,\n full_page: bool,\n screenshot_type: str = \"png\",\n ref: str = \"\",\n element: str = \"\", # pylint: disable=unused-argument\n frame_selector: str = \"\",\n) -> ToolResponse:\n path = (path or \"\").strip()\n if not path:\n ext = \"jpeg\" if screenshot_type == \"jpeg\" else \"png\"\n path = f\"page-{int(time.time())}.{ext}\"\n page = _get_page(page_id)\n if not page:\n return _tool_response(\n json.dumps(\n {\"ok\": False, \"error\": f\"Page '{page_id}' not found\"},\n ensure_ascii=False,\n indent=2,\n ),\n )\n try:\n if ref and ref.strip():\n locator = _get_locator_by_ref(\n page,\n page_id,\n ref.strip(),\n frame_selector,\n )\n if locator is None:\n return _tool_response(\n json.dumps(\n {\"ok\": False, \"error\": f\"Unknown ref: {ref}\"},\n ensure_ascii=False,\n indent=2,\n ),\n )\n if _USE_SYNC_PLAYWRIGHT:\n await _run_sync(\n locator.screenshot,\n path=path,\n type=screenshot_type\n if screenshot_type == \"jpeg\"\n else \"png\",\n )\n else:\n await locator.screenshot(\n path=path,\n type=screenshot_type\n if screenshot_type == \"jpeg\"\n else \"png\",\n )\n else:\n if frame_selector and frame_selector.strip():\n root = _get_root(page, page_id, frame_selector)\n locator = root.locator(\"body\").first\n if _USE_SYNC_PLAYWRIGHT:\n await _run_sync(\n locator.screenshot,\n path=path,\n type=screenshot_type\n if screenshot_type == \"jpeg\"\n else \"png\",\n )\n else:\n await locator.screenshot(\n path=path,\n type=screenshot_type\n if screenshot_type == \"jpeg\"\n else \"png\",\n )\n else:\n if _USE_SYNC_PLAYWRIGHT:\n await _run_sync(\n page.screenshot,\n path=path,\n full_page=full_page,\n type=screenshot_type\n if screenshot_type == \"jpeg\"\n else \"png\",\n )\n else:\n await page.screenshot(\n path=path,\n full_page=full_page,\n type=screenshot_type\n if screenshot_type == \"jpeg\"\n else \"png\",\n )\n return _tool_response(\n json.dumps(\n {\n \"ok\": True,\n \"message\": f\"Screenshot saved to {path}\",\n \"path\": path,\n },\n ensure_ascii=False,\n indent=2,\n ),\n )\n except Exception as e:\n return _tool_response(\n json.dumps(\n {\"ok\": False, \"error\": f\"Screenshot failed: {e!s}\"},\n ensure_ascii=False,\n indent=2,\n ),\n )\n\n\nasync def _action_click( # pylint: disable=too-many-branches\n page_id: str,\n selector: str,\n ref: str = \"\",\n element: str = \"\", # pylint: disable=unused-argument\n wait: int = 0,\n double_click: bool = False,\n button: str = \"left\",\n modifiers_json: str = \"\",\n frame_selector: str = \"\",\n) -> ToolResponse:\n ref = (ref or \"\").strip()\n selector = (selector or \"\").strip()\n if not ref and not selector:\n return _tool_response(\n json.dumps(\n {\"ok\": False, \"error\": \"selector or ref required for click\"},\n ensure_ascii=False,\n indent=2,\n ),\n )\n page = _get_page(page_id)\n if not page:\n return _tool_response(\n json.dumps(\n {\"ok\": False, \"error\": f\"Page '{page_id}' not found\"},\n ensure_ascii=False,\n indent=2,\n ),\n )\n try:\n if wait > 0:\n await asyncio.sleep(wait / 1000.0)\n mods = _parse_json_param(modifiers_json, [])\n if not isinstance(mods, list):\n mods = []\n kwargs = {\n \"button\": button\n if button in (\"left\", \"right\", \"middle\")\n else \"left\",\n }\n if mods:\n kwargs[\"modifiers\"] = [\n m\n for m in mods\n if m in (\"Alt\", \"Control\", \"ControlOrMeta\", \"Meta\", \"Shift\")\n ]\n\n if _USE_SYNC_PLAYWRIGHT:\n loop = asyncio.get_event_loop()\n if ref:\n locator = _get_locator_by_ref(\n page,\n page_id,\n ref,\n frame_selector,\n )\n if locator is None:\n return _tool_response(\n json.dumps(\n {\"ok\": False, \"error\": f\"Unknown ref: {ref}\"},\n ensure_ascii=False,\n indent=2,\n ),\n )\n if double_click:\n await loop.run_in_executor(\n _get_executor(),\n lambda: locator.dblclick(**kwargs),\n )\n else:\n await loop.run_in_executor(\n _get_executor(),\n lambda: locator.click(**kwargs),\n )\n else:\n root = _get_root(page, page_id, frame_selector)\n locator = root.locator(selector).first\n if double_click:\n await loop.run_in_executor(\n _get_executor(),\n lambda: locator.dblclick(**kwargs),\n )\n else:\n await loop.run_in_executor(\n _get_executor(),\n lambda: locator.click(**kwargs),\n )\n else:\n # Standard async mode\n if ref:\n locator = _get_locator_by_ref(\n page,\n page_id,\n ref,\n frame_selector,\n )\n if locator is None:\n return _tool_response(\n json.dumps(\n {\"ok\": False, \"error\": f\"Unknown ref: {ref}\"},\n ensure_ascii=False,\n indent=2,\n ),\n )\n if double_click:\n await locator.dblclick(**kwargs)\n else:\n await locator.click(**kwargs)\n else:\n root = _get_root(page, page_id, frame_selector)\n locator = root.locator(selector).first\n if double_click:\n await locator.dblclick(**kwargs)\n else:\n await locator.click(**kwargs)\n\n return _tool_response(\n json.dumps(\n {\"ok\": True, \"message\": f\"Clicked {ref or selector}\"},\n ensure_ascii=False,\n indent=2,\n ),\n )\n except Exception as e:\n return _tool_response(\n json.dumps(\n {\"ok\": False, \"error\": f\"Click failed: {e!s}\"},\n ensure_ascii=False,\n indent=2,\n ),\n )\n\n\nasync def _action_type(\n page_id: str,\n selector: str,\n ref: str = \"\",\n element: str = \"\", # pylint: disable=unused-argument\n text: str = \"\",\n submit: bool = False,\n slowly: bool = False,\n frame_selector: str = \"\",\n) -> ToolResponse:\n ref = (ref or \"\").strip()\n selector = (selector or \"\").strip()\n if not ref and not selector:\n return _tool_response(\n json.dumps(\n {\"ok\": False, \"error\": \"selector or ref required for type\"},\n ensure_ascii=False,\n indent=2,\n ),\n )\n page = _get_page(page_id)\n if not page:\n return _tool_response(\n json.dumps(\n {\"ok\": False, \"error\": f\"Page '{page_id}' not found\"},\n ensure_ascii=False,\n indent=2,\n ),\n )\n try:\n if ref:\n locator = _get_locator_by_ref(page, page_id, ref, frame_selector)\n if locator is None:\n return _tool_response(\n json.dumps(\n {\"ok\": False, \"error\": f\"Unknown ref: {ref}\"},\n ensure_ascii=False,\n indent=2,\n ),\n )\n if _USE_SYNC_PLAYWRIGHT:\n loop = asyncio.get_event_loop()\n if slowly:\n await loop.run_in_executor(\n _get_executor(),\n lambda: locator.press_sequentially(text or \"\"),\n )\n else:\n await loop.run_in_executor(\n _get_executor(),\n lambda: locator.fill(text or \"\"),\n )\n if submit:\n await loop.run_in_executor(\n _get_executor(),\n lambda: locator.press(\"Enter\"),\n )\n else:\n if slowly:\n await locator.press_sequentially(text or \"\")\n else:\n await locator.fill(text or \"\")\n if submit:\n await locator.press(\"Enter\")\n else:\n root = _get_root(page, page_id, frame_selector)\n loc = root.locator(selector).first\n if _USE_SYNC_PLAYWRIGHT:\n loop = asyncio.get_event_loop()\n if slowly:\n await loop.run_in_executor(\n _get_executor(),\n lambda: loc.press_sequentially(text or \"\"),\n )\n else:\n await loop.run_in_executor(\n _get_executor(),\n lambda: loc.fill(text or \"\"),\n )\n if submit:\n await loop.run_in_executor(\n _get_executor(),\n lambda: loc.press(\"Enter\"),\n )\n else:\n if slowly:\n await loc.press_sequentially(text or \"\")\n else:\n await loc.fill(text or \"\")\n if submit:\n await loc.press(\"Enter\")\n return _tool_response(\n json.dumps(\n {\"ok\": True, \"message\": f\"Typed into {ref or selector}\"},\n ensure_ascii=False,\n indent=2,\n ),\n )\n except Exception as e:\n return _tool_response(\n json.dumps(\n {\"ok\": False, \"error\": f\"Type failed: {e!s}\"},\n ensure_ascii=False,\n indent=2,\n ),\n )\n\n\nasync def _action_eval(page_id: str, code: str) -> ToolResponse:\n code = (code or \"\").strip()\n if not code:\n return _tool_response(\n json.dumps(\n {\"ok\": False, \"error\": \"code required for eval\"},\n ensure_ascii=False,\n indent=2,\n ),\n )\n page = _get_page(page_id)\n if not page:\n return _tool_response(\n json.dumps(\n {\"ok\": False, \"error\": f\"Page '{page_id}' not found\"},\n ensure_ascii=False,\n indent=2,\n ),\n )\n try:\n if code.strip().startswith(\"(\") or code.strip().startswith(\"function\"):\n if _USE_SYNC_PLAYWRIGHT:\n result = await _run_sync(page.evaluate, code)\n else:\n result = await page.evaluate(code)\n else:\n if _USE_SYNC_PLAYWRIGHT:\n result = await _run_sync(\n page.evaluate,\n f\"() => {{ return ({code}); }}\",\n )\n else:\n result = await page.evaluate(f\"() => {{ return ({code}); }}\")\n try:\n out = json.dumps(\n {\"ok\": True, \"result\": result},\n ensure_ascii=False,\n indent=2,\n )\n except TypeError:\n out = json.dumps(\n {\"ok\": True, \"result\": str(result)},\n ensure_ascii=False,\n indent=2,\n )\n return _tool_response(out)\n except Exception as e:\n return _tool_response(\n json.dumps(\n {\"ok\": False, \"error\": f\"Eval failed: {e!s}\"},\n ensure_ascii=False,\n indent=2,\n ),\n )\n\n\nasync def _action_pdf(page_id: str, path: str) -> ToolResponse:\n path = (path or \"page.pdf\").strip() or \"page.pdf\"\n page = _get_page(page_id)\n if not page:\n return _tool_response(\n json.dumps(\n {\"ok\": False, \"error\": f\"Page '{page_id}' not found\"},\n ensure_ascii=False,\n indent=2,\n ),\n )\n try:\n if _USE_SYNC_PLAYWRIGHT:\n await _run_sync(page.pdf, path=path)\n else:\n await page.pdf(path=path)\n return _tool_response(\n json.dumps(\n {\"ok\": True, \"message\": f\"PDF saved to {path}\", \"path\": path},\n ensure_ascii=False,\n indent=2,\n ),\n )\n except Exception as e:\n return _tool_response(\n json.dumps(\n {\"ok\": False, \"error\": f\"PDF failed: {e!s}\"},\n ensure_ascii=False,\n indent=2,\n ),\n )\n\n\nasync def _action_close(page_id: str) -> ToolResponse:\n page = _get_page(page_id)\n if not page:\n return _tool_response(\n json.dumps(\n {\"ok\": False, \"error\": f\"Page '{page_id}' not found\"},\n ensure_ascii=False,\n indent=2,\n ),\n )\n try:\n if _USE_SYNC_PLAYWRIGHT:\n await _run_sync(page.close)\n else:\n await page.close()\n del _state[\"pages\"][page_id]\n for key in (\n \"refs\",\n \"refs_frame\",\n \"console_logs\",\n \"network_requests\",\n \"pending_dialogs\",\n \"pending_file_choosers\",\n ):\n _state[key].pop(page_id, None)\n if _state.get(\"current_page_id\") == page_id:\n remaining = list(_state[\"pages\"].keys())\n _state[\"current_page_id\"] = remaining[0] if remaining else None\n return _tool_response(\n json.dumps(\n {\"ok\": True, \"message\": f\"Closed page '{page_id}'\"},\n ensure_ascii=False,\n indent=2,\n ),\n )\n except Exception as e:\n return _tool_response(\n json.dumps(\n {\"ok\": False, \"error\": f\"Close failed: {e!s}\"},\n ensure_ascii=False,\n indent=2,\n ),\n )\n\n\nasync def _action_snapshot(\n page_id: str,\n filename: str,\n frame_selector: str = \"\",\n) -> ToolResponse:\n page = _get_page(page_id)\n if not page:\n return _tool_response(\n json.dumps(\n {\"ok\": False, \"error\": f\"Page '{page_id}' not found\"},\n ensure_ascii=False,\n indent=2,\n ),\n )\n try:\n if _USE_SYNC_PLAYWRIGHT:\n # Hybrid mode: execute in thread pool\n loop = asyncio.get_event_loop()\n root = _get_root(page, page_id, frame_selector)\n locator = root.locator(\":root\")\n raw = await loop.run_in_executor(\n _get_executor(),\n lambda: locator.aria_snapshot(), # pylint: disable=unnecessary-lambda\n )\n else:\n root = _get_root(page, page_id, frame_selector)\n locator = root.locator(\":root\")\n raw = await locator.aria_snapshot()\n\n raw_str = str(raw) if raw is not None else \"\"\n snapshot, refs = build_role_snapshot_from_aria(\n raw_str,\n interactive=False,\n compact=False,\n )\n _state[\"refs\"][page_id] = refs\n _state[\"refs_frame\"][page_id] = (\n frame_selector.strip() if frame_selector else \"\"\n )\n out = {\n \"ok\": True,\n \"snapshot\": snapshot,\n \"refs\": list(refs.keys()),\n \"url\": page.url,\n }\n if frame_selector and frame_selector.strip():\n out[\"frame_selector\"] = frame_selector.strip()\n if filename and filename.strip():\n with open(filename.strip(), \"w\", encoding=\"utf-8\") as f:\n f.write(snapshot)\n out[\"filename\"] = filename.strip()\n return _tool_response(json.dumps(out, ensure_ascii=False, indent=2))\n except Exception as e:\n return _tool_response(\n json.dumps(\n {\"ok\": False, \"error\": f\"Snapshot failed: {e!s}\"},\n ensure_ascii=False,\n indent=2,\n ),\n )\n\n\nasync def _action_navigate_back(page_id: str) -> ToolResponse:\n page = _get_page(page_id)\n if not page:\n return _tool_response(\n json.dumps(\n {\"ok\": False, \"error\": f\"Page '{page_id}' not found\"},\n ensure_ascii=False,\n indent=2,\n ),\n )\n try:\n if _USE_SYNC_PLAYWRIGHT:\n await _run_sync(page.go_back)\n else:\n await page.go_back()\n return _tool_response(\n json.dumps(\n {\"ok\": True, \"message\": \"Navigated back\", \"url\": page.url},\n ensure_ascii=False,\n indent=2,\n ),\n )\n except Exception as e:\n return _tool_response(\n json.dumps(\n {\"ok\": False, \"error\": f\"Navigate back failed: {e!s}\"},\n ensure_ascii=False,\n indent=2,\n ),\n )\n\n\nasync def _action_evaluate(\n page_id: str,\n code: str,\n ref: str = \"\",\n element: str = \"\", # pylint: disable=unused-argument\n frame_selector: str = \"\",\n) -> ToolResponse:\n code = (code or \"\").strip()\n if not code:\n return _tool_response(\n json.dumps(\n {\"ok\": False, \"error\": \"code required for evaluate\"},\n ensure_ascii=False,\n indent=2,\n ),\n )\n page = _get_page(page_id)\n if not page:\n return _tool_response(\n json.dumps(\n {\"ok\": False, \"error\": f\"Page '{page_id}' not found\"},\n ensure_ascii=False,\n indent=2,\n ),\n )\n try:\n if ref and ref.strip():\n locator = _get_locator_by_ref(\n page,\n page_id,\n ref.strip(),\n frame_selector,\n )\n if locator is None:\n return _tool_response(\n json.dumps(\n {\"ok\": False, \"error\": f\"Unknown ref: {ref}\"},\n ensure_ascii=False,\n indent=2,\n ),\n )\n if _USE_SYNC_PLAYWRIGHT:\n result = await _run_sync(locator.evaluate, code)\n else:\n result = await locator.evaluate(code)\n else:\n if code.strip().startswith(\"(\") or code.strip().startswith(\n \"function\",\n ):\n if _USE_SYNC_PLAYWRIGHT:\n result = await _run_sync(page.evaluate, code)\n else:\n result = await page.evaluate(code)\n else:\n if _USE_SYNC_PLAYWRIGHT:\n result = await _run_sync(\n page.evaluate,\n f\"() => {{ return ({code}); }}\",\n )\n else:\n result = await page.evaluate(\n f\"() => {{ return ({code}); }}\",\n )\n try:\n out = json.dumps(\n {\"ok\": True, \"result\": result},\n ensure_ascii=False,\n indent=2,\n )\n except TypeError:\n out = json.dumps(\n {\"ok\": True, \"result\": str(result)},\n ensure_ascii=False,\n indent=2,\n )\n return _tool_response(out)\n except Exception as e:\n return _tool_response(\n json.dumps(\n {\"ok\": False, \"error\": f\"Evaluate failed: {e!s}\"},\n ensure_ascii=False,\n indent=2,\n ),\n )\n\n\nasync def _action_resize(\n page_id: str,\n width: int,\n height: int,\n) -> ToolResponse:\n if width <= 0 or height <= 0:\n return _tool_response(\n json.dumps(\n {\"ok\": False, \"error\": \"width and height must be positive\"},\n ensure_ascii=False,\n indent=2,\n ),\n )\n page = _get_page(page_id)\n if not page:\n return _tool_response(\n json.dumps(\n {\"ok\": False, \"error\": f\"Page '{page_id}' not found\"},\n ensure_ascii=False,\n indent=2,\n ),\n )\n try:\n if _USE_SYNC_PLAYWRIGHT:\n await _run_sync(\n page.set_viewport_size,\n {\"width\": width, \"height\": height},\n )\n else:\n await page.set_viewport_size({\"width\": width, \"height\": height})\n return _tool_response(\n json.dumps(\n {\"ok\": True, \"message\": f\"Resized to {width}x{height}\"},\n ensure_ascii=False,\n indent=2,\n ),\n )\n except Exception as e:\n return _tool_response(\n json.dumps(\n {\"ok\": False, \"error\": f\"Resize failed: {e!s}\"},\n ensure_ascii=False,\n indent=2,\n ),\n )\n\n\nasync def _action_console_messages(\n page_id: str,\n level: str,\n filename: str,\n) -> ToolResponse:\n level = (level or \"info\").strip().lower()\n order = (\"error\", \"warning\", \"info\", \"debug\")\n idx = order.index(level) if level in order else 2\n page = _get_page(page_id)\n if not page:\n return _tool_response(\n json.dumps(\n {\"ok\": False, \"error\": f\"Page '{page_id}' not found\"},\n ensure_ascii=False,\n indent=2,\n ),\n )\n logs = _state[\"console_logs\"].get(page_id, [])\n filtered = (\n [m for m in logs if order.index(m[\"level\"]) <= idx]\n if level in order\n else logs\n )\n lines = [f\"[{m['level']}] {m['text']}\" for m in filtered]\n text = \"\\n\".join(lines)\n if filename and filename.strip():\n with open(filename.strip(), \"w\", encoding=\"utf-8\") as f:\n f.write(text)\n return _tool_response(\n json.dumps(\n {\n \"ok\": True,\n \"message\": f\"Console messages saved to {filename}\",\n \"filename\": filename.strip(),\n },\n ensure_ascii=False,\n indent=2,\n ),\n )\n return _tool_response(\n json.dumps(\n {\"ok\": True, \"messages\": filtered, \"text\": text},\n ensure_ascii=False,\n indent=2,\n ),\n )\n\n\nasync def _action_handle_dialog(\n page_id: str,\n accept: bool,\n prompt_text: str,\n) -> ToolResponse:\n page = _get_page(page_id)\n if not page:\n return _tool_response(\n json.dumps(\n {\"ok\": False, \"error\": f\"Page '{page_id}' not found\"},\n ensure_ascii=False,\n indent=2,\n ),\n )\n dialogs = _state[\"pending_dialogs\"].get(page_id, [])\n if not dialogs:\n return _tool_response(\n json.dumps(\n {\"ok\": False, \"error\": \"No pending dialog\"},\n ensure_ascii=False,\n indent=2,\n ),\n )\n try:\n dialog = dialogs.pop(0)\n if accept:\n if prompt_text and hasattr(dialog, \"accept\"):\n if _USE_SYNC_PLAYWRIGHT:\n await _run_sync(dialog.accept, prompt_text)\n else:\n await dialog.accept(prompt_text)\n else:\n if _USE_SYNC_PLAYWRIGHT:\n await _run_sync(dialog.accept)\n else:\n await dialog.accept()\n else:\n if _USE_SYNC_PLAYWRIGHT:\n await _run_sync(dialog.dismiss)\n else:\n await dialog.dismiss()\n return _tool_response(\n json.dumps(\n {\"ok\": True, \"message\": \"Dialog handled\"},\n ensure_ascii=False,\n indent=2,\n ),\n )\n except Exception as e:\n return _tool_response(\n json.dumps(\n {\"ok\": False, \"error\": f\"Handle dialog failed: {e!s}\"},\n ensure_ascii=False,\n indent=2,\n ),\n )\n\n\nasync def _action_file_upload(page_id: str, paths_json: str) -> ToolResponse:\n page = _get_page(page_id)\n if not page:\n return _tool_response(\n json.dumps(\n {\"ok\": False, \"error\": f\"Page '{page_id}' not found\"},\n ensure_ascii=False,\n indent=2,\n ),\n )\n paths = _parse_json_param(paths_json, [])\n if not isinstance(paths, list):\n paths = []\n try:\n choosers = _state[\"pending_file_choosers\"].get(page_id, [])\n if not choosers:\n return _tool_response(\n json.dumps(\n {\n \"ok\": False,\n \"error\": \"No chooser. Click upload then file_upload.\",\n },\n ensure_ascii=False,\n indent=2,\n ),\n )\n chooser = choosers.pop(0)\n if paths:\n if _USE_SYNC_PLAYWRIGHT:\n await _run_sync(chooser.set_files, paths)\n else:\n await chooser.set_files(paths)\n return _tool_response(\n json.dumps(\n {\"ok\": True, \"message\": f\"Uploaded {len(paths)} file(s)\"},\n ensure_ascii=False,\n indent=2,\n ),\n )\n if _USE_SYNC_PLAYWRIGHT:\n await _run_sync(chooser.set_files, [])\n else:\n await chooser.set_files([])\n return _tool_response(\n json.dumps(\n {\"ok\": True, \"message\": \"File chooser cancelled\"},\n ensure_ascii=False,\n indent=2,\n ),\n )\n except Exception as e:\n return _tool_response(\n json.dumps(\n {\"ok\": False, \"error\": f\"File upload failed: {e!s}\"},\n ensure_ascii=False,\n indent=2,\n ),\n )\n\n\nasync def _action_fill_form(page_id: str, fields_json: str) -> ToolResponse:\n page = _get_page(page_id)\n if not page:\n return _tool_response(\n json.dumps(\n {\"ok\": False, \"error\": f\"Page '{page_id}' not found\"},\n ensure_ascii=False,\n indent=2,\n ),\n )\n fields = _parse_json_param(fields_json, [])\n if not isinstance(fields, list) or not fields:\n return _tool_response(\n json.dumps(\n {\"ok\": False, \"error\": \"fields required (JSON array)\"},\n ensure_ascii=False,\n indent=2,\n ),\n )\n refs = _get_refs(page_id)\n # Use last snapshot's frame so fill_form works after iframe snapshot\n frame = _state[\"refs_frame\"].get(page_id, \"\")\n try:\n for f in fields:\n ref = (f.get(\"ref\") or \"\").strip()\n if not ref or ref not in refs:\n continue\n locator = _get_locator_by_ref(page, page_id, ref, frame)\n if locator is None:\n continue\n field_type = (f.get(\"type\") or \"textbox\").lower()\n value = f.get(\"value\")\n if field_type == \"checkbox\":\n if isinstance(value, str):\n value = value.strip().lower() in (\"true\", \"1\", \"yes\")\n if _USE_SYNC_PLAYWRIGHT:\n await _run_sync(locator.set_checked, bool(value))\n else:\n await locator.set_checked(bool(value))\n elif field_type == \"radio\":\n if _USE_SYNC_PLAYWRIGHT:\n await _run_sync(locator.set_checked, True)\n else:\n await locator.set_checked(True)\n elif field_type == \"combobox\":\n if _USE_SYNC_PLAYWRIGHT:\n await _run_sync(\n locator.select_option,\n label=value if isinstance(value, str) else None,\n value=value,\n )\n else:\n await locator.select_option(\n label=value if isinstance(value, str) else None,\n value=value,\n )\n elif field_type == \"slider\":\n if _USE_SYNC_PLAYWRIGHT:\n await _run_sync(locator.fill, str(value))\n else:\n await locator.fill(str(value))\n else:\n if _USE_SYNC_PLAYWRIGHT:\n await _run_sync(\n locator.fill,\n str(value) if value is not None else \"\",\n )\n else:\n await locator.fill(str(value) if value is not None else \"\")\n return _tool_response(\n json.dumps(\n {\"ok\": True, \"message\": f\"Filled {len(fields)} field(s)\"},\n ensure_ascii=False,\n indent=2,\n ),\n )\n except Exception as e:\n return _tool_response(\n json.dumps(\n {\"ok\": False, \"error\": f\"Fill form failed: {e!s}\"},\n ensure_ascii=False,\n indent=2,\n ),\n )\n\n\ndef _run_playwright_install() -> None:\n \"\"\"Run playwright install in a blocking way (for use in thread).\"\"\"\n subprocess.run(\n [sys.executable, \"-m\", \"playwright\", \"install\"],\n check=True,\n capture_output=True,\n text=True,\n timeout=600, # 10 minutes max\n )\n\n\nasync def _action_install() -> ToolResponse:\n \"\"\"Install Playwright browsers. If a system Chrome/Chromium/Edge is found,\n use it and skip download. On macOS with no Chromium, use Safari (WebKit)\n so no download is needed. Only run playwright install when necessary.\n \"\"\"\n exe = _chromium_executable_path()\n if exe:\n return _tool_response(\n json.dumps(\n {\n \"ok\": True,\n \"message\": f\"Using system browser (no download): {exe}\",\n },\n ensure_ascii=False,\n indent=2,\n ),\n )\n if _use_webkit_fallback():\n return _tool_response(\n json.dumps(\n {\n \"ok\": True,\n \"message\": \"On macOS using Safari (WebKit); no browser download needed.\",\n },\n ensure_ascii=False,\n indent=2,\n ),\n )\n try:\n await asyncio.to_thread(_run_playwright_install)\n return _tool_response(\n json.dumps(\n {\"ok\": True, \"message\": \"Browser installed\"},\n ensure_ascii=False,\n indent=2,\n ),\n )\n except subprocess.TimeoutExpired:\n return _tool_response(\n json.dumps(\n {\n \"ok\": False,\n \"error\": \"Browser install timed out (10 min). Run manually in terminal: \"\n f\"{sys.executable!s} -m playwright install\",\n },\n ensure_ascii=False,\n indent=2,\n ),\n )\n except Exception as e:\n return _tool_response(\n json.dumps(\n {\n \"ok\": False,\n \"error\": f\"Install failed: {e!s}. Install manually: \"\n f\"{sys.executable!s} -m pip install playwright && \"\n f\"{sys.executable!s} -m playwright install\",\n },\n ensure_ascii=False,\n indent=2,\n ),\n )\n\n\nasync def _action_press_key(page_id: str, key: str) -> ToolResponse:\n key = (key or \"\").strip()\n if not key:\n return _tool_response(\n json.dumps(\n {\"ok\": False, \"error\": \"key required for press_key\"},\n ensure_ascii=False,\n indent=2,\n ),\n )\n page = _get_page(page_id)\n if not page:\n return _tool_response(\n json.dumps(\n {\"ok\": False, \"error\": f\"Page '{page_id}' not found\"},\n ensure_ascii=False,\n indent=2,\n ),\n )\n try:\n if _USE_SYNC_PLAYWRIGHT:\n await _run_sync(page.keyboard.press, key)\n else:\n await page.keyboard.press(key)\n return _tool_response(\n json.dumps(\n {\"ok\": True, \"message\": f\"Pressed key {key}\"},\n ensure_ascii=False,\n indent=2,\n ),\n )\n except Exception as e:\n return _tool_response(\n json.dumps(\n {\"ok\": False, \"error\": f\"Press key failed: {e!s}\"},\n ensure_ascii=False,\n indent=2,\n ),\n )\n\n\nasync def _action_network_requests(\n page_id: str,\n include_static: bool,\n filename: str,\n) -> ToolResponse:\n page = _get_page(page_id)\n if not page:\n return _tool_response(\n json.dumps(\n {\"ok\": False, \"error\": f\"Page '{page_id}' not found\"},\n ensure_ascii=False,\n indent=2,\n ),\n )\n requests = _state[\"network_requests\"].get(page_id, [])\n if not include_static:\n static = (\"image\", \"stylesheet\", \"font\", \"media\")\n requests = [r for r in requests if r.get(\"resourceType\") not in static]\n lines = [\n f\"{r.get('method', '')} {r.get('url', '')} {r.get('status', '')}\"\n for r in requests\n ]\n text = \"\\n\".join(lines)\n if filename and filename.strip():\n with open(filename.strip(), \"w\", encoding=\"utf-8\") as f:\n f.write(text)\n return _tool_response(\n json.dumps(\n {\n \"ok\": True,\n \"message\": f\"Network requests saved to {filename}\",\n \"filename\": filename.strip(),\n },\n ensure_ascii=False,\n indent=2,\n ),\n )\n return _tool_response(\n json.dumps(\n {\"ok\": True, \"requests\": requests, \"text\": text},\n ensure_ascii=False,\n indent=2,\n ),\n )\n\n\nasync def _action_run_code(page_id: str, code: str) -> ToolResponse:\n \"\"\"Run JS in page (like eval). Use evaluate for element (ref).\"\"\"\n code = (code or \"\").strip()\n if not code:\n return _tool_response(\n json.dumps(\n {\"ok\": False, \"error\": \"code required for run_code\"},\n ensure_ascii=False,\n indent=2,\n ),\n )\n page = _get_page(page_id)\n if not page:\n return _tool_response(\n json.dumps(\n {\"ok\": False, \"error\": f\"Page '{page_id}' not found\"},\n ensure_ascii=False,\n indent=2,\n ),\n )\n try:\n if code.strip().startswith(\"(\") or code.strip().startswith(\"function\"):\n if _USE_SYNC_PLAYWRIGHT:\n result = await _run_sync(page.evaluate, code)\n else:\n result = await page.evaluate(code)\n else:\n if _USE_SYNC_PLAYWRIGHT:\n result = await _run_sync(\n page.evaluate,\n f\"() => {{ return ({code}); }}\",\n )\n else:\n result = await page.evaluate(f\"() => {{ return ({code}); }}\")\n try:\n out = json.dumps(\n {\"ok\": True, \"result\": result},\n ensure_ascii=False,\n indent=2,\n )\n except TypeError:\n out = json.dumps(\n {\"ok\": True, \"result\": str(result)},\n ensure_ascii=False,\n indent=2,\n )\n return _tool_response(out)\n except Exception as e:\n return _tool_response(\n json.dumps(\n {\"ok\": False, \"error\": f\"Run code failed: {e!s}\"},\n ensure_ascii=False,\n indent=2,\n ),\n )\n\n\nasync def _action_drag(\n page_id: str,\n start_ref: str,\n end_ref: str,\n start_selector: str = \"\",\n end_selector: str = \"\",\n start_element: str = \"\", # pylint: disable=unused-argument\n end_element: str = \"\", # pylint: disable=unused-argument\n frame_selector: str = \"\",\n) -> ToolResponse:\n start_ref = (start_ref or \"\").strip()\n end_ref = (end_ref or \"\").strip()\n start_selector = (start_selector or \"\").strip()\n end_selector = (end_selector or \"\").strip()\n use_refs = bool(start_ref and end_ref)\n use_selectors = bool(start_selector and end_selector)\n if not use_refs and not use_selectors:\n return _tool_response(\n json.dumps(\n {\n \"ok\": False,\n \"error\": (\n \"drag needs (start_ref,end_ref) or (start_sel,end_sel)\"\n ),\n },\n ensure_ascii=False,\n indent=2,\n ),\n )\n page = _get_page(page_id)\n if not page:\n return _tool_response(\n json.dumps(\n {\"ok\": False, \"error\": f\"Page '{page_id}' not found\"},\n ensure_ascii=False,\n indent=2,\n ),\n )\n try:\n root = _get_root(page, page_id, frame_selector)\n if use_refs:\n start_locator = _get_locator_by_ref(\n page,\n page_id,\n start_ref,\n frame_selector,\n )\n end_locator = _get_locator_by_ref(\n page,\n page_id,\n end_ref,\n frame_selector,\n )\n if start_locator is None or end_locator is None:\n return _tool_response(\n json.dumps(\n {\"ok\": False, \"error\": \"Unknown ref for drag\"},\n ensure_ascii=False,\n indent=2,\n ),\n )\n else:\n start_locator = root.locator(start_selector).first\n end_locator = root.locator(end_selector).first\n if _USE_SYNC_PLAYWRIGHT:\n await _run_sync(start_locator.drag_to, end_locator)\n else:\n await start_locator.drag_to(end_locator)\n return _tool_response(\n json.dumps(\n {\"ok\": True, \"message\": \"Drag completed\"},\n ensure_ascii=False,\n indent=2,\n ),\n )\n except Exception as e:\n return _tool_response(\n json.dumps(\n {\"ok\": False, \"error\": f\"Drag failed: {e!s}\"},\n ensure_ascii=False,\n indent=2,\n ),\n )\n\n\nasync def _action_hover(\n page_id: str,\n ref: str = \"\",\n element: str = \"\", # pylint: disable=unused-argument\n selector: str = \"\",\n frame_selector: str = \"\",\n) -> ToolResponse:\n ref = (ref or \"\").strip()\n selector = (selector or \"\").strip()\n if not ref and not selector:\n return _tool_response(\n json.dumps(\n {\"ok\": False, \"error\": \"hover requires ref or selector\"},\n ensure_ascii=False,\n indent=2,\n ),\n )\n page = _get_page(page_id)\n if not page:\n return _tool_response(\n json.dumps(\n {\"ok\": False, \"error\": f\"Page '{page_id}' not found\"},\n ensure_ascii=False,\n indent=2,\n ),\n )\n try:\n if ref:\n locator = _get_locator_by_ref(page, page_id, ref, frame_selector)\n if locator is None:\n return _tool_response(\n json.dumps(\n {\"ok\": False, \"error\": f\"Unknown ref: {ref}\"},\n ensure_ascii=False,\n indent=2,\n ),\n )\n else:\n root = _get_root(page, page_id, frame_selector)\n locator = root.locator(selector).first\n if _USE_SYNC_PLAYWRIGHT:\n await _run_sync(locator.hover)\n else:\n await locator.hover()\n return _tool_response(\n json.dumps(\n {\"ok\": True, \"message\": f\"Hovered {ref or selector}\"},\n ensure_ascii=False,\n indent=2,\n ),\n )\n except Exception as e:\n return _tool_response(\n json.dumps(\n {\"ok\": False, \"error\": f\"Hover failed: {e!s}\"},\n ensure_ascii=False,\n indent=2,\n ),\n )\n\n\nasync def _action_select_option(\n page_id: str,\n ref: str = \"\",\n element: str = \"\", # pylint: disable=unused-argument\n values_json: str = \"\",\n frame_selector: str = \"\",\n) -> ToolResponse:\n ref = (ref or \"\").strip()\n values = _parse_json_param(values_json, [])\n if not isinstance(values, list):\n values = [values] if values is not None else []\n if not ref:\n return _tool_response(\n json.dumps(\n {\"ok\": False, \"error\": \"ref required for select_option\"},\n ensure_ascii=False,\n indent=2,\n ),\n )\n if not values:\n return _tool_response(\n json.dumps(\n {\n \"ok\": False,\n \"error\": \"values required (JSON array or comma-separated)\",\n },\n ensure_ascii=False,\n indent=2,\n ),\n )\n page = _get_page(page_id)\n if not page:\n return _tool_response(\n json.dumps(\n {\"ok\": False, \"error\": f\"Page '{page_id}' not found\"},\n ensure_ascii=False,\n indent=2,\n ),\n )\n try:\n locator = _get_locator_by_ref(page, page_id, ref, frame_selector)\n if locator is None:\n return _tool_response(\n json.dumps(\n {\"ok\": False, \"error\": f\"Unknown ref: {ref}\"},\n ensure_ascii=False,\n indent=2,\n ),\n )\n if _USE_SYNC_PLAYWRIGHT:\n await _run_sync(locator.select_option, value=values)\n else:\n await locator.select_option(value=values)\n return _tool_response(\n json.dumps(\n {\"ok\": True, \"message\": f\"Selected {values}\"},\n ensure_ascii=False,\n indent=2,\n ),\n )\n except Exception as e:\n return _tool_response(\n json.dumps(\n {\"ok\": False, \"error\": f\"Select option failed: {e!s}\"},\n ensure_ascii=False,\n indent=2,\n ),\n )\n\n\nasync def _action_tabs( # pylint: disable=too-many-return-statements\n page_id: str,\n tab_action: str,\n index: int,\n) -> ToolResponse:\n tab_action = (tab_action or \"\").strip().lower()\n if not tab_action:\n return _tool_response(\n json.dumps(\n {\n \"ok\": False,\n \"error\": \"tab_action required (list, new, close, select)\",\n },\n ensure_ascii=False,\n indent=2,\n ),\n )\n pages = _state[\"pages\"]\n page_ids = list(pages.keys())\n if tab_action == \"list\":\n return _tool_response(\n json.dumps(\n {\"ok\": True, \"tabs\": page_ids, \"count\": len(page_ids)},\n ensure_ascii=False,\n indent=2,\n ),\n )\n if tab_action == \"new\":\n if _USE_SYNC_PLAYWRIGHT:\n if not _state[\"_sync_context\"]:\n ok = await _ensure_browser()\n if not ok:\n err = (\n _state.get(\"_last_browser_error\")\n or \"Browser not started\"\n )\n return _tool_response(\n json.dumps(\n {\"ok\": False, \"error\": err},\n ensure_ascii=False,\n indent=2,\n ),\n )\n else:\n if not _state[\"context\"]:\n ok = await _ensure_browser()\n if not ok:\n err = (\n _state.get(\"_last_browser_error\")\n or \"Browser not started\"\n )\n return _tool_response(\n json.dumps(\n {\"ok\": False, \"error\": err},\n ensure_ascii=False,\n indent=2,\n ),\n )\n try:\n if _USE_SYNC_PLAYWRIGHT:\n page = await _run_sync(_state[\"_sync_context\"].new_page)\n else:\n page = await _state[\"context\"].new_page()\n new_id = _next_page_id()\n _state[\"refs\"][new_id] = {}\n _state[\"console_logs\"][new_id] = []\n _state[\"network_requests\"][new_id] = []\n _state[\"pending_dialogs\"][new_id] = []\n _attach_page_listeners(page, new_id)\n _state[\"pages\"][new_id] = page\n _state[\"current_page_id\"] = new_id\n return _tool_response(\n json.dumps(\n {\n \"ok\": True,\n \"page_id\": new_id,\n \"tabs\": list(_state[\"pages\"].keys()),\n },\n ensure_ascii=False,\n indent=2,\n ),\n )\n except Exception as e:\n return _tool_response(\n json.dumps(\n {\"ok\": False, \"error\": f\"New tab failed: {e!s}\"},\n ensure_ascii=False,\n indent=2,\n ),\n )\n if tab_action == \"close\":\n target_id = page_ids[index] if 0 <= index < len(page_ids) else page_id\n return await _action_close(target_id)\n if tab_action == \"select\":\n target_id = page_ids[index] if 0 <= index < len(page_ids) else page_id\n _state[\"current_page_id\"] = target_id\n return _tool_response(\n json.dumps(\n {\n \"ok\": True,\n \"message\": f\"Use page_id={target_id} for later actions\",\n \"page_id\": target_id,\n },\n ensure_ascii=False,\n indent=2,\n ),\n )\n return _tool_response(\n json.dumps(\n {\"ok\": False, \"error\": f\"Unknown tab_action: {tab_action}\"},\n ensure_ascii=False,\n indent=2,\n ),\n )\n\n\nasync def _action_wait_for(\n page_id: str,\n wait_time: float,\n text: str,\n text_gone: str,\n) -> ToolResponse:\n page = _get_page(page_id)\n if not page:\n return _tool_response(\n json.dumps(\n {\"ok\": False, \"error\": f\"Page '{page_id}' not found\"},\n ensure_ascii=False,\n indent=2,\n ),\n )\n try:\n if wait_time and wait_time > 0:\n await asyncio.sleep(wait_time)\n text = (text or \"\").strip()\n text_gone = (text_gone or \"\").strip()\n if text:\n locator = page.get_by_text(text)\n if _USE_SYNC_PLAYWRIGHT:\n await _run_sync(\n locator.wait_for,\n state=\"visible\",\n timeout=30000,\n )\n else:\n await locator.wait_for(\n state=\"visible\",\n timeout=30000,\n )\n if text_gone:\n locator = page.get_by_text(text_gone)\n if _USE_SYNC_PLAYWRIGHT:\n await _run_sync(\n locator.wait_for,\n state=\"hidden\",\n timeout=30000,\n )\n else:\n await locator.wait_for(\n state=\"hidden\",\n timeout=30000,\n )\n return _tool_response(\n json.dumps(\n {\"ok\": True, \"message\": \"Wait completed\"},\n ensure_ascii=False,\n indent=2,\n ),\n )\n except Exception as e:\n return _tool_response(\n json.dumps(\n {\"ok\": False, \"error\": f\"Wait failed: {e!s}\"},\n ensure_ascii=False,\n indent=2,\n ),\n )\n" }, { "path": "src/copaw/agents/tools/browser_snapshot.py", "content": "# -*- coding: utf-8 -*-\n\"\"\"Build role snapshot + refs from Playwright aria_snapshot.\"\"\"\n\nimport re\nfrom typing import Any\n\nINTERACTIVE_ROLES = frozenset(\n {\n \"button\",\n \"link\",\n \"textbox\",\n \"checkbox\",\n \"radio\",\n \"combobox\",\n \"listbox\",\n \"menuitem\",\n \"menuitemcheckbox\",\n \"menuitemradio\",\n \"option\",\n \"searchbox\",\n \"slider\",\n \"spinbutton\",\n \"switch\",\n \"tab\",\n \"treeitem\",\n },\n)\n\nCONTENT_ROLES = frozenset(\n {\n \"heading\",\n \"cell\",\n \"gridcell\",\n \"columnheader\",\n \"rowheader\",\n \"listitem\",\n \"article\",\n \"region\",\n \"main\",\n \"navigation\",\n },\n)\n\nSTRUCTURAL_ROLES = frozenset(\n {\n \"generic\",\n \"group\",\n \"list\",\n \"table\",\n \"row\",\n \"rowgroup\",\n \"grid\",\n \"treegrid\",\n \"menu\",\n \"menubar\",\n \"toolbar\",\n \"tablist\",\n \"tree\",\n \"directory\",\n \"document\",\n \"application\",\n \"presentation\",\n \"none\",\n },\n)\n\n\ndef _get_indent_level(line: str) -> int:\n m = re.match(r\"^(\\s*)\", line)\n return int(len(m.group(1)) / 2) if m else 0\n\n\ndef _create_tracker() -> dict[str, Any]:\n counts: dict[str, int] = {}\n refs_by_key: dict[str, list[str]] = {}\n\n def get_key(role: str, name: str | None) -> str:\n return f\"{role}:{name or ''}\"\n\n def get_next_index(role: str, name: str | None) -> int:\n key = get_key(role, name)\n current = counts.get(key, 0)\n counts[key] = current + 1\n return current\n\n def track_ref(role: str, name: str | None, ref: str) -> None:\n key = get_key(role, name)\n refs_by_key.setdefault(key, []).append(ref)\n\n def get_duplicate_keys() -> set[str]:\n return {k for k, refs in refs_by_key.items() if len(refs) > 1}\n\n return {\n \"get_next_index\": get_next_index,\n \"track_ref\": track_ref,\n \"get_duplicate_keys\": get_duplicate_keys,\n \"get_key\": get_key,\n }\n\n\ndef _remove_nth_from_non_duplicates(\n refs: dict[str, dict],\n tracker: dict,\n) -> None:\n dup_keys = tracker[\"get_duplicate_keys\"]()\n for _, data in list(refs.items()):\n key = tracker[\"get_key\"](data[\"role\"], data.get(\"name\"))\n if key not in dup_keys and \"nth\" in data:\n del data[\"nth\"]\n\n\ndef _compact_tree(tree: str) -> str:\n lines = tree.split(\"\\n\")\n result = []\n for i, line in enumerate(lines):\n if \"[ref=\" in line:\n result.append(line)\n continue\n if \":\" in line and not line.rstrip().endswith(\":\"):\n result.append(line)\n continue\n current_indent = _get_indent_level(line)\n has_relevant = False\n for j in range(i + 1, len(lines)):\n if _get_indent_level(lines[j]) <= current_indent:\n break\n if \"[ref=\" in lines[j]:\n has_relevant = True\n break\n if has_relevant:\n result.append(line)\n return \"\\n\".join(result)\n\n\ndef _process_line( # pylint: disable=too-many-return-statements\n line: str,\n refs: dict[str, dict],\n options: dict[str, Any],\n tracker: dict,\n next_ref: Any,\n) -> str | None:\n depth = _get_indent_level(line)\n max_depth_val = options.get(\"maxDepth\")\n if max_depth_val is not None and depth > max_depth_val:\n return None\n\n m = re.match(r'^(\\s*-\\s*)(\\w+)(?:\\s+\"([^\"]*)\")?(.*)$', line)\n if not m:\n return None if options.get(\"interactive\") else line\n\n prefix, role_raw, name, suffix = m.groups()\n if role_raw.startswith(\"/\"):\n return None if options.get(\"interactive\") else line\n\n role = role_raw.lower()\n is_interactive = role in INTERACTIVE_ROLES\n is_content = role in CONTENT_ROLES\n is_structural = role in STRUCTURAL_ROLES\n\n if options.get(\"interactive\") and not is_interactive:\n return None\n if options.get(\"compact\") and is_structural and not name:\n return None\n\n should_have_ref = is_interactive or (is_content and name)\n if not should_have_ref:\n return line\n\n ref = next_ref()\n nth = tracker[\"get_next_index\"](role, name)\n tracker[\"track_ref\"](role, name, ref)\n refs[ref] = {\"role\": role, \"name\": name, \"nth\": nth}\n\n enhanced = f\"{prefix}{role_raw}\"\n if name:\n enhanced += f' \"{name}\"'\n enhanced += f\" [ref={ref}]\"\n if nth is not None and nth > 0:\n enhanced += f\" [nth={nth}]\"\n if suffix:\n enhanced += suffix\n return enhanced\n\n\ndef build_role_snapshot_from_aria(\n aria_snapshot: str,\n *,\n interactive: bool = False,\n compact: bool = False,\n max_depth: int | None = None,\n) -> tuple[str, dict[str, dict]]:\n \"\"\"Build snapshot + refs from Playwright locator.aria_snapshot() output.\"\"\"\n options = {\n \"interactive\": interactive,\n \"compact\": compact,\n \"maxDepth\": max_depth,\n }\n lines = aria_snapshot.split(\"\\n\")\n refs: dict[str, dict] = {}\n tracker = _create_tracker()\n counter = [0]\n\n def next_ref() -> str:\n counter[0] += 1\n return f\"e{counter[0]}\"\n\n if options.get(\"interactive\"):\n result_lines = []\n for line in lines:\n depth = _get_indent_level(line)\n max_d = options.get(\"maxDepth\")\n if max_d is not None and depth > max_d:\n continue\n m = re.match(r'^(\\s*-\\s*)(\\w+)(?:\\s+\"([^\"]*)\")?(.*)$', line)\n if not m:\n continue\n _, role_raw, name, suffix = m.groups()\n if role_raw.startswith(\"/\"):\n continue\n role = role_raw.lower()\n if role not in INTERACTIVE_ROLES:\n continue\n ref = next_ref()\n nth = tracker[\"get_next_index\"](role, name)\n tracker[\"track_ref\"](role, name, ref)\n refs[ref] = {\"role\": role, \"name\": name, \"nth\": nth}\n enhanced = f\"- {role_raw}\"\n if name:\n enhanced += f' \"{name}\"'\n enhanced += f\" [ref={ref}]\"\n if nth is not None and nth > 0:\n enhanced += f\" [nth={nth}]\"\n if \"[\" in suffix:\n enhanced += suffix\n result_lines.append(enhanced)\n _remove_nth_from_non_duplicates(refs, tracker)\n snapshot = \"\\n\".join(result_lines) or \"(no interactive elements)\"\n return snapshot, refs\n\n result_lines = []\n for line in lines:\n processed = _process_line(line, refs, options, tracker, next_ref)\n if processed is not None:\n result_lines.append(processed)\n _remove_nth_from_non_duplicates(refs, tracker)\n tree = \"\\n\".join(result_lines) or \"(empty)\"\n snapshot = _compact_tree(tree) if options.get(\"compact\") else tree\n return snapshot, refs\n" }, { "path": "src/copaw/agents/tools/desktop_screenshot.py", "content": "# -*- coding: utf-8 -*-\n\"\"\"Desktop/screen screenshot tool.\"\"\"\n\nimport json\nimport os\nimport platform\nimport subprocess\nimport tempfile\nimport time\n\nfrom agentscope.message import TextBlock\nfrom agentscope.tool import ToolResponse\n\n\ndef _tool_error(msg: str) -> ToolResponse:\n return ToolResponse(\n content=[\n TextBlock(\n type=\"text\",\n text=json.dumps(\n {\"ok\": False, \"error\": msg},\n ensure_ascii=False,\n indent=2,\n ),\n ),\n ],\n )\n\n\ndef _tool_ok(path: str, message: str) -> ToolResponse:\n return ToolResponse(\n content=[\n TextBlock(\n type=\"text\",\n text=json.dumps(\n {\n \"ok\": True,\n \"path\": os.path.abspath(path),\n \"message\": message,\n },\n ensure_ascii=False,\n indent=2,\n ),\n ),\n ],\n )\n\n\ndef _capture_mss(path: str) -> ToolResponse:\n \"\"\"Full-screen capture using mss (Windows, Linux, macOS).\"\"\"\n try:\n import mss\n except ImportError:\n return _tool_error(\n \"desktop_screenshot requires the 'mss' package. \"\n \"Install with: pip install mss\",\n )\n try:\n with mss.mss() as sct:\n # mon=0: all monitors combined\n sct.shot(mon=0, output=path)\n if not os.path.isfile(path):\n return _tool_error(\"mss reported success but file was not created\")\n return _tool_ok(path, f\"Desktop screenshot saved to {path}\")\n except Exception as e:\n return _tool_error(f\"desktop_screenshot (mss) failed: {e!s}\")\n\n\ndef _capture_macos_screencapture(\n path: str,\n capture_window: bool,\n) -> ToolResponse:\n \"\"\"macOS: screencapture (supports window selection with -w).\"\"\"\n cmd = [\"screencapture\", \"-x\", path]\n if capture_window:\n cmd.insert(-1, \"-w\")\n try:\n result = subprocess.run(\n cmd,\n capture_output=True,\n text=True,\n timeout=30,\n check=False,\n )\n if result.returncode != 0:\n stderr = (result.stderr or \"\").strip() or \"Unknown error\"\n return _tool_error(f\"screencapture failed: {stderr}\")\n if not os.path.isfile(path):\n return _tool_error(\n \"screencapture reported success but file was not created\",\n )\n return _tool_ok(path, f\"Desktop screenshot saved to {path}\")\n except subprocess.TimeoutExpired:\n return _tool_error(\n \"screencapture timed out (e.g. window selection cancelled)\",\n )\n except Exception as e:\n return _tool_error(f\"desktop_screenshot failed: {e!s}\")\n\n\nasync def desktop_screenshot(\n path: str = \"\",\n capture_window: bool = False,\n) -> ToolResponse:\n \"\"\"Capture a screenshot of the entire desktop (all monitors)\n or a single window.\n\n Supported platforms: Windows, Linux, macOS. Full-screen\n capture uses the mss library on all platforms.\n On macOS, capture_window=True uses the system screencapture\n tool to let the user click a window to capture.\n\n Args:\n path (`str`):\n Optional path to save the screenshot. If empty, saves to a temp\n file and returns that path. Should end in .png for PNG output.\n capture_window (`bool`):\n If True on macOS, the user can click a window to capture just\n that window. On Windows/Linux, only full-screen is supported\n (capture_window is ignored).\n\n Returns:\n `ToolResponse`:\n JSON with \"ok\", \"path\" (saved file path), and optional \"message\"\n or \"error\".\n \"\"\"\n path = (path or \"\").strip()\n if not path:\n path = os.path.join(\n tempfile.gettempdir(),\n f\"desktop_screenshot_{int(time.time())}.png\",\n )\n if not path.lower().endswith(\".png\"):\n path = path.rstrip(\"/\\\\\") + \".png\"\n\n system = platform.system()\n\n # macOS: optional window selection via screencapture -w\n if system == \"Darwin\" and capture_window:\n return _capture_macos_screencapture(path, capture_window=True)\n\n # Full-screen on all platforms (macOS, Linux, Windows) via mss\n return _capture_mss(path)\n" }, { "path": "src/copaw/agents/tools/file_io.py", "content": "# -*- coding: utf-8 -*-\n# flake8: noqa: E501\n# pylint: disable=line-too-long\nimport os\nfrom pathlib import Path\nfrom typing import Optional\n\nfrom agentscope.message import TextBlock\nfrom agentscope.tool import ToolResponse\n\nfrom ...constant import WORKING_DIR\nfrom ...config.context import get_current_workspace_dir\nfrom .utils import truncate_file_output, read_file_safe\n\n\ndef _resolve_file_path(file_path: str) -> str:\n \"\"\"Resolve file path: use absolute path as-is,\n resolve relative path from current workspace or WORKING_DIR.\n\n Args:\n file_path: The input file path (absolute or relative).\n\n Returns:\n The resolved absolute file path as string.\n \"\"\"\n path = Path(file_path).expanduser()\n if path.is_absolute():\n return str(path)\n else:\n # Use current workspace_dir from context, fallback to WORKING_DIR\n workspace_dir = get_current_workspace_dir() or WORKING_DIR\n return str(workspace_dir / file_path)\n\n\nasync def read_file( # pylint: disable=too-many-return-statements\n file_path: str,\n start_line: Optional[int] = None,\n end_line: Optional[int] = None,\n) -> ToolResponse:\n \"\"\"Read a file. Relative paths resolve from WORKING_DIR.\n\n Use start_line/end_line to read a specific line range (output includes\n line numbers). Omit both to read the full file.\n\n Args:\n file_path (`str`):\n Path to the file.\n start_line (`int`, optional):\n First line to read (1-based, inclusive).\n end_line (`int`, optional):\n Last line to read (1-based, inclusive).\n \"\"\"\n\n # Convert start_line/end_line to int if they are strings\n if start_line is not None:\n try:\n start_line = int(start_line)\n except (ValueError, TypeError):\n return ToolResponse(\n content=[\n TextBlock(\n type=\"text\",\n text=f\"Error: start_line must be an integer, got {start_line!r}.\",\n ),\n ],\n )\n\n if end_line is not None:\n try:\n end_line = int(end_line)\n except (ValueError, TypeError):\n return ToolResponse(\n content=[\n TextBlock(\n type=\"text\",\n text=f\"Error: end_line must be an integer, got {end_line!r}.\",\n ),\n ],\n )\n\n file_path = _resolve_file_path(file_path)\n\n if not os.path.exists(file_path):\n return ToolResponse(\n content=[\n TextBlock(\n type=\"text\",\n text=f\"Error: The file {file_path} does not exist.\",\n ),\n ],\n )\n\n if not os.path.isfile(file_path):\n return ToolResponse(\n content=[\n TextBlock(\n type=\"text\",\n text=f\"Error: The path {file_path} is not a file.\",\n ),\n ],\n )\n\n try:\n content = read_file_safe(file_path)\n all_lines = content.split(\"\\n\")\n total = len(all_lines)\n\n # Determine read range\n s = max(1, start_line if start_line is not None else 1)\n e = min(total, end_line if end_line is not None else total)\n\n if s > total:\n return ToolResponse(\n content=[\n TextBlock(\n type=\"text\",\n text=f\"Error: start_line {s} exceeds file length ({total} lines).\",\n ),\n ],\n )\n\n if s > e:\n return ToolResponse(\n content=[\n TextBlock(\n type=\"text\",\n text=f\"Error: start_line ({s}) > end_line ({e}).\",\n ),\n ],\n )\n\n # Extract selected lines\n selected_content = \"\\n\".join(all_lines[s - 1 : e])\n\n # Apply smart truncation (consistent with shell output format)\n text = truncate_file_output(\n selected_content,\n start_line=s,\n total_lines=total,\n )\n\n # Add continuation hint if partial read without truncation\n if text == selected_content and e < total:\n remaining = total - e\n text = (\n f\"{file_path} (lines {s}-{e} of {total})\\n{text}\\n\\n\"\n f\"[{remaining} more lines. Use start_line={e + 1} to continue.]\"\n )\n\n return ToolResponse(\n content=[TextBlock(type=\"text\", text=text)],\n )\n\n except Exception as e:\n return ToolResponse(\n content=[\n TextBlock(\n type=\"text\",\n text=f\"Error: Read file failed due to \\n{e}\",\n ),\n ],\n )\n\n\nasync def write_file(\n file_path: str,\n content: str,\n) -> ToolResponse:\n \"\"\"Create or overwrite a file. Relative paths resolve from WORKING_DIR.\n\n Args:\n file_path (`str`):\n Path to the file.\n content (`str`):\n Content to write.\n \"\"\"\n\n if not file_path:\n return ToolResponse(\n content=[\n TextBlock(\n type=\"text\",\n text=\"Error: No `file_path` provided.\",\n ),\n ],\n )\n\n file_path = _resolve_file_path(file_path)\n\n try:\n with open(file_path, \"w\", encoding=\"utf-8\") as file:\n file.write(content)\n return ToolResponse(\n content=[\n TextBlock(\n type=\"text\",\n text=f\"Wrote {len(content)} bytes to {file_path}.\",\n ),\n ],\n )\n except Exception as e:\n return ToolResponse(\n content=[\n TextBlock(\n type=\"text\",\n text=f\"Error: Write file failed due to \\n{e}\",\n ),\n ],\n )\n\n\n# pylint: disable=too-many-return-statements\nasync def edit_file(\n file_path: str,\n old_text: str,\n new_text: str,\n) -> ToolResponse:\n \"\"\"Find-and-replace text in a file. All occurrences of old_text are\n replaced with new_text. Relative paths resolve from WORKING_DIR.\n\n Args:\n file_path (`str`):\n Path to the file.\n old_text (`str`):\n Exact text to find.\n new_text (`str`):\n Replacement text.\n \"\"\"\n\n if not file_path:\n return ToolResponse(\n content=[\n TextBlock(\n type=\"text\",\n text=\"Error: No `file_path` provided.\",\n ),\n ],\n )\n\n resolved_path = _resolve_file_path(file_path)\n\n if not os.path.exists(resolved_path):\n return ToolResponse(\n content=[\n TextBlock(\n type=\"text\",\n text=f\"Error: The file {resolved_path} does not exist.\",\n ),\n ],\n )\n\n if not os.path.isfile(resolved_path):\n return ToolResponse(\n content=[\n TextBlock(\n type=\"text\",\n text=f\"Error: The path {resolved_path} is not a file.\",\n ),\n ],\n )\n\n try:\n content = read_file_safe(resolved_path)\n except Exception as e:\n return ToolResponse(\n content=[\n TextBlock(\n type=\"text\",\n text=f\"Error: Read file failed due to \\n{e}\",\n ),\n ],\n )\n\n if old_text not in content:\n return ToolResponse(\n content=[\n TextBlock(\n type=\"text\",\n text=f\"Error: The text to replace was not found in {file_path}.\",\n ),\n ],\n )\n\n new_content = content.replace(old_text, new_text)\n write_response = await write_file(\n file_path=resolved_path,\n content=new_content,\n )\n\n if write_response.content and len(write_response.content) > 0:\n write_text = write_response.content[0].get(\"text\", \"\")\n if write_text.startswith(\"Error:\"):\n return write_response\n\n return ToolResponse(\n content=[\n TextBlock(\n type=\"text\",\n text=f\"Successfully replaced text in {file_path}.\",\n ),\n ],\n )\n\n\nasync def append_file(\n file_path: str,\n content: str,\n) -> ToolResponse:\n \"\"\"Append content to the end of a file. Relative paths resolve from\n WORKING_DIR.\n\n Args:\n file_path (`str`):\n Path to the file.\n content (`str`):\n Content to append.\n \"\"\"\n\n if not file_path:\n return ToolResponse(\n content=[\n TextBlock(\n type=\"text\",\n text=\"Error: No `file_path` provided.\",\n ),\n ],\n )\n\n file_path = _resolve_file_path(file_path)\n\n try:\n with open(file_path, \"a\", encoding=\"utf-8\") as file:\n file.write(content)\n return ToolResponse(\n content=[\n TextBlock(\n type=\"text\",\n text=f\"Appended {len(content)} bytes to {file_path}.\",\n ),\n ],\n )\n except Exception as e:\n return ToolResponse(\n content=[\n TextBlock(\n type=\"text\",\n text=f\"Error: Append file failed due to \\n{e}\",\n ),\n ],\n )\n" }, { "path": "src/copaw/agents/tools/file_search.py", "content": "# -*- coding: utf-8 -*-\n# flake8: noqa: E501\n# pylint: disable=line-too-long\n\"\"\"File search tools: grep (content search) and glob (file discovery).\"\"\"\n\nimport re\nfrom pathlib import Path\nfrom typing import Optional\n\nfrom agentscope.message import TextBlock\nfrom agentscope.tool import ToolResponse\n\nfrom ...constant import WORKING_DIR\nfrom ...config.context import get_current_workspace_dir\nfrom .file_io import _resolve_file_path\n\n# Skip binary / large files\n_BINARY_EXTENSIONS = frozenset(\n {\n \".png\",\n \".jpg\",\n \".jpeg\",\n \".gif\",\n \".bmp\",\n \".ico\",\n \".webp\",\n \".svg\",\n \".mp3\",\n \".mp4\",\n \".avi\",\n \".mov\",\n \".mkv\",\n \".flac\",\n \".wav\",\n \".zip\",\n \".tar\",\n \".gz\",\n \".bz2\",\n \".7z\",\n \".rar\",\n \".pdf\",\n \".doc\",\n \".docx\",\n \".xls\",\n \".xlsx\",\n \".ppt\",\n \".pptx\",\n \".exe\",\n \".dll\",\n \".so\",\n \".dylib\",\n \".bin\",\n \".dat\",\n \".woff\",\n \".woff2\",\n \".ttf\",\n \".eot\",\n \".otf\",\n \".pyc\",\n \".pyo\",\n \".class\",\n \".o\",\n \".a\",\n },\n)\n\n_MAX_MATCHES = 200\n_MAX_FILE_SIZE = 2 * 1024 * 1024 # 2 MB\n\n\ndef _is_text_file(path: Path) -> bool:\n \"\"\"Heuristic check: skip known binary extensions and large files.\"\"\"\n if path.suffix.lower() in _BINARY_EXTENSIONS:\n return False\n try:\n if path.stat().st_size > _MAX_FILE_SIZE:\n return False\n except OSError:\n return False\n return True\n\n\nasync def grep_search( # pylint: disable=too-many-branches\n pattern: str,\n path: Optional[str] = None,\n is_regex: bool = False,\n case_sensitive: bool = True,\n context_lines: int = 0,\n) -> ToolResponse:\n \"\"\"Search file contents by pattern, recursively. Relative paths resolve\n from WORKING_DIR. Output format: ``path:line_number: content``.\n\n Args:\n pattern (`str`):\n Search string (or regex when is_regex=True).\n path (`str`, optional):\n File or directory to search in. Defaults to WORKING_DIR.\n is_regex (`bool`, optional):\n Treat pattern as a regular expression. Defaults to False.\n case_sensitive (`bool`, optional):\n Case-sensitive matching. Defaults to True.\n context_lines (`int`, optional):\n Context lines before and after each match (like grep -C).\n Defaults to 0.\n \"\"\"\n if not pattern:\n return ToolResponse(\n content=[\n TextBlock(\n type=\"text\",\n text=\"Error: No search `pattern` provided.\",\n ),\n ],\n )\n\n search_root = (\n Path(_resolve_file_path(path))\n if path\n else (get_current_workspace_dir() or WORKING_DIR)\n )\n\n if not search_root.exists():\n return ToolResponse(\n content=[\n TextBlock(\n type=\"text\",\n text=f\"Error: The path {search_root} does not exist.\",\n ),\n ],\n )\n\n # Compile regex\n flags = 0 if case_sensitive else re.IGNORECASE\n try:\n if is_regex:\n regex = re.compile(pattern, flags)\n else:\n regex = re.compile(re.escape(pattern), flags)\n except re.error as e:\n return ToolResponse(\n content=[\n TextBlock(\n type=\"text\",\n text=f\"Error: Invalid regex pattern — {e}\",\n ),\n ],\n )\n\n matches: list[str] = []\n truncated = False\n\n # Collect files to search\n single_file = search_root.is_file()\n if single_file:\n files = [search_root]\n else:\n files = sorted(\n f\n for f in search_root.rglob(\"*\")\n if f.is_file() and _is_text_file(f)\n )\n\n for file_path in files:\n if truncated:\n break\n try:\n lines = file_path.read_text(\n encoding=\"utf-8\",\n errors=\"ignore\",\n ).splitlines()\n except OSError:\n continue\n\n for line_no, line in enumerate(lines, start=1):\n if regex.search(line):\n if len(matches) >= _MAX_MATCHES:\n truncated = True\n break\n\n # Context window\n start = max(0, line_no - 1 - context_lines)\n end = min(len(lines), line_no + context_lines)\n\n # For single-file search show the filename, not '.'\n if single_file:\n rel = file_path.name\n else:\n rel = _relative_display(file_path, search_root)\n for ctx_idx in range(start, end):\n prefix = \">\" if ctx_idx == line_no - 1 else \" \"\n matches.append(\n f\"{rel}:{ctx_idx + 1}:{prefix} {lines[ctx_idx]}\",\n )\n if context_lines > 0:\n matches.append(\"---\")\n\n if not matches:\n return ToolResponse(\n content=[\n TextBlock(\n type=\"text\",\n text=f\"No matches found for pattern: {pattern}\",\n ),\n ],\n )\n\n result = \"\\n\".join(matches)\n if truncated:\n result += f\"\\n\\n(Results truncated at {_MAX_MATCHES} matches.)\"\n\n return ToolResponse(\n content=[\n TextBlock(\n type=\"text\",\n text=result,\n ),\n ],\n )\n\n\nasync def glob_search(\n pattern: str,\n path: Optional[str] = None,\n) -> ToolResponse:\n \"\"\"Find files matching a glob pattern (e.g. ``\"*.py\"``, ``\"**/*.json\"``).\n Relative paths resolve from WORKING_DIR.\n\n Args:\n pattern (`str`):\n Glob pattern to match.\n path (`str`, optional):\n Root directory to search from. Defaults to WORKING_DIR.\n \"\"\"\n if not pattern:\n return ToolResponse(\n content=[\n TextBlock(\n type=\"text\",\n text=\"Error: No glob `pattern` provided.\",\n ),\n ],\n )\n\n search_root = (\n Path(_resolve_file_path(path))\n if path\n else (get_current_workspace_dir() or WORKING_DIR)\n )\n\n if not search_root.exists():\n return ToolResponse(\n content=[\n TextBlock(\n type=\"text\",\n text=f\"Error: The path {search_root} does not exist.\",\n ),\n ],\n )\n\n if not search_root.is_dir():\n return ToolResponse(\n content=[\n TextBlock(\n type=\"text\",\n text=f\"Error: The path {search_root} is not a directory.\",\n ),\n ],\n )\n\n try:\n results: list[str] = []\n truncated = False\n for entry in sorted(search_root.glob(pattern)):\n rel = _relative_display(entry, search_root)\n suffix = \"/\" if entry.is_dir() else \"\"\n results.append(f\"{rel}{suffix}\")\n if len(results) >= _MAX_MATCHES:\n truncated = True\n break\n\n if not results:\n return ToolResponse(\n content=[\n TextBlock(\n type=\"text\",\n text=f\"No files matched pattern: {pattern}\",\n ),\n ],\n )\n\n text = \"\\n\".join(results)\n if truncated:\n text += f\"\\n\\n(Results truncated at {_MAX_MATCHES} entries.)\"\n\n return ToolResponse(\n content=[\n TextBlock(\n type=\"text\",\n text=text,\n ),\n ],\n )\n except Exception as e:\n return ToolResponse(\n content=[\n TextBlock(\n type=\"text\",\n text=f\"Error: Glob search failed due to\\n{e}\",\n ),\n ],\n )\n\n\ndef _relative_display(target: Path, root: Path) -> str:\n \"\"\"Return a relative path string if possible, otherwise absolute.\"\"\"\n try:\n return str(target.relative_to(root))\n except ValueError:\n return str(target)\n" }, { "path": "src/copaw/agents/tools/get_current_time.py", "content": "# -*- coding: utf-8 -*-\n\"\"\"Tools for getting and setting the user timezone.\"\"\"\n\nimport logging\nfrom datetime import datetime, timezone\nfrom zoneinfo import ZoneInfo, ZoneInfoNotFoundError\n\nfrom agentscope.message import TextBlock\nfrom agentscope.tool import ToolResponse\n\nfrom ...config import load_config, save_config\n\nlogger = logging.getLogger(__name__)\n\n\nasync def get_current_time() -> ToolResponse:\n \"\"\"Get the current time.\n Only call this tool when the user explicitly asks for the time.\n\n Returns:\n `ToolResponse`:\n The current time string,\n e.g. \"2026-02-13 19:30:45 Asia/Shanghai (Friday)\".\n \"\"\"\n user_tz = load_config().user_timezone or \"UTC\"\n try:\n now = datetime.now(ZoneInfo(user_tz))\n except (ZoneInfoNotFoundError, KeyError):\n logger.warning(\"Invalid timezone %r, falling back to UTC\", user_tz)\n now = datetime.now(timezone.utc)\n user_tz = \"UTC\"\n\n time_str = (\n f\"{now.strftime('%Y-%m-%d %H:%M:%S')} \"\n f\"{user_tz} ({now.strftime('%A')})\"\n )\n\n return ToolResponse(\n content=[\n TextBlock(\n type=\"text\",\n text=time_str,\n ),\n ],\n )\n\n\nasync def set_user_timezone(timezone_name: str) -> ToolResponse:\n \"\"\"Set the user timezone.\n Only call this tool when the user explicitly asks to change their timezone.\n\n Args:\n timezone_name: IANA timezone name (e.g. \"Asia/Shanghai\",\n \"America/New_York\", \"Europe/London\", \"UTC\").\n\n Returns:\n `ToolResponse`: Confirmation with the new timezone and current time.\n \"\"\"\n tz_name = timezone_name.strip()\n if not tz_name:\n return ToolResponse(\n content=[TextBlock(type=\"text\", text=\"Error: timezone is empty.\")],\n )\n\n try:\n now = datetime.now(ZoneInfo(tz_name))\n except (ZoneInfoNotFoundError, KeyError):\n return ToolResponse(\n content=[\n TextBlock(\n type=\"text\",\n text=f\"Error: invalid timezone '{tz_name}'.\",\n ),\n ],\n )\n\n config = load_config()\n config.user_timezone = tz_name\n save_config(config)\n\n time_str = (\n f\"{now.strftime('%Y-%m-%d %H:%M:%S')} \"\n f\"{tz_name} ({now.strftime('%A')})\"\n )\n return ToolResponse(\n content=[\n TextBlock(\n type=\"text\",\n text=f\"Timezone set to {tz_name}. Current time: {time_str}\",\n ),\n ],\n )\n" }, { "path": "src/copaw/agents/tools/get_token_usage.py", "content": "# -*- coding: utf-8 -*-\n\"\"\"Tool to query token usage statistics.\"\"\"\n\nfrom datetime import date, timedelta\n\nfrom agentscope.message import TextBlock\nfrom agentscope.tool import ToolResponse\n\nfrom ...token_usage import get_token_usage_manager\n\n\nasync def get_token_usage(\n days: int = 30,\n model_name: str | None = None,\n provider_id: str | None = None,\n) -> ToolResponse:\n \"\"\"Query LLM token usage over the past N days.\n\n Use this when the user asks about token consumption, API usage,\n or how many tokens have been used.\n\n Args:\n days: Number of days to look back (default: 30).\n model_name: Optional model name to filter by.\n provider_id: Optional provider ID to filter by.\n\n Returns:\n ToolResponse with a formatted summary of token usage.\n \"\"\"\n end = date.today()\n start = end - timedelta(days=max(1, min(days, 365)))\n summary = await get_token_usage_manager().get_summary(\n start_date=start,\n end_date=end,\n model_name=model_name,\n provider_id=provider_id,\n )\n\n lines: list[str] = []\n filter_desc = []\n if model_name:\n filter_desc.append(f\"model={model_name}\")\n if provider_id:\n filter_desc.append(f\"provider={provider_id}\")\n if not filter_desc:\n filter_desc.append(\"all models\")\n lines.append(f\"Token usage ({start} ~ {end}, {', '.join(filter_desc)}):\")\n lines.append(\"\")\n total_tokens = (\n summary.total_prompt_tokens + summary.total_completion_tokens\n )\n lines.append(f\"- Total tokens: {total_tokens:,}\")\n lines.append(f\"- Prompt tokens: {summary.total_prompt_tokens:,}\")\n lines.append(\n f\"- Completion tokens: {summary.total_completion_tokens:,}\",\n )\n lines.append(f\"- Total calls: {summary.total_calls:,}\")\n lines.append(\"\")\n\n if summary.by_model:\n lines.append(\"By model:\")\n for model, stats in summary.by_model.items():\n tokens = stats.prompt_tokens + stats.completion_tokens\n lines.append(\n f\" - {model}: {tokens:,} tokens ({stats.call_count} calls)\",\n )\n lines.append(\"\")\n\n if summary.by_date and len(summary.by_date) <= 14:\n lines.append(\"By date:\")\n for dt, stats in list(summary.by_date.items())[-7:]:\n tokens = stats.prompt_tokens + stats.completion_tokens\n lines.append(\n f\" - {dt}: {tokens:,} tokens ({stats.call_count} calls)\",\n )\n elif summary.by_date:\n lines.append(\n f\"By date: {len(summary.by_date)} days with usage \"\n \"(see console for details)\",\n )\n\n text = \"\\n\".join(lines) if lines else \"No token usage data in this period.\"\n return ToolResponse(\n content=[TextBlock(type=\"text\", text=text)],\n )\n" }, { "path": "src/copaw/agents/tools/memory_search.py", "content": "# -*- coding: utf-8 -*-\n\"\"\"Memory search tool for semantic search in memory files.\"\"\"\nfrom agentscope.tool import ToolResponse\nfrom agentscope.message import TextBlock\n\n\ndef create_memory_search_tool(memory_manager):\n \"\"\"Create a memory_search tool function with bound memory_manager.\n\n Args:\n memory_manager: MemoryManager instance to use for searching\n\n Returns:\n An async function that can be registered as a tool\n \"\"\"\n\n async def memory_search(\n query: str,\n max_results: int = 5,\n min_score: float = 0.1,\n ) -> ToolResponse:\n \"\"\"\n Search MEMORY.md and memory/*.md files semantically.\n\n Use this tool before answering questions about prior work, decisions,\n dates, people, preferences, or todos. Returns top relevant snippets\n with file paths and line numbers.\n\n Args:\n query (`str`):\n The semantic search query to find relevant memory snippets.\n max_results (`int`, optional):\n Maximum number of search results to return. Defaults to 5.\n min_score (`float`, optional):\n Minimum similarity score for results. Defaults to 0.1.\n\n Returns:\n `ToolResponse`:\n Search results formatted with paths, line numbers, and content.\n \"\"\"\n if memory_manager is None:\n return ToolResponse(\n content=[\n TextBlock(\n type=\"text\",\n text=\"Error: Memory manager is not enabled.\",\n ),\n ],\n )\n\n try:\n # memory_manager.memory_search already returns ToolResponse\n return await memory_manager.memory_search(\n query=query,\n max_results=max_results,\n min_score=min_score,\n )\n\n except Exception as e:\n return ToolResponse(\n content=[\n TextBlock(\n type=\"text\",\n text=f\"Error: Memory search failed due to\\n{e}\",\n ),\n ],\n )\n\n return memory_search\n" }, { "path": "src/copaw/agents/tools/send_file.py", "content": "# -*- coding: utf-8 -*-\n# flake8: noqa: E501\n# pylint: disable=line-too-long,too-many-return-statements\nimport os\nimport mimetypes\nimport unicodedata\n\nfrom agentscope.tool import ToolResponse\nfrom agentscope.message import (\n TextBlock,\n ImageBlock,\n AudioBlock,\n VideoBlock,\n)\n\nfrom ..schema import FileBlock\n\n\ndef _auto_as_type(mt: str) -> str:\n if mt.startswith(\"image/\"):\n return \"image\"\n if mt.startswith(\"audio/\"):\n return \"audio\"\n if mt.startswith(\"video/\"):\n return \"video\"\n return \"file\"\n\n\nasync def send_file_to_user(\n file_path: str,\n) -> ToolResponse:\n \"\"\"Send a file to the user.\n\n Args:\n file_path (`str`):\n Path to the file to send.\n\n Returns:\n `ToolResponse`:\n The tool response containing the file or an error message.\n \"\"\"\n\n # Normalize the path: expand ~ and fix Unicode normalization differences\n # (e.g. macOS stores filenames as NFD but paths from the LLM arrive as NFC,\n # causing os.path.exists to return False for files that do exist).\n file_path = os.path.expanduser(unicodedata.normalize(\"NFC\", file_path))\n\n if not os.path.exists(file_path):\n return ToolResponse(\n content=[\n TextBlock(\n type=\"text\",\n text=f\"Error: The file {file_path} does not exist.\",\n ),\n ],\n )\n\n if not os.path.isfile(file_path):\n return ToolResponse(\n content=[\n TextBlock(\n type=\"text\",\n text=f\"Error: The path {file_path} is not a file.\",\n ),\n ],\n )\n\n # Detect MIME type\n mime_type, _ = mimetypes.guess_type(file_path)\n if mime_type is None:\n # Default to application/octet-stream for unknown types\n mime_type = \"application/octet-stream\"\n as_type = _auto_as_type(mime_type)\n\n try:\n # Use local file URL instead of base64\n absolute_path = os.path.abspath(file_path)\n file_url = f\"file://{absolute_path}\"\n source = {\"type\": \"url\", \"url\": file_url}\n\n if as_type == \"image\":\n return ToolResponse(\n content=[\n ImageBlock(type=\"image\", source=source),\n TextBlock(type=\"text\", text=\"File sent successfully.\"),\n ],\n )\n if as_type == \"audio\":\n return ToolResponse(\n content=[\n AudioBlock(type=\"audio\", source=source),\n TextBlock(type=\"text\", text=\"File sent successfully.\"),\n ],\n )\n if as_type == \"video\":\n return ToolResponse(\n content=[\n VideoBlock(type=\"video\", source=source),\n TextBlock(type=\"text\", text=\"File sent successfully.\"),\n ],\n )\n\n return ToolResponse(\n content=[\n FileBlock(\n type=\"file\",\n source=source,\n filename=os.path.basename(file_path),\n ),\n TextBlock(type=\"text\", text=\"File sent successfully.\"),\n ],\n )\n\n except Exception as e:\n return ToolResponse(\n content=[\n TextBlock(\n type=\"text\",\n text=f\"Error: Send file failed due to \\n{e}\",\n ),\n ],\n )\n" }, { "path": "src/copaw/agents/tools/shell.py", "content": "# -*- coding: utf-8 -*-\n# flake8: noqa: E501\n# pylint: disable=line-too-long\n\"\"\"The shell command tool.\"\"\"\n\nimport asyncio\nimport locale\nimport os\nimport subprocess\nimport sys\nfrom pathlib import Path\nfrom typing import Optional\n\nfrom agentscope.message import TextBlock\nfrom agentscope.tool import ToolResponse\n\nfrom ...constant import WORKING_DIR\nfrom ...config.context import get_current_workspace_dir\n\n\ndef _kill_process_tree_win32(pid: int) -> None:\n \"\"\"Kill a process and all its descendants on Windows via taskkill.\n\n Uses ``taskkill /F /T`` which forcefully terminates the entire process\n tree, including grandchild processes that ``Popen.kill()`` would miss.\n \"\"\"\n try:\n subprocess.call(\n [\"taskkill\", \"/F\", \"/T\", \"/PID\", str(pid)],\n stdout=subprocess.DEVNULL,\n stderr=subprocess.DEVNULL,\n timeout=10,\n )\n except Exception:\n pass\n\n\ndef _execute_subprocess_sync(\n cmd: str,\n cwd: str,\n timeout: int,\n env: dict | None = None,\n) -> tuple[int, str, str]:\n \"\"\"Execute subprocess synchronously in a thread.\n\n This function runs in a separate thread to avoid Windows asyncio\n subprocess limitations.\n\n Uses ``Popen`` directly instead of ``subprocess.run`` because the\n latter's internal cleanup after a timeout calls ``communicate()``\n **without** a timeout, which hangs when descendant processes still\n hold the pipe handles open (e.g. ``notepad.exe``, ``cmd /k pause``).\n\n Args:\n cmd (`str`):\n The shell command to execute.\n cwd (`str`):\n The working directory for the command execution.\n timeout (`int`):\n The maximum time (in seconds) allowed for the command to run.\n env (`dict | None`):\n Environment variables for the subprocess.\n\n Returns:\n `tuple[int, str, str]`:\n A tuple containing the return code, standard output, and\n standard error of the executed command. If timeout occurs, the\n return code will be -1 and stderr will contain timeout information.\n \"\"\"\n try:\n wrapped = f'cmd /D /S /C \"{cmd}\"'\n with subprocess.Popen(\n wrapped,\n shell=False,\n stdout=subprocess.PIPE,\n stderr=subprocess.PIPE,\n text=False,\n cwd=cwd,\n env=env,\n creationflags=subprocess.CREATE_NEW_PROCESS_GROUP,\n ) as proc:\n try:\n stdout, stderr = proc.communicate(timeout=timeout)\n return (\n proc.returncode,\n smart_decode(stdout),\n smart_decode(stderr),\n )\n except subprocess.TimeoutExpired:\n _kill_process_tree_win32(proc.pid)\n\n # Try to drain remaining output after the tree has been killed.\n # The second communicate() should return quickly now that all\n # writers are dead. Guard with a timeout just in case.\n try:\n stdout, stderr = proc.communicate(timeout=5)\n stdout_str = smart_decode(stdout)\n stderr_str = smart_decode(stderr)\n except (subprocess.TimeoutExpired, OSError, ValueError):\n stdout_str, stderr_str = \"\", \"\"\n # Force-close pipes to unblock any lingering reader threads\n # spawned by the first communicate() call.\n for pipe in (proc.stdout, proc.stderr, proc.stdin):\n if pipe:\n try:\n pipe.close()\n except OSError:\n pass\n try:\n proc.wait(timeout=3)\n except subprocess.TimeoutExpired:\n pass\n\n timeout_msg = f\"Command execution exceeded the timeout of {timeout} seconds.\"\n if stderr_str:\n stderr_str = f\"{stderr_str}\\n{timeout_msg}\"\n else:\n stderr_str = timeout_msg\n return -1, stdout_str, stderr_str\n\n except Exception as e:\n return -1, \"\", str(e)\n\n\n# pylint: disable=too-many-branches, too-many-statements\nasync def execute_shell_command(\n command: str,\n timeout: int = 60,\n cwd: Optional[Path] = None,\n) -> ToolResponse:\n \"\"\"Execute given command and return the return code, standard output and\n error within , and\n tags.\n\n IMPORTANT: Always consider the operating system before choosing commands.\n\n Args:\n command (`str`):\n The shell command to execute.\n timeout (`int`, defaults to `10`):\n The maximum time (in seconds) allowed for the command to run.\n Default is 60 seconds.\n cwd (`Optional[Path]`, defaults to `None`):\n The working directory for the command execution.\n If None, defaults to WORKING_DIR.\n\n Returns:\n `ToolResponse`:\n The tool response containing the return code, standard output, and\n standard error of the executed command. If timeout occurs, the\n return code will be -1 and stderr will contain timeout information.\n \"\"\"\n\n cmd = (command or \"\").strip()\n\n # Set working directory\n # Use current workspace_dir from context, fallback to WORKING_DIR\n if cwd is not None:\n working_dir = cwd\n else:\n working_dir = get_current_workspace_dir() or WORKING_DIR\n\n # Ensure the venv Python is on PATH for subprocesses\n env = os.environ.copy()\n python_bin_dir = str(Path(sys.executable).parent)\n existing_path = env.get(\"PATH\", \"\")\n if existing_path:\n env[\"PATH\"] = python_bin_dir + os.pathsep + existing_path\n else:\n env[\"PATH\"] = python_bin_dir\n\n try:\n if sys.platform == \"win32\":\n # Windows: use thread pool to avoid asyncio subprocess limitations\n returncode, stdout_str, stderr_str = await asyncio.to_thread(\n _execute_subprocess_sync,\n cmd,\n str(working_dir),\n timeout,\n env,\n )\n else:\n proc = await asyncio.create_subprocess_shell(\n cmd,\n stdout=asyncio.subprocess.PIPE,\n stderr=asyncio.subprocess.PIPE,\n bufsize=0,\n cwd=str(working_dir),\n env=env,\n )\n\n try:\n # Apply timeout to communicate directly; wait()+communicate()\n # can hang if descendants keep stdout/stderr pipes open.\n stdout, stderr = await asyncio.wait_for(\n proc.communicate(),\n timeout=timeout,\n )\n stdout_str = smart_decode(stdout)\n stderr_str = smart_decode(stderr)\n returncode = proc.returncode\n\n except asyncio.TimeoutError:\n # Handle timeout\n stderr_suffix = (\n f\"⚠️ TimeoutError: The command execution exceeded \"\n f\"the timeout of {timeout} seconds. \"\n f\"Please consider increasing the timeout value if this command \"\n f\"requires more time to complete.\"\n )\n returncode = -1\n try:\n proc.terminate()\n # Wait a bit for graceful termination\n try:\n await asyncio.wait_for(proc.wait(), timeout=1)\n except asyncio.TimeoutError:\n # Force kill if graceful termination fails\n proc.kill()\n await proc.wait()\n\n # Avoid hanging forever while draining pipes after timeout.\n try:\n stdout, stderr = await asyncio.wait_for(\n proc.communicate(),\n timeout=1,\n )\n except asyncio.TimeoutError:\n stdout, stderr = b\"\", b\"\"\n stdout_str = smart_decode(stdout)\n stderr_str = smart_decode(stderr)\n if stderr_str:\n stderr_str += f\"\\n{stderr_suffix}\"\n else:\n stderr_str = stderr_suffix\n except ProcessLookupError:\n stdout_str = \"\"\n stderr_str = stderr_suffix\n\n # Apply output truncation\n # stdout_str = truncate_shell_output(stdout_str)\n # stderr_str = truncate_shell_output(stderr_str)\n\n # Format the response in a human-friendly way\n if returncode == 0:\n # Success case: just show the output\n if stdout_str:\n response_text = stdout_str\n else:\n response_text = \"Command executed successfully (no output).\"\n else:\n # Error case: show detailed information\n response_parts = [f\"Command failed with exit code {returncode}.\"]\n if stdout_str:\n response_parts.append(f\"\\n[stdout]\\n{stdout_str}\")\n if stderr_str:\n response_parts.append(f\"\\n[stderr]\\n{stderr_str}\")\n response_text = \"\".join(response_parts)\n\n return ToolResponse(\n content=[\n TextBlock(\n type=\"text\",\n text=response_text,\n ),\n ],\n )\n\n except Exception as e:\n return ToolResponse(\n content=[\n TextBlock(\n type=\"text\",\n text=f\"Error: Shell command execution failed due to \\n{e}\",\n ),\n ],\n )\n\n\ndef smart_decode(data: bytes) -> str:\n try:\n decoded_str = data.decode(\"utf-8\")\n except UnicodeDecodeError:\n encoding = locale.getpreferredencoding(False) or \"utf-8\"\n decoded_str = data.decode(encoding, errors=\"replace\")\n\n return decoded_str.strip(\"\\n\")\n" }, { "path": "src/copaw/agents/tools/utils.py", "content": "# -*- coding: utf-8 -*-\n\"\"\"Shared utilities for file and shell tools.\"\"\"\n\n# Default truncation limits\nDEFAULT_MAX_LINES = 1000\nDEFAULT_MAX_BYTES = 30 * 1024 # 30KB\n\n\n# pylint: disable=too-many-branches\ndef truncate_output(\n text: str,\n max_lines: int = DEFAULT_MAX_LINES,\n max_bytes: int = DEFAULT_MAX_BYTES,\n keep: str = \"head\",\n) -> tuple[str, bool, int, str]:\n \"\"\"Smart truncation for large content.\n\n Args:\n text: Text content to truncate.\n max_lines: Maximum number of lines.\n max_bytes: Maximum size in bytes.\n keep: Which part to keep - \"head\" (first lines) or \"tail\" (last lines).\n\n Returns:\n (truncated_content, was_truncated, output_line_count, truncate_reason)\n \"\"\"\n if not text:\n return text, False, 0, \"\"\n\n lines = text.split(\"\\n\")\n total_lines = len(lines)\n\n # No truncation needed\n if total_lines <= max_lines and len(text.encode(\"utf-8\")) <= max_bytes:\n return text, False, total_lines, \"\"\n\n # Apply line limit\n if total_lines > max_lines:\n if keep == \"tail\":\n lines = lines[-max_lines:]\n else:\n lines = lines[:max_lines]\n reason = \"lines\"\n else:\n reason = \"\"\n\n # Apply byte limit\n if len(\"\\n\".join(lines).encode(\"utf-8\")) > max_bytes:\n if keep == \"tail\":\n while (\n len(lines) > 1\n and len(\"\\n\".join(lines).encode(\"utf-8\")) > max_bytes\n ):\n lines.pop(0)\n # Handle single line exceeding byte limit\n if lines and len(lines[0].encode(\"utf-8\")) > max_bytes:\n lines[0] = _truncate_line_by_bytes_tail(lines[0], max_bytes)\n else:\n truncated = []\n current_bytes = 0\n for line in lines:\n line_bytes = len(line.encode(\"utf-8\")) + 1\n if current_bytes + line_bytes > max_bytes:\n # Truncate single line at byte level if it's the first line\n if not truncated:\n remaining = max_bytes - current_bytes\n truncated.append(\n _truncate_line_by_bytes(line, remaining),\n )\n break\n truncated.append(line)\n current_bytes += line_bytes\n lines = truncated\n reason = \"bytes\"\n\n return \"\\n\".join(lines), True, len(lines), reason\n\n\ndef _truncate_line_by_bytes(line: str, max_bytes: int) -> str:\n \"\"\"Truncate a single line to fit within byte limit (keep head).\n\n Handles UTF-8 multi-byte characters safely.\n\n Args:\n line: The line to truncate.\n max_bytes: Maximum bytes allowed.\n\n Returns:\n Truncated line that fits within byte limit.\n \"\"\"\n if len(line.encode(\"utf-8\")) <= max_bytes:\n return line\n\n # Binary search for the right character position\n low, high = 0, len(line)\n while low < high:\n mid = (low + high + 1) // 2\n if len(line[:mid].encode(\"utf-8\")) <= max_bytes:\n low = mid\n else:\n high = mid - 1\n\n return line[:low]\n\n\ndef _truncate_line_by_bytes_tail(line: str, max_bytes: int) -> str:\n \"\"\"Truncate a single line to fit within byte limit (keep tail).\n\n Handles UTF-8 multi-byte characters safely.\n\n Args:\n line: The line to truncate.\n max_bytes: Maximum bytes allowed.\n\n Returns:\n Truncated line that fits within byte limit, keeping the tail.\n \"\"\"\n if len(line.encode(\"utf-8\")) <= max_bytes:\n return line\n\n # Binary search for the right character position from the end\n low, high = 0, len(line)\n while low < high:\n mid = (low + high) // 2\n if len(line[mid:].encode(\"utf-8\")) <= max_bytes:\n high = mid\n else:\n low = mid + 1\n\n return line[low:]\n\n\ndef truncate_file_output(\n text: str,\n start_line: int = 1,\n total_lines: int = 0,\n) -> str:\n \"\"\"Truncate file output to first N lines or M bytes.\n\n Includes a truncation notice with continuation hint when applied.\n\n Args:\n text: The output text to truncate.\n start_line: The starting line number (1-based).\n total_lines: Total lines in the original file.\n\n Returns:\n Truncated text with notice if truncated.\n \"\"\"\n if not text:\n return text\n\n try:\n truncated, was_truncated, output_lines, reason = truncate_output(\n text,\n keep=\"head\",\n )\n\n if not was_truncated:\n return text\n\n end_line = start_line + output_lines - 1\n next_line = end_line + 1\n\n if reason == \"lines\":\n notice = (\n f\"\\n\\n[Output truncated: showing lines \"\n f\"{start_line}-{end_line} of {total_lines} total. \"\n f\"Use start_line={next_line} to continue.]\"\n )\n else:\n notice = (\n f\"\\n\\n[Output truncated: showing lines \"\n f\"{start_line}-{end_line} of {total_lines} \"\n f\"({DEFAULT_MAX_BYTES // 1024}KB limit). \"\n f\"Use start_line={next_line} to continue.]\"\n )\n\n return truncated + notice\n except Exception:\n return text\n\n\ndef truncate_shell_output(text: str) -> str:\n \"\"\"Truncate shell output to last N lines or M bytes.\n\n Includes a truncation notice when applied.\n\n Args:\n text: The output text to truncate.\n\n Returns:\n Truncated text with notice if truncated.\n \"\"\"\n if not text:\n return text\n\n try:\n total_lines = len(text.split(\"\\n\"))\n truncated, was_truncated, output_lines, reason = truncate_output(\n text,\n keep=\"tail\",\n )\n\n if not was_truncated:\n return text\n\n start_line = total_lines - output_lines + 1\n if reason == \"lines\":\n notice = (\n \"\\n\\n[Output truncated: showing lines \"\n f\"{start_line}-{total_lines} of {total_lines} total]\"\n )\n else:\n notice = (\n \"\\n\\n[Output truncated: showing lines \"\n f\"{start_line}-{total_lines} of {total_lines} \"\n f\"({DEFAULT_MAX_BYTES // 1024}KB limit)]\"\n )\n\n return truncated + notice\n except Exception:\n return text\n\n\ndef read_file_safe(file_path: str) -> str:\n \"\"\"Read file with Unicode error handling.\n\n Args:\n file_path: Path to the file.\n\n Returns:\n File content as string.\n \"\"\"\n try:\n with open(file_path, \"r\", encoding=\"utf-8\") as f:\n return f.read()\n except UnicodeDecodeError:\n with open(file_path, \"r\", encoding=\"utf-8\", errors=\"ignore\") as f:\n return f.read()\n" }, { "path": "src/copaw/agents/tools/view_image.py", "content": "# -*- coding: utf-8 -*-\n\"\"\"Load an image file into the LLM context for visual analysis.\"\"\"\n\nimport mimetypes\nimport os\nimport unicodedata\nfrom pathlib import Path\n\nfrom agentscope.message import ImageBlock, TextBlock\nfrom agentscope.tool import ToolResponse\n\n_IMAGE_EXTENSIONS = {\n \".png\",\n \".jpg\",\n \".jpeg\",\n \".gif\",\n \".webp\",\n \".bmp\",\n \".tiff\",\n \".tif\",\n}\n\n\nasync def view_image(image_path: str) -> ToolResponse:\n \"\"\"Load an image file into the LLM context so the model can see it.\n\n Use this after desktop_screenshot, browser_use, or any tool that\n produces an image file path.\n\n Args:\n image_path (`str`):\n Path to the image file to view.\n\n Returns:\n `ToolResponse`:\n An ImageBlock the model can inspect, or an error message.\n \"\"\"\n image_path = unicodedata.normalize(\n \"NFC\",\n os.path.expanduser(image_path),\n )\n resolved = Path(image_path).resolve()\n\n if not resolved.exists() or not resolved.is_file():\n return ToolResponse(\n content=[\n TextBlock(\n type=\"text\",\n text=f\"Error: {image_path} does not exist or \"\n \"is not a file.\",\n ),\n ],\n )\n\n ext = resolved.suffix.lower()\n mime, _ = mimetypes.guess_type(str(resolved))\n if ext not in _IMAGE_EXTENSIONS and (\n not mime or not mime.startswith(\"image/\")\n ):\n return ToolResponse(\n content=[\n TextBlock(\n type=\"text\",\n text=f\"Error: {resolved.name} is not a supported \"\n \"image format.\",\n ),\n ],\n )\n\n return ToolResponse(\n content=[\n ImageBlock(\n type=\"image\",\n source={\"type\": \"url\", \"url\": str(resolved)},\n ),\n TextBlock(\n type=\"text\",\n text=f\"Image loaded: {resolved.name}\",\n ),\n ],\n )\n" }, { "path": "src/copaw/agents/utils/__init__.py", "content": "# -*- coding: utf-8 -*-\n\"\"\"\nAgent utilities package.\n\nThis package provides utilities for agent operations:\n- file_handling: File download and management\n- message_processing: Message content manipulation and validation\n- tool_message_utils: Tool message validation and sanitization\n- setup_utils: Setup and initialization utilities\n\"\"\"\n\n# File handling\nfrom .file_handling import (\n download_file_from_base64,\n download_file_from_url,\n)\n\n# Message processing\nfrom .message_processing import (\n is_first_user_interaction,\n prepend_to_message_content,\n process_file_and_media_blocks_in_message,\n)\n\n# Setup utilities\nfrom .setup_utils import copy_md_files\n\n# Token counting\nfrom .copaw_token_counter import get_copaw_token_counter\n\n# Tool message utilities\nfrom .tool_message_utils import (\n _dedup_tool_blocks,\n _remove_invalid_tool_blocks,\n _repair_empty_tool_inputs,\n _sanitize_tool_messages,\n check_valid_messages,\n extract_tool_ids,\n)\n\n__all__ = [\n # File handling\n \"download_file_from_base64\",\n \"download_file_from_url\",\n # Message processing\n \"process_file_and_media_blocks_in_message\",\n \"is_first_user_interaction\",\n \"prepend_to_message_content\",\n # Setup utilities\n \"copy_md_files\",\n # Token counting\n \"get_copaw_token_counter\",\n # Tool message utilities\n \"_dedup_tool_blocks\",\n \"_remove_invalid_tool_blocks\",\n \"_repair_empty_tool_inputs\",\n \"_sanitize_tool_messages\",\n \"check_valid_messages\",\n \"extract_tool_ids\",\n]\n" }, { "path": "src/copaw/agents/utils/audio_transcription.py", "content": "# -*- coding: utf-8 -*-\n\"\"\"Audio transcription utility.\n\nTranscribes audio files to text using either:\n- An OpenAI-compatible ``/v1/audio/transcriptions`` endpoint (Whisper API), or\n- The locally installed ``openai-whisper`` Python library (Local Whisper).\n\nTranscription is only attempted when explicitly enabled via the\n``transcription_provider_type`` config setting. The default is ``\"disabled\"``.\n\"\"\"\n\nimport asyncio\nimport logging\nimport shutil\nimport threading\nfrom typing import List, Optional, Tuple\n\nlogger = logging.getLogger(__name__)\n\n# ------------------------------------------------------------------\n# Cached local-whisper model (lazy singleton)\n# ------------------------------------------------------------------\n_local_whisper_model = None\n_local_whisper_lock = threading.Lock()\n\n\ndef _get_local_whisper_model():\n \"\"\"Return a cached whisper model, loading it on first call.\"\"\"\n global _local_whisper_model # noqa: PLW0603\n if _local_whisper_model is not None:\n return _local_whisper_model\n with _local_whisper_lock:\n if _local_whisper_model is not None:\n return _local_whisper_model\n import whisper\n\n _local_whisper_model = whisper.load_model(\"base\")\n return _local_whisper_model\n\n\n# ------------------------------------------------------------------\n# Provider helpers\n# ------------------------------------------------------------------\n\n\ndef _url_for_provider(provider) -> Optional[Tuple[str, str]]:\n \"\"\"Return ``(base_url, api_key)`` if *provider* can serve transcription.\n\n Supports providers that do not require an API key (e.g. local Ollama).\n \"\"\"\n from ...providers.openai_provider import OpenAIProvider\n from ...providers.ollama_provider import OllamaProvider\n\n if isinstance(provider, OpenAIProvider):\n requires_key = getattr(provider, \"require_api_key\", True)\n key = provider.api_key or \"\"\n if requires_key and not key:\n return None\n base = provider.base_url.rstrip(\"/\")\n if not base.endswith(\"/v1\"):\n base += \"/v1\"\n return (base, key or \"\")\n if isinstance(provider, OllamaProvider):\n base = provider.base_url.rstrip(\"/\")\n if not base.endswith(\"/v1\"):\n base += \"/v1\"\n return (base, provider.api_key or \"\")\n return None\n\n\ndef _get_manager():\n \"\"\"Return ProviderManager singleton or None.\"\"\"\n try:\n from ...providers.provider_manager import ProviderManager\n\n return ProviderManager.get_instance()\n except Exception:\n logger.debug(\"ProviderManager not initialised yet\")\n return None\n\n\n# ------------------------------------------------------------------\n# Public helpers for API / Console UI\n# ------------------------------------------------------------------\n\n\ndef list_transcription_providers() -> List[dict]:\n \"\"\"Return providers capable of audio transcription.\n\n Each entry is ``{\"id\": ..., \"name\": ..., \"available\": bool}``.\n Availability is based on whether the provider has usable credentials.\n \"\"\"\n manager = _get_manager()\n if manager is None:\n return []\n\n results: list[dict] = []\n all_providers = {\n **getattr(manager, \"builtin_providers\", {}),\n **getattr(manager, \"custom_providers\", {}),\n }\n for provider in all_providers.values():\n creds = _url_for_provider(provider)\n if creds is not None:\n results.append(\n {\n \"id\": provider.id,\n \"name\": provider.name,\n \"available\": True,\n },\n )\n return results\n\n\ndef get_configured_transcription_provider_id() -> str:\n \"\"\"Return the explicitly configured provider ID (raw config value).\"\"\"\n from ...config import load_config\n\n return load_config().agents.transcription_provider_id\n\n\ndef check_local_whisper_available() -> dict:\n \"\"\"Check whether the local whisper provider can be used.\n\n Returns a dict with::\n\n {\n \"available\": bool,\n \"ffmpeg_installed\": bool,\n \"whisper_installed\": bool,\n }\n \"\"\"\n ffmpeg_ok = shutil.which(\"ffmpeg\") is not None\n\n whisper_ok = False\n try:\n import whisper as _whisper # noqa: F401\n\n whisper_ok = True\n except ImportError:\n pass\n\n return {\n \"available\": ffmpeg_ok and whisper_ok,\n \"ffmpeg_installed\": ffmpeg_ok,\n \"whisper_installed\": whisper_ok,\n }\n\n\n# ------------------------------------------------------------------\n# Transcription backends\n# ------------------------------------------------------------------\n\n\nasync def _transcribe_local_whisper(file_path: str) -> Optional[str]:\n \"\"\"Transcribe using the locally installed ``openai-whisper`` library.\n\n Requires both ``ffmpeg`` and ``openai-whisper`` to be installed.\n Returns the transcribed text, or ``None`` on failure.\n \"\"\"\n status = check_local_whisper_available()\n if not status[\"available\"]:\n missing = []\n if not status[\"ffmpeg_installed\"]:\n missing.append(\"ffmpeg\")\n if not status[\"whisper_installed\"]:\n missing.append(\"openai-whisper\")\n logger.warning(\n \"Local Whisper unavailable (missing: %s). \"\n \"Install the missing dependencies to use local transcription.\",\n \", \".join(missing),\n )\n return None\n\n def _run():\n model = _get_local_whisper_model()\n result = model.transcribe(file_path)\n return (result.get(\"text\") or \"\").strip()\n\n try:\n text = await asyncio.to_thread(_run)\n if text:\n logger.debug(\n \"Local Whisper transcribed %s: %s\",\n file_path,\n text[:80],\n )\n return text\n logger.warning(\n \"Local Whisper returned empty text for %s\",\n file_path,\n )\n return None\n except Exception:\n logger.warning(\n \"Local Whisper transcription failed for %s\",\n file_path,\n exc_info=True,\n )\n return None\n\n\ndef _get_configured_provider_creds() -> Optional[Tuple[str, str]]:\n \"\"\"Return ``(base_url, api_key)`` for the explicitly configured provider.\n\n Returns ``None`` when no provider is configured or the configured\n provider is not found / has no usable credentials.\n \"\"\"\n from ...config import load_config\n\n configured_id = load_config().agents.transcription_provider_id\n if not configured_id:\n return None\n\n manager = _get_manager()\n if manager is None:\n return None\n\n provider = manager.get_provider(configured_id)\n if provider is None:\n logger.warning(\n \"Configured transcription provider '%s' not found\",\n configured_id,\n )\n return None\n\n creds = _url_for_provider(provider)\n if creds is None:\n logger.warning(\n \"Configured transcription provider '%s' has no usable credentials\",\n configured_id,\n )\n return creds\n\n\nasync def _transcribe_whisper_api(file_path: str) -> Optional[str]:\n \"\"\"Transcribe using the OpenAI-compatible Whisper API endpoint.\n\n Only uses the explicitly configured provider — no auto-detection.\n Returns the transcribed text, or ``None`` on failure.\n \"\"\"\n creds = _get_configured_provider_creds()\n if creds is None:\n logger.warning(\n \"No transcription provider configured; skipping transcription\",\n )\n return None\n\n base_url, api_key = creds\n\n try:\n from openai import AsyncOpenAI\n except ImportError:\n logger.warning(\n \"openai package not installed; cannot transcribe audio\",\n )\n return None\n\n from ...config import load_config\n\n model_name = load_config().agents.transcription_model or \"whisper-1\"\n\n client = AsyncOpenAI(\n base_url=base_url,\n api_key=api_key or \"none\",\n timeout=60,\n )\n\n try:\n with open(file_path, \"rb\") as f:\n transcript = await client.audio.transcriptions.create(\n model=model_name,\n file=f,\n )\n text = transcript.text.strip()\n if text:\n logger.debug(\"Transcribed audio %s: %s\", file_path, text[:80])\n return text\n logger.warning(\"Transcription returned empty text for %s\", file_path)\n return None\n except Exception:\n logger.warning(\n \"Audio transcription failed for %s\",\n file_path,\n exc_info=True,\n )\n return None\n\n\n# ------------------------------------------------------------------\n# Public entry point\n# ------------------------------------------------------------------\n\n\nasync def transcribe_audio(file_path: str) -> Optional[str]:\n \"\"\"Transcribe an audio file to text.\n\n Dispatches to either the Whisper API or local Whisper based on the\n ``transcription_provider_type`` config setting. When the setting is\n ``\"disabled\"`` (the default), returns ``None`` immediately.\n\n Returns the transcribed text, or ``None`` on failure.\n \"\"\"\n from ...config import load_config\n\n provider_type = load_config().agents.transcription_provider_type\n\n if provider_type == \"disabled\":\n logger.debug(\"Transcription is disabled; skipping\")\n return None\n if provider_type == \"local_whisper\":\n return await _transcribe_local_whisper(file_path)\n if provider_type == \"whisper_api\":\n return await _transcribe_whisper_api(file_path)\n\n logger.warning(\"Unknown transcription_provider_type: %s\", provider_type)\n return None\n" }, { "path": "src/copaw/agents/utils/copaw_token_counter.py", "content": "# -*- coding: utf-8 -*-\n\"\"\"Token counting utilities for CoPaw using HuggingFace tokenizers.\n\nThis module provides a configurable token counter that supports dynamic\nswitching between different tokenizer models based on runtime configuration.\n\"\"\"\nimport logging\nimport os\nfrom pathlib import Path\nfrom typing import Any, TYPE_CHECKING\n\nfrom agentscope.token import HuggingFaceTokenCounter\n\nif TYPE_CHECKING:\n from copaw.config.config import AgentProfileConfig\n\nlogger = logging.getLogger(__name__)\n\n\nclass CopawTokenCounter(HuggingFaceTokenCounter):\n \"\"\"Token counter for CoPaw with configurable tokenizer support.\n\n This class extends HuggingFaceTokenCounter to provide token counting\n functionality with support for both local and remote tokenizers,\n as well as HuggingFace mirror for users in China.\n\n Attributes:\n token_count_model: The tokenizer model path or \"default\" for\n local tokenizer.\n token_count_use_mirror: Whether to use HuggingFace mirror.\n token_count_estimate_divisor: Divisor for character-based token\n estimation.\n \"\"\"\n\n def __init__(\n self,\n token_count_model: str,\n token_count_use_mirror: bool,\n token_count_estimate_divisor: float = 3.75,\n **kwargs,\n ):\n \"\"\"Initialize the token counter with the specified configuration.\n\n Args:\n token_count_model: The tokenizer model path. Use \"default\"\n for the bundled local tokenizer, or provide a HuggingFace\n model identifier or path to a custom tokenizer.\n token_count_use_mirror: Whether to use the HuggingFace mirror\n (https://hf-mirror.com) for downloading tokenizers.\n Useful for users in China.\n token_count_estimate_divisor: Divisor for character-based token\n estimation (default: 3.75).\n **kwargs: Additional keyword arguments passed to\n HuggingFaceTokenCounter.\n \"\"\"\n self.token_count_model = token_count_model\n self.token_count_use_mirror = token_count_use_mirror\n self.token_count_estimate_divisor = token_count_estimate_divisor\n\n # Set HuggingFace endpoint for mirror support\n if token_count_use_mirror:\n mirror = \"https://hf-mirror.com\"\n else:\n mirror = \"https://huggingface.co\"\n\n os.environ[\"HF_ENDPOINT\"] = mirror\n\n # if the huggingface is already imported in other dependencies,\n # we need to set the endpoint manually\n import huggingface_hub.constants\n\n huggingface_hub.constants.ENDPOINT = mirror\n huggingface_hub.constants.HUGGINGFACE_CO_URL_TEMPLATE = (\n mirror + \"/{repo_id}/resolve/{revision}/{filename}\"\n )\n\n # Resolve tokenizer path\n if token_count_model == \"default\":\n tokenizer_path = str(\n Path(__file__).parent.parent.parent / \"tokenizer\",\n )\n else:\n tokenizer_path = token_count_model\n\n try:\n super().__init__(\n pretrained_model_name_or_path=tokenizer_path,\n use_mirror=token_count_use_mirror,\n use_fast=True,\n trust_remote_code=True,\n **kwargs,\n )\n self._tokenizer_available = True\n\n except Exception as e:\n logger.exception(\"Failed to initialize tokenizer: %s\", e)\n self._tokenizer_available = False\n\n async def count(\n self,\n messages: list[dict],\n tools: list[dict] | None = None,\n text: str | None = None,\n **kwargs: Any,\n ) -> int:\n \"\"\"Count tokens in messages or text.\n\n If text is provided, counts tokens directly in the text string.\n Otherwise, counts tokens in the messages using the parent class method.\n\n Args:\n messages: List of message dictionaries in chat format.\n tools: Optional list of tool definitions for token counting.\n text: Optional text string to count tokens directly.\n **kwargs: Additional keyword arguments passed to parent\n count method.\n\n Returns:\n The number of tokens, guaranteed to be at least the\n estimated minimum.\n \"\"\"\n if text:\n if self._tokenizer_available:\n try:\n token_ids = self.tokenizer.encode(text)\n return max(len(token_ids), self.estimate_tokens(text))\n except Exception as e:\n logger.exception(\n \"Failed to encode text with tokenizer: %s\",\n e,\n )\n return self.estimate_tokens(text)\n else:\n return self.estimate_tokens(text)\n else:\n return await super().count(messages, tools, **kwargs)\n\n def estimate_tokens(self, text: str) -> int:\n \"\"\"Estimate the number of tokens in a text string.\n\n Provides a fast character-based estimation as a fallback\n or lower bound. Uses the configured divisor from agent settings.\n\n Args:\n text: The text string to estimate tokens for.\n\n Returns:\n The estimated number of tokens in the text string.\n \"\"\"\n return int(\n len(text.encode(\"utf-8\")) / self.token_count_estimate_divisor\n + 0.5,\n )\n\n\n# Global token counter instance cache (keyed by configuration tuple)\n_token_counter_cache: dict[tuple, CopawTokenCounter] = {}\n\n\ndef get_copaw_token_counter(\n agent_config: \"AgentProfileConfig\",\n) -> CopawTokenCounter:\n \"\"\"Get or create a token counter instance for the given agent conf.\n\n This function implements a cache based on token counter configuration.\n If a token counter with the same configuration already exists, it will be\n reused. Otherwise, a new instance will be created.\n\n Args:\n agent_config: Agent profile configuration containing running\n settings including token_count_model, token_count_use_mirror,\n and token_count_estimate_divisor.\n\n Returns:\n CopawTokenCounter: A token counter instance for the given\n configuration.\n\n Note:\n Token counters are cached by their configuration tuple to enable\n reuse across agents with identical settings.\n \"\"\"\n running_config = agent_config.running\n config_key = (\n running_config.token_count_model,\n running_config.token_count_use_mirror,\n )\n\n if config_key not in _token_counter_cache:\n _token_counter_cache[config_key] = CopawTokenCounter(\n token_count_model=running_config.token_count_model,\n token_count_use_mirror=running_config.token_count_use_mirror,\n token_count_estimate_divisor=(\n running_config.token_count_estimate_divisor\n ),\n )\n logger.info(\n f\"Token counter created with \"\n f\"model={running_config.token_count_model}, \"\n f\"mirror={running_config.token_count_use_mirror}, \"\n f\"divisor={running_config.token_count_estimate_divisor}\",\n )\n else:\n # Update estimate divisor for cached counter\n _token_counter_cache[\n config_key\n ].token_count_estimate_divisor = (\n running_config.token_count_estimate_divisor\n )\n\n return _token_counter_cache[config_key]\n" }, { "path": "src/copaw/agents/utils/file_handling.py", "content": "# -*- coding: utf-8 -*-\n\"\"\"File handling utilities for downloading and managing files.\n\nThis module provides utilities for:\n- Downloading files from base64 encoded data\n- Downloading files from URLs\n- Managing download directories\n\"\"\"\nimport os\nimport mimetypes\nimport base64\nimport hashlib\nimport logging\nimport subprocess\nimport urllib.parse\nimport urllib.request\nfrom pathlib import Path\nfrom typing import Optional\n\nlogger = logging.getLogger(__name__)\n\n\ndef _resolve_local_path(\n url: str,\n parsed: urllib.parse.ParseResult,\n) -> Optional[str]:\n \"\"\"Return local file path for file:// or plain path; None for remote.\"\"\"\n if parsed.scheme == \"file\":\n local_path = Path(urllib.request.url2pathname(parsed.path))\n if not local_path.exists():\n raise FileNotFoundError(f\"Local file not found: {local_path}\")\n if local_path.is_file() and local_path.stat().st_size == 0:\n raise ValueError(f\"Local file is empty: {local_path}\")\n return str(local_path.resolve())\n if parsed.scheme == \"\" and parsed.netloc == \"\":\n p = Path(url).expanduser()\n if p.exists():\n if p.is_file() and p.stat().st_size == 0:\n raise ValueError(f\"Local file is empty: {p}\")\n return str(p.resolve())\n # Windows absolute path: urlparse(\"C:\\\\path\") -> scheme=\"c\", path=\"\\\\path\"\n if (\n os.name == \"nt\"\n and len(parsed.scheme) == 1\n and parsed.scheme.isalpha()\n and (parsed.path.startswith(\"\\\\\") or parsed.path.startswith(\"/\"))\n ):\n p = Path(url.strip()).resolve()\n if p.exists() and p.is_file():\n if p.stat().st_size == 0:\n raise ValueError(f\"Local file is empty: {p}\")\n return str(p)\n return None\n\n\ndef _download_remote_to_path(url: str, local_file_path: Path) -> None:\n \"\"\"\n Download url to local_file_path via wget, curl, or urllib. Raises on fail.\n \"\"\"\n try:\n subprocess.run(\n [\"wget\", \"-q\", \"-O\", str(local_file_path), url],\n capture_output=True,\n timeout=60,\n check=True,\n )\n logger.debug(\"Downloaded file via wget to: %s\", local_file_path)\n return\n except (subprocess.CalledProcessError, FileNotFoundError) as e:\n logger.debug(\"wget failed, trying curl: %s\", e)\n try:\n subprocess.run(\n [\"curl\", \"-s\", \"-L\", \"-o\", str(local_file_path), url],\n capture_output=True,\n timeout=60,\n check=True,\n )\n logger.debug(\"Downloaded file via curl to: %s\", local_file_path)\n return\n except (subprocess.CalledProcessError, FileNotFoundError) as curl_err:\n logger.debug(\"curl failed, trying urllib: %s\", curl_err)\n try:\n urllib.request.urlretrieve(url, str(local_file_path))\n logger.debug(\"Downloaded file via urllib to: %s\", local_file_path)\n except Exception as urllib_err:\n logger.error(\n \"wget, curl and urllib all failed for URL %s: %s\",\n url,\n urllib_err,\n )\n raise RuntimeError(\n \"Failed to download file: wget, curl and urllib all failed\",\n ) from urllib_err\n\n\ndef _guess_suffix_from_url_headers(url: str) -> Optional[str]:\n \"\"\"\n HEAD request to get Content-Type and return a suffix like '.pdf'.\n Used to fix DingTalk download URLs that always return .file extension.\n Returns None on any failure (e.g. OSS forbids HEAD or returns no type).\n \"\"\"\n try:\n req = urllib.request.Request(url, method=\"HEAD\")\n with urllib.request.urlopen(req, timeout=10) as resp:\n raw = (\n (resp.headers.get(\"Content-Type\") or \"\").split(\";\")[0].strip()\n )\n if not raw:\n return None\n suffix = mimetypes.guess_extension(raw)\n return suffix if suffix else None\n except Exception:\n return None\n\n\n# Magic bytes (prefix) -> suffix for .file fallback when HEAD fails (e.g. OSS).\n_MAGIC_SUFFIX: list[tuple[bytes, str]] = [\n (b\"%PDF\", \".pdf\"),\n (b\"PK\\x03\\x04\", \".zip\"),\n (b\"PK\\x05\\x06\", \".zip\"),\n (b\"\\x89PNG\\r\\n\\x1a\\n\", \".png\"),\n (b\"\\xff\\xd8\\xff\", \".jpg\"),\n (b\"GIF87a\", \".gif\"),\n (b\"GIF89a\", \".gif\"),\n (b\"\\xd0\\xcf\\x11\\xe0\", \".doc\"), # MS Office (doc, xls, ppt)\n (b\"RIFF\", \".webp\"), # or .wav; webp has RIFF....WEBP\n]\n\n\ndef _guess_suffix_from_file_content(path: Path) -> Optional[str]:\n \"\"\"\n Guess file extension from magic bytes. Used when URL HEAD fails (e.g. OSS).\n Returns suffix like '.pdf' or None.\n \"\"\"\n try:\n with open(path, \"rb\") as f:\n head = f.read(32)\n for magic, suffix in _MAGIC_SUFFIX:\n if head.startswith(magic):\n return suffix\n return None\n except Exception:\n return None\n\n\nasync def download_file_from_base64(\n base64_data: str,\n filename: Optional[str] = None,\n download_dir: str = \"downloads\",\n) -> str:\n \"\"\"\n Save base64-encoded file data to local download directory.\n\n Args:\n base64_data: Base64-encoded file content.\n filename: The filename to save. If not provided, will generate one.\n download_dir: The directory to save files. Defaults to \"downloads\".\n\n Returns:\n The local file path.\n \"\"\"\n try:\n file_content = base64.b64decode(base64_data)\n\n download_path = Path(download_dir)\n download_path.mkdir(parents=True, exist_ok=True)\n\n if not filename:\n file_hash = hashlib.md5(file_content).hexdigest()\n filename = f\"file_{file_hash}\"\n\n local_file_path = download_path / filename\n with open(local_file_path, \"wb\") as f:\n f.write(file_content)\n\n logger.debug(\"Downloaded file to: %s\", local_file_path)\n return str(local_file_path.absolute())\n\n except Exception as e:\n logger.error(\"Failed to download file from base64: %s\", e)\n raise\n\n\nasync def download_file_from_url(\n url: str,\n filename: Optional[str] = None,\n download_dir: str = \"downloads\",\n) -> str:\n \"\"\"\n Download a file from URL to local download directory using wget or curl.\n\n Args:\n url (`str`):\n The URL of the file to download.\n filename (`str`, optional):\n The filename to save. If not provided, will extract from URL or\n generate a hash-based name.\n download_dir (`str`):\n The directory to save files. Defaults to \"downloads\".\n\n Returns:\n `str`:\n The local file path.\n \"\"\"\n try:\n parsed = urllib.parse.urlparse(url)\n local = _resolve_local_path(url, parsed)\n if local is not None:\n return local\n\n download_path = Path(download_dir)\n download_path.mkdir(parents=True, exist_ok=True)\n if not filename:\n url_filename = os.path.basename(parsed.path)\n filename = (\n url_filename\n if url_filename\n else f\"file_{hashlib.md5(url.encode()).hexdigest()}\"\n )\n local_file_path = download_path / filename\n _download_remote_to_path(url, local_file_path)\n if not local_file_path.exists():\n raise FileNotFoundError(\"Downloaded file does not exist\")\n if local_file_path.stat().st_size == 0:\n raise ValueError(\"Downloaded file is empty\")\n # DingTalk (and similar) return URLs that save as .file; replace with\n # real extension. Try HEAD first; if that fails (e.g. OSS), use magic.\n if local_file_path.suffix == \".file\":\n real_suffix = _guess_suffix_from_url_headers(url)\n if not real_suffix:\n real_suffix = _guess_suffix_from_file_content(local_file_path)\n if real_suffix:\n new_path = local_file_path.with_suffix(real_suffix)\n local_file_path.rename(new_path)\n local_file_path = new_path\n logger.debug(\n \"Replaced .file with %s for %s\",\n real_suffix,\n local_file_path,\n )\n return str(local_file_path.absolute())\n except subprocess.TimeoutExpired as e:\n logger.error(\"Download timeout for URL: %s\", url)\n raise TimeoutError(f\"Download timeout for URL: {url}\") from e\n except Exception as e:\n logger.error(\"Failed to download file from URL %s: %s\", url, e)\n raise\n" }, { "path": "src/copaw/agents/utils/message_processing.py", "content": "# -*- coding: utf-8 -*-\n\"\"\"Message processing utilities for agent communication.\n\nThis module handles:\n- File and media block processing\n- Message content manipulation\n- Message validation\n\"\"\"\nimport asyncio\nimport logging\nimport os\nimport urllib.parse\nimport urllib.request\nfrom pathlib import Path\nfrom typing import Optional\n\nfrom agentscope.message import Msg\n\nfrom ...config import load_config\nfrom .file_handling import download_file_from_base64, download_file_from_url\n\nlogger = logging.getLogger(__name__)\n\n\nasync def _process_single_file_block(\n source: dict,\n filename: Optional[str],\n) -> Optional[str]:\n \"\"\"\n Process a single file block and download the file.\n\n Args:\n source: The source dict containing file information.\n filename: The filename to save.\n\n Returns:\n The local file path if successful, None otherwise.\n \"\"\"\n if isinstance(source, dict) and source.get(\"type\") == \"base64\":\n if \"data\" in source:\n base64_data = source.get(\"data\", \"\")\n local_path = await download_file_from_base64(\n base64_data,\n filename,\n )\n logger.debug(\n \"Processed base64 file block: %s -> %s\",\n filename or \"unnamed\",\n local_path,\n )\n return local_path\n\n elif isinstance(source, dict) and source.get(\"type\") == \"url\":\n url = source.get(\"url\", \"\")\n if url:\n parsed = urllib.parse.urlparse(url)\n if parsed.scheme == \"file\":\n try:\n local_path = urllib.request.url2pathname(parsed.path)\n except Exception:\n return None\n local_path = await download_file_from_url(\n url,\n filename,\n )\n logger.debug(\n \"Processed URL file block: %s -> %s\",\n url,\n local_path,\n )\n return local_path\n\n return None\n\n\ndef _extract_source_and_filename(block: dict, block_type: str):\n \"\"\"Extract source and filename from a block.\"\"\"\n if block_type == \"file\":\n return block.get(\"source\", {}), block.get(\"filename\")\n\n source = block.get(\"source\", {})\n if not isinstance(source, dict):\n return None, None\n\n filename = None\n if source.get(\"type\") == \"url\":\n url = source.get(\"url\", \"\")\n if url:\n parsed = urllib.parse.urlparse(url)\n filename = os.path.basename(parsed.path) or None\n\n return source, filename\n\n\ndef _media_type_from_path(path: str) -> str:\n \"\"\"Infer audio media_type from file path suffix.\"\"\"\n ext = (os.path.splitext(path)[1] or \"\").lower()\n return {\n \".amr\": \"audio/amr\",\n \".wav\": \"audio/wav\",\n \".mp3\": \"audio/mp3\",\n \".opus\": \"audio/opus\",\n \".ogg\": \"audio/ogg\",\n \".flac\": \"audio/flac\",\n \".m4a\": \"audio/mp4\",\n \".aac\": \"audio/aac\",\n }.get(ext, \"audio/octet-stream\")\n\n\n# Extensions accepted by the agentscope OpenAIChatFormatter\n_FORMATTER_SUPPORTED_AUDIO_EXTS = {\".wav\", \".mp3\"}\n\n\ndef _convert_audio_to_wav(src_path: str) -> Optional[str]:\n \"\"\"Convert an audio file to .wav using ffmpeg if the extension is not\n natively supported by the LLM formatter.\n\n Uses a unique temporary file name to avoid overwriting existing files.\n\n Returns the path to the converted .wav file, or None if conversion\n failed or was not needed.\n \"\"\"\n ext = (os.path.splitext(src_path)[1] or \"\").lower()\n if ext in _FORMATTER_SUPPORTED_AUDIO_EXTS:\n return None # already supported, no conversion needed\n\n import subprocess\n import shutil\n import tempfile\n\n if not shutil.which(\"ffmpeg\"):\n logger.warning(\n \"ffmpeg not found; cannot convert %s audio to wav. \"\n \"Install ffmpeg to enable audio format conversion.\",\n ext,\n )\n return None\n\n # Use a temp file in the same directory to avoid clobbering.\n src_dir = os.path.dirname(src_path) or \".\"\n fd, dst_path = tempfile.mkstemp(suffix=\".wav\", dir=src_dir)\n os.close(fd)\n try:\n subprocess.run(\n [\n \"ffmpeg\",\n \"-y\",\n \"-loglevel\",\n \"error\",\n \"-i\",\n src_path,\n \"-ar\",\n \"16000\",\n \"-ac\",\n \"1\",\n dst_path,\n ],\n stdout=subprocess.DEVNULL,\n stderr=subprocess.PIPE,\n timeout=30,\n check=True,\n )\n logger.debug(\"Converted audio %s -> %s\", src_path, dst_path)\n return dst_path\n except (subprocess.CalledProcessError, subprocess.TimeoutExpired) as e:\n stderr = getattr(e, \"stderr\", b\"\") or b\"\"\n logger.warning(\n \"Audio conversion failed for %s: %s\\nffmpeg stderr: %s\",\n src_path,\n e,\n stderr.decode(errors=\"replace\"),\n )\n # Clean up the temp file on failure.\n try:\n os.unlink(dst_path)\n except OSError:\n pass\n return None\n\n\ndef _update_block_with_local_path(\n block: dict,\n block_type: str,\n local_path: str,\n) -> dict:\n \"\"\"Update block with downloaded local path.\"\"\"\n if block_type == \"file\":\n block[\"source\"] = local_path\n if not block.get(\"filename\"):\n block[\"filename\"] = os.path.basename(local_path)\n else:\n if block_type == \"audio\":\n block[\"source\"] = {\n \"type\": \"url\",\n \"url\": Path(local_path).as_uri(),\n \"media_type\": _media_type_from_path(local_path),\n }\n else:\n block[\"source\"] = {\n \"type\": \"url\",\n \"url\": Path(local_path).as_uri(),\n }\n return block\n\n\ndef _handle_download_failure(block_type: str) -> Optional[dict]:\n \"\"\"Handle download failure based on block type.\"\"\"\n if block_type == \"file\":\n return {\n \"type\": \"text\",\n \"text\": \"[Error: Unknown file source type or empty data]\",\n }\n logger.debug(\"Failed to download %s block, keeping original\", block_type)\n return None\n\n\nasync def _process_audio_block(\n message_content: list,\n index: int,\n local_path: str,\n block: dict,\n) -> bool:\n \"\"\"Handle an audio block according to the configured audio_mode.\n\n Modes:\n - ``\"auto\"`` (default): try transcription; if it succeeds, replace\n the audio block with the transcribed text and suppress file\n metadata. If transcription fails (no provider, missing deps,\n API error), show a file-uploaded placeholder instead. Audio is\n never sent directly to the model in this mode.\n - ``\"native\"``: send the audio block directly to the model\n (convert via ffmpeg if needed). No transcription is attempted.\n If the file format is unsupported and conversion fails, a text\n placeholder is shown instead.\n\n Returns:\n True if the audio was fully handled (transcribed or sent natively)\n — the \"file downloaded\" notification will be suppressed.\n False if transcription failed — the notification is kept so the\n LLM knows the file path.\n \"\"\"\n from .audio_transcription import transcribe_audio\n\n audio_mode = load_config().agents.audio_mode\n\n if audio_mode == \"native\":\n converted = await asyncio.to_thread(\n _convert_audio_to_wav,\n local_path,\n )\n ext = (os.path.splitext(local_path)[1] or \"\").lower()\n if converted:\n audio_path = converted\n elif ext in _FORMATTER_SUPPORTED_AUDIO_EXTS:\n # Already a supported format, no conversion needed.\n audio_path = local_path\n else:\n # Unsupported format and conversion failed — show placeholder\n # instead of sending an unsupported audio block to the model.\n message_content[index] = {\n \"type\": \"text\",\n \"text\": (\n \"[Voice message]: (audio conversion failed, \"\n \"install ffmpeg to enable native audio)\"\n ),\n }\n return True\n block[\"source\"] = {\n \"type\": \"url\",\n \"url\": Path(audio_path).as_uri(),\n \"media_type\": _media_type_from_path(audio_path),\n }\n return True\n\n # \"auto\": attempt transcription.\n text = await transcribe_audio(local_path)\n if text:\n message_content[index] = {\n \"type\": \"text\",\n \"text\": f\"[Voice message]: {text}\",\n }\n return True\n\n # Transcription failed — show file-uploaded placeholder.\n message_content[index] = {\n \"type\": \"text\",\n \"text\": \"[Voice message]: (audio file received)\",\n }\n return False\n\n\nasync def _process_single_block(\n message_content: list,\n index: int,\n block: dict,\n) -> Optional[str]:\n \"\"\"\n Process a single file or media block.\n\n Returns:\n Optional[str]: The local path if download was successful,\n None otherwise.\n \"\"\"\n block_type = block.get(\"type\")\n if not isinstance(block_type, str):\n return None\n\n source, filename = _extract_source_and_filename(block, block_type)\n if source is None:\n return None\n\n # Normalize: when source is \"base64\" but data is a local path (e.g.\n # DingTalk voice returns path), treat as url only if under allowed dir.\n if (\n block_type == \"audio\"\n and isinstance(source, dict)\n and source.get(\"type\") == \"base64\"\n ):\n data = source.get(\"data\")\n if isinstance(data, str) and os.path.isfile(data):\n block[\"source\"] = {\n \"type\": \"url\",\n \"url\": Path(data).as_uri(),\n \"media_type\": _media_type_from_path(data),\n }\n source = block[\"source\"]\n\n try:\n local_path = await _process_single_file_block(source, filename)\n\n if local_path:\n if block_type == \"audio\":\n # Audio blocks need transcription or format conversion\n # depending on the configured audio_mode.\n _update_block_with_local_path(block, block_type, local_path)\n handled = await _process_audio_block(\n message_content,\n index,\n local_path,\n block,\n )\n if handled:\n # Audio was transcribed or sent natively; suppress the\n # \"file downloaded\" notification that would follow.\n return None\n else:\n message_content[index] = _update_block_with_local_path(\n block,\n block_type,\n local_path,\n )\n logger.debug(\n \"Updated %s block with local path: %s\",\n block_type,\n local_path,\n )\n return local_path\n else:\n error_block = _handle_download_failure(block_type)\n if error_block:\n message_content[index] = error_block\n return None\n\n except Exception as e:\n logger.error(\"Failed to process %s block: %s\", block_type, e)\n if block_type == \"file\":\n message_content[index] = {\n \"type\": \"text\",\n \"text\": f\"[Error: Failed to download file - {e}]\",\n }\n return None\n\n\nasync def process_file_and_media_blocks_in_message(msg) -> None:\n \"\"\"\n Process file and media blocks (file, image, audio, video) in messages.\n Downloads to local and updates paths/URLs.\n\n Args:\n msg: The message object (Msg or list[Msg]) to process.\n \"\"\"\n messages = (\n [msg] if isinstance(msg, Msg) else msg if isinstance(msg, list) else []\n )\n\n for message in messages:\n if not isinstance(message, Msg):\n continue\n\n if not isinstance(message.content, list):\n continue\n\n downloaded_files = []\n\n for i, block in enumerate(message.content):\n if not isinstance(block, dict):\n continue\n\n block_type = block.get(\"type\")\n if block_type not in [\"file\", \"image\", \"audio\", \"video\"]:\n continue\n\n local_path = await _process_single_block(message.content, i, block)\n if local_path:\n downloaded_files.append((i, local_path))\n\n if downloaded_files:\n lang = load_config().agents.language\n for i, local_path in reversed(downloaded_files):\n text = (\n f\"用户上传文件，已经下载到 {local_path}\"\n if lang == \"zh\"\n else f\"User uploaded a file, downloaded to {local_path}\"\n )\n text_block = {\"type\": \"text\", \"text\": text}\n message.content.insert(i + 1, text_block)\n\n\ndef is_first_user_interaction(messages: list) -> bool:\n \"\"\"Check if this is the first user interaction.\n\n Args:\n messages: List of Msg objects from memory.\n\n Returns:\n bool: True if this is the first user message with no assistant\n responses.\n \"\"\"\n system_prompt_count = sum(1 for msg in messages if msg.role == \"system\")\n non_system_messages = messages[system_prompt_count:]\n\n user_msg_count = sum(\n 1 for msg in non_system_messages if msg.role == \"user\"\n )\n assistant_msg_count = sum(\n 1 for msg in non_system_messages if msg.role == \"assistant\"\n )\n\n return user_msg_count == 1 and assistant_msg_count == 0\n\n\ndef prepend_to_message_content(msg, guidance: str) -> None:\n \"\"\"Prepend guidance text to message content.\n\n Args:\n msg: Msg object to modify.\n guidance: Text to prepend to the message content.\n \"\"\"\n if isinstance(msg.content, str):\n msg.content = guidance + \"\\n\\n\" + msg.content\n return\n\n if not isinstance(msg.content, list):\n return\n\n for block in msg.content:\n if isinstance(block, dict) and block.get(\"type\") == \"text\":\n block[\"text\"] = guidance + \"\\n\\n\" + block.get(\"text\", \"\")\n return\n\n msg.content.insert(0, {\"type\": \"text\", \"text\": guidance})\n" }, { "path": "src/copaw/agents/utils/setup_utils.py", "content": "# -*- coding: utf-8 -*-\n\"\"\"Setup and initialization utilities for agent configuration.\n\nThis module handles copying markdown configuration files to\nthe working directory.\n\"\"\"\nimport logging\nimport shutil\nfrom pathlib import Path\n\nlogger = logging.getLogger(__name__)\n\n\ndef copy_md_files(\n language: str,\n skip_existing: bool = False,\n workspace_dir: Path | None = None,\n) -> list[str]:\n \"\"\"Copy md files from agents/md_files to working directory.\n\n Args:\n language: Language code (e.g. 'en', 'zh')\n skip_existing: If True, skip files that already exist in working dir.\n workspace_dir: Target workspace directory. If None, uses WORKING_DIR.\n\n Returns:\n List of copied file names.\n \"\"\"\n from ...constant import WORKING_DIR\n\n # Use provided workspace_dir or default to WORKING_DIR\n target_dir = workspace_dir if workspace_dir is not None else WORKING_DIR\n\n # Get md_files directory path with language subdirectory\n md_files_dir = Path(__file__).parent.parent / \"md_files\" / language\n\n if not md_files_dir.exists():\n logger.warning(\n \"MD files directory not found: %s, falling back to 'en'\",\n md_files_dir,\n )\n # Fallback to English if specified language not found\n md_files_dir = Path(__file__).parent.parent / \"md_files\" / \"en\"\n if not md_files_dir.exists():\n logger.error(\"Default 'en' md files not found either\")\n return []\n\n # Ensure target directory exists\n target_dir.mkdir(parents=True, exist_ok=True)\n\n # Copy all .md files to target directory\n copied_files: list[str] = []\n for md_file in md_files_dir.glob(\"*.md\"):\n target_file = target_dir / md_file.name\n if skip_existing and target_file.exists():\n logger.debug(\"Skipped existing md file: %s\", md_file.name)\n continue\n try:\n shutil.copy2(md_file, target_file)\n logger.debug(\"Copied md file: %s\", md_file.name)\n copied_files.append(md_file.name)\n except Exception as e:\n logger.error(\n \"Failed to copy md file '%s': %s\",\n md_file.name,\n e,\n )\n\n if copied_files:\n logger.debug(\n \"Copied %d md file(s) [%s] to %s\",\n len(copied_files),\n language,\n target_dir,\n )\n\n return copied_files\n" }, { "path": "src/copaw/agents/utils/tool_message_utils.py", "content": "# -*- coding: utf-8 -*-\n\"\"\"Tool message validation and sanitization utilities.\n\nThis module ensures tool_use and tool_result messages are properly\npaired and ordered to prevent API errors.\n\"\"\"\nimport json\nimport logging\n\nlogger = logging.getLogger(__name__)\n\n\ndef extract_tool_ids(msg) -> tuple[set[str], set[str]]:\n \"\"\"Return (tool_use_ids, tool_result_ids) found in a single message.\n\n Args:\n msg: A Msg object whose content may contain tool blocks.\n\n Returns:\n A tuple of two sets: (tool_use IDs, tool_result IDs).\n \"\"\"\n uses: set[str] = set()\n results: set[str] = set()\n if isinstance(msg.content, list):\n for block in msg.content:\n if isinstance(block, dict) and block.get(\"id\"):\n btype = block.get(\"type\")\n if btype == \"tool_use\":\n uses.add(block[\"id\"])\n elif btype == \"tool_result\":\n results.add(block[\"id\"])\n return uses, results\n\n\ndef check_valid_messages(messages: list) -> bool:\n \"\"\"\n Check if the messages are valid by ensuring all tool_use blocks have\n corresponding tool_result blocks.\n\n Args:\n messages: List of Msg objects to validate.\n\n Returns:\n bool: True if all tool_use IDs have matching tool_result IDs,\n False otherwise.\n \"\"\"\n use_ids: set[str] = set()\n result_ids: set[str] = set()\n for msg in messages:\n u, r = extract_tool_ids(msg)\n use_ids |= u\n result_ids |= r\n return use_ids == result_ids\n\n\ndef _reorder_tool_results(msgs: list) -> list:\n \"\"\"Move tool_result messages right after their corresponding tool_use.\n\n Handles duplicate tool_call_ids by consuming results FIFO.\n \"\"\"\n results_by_id: dict[str, list[object]] = {}\n result_msg_ids: set[int] = set()\n for msg in msgs:\n if isinstance(msg.content, list):\n for block in msg.content:\n if (\n isinstance(block, dict)\n and block.get(\"type\") == \"tool_result\"\n and block.get(\"id\")\n ):\n results_by_id.setdefault(block[\"id\"], []).append(msg)\n result_msg_ids.add(id(msg))\n\n consumed: dict[str, int] = {}\n reordered: list = []\n placed: set[int] = set()\n for msg in msgs:\n if id(msg) in result_msg_ids:\n continue\n reordered.append(msg)\n if not isinstance(msg.content, list):\n continue\n for block in msg.content:\n if not (\n isinstance(block, dict)\n and block.get(\"type\") == \"tool_use\"\n and block.get(\"id\")\n ):\n continue\n bid = block[\"id\"]\n candidates = results_by_id.get(bid, [])\n ci = consumed.get(bid, 0)\n if ci >= len(candidates):\n continue\n rm = candidates[ci]\n consumed[bid] = ci + 1\n if id(rm) not in placed:\n reordered.append(rm)\n placed.add(id(rm))\n\n return reordered\n\n\ndef _remove_unpaired_tool_messages(msgs: list) -> list:\n \"\"\"Remove tool_use/tool_result messages that aren't properly paired.\n\n Each tool_use must be immediately followed by tool_results for all\n its IDs. Unpaired messages and orphaned results are removed.\n \"\"\"\n to_remove: set[int] = set()\n\n i = 0\n while i < len(msgs):\n use_ids, _ = extract_tool_ids(msgs[i])\n if not use_ids:\n i += 1\n continue\n required = set(use_ids)\n j = i + 1\n result_indices: list[int] = []\n while j < len(msgs) and required:\n _, r = extract_tool_ids(msgs[j])\n if not r:\n break\n required -= r\n result_indices.append(j)\n j += 1\n if required:\n to_remove.add(i)\n to_remove.update(result_indices)\n i += 1\n else:\n i = j\n\n surviving_use_ids: set[str] = set()\n for idx, msg in enumerate(msgs):\n if idx not in to_remove:\n u, _ = extract_tool_ids(msg)\n surviving_use_ids |= u\n for idx, msg in enumerate(msgs):\n if idx in to_remove:\n continue\n _, r = extract_tool_ids(msg)\n if r and not r.issubset(surviving_use_ids):\n to_remove.add(idx)\n\n return [msg for idx, msg in enumerate(msgs) if idx not in to_remove]\n\n\ndef _dedup_tool_blocks(msgs: list) -> list:\n \"\"\"Remove duplicate tool_use blocks (same ID) within a single message.\"\"\"\n changed = False\n result: list = []\n for msg in msgs:\n if not isinstance(msg.content, list):\n result.append(msg)\n continue\n seen_ids: set[str] = set()\n new_blocks: list = []\n deduped = False\n for block in msg.content:\n if (\n isinstance(block, dict)\n and block.get(\"type\") == \"tool_use\"\n and block.get(\"id\")\n ):\n if block[\"id\"] in seen_ids:\n deduped = True\n continue\n seen_ids.add(block[\"id\"])\n new_blocks.append(block)\n if deduped:\n msg.content = new_blocks\n changed = True\n result.append(msg)\n return result if changed else msgs\n\n\ndef _remove_invalid_tool_blocks(msgs: list) -> list:\n \"\"\"Remove tool_use/tool_result blocks with invalid id/name.\n\n A valid tool_use block must have:\n - Non-empty, non-None id\n - Non-empty, non-None name\n\n A valid tool_result block must have:\n - Non-empty, non-None id\n\n Args:\n msgs: List of Msg objects to validate.\n\n Returns:\n List of Msg objects with invalid tool blocks removed.\n \"\"\"\n changed = False\n result: list = []\n\n for msg in msgs:\n if not isinstance(msg.content, list):\n result.append(msg)\n continue\n\n new_blocks: list = []\n removed = False\n\n for block in msg.content:\n if not isinstance(block, dict):\n new_blocks.append(block)\n continue\n\n block_type = block.get(\"type\")\n\n # Validate tool_use and tool_result blocks\n if block_type in (\"tool_use\", \"tool_result\"):\n block_id = block.get(\"id\")\n block_name = block.get(\"name\")\n\n # Check if id is valid (not None, not empty string)\n if not block_id:\n logger.warning(\n \"Removing %s with invalid id: id=%r, name=%r\",\n block_type,\n block_id,\n block_name,\n )\n removed = True\n continue\n\n # For tool_use, also check name is non-empty\n if block_type == \"tool_use\" and not block_name:\n logger.warning(\n \"Removing tool_use with invalid name: id=%r, name=%r\",\n block_id,\n block_name,\n )\n removed = True\n continue\n\n new_blocks.append(block)\n\n if removed:\n msg.content = new_blocks\n changed = True\n\n result.append(msg)\n\n return result if changed else msgs\n\n\ndef _repair_empty_tool_inputs(\n msgs: list,\n) -> list:\n \"\"\"Repair tool_use blocks with empty input but valid raw_input.\n\n This fixes a bug in AgentScope 1.0.16dev where stream_tool_parsing\n may fail to parse arguments correctly, leaving input={} while\n raw_input contains valid JSON.\n\n Args:\n msgs: List of Msg objects to repair.\n\n Returns:\n List of Msg objects with repaired tool_use blocks.\n \"\"\"\n # pylint: disable=too-many-nested-blocks\n changed = False\n result: list = []\n\n for msg in msgs:\n if not isinstance(msg.content, list):\n result.append(msg)\n continue\n\n new_blocks: list = []\n repaired = False\n\n for block in msg.content:\n if not isinstance(block, dict):\n new_blocks.append(block)\n continue\n\n # Check if this is a tool_use with empty input but valid raw_input\n if block.get(\"type\") == \"tool_use\":\n input_field = block.get(\"input\", {})\n raw_input = block.get(\"raw_input\", \"\")\n\n # If input is empty but raw_input has content, try to parse\n if not input_field and raw_input and raw_input != \"{}\":\n try:\n parsed = json.loads(raw_input)\n if isinstance(parsed, dict) and parsed:\n # Success! Update the input field\n block[\"input\"] = parsed\n repaired = True\n logger.info(\n \"Repaired tool_use input from raw_input: \"\n \"id=%s, name=%s, keys=%s\",\n block.get(\"id\"),\n block.get(\"name\"),\n list(parsed.keys()),\n )\n except (json.JSONDecodeError, TypeError) as e:\n logger.warning(\n \"Failed to repair tool_use input from raw_input: \"\n \"id=%s, name=%s, error=%s\",\n block.get(\"id\"),\n block.get(\"name\"),\n e,\n )\n\n new_blocks.append(block)\n\n if repaired:\n msg.content = new_blocks\n changed = True\n\n result.append(msg)\n\n return result if changed else msgs\n\n\ndef _sanitize_tool_messages(msgs: list) -> list:\n \"\"\"Ensure tool_use/tool_result messages are properly paired and ordered.\n\n Returns the original list unchanged if no fix is needed.\n \"\"\"\n # First, repair tool_use blocks with empty input but valid raw_input\n msgs = _repair_empty_tool_inputs(msgs)\n # Then, remove invalid tool blocks (empty id, None name, etc.)\n msgs = _remove_invalid_tool_blocks(msgs)\n # Finally, remove duplicate tool blocks\n msgs = _dedup_tool_blocks(msgs)\n\n pending: dict[str, int] = {}\n needs_fix = False\n for msg in msgs:\n msg_uses, msg_results = extract_tool_ids(msg)\n for rid in msg_results:\n if pending.get(rid, 0) <= 0:\n needs_fix = True\n break\n pending[rid] -= 1\n if pending[rid] == 0:\n del pending[rid]\n if needs_fix:\n break\n if pending and not msg_results:\n needs_fix = True\n break\n for uid in msg_uses:\n pending[uid] = pending.get(uid, 0) + 1\n if not needs_fix and not pending:\n return msgs\n\n logger.debug(\"Sanitizing tool messages: fixing order/pairing issues\")\n return _remove_unpaired_tool_messages(_reorder_tool_results(msgs))\n\n\ndef _truncate_text(text: str, max_length: int) -> str:\n \"\"\"Truncate text to max length, keeping head and tail portions.\n\n Args:\n text: The text to truncate\n max_length: Maximum allowed length\n\n Returns:\n Truncated text with middle replaced by [...truncated...]\n \"\"\"\n text = str(text) if text else \"\"\n if not text:\n return text\n\n if len(text) <= max_length:\n return text\n\n half_length = max_length // 2\n truncated_chars = len(text) - max_length\n logger.info(\n \"Text truncated: original %d chars, kept head %d + tail %d, \"\n \"removed %d chars.\",\n len(text),\n half_length,\n half_length,\n truncated_chars,\n )\n return (\n f\"{text[:half_length]}\\n\\n[...truncated {truncated_chars} \"\n f\"chars...]\\n\\n{text[-half_length:]}\"\n )\n" }, { "path": "src/copaw/app/__init__.py", "content": "" }, { "path": "src/copaw/app/_app.py", "content": "# -*- coding: utf-8 -*-\n# pylint: disable=redefined-outer-name,unused-argument\nimport mimetypes\nimport os\nimport time\nfrom contextlib import asynccontextmanager\nfrom pathlib import Path\n\nfrom fastapi import FastAPI, HTTPException\nfrom fastapi.middleware.cors import CORSMiddleware\nfrom fastapi.staticfiles import StaticFiles\nfrom fastapi.responses import FileResponse\nfrom agentscope_runtime.engine.app import AgentApp\n\nfrom ..config import load_config # pylint: disable=no-name-in-module\nfrom ..config.utils import get_config_path\nfrom ..constant import DOCS_ENABLED, LOG_LEVEL_ENV, CORS_ORIGINS, WORKING_DIR\nfrom ..__version__ import __version__\nfrom ..utils.logging import setup_logger, add_copaw_file_handler\nfrom .auth import AuthMiddleware\nfrom .routers import router as api_router, create_agent_scoped_router\nfrom .routers.agent_scoped import AgentContextMiddleware\nfrom .routers.voice import voice_router\nfrom ..envs import load_envs_into_environ\nfrom ..providers.provider_manager import ProviderManager\nfrom .multi_agent_manager import MultiAgentManager\nfrom .migration import (\n migrate_legacy_workspace_to_default_agent,\n ensure_default_agent_exists,\n)\n\n# Apply log level on load so reload child process gets same level as CLI.\nlogger = setup_logger(os.environ.get(LOG_LEVEL_ENV, \"info\"))\n\n# Ensure static assets are served with browser-compatible MIME types across\n# platforms (notably Windows may miss .js/.mjs mappings).\nmimetypes.init()\nmimetypes.add_type(\"application/javascript\", \".js\")\nmimetypes.add_type(\"application/javascript\", \".mjs\")\nmimetypes.add_type(\"text/css\", \".css\")\nmimetypes.add_type(\"application/wasm\", \".wasm\")\n\n# Load persisted env vars into os.environ at module import time\n# so they are available before the lifespan starts.\nload_envs_into_environ()\n\n\n# Dynamic runner that selects the correct workspace runner based on request\nclass DynamicMultiAgentRunner:\n \"\"\"Runner wrapper that dynamically routes to the correct workspace runner.\n\n This allows AgentApp to work with multiple agents by inspecting\n the X-Agent-Id header on each request.\n \"\"\"\n\n def __init__(self):\n self.framework_type = \"agentscope\"\n self._multi_agent_manager = None\n\n def set_multi_agent_manager(self, manager):\n \"\"\"Set the MultiAgentManager instance after initialization.\"\"\"\n self._multi_agent_manager = manager\n\n async def _get_workspace_runner(self, request):\n \"\"\"Get the correct workspace runner based on request.\"\"\"\n from .agent_context import get_current_agent_id\n\n # Get agent_id from context (set by middleware or header)\n agent_id = get_current_agent_id()\n\n logger.debug(f\"_get_workspace_runner: agent_id={agent_id}\")\n\n # Get the correct workspace runner\n if not self._multi_agent_manager:\n raise RuntimeError(\"MultiAgentManager not initialized\")\n\n try:\n workspace = await self._multi_agent_manager.get_agent(agent_id)\n logger.debug(\n \"Got workspace: %s, runner: %s\",\n workspace.agent_id,\n workspace.runner,\n )\n return workspace.runner\n except ValueError as e:\n logger.error(f\"Agent not found: {e}\")\n raise\n except Exception as e:\n logger.error(\n f\"Error getting workspace runner: {e}\",\n exc_info=True,\n )\n raise\n\n async def stream_query(self, request, *args, **kwargs):\n \"\"\"Dynamically route to the correct workspace runner.\"\"\"\n logger.debug(\"DynamicMultiAgentRunner.stream_query called\")\n try:\n runner = await self._get_workspace_runner(request)\n logger.debug(f\"Got runner: {runner}, type: {type(runner)}\")\n # Delegate to the actual runner's stream_query generator\n count = 0\n async for item in runner.stream_query(request, *args, **kwargs):\n count += 1\n logger.debug(f\"Yielding item #{count}: {type(item)}\")\n yield item\n logger.debug(f\"stream_query completed, yielded {count} items\")\n except Exception as e:\n logger.error(\n f\"Error in stream_query: {e}\",\n exc_info=True,\n )\n # Yield error message to client\n yield {\n \"error\": str(e),\n \"type\": \"error\",\n }\n\n async def query_handler(self, request, *args, **kwargs):\n \"\"\"Dynamically route to the correct workspace runner.\"\"\"\n runner = await self._get_workspace_runner(request)\n # Delegate to the actual runner's query_handler generator\n async for item in runner.query_handler(request, *args, **kwargs):\n yield item\n\n # Async context manager support for AgentApp lifecycle\n async def __aenter__(self):\n \"\"\"\n No-op context manager entry (workspaces manage their own runners).\n \"\"\"\n return self\n\n async def __aexit__(self, exc_type, exc_val, exc_tb):\n \"\"\"No-op context manager exit (workspaces manage their own runners).\"\"\"\n return None\n\n\n# Use dynamic runner for AgentApp\nrunner = DynamicMultiAgentRunner()\n\nagent_app = AgentApp(\n app_name=\"Friday\",\n app_description=\"A helpful assistant\",\n runner=runner,\n)\n\n\n@asynccontextmanager\nasync def lifespan(\n app: FastAPI,\n): # pylint: disable=too-many-statements,too-many-branches\n startup_start_time = time.time()\n add_copaw_file_handler(WORKING_DIR / \"copaw.log\")\n\n # Auto-register admin from env vars (for automated deployments)\n from .auth import auto_register_from_env\n\n auto_register_from_env()\n\n try:\n from ..utils.telemetry import (\n collect_and_upload_telemetry,\n has_telemetry_been_collected,\n is_telemetry_opted_out,\n )\n\n if not is_telemetry_opted_out(\n WORKING_DIR,\n ) and not has_telemetry_been_collected(WORKING_DIR):\n collect_and_upload_telemetry(WORKING_DIR)\n except Exception:\n logger.debug(\n \"Telemetry collection skipped due to error\",\n exc_info=True,\n )\n\n # --- Multi-agent migration and initialization ---\n logger.info(\"Checking for legacy config migration...\")\n migrate_legacy_workspace_to_default_agent()\n ensure_default_agent_exists()\n\n # --- Multi-agent manager initialization ---\n logger.info(\"Initializing MultiAgentManager...\")\n multi_agent_manager = MultiAgentManager()\n\n # Start all configured agents (handled by manager)\n await multi_agent_manager.start_all_configured_agents()\n\n # --- Model provider manager (non-reloadable, in-memory) ---\n provider_manager = ProviderManager.get_instance()\n\n # Expose to endpoints - multi-agent manager\n app.state.multi_agent_manager = multi_agent_manager\n\n # Connect DynamicMultiAgentRunner to MultiAgentManager\n if isinstance(runner, DynamicMultiAgentRunner):\n runner.set_multi_agent_manager(multi_agent_manager)\n\n # Helper function to get agent instance by ID (async)\n async def _get_agent_by_id(agent_id: str = None):\n \"\"\"Get agent instance by ID, or active agent if not specified.\"\"\"\n if agent_id is None:\n config = load_config(get_config_path())\n agent_id = config.agents.active_agent or \"default\"\n return await multi_agent_manager.get_agent(agent_id)\n\n app.state.get_agent_by_id = _get_agent_by_id\n\n # Global managers (shared across all agents)\n app.state.provider_manager = provider_manager\n\n # Setup approval service with default agent's channel_manager\n default_agent = await multi_agent_manager.get_agent(\"default\")\n if default_agent.channel_manager:\n from .approvals import get_approval_service\n\n get_approval_service().set_channel_manager(\n default_agent.channel_manager,\n )\n\n startup_elapsed = time.time() - startup_start_time\n logger.debug(\n f\"Application startup completed in {startup_elapsed:.3f} seconds\",\n )\n\n try:\n yield\n finally:\n # Stop multi-agent manager (stops all agents and their components)\n multi_agent_mgr = getattr(app.state, \"multi_agent_manager\", None)\n if multi_agent_mgr is not None:\n logger.info(\"Stopping MultiAgentManager...\")\n try:\n await multi_agent_mgr.stop_all()\n except Exception as e:\n logger.error(f\"Error stopping MultiAgentManager: {e}\")\n\n logger.info(\"Application shutdown complete\")\n\n\napp = FastAPI(\n lifespan=lifespan,\n docs_url=\"/docs\" if DOCS_ENABLED else None,\n redoc_url=\"/redoc\" if DOCS_ENABLED else None,\n openapi_url=\"/openapi.json\" if DOCS_ENABLED else None,\n)\n\n# Add agent context middleware for agent-scoped routes\napp.add_middleware(AgentContextMiddleware)\n\napp.add_middleware(AuthMiddleware)\n\n# Apply CORS middleware if CORS_ORIGINS is set\nif CORS_ORIGINS:\n origins = [o.strip() for o in CORS_ORIGINS.split(\",\") if o.strip()]\n app.add_middleware(\n CORSMiddleware,\n allow_origins=origins,\n allow_credentials=True,\n allow_methods=[\"*\"],\n allow_headers=[\"*\"],\n expose_headers=[\"Content-Disposition\"],\n )\n\n\n# Console static dir: env, or copaw package data (console), or cwd.\n_CONSOLE_STATIC_ENV = \"COPAW_CONSOLE_STATIC_DIR\"\n\n\ndef _resolve_console_static_dir() -> str:\n if os.environ.get(_CONSOLE_STATIC_ENV):\n return os.environ[_CONSOLE_STATIC_ENV]\n # Shipped dist lives in copaw package as static data\n pkg_dir = Path(__file__).resolve().parent.parent\n candidate = pkg_dir / \"console\"\n if candidate.is_dir() and (candidate / \"index.html\").exists():\n return str(candidate)\n\n # Fallback to repo data\n repo_dir = pkg_dir.parent.parent\n candidate = repo_dir / \"console\" / \"dist\"\n if candidate.is_dir() and (candidate / \"index.html\").exists():\n return str(candidate)\n\n # Fallback to cwd data\n cwd = Path(os.getcwd())\n for subdir in (\"console/dist\", \"console_dist\"):\n candidate = cwd / subdir\n if candidate.is_dir() and (candidate / \"index.html\").exists():\n return str(candidate)\n\n fallback = cwd / \"console\" / \"dist\"\n logger.warning(\n f\"Console static directory not found. Falling back to '{fallback}'.\",\n )\n return str(fallback)\n\n\n_CONSOLE_STATIC_DIR = _resolve_console_static_dir()\n_CONSOLE_INDEX = (\n Path(_CONSOLE_STATIC_DIR) / \"index.html\" if _CONSOLE_STATIC_DIR else None\n)\nlogger.info(f\"STATIC_DIR: {_CONSOLE_STATIC_DIR}\")\n\n\n@app.get(\"/\")\ndef read_root():\n if _CONSOLE_INDEX and _CONSOLE_INDEX.exists():\n return FileResponse(_CONSOLE_INDEX)\n return {\n \"message\": (\n \"CoPaw Web Console is not available. \"\n \"If you installed CoPaw from source code, please run \"\n \"`npm ci && npm run build` in CoPaw's `console/` \"\n \"directory, and restart CoPaw to enable the \"\n \"web console.\"\n ),\n }\n\n\n@app.get(\"/api/version\")\ndef get_version():\n \"\"\"Return the current CoPaw version.\"\"\"\n return {\"version\": __version__}\n\n\napp.include_router(api_router, prefix=\"/api\")\n\n# Agent-scoped router: /api/agents/{agentId}/chats, etc.\nagent_scoped_router = create_agent_scoped_router()\napp.include_router(agent_scoped_router, prefix=\"/api\")\n\n\napp.include_router(\n agent_app.router,\n prefix=\"/api/agent\",\n tags=[\"agent\"],\n)\n\n# Voice channel: Twilio-facing endpoints at root level (not under /api/).\n# POST /voice/incoming, WS /voice/ws, POST /voice/status-callback\napp.include_router(voice_router, tags=[\"voice\"])\n\n# Console static files and SPA fallback\n# Register these AFTER API routes to ensure proper routing priority\nif os.path.isdir(_CONSOLE_STATIC_DIR):\n _console_path = Path(_CONSOLE_STATIC_DIR)\n\n def _serve_console_index():\n if _CONSOLE_INDEX and _CONSOLE_INDEX.exists():\n return FileResponse(_CONSOLE_INDEX)\n\n raise HTTPException(status_code=404, detail=\"Not Found\")\n\n @app.get(\"/logo.png\")\n def _console_logo():\n f = _console_path / \"logo.png\"\n if f.is_file():\n return FileResponse(f, media_type=\"image/png\")\n raise HTTPException(status_code=404, detail=\"Not Found\")\n\n @app.get(\"/dark-logo.png\")\n def _console_dark_logo():\n f = _console_path / \"dark-logo.png\"\n if f.is_file():\n return FileResponse(f, media_type=\"image/png\")\n raise HTTPException(status_code=404, detail=\"Not Found\")\n\n @app.get(\"/copaw-symbol.svg\")\n def _console_icon():\n f = _console_path / \"copaw-symbol.svg\"\n if f.is_file():\n return FileResponse(f, media_type=\"image/svg+xml\")\n raise HTTPException(status_code=404, detail=\"Not Found\")\n\n @app.get(\"/copaw-dark.png\")\n def _console_dark_icon():\n f = _console_path / \"copaw-dark.png\"\n if f.is_file():\n return FileResponse(f, media_type=\"image/png\")\n raise HTTPException(status_code=404, detail=\"Not Found\")\n\n _assets_dir = _console_path / \"assets\"\n if _assets_dir.is_dir():\n app.mount(\n \"/assets\",\n StaticFiles(directory=str(_assets_dir)),\n name=\"assets\",\n )\n\n @app.get(\"/console\")\n @app.get(\"/console/\")\n @app.get(\"/console/{full_path:path}\")\n def _console_spa_alias(full_path: str = \"\"):\n _ = full_path\n return _serve_console_index()\n\n # SPA fallback: catch-all route for frontend routing\n # Must be registered AFTER all API routes to avoid conflicts\n @app.get(\"/{full_path:path}\")\n def _console_spa(full_path: str):\n # Prevent catching common system/special paths\n if full_path in (\"docs\", \"redoc\", \"openapi.json\"):\n raise HTTPException(status_code=404, detail=\"Not Found\")\n # Skip API routes (should already be matched due to registration order)\n if full_path.startswith(\"api/\") or full_path == \"api\":\n raise HTTPException(status_code=404, detail=\"Not Found\")\n return _serve_console_index()\n" }, { "path": "src/copaw/app/agent_config_watcher.py", "content": "# -*- coding: utf-8 -*-\n\"\"\"Watch agent.json for changes and auto-reload agent components.\n\nThis watcher monitors an agent's workspace/agent.json file for changes\nand automatically reloads channels, heartbeat, and other configurations\nwithout requiring manual restart.\n\"\"\"\n\nfrom __future__ import annotations\n\nimport asyncio\nimport logging\nfrom pathlib import Path\nfrom typing import Any, Optional, TYPE_CHECKING\n\nfrom ..config.config import load_agent_config\nfrom ..config.utils import get_available_channels\n\nif TYPE_CHECKING:\n from ..config.config import ChannelConfig, HeartbeatConfig\n\nlogger = logging.getLogger(__name__)\n\n# How often to poll (seconds)\nDEFAULT_POLL_INTERVAL = 2.0\n\n\ndef _heartbeat_hash(hb: Optional[HeartbeatConfig]) -> int:\n \"\"\"Hash of heartbeat config for change detection.\"\"\"\n if hb is None:\n return hash(\"None\")\n return hash(str(hb.model_dump(mode=\"json\")))\n\n\nclass AgentConfigWatcher:\n \"\"\"Poll agent.json mtime and reload changed configs automatically.\n\n This watcher is agent-scoped and monitors a specific agent's\n workspace/agent.json file for configuration changes.\n \"\"\"\n\n def __init__(\n self,\n agent_id: str,\n workspace_dir: Path,\n channel_manager: Any,\n cron_manager: Any = None,\n poll_interval: float = DEFAULT_POLL_INTERVAL,\n ):\n \"\"\"Initialize agent config watcher.\n\n Args:\n agent_id: Agent ID to monitor\n workspace_dir: Path to agent's workspace directory\n channel_manager: ChannelManager instance for this agent\n cron_manager: CronManager instance for this agent (optional)\n poll_interval: How often to check for changes (seconds)\n \"\"\"\n self._agent_id = agent_id\n self._workspace_dir = workspace_dir\n self._config_path = workspace_dir / \"agent.json\"\n self._channel_manager = channel_manager\n self._cron_manager = cron_manager\n self._poll_interval = poll_interval\n self._task: Optional[asyncio.Task] = None\n\n # Snapshot of the last known config (for diffing)\n self._last_channels: Optional[ChannelConfig] = None\n self._last_channels_hash: Optional[int] = None\n self._last_heartbeat_hash: Optional[int] = None\n # mtime of agent.json at last check\n self._last_mtime: float = 0.0\n\n async def start(self) -> None:\n \"\"\"Take initial snapshot and start the polling task.\"\"\"\n self._snapshot()\n self._task = asyncio.create_task(\n self._poll_loop(),\n name=f\"agent_config_watcher_{self._agent_id}\",\n )\n logger.info(\n f\"AgentConfigWatcher started for agent {self._agent_id} \"\n f\"(poll={self._poll_interval}s, path={self._config_path})\",\n )\n\n async def stop(self) -> None:\n \"\"\"Stop the polling task.\"\"\"\n if self._task:\n self._task.cancel()\n try:\n await self._task\n except asyncio.CancelledError:\n pass\n self._task = None\n logger.info(f\"AgentConfigWatcher stopped for agent {self._agent_id}\")\n\n # ------------------------------------------------------------------\n # Internal methods\n # ------------------------------------------------------------------\n\n def _snapshot(self) -> None:\n \"\"\"Load current agent config; record mtime and hashes.\"\"\"\n try:\n self._last_mtime = self._config_path.stat().st_mtime\n except FileNotFoundError:\n self._last_mtime = 0.0\n\n try:\n agent_config = load_agent_config(self._agent_id)\n if agent_config.channels:\n self._last_channels = agent_config.channels.model_copy(\n deep=True,\n )\n self._last_channels_hash = self._channels_hash(\n agent_config.channels,\n )\n else:\n self._last_channels = None\n self._last_channels_hash = None\n\n self._last_heartbeat_hash = _heartbeat_hash(\n agent_config.heartbeat,\n )\n except Exception:\n logger.exception(\n f\"AgentConfigWatcher: failed to load initial config \"\n f\"for agent {self._agent_id}\",\n )\n self._last_channels = None\n self._last_channels_hash = None\n self._last_heartbeat_hash = None\n\n @staticmethod\n def _channels_hash(channels: ChannelConfig) -> int:\n \"\"\"Fast hash of channels section for quick change detection.\"\"\"\n return hash(str(channels.model_dump(mode=\"json\")))\n\n @staticmethod\n def _channel_dump(ch: Any) -> Any:\n \"\"\"Return JSON-serializable dict for channel config, or None.\"\"\"\n if ch is None:\n return None\n if isinstance(ch, dict):\n return ch\n if hasattr(ch, \"model_dump\"):\n return ch.model_dump(mode=\"json\")\n return None\n\n async def _reload_one_channel(\n self,\n name: str,\n new_ch: Any,\n new_channels: ChannelConfig,\n old_ch: Any,\n ) -> None:\n \"\"\"Reload a single channel; on failure revert new_channels entry.\"\"\"\n try:\n old_channel = await self._channel_manager.get_channel(name)\n if old_channel is None:\n logger.warning(\n f\"AgentConfigWatcher ({self._agent_id}): \"\n f\"channel '{name}' not found, skip\",\n )\n return\n new_channel = old_channel.clone(new_ch)\n await self._channel_manager.replace_channel(new_channel)\n logger.info(\n f\"AgentConfigWatcher ({self._agent_id}): \"\n f\"channel '{name}' reloaded\",\n )\n except Exception:\n logger.exception(\n f\"AgentConfigWatcher ({self._agent_id}): \"\n f\"failed to reload channel '{name}'\",\n )\n setattr(new_channels, name, old_ch if old_ch else new_ch)\n\n async def _apply_channel_changes(self, agent_config: Any) -> None:\n \"\"\"Diff channels and reload changed ones; update snapshot.\"\"\"\n if not agent_config.channels:\n return\n\n new_hash = self._channels_hash(agent_config.channels)\n if new_hash == self._last_channels_hash:\n return\n\n new_channels = agent_config.channels\n old_channels = self._last_channels\n extra_new = getattr(new_channels, \"__pydantic_extra__\", None) or {}\n extra_old = (\n getattr(old_channels, \"__pydantic_extra__\", None)\n if old_channels\n else {}\n )\n\n for name in get_available_channels():\n new_ch = getattr(new_channels, name, None) or extra_new.get(name)\n old_ch = (\n getattr(old_channels, name, None) or extra_old.get(name)\n if old_channels\n else None\n )\n if new_ch is None:\n continue\n new_dump = self._channel_dump(new_ch)\n old_dump = self._channel_dump(old_ch)\n if new_dump is not None and new_dump == old_dump:\n continue\n logger.info(\n f\"AgentConfigWatcher ({self._agent_id}): \"\n f\"channel '{name}' config changed, reloading\",\n )\n await self._reload_one_channel(name, new_ch, new_channels, old_ch)\n\n self._last_channels = new_channels.model_copy(deep=True)\n self._last_channels_hash = self._channels_hash(new_channels)\n\n async def _apply_heartbeat_change(self, agent_config: Any) -> None:\n \"\"\"Update heartbeat hash and reschedule if changed.\"\"\"\n new_hb_hash = _heartbeat_hash(agent_config.heartbeat)\n if (\n self._cron_manager is not None\n and new_hb_hash != self._last_heartbeat_hash\n ):\n self._last_heartbeat_hash = new_hb_hash\n try:\n await self._cron_manager.reschedule_heartbeat()\n logger.info(\n f\"AgentConfigWatcher ({self._agent_id}): \"\n f\"heartbeat rescheduled\",\n )\n except Exception:\n logger.exception(\n f\"AgentConfigWatcher ({self._agent_id}): \"\n f\"failed to reschedule heartbeat\",\n )\n else:\n self._last_heartbeat_hash = new_hb_hash\n\n async def _poll_loop(self) -> None:\n \"\"\"Main polling loop.\"\"\"\n while True:\n try:\n await asyncio.sleep(self._poll_interval)\n await self._check()\n except Exception:\n logger.exception(\n f\"AgentConfigWatcher ({self._agent_id}): \"\n f\"poll iteration failed\",\n )\n\n async def _check(self) -> None:\n \"\"\"Check for config changes and reload if needed.\"\"\"\n try:\n mtime = self._config_path.stat().st_mtime\n except FileNotFoundError:\n return\n\n if mtime == self._last_mtime:\n return\n\n self._last_mtime = mtime\n\n try:\n agent_config = load_agent_config(self._agent_id)\n except Exception:\n logger.exception(\n f\"AgentConfigWatcher ({self._agent_id}): \"\n f\"failed to parse agent.json\",\n )\n return\n\n # Apply changes\n if self._channel_manager:\n await self._apply_channel_changes(agent_config)\n if self._cron_manager:\n await self._apply_heartbeat_change(agent_config)\n" }, { "path": "src/copaw/app/agent_context.py", "content": "# -*- coding: utf-8 -*-\n\"\"\"Agent context utilities for multi-agent support.\n\nProvides utilities to get the correct agent instance for each request.\n\"\"\"\nfrom contextvars import ContextVar\nfrom typing import Optional, TYPE_CHECKING\nfrom fastapi import Request\nfrom .multi_agent_manager import MultiAgentManager\nfrom ..config.utils import load_config\n\nif TYPE_CHECKING:\n from .workspace import Workspace\n\n# Context variable to store current agent ID across async calls\n_current_agent_id: ContextVar[Optional[str]] = ContextVar(\n \"current_agent_id\",\n default=None,\n)\n\n\nasync def get_agent_for_request(\n request: Request,\n agent_id: Optional[str] = None,\n) -> \"Workspace\":\n \"\"\"Get agent workspace for current request.\n\n Priority:\n 1. agent_id parameter (explicit override)\n 2. request.state.agent_id (from agent-scoped router)\n 3. X-Agent-Id header (from frontend)\n 4. Active agent from config\n\n Args:\n request: FastAPI request object\n agent_id: Agent ID override (highest priority)\n\n Returns:\n Workspace for the specified or active agent\n\n Raises:\n HTTPException: If agent not found\n \"\"\"\n from fastapi import HTTPException\n\n # Determine which agent to use\n target_agent_id = agent_id\n\n # Check request.state.agent_id (set by agent-scoped router)\n if not target_agent_id and hasattr(request.state, \"agent_id\"):\n target_agent_id = request.state.agent_id\n\n # Check X-Agent-Id header\n if not target_agent_id:\n target_agent_id = request.headers.get(\"X-Agent-Id\")\n\n if not target_agent_id:\n # Fallback to active agent from config\n config = load_config()\n target_agent_id = config.agents.active_agent or \"default\"\n\n # Get MultiAgentManager\n if not hasattr(request.app.state, \"multi_agent_manager\"):\n raise HTTPException(\n status_code=500,\n detail=\"MultiAgentManager not initialized\",\n )\n\n manager: MultiAgentManager = request.app.state.multi_agent_manager\n\n try:\n workspace = await manager.get_agent(target_agent_id)\n if not workspace:\n raise HTTPException(\n status_code=404,\n detail=f\"Agent '{target_agent_id}' not found\",\n )\n return workspace\n except Exception as e:\n raise HTTPException(\n status_code=500,\n detail=f\"Failed to get agent: {str(e)}\",\n ) from e\n\n\ndef get_active_agent_id() -> str:\n \"\"\"Get current active agent ID from config.\n\n Returns:\n Active agent ID, defaults to \"default\"\n \"\"\"\n try:\n config = load_config()\n return config.agents.active_agent or \"default\"\n except Exception:\n return \"default\"\n\n\ndef set_current_agent_id(agent_id: str) -> None:\n \"\"\"Set current agent ID in context.\n\n Args:\n agent_id: Agent ID to set\n \"\"\"\n _current_agent_id.set(agent_id)\n\n\ndef get_current_agent_id() -> str:\n \"\"\"Get current agent ID from context or config fallback.\n\n Returns:\n Current agent ID, defaults to active agent or \"default\"\n \"\"\"\n agent_id = _current_agent_id.get()\n if agent_id:\n return agent_id\n return get_active_agent_id()\n" }, { "path": "src/copaw/app/approvals/__init__.py", "content": "# -*- coding: utf-8 -*-\n\"\"\"Approval service exports.\"\"\"\n\nfrom .service import (\n ApprovalService,\n PendingApproval,\n get_approval_service,\n)\n\n__all__ = [\n \"ApprovalService\",\n \"PendingApproval\",\n \"get_approval_service\",\n]\n" }, { "path": "src/copaw/app/approvals/service.py", "content": "# -*- coding: utf-8 -*-\n\"\"\"Approval service for sensitive tool execution.\n\nThe ``ApprovalService`` is the single central store for pending /\ncompleted approval records. Approval is granted exclusively via\nthe ``/daemon approve`` command in the chat interface.\n\"\"\"\nfrom __future__ import annotations\n\nimport asyncio\nimport logging\nimport time\nimport uuid\nfrom dataclasses import dataclass, field\nfrom typing import TYPE_CHECKING, Any\n\nfrom ...security.tool_guard.approval import ApprovalDecision\n\nif TYPE_CHECKING:\n from ...security.tool_guard.models import ToolGuardResult\n\nlogger = logging.getLogger(__name__)\n\n_GC_MAX_AGE_SECONDS = 3600.0\n_GC_MAX_COMPLETED = 500\n_GC_PENDING_MAX_AGE_SECONDS = 1800.0\n_GC_MAX_PENDING = 200\n\n\n# ------------------------------------------------------------------\n# Data model\n# ------------------------------------------------------------------\n\n\n@dataclass\nclass PendingApproval:\n \"\"\"In-memory record for one pending approval.\"\"\"\n\n request_id: str\n session_id: str\n user_id: str\n channel: str\n tool_name: str\n created_at: float\n future: asyncio.Future[ApprovalDecision]\n status: str = \"pending\"\n resolved_at: float | None = None\n result_summary: str = \"\"\n findings_count: int = 0\n extra: dict[str, Any] = field(default_factory=dict)\n\n\n# ------------------------------------------------------------------\n# Service\n# ------------------------------------------------------------------\n\n\nclass ApprovalService:\n \"\"\"Central approval service.\n\n Tracks pending and completed approval records. Approval is\n resolved via ``/daemon approve`` (see ``runner.py`` and\n ``daemon_commands.py``).\n \"\"\"\n\n def __init__(self) -> None:\n self._lock = asyncio.Lock()\n self._pending: dict[str, PendingApproval] = {}\n self._completed: dict[str, PendingApproval] = {}\n self._channel_manager: Any | None = None\n\n def set_channel_manager(self, channel_manager: Any) -> None:\n \"\"\"Store a reference to the channel manager for push notifications.\"\"\"\n self._channel_manager = channel_manager\n\n # ------------------------------------------------------------------\n # Core approval lifecycle\n # ------------------------------------------------------------------\n\n async def create_pending(\n self,\n *,\n session_id: str,\n user_id: str,\n channel: str,\n tool_name: str,\n result: \"ToolGuardResult\",\n extra: dict[str, Any] | None = None,\n ) -> PendingApproval:\n \"\"\"Create a pending approval record and return it.\"\"\"\n from ...security.tool_guard.approval import format_findings_summary\n\n request_id = str(uuid.uuid4())\n loop = asyncio.get_running_loop()\n\n pending = PendingApproval(\n request_id=request_id,\n session_id=session_id,\n user_id=user_id,\n channel=channel,\n tool_name=tool_name,\n created_at=time.time(),\n future=loop.create_future(),\n result_summary=format_findings_summary(result),\n findings_count=result.findings_count,\n extra=dict(extra or {}),\n )\n\n async with self._lock:\n self._pending[request_id] = pending\n self._gc_pending_locked()\n self._gc_completed_locked()\n\n return pending\n\n async def resolve_request(\n self,\n request_id: str,\n decision: ApprovalDecision,\n ) -> PendingApproval | None:\n \"\"\"Resolve one pending approval request.\"\"\"\n async with self._lock:\n pending = self._pending.pop(request_id, None)\n if pending is None:\n return self._completed.get(request_id)\n\n pending.status = decision.value\n pending.resolved_at = time.time()\n self._completed[request_id] = pending\n self._gc_completed_locked()\n\n if not pending.future.done():\n pending.future.set_result(decision)\n\n return pending\n\n async def get_request(self, request_id: str) -> PendingApproval | None:\n \"\"\"Get a request by id whether pending or already resolved.\"\"\"\n async with self._lock:\n return self._pending.get(request_id) or self._completed.get(\n request_id,\n )\n\n async def get_pending_by_session(\n self,\n session_id: str,\n ) -> PendingApproval | None:\n \"\"\"Return the most recent pending approval for *session_id*.\"\"\"\n async with self._lock:\n for pending in reversed(list(self._pending.values())):\n if (\n pending.session_id == session_id\n and pending.status == \"pending\"\n ):\n return pending\n return None\n\n async def consume_approval(\n self,\n session_id: str,\n tool_name: str,\n tool_params: dict[str, Any] | None = None,\n ) -> bool:\n \"\"\"Check and consume a one-shot tool approval.\n\n If *tool_name* was recently approved via ``/daemon approve``\n for *session_id*, remove the completed record and return\n ``True`` so the caller can skip the guard check.\n\n When *tool_params* is given, the approved call's stored\n parameters are compared. A mismatch causes the approval\n to be rejected (returns ``False``), preventing an approved\n ``rm foo.txt`` from being used to execute ``rm -rf /``.\n \"\"\"\n async with self._lock:\n for key, completed in list(self._completed.items()):\n if (\n completed.session_id == session_id\n and completed.tool_name == tool_name\n and completed.status == \"approved\"\n ):\n if tool_params is not None:\n approved_call = completed.extra.get(\n \"tool_call\",\n {},\n )\n approved_params = approved_call.get(\n \"input\",\n {},\n )\n if approved_params != tool_params:\n logger.warning(\n \"Tool guard: params mismatch for \"\n \"'%s' (session %s), rejecting \"\n \"stale approval\",\n tool_name,\n session_id[:8],\n )\n del self._completed[key]\n return False\n del self._completed[key]\n return True\n return False\n\n # ------------------------------------------------------------------\n # Garbage collection\n # ------------------------------------------------------------------\n\n def _gc_pending_locked(self) -> None:\n \"\"\"Evict stale pending records whose futures were never resolved.\n\n Caller must hold ``_lock``.\n \"\"\"\n now = time.time()\n expired = [\n k\n for k, v in self._pending.items()\n if now - v.created_at > _GC_PENDING_MAX_AGE_SECONDS\n ]\n for k in expired:\n pending = self._pending.pop(k)\n if not pending.future.done():\n pending.future.set_result(ApprovalDecision.TIMEOUT)\n pending.status = \"timeout\"\n pending.resolved_at = now\n self._completed[k] = pending\n\n overflow = len(self._pending) - _GC_MAX_PENDING\n if overflow <= 0:\n return\n ordered = sorted(\n self._pending.items(),\n key=lambda item: item[1].created_at,\n )\n for key, pending in ordered[:overflow]:\n del self._pending[key]\n if not pending.future.done():\n pending.future.set_result(ApprovalDecision.TIMEOUT)\n pending.status = \"timeout\"\n pending.resolved_at = now\n self._completed[key] = pending\n\n def _gc_completed_locked(self) -> None:\n \"\"\"Remove stale/overflow completed records.\n\n Caller must hold ``_lock``.\n \"\"\"\n now = time.time()\n expired = [\n k\n for k, v in self._completed.items()\n if v.resolved_at and now - v.resolved_at > _GC_MAX_AGE_SECONDS\n ]\n for k in expired:\n del self._completed[k]\n\n # Still over cap: evict oldest completed records first.\n overflow = len(self._completed) - _GC_MAX_COMPLETED\n if overflow <= 0:\n return\n ordered = sorted(\n self._completed.items(),\n key=lambda item: item[1].resolved_at or item[1].created_at,\n )\n for key, _pending in ordered[:overflow]:\n del self._completed[key]\n\n\n# ------------------------------------------------------------------\n# Singleton\n# ------------------------------------------------------------------\n\n_approval_service: ApprovalService | None = None\n\n\ndef get_approval_service() -> ApprovalService:\n \"\"\"Return the process-wide approval service singleton.\"\"\"\n global _approval_service\n if _approval_service is None:\n _approval_service = ApprovalService()\n return _approval_service\n" }, { "path": "src/copaw/app/auth.py", "content": "# -*- coding: utf-8 -*-\n\"\"\"Authentication module: password hashing, JWT tokens, and FastAPI middleware.\n\nLogin is disabled by default and only enabled when the environment\nvariable ``COPAW_AUTH_ENABLED`` is set to a truthy value (``true``,\n``1``, ``yes``). Credentials are created through a web-based\nregistration flow rather than environment variables, so that agents\nrunning inside the process cannot read plaintext passwords.\n\nSingle-user design: only one account can be registered. If the user\nforgets their password, delete ``auth.json`` from ``SECRET_DIR`` and\nrestart the service to re-register.\n\nUses only Python stdlib (hashlib, hmac, secrets) to avoid adding new\ndependencies. The password is stored as a salted SHA-256 hash in\n``auth.json`` under ``SECRET_DIR``.\n\"\"\"\nfrom __future__ import annotations\n\nimport hashlib\nimport hmac\nimport json\nimport logging\nimport os\nimport secrets\nimport time\nfrom typing import Optional\n\nfrom fastapi import Request, Response\nfrom starlette.middleware.base import BaseHTTPMiddleware\n\nfrom ..constant import SECRET_DIR\n\nlogger = logging.getLogger(__name__)\n\nAUTH_FILE = SECRET_DIR / \"auth.json\"\n\n# Token validity: 7 days\nTOKEN_EXPIRY_SECONDS = 7 * 24 * 3600\n\n# Paths that do NOT require authentication\n_PUBLIC_PATHS: frozenset[str] = frozenset(\n {\n \"/api/auth/login\",\n \"/api/auth/status\",\n \"/api/auth/register\",\n \"/api/version\",\n },\n)\n\n# Prefixes that do NOT require authentication (static assets)\n_PUBLIC_PREFIXES: tuple[str, ...] = (\n \"/assets/\",\n \"/logo.png\",\n \"/copaw-symbol.svg\",\n)\n\n\n# ---------------------------------------------------------------------------\n# Helpers (reuse SECRET_DIR patterns from envs/store.py)\n# ---------------------------------------------------------------------------\n\n\ndef _chmod_best_effort(path, mode: int) -> None:\n try:\n os.chmod(path, mode)\n except OSError:\n pass\n\n\ndef _prepare_secret_parent(path) -> None:\n path.parent.mkdir(parents=True, exist_ok=True)\n _chmod_best_effort(path.parent, 0o700)\n\n\n# ---------------------------------------------------------------------------\n# Password hashing (salted SHA-256, no external deps)\n# ---------------------------------------------------------------------------\n\n\ndef _hash_password(\n password: str,\n salt: Optional[str] = None,\n) -> tuple[str, str]:\n \"\"\"Hash *password* with *salt*. Returns ``(hash_hex, salt_hex)``.\"\"\"\n if salt is None:\n salt = secrets.token_hex(16)\n h = hashlib.sha256((salt + password).encode(\"utf-8\")).hexdigest()\n return h, salt\n\n\ndef verify_password(password: str, stored_hash: str, salt: str) -> bool:\n \"\"\"Verify *password* against a stored hash.\"\"\"\n h, _ = _hash_password(password, salt)\n return hmac.compare_digest(h, stored_hash)\n\n\n# ---------------------------------------------------------------------------\n# Token generation / verification (HMAC-SHA256, no PyJWT needed)\n# ---------------------------------------------------------------------------\n\n\ndef _get_jwt_secret() -> str:\n \"\"\"Return the signing secret, creating one if absent.\"\"\"\n data = _load_auth_data()\n secret = data.get(\"jwt_secret\", \"\")\n if not secret:\n secret = secrets.token_hex(32)\n data[\"jwt_secret\"] = secret\n _save_auth_data(data)\n return secret\n\n\ndef create_token(username: str) -> str:\n \"\"\"Create an HMAC-signed token: ``base64(payload).signature``.\"\"\"\n import base64\n\n secret = _get_jwt_secret()\n payload = json.dumps(\n {\n \"sub\": username,\n \"exp\": int(time.time()) + TOKEN_EXPIRY_SECONDS,\n \"iat\": int(time.time()),\n },\n )\n payload_b64 = base64.urlsafe_b64encode(payload.encode()).decode()\n sig = hmac.new(\n secret.encode(),\n payload_b64.encode(),\n hashlib.sha256,\n ).hexdigest()\n return f\"{payload_b64}.{sig}\"\n\n\ndef verify_token(token: str) -> Optional[str]:\n \"\"\"Verify *token*, return username if valid, ``None`` otherwise.\"\"\"\n import base64\n\n try:\n parts = token.split(\".\", 1)\n if len(parts) != 2:\n return None\n payload_b64, sig = parts\n secret = _get_jwt_secret()\n expected_sig = hmac.new(\n secret.encode(),\n payload_b64.encode(),\n hashlib.sha256,\n ).hexdigest()\n if not hmac.compare_digest(sig, expected_sig):\n return None\n payload = json.loads(base64.urlsafe_b64decode(payload_b64))\n if payload.get(\"exp\", 0) < time.time():\n return None\n return payload.get(\"sub\")\n except (json.JSONDecodeError, KeyError, ValueError, TypeError) as exc:\n logger.debug(\"Token verification failed: %s\", exc)\n return None\n\n\n# ---------------------------------------------------------------------------\n# Auth data persistence (auth.json in SECRET_DIR)\n# ---------------------------------------------------------------------------\n\n\ndef _load_auth_data() -> dict:\n \"\"\"Load ``auth.json`` from ``SECRET_DIR``.\n\n Returns the parsed dict, or a sentinel with ``_auth_load_error``\n set to ``True`` when the file exists but cannot be read/parsed so\n that callers can fail closed instead of silently bypassing auth.\n \"\"\"\n if AUTH_FILE.is_file():\n try:\n with open(AUTH_FILE, \"r\", encoding=\"utf-8\") as f:\n return json.load(f)\n except (json.JSONDecodeError, OSError) as exc:\n logger.error(\"Failed to load auth file %s: %s\", AUTH_FILE, exc)\n return {\"_auth_load_error\": True}\n return {}\n\n\ndef _save_auth_data(data: dict) -> None:\n \"\"\"Save ``auth.json`` to ``SECRET_DIR`` with restrictive permissions.\"\"\"\n _prepare_secret_parent(AUTH_FILE)\n with open(AUTH_FILE, \"w\", encoding=\"utf-8\") as f:\n json.dump(data, f, indent=2, ensure_ascii=False)\n _chmod_best_effort(AUTH_FILE, 0o600)\n\n\ndef is_auth_enabled() -> bool:\n \"\"\"Check whether authentication is enabled via environment variable.\n\n Returns ``True`` when ``COPAW_AUTH_ENABLED`` is set to a truthy\n value (``true``, ``1``, ``yes``). The presence of a registered\n user is checked separately by the middleware so that the first\n user can still reach the registration page.\n \"\"\"\n env_flag = os.environ.get(\"COPAW_AUTH_ENABLED\", \"\").strip().lower()\n return env_flag in (\"true\", \"1\", \"yes\")\n\n\ndef has_registered_users() -> bool:\n \"\"\"Return ``True`` if a user has been registered.\"\"\"\n data = _load_auth_data()\n return bool(data.get(\"user\"))\n\n\n# ---------------------------------------------------------------------------\n# Registration (single-user)\n# ---------------------------------------------------------------------------\n\n\ndef register_user(username: str, password: str) -> Optional[str]:\n \"\"\"Register the single user account.\n\n Returns a token on success, ``None`` if a user already exists.\n \"\"\"\n data = _load_auth_data()\n\n # Only one user allowed\n if data.get(\"user\"):\n return None\n\n pw_hash, salt = _hash_password(password)\n data[\"user\"] = {\n \"username\": username,\n \"password_hash\": pw_hash,\n \"password_salt\": salt,\n }\n\n # Ensure jwt_secret exists\n if not data.get(\"jwt_secret\"):\n data[\"jwt_secret\"] = secrets.token_hex(32)\n\n _save_auth_data(data)\n logger.info(\"User '%s' registered\", username)\n return create_token(username)\n\n\ndef auto_register_from_env() -> None:\n \"\"\"Auto-register admin user from environment variables.\n\n Called once during application startup. If ``COPAW_AUTH_ENABLED``\n is truthy and both ``COPAW_AUTH_USERNAME`` and ``COPAW_AUTH_PASSWORD``\n are set, the admin account is created automatically — useful for\n Docker, Kubernetes, server-panel, and other automated deployments\n where interactive web registration is not practical.\n\n Skips silently when:\n - authentication is not enabled\n - a user has already been registered\n - either env var is missing or empty\n \"\"\"\n if not is_auth_enabled():\n return\n if has_registered_users():\n return\n\n username = os.environ.get(\"COPAW_AUTH_USERNAME\", \"\").strip()\n password = os.environ.get(\"COPAW_AUTH_PASSWORD\", \"\").strip()\n if not username or not password:\n return\n\n token = register_user(username, password)\n if token:\n logger.info(\n \"Auto-registered user '%s' from environment variables\",\n username,\n )\n\n\n# ---------------------------------------------------------------------------\n# Authentication\n# ---------------------------------------------------------------------------\n\n\ndef authenticate(username: str, password: str) -> Optional[str]:\n \"\"\"Authenticate *username* / *password*. Returns a token if valid.\"\"\"\n data = _load_auth_data()\n user = data.get(\"user\")\n if not user:\n return None\n if user.get(\"username\") != username:\n return None\n stored_hash = user.get(\"password_hash\", \"\")\n stored_salt = user.get(\"password_salt\", \"\")\n if (\n stored_hash\n and stored_salt\n and verify_password(password, stored_hash, stored_salt)\n ):\n return create_token(username)\n return None\n\n\n# ---------------------------------------------------------------------------\n# FastAPI middleware\n# ---------------------------------------------------------------------------\n\n\nclass AuthMiddleware(BaseHTTPMiddleware):\n \"\"\"Middleware that checks Bearer token on protected routes.\"\"\"\n\n async def dispatch(\n self,\n request: Request,\n call_next,\n ) -> Response:\n \"\"\"Check Bearer token on protected API routes; skip public paths.\"\"\"\n if self._should_skip_auth(request):\n return await call_next(request)\n\n token = self._extract_token(request)\n if not token:\n return Response(\n content=json.dumps({\"detail\": \"Not authenticated\"}),\n status_code=401,\n media_type=\"application/json\",\n )\n\n user = verify_token(token)\n if user is None:\n return Response(\n content=json.dumps(\n {\"detail\": \"Invalid or expired token\"},\n ),\n status_code=401,\n media_type=\"application/json\",\n )\n\n request.state.user = user\n return await call_next(request)\n\n @staticmethod\n def _should_skip_auth(request: Request) -> bool:\n \"\"\"Return ``True`` when the request does not require auth.\"\"\"\n if not is_auth_enabled() or not has_registered_users():\n return True\n\n path = request.url.path\n\n if request.method == \"OPTIONS\":\n return True\n\n if path in _PUBLIC_PATHS or any(\n path.startswith(p) for p in _PUBLIC_PREFIXES\n ):\n return True\n\n # Only protect /api/ routes\n if not path.startswith(\"/api/\"):\n return True\n\n # Allow localhost requests without auth (CLI runs locally)\n client_host = request.client.host if request.client else \"\"\n return client_host in (\"127.0.0.1\", \"::1\")\n\n @staticmethod\n def _extract_token(request: Request) -> Optional[str]:\n \"\"\"Extract Bearer token from header or WebSocket query param.\"\"\"\n auth_header = request.headers.get(\"Authorization\", \"\")\n if auth_header.startswith(\"Bearer \"):\n return auth_header[7:]\n if \"upgrade\" in request.headers.get(\"connection\", \"\").lower():\n return request.query_params.get(\"token\")\n return None\n" }, { "path": "src/copaw/app/channels/__init__.py", "content": "# -*- coding: utf-8 -*-\n# ChannelManager is provided by __getattr__ (lazy-loaded).\n# pylint: disable=undefined-all-variable\n__all__ = [\"ChannelManager\"]\n\n\ndef __getattr__(name: str):\n \"\"\"Lazy-load ChannelManager to avoid pulling feishu/lark_oapi on CLI.\"\"\"\n if name == \"ChannelManager\":\n from .manager import ChannelManager\n\n return ChannelManager\n raise AttributeError(f\"module {__name__!r} has no attribute {name!r}\")\n" }, { "path": "src/copaw/app/channels/base.py", "content": "# -*- coding: utf-8 -*-\n# pylint: disable=too-many-branches,too-many-statements,unused-argument\n# pylint: disable=too-many-public-methods,unnecessary-pass\n\"\"\"\nBase Channel: bound to AgentRequest/AgentResponse, unified by process.\n\"\"\"\nfrom __future__ import annotations\n\nimport asyncio\nimport logging\nfrom abc import ABC\nfrom typing import (\n Optional,\n Dict,\n Any,\n List,\n Union,\n AsyncIterator,\n Callable,\n TYPE_CHECKING,\n)\n\nfrom agentscope_runtime.engine.schemas.agent_schemas import (\n RunStatus,\n ContentType,\n TextContent,\n ImageContent,\n VideoContent,\n AudioContent,\n FileContent,\n RefusalContent,\n MessageType,\n)\n\nfrom .renderer import MessageRenderer, RenderStyle\nfrom .schema import ChannelType\nfrom ...config.utils import load_config\n\n# Optional callback to enqueue payload (set by manager)\nEnqueueCallback = Optional[Callable[[Any], None]]\n\n# Called when a user-originated reply was sent (channel, user_id, session_id)\nOnReplySent = Optional[Callable[[str, str, str], None]]\n\nlogger = logging.getLogger(__name__)\n\nif TYPE_CHECKING:\n from agentscope_runtime.engine.schemas.agent_schemas import (\n AgentRequest,\n AgentResponse,\n Event,\n )\n\n# process: accepts AgentRequest, streams Event\n# (including message events with status completed)\nProcessHandler = Callable[[Any], AsyncIterator[\"Event\"]]\n\n# Outgoing part = runtime content types (no Dict[str, Any])\nOutgoingContentPart = Union[\n TextContent,\n ImageContent,\n VideoContent,\n AudioContent,\n FileContent,\n RefusalContent,\n]\n\n\nclass BaseChannel(ABC):\n \"\"\"Base for all channels. Queue lives in ChannelManager; channel defines\n how to consume via consume_one().\n \"\"\"\n\n channel: ChannelType\n\n # If True, manager creates a queue and consumer loop for this channel.\n uses_manager_queue: bool = True\n\n def __init__(\n self,\n process: ProcessHandler,\n on_reply_sent: OnReplySent = None,\n show_tool_details: bool = True,\n filter_tool_messages: bool = False,\n filter_thinking: bool = False,\n dm_policy: str = \"open\",\n group_policy: str = \"open\",\n allow_from: Optional[list] = None,\n deny_message: str = \"\",\n require_mention: bool = False,\n ):\n self._process = process\n self._on_reply_sent = on_reply_sent\n self._show_tool_details = show_tool_details\n self._filter_tool_messages = filter_tool_messages\n self._filter_thinking = filter_thinking\n self.dm_policy = dm_policy or \"open\"\n self.group_policy = group_policy or \"open\"\n self.allow_from = set(allow_from or [])\n self.deny_message = deny_message or \"\"\n self.require_mention = require_mention\n self._enqueue: EnqueueCallback = None\n cfg = load_config()\n internal_tools = frozenset(\n name\n for name, tc in cfg.tools.builtin_tools.items()\n if not tc.display_to_user\n )\n self._render_style = RenderStyle(\n show_tool_details=show_tool_details,\n filter_tool_messages=filter_tool_messages,\n filter_thinking=filter_thinking,\n internal_tools=internal_tools,\n )\n self._renderer = MessageRenderer(self._render_style)\n self._http: Optional[Any] = None\n # Debounce: content from messages that had no text; merged when text\n # arrives. Key = session_id.\n self._pending_content_by_session: Dict[str, List[Any]] = {}\n # Time debounce: merge native payloads within _debounce_seconds.\n # Set > 0 in subclass (e.g. 0.3). Key = get_debounce_key(payload).\n self._debounce_seconds: float = 0.0\n self._debounce_pending: Dict[str, List[Any]] = {}\n self._debounce_timers: Dict[str, asyncio.Task[None]] = {}\n\n def _is_native_payload(self, payload: Any) -> bool:\n \"\"\"True if payload is a native dict that can be time-debounced.\"\"\"\n return isinstance(payload, dict) and \"content_parts\" in payload\n\n def get_debounce_key(self, payload: Any) -> str:\n \"\"\"\n Key for time debounce (same key = same conversation).\n Delegates to ``resolve_session_id`` so every channel gets\n session-scoped isolation automatically.\n \"\"\"\n if isinstance(payload, dict):\n sender_id = payload.get(\"sender_id\") or \"\"\n meta = payload.get(\"meta\") or {}\n return payload.get(\"session_id\") or self.resolve_session_id(\n sender_id,\n meta,\n )\n return getattr(payload, \"session_id\", \"\") or \"\"\n\n def merge_native_items(self, items: List[Any]) -> Any:\n \"\"\"\n Merge multiple native payloads into one. Override for\n channel-specific merge (e.g. meta keys). Default: concat\n content_parts, merge meta (reply_future, reply_loop, etc.).\n \"\"\"\n if not items:\n return None\n first = items[0] if isinstance(items[0], dict) else {}\n merged_parts: List[Any] = []\n merged_meta: Dict[str, Any] = dict(first.get(\"meta\") or {})\n for it in items:\n p = it if isinstance(it, dict) else {}\n merged_parts.extend(p.get(\"content_parts\") or [])\n m = p.get(\"meta\") or {}\n for k in (\n \"reply_future\",\n \"reply_loop\",\n \"incoming_message\",\n \"conversation_id\",\n \"message_id\",\n ):\n if k in m:\n merged_meta[k] = m[k]\n return {\n \"channel_id\": first.get(\"channel_id\") or self.channel,\n \"sender_id\": first.get(\"sender_id\") or \"\",\n \"content_parts\": merged_parts,\n \"meta\": merged_meta,\n }\n\n def merge_requests(self, requests: List[Any]) -> Any:\n \"\"\"\n Merge multiple AgentRequest payloads (same session) into one.\n Used when manager drains same-session queue: concatenate\n input[0].content from all, keep first request's meta/session.\n Returns one request; None if requests empty.\n \"\"\"\n if not requests:\n return None\n first = requests[0]\n if len(requests) == 1:\n return first\n all_contents: List[Any] = []\n for req in requests:\n inp = getattr(req, \"input\", None) or []\n if inp and hasattr(inp[0], \"content\"):\n all_contents.extend(getattr(inp[0], \"content\") or [])\n if not all_contents:\n return first\n msg = first.input[0]\n if hasattr(msg, \"model_copy\"):\n new_msg = msg.model_copy(update={\"content\": all_contents})\n else:\n new_msg = msg\n setattr(new_msg, \"content\", all_contents)\n if hasattr(first, \"model_copy\"):\n return first.model_copy(\n update={\"input\": [new_msg]},\n )\n first.input[0] = new_msg\n return first\n\n def _on_debounce_buffer_append(\n self,\n key: str,\n payload: Any,\n existing_items: List[Any],\n ) -> None:\n \"\"\"\n Hook when appending to time-debounce buffer (existing_items\n non-empty). Override e.g. to unblock previous reply_future.\n \"\"\"\n del key\n del payload\n del existing_items\n\n def _content_has_text(self, contents: List[Any]) -> bool:\n \"\"\"True if contents has at least one TEXT or REFUSAL with non-empty.\"\"\"\n if not contents:\n return False\n for c in contents:\n t = getattr(c, \"type\", None)\n if (\n t == ContentType.TEXT\n and (getattr(c, \"text\", None) or \"\").strip()\n ):\n return True\n if (\n t == ContentType.REFUSAL\n and (getattr(c, \"refusal\", None) or \"\").strip()\n ):\n return True\n return False\n\n def _content_has_audio(self, contents: List[Any]) -> bool:\n \"\"\"True if contents has at least one AUDIO block.\"\"\"\n return any(\n getattr(c, \"type\", None) == ContentType.AUDIO\n for c in (contents or [])\n )\n\n def _apply_no_text_debounce(\n self,\n session_id: str,\n content_parts: List[Any],\n ) -> tuple[bool, List[Any]]:\n \"\"\"\n Debounce: if content has no text, buffer and return (False, []).\n If has text, return (True, merged) with any buffered content prepended.\n Audio-only messages bypass debounce and are processed immediately\n (voice messages are standalone user input, not partial uploads).\n \"\"\"\n if not self._content_has_text(content_parts):\n if self._content_has_audio(content_parts):\n # Audio-only messages (e.g. voice messages) should be\n # processed immediately — they are complete user input.\n pending = self._pending_content_by_session.pop(\n session_id,\n [],\n )\n merged = pending + list(content_parts)\n return (True, merged)\n self._pending_content_by_session.setdefault(\n session_id,\n [],\n ).extend(content_parts)\n logger.debug(\n \"channel debounce: no text, buffered session_id=%s\",\n session_id[:24] if session_id else \"\",\n )\n return (False, [])\n pending = self._pending_content_by_session.pop(session_id, [])\n merged = pending + list(content_parts)\n return (True, merged)\n\n def _check_allowlist(\n self,\n sender_id: str,\n is_group: bool,\n ) -> tuple[bool, Optional[str]]:\n \"\"\"Check sender against allowlist policy.\"\"\"\n policy = self.group_policy if is_group else self.dm_policy\n if policy == \"open\":\n return True, None\n if sender_id in self.allow_from:\n return True, None\n if self.deny_message:\n return False, self.deny_message\n if is_group:\n return (\n False,\n \"Sorry, this bot is only available to authorized users.\",\n )\n return False, (\n \"Sorry, you are not authorized to use this bot. \"\n \"Please contact the administrator to add your ID \"\n f\"to the allowlist. Your ID: {sender_id}\"\n )\n\n def _check_group_mention(\n self,\n is_group: bool,\n meta: dict,\n ) -> bool:\n \"\"\"Return True if message should be processed under mention policy.\"\"\"\n if not is_group or not self.require_mention:\n return True\n return bool(\n meta.get(\"bot_mentioned\") or meta.get(\"has_bot_command\"),\n )\n\n def set_enqueue(self, cb: EnqueueCallback) -> None:\n \"\"\"Set enqueue callback (called by ChannelManager).\"\"\"\n self._enqueue = cb\n\n @classmethod\n def from_env(\n cls,\n process: ProcessHandler,\n on_reply_sent: OnReplySent = None,\n ) -> \"BaseChannel\":\n raise NotImplementedError\n\n @classmethod\n def from_config(\n cls,\n process: ProcessHandler,\n config: Any,\n on_reply_sent: OnReplySent = None,\n show_tool_details: bool = True,\n filter_tool_messages: bool = False,\n filter_thinking: bool = False,\n ) -> \"BaseChannel\":\n raise NotImplementedError\n\n def resolve_session_id(\n self,\n sender_id: str,\n channel_meta: Optional[Dict[str, Any]] = None,\n ) -> str:\n \"\"\"\n Map sender and optional channel meta to session_id.\n Override in subclasses for channel-specific session keys\n (e.g. short suffix of conversation_id for cron lookup).\n \"\"\"\n return f\"{self.channel}:{sender_id}\"\n\n def build_agent_request_from_user_content(\n self,\n channel_id: str,\n sender_id: str,\n session_id: str,\n content_parts: List[Any],\n channel_meta: Optional[Dict[str, Any]] = None,\n ) -> \"AgentRequest\":\n \"\"\"\n Build AgentRequest from runtime content parts (Message content list).\n Use agentscope_runtime Message/Content types; no intermediate envelope.\n Subclasses call this after parsing native payload to content_parts.\n \"\"\"\n from agentscope_runtime.engine.schemas.agent_schemas import (\n AgentRequest,\n Message,\n Role,\n )\n\n if not content_parts:\n content_parts = [\n TextContent(type=ContentType.TEXT, text=\" \"),\n ]\n msg = Message(\n type=MessageType.MESSAGE,\n role=Role.USER,\n content=content_parts,\n )\n return AgentRequest(\n session_id=session_id,\n user_id=sender_id,\n input=[msg],\n channel=channel_id,\n )\n\n def build_agent_request_from_native(\n self,\n native_payload: Any,\n ) -> \"AgentRequest\":\n \"\"\"\n Convert channel-native message payload to AgentRequest.\n Subclasses must implement: parse native -> content_parts (runtime\n Content types), session_id, then build_agent_request_from_user_content.\n Attach channel_meta to result for send path:\n request.channel_meta = meta.\n \"\"\"\n raise NotImplementedError(\n f\"{self.__class__.__name__} must implement \"\n \"build_agent_request_from_native(native_payload)\",\n )\n\n def _payload_to_request(self, payload: Any) -> \"AgentRequest\":\n \"\"\"\n Convert queue payload to AgentRequest. Default: if payload looks like\n AgentRequest (has session_id, input), return it; else\n build_agent_request_from_native(payload). Override if needed.\n \"\"\"\n if payload is None:\n raise ValueError(\"payload is None\")\n if hasattr(payload, \"session_id\") and hasattr(payload, \"input\"):\n return payload\n return self.build_agent_request_from_native(payload)\n\n def get_to_handle_from_request(self, request: \"AgentRequest\") -> str:\n \"\"\"\n Resolve send target (to_handle) from AgentRequest. Default: user_id.\n Override for channels that send by session_id (e.g. Feishu).\n \"\"\"\n return getattr(request, \"user_id\", \"\") or \"\"\n\n def get_on_reply_sent_args(\n self,\n request: \"AgentRequest\",\n to_handle: str,\n ) -> tuple:\n \"\"\"\n Args for _on_reply_sent(channel, *args). Default: (to_handle,\n session_id). Override e.g. to pass (user_id, session_id).\n \"\"\"\n session_id = (\n getattr(request, \"session_id\", \"\") or f\"{self.channel}:{to_handle}\"\n )\n return (to_handle, session_id)\n\n async def refresh_webhook_or_token(self) -> None:\n \"\"\"\n Optional: refresh webhook URL or API token. Override for channels\n that need periodic or on-401 refresh. Default no-op.\n \"\"\"\n\n async def consume_one(self, payload: Any) -> None:\n \"\"\"\n Process one payload from the manager-owned queue. If\n _debounce_seconds > 0 and payload is native (dict with\n content_parts), append to buffer and flush after delay;\n otherwise call _consume_one_request(payload). Messages\n with no text are buffered until text arrives (see\n _apply_no_text_debounce). Override only when you need\n a different flow (e.g. print).\n \"\"\"\n if self._debounce_seconds > 0 and self._is_native_payload(payload):\n key = self.get_debounce_key(payload)\n if key in self._debounce_pending and self._debounce_pending[key]:\n self._on_debounce_buffer_append(\n key,\n payload,\n self._debounce_pending[key],\n )\n self._debounce_pending.setdefault(key, []).append(payload)\n old = self._debounce_timers.pop(key, None)\n if old and not old.done():\n old.cancel()\n\n async def flush(k: str) -> None:\n await asyncio.sleep(self._debounce_seconds)\n items = self._debounce_pending.pop(k, [])\n self._debounce_timers.pop(k, None)\n if not items:\n return\n merged = self.merge_native_items(items)\n if not merged:\n return\n await self._consume_one_request(merged)\n\n self._debounce_timers[key] = asyncio.create_task(flush(key))\n return\n await self._consume_one_request(payload)\n\n async def _consume_one_request(self, payload: Any) -> None:\n \"\"\"\n Convert payload to request, apply no-text debounce, run _process,\n send messages, handle errors and on_reply_sent. Used by\n consume_one (direct or after time-debounce flush).\n \"\"\"\n request = self._payload_to_request(payload)\n # Build meta from payload so session_webhook is never lost when\n # request has no channel_meta (e.g. AgentRequest schema has no field).\n if isinstance(payload, dict):\n meta_from_payload = dict(payload.get(\"meta\") or {})\n if payload.get(\"session_webhook\"):\n meta_from_payload[\"session_webhook\"] = payload[\n \"session_webhook\"\n ]\n # Always attach so channel _before_consume_process can use it\n # (e.g. Feishu save receive_id for cron send).\n setattr(request, \"channel_meta\", meta_from_payload)\n session_id = getattr(request, \"session_id\", \"\") or \"\"\n if request.input:\n contents = list(getattr(request.input[0], \"content\", None) or [])\n should_process, merged = self._apply_no_text_debounce(\n session_id,\n contents,\n )\n if not should_process:\n return\n if merged and (\n hasattr(request.input[0], \"model_copy\")\n or hasattr(request.input[0], \"content\")\n ):\n if hasattr(request.input[0], \"model_copy\"):\n request.input[0] = request.input[0].model_copy(\n update={\"content\": merged},\n )\n else:\n request.input[0].content = merged\n to_handle = self.get_to_handle_from_request(request)\n await self._before_consume_process(request)\n # Prefer meta built from payload so session_webhook is present when\n # request.channel_meta is missing (AgentRequest may not have the attr).\n if isinstance(payload, dict):\n send_meta = dict(payload.get(\"meta\") or {})\n if payload.get(\"session_webhook\"):\n send_meta[\"session_webhook\"] = payload[\"session_webhook\"]\n else:\n send_meta = getattr(request, \"channel_meta\", None) or {}\n bot_prefix = getattr(self, \"bot_prefix\", None) or getattr(\n self,\n \"_bot_prefix\",\n \"\",\n )\n if bot_prefix and \"bot_prefix\" not in send_meta:\n send_meta = {**send_meta, \"bot_prefix\": bot_prefix}\n logger.info(\n \"base _consume_one_request: send_meta has_session_webhook=%s\",\n bool((send_meta or {}).get(\"session_webhook\")),\n )\n await self._run_process_loop(request, to_handle, send_meta)\n\n async def _run_process_loop(\n self,\n request: \"AgentRequest\",\n to_handle: str,\n send_meta: Dict[str, Any],\n ) -> None:\n \"\"\"\n Run _process and send events. Override to use channel-specific\n loop (e.g. DingTalk _process_one_request with webhook sends).\n \"\"\"\n last_response = None\n try:\n async for event in self._process(request):\n obj = getattr(event, \"object\", None)\n status = getattr(event, \"status\", None)\n if obj == \"message\" and status == RunStatus.Completed:\n await self.on_event_message_completed(\n request,\n to_handle,\n event,\n send_meta,\n )\n elif obj == \"response\":\n last_response = event\n await self.on_event_response(request, event)\n err_msg = self._get_response_error_message(last_response)\n if err_msg:\n await self._on_consume_error(\n request,\n to_handle,\n f\"Error: {err_msg}\",\n )\n if self._on_reply_sent:\n args = self.get_on_reply_sent_args(request, to_handle)\n self._on_reply_sent(self.channel, *args)\n except Exception:\n logger.exception(\"channel consume_one failed\")\n await self._on_consume_error(\n request,\n to_handle,\n \"An error occurred while processing your request.\",\n )\n\n def _get_response_error_message(self, last_response: Any) -> Optional[str]:\n \"\"\"\n Extract error message from runtime response event.\n Handles AgentResponse.error or Event wrapper (e.g. .data / .response).\n \"\"\"\n if not last_response:\n return None\n resp = last_response\n if getattr(last_response, \"data\", None) is not None:\n resp = last_response.data\n elif getattr(last_response, \"response\", None) is not None:\n resp = last_response.response\n err = getattr(resp, \"error\", None)\n if not err:\n return None\n if hasattr(err, \"message\"):\n return getattr(err, \"message\", None) or str(err)\n if isinstance(err, dict):\n return err.get(\"message\") or str(err)\n return str(err)\n\n async def _before_consume_process(self, request: \"AgentRequest\") -> None:\n \"\"\"\n Hook called once per consume_one before running _process. Override\n to e.g. save receive_id for send path (Feishu).\n \"\"\"\n\n async def on_event_message_completed(\n self,\n request: \"AgentRequest\",\n to_handle: str,\n event: Any,\n send_meta: Dict[str, Any],\n ) -> None:\n \"\"\"\n Hook: one message event completed. Default: send_message_content.\n Override for batch/debounce (e.g. DingTalk merge then send).\n \"\"\"\n await self.send_message_content(to_handle, event, send_meta)\n\n async def on_event_response(\n self,\n request: \"AgentRequest\",\n event: Any,\n ) -> None:\n \"\"\"Hook: response event received. Default: no-op.\"\"\"\n\n async def _on_consume_error(\n self,\n request: Any,\n to_handle: str,\n err_text: str,\n ) -> None:\n \"\"\"\n Called when consume_one hits an error or response.error. Default:\n send err_text via send_content_parts. Override to send via channel\n API (e.g. imessage _send_sync).\n \"\"\"\n await self.send_content_parts(\n to_handle,\n [TextContent(type=ContentType.TEXT, text=err_text)],\n getattr(request, \"channel_meta\", None) or {},\n )\n\n async def send_response(\n self,\n to_handle: str,\n response: \"AgentResponse\",\n meta: Optional[Dict[str, Any]] = None,\n ) -> None:\n \"\"\"\n Convert AgentResponse to this channel's reply and send.\n Default: take last message text from output and call\n send(to_handle, text, meta).\n Subclasses may override to support image, video attachments.\n \"\"\"\n text = self._response_to_text(response)\n await self.send(to_handle, text or \"\", meta)\n\n def _message_to_content_parts(\n self,\n message: Any,\n ) -> List[OutgoingContentPart]:\n \"\"\"\n Convert a Message (object=='message') into sendable parts.\n Delegates to self._renderer; override _renderer or _render_style\n for channel-specific formatting.\n \"\"\"\n return self._renderer.message_to_parts(message)\n\n async def send_message_content(\n self,\n to_handle: str,\n message: Any,\n meta: Optional[Dict[str, Any]] = None,\n ) -> None:\n \"\"\"\n Send all content of a Message\n (text, image, video, audio, file, refusal).\n Subclasses may override send_content_parts for channel-specific\n multi-part sending.\n \"\"\"\n parts = self._message_to_content_parts(message)\n if not parts:\n logger.debug(\n f\"channel send_message_content: no parts for to_handle=\"\n f\"{to_handle}, skip send\",\n )\n return\n logger.debug(\n f\"channel send_message_content: to_handle={to_handle} \"\n f\"parts_count={len(parts)} \"\n f\"part_types={[getattr(p, 'type', None) for p in parts]}\",\n )\n await self.send_content_parts(to_handle, parts, meta)\n\n async def send_content_parts(\n self,\n to_handle: str,\n parts: List[OutgoingContentPart],\n meta: Optional[Dict[str, Any]] = None,\n ) -> None:\n \"\"\"\n Send a list of content parts.\n Default: merge text/refusal into one text, append media URLs as\n fallback, send one message; optionally call send_media for each\n media part if overridden.\n \"\"\"\n text_parts: List[str] = []\n media_parts: List[OutgoingContentPart] = []\n for p in parts:\n t = getattr(p, \"type\", None)\n if t == ContentType.TEXT and getattr(p, \"text\", None):\n text_parts.append(p.text or \"\")\n elif t == ContentType.REFUSAL and getattr(p, \"refusal\", None):\n text_parts.append(p.refusal or \"\")\n elif t in (\n ContentType.IMAGE,\n ContentType.VIDEO,\n ContentType.AUDIO,\n ContentType.FILE,\n ):\n media_parts.append(p)\n body = \"\\n\".join(text_parts) if text_parts else \"\"\n prefix = (meta or {}).get(\"bot_prefix\", \"\") or \"\"\n if prefix and body:\n body = prefix + body\n for m in media_parts:\n t = getattr(m, \"type\", None)\n if t == ContentType.IMAGE and getattr(m, \"image_url\", None):\n body += f\"\\n[Image: {m.image_url}]\"\n elif t == ContentType.VIDEO and getattr(m, \"video_url\", None):\n body += f\"\\n[Video: {m.video_url}]\"\n elif t == ContentType.FILE and (\n getattr(m, \"file_url\", None) or getattr(m, \"file_id\", None)\n ):\n body += f\"\\n[File: {m.file_url or m.file_id}]\"\n elif t == ContentType.AUDIO and getattr(m, \"data\", None):\n body += \"\\n[Audio]\"\n if body.strip():\n logger.debug(\n f\"channel send_content_parts: to_handle={to_handle} \"\n f\"body_len={len(body)} preview=\"\n f\"{body[:120] + '...' if len(body) > 120 else body}\",\n )\n await self.send(to_handle, body.strip(), meta)\n for m in media_parts:\n await self.send_media(to_handle, m, meta)\n\n async def send_media(\n self,\n to_handle: str,\n part: OutgoingContentPart,\n meta: Optional[Dict[str, Any]] = None,\n ) -> None:\n \"\"\"\n Send a single media part (image, video, audio, file).\n Default: no-op (already appended to text in send_content_parts).\n Subclasses override to send real attachments.\n \"\"\"\n pass\n\n def _response_to_text(self, response: \"AgentResponse\") -> str:\n \"\"\"Extract reply text from AgentResponse (last message in output).\"\"\"\n if not response.output:\n return \"\"\n last_msg = response.output[-1]\n if last_msg.type != MessageType.MESSAGE or not last_msg.content:\n return \"\"\n parts = []\n for c in last_msg.content:\n if getattr(c, \"type\", None) == ContentType.TEXT and getattr(\n c,\n \"text\",\n None,\n ):\n parts.append(c.text)\n elif getattr(c, \"type\", None) == ContentType.REFUSAL and getattr(\n c,\n \"refusal\",\n None,\n ):\n parts.append(c.refusal)\n return \"\".join(parts)\n\n def clone(self, config) -> \"BaseChannel\":\n \"\"\"Clone a new channel instance with updated config, cloning\n process and on_reply_sent from self.\n\n Subclasses must implement from_config(process, config, on_reply_sent).\n\n show_tool_details is global config (not in channel config), so we\n preserve from self. filter_tool_messages and filter_thinking are\n per-channel config, so we read from new config.\n \"\"\"\n return self.__class__.from_config(\n process=self._process,\n config=config,\n on_reply_sent=self._on_reply_sent,\n show_tool_details=getattr(self, \"_show_tool_details\", True),\n filter_tool_messages=getattr(\n config,\n \"filter_tool_messages\",\n False,\n ),\n filter_thinking=getattr(\n config,\n \"filter_thinking\",\n False,\n ),\n )\n\n async def start(self) -> None:\n raise NotImplementedError\n\n async def stop(self) -> None:\n raise NotImplementedError\n\n async def send(\n self,\n to_handle: str,\n text: str,\n meta: Optional[Dict[str, Any]] = None,\n ) -> None:\n \"\"\"Subclass implements: send one text\n (and optional attachments) to to_handle.\n \"\"\"\n raise NotImplementedError\n\n def to_handle_from_target(self, *, user_id: str, session_id: str) -> str:\n \"\"\"Map cron dispatch target to channel-specific to_handle.\n\n Default: use user_id. For many channels, this is enough.\n Discord proactive send relies on meta['channel_id'] or\n meta['user_id'] anyway.\n \"\"\"\n return user_id\n\n async def send_event(\n self,\n *,\n user_id: str,\n session_id: str,\n event: \"Event\",\n meta: Optional[Dict[str, Any]] = None,\n ) -> None:\n \"\"\"Send a runner Event to this channel (non-stream).\n\n We only send when event is a completed message, then reuse\n send_message_content().\n \"\"\"\n # Delay import to avoid hard dependency at module import time\n\n obj = getattr(event, \"object\", None)\n status = getattr(event, \"status\", None)\n\n if obj != \"message\" or status != RunStatus.Completed:\n return\n\n to_handle = self.to_handle_from_target(\n user_id=user_id,\n session_id=session_id,\n )\n await self.send_message_content(to_handle, event, meta)\n" }, { "path": "src/copaw/app/channels/console/__init__.py", "content": "# -*- coding: utf-8 -*-\n\"\"\"Console channel package.\"\"\"\nfrom .channel import ConsoleChannel\n\n__all__ = [\"ConsoleChannel\"]\n" }, { "path": "src/copaw/app/channels/console/channel.py", "content": "# -*- coding: utf-8 -*-\n# pylint: disable=too-many-branches,too-many-statements\n\"\"\"Console Channel.\n\nA lightweight channel that prints all agent responses to stdout.\n\nMessages are sent to the agent via the standard AgentApp ``/agent/process``\nendpoint or via POST /console/chat. This channel handles the **output** side:\nwhenever a completed message event or a proactive send arrives, it is\npretty-printed to the terminal.\n\"\"\"\nfrom __future__ import annotations\n\nimport logging\nimport os\nimport sys\nimport json\nfrom datetime import datetime\nfrom pathlib import Path\nfrom typing import Any, AsyncGenerator, Dict, List, Optional, Union\n\nfrom agentscope_runtime.engine.schemas.agent_schemas import RunStatus\n\nfrom ....config.config import ConsoleConfig as ConsoleChannelConfig\nfrom ...console_push_store import append as push_store_append\nfrom ....constant import DEFAULT_MEDIA_DIR\nfrom ..base import (\n BaseChannel,\n ContentType,\n FileContent,\n ImageContent,\n OnReplySent,\n OutgoingContentPart,\n ProcessHandler,\n VideoContent,\n TextContent,\n)\n\n\nlogger = logging.getLogger(__name__)\n\n# ANSI colour helpers (degrade gracefully if not a tty)\n_USE_COLOR = hasattr(sys.stdout, \"isatty\") and sys.stdout.isatty()\n\n_GREEN = \"\\033[32m\" if _USE_COLOR else \"\"\n_YELLOW = \"\\033[33m\" if _USE_COLOR else \"\"\n_RED = \"\\033[31m\" if _USE_COLOR else \"\"\n_BOLD = \"\\033[1m\" if _USE_COLOR else \"\"\n_RESET = \"\\033[0m\" if _USE_COLOR else \"\"\n\n\ndef _ts() -> str:\n return datetime.now().strftime(\"%H:%M:%S\")\n\n\nclass ConsoleChannel(BaseChannel):\n \"\"\"Console Channel: prints agent responses to stdout.\n\n Input is handled by AgentApp's ``/agent/process`` endpoint; this\n channel only takes care of output (printing to the terminal).\n\n Supports filtering options via config:\n - show_tool_details: Display tool execution details\n - filter_tool_messages: Hide intermediate tool messages\n - filter_thinking: Hide agent thinking/reasoning blocks\n \"\"\"\n\n channel = \"console\"\n\n def __init__(\n self,\n process: ProcessHandler,\n enabled: bool,\n bot_prefix: str,\n on_reply_sent: OnReplySent = None,\n show_tool_details: bool = True,\n filter_tool_messages: bool = False,\n filter_thinking: bool = False,\n workspace_dir: Optional[Union[str, Path]] = None,\n media_dir: Optional[str] = None,\n ):\n \"\"\"Initialize ConsoleChannel.\n\n Args:\n process: Handler for agent requests.\n enabled: Whether this channel is active.\n bot_prefix: Prefix string for bot messages.\n on_reply_sent: Callback when reply is sent.\n show_tool_details: Whether to show tool execution details.\n filter_tool_messages: Whether to filter out tool messages.\n filter_thinking: Whether to filter thinking/reasoning blocks.\n workspace_dir: Agent workspace directory; used to resolve uploaded\n file names (media_dir = workspace_dir / \"media\").\n media_dir: Agent workspace directory for resolving uploads.\n \"\"\"\n super().__init__(\n process,\n on_reply_sent=on_reply_sent,\n show_tool_details=show_tool_details,\n filter_tool_messages=filter_tool_messages,\n filter_thinking=filter_thinking,\n )\n self.enabled = enabled\n self.bot_prefix = bot_prefix\n self._workspace_dir = (\n Path(workspace_dir).expanduser() if workspace_dir else None\n )\n\n # Use workspace-specific media dir if workspace_dir is provided\n if not media_dir and self._workspace_dir:\n self._media_dir = self._workspace_dir / \"media\"\n elif media_dir:\n self._media_dir = Path(media_dir).expanduser()\n else:\n self._media_dir = DEFAULT_MEDIA_DIR\n self._media_dir.mkdir(parents=True, exist_ok=True)\n\n @property\n def media_dir(self) -> Path:\n \"\"\"Media directory\"\"\"\n return self._media_dir\n\n @classmethod\n def from_env(\n cls,\n process: ProcessHandler,\n on_reply_sent: OnReplySent = None,\n ) -> \"ConsoleChannel\":\n return cls(\n process=process,\n enabled=os.getenv(\"CONSOLE_CHANNEL_ENABLED\", \"1\") == \"1\",\n bot_prefix=os.getenv(\"CONSOLE_BOT_PREFIX\", \"[BOT] \"),\n on_reply_sent=on_reply_sent,\n media_dir=os.getenv(\"CONSOLE_MEDIA_DIR\", \"\"),\n )\n\n @classmethod\n def from_config(\n cls,\n process: ProcessHandler,\n config: ConsoleChannelConfig,\n on_reply_sent: OnReplySent = None,\n show_tool_details: bool = True,\n filter_tool_messages: bool = False,\n filter_thinking: bool = False,\n workspace_dir: Optional[Union[str, Path]] = None,\n ) -> \"ConsoleChannel\":\n \"\"\"Create ConsoleChannel from config.\n\n Args:\n process: Handler for agent requests.\n config: Console channel configuration.\n on_reply_sent: Callback when reply is sent.\n show_tool_details: Whether to show tool execution details.\n filter_tool_messages: Whether to filter out tool messages.\n filter_thinking: Whether to filter thinking/reasoning blocks.\n workspace_dir: Agent workspace directory for resolving uploads.\n\n Returns:\n Configured ConsoleChannel instance.\n \"\"\"\n return cls(\n process=process,\n enabled=config.enabled,\n bot_prefix=config.bot_prefix or \"[BOT] \",\n on_reply_sent=on_reply_sent,\n show_tool_details=show_tool_details,\n filter_tool_messages=filter_tool_messages,\n filter_thinking=filter_thinking,\n workspace_dir=workspace_dir,\n media_dir=config.media_dir or \"\",\n )\n\n def resolve_session_id(\n self,\n sender_id: str,\n channel_meta: Optional[dict] = None,\n ) -> str:\n \"\"\"Resolve session_id: use explicit meta['session_id'] when provided\n (e.g. from the HTTP /console/chat API), otherwise fall back to\n 'console:'.\n \"\"\"\n if channel_meta and channel_meta.get(\"session_id\"):\n return channel_meta[\"session_id\"]\n return f\"{self.channel}:{sender_id}\"\n\n def _resolve_console_upload_refs(\n self,\n content_parts: List[Any],\n ) -> List[Any]:\n \"\"\"Resolve Image/File/Audio/VideoContent.\"\"\"\n if not self._media_dir:\n return content_parts\n\n def resolve_one(part: Any) -> Optional[OutgoingContentPart]:\n content_type = getattr(part, \"type\", None)\n if content_type == ContentType.IMAGE:\n url = getattr(part, \"image_url\", None)\n if url:\n return ImageContent(\n type=ContentType.IMAGE,\n image_url=str(self._media_dir / url),\n )\n elif content_type == ContentType.VIDEO:\n url = getattr(part, \"video_url\", None)\n if url:\n return VideoContent(\n type=ContentType.VIDEO,\n video_url=str(self._media_dir / url),\n )\n elif content_type == ContentType.AUDIO:\n url = getattr(part, \"data\", None) or getattr(\n part,\n \"audio_url\",\n None,\n )\n if url:\n # Todo: support local audio file\n return FileContent(\n type=ContentType.FILE,\n filename=getattr(part, \"filename\", None) or url,\n file_url=str(self._media_dir / url),\n )\n elif content_type == ContentType.FILE:\n url = getattr(part, \"file_url\", None)\n if url:\n return FileContent(\n type=ContentType.FILE,\n filename=getattr(part, \"filename\", None) or url,\n file_url=str(self._media_dir / url),\n )\n elif content_type == ContentType.TEXT:\n return TextContent(type=ContentType.TEXT, text=part.text)\n return part\n\n input_content_parts = []\n for content in content_parts:\n part = resolve_one(content)\n if part is not None:\n input_content_parts.append(part)\n return input_content_parts\n\n def build_agent_request_from_native(self, native_payload: Any) -> Any:\n \"\"\"\n Build AgentRequest from console native payload (dict with\n channel_id, sender_id, content_parts, meta). content_parts are\n runtime Content types.\n \"\"\"\n payload = native_payload if isinstance(native_payload, dict) else {}\n channel_id = payload.get(\"channel_id\") or self.channel\n sender_id = payload.get(\"sender_id\") or \"\"\n content_parts = payload.get(\"content_parts\") or []\n content_parts = self._resolve_console_upload_refs(content_parts)\n meta = payload.get(\"meta\") or {}\n session_id = self.resolve_session_id(sender_id, meta)\n request = self.build_agent_request_from_user_content(\n channel_id=channel_id,\n sender_id=sender_id,\n session_id=session_id,\n content_parts=content_parts,\n channel_meta=meta,\n )\n request.channel_meta = meta\n return request\n\n async def stream_one(self, payload: Any) -> AsyncGenerator[str, None]:\n \"\"\"Process one payload and yield SSE-formatted events\"\"\"\n if isinstance(payload, dict) and \"content_parts\" in payload:\n session_id = self.resolve_session_id(\n payload.get(\"sender_id\") or \"\",\n payload.get(\"meta\"),\n )\n content_parts = payload.get(\"content_parts\") or []\n should_process, merged = self._apply_no_text_debounce(\n session_id,\n content_parts,\n )\n if not should_process:\n return\n payload = {**payload, \"content_parts\": merged}\n request = self.build_agent_request_from_native(payload)\n else:\n request = payload\n if getattr(request, \"input\", None):\n session_id = getattr(request, \"session_id\", \"\") or \"\"\n contents = list(\n getattr(request.input[0], \"content\", None) or [],\n )\n should_process, merged = self._apply_no_text_debounce(\n session_id,\n contents,\n )\n if not should_process:\n return\n if merged and hasattr(request.input[0], \"content\"):\n request.input[0].content = merged\n try:\n send_meta = getattr(request, \"channel_meta\", None) or {}\n send_meta.setdefault(\"bot_prefix\", self.bot_prefix)\n last_response = None\n event_count = 0\n\n async for event in self._process(request):\n event_count += 1\n obj = getattr(event, \"object\", None)\n status = getattr(event, \"status\", None)\n ev_type = getattr(event, \"type\", None)\n\n logger.debug(\n \"console event #%s: object=%s status=%s type=%s\",\n event_count,\n obj,\n status,\n ev_type,\n )\n\n if hasattr(event, \"model_dump_json\"):\n data = event.model_dump_json()\n elif hasattr(event, \"json\"):\n data = event.json()\n else:\n data = json.dumps({\"text\": str(event)})\n yield f\"data: {data}\\n\\n\"\n\n if obj == \"message\" and status == RunStatus.Completed:\n parts = self._message_to_content_parts(event)\n self._print_parts(parts, ev_type)\n\n elif obj == \"response\":\n last_response = event\n\n logger.info(\n \"console stream done: event_count=%s has_response=%s\",\n event_count,\n last_response is not None,\n )\n\n err_msg = self._get_response_error_message(last_response)\n if err_msg:\n self._print_error(err_msg)\n\n to_handle = request.user_id or \"\"\n if self._on_reply_sent:\n self._on_reply_sent(\n self.channel,\n to_handle,\n request.session_id or f\"{self.channel}:{to_handle}\",\n )\n\n except Exception as e:\n logger.exception(\"console process/reply failed\")\n err_msg = str(e).strip() or \"An error occurred while processing.\"\n self._print_error(err_msg)\n\n async def consume_one(self, payload: Any) -> None:\n \"\"\"Process one payload; drain stream_one (queue/terminal).\"\"\"\n async for _ in self.stream_one(payload):\n pass\n\n # ── pretty-print helpers ────────────────────────────────────────\n\n def _print_parts(\n self,\n parts: List[OutgoingContentPart],\n ev_type: Optional[str] = None,\n ) -> None:\n \"\"\"Print outgoing content parts to stdout.\"\"\"\n ts = _ts()\n label = f\" ({ev_type})\" if ev_type else \"\"\n print(\n f\"\\n{_GREEN}{_BOLD}🤖 [{ts}] Bot{label}{_RESET}\",\n )\n for p in parts:\n t = getattr(p, \"type\", None)\n if t == ContentType.TEXT and getattr(p, \"text\", None):\n print(f\"{self.bot_prefix}{p.text}\")\n elif t == ContentType.REFUSAL and getattr(p, \"refusal\", None):\n print(f\"{_RED}⚠ Refusal: {p.refusal}{_RESET}\")\n elif t == ContentType.IMAGE and getattr(p, \"image_url\", None):\n print(f\"{_YELLOW}🖼 [Image: {p.image_url}]{_RESET}\")\n elif t == ContentType.VIDEO and getattr(p, \"video_url\", None):\n print(f\"{_YELLOW}🎬 [Video: {p.video_url}]{_RESET}\")\n elif t == ContentType.AUDIO and getattr(p, \"data\", None):\n print(f\"{_YELLOW}🔊 [Audio]{_RESET}\")\n elif t == ContentType.FILE:\n url = (\n getattr(p, \"file_url\", None)\n or getattr(p, \"file_id\", None)\n or \"\"\n )\n print(f\"{_YELLOW}📎 [File: {url}]{_RESET}\")\n print()\n\n def _print_error(self, err: str) -> None:\n ts = _ts()\n print(\n f\"\\n{_RED}{_BOLD}❌ [{ts}] Error{_RESET}\\n\"\n f\"{_RED}{err}{_RESET}\\n\",\n )\n\n def _parts_to_text(\n self,\n parts: List[OutgoingContentPart],\n meta: Optional[Dict[str, Any]] = None,\n ) -> str:\n \"\"\"\n Merge parts to one body string (same logic as base send_content_parts).\n \"\"\"\n text_parts: List[str] = []\n for p in parts:\n t = getattr(p, \"type\", None)\n if t == ContentType.TEXT and getattr(p, \"text\", None):\n text_parts.append(p.text or \"\")\n elif t == ContentType.REFUSAL and getattr(p, \"refusal\", None):\n text_parts.append(p.refusal or \"\")\n body = \"\\n\".join(text_parts) if text_parts else \"\"\n prefix = (meta or {}).get(\"bot_prefix\", self.bot_prefix) or \"\"\n if prefix and body:\n body = prefix + body\n return body\n\n # ── send (for proactive sends / cron) ───────────────────────────\n\n async def send(\n self,\n to_handle: str,\n text: str,\n meta: Optional[Dict[str, Any]] = None,\n ) -> None:\n \"\"\"Send a text message — prints to stdout and pushes to frontend.\"\"\"\n if not self.enabled:\n return\n ts = _ts()\n prefix = (meta or {}).get(\"bot_prefix\", self.bot_prefix) or \"\"\n print(\n f\"\\n{_GREEN}{_BOLD}🤖 [{ts}] Bot → {to_handle}{_RESET}\\n\"\n f\"{prefix}{text}\\n\",\n )\n sid = (meta or {}).get(\"session_id\")\n if sid and text.strip():\n await push_store_append(sid, text.strip())\n\n async def send_content_parts(\n self,\n to_handle: str,\n parts: List[OutgoingContentPart],\n meta: Optional[Dict[str, Any]] = None,\n ) -> None:\n \"\"\"\n Send content parts — prints to stdout and pushes to frontend store.\n \"\"\"\n self._print_parts(parts)\n sid = (meta or {}).get(\"session_id\")\n if sid:\n body = self._parts_to_text(parts, meta)\n if body.strip():\n await push_store_append(sid, body.strip())\n\n # ── lifecycle ───────────────────────────────────────────────────\n\n async def start(self) -> None:\n if not self.enabled:\n logger.debug(\"console channel disabled\")\n return\n logger.info(\"Console channel started\")\n\n async def stop(self) -> None:\n if not self.enabled:\n return\n logger.info(\"console channel stopped\")\n" }, { "path": "src/copaw/app/channels/dingtalk/__init__.py", "content": "# -*- coding: utf-8 -*-\n\"\"\"DingTalk channel package.\"\"\"\nfrom .channel import DingTalkChannel\n\n__all__ = [\"DingTalkChannel\"]\n" }, { "path": "src/copaw/app/channels/dingtalk/ai_card.py", "content": "# -*- coding: utf-8 -*-\n\"\"\"DingTalk AI Card helpers.\"\"\"\n\nfrom __future__ import annotations\n\nimport json\nimport re\nimport time\nfrom dataclasses import asdict, dataclass\nfrom pathlib import Path\nfrom typing import Dict, List\n\nPROCESSING = \"1\"\nINPUTING = \"2\"\nFINISHED = \"3\"\nFAILED = \"5\"\n_TERMINAL_STATES = {FINISHED, FAILED}\n\n\n@dataclass\nclass ActiveAICard:\n card_instance_id: str\n access_token: str\n conversation_id: str\n account_id: str\n store_path: str\n created_at: int\n last_updated: int\n state: str\n last_streamed_content: str = \"\"\n\n\nclass AICardPendingStore:\n \"\"\"Persist active inbound cards for crash recovery.\"\"\"\n\n def __init__(self, path: Path):\n self._path = path\n\n @property\n def path(self) -> Path:\n return self._path\n\n def load(self) -> List[dict]:\n if not self._path.is_file():\n return []\n try:\n data = json.loads(self._path.read_text(encoding=\"utf-8\"))\n pending = (\n data.get(\"pending_cards\") if isinstance(data, dict) else []\n )\n return pending if isinstance(pending, list) else []\n except Exception:\n return []\n\n def save(self, cards: Dict[str, ActiveAICard]) -> None:\n self._path.parent.mkdir(parents=True, exist_ok=True)\n pending_cards = [\n {\n \"account_id\": v.account_id,\n \"card_instance_id\": v.card_instance_id,\n \"conversation_id\": v.conversation_id,\n \"created_at\": v.created_at,\n \"last_updated\": v.last_updated,\n \"state\": v.state,\n }\n for v in cards.values()\n if v.state not in _TERMINAL_STATES\n ]\n data = {\n \"version\": 1,\n \"updated_at\": int(time.time() * 1000),\n \"pending_cards\": pending_cards,\n }\n tmp = self._path.with_suffix(\".tmp\")\n tmp.write_text(\n json.dumps(data, ensure_ascii=False, indent=2),\n encoding=\"utf-8\",\n )\n tmp.replace(self._path)\n\n\ndef is_group_conversation(conversation_id: str) -> bool:\n return (conversation_id or \"\").startswith(\"cid\")\n\n\ndef thinking_or_tool_to_card_text(text: str, title: str) -> str:\n body = (text or \"\")[:500]\n if len(text or \"\") > 500:\n body += \"…\"\n lines = body.splitlines() or [\"\"]\n fixed = []\n for ln in lines:\n ln = re.sub(r\"^_$\", \"*\", ln)\n ln = re.sub(r\"_$\", \"*\", ln)\n fixed.append(f\"> {ln}\")\n return f\"{title}\\n\" + \"\\n\".join(fixed)\n\n\ndef to_pending_record(card: ActiveAICard) -> dict:\n data = asdict(card)\n data.pop(\"access_token\", None)\n data.pop(\"store_path\", None)\n data.pop(\"last_streamed_content\", None)\n return data\n" }, { "path": "src/copaw/app/channels/dingtalk/channel.py", "content": "# -*- coding: utf-8 -*-\n# pylint: disable=too-many-statements,too-many-branches\n# pylint: disable=too-many-return-statements\n\"\"\"DingTalk Channel.\n\nWhy only one reply by default: DingTalk Stream callback is request-reply.\nThe handler process() is awaited until reply_future is set once,\nthen reply_text() is called once.\nSo we merge all streamed content into one reply. When sessionWebhook is\npresent we can send multiple messages via that webhook (one POST per\ncompleted message), then set the future to a sentinel so process() skips the\nsingle reply_text.\n\"\"\"\n\nfrom __future__ import annotations\n\nimport asyncio\nimport base64\nimport hashlib\nimport json\nimport logging\nimport mimetypes\nimport os\nimport threading\nimport time\nfrom pathlib import Path\nfrom typing import TYPE_CHECKING, Any, Dict, List, Optional\nfrom uuid import uuid4\nfrom urllib.parse import urlparse\n\nimport aiohttp\nimport dingtalk_stream\nfrom dingtalk_stream import ChatbotMessage\nfrom agentscope_runtime.engine.schemas.agent_schemas import RunStatus\n\nfrom ..utils import file_url_to_local_path\nfrom ....config.config import DingTalkConfig as DingTalkChannelConfig\nfrom ....config.utils import get_config_path\nfrom ....constant import DEFAULT_MEDIA_DIR\n\nfrom ..base import (\n BaseChannel,\n ContentType,\n OnReplySent,\n OutgoingContentPart,\n ProcessHandler,\n)\n\nfrom .constants import (\n AI_CARD_PROCESSING_TEXT,\n AI_CARD_RECOVERY_FINAL_TEXT,\n AI_CARD_STREAM_MIN_INTERVAL_SECONDS,\n AI_CARD_TOKEN_PREEMPTIVE_REFRESH_SECONDS,\n DINGTALK_TOKEN_TTL_SECONDS,\n SENT_VIA_AI_CARD,\n SENT_VIA_WEBHOOK,\n)\nfrom .content_utils import (\n parse_data_url,\n session_param_from_webhook_url,\n short_session_id_from_conversation_id,\n)\nfrom .handler import DingTalkChannelHandler\nfrom . import markdown as dingtalk_markdown\nfrom .ai_card import (\n FAILED,\n FINISHED,\n INPUTING,\n PROCESSING,\n AICardPendingStore,\n ActiveAICard,\n)\nfrom .utils import guess_suffix_from_file_content\n\nif TYPE_CHECKING:\n from agentscope_runtime.engine.schemas.agent_schemas import AgentRequest\n\nlogger = logging.getLogger(__name__)\n\n\nclass DingTalkChannel(BaseChannel):\n \"\"\"DingTalk Channel: DingTalk Stream -> Incoming -> to_agent_request ->\n process -> send_response -> DingTalk reply.\n\n Proactive send (stored sessionWebhook):\n - We store sessionWebhook from incoming messages in memory; send() uses it.\n - Key uses short suffix of conversation_id so request and cron stay short.\n - to_handle \"dingtalk:sw:\" (session_id = last N of conv id).\n - Note: sessionWebhook has an expiry (sessionWebhookExpiredTime);\n push only works for users who have chatted recently. For cron to\n users who may not\n have spoken, consider Open API (corp_id + batchSend) instead.\n \"\"\"\n\n channel = \"dingtalk\"\n\n def __init__(\n self,\n process: ProcessHandler,\n enabled: bool,\n client_id: str,\n client_secret: str,\n bot_prefix: str,\n message_type: str = \"markdown\",\n card_template_id: str = \"\",\n card_template_key: str = \"content\",\n robot_code: str = \"\",\n media_dir: str = \"\",\n workspace_dir: Path | None = None,\n on_reply_sent: OnReplySent = None,\n show_tool_details: bool = True,\n filter_tool_messages: bool = False,\n dm_policy: str = \"open\",\n group_policy: str = \"open\",\n allow_from: Optional[List[str]] = None,\n deny_message: str = \"\",\n filter_thinking: bool = False,\n require_mention: bool = False,\n ):\n super().__init__(\n process,\n on_reply_sent=on_reply_sent,\n show_tool_details=show_tool_details,\n filter_tool_messages=filter_tool_messages,\n filter_thinking=filter_thinking,\n dm_policy=dm_policy,\n group_policy=group_policy,\n allow_from=allow_from,\n deny_message=deny_message,\n require_mention=require_mention,\n )\n self.enabled = enabled\n self.client_id = client_id\n self.client_secret = client_secret\n self.bot_prefix = bot_prefix\n self.message_type = (message_type or \"markdown\").strip().lower()\n self.card_template_id = card_template_id or \"\"\n self.card_template_key = card_template_key or \"content\"\n self.robot_code = robot_code or self.client_id\n self._workspace_dir = (\n Path(workspace_dir).expanduser() if workspace_dir else None\n )\n self._active_cards: Dict[str, ActiveAICard] = {}\n self._active_cards_lock = asyncio.Lock()\n cards_dir = self._workspace_dir or get_config_path().parent\n self._card_store = AICardPendingStore(\n cards_dir / \"dingtalk-active-cards.json\",\n )\n # Use workspace-specific media dir if workspace_dir is provided\n if not media_dir and self._workspace_dir:\n self._media_dir = self._workspace_dir / \"media\"\n elif media_dir:\n self._media_dir = Path(media_dir).expanduser()\n else:\n self._media_dir = DEFAULT_MEDIA_DIR\n self._media_dir.mkdir(parents=True, exist_ok=True)\n\n self._client: Optional[dingtalk_stream.DingTalkStreamClient] = None\n self._loop: Optional[asyncio.AbstractEventLoop] = None\n self._stream_thread: Optional[threading.Thread] = None\n self._stop_event = threading.Event()\n self._http: Optional[aiohttp.ClientSession] = None\n\n # Store sessionWebhook for proactive send (in-memory).\n # Key is a handle string, e.g. \"dingtalk:sw:\"\n self._session_webhook_store: Dict[str, str] = {}\n self._session_webhook_lock = asyncio.Lock()\n\n # Time debounce disabled: manager drains same-session from queue\n # and merges before calling us.\n self._debounce_seconds = 0.0\n\n # Token cache (instance-level for multi-instance / tests)\n self._token_lock = asyncio.Lock()\n self._token_value: Optional[str] = None\n self._token_expires_at: float = 0.0\n\n # Dedup: in-flight message_ids only (message_id is sufficient).\n self._processing_message_ids: set = set()\n self._processing_message_ids_lock = threading.Lock()\n\n @classmethod\n def from_env(\n cls,\n process: ProcessHandler,\n on_reply_sent: OnReplySent = None,\n ) -> \"DingTalkChannel\":\n allow_from_env = os.getenv(\"DINGTALK_ALLOW_FROM\", \"\")\n allow_from = (\n [s.strip() for s in allow_from_env.split(\",\") if s.strip()]\n if allow_from_env\n else []\n )\n return cls(\n process=process,\n enabled=os.getenv(\"DINGTALK_CHANNEL_ENABLED\", \"1\") == \"1\",\n client_id=os.getenv(\"DINGTALK_CLIENT_ID\", \"\"),\n client_secret=os.getenv(\"DINGTALK_CLIENT_SECRET\", \"\"),\n bot_prefix=os.getenv(\"DINGTALK_BOT_PREFIX\", \"[BOT] \"),\n message_type=os.getenv(\"DINGTALK_MESSAGE_TYPE\", \"markdown\"),\n card_template_id=os.getenv(\"DINGTALK_CARD_TEMPLATE_ID\", \"\"),\n card_template_key=os.getenv(\n \"DINGTALK_CARD_TEMPLATE_KEY\",\n \"content\",\n ),\n robot_code=os.getenv(\"DINGTALK_ROBOT_CODE\", \"\")\n or os.getenv(\"DINGTALK_CLIENT_ID\", \"\"),\n media_dir=os.getenv(\"DINGTALK_MEDIA_DIR\", \"\"),\n on_reply_sent=on_reply_sent,\n dm_policy=os.getenv(\"DINGTALK_DM_POLICY\", \"open\"),\n group_policy=os.getenv(\"DINGTALK_GROUP_POLICY\", \"open\"),\n allow_from=allow_from,\n deny_message=os.getenv(\"DINGTALK_DENY_MESSAGE\", \"\"),\n require_mention=os.getenv(\"DINGTALK_REQUIRE_MENTION\", \"0\") == \"1\",\n )\n\n @classmethod\n def from_config(\n cls,\n process: ProcessHandler,\n config: DingTalkChannelConfig,\n on_reply_sent: OnReplySent = None,\n show_tool_details: bool = True,\n filter_tool_messages: bool = False,\n filter_thinking: bool = False,\n workspace_dir: Path | None = None,\n ) -> \"DingTalkChannel\":\n return cls(\n process=process,\n enabled=config.enabled,\n client_id=config.client_id or \"\",\n client_secret=config.client_secret or \"\",\n bot_prefix=config.bot_prefix or \"[BOT] \",\n message_type=getattr(config, \"message_type\", \"markdown\"),\n card_template_id=getattr(config, \"card_template_id\", \"\"),\n card_template_key=getattr(config, \"card_template_key\", \"content\"),\n robot_code=(\n getattr(config, \"robot_code\", \"\") or config.client_id or \"\"\n ),\n media_dir=config.media_dir or \"\",\n workspace_dir=workspace_dir,\n on_reply_sent=on_reply_sent,\n show_tool_details=show_tool_details,\n filter_tool_messages=filter_tool_messages,\n dm_policy=config.dm_policy or \"open\",\n group_policy=config.group_policy or \"open\",\n allow_from=config.allow_from or [],\n deny_message=config.deny_message or \"\",\n filter_thinking=filter_thinking,\n require_mention=config.require_mention,\n )\n\n # ---------------------------\n # Proactive send: webhook store\n # ---------------------------\n\n def resolve_session_id(\n self,\n sender_id: str,\n channel_meta: Optional[Dict[str, Any]] = None,\n ) -> str:\n \"\"\"Session_id = short suffix of conversation_id for cron lookup.\"\"\"\n meta = channel_meta or {}\n cid = meta.get(\"conversation_id\")\n if cid:\n return short_session_id_from_conversation_id(cid)\n return f\"{self.channel}:{sender_id}\"\n\n def build_agent_request_from_native(\n self,\n native_payload: Any,\n ) -> \"AgentRequest\":\n \"\"\"Build AgentRequest from DingTalk native dict (runtime content).\"\"\"\n payload = native_payload if isinstance(native_payload, dict) else {}\n channel_id = payload.get(\"channel_id\") or self.channel\n sender_id = payload.get(\"sender_id\") or \"\"\n content_parts = payload.get(\"content_parts\") or []\n meta = dict(payload.get(\"meta\") or {})\n if payload.get(\"session_webhook\"):\n meta[\"session_webhook\"] = payload[\"session_webhook\"]\n session_id = self.resolve_session_id(sender_id, meta)\n request = self.build_agent_request_from_user_content(\n channel_id=channel_id,\n sender_id=sender_id,\n session_id=session_id,\n content_parts=content_parts,\n channel_meta=meta,\n )\n if hasattr(request, \"channel_meta\"):\n request.channel_meta = meta\n return request\n\n def to_handle_from_target(self, *, user_id: str, session_id: str) -> str:\n # Key by session_id (short suffix of conversation_id) so cron can\n # use the same session_id to look up stored sessionWebhook.\n return f\"dingtalk:sw:{session_id}\"\n\n def _route_from_handle(self, to_handle: str) -> dict:\n # to_handle:\n # - \"dingtalk:sw:\" -> use stored webhook by key\n # - \"dingtalk:webhook:\" -> direct webhook URL\n # - \"\" (starts with http/https) -> direct webhook URL\n s = (to_handle or \"\").strip()\n if s.startswith(\"http://\") or s.startswith(\"https://\"):\n return {\"session_webhook\": s}\n\n parts = s.split(\":\", 2)\n if len(parts) == 3 and parts[0] == \"dingtalk\":\n kind, ident = parts[1], parts[2]\n if kind == \"sw\":\n return {\"webhook_key\": f\"dingtalk:sw:{ident}\"}\n if kind == \"webhook\":\n return {\"session_webhook\": ident}\n return {\"webhook_key\": s} if s else {}\n\n def _session_webhook_store_path(self) -> Path:\n \"\"\"Path to persist session webhook mapping (for cron after restart).\n\n Uses agent workspace directory if available, otherwise falls back\n to global config directory for backward compatibility.\n \"\"\"\n if self._workspace_dir:\n return self._workspace_dir / \"dingtalk_session_webhooks.json\"\n return get_config_path().parent / \"dingtalk_session_webhooks.json\"\n\n def _load_session_webhook_store_from_disk(self) -> None:\n \"\"\"Load session webhook mapping from disk into memory.\"\"\"\n path = self._session_webhook_store_path()\n if not path.is_file():\n return\n try:\n with open(path, \"r\", encoding=\"utf-8\") as f:\n data = json.load(f)\n if isinstance(data, dict):\n for k, v in data.items():\n if isinstance(v, str) and v:\n self._session_webhook_store[k] = v\n except Exception:\n logger.debug(\n \"dingtalk load session_webhook store from %s failed\",\n path,\n exc_info=True,\n )\n\n def _save_session_webhook_store_to_disk(self) -> None:\n \"\"\"Persist in-memory session webhook store to disk.\"\"\"\n path = self._session_webhook_store_path()\n try:\n path.parent.mkdir(parents=True, exist_ok=True)\n with open(path, \"w\", encoding=\"utf-8\") as f:\n json.dump(\n self._session_webhook_store,\n f,\n indent=2,\n ensure_ascii=False,\n )\n except Exception:\n logger.debug(\n \"dingtalk save session_webhook store to %s failed\",\n path,\n exc_info=True,\n )\n\n async def _save_session_webhook(\n self,\n webhook_key: str,\n session_webhook: str,\n ) -> None:\n if not webhook_key or not session_webhook:\n logger.debug(\n \"dingtalk _save_session_webhook skip: key=%s has_url=%s\",\n bool(webhook_key),\n bool(session_webhook),\n )\n return\n session_in_url = session_param_from_webhook_url(session_webhook)\n logger.info(\n \"dingtalk _save_session_webhook: \"\n \"webhook_key=%s session_from_url=%s\",\n webhook_key,\n session_in_url,\n )\n async with self._session_webhook_lock:\n self._session_webhook_store[webhook_key] = session_webhook\n self._save_session_webhook_store_to_disk()\n\n async def _load_session_webhook(self, webhook_key: str) -> Optional[str]:\n if not webhook_key:\n logger.debug(\"dingtalk _load_session_webhook: empty webhook_key\")\n return None\n async with self._session_webhook_lock:\n out = self._session_webhook_store.get(webhook_key)\n if out is not None:\n logger.info(\n \"dingtalk _load_session_webhook hit: webhook_key=%s \"\n \"session_from_url=%s\",\n webhook_key,\n session_param_from_webhook_url(out),\n )\n return out\n self._load_session_webhook_store_from_disk()\n out = self._session_webhook_store.get(webhook_key)\n if out is not None:\n logger.info(\n \"dingtalk _load_session_webhook hit(disk): webhook_key=%s \"\n \"session_from_url=%s\",\n webhook_key,\n session_param_from_webhook_url(out),\n )\n return out\n logger.info(\n \"dingtalk _load_session_webhook miss: webhook_key=%s\",\n webhook_key,\n )\n return None\n\n # ---------------------------\n # Reply via stream thread\n # ---------------------------\n\n def _try_accept_message(self, msg_id: str) -> bool:\n \"\"\"Return True if accepted; False if duplicate (msg_id already in\n progress). Thread-safe; handler in stream thread.\n \"\"\"\n with self._processing_message_ids_lock:\n if msg_id and msg_id in self._processing_message_ids:\n logger.info(\n \"dingtalk dedup reject: msg_id already in progress \"\n \"msg_id=%r\",\n msg_id,\n )\n return False\n if msg_id:\n self._processing_message_ids.add(msg_id)\n logger.debug(\n \"dingtalk dedup accept: msg_id=%r in_flight_count=%s\",\n msg_id or \"(empty)\",\n len(self._processing_message_ids),\n )\n return True\n\n def _release_message_ids(self, msg_ids: List[str]) -> None:\n \"\"\"Release msg ids after reply.\"\"\"\n if not msg_ids:\n return\n with self._processing_message_ids_lock:\n for mid in msg_ids:\n if mid:\n self._processing_message_ids.discard(mid)\n logger.debug(\n \"dingtalk dedup release: msg_ids=%s in_flight_count=%s\",\n msg_ids,\n len(self._processing_message_ids),\n )\n\n @staticmethod\n def _safe_set_future_result(\n future: \"asyncio.Future[str]\",\n text: str,\n ) -> None:\n \"\"\"Set future result only if not already done (idempotent).\n\n Guards against InvalidStateError when _ack_early already resolved\n the future before _reply_sync_batch is called at stream end.\n \"\"\"\n if not future.done():\n future.set_result(text)\n\n def _reply_sync(self, meta: Dict[str, Any], text: str) -> None:\n \"\"\"Resolve reply_future on the stream thread's loop so process()\n can continue and reply.\n \"\"\"\n reply_loop = meta.get(\"reply_loop\")\n reply_future = meta.get(\"reply_future\")\n if reply_loop is None or reply_future is None:\n return\n reply_loop.call_soon_threadsafe(\n self._safe_set_future_result,\n reply_future,\n text,\n )\n if \"_message_ids\" in meta:\n ids = meta[\"_message_ids\"]\n else:\n ids = [meta.get(\"message_id\")] if meta.get(\"message_id\") else []\n self._release_message_ids(ids)\n\n def _reply_sync_batch(self, meta: Dict[str, Any], text: str) -> None:\n \"\"\"\n Resolve all reply_futures (merged batch) so every waiter unblocks.\n \"\"\"\n lst = meta.get(\"_reply_futures_list\") or []\n if lst:\n for reply_loop, reply_future in lst:\n if reply_loop and reply_future:\n reply_loop.call_soon_threadsafe(\n self._safe_set_future_result,\n reply_future,\n text,\n )\n ids = meta[\"_message_ids\"] if \"_message_ids\" in meta else []\n self._release_message_ids(ids)\n else:\n self._reply_sync(meta, text)\n\n def _ack_early(self, meta: Dict[str, Any], text: str) -> None:\n \"\"\"Resolve reply_futures immediately for streaming paths (AI card /\n sessionWebhook) WITHOUT releasing dedup msg_ids.\n\n Unblocks the DingTalk stream callback handler so it can return\n STATUS_OK to the SDK quickly, preventing DingTalk retry storms\n during long LLM generation. Dedup msg_ids are released later by\n _reply_sync_batch once streaming fully completes, so any DingTalk\n re-delivery before that point is still correctly rejected.\n \"\"\"\n lst = meta.get(\"_reply_futures_list\") or []\n if lst:\n for reply_loop, reply_future in lst:\n if reply_loop and reply_future:\n reply_loop.call_soon_threadsafe(\n self._safe_set_future_result,\n reply_future,\n text,\n )\n futures_count = len(lst)\n else:\n reply_loop = meta.get(\"reply_loop\")\n reply_future = meta.get(\"reply_future\")\n if reply_loop and reply_future:\n reply_loop.call_soon_threadsafe(\n self._safe_set_future_result,\n reply_future,\n text,\n )\n futures_count = 1 if meta.get(\"reply_future\") else 0\n logger.debug(\n \"dingtalk _ack_early: text=%r futures_count=%s\",\n text,\n futures_count,\n )\n\n def _get_session_webhook(\n self,\n meta: Optional[Dict[str, Any]],\n ) -> Optional[str]:\n \"\"\"Get sessionWebhook from meta (persisted) or incoming_message.\"\"\"\n if not meta:\n return None\n out = meta.get(\"session_webhook\") or meta.get(\"sessionWebhook\")\n if out:\n return out\n inc = meta.get(\"incoming_message\")\n if inc is None:\n return None\n return getattr(inc, \"sessionWebhook\", None) or getattr(\n inc,\n \"session_webhook\",\n None,\n )\n\n def _parts_to_single_text(\n self,\n parts: List[OutgoingContentPart],\n bot_prefix: str = \"\",\n ) -> str:\n \"\"\"Build one reply text from parts\n (same logic as send_content_parts body).\n \"\"\"\n text_parts: List[str] = []\n for p in parts:\n t = getattr(p, \"type\", None)\n if t == ContentType.TEXT and getattr(p, \"text\", None):\n text_parts.append(p.text or \"\")\n elif t == ContentType.REFUSAL and getattr(p, \"refusal\", None):\n text_parts.append(p.refusal or \"\")\n elif t == ContentType.IMAGE and getattr(p, \"image_url\", None):\n text_parts.append(f\"[Image: {p.image_url}]\")\n elif t == ContentType.VIDEO and getattr(p, \"video_url\", None):\n text_parts.append(f\"[Video: {p.video_url}]\")\n elif t == ContentType.FILE and (\n getattr(p, \"file_url\", None) or getattr(p, \"file_id\", None)\n ):\n url_or_id = getattr(p, \"file_url\", None) or getattr(\n p,\n \"file_id\",\n None,\n )\n text_parts.append(f\"[File: {url_or_id}]\")\n elif t == ContentType.AUDIO and getattr(p, \"data\", None):\n text_parts.append(\"[Audio]\")\n body = \"\\n\".join(text_parts) if text_parts else \"\"\n if bot_prefix and body:\n body = bot_prefix + body\n return body\n\n async def _send_payload_via_session_webhook(\n self,\n session_webhook: str,\n payload: Dict[str, Any],\n ) -> bool:\n \"\"\"Send one message via DingTalk sessionWebhook with given JSON\n payload (e.g. msgtype text, markdown, image, file). Returns True\n on success.\n \"\"\"\n msgtype = payload.get(\"msgtype\", \"?\")\n session_in_url = session_param_from_webhook_url(session_webhook)\n wh = (\n session_webhook[:60] + \"...\"\n if len(session_webhook) > 60\n else session_webhook\n )\n logger.info(\n \"dingtalk sessionWebhook send: msgtype=%s webhook_host=%s \"\n \"session_from_url=%s\",\n msgtype,\n wh,\n session_in_url,\n )\n logger.debug(\"dingtalk sessionWebhook send: payload=%s\", payload)\n try:\n async with self._http.post(\n session_webhook,\n json=payload,\n headers={\n \"Content-Type\": \"application/json; charset=utf-8\",\n },\n ) as resp:\n body_text = await resp.text()\n if resp.status >= 400:\n logger.warning(\n \"dingtalk sessionWebhook POST failed: msgtype=%s \"\n \"status=%s body=%s\",\n msgtype,\n resp.status,\n body_text[:500],\n )\n return False\n try:\n body_json = json.loads(body_text) if body_text else {}\n except json.JSONDecodeError:\n body_json = {}\n errcode = body_json.get(\"errcode\", 0)\n errmsg = body_json.get(\"errmsg\", \"\")\n if errcode != 0:\n logger.warning(\n \"dingtalk sessionWebhook POST API error: msgtype=%s \"\n \"session_from_url=%s errcode=%s errmsg=%s body=%s\",\n msgtype,\n session_in_url,\n errcode,\n errmsg,\n body_text[:300],\n )\n return False\n logger.info(\n \"dingtalk sessionWebhook POST ok: msgtype=%s status=%s \"\n \"errcode=%s\",\n msgtype,\n resp.status,\n errcode,\n )\n return True\n except Exception:\n logger.exception(\n f\"dingtalk sessionWebhook POST failed: msgtype={msgtype}\",\n )\n return False\n\n async def _send_via_session_webhook(\n self,\n session_webhook: str,\n body: str,\n bot_prefix: str = \"\",\n ) -> bool:\n \"\"\"Send one text message via DingTalk sessionWebhook. Returns True\n on success.\"\"\"\n text = (bot_prefix + body) if body else bot_prefix\n if len(text) > 3500:\n payload = {\"msgtype\": \"text\", \"text\": {\"content\": text}}\n else:\n norm = dingtalk_markdown.normalize_dingtalk_markdown(text)\n payload = {\n \"msgtype\": \"markdown\",\n \"markdown\": {\n \"title\": f\"💬{norm[:10]}...\",\n \"text\": norm,\n },\n }\n return await self._send_payload_via_session_webhook(\n session_webhook,\n payload,\n )\n\n async def _upload_media(\n self,\n data: bytes,\n media_type: str,\n filename: Optional[str] = None,\n content_type: Optional[str] = None,\n ) -> Optional[str]:\n \"\"\"Upload media via DingTalk Open API and return media_id.\"\"\"\n logger.info(\n \"dingtalk upload_media: type=%s size=%s filename=%s\",\n media_type,\n len(data),\n filename or \"(none)\",\n )\n token = await self._get_access_token()\n # Use oapi media upload (api.dingtalk.com upload returns 404).\n # Doc:\n # https://open.dingtalk.com/document/development/upload-media-files\n url = (\n \"https://oapi.dingtalk.com/media/upload\"\n f\"?access_token={token}&type={media_type}\"\n )\n ext = \"jpg\" if media_type == \"image\" else \"bin\"\n name = filename or f\"upload.{ext}\"\n logger.info(f\"dingtalk upload_media: name={name}\")\n form = aiohttp.FormData()\n form.add_field(\n \"media\",\n data,\n filename=name,\n content_type=content_type\n or mimetypes.guess_type(name)[0]\n or \"application/octet-stream\",\n )\n try:\n async with self._http.post(url, data=form) as resp:\n result = await resp.json(content_type=None)\n if resp.status >= 400:\n logger.warning(\n \"dingtalk upload_media failed: type=%s status=%s \"\n \"body=%s\",\n media_type,\n resp.status,\n result,\n )\n return None\n errcode = result.get(\"errcode\", 0)\n if errcode != 0:\n logger.warning(\n \"dingtalk upload_media oapi err: type=%s errcode=%s\",\n media_type,\n errcode,\n )\n return None\n media_id = (\n result.get(\"media_id\")\n or result.get(\"mediaId\")\n or (result.get(\"result\") or {}).get(\"media_id\")\n or (result.get(\"result\") or {}).get(\"mediaId\")\n )\n if media_id:\n mid_preview = (\n media_id[:32] + \"...\"\n if len(media_id) > 32\n else media_id\n )\n logger.info(\n \"dingtalk upload_media ok: type=%s media_id=%s\",\n media_type,\n mid_preview,\n )\n else:\n logger.warning(\n \"dingtalk upload_media: no media_id in response\",\n )\n return media_id\n except Exception:\n logger.exception(\n \"dingtalk upload_media failed: type=%s filename=%s\",\n media_type,\n filename,\n )\n return None\n\n async def _fetch_bytes_from_url(self, url: str) -> Optional[bytes]:\n \"\"\"Download binary content from URL. Returns None on failure.\n\n Supports http(s):// and file:// URLs. file:// is read from local disk.\n \"\"\"\n logger.info(\n \"dingtalk fetch_bytes_from_url: url=%s\",\n url[:80] + \"...\" if len(url) > 80 else url,\n )\n try:\n path = file_url_to_local_path(url)\n if path is not None:\n data = await asyncio.to_thread(Path(path).read_bytes)\n logger.info(\n \"dingtalk fetch_bytes_from_url ok: size=%s (file)\",\n len(data),\n )\n return data\n if url.strip().lower().startswith(\"file:\"):\n logger.warning(\n f\"dingtalk fetch_bytes_from_url: empty file path for \"\n f\"url={url[:80]}\",\n )\n return None\n async with self._http.get(url) as resp:\n if resp.status >= 400:\n logger.warning(\n \"dingtalk fetch_bytes_from_url failed: status=%s\",\n resp.status,\n )\n return None\n data = await resp.read()\n logger.info(\n \"dingtalk fetch_bytes_from_url ok: size=%s\",\n len(data),\n )\n return data\n except Exception:\n logger.exception(\n \"dingtalk fetch_bytes_from_url failed: url=%s\",\n url[:80],\n )\n return None\n\n async def _get_session_webhook_for_send(\n self,\n to_handle: str,\n meta: Optional[Dict[str, Any]],\n ) -> Optional[str]:\n \"\"\"Resolve session_webhook for sending. Prefer current request's\n webhook (meta); only use store for proactive send (e.g. cron).\n When this is a reply to a user message (meta has reply_future or\n conversation_id) and meta has no session_webhook, do not fall back\n to store so we never use a stale/expired webhook.\n \"\"\"\n m = meta or {}\n webhook = m.get(\"session_webhook\") or m.get(\"sessionWebhook\")\n if webhook:\n logger.info(\n \"dingtalk _get_session_webhook_for_send: to_handle=%s \"\n \"source=meta session_from_url=%s\",\n to_handle[:40] if to_handle else \"\",\n session_param_from_webhook_url(webhook),\n )\n return webhook\n route = self._route_from_handle(to_handle)\n webhook = route.get(\"session_webhook\")\n if webhook:\n logger.info(\n \"dingtalk _get_session_webhook_for_send: to_handle=%s \"\n \"source=route session_from_url=%s\",\n to_handle[:40] if to_handle else \"\",\n session_param_from_webhook_url(webhook),\n )\n return webhook\n # Current-request context but no webhook in meta: do not use store\n # (could be expired after long idle).\n if m.get(\"reply_future\") is not None or m.get(\"conversation_id\"):\n logger.info(\n \"dingtalk _get_session_webhook_for_send: to_handle=%s \"\n \"current request has no session_webhook, skip store\",\n to_handle[:40] if to_handle else \"\",\n )\n return None\n key = route.get(\"webhook_key\")\n if key:\n webhook = await self._load_session_webhook(key)\n if webhook:\n logger.info(\n \"dingtalk _get_session_webhook_for_send: to_handle=%s \"\n \"source=store webhook_key=%s\",\n to_handle[:40] if to_handle else \"\",\n key,\n )\n return webhook\n logger.info(\n \"dingtalk _get_session_webhook_for_send: to_handle=%s source=none\",\n to_handle[:40] if to_handle else \"\",\n )\n return None\n\n def _map_upload_type(self, part: OutgoingContentPart) -> Optional[str]:\n \"\"\"\n Map OutgoingContentPart type to DingTalk media/upload type.\n DingTalk upload type must be one of: image | voice | video | file\n \"\"\"\n ptype = getattr(part, \"type\", None)\n if ptype in (ContentType.TEXT, ContentType.REFUSAL, None):\n return None # no upload\n if ptype == ContentType.IMAGE:\n return \"image\"\n if ptype == ContentType.AUDIO:\n return \"voice\"\n if ptype == ContentType.VIDEO:\n return \"video\"\n if ptype == ContentType.FILE:\n return \"file\"\n return \"file\"\n\n async def _send_media_part_via_webhook(\n self,\n session_webhook: str,\n part: OutgoingContentPart,\n ) -> bool:\n \"\"\"Upload and send one media part via session webhook.\"\"\"\n ptype = getattr(part, \"type\", None)\n upload_type = self._map_upload_type(part)\n\n logger.info(\n \"dingtalk _send_media_part_via_webhook: type=%s upload_type=%s\",\n ptype,\n upload_type,\n )\n\n # text/auto/refusal: no-op here (text is handled elsewhere)\n if upload_type is None:\n return True\n\n # ---------- image special-case: if public picURL, send directly ------\n if upload_type == \"image\":\n url = getattr(part, \"image_url\", None) or \"\"\n url = (url or \"\").strip() if isinstance(url, str) else \"\"\n if self._is_public_http_url(url):\n payload = {\"msgtype\": \"image\", \"image\": {\"picURL\": url}}\n return await self._send_payload_via_session_webhook(\n session_webhook,\n payload,\n )\n # else: fallthrough to upload-by-bytes then send as file\n # (your existing fallback)\n\n # ---------- decide filename/ext ----------\n default_name = {\n \"image\": \"image.png\",\n \"voice\": \"audio.amr\",\n \"video\": \"video.mp4\",\n \"file\": \"file.bin\",\n }.get(upload_type, \"file.bin\")\n filename, ext = self._guess_filename_and_ext(\n part,\n default=default_name,\n )\n # AudioContent URL is in part.data; derive filename/ext for m4a etc.\n if ptype == ContentType.AUDIO:\n data_attr = getattr(part, \"data\", None)\n if isinstance(data_attr, str) and (\n data_attr.startswith(\"http\") or data_attr.startswith(\"file:\")\n ):\n try:\n path = urlparse(data_attr).path\n base = os.path.basename(path)\n if base and \".\" in base:\n filename = base\n ext = base.rsplit(\".\", 1)[-1].lower()\n except Exception:\n pass\n if upload_type == \"video\" and ext not in (\"mp4\",):\n upload_type = \"file\"\n elif upload_type == \"voice\":\n upload_type = \"file\"\n\n # ---------- if already has media id ----------\n # for file you used file_id;\n # keep compatibility but also accept media_id\n media_id = (\n getattr(part, \"media_id\", None)\n or getattr(part, \"mediaId\", None)\n or getattr(part, \"file_id\", None)\n )\n if media_id:\n media_id = str(media_id).strip()\n if not media_id:\n return False\n\n if upload_type == \"image\":\n # sendBySession supports image by picURL;\n # but if we only have mediaId, send as file\n payload = {\n \"msgtype\": \"file\",\n \"file\": {\n \"mediaId\": media_id,\n \"fileType\": ext,\n \"fileName\": filename,\n },\n }\n return await self._send_payload_via_session_webhook(\n session_webhook,\n payload,\n )\n\n if upload_type == \"voice\":\n # sendBySession returns 400105 \"unsupported msgtype\" for voice.\n payload = {\n \"msgtype\": \"file\",\n \"file\": {\n \"mediaId\": media_id,\n \"fileType\": ext,\n \"fileName\": filename,\n },\n }\n return await self._send_payload_via_session_webhook(\n session_webhook,\n payload,\n )\n\n if upload_type == \"video\":\n pic_media_id = (\n getattr(part, \"pic_media_id\", None)\n or getattr(part, \"picMediaId\", None)\n or \"\"\n )\n pic_media_id = (pic_media_id or \"\").strip()\n if pic_media_id:\n duration = getattr(part, \"duration\", None)\n if duration is None:\n duration = 1\n payload = {\n \"msgtype\": \"video\",\n \"video\": {\n \"videoMediaId\": media_id,\n \"duration\": str(int(duration)),\n \"picMediaId\": pic_media_id,\n },\n }\n return await self._send_payload_via_session_webhook(\n session_webhook,\n payload,\n )\n # No picMediaId: send as file so user still gets the video\n payload = {\n \"msgtype\": \"file\",\n \"file\": {\n \"mediaId\": media_id,\n \"fileType\": ext,\n \"fileName\": filename,\n },\n }\n return await self._send_payload_via_session_webhook(\n session_webhook,\n payload,\n )\n\n # file\n payload = {\n \"msgtype\": \"file\",\n \"file\": {\n \"mediaId\": media_id,\n \"fileType\": ext,\n \"fileName\": filename,\n },\n }\n return await self._send_payload_via_session_webhook(\n session_webhook,\n payload,\n )\n\n # ---------- load bytes from base64 or url ----------\n data: Optional[bytes] = None\n url = (\n getattr(part, \"file_url\", None)\n or getattr(part, \"image_url\", None)\n or getattr(part, \"video_url\", None)\n or \"\"\n )\n # AudioContent stores URL in \"data\" (renderer _blocks_to_parts)\n if not url and ptype == ContentType.AUDIO:\n data_attr = getattr(part, \"data\", None)\n if isinstance(data_attr, str) and (\n data_attr.startswith(\"http\") or data_attr.startswith(\"file:\")\n ):\n url = data_attr\n url = (url or \"\").strip() if isinstance(url, str) else \"\"\n raw_b64 = None\n if (\n isinstance(url, str)\n and url.startswith(\"data:\")\n and \"base64,\" in url\n ):\n raw_b64 = url\n url = \"\"\n if not raw_b64:\n raw_b64 = getattr(part, \"base64\", None)\n\n if raw_b64:\n if isinstance(raw_b64, str) and raw_b64.startswith(\"data:\"):\n data, mime = parse_data_url(raw_b64)\n content_type_for_upload = (\n mime or getattr(part, \"mime_type\", None) or \"\"\n ).strip()\n if mime and not getattr(part, \"filename\", None):\n ext_guess = (mimetypes.guess_extension(mime) or \"\").lstrip(\n \".\",\n ) or \"\"\n if ext_guess:\n filename = f\"upload.{ext_guess}\"\n ext = ext_guess\n else:\n data = base64.b64decode(raw_b64, validate=False)\n content_type_for_upload = (\n getattr(part, \"mime_type\", None) or \"\"\n ).strip()\n else:\n content_type_for_upload = (\n getattr(part, \"mime_type\", None) or \"\"\n ).strip()\n if not data and url:\n data = await self._fetch_bytes_from_url(url)\n\n if not data:\n logger.warning(\n \"dingtalk media part: no data to upload (empty file?), \"\n \"type=%s\",\n ptype,\n )\n return False\n\n # ---------- upload ----------\n media_id = await self._upload_media(\n data,\n upload_type, # image | voice | video | file\n filename=filename,\n content_type=content_type_for_upload or None,\n )\n if not media_id:\n return False\n\n # ---------- send ----------\n if upload_type == \"image\":\n # no public url -> safest is send as file (your current behavior)\n payload = {\n \"msgtype\": \"file\",\n \"file\": {\n \"mediaId\": media_id,\n \"fileType\": ext,\n \"fileName\": filename,\n },\n }\n return await self._send_payload_via_session_webhook(\n session_webhook,\n payload,\n )\n\n if upload_type == \"voice\":\n # sendBySession returns 400105 for voice; send as file.\n payload = {\n \"msgtype\": \"file\",\n \"file\": {\n \"mediaId\": media_id,\n \"fileType\": ext,\n \"fileName\": filename,\n },\n }\n return await self._send_payload_via_session_webhook(\n session_webhook,\n payload,\n )\n\n if upload_type == \"video\":\n pic_media_id = (\n getattr(part, \"pic_media_id\", None)\n or getattr(part, \"picMediaId\", None)\n or \"\"\n ).strip()\n if pic_media_id:\n duration = getattr(part, \"duration\", None)\n if duration is None:\n duration = 1\n payload = {\n \"msgtype\": \"video\",\n \"video\": {\n \"videoMediaId\": media_id,\n \"duration\": str(int(duration)),\n \"picMediaId\": pic_media_id,\n },\n }\n return await self._send_payload_via_session_webhook(\n session_webhook,\n payload,\n )\n # No picMediaId: send as file so user still gets the video\n payload = {\n \"msgtype\": \"file\",\n \"file\": {\n \"mediaId\": media_id,\n \"fileType\": ext,\n \"fileName\": filename,\n },\n }\n return await self._send_payload_via_session_webhook(\n session_webhook,\n payload,\n )\n\n payload = {\n \"msgtype\": \"file\",\n \"file\": {\n \"mediaId\": media_id,\n \"fileType\": ext,\n \"fileName\": filename,\n },\n }\n return await self._send_payload_via_session_webhook(\n session_webhook,\n payload,\n )\n\n async def send_content_parts(\n self,\n to_handle: str,\n parts: List[OutgoingContentPart],\n meta: Optional[Dict[str, Any]] = None,\n ) -> None:\n \"\"\"Build one body from parts. If meta has reply_future (reply path),\n deliver via _reply_sync; otherwise proactive send via send().\n When session_webhook is available, sends text then image/file\n messages (upload media first for image/file).\n \"\"\"\n text_parts = []\n media_parts: List[OutgoingContentPart] = []\n for p in parts:\n t = getattr(p, \"type\", None) or (\n p.get(\"type\") if isinstance(p, dict) else None\n )\n text_val = getattr(p, \"text\", None) or (\n p.get(\"text\") if isinstance(p, dict) else None\n )\n refusal_val = getattr(p, \"refusal\", None) or (\n p.get(\"refusal\") if isinstance(p, dict) else None\n )\n if t == ContentType.TEXT and text_val:\n text_parts.append(text_val or \"\")\n elif t == ContentType.REFUSAL and refusal_val:\n text_parts.append(refusal_val or \"\")\n elif t == ContentType.IMAGE:\n media_parts.append(p)\n elif t == ContentType.FILE:\n media_parts.append(p)\n elif t == ContentType.VIDEO:\n media_parts.append(p)\n elif t == ContentType.AUDIO:\n media_parts.append(p)\n body = \"\\n\".join(text_parts) if text_parts else \"\"\n prefix = (meta or {}).get(\"bot_prefix\", \"\") or \"\"\n if prefix and body:\n body = prefix + body\n elif prefix and not body and not media_parts:\n body = prefix\n m = meta or {}\n session_webhook = await self._get_session_webhook_for_send(\n to_handle,\n meta,\n )\n logger.info(\n \"dingtalk send_content_parts: to_handle=%s has_webhook=%s \"\n \"text_parts=%s media_parts=%s\",\n to_handle[:40] if to_handle else \"\",\n bool(session_webhook),\n len(text_parts),\n len(media_parts),\n )\n if session_webhook and (body.strip() or media_parts):\n if body.strip():\n logger.info(\"dingtalk send_content_parts: sending text body\")\n await self._send_via_session_webhook(\n session_webhook,\n body.strip(),\n bot_prefix=\"\",\n )\n for i, part in enumerate(media_parts):\n logger.info(\n \"dingtalk send_content_parts: \"\n \"sending media part %s/%s type=%s\",\n i + 1,\n len(media_parts),\n getattr(part, \"type\", None),\n )\n ok = await self._send_media_part_via_webhook(\n session_webhook,\n part,\n )\n logger.info(\n \"dingtalk send_content_parts: media part %s result=%s\",\n i + 1,\n ok,\n )\n if m.get(\"reply_loop\") is not None and m.get(\"reply_future\"):\n self._reply_sync(m, SENT_VIA_WEBHOOK)\n return\n if not body and media_parts:\n for p in media_parts:\n if getattr(p, \"type\", None) == ContentType.IMAGE and getattr(\n p,\n \"image_url\",\n None,\n ):\n text_parts.append(f\"[Image: {p.image_url}]\")\n elif getattr(p, \"type\", None) == ContentType.FILE and (\n getattr(p, \"file_url\", None) or getattr(p, \"file_id\", None)\n ):\n furl = getattr(p, \"file_url\", None)\n fid = getattr(p, \"file_id\", None)\n url_or_id = furl or fid\n text_parts.append(f\"[File: {url_or_id}]\")\n body = \"\\n\".join(text_parts) if text_parts else \"\"\n if prefix and body:\n body = prefix + body\n if (\n m.get(\"reply_loop\") is not None\n and m.get(\"reply_future\") is not None\n ):\n self._reply_sync(m, body)\n else:\n await self.send(to_handle, body.strip() or prefix, meta)\n\n def merge_native_items(self, items: List[Any]) -> Any:\n \"\"\"Merge payloads (content_parts + meta) for DingTalk.\"\"\"\n return self._merge_native(items)\n\n def _on_debounce_buffer_append(\n self,\n key: str,\n payload: Any,\n existing_items: List[Any],\n ) -> None:\n \"\"\"Unblock previous reply_future so stream callback does not block.\"\"\"\n del key\n del payload\n if not existing_items:\n return\n prev = existing_items[-1]\n pm = prev.get(\"meta\") or {} if isinstance(prev, dict) else {}\n if (\n pm.get(\"reply_loop\") is not None\n and pm.get(\"reply_future\") is not None\n ):\n self._reply_sync(pm, SENT_VIA_WEBHOOK)\n\n async def _run_process_loop(\n self,\n request: Any,\n to_handle: str,\n send_meta: Dict[str, Any],\n ) -> None:\n \"\"\"Use webhook multi-message send instead of default loop.\"\"\"\n del to_handle\n\n sender_id = getattr(request, \"user_id\", \"\") or \"\"\n is_group = bool((send_meta or {}).get(\"is_group\", False))\n allowed, error_msg = self._check_allowlist(\n sender_id,\n is_group,\n )\n if not allowed:\n logger.info(\n \"dingtalk allowlist blocked: sender=%s is_group=%s\",\n sender_id,\n is_group,\n )\n session_webhook = self._get_session_webhook(send_meta)\n if session_webhook:\n await self._send_via_session_webhook(\n session_webhook,\n self.bot_prefix + (error_msg or \"\"),\n bot_prefix=\"\",\n )\n else:\n self._reply_sync_batch(\n send_meta,\n self.bot_prefix + (error_msg or \"\"),\n )\n return\n\n if not self._check_group_mention(is_group, send_meta):\n return\n\n logger.info(\n \"dingtalk _run_process_loop: send_meta has_sw=%s \"\n \"req.channel_meta has_sw=%s\",\n bool((send_meta or {}).get(\"session_webhook\")),\n bool(\n (getattr(request, \"channel_meta\", None) or {}).get(\n \"session_webhook\",\n ),\n ),\n )\n # Keep only JSON-serializable keys on request for tracing; pass full\n # send_meta as reply_meta for _reply_sync_batch / send_content_parts.\n _NON_SERIALIZABLE = (\n \"incoming_message\",\n \"reply_loop\",\n \"reply_future\",\n \"_reply_futures_list\",\n )\n safe_meta = {\n k: v\n for k, v in (send_meta or {}).items()\n if k not in _NON_SERIALIZABLE\n }\n request.channel_meta = safe_meta\n logger.info(\n \"dingtalk _run_process_loop: after set channel_meta has_sw=%s\",\n bool((request.channel_meta or {}).get(\"session_webhook\")),\n )\n try:\n await self._process_one_request(request, reply_meta=send_meta)\n except Exception as e:\n logger.exception(\"dingtalk _process_one_request failed\")\n err_msg = str(e).strip() or \"An error occurred while processing.\"\n self._reply_sync_batch(\n send_meta,\n self.bot_prefix + f\"Error: {err_msg}\",\n )\n raise\n\n async def _process_one_request(\n self,\n request: Any,\n reply_meta: Optional[Dict[str, Any]] = None,\n ) -> None: # pylint: disable=too-many-branches\n meta = getattr(request, \"channel_meta\", None) or {}\n reply_meta = reply_meta or meta\n session_webhook = self._get_session_webhook(meta)\n use_multi = bool(session_webhook)\n logger.debug(\n \"dingtalk _process_one_request: has_session_webhook=%s\",\n use_multi,\n )\n logger.info(\n \"dingtalk _process_one_request: meta has_sw=%s use_multi=%s\",\n bool(meta.get(\"session_webhook\")),\n use_multi,\n )\n last_response = None\n accumulated_parts: list = []\n event_count = 0\n # _acked_early: reply_future already resolved so DingTalk handler\n # returned STATUS_OK quickly; msg_ids still held for dedup until\n # streaming fully completes (_reply_sync_batch at the end).\n _acked_early = False\n conversation_id = str(meta.get(\"conversation_id\") or \"\")\n use_ai_card = self._ai_card_enabled() and bool(conversation_id)\n logger.info(\n \"dingtalk ai card gate: enabled=%s \"\n \"message_type=%s has_template=%s \"\n \"has_robot=%s has_conversation=%s\",\n use_ai_card,\n self.message_type,\n bool(self.card_template_id),\n bool(self.robot_code),\n bool(conversation_id),\n )\n card: Optional[ActiveAICard] = None\n card_full_text = \"\"\n if use_ai_card:\n try:\n card = await self._create_ai_card(\n conversation_id,\n meta=meta,\n inbound=True,\n )\n # AI card created: ACK DingTalk immediately so the stream\n # callback handler returns STATUS_OK without waiting for\n # the full LLM response. This stops DingTalk retry storms\n # on long-form generations. Dedup msg_ids are kept until\n # streaming finishes (see _reply_sync_batch below).\n self._ack_early(reply_meta, SENT_VIA_AI_CARD)\n _acked_early = True\n logger.info(\n \"dingtalk _ack_early: AI card created, \"\n \"handler unblocked early\",\n )\n except Exception:\n logger.exception(\n \"dingtalk create ai card failed, fallback to markdown\",\n )\n use_ai_card = False\n\n # Store sessionWebhook (keyed by conversation).\n if session_webhook:\n fallback_sid = f\"{self.channel}:{request.user_id}\"\n webhook_key = self.to_handle_from_target(\n user_id=request.user_id or \"\",\n session_id=request.session_id or fallback_sid,\n )\n logger.info(\n \"dingtalk _process_one_request: storing webhook \"\n \"session_id=%s conversation_id=%s webhook_key=%s\",\n getattr(request, \"session_id\", None),\n meta.get(\"conversation_id\"),\n webhook_key,\n )\n await self._save_session_webhook(\n webhook_key,\n session_webhook,\n )\n\n async for event in self._process(request):\n event_count += 1\n obj = getattr(event, \"object\", None)\n status = getattr(event, \"status\", None)\n ev_type = getattr(event, \"type\", None)\n logger.debug(\n \"dingtalk event #%s: object=%s status=%s type=%s\",\n event_count,\n obj,\n status,\n ev_type,\n )\n if obj == \"message\" and status == RunStatus.Completed:\n parts = self._message_to_content_parts(event)\n logger.info(\n f\"dingtalk completed message: type={ev_type} \"\n f\"parts_count={len(parts)}\",\n )\n body = self._parts_to_single_text(\n parts,\n bot_prefix=\"\",\n )\n if use_ai_card and card:\n next_card_text = self._merge_ai_card_text(\n card_full_text,\n body,\n )\n try:\n if next_card_text != card_full_text:\n card_full_text = next_card_text\n await self._stream_ai_card(\n card,\n card_full_text,\n finalize=False,\n )\n except Exception:\n logger.exception(\n \"dingtalk stream ai card failed,\"\n \" fallback to markdown\",\n )\n await self._mark_card_failed(conversation_id)\n use_ai_card = False\n fallback_body = body.strip() or card_full_text.strip()\n if use_multi and session_webhook and fallback_body:\n await self._send_via_session_webhook(\n session_webhook,\n fallback_body,\n bot_prefix=\"\",\n )\n else:\n accumulated_parts.extend(parts)\n elif use_multi and parts and session_webhook:\n if body.strip():\n await self._send_via_session_webhook(\n session_webhook,\n body.strip(),\n bot_prefix=\"\",\n )\n # First webhook message sent: ACK DingTalk early so\n # handler returns STATUS_OK without waiting for the\n # full LLM response.\n if not _acked_early:\n self._ack_early(reply_meta, SENT_VIA_WEBHOOK)\n _acked_early = True\n logger.info(\n \"dingtalk _ack_early: first webhook chunk \"\n \"sent, handler unblocked early\",\n )\n _media_types = (\n ContentType.IMAGE,\n ContentType.FILE,\n ContentType.VIDEO,\n ContentType.AUDIO,\n )\n for part in parts:\n if getattr(part, \"type\", None) in _media_types:\n await self._send_media_part_via_webhook(\n session_webhook,\n part,\n )\n else:\n accumulated_parts.extend(parts)\n elif obj == \"response\":\n last_response = event\n\n logger.info(\n \"dingtalk stream done: event_count=%s parts=%s webhook=%s\",\n event_count,\n len(accumulated_parts),\n use_multi,\n )\n\n err_msg = self._get_response_error_message(last_response)\n if use_ai_card and card:\n final_text = card_full_text or self._build_ai_card_initial_text()\n try:\n if err_msg:\n final_text = self.bot_prefix + f\"Error: {err_msg}\"\n await self._stream_ai_card(card, final_text, finalize=True)\n except Exception:\n logger.exception(\"dingtalk finalize ai card failed\")\n await self._mark_card_failed(conversation_id)\n if use_multi and session_webhook:\n await self._send_via_session_webhook(\n session_webhook,\n final_text,\n bot_prefix=\"\",\n )\n self._reply_sync_batch(reply_meta, SENT_VIA_AI_CARD)\n elif err_msg:\n err_text = self.bot_prefix + f\"Error: {err_msg}\"\n if use_multi and session_webhook:\n await self._send_via_session_webhook(\n session_webhook,\n err_text,\n bot_prefix=\"\",\n )\n self._reply_sync_batch(\n reply_meta,\n SENT_VIA_WEBHOOK if use_multi else err_text,\n )\n elif use_multi:\n self._reply_sync_batch(reply_meta, SENT_VIA_WEBHOOK)\n elif accumulated_parts:\n sid = getattr(request, \"session_id\", \"\") or \"\"\n to_handle = (\n self.to_handle_from_target(\n user_id=request.user_id or \"\",\n session_id=sid,\n )\n if sid\n else (request.user_id or \"\")\n )\n await self.send_content_parts(\n to_handle,\n accumulated_parts,\n reply_meta,\n )\n elif last_response is None:\n self._reply_sync_batch(\n reply_meta,\n self.bot_prefix\n + \"An error occurred while processing your request.\",\n )\n\n if self._on_reply_sent:\n self._on_reply_sent(\n self.channel,\n request.user_id or \"\",\n request.session_id or f\"{self.channel}:{request.user_id}\",\n )\n\n def _merge_native(self, items: list) -> dict:\n \"\"\"Merge multiple native payloads into one (content_parts + meta).\"\"\"\n if not items:\n return {}\n first = items[0] if isinstance(items[0], dict) else {}\n merged_parts: List[Any] = []\n merged_meta: Dict[str, Any] = dict(first.get(\"meta\") or {})\n\n reply_futures_list: List[tuple] = []\n message_ids_list: List[str] = []\n for it in items:\n payload = it if isinstance(it, dict) else {}\n merged_parts.extend(payload.get(\"content_parts\") or [])\n m = payload.get(\"meta\") or {}\n for k in (\n \"reply_future\",\n \"reply_loop\",\n \"incoming_message\",\n \"conversation_id\",\n \"session_webhook\",\n ):\n if k in m:\n merged_meta[k] = m[k]\n if m.get(\"reply_loop\") and m.get(\"reply_future\"):\n reply_futures_list.append((m[\"reply_loop\"], m[\"reply_future\"]))\n mid = m.get(\"message_id\") or payload.get(\"message_id\")\n if mid:\n message_ids_list.append(str(mid))\n\n merged_meta[\"batched_count\"] = len(items)\n merged_meta[\"_reply_futures_list\"] = reply_futures_list\n merged_meta[\"_message_ids\"] = message_ids_list\n # Queue is FIFO: batch = [oldest, ..., newest]. Prefer\n # session_webhook from newest (last item) so send uses current\n # session.\n out_sw: Optional[str] = None\n for it in reversed(items):\n pl = it if isinstance(it, dict) else {}\n sw = pl.get(\"session_webhook\") or (pl.get(\"meta\") or {}).get(\n \"session_webhook\",\n )\n if sw:\n out_sw = sw\n break\n out = {\n \"channel_id\": first.get(\"channel_id\") or self.channel,\n \"sender_id\": first.get(\"sender_id\") or \"\",\n \"content_parts\": merged_parts,\n \"meta\": merged_meta,\n }\n if out_sw:\n out[\"session_webhook\"] = out_sw\n merged_meta[\"session_webhook\"] = out_sw\n return out\n\n def _run_stream_forever(self) -> None:\n \"\"\"Run stream loop; on _stop_event close websocket and exit cleanly.\"\"\"\n logger.info(\n \"dingtalk stream thread started (client_id=%s)\",\n self.client_id,\n )\n try:\n if self._client:\n asyncio.run(self._stream_loop())\n except Exception:\n logger.exception(\"dingtalk stream thread failed\")\n finally:\n self._stop_event.set()\n logger.info(\"dingtalk stream thread stopped\")\n\n async def _stream_loop(self) -> None:\n \"\"\"\n Drive DingTalkStreamClient.start() and stop when _stop_event is set.\n Closes client.websocket and cancels tasks to avoid \"Task was destroyed\n but it is pending\" on process exit.\n \"\"\"\n client = self._client\n if not client:\n return\n main_task = asyncio.create_task(client.start())\n\n async def stop_watcher() -> None:\n while not self._stop_event.is_set():\n await asyncio.sleep(0.5)\n if client.websocket is not None:\n try:\n await client.websocket.close()\n except Exception:\n pass\n while not main_task.done():\n main_task.cancel()\n await asyncio.sleep(0.1)\n\n watcher_task = asyncio.create_task(stop_watcher())\n try:\n await main_task\n except asyncio.CancelledError:\n pass\n except Exception:\n logger.exception(\"dingtalk stream start() failed\")\n watcher_task.cancel()\n try:\n await watcher_task\n except asyncio.CancelledError:\n pass\n # Cancel remaining tasks (e.g. background_task) so loop exits cleanly\n loop = asyncio.get_running_loop()\n pending = [\n t\n for t in asyncio.all_tasks(loop)\n if t is not asyncio.current_task() and not t.done()\n ]\n for t in pending:\n t.cancel()\n if pending:\n try:\n await asyncio.wait_for(\n asyncio.gather(*pending, return_exceptions=True),\n timeout=4.0,\n )\n except asyncio.TimeoutError:\n pass\n\n async def start(self) -> None:\n if not self.enabled:\n logger.debug(\"disabled by env DINGTALK_CHANNEL_ENABLED=0\")\n return\n self._load_session_webhook_store_from_disk()\n if not self.client_id or not self.client_secret:\n raise RuntimeError(\n \"DINGTALK_CLIENT_ID and DINGTALK_CLIENT_SECRET are required \"\n \"when channel is enabled.\",\n )\n\n self._loop = asyncio.get_running_loop()\n\n credential = dingtalk_stream.Credential(\n self.client_id,\n self.client_secret,\n )\n self._client = dingtalk_stream.DingTalkStreamClient(credential)\n enqueue_cb = getattr(self, \"_enqueue\", None)\n internal_handler = DingTalkChannelHandler(\n main_loop=self._loop,\n enqueue_callback=enqueue_cb,\n bot_prefix=self.bot_prefix,\n download_url_fetcher=self._fetch_and_download_media,\n try_accept_message=self._try_accept_message,\n )\n self._client.register_callback_handler(\n ChatbotMessage.TOPIC,\n internal_handler,\n )\n\n self._stop_event.clear()\n self._stream_thread = threading.Thread(\n target=self._run_stream_forever,\n daemon=True,\n )\n self._stream_thread.start()\n if self._http is None:\n self._http = aiohttp.ClientSession()\n await self._recover_active_cards()\n\n async def stop(self) -> None:\n if not self.enabled:\n return\n self._stop_event.set()\n if self._stream_thread:\n self._stream_thread.join(timeout=3)\n for task in self._debounce_timers.values():\n if task and not task.done():\n task.cancel()\n if self._debounce_timers:\n await asyncio.gather(\n *self._debounce_timers.values(),\n return_exceptions=True,\n )\n self._debounce_timers.clear()\n self._debounce_pending.clear()\n # best-effort finalize active cards before stopping\n for conv_id in list(self._active_cards.keys()):\n try:\n card = self._active_cards.get(conv_id)\n if card and card.state not in (FINISHED, FAILED):\n await self._stream_ai_card(\n card,\n card.last_streamed_content\n or AI_CARD_RECOVERY_FINAL_TEXT,\n finalize=True,\n )\n except Exception:\n logger.debug(\n \"dingtalk finalize active card on stop failed\",\n exc_info=True,\n )\n if self._http is not None:\n await self._http.close()\n self._http = None\n self._client = None\n\n # Note: dingtalk_stream SDK has AICardReplier/CardReplier,\n # but those APIs are request/reply oriented and tied to ChatbotMessage\n # context; here we keep raw OpenAPI calls to support proactive recovery\n # and persisted card lifecycles across restarts.\n def _ai_card_enabled(self) -> bool:\n return (\n self.message_type == \"card\"\n and bool(self.card_template_id)\n and bool(self.robot_code)\n )\n\n def _build_ai_card_initial_text(self) -> str:\n return self.bot_prefix + AI_CARD_PROCESSING_TEXT\n\n def _merge_ai_card_text(self, current: str, incoming: str) -> str:\n current = (current or \"\").strip()\n incoming = (incoming or \"\").strip()\n if not incoming:\n return current\n if not current:\n return incoming\n if incoming == current or current.endswith(incoming):\n return current\n return f\"{current}\\n{incoming}\".strip()\n\n async def _save_active_cards(self) -> None:\n async with self._active_cards_lock:\n self._card_store.save(self._active_cards)\n\n async def _mark_card_failed(self, conversation_id: str) -> None:\n async with self._active_cards_lock:\n card = self._active_cards.get(conversation_id)\n if card:\n card.state = FAILED\n card.last_updated = int(time.time() * 1000)\n self._active_cards.pop(conversation_id, None)\n self._card_store.save(self._active_cards)\n\n async def _create_ai_card(\n self,\n conversation_id: str,\n meta: Optional[Dict[str, Any]] = None,\n inbound: bool = True,\n ) -> Optional[ActiveAICard]:\n if not self._ai_card_enabled() or self._http is None:\n logger.warning(\n \"dingtalk create ai card skipped: enabled=%s http_ready=%s \"\n \"message_type=%s has_template=%s has_robot=%s\",\n self._ai_card_enabled(),\n self._http is not None,\n self.message_type,\n bool(self.card_template_id),\n bool(self.robot_code),\n )\n return None\n token = await self._get_access_token()\n card_instance_id = f\"card_{uuid4()}\"\n meta = meta or {}\n incoming_message = meta.get(\"incoming_message\")\n sender_staff_id = (\n meta.get(\"sender_staff_id\")\n or getattr(incoming_message, \"sender_staff_id\", None)\n or getattr(incoming_message, \"senderStaffId\", None)\n or \"\"\n )\n is_group = bool(meta.get(\"is_group\"))\n create_payload: Dict[str, Any] = {\n \"cardTemplateId\": self.card_template_id,\n \"outTrackId\": card_instance_id,\n \"cardData\": {\"cardParamMap\": {self.card_template_key: \"\"}},\n \"callbackType\": \"STREAM\",\n \"imGroupOpenSpaceModel\": {\"supportForward\": True},\n \"imRobotOpenSpaceModel\": {\"supportForward\": True},\n }\n\n headers = {\n \"Content-Type\": \"application/json\",\n \"x-acs-dingtalk-access-token\": token,\n }\n create_url = \"https://api.dingtalk.com/v1.0/card/instances\"\n logger.info(\n \"dingtalk create ai card: conversation_id=%s is_group=%s \"\n \"sender_staff_id=%s template_id=%s inbound=%s\",\n conversation_id,\n is_group,\n sender_staff_id,\n self.card_template_id,\n inbound,\n )\n async with self._http.post(\n create_url,\n json=create_payload,\n headers=headers,\n ) as resp:\n body = await resp.text()\n logger.info(\n \"dingtalk create ai card response: status=%s body=%s\",\n resp.status,\n body[:1000],\n )\n if resp.status >= 400:\n raise RuntimeError(\n \"create ai card failed\"\n f\" status={resp.status}\"\n f\" body={body[:500]}\",\n )\n\n if is_group:\n open_space_id = f\"dtv1.card//IM_GROUP.{conversation_id}\"\n deliver_payload: Dict[str, Any] = {\n \"outTrackId\": card_instance_id,\n \"userIdType\": 1,\n \"openSpaceId\": open_space_id,\n \"imGroupOpenDeliverModel\": {\n \"robotCode\": self.robot_code,\n },\n }\n else:\n if not sender_staff_id:\n raise RuntimeError(\n \"create ai card failed:\"\n \" missing sender_staff_id for IM_ROBOT\",\n )\n open_space_id = f\"dtv1.card//IM_ROBOT.{sender_staff_id}\"\n deliver_payload = {\n \"outTrackId\": card_instance_id,\n \"userIdType\": 1,\n \"openSpaceId\": open_space_id,\n \"imRobotOpenDeliverModel\": {\n \"spaceType\": \"IM_ROBOT\",\n },\n }\n\n deliver_url = \"https://api.dingtalk.com/v1.0/card/instances/deliver\"\n logger.info(\n \"dingtalk deliver ai card: conversation_id=%s open_space_id=%s\",\n conversation_id,\n open_space_id,\n )\n async with self._http.post(\n deliver_url,\n json=deliver_payload,\n headers=headers,\n ) as resp:\n deliver_body = await resp.text()\n logger.info(\n \"dingtalk deliver ai card response: status=%s body=%s\",\n resp.status,\n deliver_body[:1000],\n )\n if resp.status >= 400:\n raise RuntimeError(\n \"deliver ai card failed\"\n f\" status={resp.status}\"\n f\" body={deliver_body[:500]}\",\n )\n\n try:\n deliver_data = json.loads(deliver_body) if deliver_body else {}\n except json.JSONDecodeError:\n deliver_data = {}\n result = (\n deliver_data.get(\"result\")\n if isinstance(deliver_data, dict)\n else None\n )\n if isinstance(result, list):\n deliver_results = result\n elif isinstance(result, dict):\n deliver_results = result.get(\"deliverResults\")\n else:\n deliver_results = None\n if isinstance(deliver_results, list):\n failed = [\n item\n for item in deliver_results\n if isinstance(item, dict) and not item.get(\"success\", False)\n ]\n if failed:\n err = failed[0]\n raise RuntimeError(\n \"deliver ai card failed: \"\n f\"spaceId={err.get('spaceId')} \"\n f\"spaceType={err.get('spaceType')} \"\n f\"errorMsg={err.get('errorMsg')}\",\n )\n logger.info(\n \"dingtalk create ai card ok:\"\n \" conversation_id=%s card_instance_id=%s\",\n conversation_id,\n card_instance_id,\n )\n\n now_ms = int(time.time() * 1000)\n card = ActiveAICard(\n card_instance_id=card_instance_id,\n access_token=token,\n conversation_id=conversation_id,\n account_id=\"default\",\n store_path=str(self._card_store.path),\n created_at=now_ms,\n last_updated=now_ms,\n state=PROCESSING,\n last_streamed_content=\"\",\n )\n async with self._active_cards_lock:\n self._active_cards[conversation_id] = card\n if inbound:\n self._card_store.save(self._active_cards)\n return card\n\n async def _stream_ai_card(\n self,\n card: ActiveAICard,\n content: str,\n finalize: bool = False,\n ) -> bool:\n if self._http is None or card.state in (FINISHED, FAILED):\n return False\n\n content = (content or \"\").strip()\n if not content:\n return False\n\n now_ms = int(time.time() * 1000)\n if not finalize:\n if content == (card.last_streamed_content or \"\").strip():\n return False\n if (\n card.last_updated\n and (now_ms - card.last_updated)\n < AI_CARD_STREAM_MIN_INTERVAL_SECONDS * 1000\n ):\n return False\n\n if (\n now_ms - card.created_at\n ) > AI_CARD_TOKEN_PREEMPTIVE_REFRESH_SECONDS * 1000:\n card.access_token = await self._get_access_token()\n\n payload = {\n \"outTrackId\": card.card_instance_id,\n \"guid\": str(uuid4()),\n \"key\": self.card_template_key,\n \"content\": content,\n \"isFull\": True,\n \"isFinalize\": finalize,\n \"isError\": False,\n }\n url = \"https://api.dingtalk.com/v1.0/card/streaming\"\n\n async def _do_stream(token: str):\n headers = {\n \"Content-Type\": \"application/json\",\n \"x-acs-dingtalk-access-token\": token,\n }\n logger.info(\n \"dingtalk stream ai card: conversation_id=%s finalize=%s \"\n \"content_len=%s\",\n card.conversation_id,\n finalize,\n len(content),\n )\n async with self._http.put(\n url,\n json=payload,\n headers=headers,\n ) as resp:\n txt = await resp.text()\n logger.info(\n \"dingtalk stream ai card response:\"\n \" status=%s finalize=%s body=%s\",\n resp.status,\n finalize,\n txt[:1000],\n )\n return resp.status, txt\n\n status, txt = await _do_stream(card.access_token)\n if status == 401:\n card.access_token = await self._get_access_token()\n status, txt = await _do_stream(card.access_token)\n\n if status >= 400:\n if status == 500 and \"unknownError\" in txt:\n raise RuntimeError(\n \"dingtalk ai card unknownError:\"\n \" card_template_key mismatch?\",\n )\n raise RuntimeError(\n f\"stream ai card failed status={status} body={txt[:500]}\",\n )\n logger.info(\n \"dingtalk stream ai card ok: conversation_id=%s finalize=%s\",\n card.conversation_id,\n finalize,\n )\n\n card.last_streamed_content = content\n card.last_updated = int(time.time() * 1000)\n if finalize:\n card.state = FINISHED\n async with self._active_cards_lock:\n self._active_cards.pop(card.conversation_id, None)\n self._card_store.save(self._active_cards)\n elif card.state == PROCESSING:\n card.state = INPUTING\n await self._save_active_cards()\n return True\n\n async def _finish_ai_card(\n self,\n conversation_id: str,\n final_content: str,\n ) -> bool:\n async with self._active_cards_lock:\n card = self._active_cards.get(conversation_id)\n if not card:\n return False\n return await self._stream_ai_card(card, final_content, finalize=True)\n\n async def _recover_active_cards(self) -> None:\n if not self._ai_card_enabled() or self._http is None:\n return\n records = self._card_store.load()\n if not records:\n return\n token = await self._get_access_token()\n for item in records:\n state = str(item.get(\"state\") or \"\")\n if state in (FINISHED, FAILED):\n continue\n conversation_id = item.get(\"conversation_id\") or \"\"\n card_id = item.get(\"card_instance_id\") or f\"card_{uuid4()}\"\n if not conversation_id:\n continue\n card = ActiveAICard(\n card_instance_id=card_id,\n access_token=token,\n conversation_id=conversation_id,\n account_id=item.get(\"account_id\") or \"default\",\n store_path=str(self._card_store.path),\n created_at=int(\n item.get(\"created_at\") or int(time.time() * 1000),\n ),\n last_updated=int(\n item.get(\"last_updated\") or int(time.time() * 1000),\n ),\n state=state or PROCESSING,\n last_streamed_content=\"\",\n )\n async with self._active_cards_lock:\n self._active_cards[conversation_id] = card\n try:\n await self._stream_ai_card(\n card,\n AI_CARD_RECOVERY_FINAL_TEXT,\n finalize=True,\n )\n except Exception:\n logger.exception(\"dingtalk ai card recovery finalize failed\")\n await self._mark_card_failed(conversation_id)\n\n async def send(\n self,\n to_handle: str,\n text: str,\n meta: Optional[Dict[str, Any]] = None,\n ) -> None:\n \"\"\"\n Proactive send for DingTalk via stored sessionWebhook.\n\n Supports:\n 1) meta[\"session_webhook\"] or meta[\"sessionWebhook\"]: direct url\n 2) to_handle: dingtalk:sw: (stored) or http(s) url\n If no webhook is found, logs warning and returns (no 500).\n \"\"\"\n if not self.enabled:\n return\n if self._http is None:\n return\n\n meta = meta or {}\n\n # direct webhook provided in meta\n session_webhook = meta.get(\"session_webhook\") or meta.get(\n \"sessionWebhook\",\n )\n\n if not session_webhook:\n route = self._route_from_handle(to_handle)\n session_webhook = route.get(\"session_webhook\")\n if not session_webhook:\n webhook_key = route.get(\"webhook_key\")\n if webhook_key:\n session_webhook = await self._load_session_webhook(\n webhook_key,\n )\n\n if not session_webhook:\n logger.warning(\n \"DingTalkChannel.send: no sessionWebhook for to_handle=%s. \"\n \"User must have chatted with the bot first, or pass \"\n \"meta['session_webhook']. Skip sending.\",\n to_handle,\n )\n return\n\n logger.info(\n \"DingTalkChannel.send to_handle=%s len=%s\",\n to_handle,\n len(text),\n )\n\n # Caller (send_content_parts) already prepends bot_prefix to text.\n await self._send_via_session_webhook(\n session_webhook,\n text,\n bot_prefix=\"\",\n )\n\n async def _get_access_token(self) -> str:\n \"\"\"Get and cache DingTalk accessToken for 1 hour (instance-level).\"\"\"\n if not self.client_id or not self.client_secret:\n raise RuntimeError(\"DingTalk client_id/client_secret missing\")\n\n now = asyncio.get_running_loop().time()\n if self._token_value and now < self._token_expires_at:\n return self._token_value\n\n async with self._token_lock:\n now = asyncio.get_running_loop().time()\n if self._token_value and now < self._token_expires_at:\n return self._token_value\n\n url = \"https://api.dingtalk.com/v1.0/oauth2/accessToken\"\n payload = {\n \"appKey\": self.client_id,\n \"appSecret\": self.client_secret,\n }\n\n async with self._http.post(url, json=payload) as resp:\n data = await resp.json(content_type=None)\n if resp.status >= 400:\n raise RuntimeError(\n f\"get accessToken failed status={resp.status} \"\n f\"body={data}\",\n )\n\n token = data.get(\"accessToken\") or data.get(\"access_token\")\n if not token:\n raise RuntimeError(\n f\"accessToken not found in response: {data}\",\n )\n\n self._token_value = token\n self._token_expires_at = (\n asyncio.get_running_loop().time() + DINGTALK_TOKEN_TTL_SECONDS\n )\n return token\n\n async def _get_message_file_download_url(\n self,\n *,\n download_code: str,\n robot_code: str,\n ) -> Optional[str]:\n \"\"\"Call DingTalk messageFiles/download to get a downloadable URL.\"\"\"\n if not download_code or not robot_code:\n return None\n if self._http is None:\n return None\n\n token = await self._get_access_token()\n url = \"https://api.dingtalk.com/v1.0/robot/messageFiles/download\"\n payload = {\"downloadCode\": download_code, \"robotCode\": robot_code}\n headers = {\n \"Content-Type\": \"application/json\",\n \"x-acs-dingtalk-access-token\": token,\n }\n\n async with self._http.post(\n url,\n json=payload,\n headers=headers,\n ) as resp:\n data = await resp.json(content_type=None)\n if resp.status >= 400:\n logger.warning(\n \"messageFiles/download failed status=%s body=%s\",\n resp.status,\n data,\n )\n return None\n\n logger.debug(\"messageFiles/download response=%s\", data)\n return (\n data.get(\"downloadUrl\")\n or data.get(\"url\")\n or (data.get(\"result\") or {}).get(\"downloadUrl\")\n or (data.get(\"result\") or {}).get(\"url\")\n )\n\n async def _download_media_to_local(\n self,\n url: str,\n safe_key: str,\n filename_hint: str = \"file.bin\",\n ) -> Optional[str]:\n \"\"\"Download media to media_dir; return local path or None.\n Suffix from Content-Type then magic bytes.\n \"\"\"\n if not url or not url.strip().startswith((\"http://\", \"https://\")):\n return None\n if self._http is None:\n return None\n try:\n async with self._http.get(url) as resp:\n if resp.status >= 400:\n logger.warning(\n \"dingtalk media download failed status=%s\",\n resp.status,\n )\n return None\n data = await resp.read()\n content_type = (\n resp.headers.get(\"Content-Type\", \"\").split(\";\")[0].strip()\n )\n disposition = resp.headers.get(\n \"Content-Disposition\",\n \"\",\n )\n filename = filename_hint\n if \"filename=\" in disposition:\n part = (\n disposition.split(\"filename=\", 1)[-1].strip().strip(\"'\\\"\")\n )\n if part:\n filename = part\n suffix = \".file\"\n if \".\" in filename:\n ext = filename.rsplit(\".\", 1)[-1].lower().strip()\n if ext:\n suffix = \".\" + ext\n elif content_type:\n suffix = mimetypes.guess_extension(content_type) or \".file\"\n self._media_dir.mkdir(parents=True, exist_ok=True)\n path = self._media_dir / f\"{safe_key}{suffix}\"\n path.write_bytes(data)\n # Fix .file/.bin with magic bytes so images get .png/.jpg etc.\n if path.suffix in (\".file\", \".bin\"):\n real_suffix = guess_suffix_from_file_content(path)\n if real_suffix:\n new_path = path.with_suffix(real_suffix)\n path.rename(new_path)\n path = new_path\n logger.debug(\n \"dingtalk replaced suffix with %s for %s\",\n real_suffix,\n path,\n )\n return str(path)\n except Exception:\n logger.exception(\"dingtalk _download_media_to_local failed\")\n return None\n\n async def _fetch_and_download_media(\n self,\n *,\n download_code: str,\n robot_code: str,\n filename_hint: str = \"file.bin\",\n ) -> Optional[str]:\n \"\"\"Get download URL from API, save to local, return path.\"\"\"\n url = await self._get_message_file_download_url(\n download_code=download_code,\n robot_code=robot_code,\n )\n if not url:\n return None\n key = hashlib.md5(\n (download_code + robot_code).encode(),\n ).hexdigest()[:24]\n return await self._download_media_to_local(\n url,\n key,\n filename_hint,\n )\n\n def _guess_filename_and_ext(\n self,\n part: OutgoingContentPart,\n default: str,\n ) -> tuple[str, str]:\n \"\"\"\n Return (filename, ext) where ext has no dot.\n Tries: part.filename -> url path basename -> default\n \"\"\"\n filename = (getattr(part, \"filename\", None) or \"\").strip()\n\n if not filename:\n url = (\n getattr(part, \"file_url\", None)\n or getattr(part, \"image_url\", None)\n or getattr(part, \"video_url\", None)\n or \"\"\n )\n url = (url or \"\").strip() if isinstance(url, str) else \"\"\n if url:\n try:\n path = urlparse(url).path\n base = os.path.basename(path)\n if base:\n filename = base\n except Exception:\n pass\n\n if not filename:\n filename = default\n\n ext = \"\"\n if \".\" in filename:\n ext = filename.rsplit(\".\", 1)[-1].lower().strip()\n\n if not ext:\n # try from mime_type if provided\n mime = (\n getattr(part, \"mime_type\", None)\n or getattr(part, \"content_type\", None)\n or \"\"\n ).strip()\n if mime:\n guess = mimetypes.guess_extension(mime) # like \".png\"\n if guess:\n ext = guess.lstrip(\".\").lower()\n\n if not ext:\n ext = (\n default.rsplit(\".\", 1)[-1].lower() if \".\" in default else \"bin\"\n )\n\n # normalize common cases\n if ext == \"jpeg\":\n ext = \"jpg\"\n\n return filename, ext\n\n def _is_public_http_url(self, s: Optional[str]) -> bool:\n if not s or not isinstance(s, str):\n return False\n s = s.strip()\n return s.startswith(\"http://\") or s.startswith(\"https://\")\n" }, { "path": "src/copaw/app/channels/dingtalk/constants.py", "content": "# -*- coding: utf-8 -*-\n\"\"\"DingTalk channel constants.\"\"\"\n\n# When consumer sends all messages via sessionWebhook, process() skips reply\nSENT_VIA_WEBHOOK = \"__SENT_VIA_WEBHOOK__\"\nSENT_VIA_AI_CARD = \"__SENT_VIA_AI_CARD__\"\n\n# Token cache TTL (1 hour)\nDINGTALK_TOKEN_TTL_SECONDS = 3600\n\n# Minimum interval between non-final AI Card updates.\nAI_CARD_STREAM_MIN_INTERVAL_SECONDS = 0.6\n\n# Time debounce (300ms)\nDINGTALK_DEBOUNCE_SECONDS = 0.3\n\n# Short suffix length for session_id from conversation_id\nDINGTALK_SESSION_ID_SUFFIX_LEN = 8\n\n# DingTalk message type to runtime content type\nDINGTALK_TYPE_MAPPING = {\n \"picture\": \"image\",\n \"voice\": \"audio\",\n}\n\nAI_CARD_TOKEN_PREEMPTIVE_REFRESH_SECONDS = 90 * 60\nAI_CARD_PROCESSING_TEXT = \"处理中...\"\nAI_CARD_RECOVERY_FINAL_TEXT = \"⚠️ 上一次回复处理中断，已自动结束。请重新发送你的问题。\"\n" }, { "path": "src/copaw/app/channels/dingtalk/content_utils.py", "content": "# -*- coding: utf-8 -*-\n\"\"\"DingTalk content parsing and session helpers.\"\"\"\n\nfrom __future__ import annotations\n\nimport base64\nimport binascii\nimport re\nfrom typing import Any, Optional\nfrom urllib.parse import parse_qs, urlparse\n\nfrom agentscope_runtime.engine.schemas.agent_schemas import (\n AudioContent,\n FileContent,\n ImageContent,\n VideoContent,\n)\n\nfrom ..base import ContentType\n\nfrom .constants import (\n DINGTALK_SESSION_ID_SUFFIX_LEN,\n DINGTALK_TYPE_MAPPING,\n)\n\n\n_DATA_URL_RE = re.compile(\n r\"^data:(?P[^;]+);base64,(?P.*)$\",\n re.I | re.S,\n)\n\n\ndef dingtalk_content_from_type(mapped: str, url: str) -> Any:\n \"\"\"Build runtime Content from DingTalk type and download URL.\"\"\"\n if mapped == \"image\":\n return ImageContent(type=ContentType.IMAGE, image_url=url)\n if mapped == \"video\":\n return VideoContent(type=ContentType.VIDEO, video_url=url)\n if mapped == \"audio\":\n return AudioContent(\n type=ContentType.AUDIO,\n data=url,\n format=\"amr\",\n )\n return FileContent(type=ContentType.FILE, file_url=url)\n\n\ndef parse_data_url(data_url: str) -> tuple[bytes, Optional[str]]:\n \"\"\"Return (bytes, mime or None).\"\"\"\n m = _DATA_URL_RE.match(data_url.strip())\n if not m:\n return base64.b64decode(data_url, validate=False), None\n\n mime = (m.group(\"mime\") or \"\").strip().lower()\n b64 = m.group(\"b64\").strip()\n try:\n data = base64.b64decode(b64, validate=False)\n except (binascii.Error, ValueError):\n data = base64.b64decode(b64 + \"==\", validate=False)\n return data, mime or None\n\n\ndef sender_from_chatbot_message(incoming_message: Any) -> tuple[str, bool]:\n \"\"\"Build sender as nickname#last4(sender_id).\n Return (sender, should_skip).\n \"\"\"\n nickname = (\n getattr(incoming_message, \"sender_nick\", None)\n or getattr(incoming_message, \"senderNick\", None)\n or \"\"\n )\n nickname = nickname.strip() if isinstance(nickname, str) else \"\"\n sender_id = (\n getattr(incoming_message, \"sender_id\", None)\n or getattr(incoming_message, \"senderId\", None)\n or \"\"\n )\n sender_id = str(sender_id).strip() if sender_id else \"\"\n has_sender_id = bool(sender_id)\n has_nickname = bool(nickname)\n\n suffix = sender_id[-4:] if len(sender_id) >= 4 else sender_id\n sender = f\"{(nickname or 'unknown')}#{(suffix or '????')}\"\n\n skip = (not has_sender_id) and (not has_nickname)\n return sender, skip\n\n\ndef conversation_id_from_chatbot_message(incoming_message: Any) -> str:\n \"\"\"Extract conversation_id from DingTalk ChatbotMessage.\"\"\"\n cid = getattr(incoming_message, \"conversationId\", None) or getattr(\n incoming_message,\n \"conversation_id\",\n None,\n )\n return str(cid).strip() if cid else \"\"\n\n\ndef conversation_type_from_chatbot_message(incoming_message: Any) -> str:\n \"\"\"Extract conversation_type from DingTalk ChatbotMessage.\n\n Returns:\n \"dm\" for direct message (conversationType=1)\n \"group\" for group chat (conversationType=2)\n \"dm\" as default if not specified\n \"\"\"\n conv_type = getattr(incoming_message, \"conversationType\", None) or getattr(\n incoming_message,\n \"conversation_type\",\n None,\n )\n if conv_type:\n return \"group\" if str(conv_type) == \"2\" else \"dm\"\n return \"dm\"\n\n\ndef short_session_id_from_conversation_id(conversation_id: str) -> str:\n \"\"\"Use last N chars of conversation_id as session_id.\"\"\"\n n = DINGTALK_SESSION_ID_SUFFIX_LEN\n return (\n conversation_id[-n:] if len(conversation_id) >= n else conversation_id\n )\n\n\ndef session_param_from_webhook_url(url: str) -> Optional[str]:\n \"\"\"Extract session= param from sendBySession URL for debug logging.\"\"\"\n if not url or \"?\" not in url:\n return None\n parsed = urlparse(url)\n qs = parse_qs(parsed.query)\n vals = qs.get(\"session\", [])\n return (\n vals[0][:24] + \"...\"\n if vals and len(vals[0]) > 24\n else (vals[0] if vals else None)\n )\n\n\ndef get_type_mapping() -> dict:\n \"\"\"Return DingTalk type mapping (for handler use).\"\"\"\n return dict(DINGTALK_TYPE_MAPPING)\n" }, { "path": "src/copaw/app/channels/dingtalk/handler.py", "content": "# -*- coding: utf-8 -*-\n\"\"\"DingTalk Stream callback handler: message -> native dict -> reply.\"\"\"\n\nfrom __future__ import annotations\n\nimport asyncio\nimport logging\nfrom typing import Any, Callable, Dict, List, Optional\n\nimport dingtalk_stream\nfrom dingtalk_stream import CallbackMessage, ChatbotMessage\nfrom agentscope_runtime.engine.schemas.agent_schemas import (\n TextContent,\n)\n\nfrom ..base import ContentType\n\nfrom .constants import SENT_VIA_AI_CARD, SENT_VIA_WEBHOOK\nfrom .content_utils import (\n conversation_id_from_chatbot_message,\n conversation_type_from_chatbot_message,\n dingtalk_content_from_type,\n get_type_mapping,\n sender_from_chatbot_message,\n session_param_from_webhook_url,\n)\n\nlogger = logging.getLogger(__name__)\n\n# Download filename hint by type (e.g. voice -> .amr).\nFILENAME_HINT_BY_MAPPED = {\n \"audio\": \"audio.amr\",\n \"image\": \"image.png\",\n \"video\": \"video.mp4\",\n}\nDEFAULT_FILENAME_HINT = \"file.bin\"\n\n\nclass DingTalkChannelHandler(dingtalk_stream.ChatbotHandler):\n \"\"\"Internal handler: convert DingTalk message to native dict, enqueue via\n manager (thread-safe), await reply_future, then reply.\"\"\"\n\n def __init__(\n self,\n main_loop: asyncio.AbstractEventLoop,\n enqueue_callback: Optional[Callable[[Any], None]],\n bot_prefix: str,\n download_url_fetcher,\n try_accept_message: Optional[Callable[[str], bool]] = None,\n ):\n super().__init__()\n self._main_loop = main_loop\n self._enqueue_callback = enqueue_callback\n self._bot_prefix = bot_prefix\n self._download_url_fetcher = download_url_fetcher\n self._try_accept_message = try_accept_message\n\n def _emit_native_threadsafe(self, native: dict) -> None:\n if self._enqueue_callback:\n self._main_loop.call_soon_threadsafe(\n self._enqueue_callback,\n native,\n )\n\n def _fetch_download_url_and_content(\n self,\n download_code: str,\n robot_code: str,\n mapped: str,\n filename_hint: Optional[str] = None,\n ) -> Optional[Any]:\n \"\"\"Fetch media by download_code; return Content to append or None.\"\"\"\n hint = (filename_hint or \"\").strip() or FILENAME_HINT_BY_MAPPED.get(\n mapped,\n DEFAULT_FILENAME_HINT,\n )\n try:\n fut = asyncio.run_coroutine_threadsafe(\n self._download_url_fetcher(\n download_code=download_code,\n robot_code=robot_code,\n filename_hint=hint,\n ),\n self._main_loop,\n )\n download_url = fut.result(timeout=15)\n return dingtalk_content_from_type(mapped, download_url)\n except Exception:\n return None\n\n @staticmethod\n def _extract_filename_hint(payload: Dict[str, Any]) -> Optional[str]:\n \"\"\"Extract filename hint from DingTalk payload variants.\"\"\"\n for key in (\"fileName\", \"file_name\", \"filename\", \"name\", \"title\"):\n val = payload.get(key)\n if isinstance(val, str) and val.strip():\n return val.strip()\n return None\n\n def _parse_rich_content(\n self,\n incoming_message: Any,\n ) -> List[Any]:\n \"\"\"Parse richText from incoming_message into runtime Content list.\"\"\"\n content: List[Any] = []\n type_mapping = get_type_mapping()\n try:\n robot_code = getattr(\n incoming_message,\n \"robot_code\",\n None,\n ) or getattr(incoming_message, \"robotCode\", None)\n msg_dict = incoming_message.to_dict()\n c = msg_dict.get(\"content\") or {}\n raw = c.get(\"richText\")\n raw = raw or c.get(\"rich_text\")\n rich_list = raw if isinstance(raw, list) else []\n for item in rich_list:\n if not isinstance(item, dict):\n continue\n # Text may be under \"text\" or \"content\" (API variation).\n item_text = item.get(\"text\") or item.get(\"content\")\n if item_text is not None:\n stripped = (item_text or \"\").strip()\n if stripped:\n content.append(\n TextContent(\n type=ContentType.TEXT,\n text=stripped,\n ),\n )\n # Picture items may use pictureDownloadCode or downloadCode.\n dl_code = (\n item.get(\"downloadCode\")\n or item.get(\"download_code\")\n or item.get(\"pictureDownloadCode\")\n or item.get(\"picture_download_code\")\n )\n if not dl_code or not robot_code:\n continue\n mapped = type_mapping.get(\n item.get(\"type\", \"file\"),\n item.get(\"type\", \"file\"),\n )\n filename_hint = self._extract_filename_hint(item)\n part_content = self._fetch_download_url_and_content(\n dl_code,\n robot_code,\n mapped,\n filename_hint=filename_hint,\n )\n if part_content is not None:\n content.append(part_content)\n\n # -------- 2) single downloadCode (pure picture/file) --------\n if not content:\n dl_code = c.get(\"downloadCode\") or c.get(\"download_code\")\n if dl_code and robot_code:\n msgtype = (\n (\n msg_dict.get(\n \"msgtype\",\n )\n or \"\"\n )\n .lower()\n .strip()\n )\n mapped = type_mapping.get(\n msgtype,\n msgtype or \"file\",\n )\n if mapped not in (\"image\", \"file\", \"video\", \"audio\"):\n mapped = \"file\"\n filename_hint = self._extract_filename_hint(c)\n part_content = self._fetch_download_url_and_content(\n dl_code,\n robot_code,\n mapped,\n filename_hint=filename_hint,\n )\n if part_content is not None:\n content.append(part_content)\n\n except Exception:\n logger.exception(\"failed to fetch richText download url(s)\")\n return content\n\n async def process(self, callback: CallbackMessage) -> tuple[int, str]:\n # pylint: disable=too-many-branches,too-many-statements\n try:\n # Raw msgId from channel callback for dedup (not assigned id).\n raw_data = getattr(callback, \"data\", None) or {}\n raw_msg_id = str(\n raw_data.get(\"msgId\") or raw_data.get(\"msg_id\") or \"\",\n ).strip()\n logger.info(\n \"dingtalk raw callback: msgId=%r keys=%s\",\n raw_msg_id or \"(empty)\",\n list(raw_data.keys()) if isinstance(raw_data, dict) else \"?\",\n )\n incoming_message = ChatbotMessage.from_dict(callback.data)\n\n logger.debug(\n \"Dingtalk message received: %s\",\n incoming_message.to_dict(),\n )\n content_parts: List[Any] = []\n text = \"\"\n if incoming_message.text:\n text = (incoming_message.text.content or \"\").strip()\n if text:\n content_parts.append(\n TextContent(type=ContentType.TEXT, text=text),\n )\n # Always parse rich content so images/files are not dropped\n # when the message also contains text.\n content = self._parse_rich_content(incoming_message)\n # If text was extracted separately and rich content has no\n # text items, prepend the text so both text and media are\n # preserved. Do not prepend when top-level text is only a\n # placeholder (e.g. \"\\\\n\", \"//n\") so image+text from richText\n # is not overwritten.\n rich_has_text = any(\n item.type == \"text\" and (item.text or \"\").strip()\n for item in content\n )\n text_is_placeholder = not (text or \"\").strip() or (\n (text or \"\").strip() in (\"\\\\n\", \"//n\")\n )\n if (\n text\n and content\n and not rich_has_text\n and not text_is_placeholder\n ):\n content.insert(\n 0,\n TextContent(type=ContentType.TEXT, text=text),\n )\n # Use rich content (text + media with local paths) when present.\n parts_to_send = content if content else content_parts\n\n sender, skip = sender_from_chatbot_message(incoming_message)\n if skip:\n return dingtalk_stream.AckMessage.STATUS_OK, \"ok\"\n\n conversation_id = conversation_id_from_chatbot_message(\n incoming_message,\n )\n conversation_type = conversation_type_from_chatbot_message(\n incoming_message,\n )\n is_group = conversation_type == \"group\"\n is_bot_mentioned = bool(raw_data.get(\"isInAtList\"))\n\n loop = asyncio.get_running_loop()\n reply_future: asyncio.Future[str] = loop.create_future()\n meta: Dict[str, Any] = {\n \"incoming_message\": incoming_message,\n \"reply_future\": reply_future,\n \"reply_loop\": loop,\n \"conversation_type\": conversation_type,\n \"is_group\": is_group,\n \"sender_staff_id\": getattr(\n incoming_message,\n \"sender_staff_id\",\n None,\n )\n or getattr(incoming_message, \"senderStaffId\", None)\n or \"\",\n }\n if is_bot_mentioned:\n meta[\"bot_mentioned\"] = True\n if conversation_id:\n meta[\"conversation_id\"] = conversation_id\n if raw_msg_id:\n meta[\"message_id\"] = raw_msg_id\n sw = getattr(incoming_message, \"sessionWebhook\", None) or getattr(\n incoming_message,\n \"session_webhook\",\n None,\n )\n logger.debug(\n \"dingtalk request: has_session_webhook=%s sender=%s\",\n bool(sw),\n sender,\n )\n if sw:\n meta[\"session_webhook\"] = sw\n sw_exp = getattr(\n incoming_message,\n \"sessionWebhookExpiredTime\",\n None,\n ) or getattr(\n incoming_message,\n \"session_webhook_expired_time\",\n None,\n )\n logger.info(\n \"dingtalk recv: session_webhook present \"\n \"session_from_url=%s \"\n \"expired_time=%s\",\n session_param_from_webhook_url(sw),\n sw_exp,\n )\n else:\n logger.debug(\n \"dingtalk recv: no sessionWebhook on incoming_message\",\n )\n\n # Dedup by message_id only.\n if self._try_accept_message and not self._try_accept_message(\n raw_msg_id,\n ):\n logger.info(\n \"dingtalk duplicate ignored: raw_msg_id=%r from=%s\",\n raw_msg_id,\n sender,\n )\n self.reply_text(\" \", incoming_message)\n return dingtalk_stream.AckMessage.STATUS_OK, \"ok\"\n\n logger.info(\n \"dingtalk accept: raw_msg_id=%r\",\n raw_msg_id or \"(empty)\",\n )\n native = {\n \"channel_id\": \"dingtalk\",\n \"sender_id\": sender,\n \"content_parts\": parts_to_send,\n \"meta\": meta,\n }\n if raw_msg_id:\n native[\"message_id\"] = raw_msg_id\n if sw:\n native[\"session_webhook\"] = sw\n logger.info(\n \"dingtalk emit: native has_sw=%s meta_sw=%s\",\n bool(native.get(\"session_webhook\")),\n bool((native.get(\"meta\") or {}).get(\"session_webhook\")),\n )\n logger.info(\"recv from=%s text=%s\", sender, text[:100])\n self._emit_native_threadsafe(native)\n\n response_text = await reply_future\n if response_text == SENT_VIA_AI_CARD:\n logger.info(\"sent to=%s via ai card\", sender)\n self.reply_text(\" \", incoming_message)\n elif response_text == SENT_VIA_WEBHOOK:\n logger.info(\n \"sent to=%s via sessionWebhook (multi-message)\",\n sender,\n )\n # Stream connection still expects a reply frame;\n # send minimal ack so the connection completes and next\n # messages work.\n self.reply_text(\" \", incoming_message)\n else:\n out = self._bot_prefix + response_text\n self.reply_text(out, incoming_message)\n logger.info(\"sent to=%s text=%r\", sender, out[:100])\n return dingtalk_stream.AckMessage.STATUS_OK, \"ok\"\n\n except Exception:\n logger.exception(\"process failed\")\n return dingtalk_stream.AckMessage.STATUS_SYSTEM_EXCEPTION, \"error\"\n" }, { "path": "src/copaw/app/channels/dingtalk/markdown.py", "content": "# -*- coding: utf-8 -*-\n\"\"\"DingTalk Markdown normalization helpers.\"\"\"\n\nimport re\n\n\ndef ensure_list_spacing(text: str) -> str:\n \"\"\"\n Ensure there is a blank line before numbered list items (e.g. \"1. ...\"),\n to avoid DingTalk merging the list item into the previous paragraph and\n breaking Markdown parsing.\n\n Example (before):\n Image: `xxx`\n 3. **Make sure you are on the latest branch**\n\n Example (after):\n Image: `xxx`\n\n 3. **Make sure you are on the latest branch**\n \"\"\"\n lines = text.split(\"\\n\")\n out = []\n\n for i, line in enumerate(lines):\n is_numbered = re.match(r\"^\\d+\\.\\s\", line.strip()) is not None\n if is_numbered and i > 0:\n prev = lines[i - 1]\n prev_is_empty = prev.strip() == \"\"\n prev_is_numbered = (\n re.match(\n r\"^\\d+\\.\\s\",\n prev.strip(),\n )\n is not None\n )\n if not prev_is_empty and not prev_is_numbered:\n out.append(\"\")\n out.append(line)\n\n return \"\\n\".join(out)\n\n\ndef dedent_code_blocks(text: str) -> str:\n \"\"\"\n Remove unnecessary leading indentation before fenced code blocks.\n\n DingTalk may render code blocks incorrectly if the opening ``` fence\n is indented. This function detects an indented fenced block and\n removes the same indentation from all lines inside that block.\n \"\"\"\n pattern = r\"^([ \\t]*)(```[^\\n]*\\n.*?\\n```)[ \\t]*$\"\n\n def _dedent(m: re.Match) -> str:\n indent = m.group(1)\n block = m.group(2)\n if not indent:\n return block\n\n n = len(indent)\n lines = block.split(\"\\n\")\n new_lines = []\n for ln in lines:\n if ln.startswith(indent):\n new_lines.append(ln[n:])\n else:\n new_lines.append(ln)\n return \"\\n\".join(new_lines)\n\n return re.sub(pattern, _dedent, text, flags=re.MULTILINE | re.DOTALL)\n\n\ndef format_code_blocks(text: str, prefix: str = \"·\") -> str:\n \"\"\"\n Prefix each non-empty line inside fenced code blocks with a marker.\n\n This is sometimes used as a workaround when DingTalk's Markdown parser\n behaves unexpectedly with certain code content.\n \"\"\"\n pattern = r\"```([^\\n]*)\\n(.*?)\\n```\"\n\n def _replace(m: re.Match) -> str:\n lang = m.group(1).strip()\n code = m.group(2)\n\n prefixed = []\n for ln in code.split(\"\\n\"):\n prefixed.append(f\"{prefix}{ln}\" if ln.strip() else ln)\n\n fence = f\"```{lang}\".rstrip()\n return fence + \"\\n\" + \"\\n\".join(prefixed) + \"\\n```\"\n\n return re.sub(pattern, _replace, text, flags=re.DOTALL)\n\n\ndef normalize_dingtalk_markdown(\n text: str,\n code_prefix: str | None = None,\n) -> str:\n \"\"\"\n Apply DingTalk Markdown normalization steps:\n 1) Ensure blank lines before numbered list items\n 2) Dedent fenced code blocks\n 3) Optionally prefix code lines inside fenced blocks\n \"\"\"\n text = ensure_list_spacing(text)\n text = dedent_code_blocks(text)\n if code_prefix is not None:\n text = format_code_blocks(text, prefix=code_prefix)\n return text\n" }, { "path": "src/copaw/app/channels/dingtalk/utils.py", "content": "# -*- coding: utf-8 -*-\n\"\"\"DingTalk channel helpers (media suffix guess, etc.).\"\"\"\n\nfrom pathlib import Path\nfrom typing import Optional\n\n# Magic bytes -> suffix for .file fallback (DingTalk URLs often return .file).\n# AMR-NB voice: \"#!AMR\\n\"\nDINGTALK_MAGIC_SUFFIX: list[tuple[bytes, str]] = [\n (b\"%PDF\", \".pdf\"),\n (b\"PK\\x03\\x04\", \".zip\"),\n (b\"PK\\x05\\x06\", \".zip\"),\n (b\"\\x89PNG\\r\\n\\x1a\\n\", \".png\"),\n (b\"\\xff\\xd8\\xff\", \".jpg\"),\n (b\"GIF87a\", \".gif\"),\n (b\"GIF89a\", \".gif\"),\n (b\"\\xd0\\xcf\\x11\\xe0\", \".doc\"),\n (b\"RIFF\", \".webp\"),\n (b\"#!AMR\\n\", \".amr\"),\n]\n\n\ndef guess_suffix_from_file_content(path: Path) -> Optional[str]:\n \"\"\"Guess suffix from file magic bytes. Returns e.g. '.pdf' or None.\"\"\"\n try:\n with open(path, \"rb\") as f:\n head = f.read(32)\n for magic, suffix in DINGTALK_MAGIC_SUFFIX:\n if head.startswith(magic):\n return suffix\n return None\n except Exception:\n return None\n" }, { "path": "src/copaw/app/channels/discord_/__init__.py", "content": "# -*- coding: utf-8 -*-\n\"\"\"Discord channel package.\"\"\"\nfrom .channel import DiscordChannel\n\n__all__ = [\"DiscordChannel\"]\n" }, { "path": "src/copaw/app/channels/discord_/channel.py", "content": "# -*- coding: utf-8 -*-\n# pylint: disable=too-many-branches,too-many-statements\nfrom __future__ import annotations\n\nimport os\nimport logging\nimport asyncio\nimport re\nimport tempfile\nfrom pathlib import Path\nfrom urllib.parse import urlparse\nfrom typing import Any, Optional\n\nimport aiohttp\nfrom agentscope_runtime.engine.schemas.agent_schemas import (\n TextContent,\n ImageContent,\n VideoContent,\n AudioContent,\n FileContent,\n ContentType,\n)\n\nfrom ....config.config import DiscordConfig as DiscordChannelConfig\n\nfrom ..base import (\n BaseChannel,\n OnReplySent,\n OutgoingContentPart,\n ProcessHandler,\n)\n\nlogger = logging.getLogger(__name__)\n\n# Regex that matches a code-fence opening/closing line (``` or ~~~).\n_FENCE_RE = re.compile(r\"^(`{3,}|~{3,})\")\n\n\nclass DiscordChannel(BaseChannel):\n channel = \"discord\"\n uses_manager_queue = True\n _DISCORD_MAX_LEN: int = 2000\n\n def __init__(\n self,\n process: ProcessHandler,\n enabled: bool,\n token: str,\n http_proxy: str,\n http_proxy_auth: str,\n bot_prefix: str,\n on_reply_sent: OnReplySent = None,\n show_tool_details: bool = True,\n filter_tool_messages: bool = False,\n filter_thinking: bool = False,\n dm_policy: str = \"open\",\n group_policy: str = \"open\",\n allow_from: Optional[list] = None,\n deny_message: str = \"\",\n require_mention: bool = False,\n ):\n super().__init__(\n process,\n on_reply_sent=on_reply_sent,\n show_tool_details=show_tool_details,\n filter_tool_messages=filter_tool_messages,\n filter_thinking=filter_thinking,\n dm_policy=dm_policy,\n group_policy=group_policy,\n allow_from=allow_from,\n deny_message=deny_message,\n require_mention=require_mention,\n )\n self.enabled = enabled\n self.token = token\n self.http_proxy = http_proxy\n self.http_proxy_auth = http_proxy_auth\n self.bot_prefix = bot_prefix\n self._task: Optional[asyncio.Task] = None\n self._client = None\n\n if self.enabled:\n import discord # type: ignore\n\n intents = discord.Intents.default()\n intents.message_content = True\n intents.dm_messages = True\n intents.messages = True\n intents.guilds = True\n\n proxy_auth = None\n if self.http_proxy_auth:\n u, p = self.http_proxy_auth.split(\":\", 1)\n proxy_auth = aiohttp.BasicAuth(u, p)\n\n self._client = discord.Client(\n intents=intents,\n proxy=self.http_proxy,\n proxy_auth=proxy_auth,\n )\n\n @self._client.event\n async def on_message(message):\n if message.author.bot:\n return\n text = (message.content or \"\").strip()\n attachments = message.attachments\n\n is_bot_mentioned = False\n bot_user = self._client.user\n if getattr(message, \"mention_everyone\", False):\n is_bot_mentioned = True\n if bot_user and bot_user in message.mentions:\n is_bot_mentioned = True\n text = re.sub(\n rf\"<@!?{bot_user.id}>\",\n \"\",\n text,\n ).strip()\n\n content_parts = []\n if text:\n content_parts.append(\n TextContent(type=ContentType.TEXT, text=text),\n )\n if attachments:\n for att in attachments:\n file_name = (att.filename or \"\").lower()\n url = att.url\n ctype = (att.content_type or \"\").lower()\n\n is_image = ctype.startswith(\n \"image/\",\n ) or file_name.endswith(\n (\n \".png\",\n \".jpg\",\n \".jpeg\",\n \".gif\",\n \".webp\",\n \".bmp\",\n \".tiff\",\n ),\n )\n is_video = ctype.startswith(\n \"video/\",\n ) or file_name.endswith(\n (\".mp4\", \".mov\", \".mkv\", \".webm\", \".avi\"),\n )\n is_audio = ctype.startswith(\n \"audio/\",\n ) or file_name.endswith(\n (\".mp3\", \".wav\", \".m4a\", \".aac\", \".ogg\", \".flac\"),\n )\n\n if is_image:\n content_parts.append(\n ImageContent(\n type=ContentType.IMAGE,\n image_url=url,\n ),\n )\n elif is_video:\n content_parts.append(\n VideoContent(\n type=ContentType.VIDEO,\n video_url=url,\n ),\n )\n elif is_audio:\n content_parts.append(\n AudioContent(\n type=ContentType.AUDIO,\n data=url,\n ),\n )\n else:\n content_parts.append(\n FileContent(\n type=ContentType.FILE,\n file_url=url,\n ),\n )\n\n is_group = message.guild is not None\n meta = {\n \"user_id\": str(message.author.id),\n \"channel_id\": str(message.channel.id),\n \"guild_id\": str(message.guild.id)\n if message.guild\n else None,\n \"message_id\": str(message.id),\n \"is_dm\": not is_group,\n \"is_group\": is_group,\n }\n if is_bot_mentioned:\n meta[\"bot_mentioned\"] = True\n\n allowed, error_msg = self._check_allowlist(\n str(message.author.id),\n is_group,\n )\n if not allowed:\n logger.info(\n \"discord allowlist blocked: sender=%s is_group=%s\",\n message.author.id,\n is_group,\n )\n await message.channel.send(error_msg or \"\")\n return\n\n if not self._check_group_mention(is_group, meta):\n return\n\n native = {\n \"channel_id\": self.channel,\n \"sender_id\": str(message.author),\n \"content_parts\": content_parts,\n \"meta\": meta,\n }\n if self._enqueue is not None:\n self._enqueue(native)\n else:\n logger.warning(\n \"discord: _enqueue not set, message dropped\",\n )\n\n @classmethod\n def from_env(\n cls,\n process: ProcessHandler,\n on_reply_sent: OnReplySent = None,\n ) -> \"DiscordChannel\":\n allow_from_env = os.getenv(\"DISCORD_ALLOW_FROM\", \"\")\n allow_from = (\n [s.strip() for s in allow_from_env.split(\",\") if s.strip()]\n if allow_from_env\n else []\n )\n return cls(\n process=process,\n enabled=os.getenv(\"DISCORD_CHANNEL_ENABLED\", \"1\") == \"1\",\n token=os.getenv(\"DISCORD_BOT_TOKEN\", \"\"),\n http_proxy=os.getenv(\n \"DISCORD_HTTP_PROXY\",\n \"\",\n ),\n http_proxy_auth=os.getenv(\"DISCORD_HTTP_PROXY_AUTH\", \"\"),\n bot_prefix=os.getenv(\"DISCORD_BOT_PREFIX\", \"[BOT] \"),\n on_reply_sent=on_reply_sent,\n dm_policy=os.getenv(\"DISCORD_DM_POLICY\", \"open\"),\n group_policy=os.getenv(\"DISCORD_GROUP_POLICY\", \"open\"),\n allow_from=allow_from,\n deny_message=os.getenv(\"DISCORD_DENY_MESSAGE\", \"\"),\n require_mention=os.getenv(\"DISCORD_REQUIRE_MENTION\", \"0\") == \"1\",\n )\n\n @classmethod\n def from_config(\n cls,\n process: ProcessHandler,\n config: DiscordChannelConfig,\n on_reply_sent: OnReplySent = None,\n show_tool_details: bool = True,\n filter_tool_messages: bool = False,\n filter_thinking: bool = False,\n ) -> \"DiscordChannel\":\n return cls(\n process=process,\n enabled=config.enabled,\n token=config.bot_token or \"\",\n http_proxy=config.http_proxy,\n http_proxy_auth=config.http_proxy_auth or \"\",\n bot_prefix=config.bot_prefix or \"[BOT] \",\n on_reply_sent=on_reply_sent,\n show_tool_details=show_tool_details,\n filter_tool_messages=filter_tool_messages,\n filter_thinking=filter_thinking,\n dm_policy=config.dm_policy or \"open\",\n group_policy=config.group_policy or \"open\",\n allow_from=config.allow_from or [],\n deny_message=config.deny_message or \"\",\n require_mention=config.require_mention,\n )\n\n async def _resolve_target(self, to_handle, _meta):\n \"\"\"Resolve a Discord Messageable from meta or to_handle.\"\"\"\n route = self._route_from_handle(to_handle)\n channel_id = route.get(\"channel_id\")\n user_id = route.get(\"user_id\")\n if channel_id:\n cid = int(channel_id)\n ch = self._client.get_channel(cid)\n if ch is None:\n ch = await self._client.fetch_channel(cid)\n return ch\n if user_id:\n uid = int(user_id)\n user = self._client.get_user(uid)\n if user is None:\n user = await self._client.fetch_user(uid)\n return user.dm_channel or await user.create_dm()\n return None\n\n @staticmethod\n def _chunk_text(text: str, max_len: int = 2000) -> list[str]:\n \"\"\"Split *text* into chunks that fit Discord's message limit.\n\n Splits at newline boundaries to preserve formatting. If a single\n line exceeds *max_len* it is hard-split at *max_len*.\n\n Markdown code fences are tracked so that a chunk ending inside an\n open fence gets a closing fence appended and the next chunk gets\n a matching opening fence prepended. This keeps code blocks\n rendered correctly across split messages.\n \"\"\"\n if len(text) <= max_len:\n return [text]\n\n chunks: list[str] = []\n current: list[str] = []\n current_len = 0\n fence_open: str = \"\" # e.g. \"```python\"\n\n def _flush() -> None:\n nonlocal fence_open\n body = \"\".join(current).rstrip(\"\\n\")\n if fence_open:\n body += \"\\n```\" # close dangling fence\n chunks.append(body)\n current.clear()\n\n for line in text.split(\"\\n\"):\n line_with_nl = line + \"\\n\"\n stripped = line.strip()\n\n # Detect fence toggle.\n if _FENCE_RE.match(stripped):\n if fence_open:\n fence_open = \"\"\n else:\n fence_open = stripped\n\n # Flush if adding this line would exceed the limit.\n if current and current_len + len(line_with_nl) > max_len:\n saved_fence = fence_open\n _flush()\n current_len = 0\n # Re-open the fence in the next chunk.\n if saved_fence:\n fence_open = saved_fence\n reopener = saved_fence + \"\\n\"\n current.append(reopener)\n current_len += len(reopener)\n\n # Single line exceeds max_len -> hard-split.\n if len(line_with_nl) > max_len:\n for i in range(0, len(line), max_len):\n chunks.append(line[i : i + max_len])\n else:\n current.append(line_with_nl)\n current_len += len(line_with_nl)\n\n if current:\n chunks.append(\"\".join(current).rstrip(\"\\n\"))\n\n return [c for c in chunks if c.strip()]\n\n async def send(\n self,\n to_handle: str,\n text: str,\n meta: Optional[dict] = None,\n ) -> None:\n \"\"\"\n Proactive send for Discord.\n\n Notes:\n - Discord cannot send to a \"user handle\" directly without resolving\n a User/Channel.\n - This implementation supports:\n 1) meta[\"channel_id\"] -> send to that channel\n 2) meta[\"user_id\"] -> DM that user (opens/uses DM channel)\n - If neither is provided, this raises ValueError.\n - Messages exceeding 2000 chars are automatically split into\n multiple messages preserving markdown code fences.\n \"\"\"\n if not self.enabled:\n return\n if not self._client:\n raise RuntimeError(\"Discord client is not initialized\")\n if not self._client.is_ready():\n raise RuntimeError(\"Discord client is not ready yet\")\n target = await self._resolve_target(to_handle, meta)\n if not target:\n raise ValueError(\n \"DiscordChannel.send requires meta['channel_id']\"\n \" or meta['user_id']\",\n )\n for chunk in self._chunk_text(text, self._DISCORD_MAX_LEN):\n await target.send(chunk)\n\n async def send_content_parts(\n self,\n to_handle: str,\n parts: list[OutgoingContentPart],\n meta: Optional[dict] = None,\n ) -> None:\n media_types = {\n ContentType.IMAGE,\n ContentType.VIDEO,\n ContentType.AUDIO,\n ContentType.FILE,\n }\n text_parts = [\n p\n for p in (parts or [])\n if getattr(p, \"type\", None) not in media_types\n ]\n media_parts = [\n p for p in (parts or []) if getattr(p, \"type\", None) in media_types\n ]\n if text_parts:\n await super().send_content_parts(\n to_handle,\n text_parts,\n meta,\n )\n for m in media_parts:\n await self.send_media(to_handle, m, meta)\n\n async def send_media(\n self,\n to_handle: str,\n part: OutgoingContentPart,\n meta: Optional[dict] = None,\n ) -> None:\n \"\"\"Send a media part as a Discord file attachment.\"\"\"\n if not self.enabled or not self._client:\n return\n if not self._client.is_ready():\n return\n import discord\n\n url = (\n getattr(part, \"image_url\", None)\n or getattr(part, \"video_url\", None)\n or getattr(part, \"data\", None)\n or getattr(part, \"file_url\", None)\n )\n if not url:\n return\n\n target = await self._resolve_target(to_handle, meta)\n if not target:\n logger.warning(\n \"discord send_media: cannot resolve target\",\n )\n return\n\n temp_path = None\n if url.startswith(\"file://\"):\n file = discord.File(url[7:])\n elif url.startswith((\"http://\", \"https://\")):\n async with aiohttp.ClientSession() as session:\n async with session.get(url) as resp:\n if resp.status != 200:\n logger.warning(\n \"discord send_media: download failed status=%d\",\n resp.status,\n )\n return\n data = await resp.read()\n parsed_path = urlparse(url).path\n suffix = Path(parsed_path).suffix\n fname = Path(parsed_path).name or f\"file{suffix}\"\n with tempfile.NamedTemporaryFile(\n delete=False,\n suffix=suffix,\n ) as tmp:\n tmp.write(data)\n temp_path = tmp.name\n file = discord.File(\n temp_path,\n filename=fname,\n )\n else:\n return\n\n try:\n await target.send(file=file)\n finally:\n if temp_path:\n Path(temp_path).unlink(missing_ok=True)\n\n async def _run(self) -> None:\n if not self.enabled or not self.token or not self._client:\n return\n await self._client.start(self.token, reconnect=True)\n\n async def start(self) -> None:\n if not self.enabled:\n return\n self._task = asyncio.create_task(self._run(), name=\"discord_gateway\")\n\n async def stop(self) -> None:\n if not self.enabled:\n return\n if self._task:\n self._task.cancel()\n try:\n await asyncio.wait_for(self._task, timeout=5)\n except (asyncio.CancelledError, Exception):\n pass\n if self._client:\n await self._client.close()\n\n def resolve_session_id(\n self,\n sender_id: str,\n channel_meta: Optional[dict] = None,\n ) -> str:\n \"\"\"Session by channel (guild) or DM user id.\"\"\"\n meta = channel_meta or {}\n is_dm = bool(meta.get(\"is_dm\"))\n channel_id = meta.get(\"channel_id\")\n user_id = meta.get(\"user_id\") or sender_id\n if is_dm:\n return f\"discord:dm:{user_id}\"\n if channel_id:\n return f\"discord:ch:{channel_id}\"\n return f\"discord:dm:{user_id}\"\n\n def get_to_handle_from_request(self, request: Any) -> str:\n \"\"\"Discord send target is session_id (discord:ch:xxx or dm:xxx).\"\"\"\n sid = getattr(request, \"session_id\", \"\")\n uid = getattr(request, \"user_id\", \"\")\n return sid or uid or \"\"\n\n def build_agent_request_from_native(self, native_payload) -> Any:\n \"\"\"Build AgentRequest from Discord dict (content_parts + meta).\"\"\"\n payload = native_payload if isinstance(native_payload, dict) else {}\n channel_id = payload.get(\"channel_id\") or self.channel\n sender_id = payload.get(\"sender_id\") or \"\"\n content_parts = payload.get(\"content_parts\") or []\n meta = payload.get(\"meta\") or {}\n user_id = str(meta.get(\"user_id\") or sender_id)\n session_id = self.resolve_session_id(user_id, meta)\n request = self.build_agent_request_from_user_content(\n channel_id=channel_id,\n sender_id=sender_id,\n session_id=session_id,\n content_parts=content_parts,\n channel_meta=meta,\n )\n request.user_id = user_id\n request.channel_meta = meta\n return request\n\n def to_handle_from_target(self, *, user_id: str, session_id: str) -> str:\n return session_id\n\n def _route_from_handle(self, to_handle: str) -> dict:\n # to_handle format: discord:ch: or discord:dm:\n parts = (to_handle or \"\").split(\":\")\n if len(parts) >= 3 and parts[0] == \"discord\":\n kind, ident = parts[1], parts[2]\n if kind == \"ch\":\n return {\"channel_id\": ident}\n if kind == \"dm\":\n return {\"user_id\": ident}\n return {}\n" }, { "path": "src/copaw/app/channels/feishu/__init__.py", "content": "# -*- coding: utf-8 -*-\n\"\"\"Feishu channel package.\"\"\"\nfrom .channel import FeishuChannel\n\n__all__ = [\"FeishuChannel\"]\n" }, { "path": "src/copaw/app/channels/feishu/channel.py", "content": "# -*- coding: utf-8 -*-\n# pylint: disable=too-many-statements,too-many-branches,protected-access\n# pylint: disable=too-many-return-statements,unused-argument\n\"\"\"Feishu (Lark) Channel.\n\nUses lark-oapi (https://github.com/larksuite/oapi-sdk-python) WebSocket\nlong connection to receive events (no public IP). Sends via Open API\n(tenant_access_token). Supports text, image, file; group chat context:\nchat_id and message_id are put in message metadata for downstream\ndeduplication.\n\"\"\"\n\nfrom __future__ import annotations\n\nimport base64\nimport asyncio\nimport json\nimport logging\nimport mimetypes\nimport re\nimport sys\nimport threading\nimport time\nimport types\nfrom collections import OrderedDict\nfrom pathlib import Path\nfrom typing import TYPE_CHECKING, Any, Dict, List, Optional, Tuple\n\nimport aiohttp\nfrom agentscope_runtime.engine.schemas.agent_schemas import (\n AudioContent,\n FileContent,\n ImageContent,\n RunStatus,\n TextContent,\n)\n\nfrom ....config.config import FeishuConfig as FeishuChannelConfig\nfrom ....config.utils import get_config_path\nfrom ....constant import DEFAULT_MEDIA_DIR\nfrom ..base import (\n BaseChannel,\n ContentType,\n OnReplySent,\n OutgoingContentPart,\n ProcessHandler,\n)\nfrom ..utils import file_url_to_local_path\nfrom .constants import (\n FEISHU_FILE_MAX_BYTES,\n FEISHU_NICKNAME_CACHE_MAX,\n FEISHU_PROCESSED_IDS_MAX,\n FEISHU_TOKEN_REFRESH_BEFORE_SECONDS,\n FEISHU_USER_NAME_FETCH_TIMEOUT,\n)\nfrom .utils import (\n build_interactive_content_chunks,\n extract_json_key,\n extract_post_image_keys,\n extract_post_media_file_keys,\n extract_post_text,\n normalize_feishu_md,\n sender_display_string,\n short_session_id_from_full_id,\n)\n\n\n# Compatibility for setuptools>=82 where pkg_resources may be absent.\n# lark-oapi imports pkg_resources.declare_namespace from its vendored protobuf\n# package init; install a minimal shim only while importing lark-oapi.\ndef _declare_namespace_shim(_name: str) -> None:\n return None\n\n\n_PKG_RESOURCES_MISSING = object()\n_original_pkg_resources: Any = sys.modules.get(\n \"pkg_resources\",\n _PKG_RESOURCES_MISSING,\n)\n_pkg_resources_shim: Optional[types.ModuleType] = None\n_pkg_resources_module: Any = None\n_declare_namespace_patched = False\n\ntry:\n import pkg_resources as _pkg_resources_module # type: ignore\nexcept ImportError: # pragma: no cover - pkg_resources absent (setuptools>=82)\n _pkg_resources_shim = types.ModuleType(\"pkg_resources\")\n _pkg_resources_shim.declare_namespace = ( # type: ignore[attr-defined]\n _declare_namespace_shim\n )\n sys.modules[\"pkg_resources\"] = _pkg_resources_shim\nelse:\n if not hasattr(_pkg_resources_module, \"declare_namespace\"):\n setattr(\n _pkg_resources_module,\n \"declare_namespace\",\n _declare_namespace_shim,\n )\n _declare_namespace_patched = True\n\ntry:\n import lark_oapi as lark\n from lark_oapi.api.im.v1 import (\n CreateImageRequest,\n CreateImageRequestBody,\n CreateMessageRequest,\n CreateMessageRequestBody,\n CreateMessageReactionRequest,\n CreateMessageReactionRequestBody,\n Emoji,\n P2ImMessageReceiveV1,\n )\nexcept ImportError: # pragma: no cover - optional dependency may be missing\n lark = None # type: ignore[assignment]\n CreateImageRequest = None # type: ignore[assignment]\n CreateImageRequestBody = None # type: ignore[assignment]\n CreateMessageRequest = None # type: ignore[assignment]\n CreateMessageRequestBody = None # type: ignore[assignment]\n CreateMessageReactionRequest = None # type: ignore[assignment]\n CreateMessageReactionRequestBody = None # type: ignore[assignment]\n Emoji = None # type: ignore[assignment]\n P2ImMessageReceiveV1 = None # type: ignore[assignment]\nfinally:\n if (\n _pkg_resources_shim is not None\n and sys.modules.get(\"pkg_resources\") is _pkg_resources_shim\n ):\n if _original_pkg_resources is _PKG_RESOURCES_MISSING:\n del sys.modules[\"pkg_resources\"]\n else:\n sys.modules[\"pkg_resources\"] = _original_pkg_resources\n if _declare_namespace_patched and _pkg_resources_module is not None:\n if (\n getattr(_pkg_resources_module, \"declare_namespace\", None)\n is _declare_namespace_shim\n ):\n delattr(_pkg_resources_module, \"declare_namespace\")\n\nif TYPE_CHECKING:\n from agentscope_runtime.engine.schemas.agent_schemas import AgentRequest\n\nlogger = logging.getLogger(__name__)\n\n\nclass FeishuChannel(BaseChannel):\n \"\"\"Feishu/Lark channel: WebSocket receive, Open API send.\n\n Session: for group chat session_id = feishu:chat_id:, for p2p\n feishu:open_id:. We store (receive_id, receive_id_type) so\n proactive send and reply work. Chat ID and message ID are set on\n the first message metadata for downstream deduplication.\n \"\"\"\n\n channel = \"feishu\"\n\n def __init__(\n self,\n process: ProcessHandler,\n enabled: bool,\n app_id: str,\n app_secret: str,\n bot_prefix: str,\n encrypt_key: str = \"\",\n verification_token: str = \"\",\n media_dir: str = \"\",\n workspace_dir: Path | None = None,\n on_reply_sent: OnReplySent = None,\n show_tool_details: bool = True,\n filter_tool_messages: bool = False,\n filter_thinking: bool = False,\n dm_policy: str = \"open\",\n group_policy: str = \"open\",\n allow_from: Optional[List[str]] = None,\n deny_message: str = \"\",\n require_mention: bool = False,\n ):\n super().__init__(\n process,\n on_reply_sent=on_reply_sent,\n show_tool_details=show_tool_details,\n filter_tool_messages=filter_tool_messages,\n filter_thinking=filter_thinking,\n dm_policy=dm_policy,\n group_policy=group_policy,\n allow_from=allow_from,\n deny_message=deny_message,\n require_mention=require_mention,\n )\n self.enabled = enabled\n self.app_id = app_id\n self.app_secret = app_secret\n self.bot_prefix = bot_prefix\n self.encrypt_key = encrypt_key or \"\"\n self.verification_token = verification_token or \"\"\n self._workspace_dir = (\n Path(workspace_dir).expanduser() if workspace_dir else None\n )\n # Use workspace-specific media dir if workspace_dir is provided\n if not media_dir and self._workspace_dir:\n self._media_dir = self._workspace_dir / \"media\"\n elif media_dir:\n self._media_dir = Path(media_dir).expanduser()\n else:\n self._media_dir = DEFAULT_MEDIA_DIR\n self._media_dir.mkdir(parents=True, exist_ok=True)\n\n self._client: Any = None\n self._ws_client: Any = None\n self._ws_thread: Optional[threading.Thread] = None\n self._loop: Optional[asyncio.AbstractEventLoop] = None\n self._ws_loop: Optional[asyncio.AbstractEventLoop] = None\n self._closed = False\n self._stop_event = threading.Event()\n\n self._tenant_access_token: Optional[str] = None\n self._tenant_access_token_expire_at: float = 0.0\n self._token_lock = asyncio.Lock()\n self._http: Optional[aiohttp.ClientSession] = None\n self._bot_open_id: Optional[str] = None\n\n # message_id dedup (ordered, trim when over limit)\n self._processed_message_ids: OrderedDict[str, None] = OrderedDict()\n # session_id -> (receive_id, receive_id_type) for send\n self._receive_id_store: Dict[str, Tuple[str, str]] = {}\n self._receive_id_lock = asyncio.Lock()\n # open_id -> nickname (from Contact API) for sender display\n self._nickname_cache: Dict[str, str] = {}\n self._nickname_cache_lock = asyncio.Lock()\n\n @classmethod\n def from_env(\n cls,\n process: ProcessHandler,\n on_reply_sent: OnReplySent = None,\n ) -> \"FeishuChannel\":\n import os\n\n allow_from_env = os.getenv(\"FEISHU_ALLOW_FROM\", \"\")\n allow_from = (\n [s.strip() for s in allow_from_env.split(\",\") if s.strip()]\n if allow_from_env\n else []\n )\n return cls(\n process=process,\n enabled=os.getenv(\"FEISHU_CHANNEL_ENABLED\", \"0\") == \"1\",\n app_id=os.getenv(\"FEISHU_APP_ID\", \"\"),\n app_secret=os.getenv(\"FEISHU_APP_SECRET\", \"\"),\n bot_prefix=os.getenv(\"FEISHU_BOT_PREFIX\", \"[BOT] \"),\n encrypt_key=os.getenv(\"FEISHU_ENCRYPT_KEY\", \"\"),\n verification_token=os.getenv(\"FEISHU_VERIFICATION_TOKEN\", \"\"),\n media_dir=os.getenv(\"FEISHU_MEDIA_DIR\", \"\"),\n on_reply_sent=on_reply_sent,\n dm_policy=os.getenv(\"FEISHU_DM_POLICY\", \"open\"),\n group_policy=os.getenv(\"FEISHU_GROUP_POLICY\", \"open\"),\n allow_from=allow_from,\n deny_message=os.getenv(\"FEISHU_DENY_MESSAGE\", \"\"),\n require_mention=os.getenv(\"FEISHU_REQUIRE_MENTION\", \"0\") == \"1\",\n )\n\n @classmethod\n def from_config(\n cls,\n process: ProcessHandler,\n config: FeishuChannelConfig,\n on_reply_sent: OnReplySent = None,\n show_tool_details: bool = True,\n filter_tool_messages: bool = False,\n filter_thinking: bool = False,\n workspace_dir: Path | None = None,\n ) -> \"FeishuChannel\":\n return cls(\n process=process,\n enabled=config.enabled,\n app_id=config.app_id or \"\",\n app_secret=config.app_secret or \"\",\n bot_prefix=config.bot_prefix or \"[BOT] \",\n encrypt_key=config.encrypt_key or \"\",\n verification_token=config.verification_token or \"\",\n media_dir=config.media_dir or \"\",\n workspace_dir=workspace_dir,\n on_reply_sent=on_reply_sent,\n show_tool_details=show_tool_details,\n filter_tool_messages=filter_tool_messages,\n filter_thinking=filter_thinking,\n dm_policy=config.dm_policy or \"open\",\n group_policy=config.group_policy or \"open\",\n allow_from=config.allow_from or [],\n deny_message=config.deny_message or \"\",\n require_mention=config.require_mention,\n )\n\n def resolve_session_id(\n self,\n sender_id: str,\n channel_meta: Optional[Dict[str, Any]] = None,\n ) -> str:\n \"\"\"Session_id = short suffix of chat_id or open_id for cron lookup.\"\"\"\n meta = channel_meta or {}\n chat_id = (meta.get(\"feishu_chat_id\") or \"\").strip()\n chat_type = (meta.get(\"feishu_chat_type\") or \"p2p\").strip()\n if chat_type == \"group\" and chat_id:\n return short_session_id_from_full_id(chat_id)\n if sender_id:\n return short_session_id_from_full_id(sender_id)\n if chat_id:\n return short_session_id_from_full_id(chat_id)\n return f\"{self.channel}:{sender_id}\"\n\n def build_agent_request_from_native(\n self,\n native_payload: Any,\n ) -> \"AgentRequest\":\n \"\"\"Build AgentRequest from Feishu native dict (content_parts).\"\"\"\n from agentscope_runtime.engine.schemas.agent_schemas import (\n AgentRequest,\n )\n\n payload = native_payload if isinstance(native_payload, dict) else {}\n channel_id = payload.get(\"channel_id\") or self.channel\n sender_id = payload.get(\"sender_id\") or \"\"\n content_parts = payload.get(\"content_parts\") or []\n meta = payload.get(\"meta\") or {}\n # Use payload.session_id when present (e.g. merged native) so we do\n # not recompute from sender_display (e.g. \"949#1d1a\") which would\n # produce wrong short id and break to_handle -> receive_id resolution.\n session_id = payload.get(\"session_id\") or self.resolve_session_id(\n sender_id,\n meta,\n )\n # Prefer real open_id from meta for user_id so to_handle is\n # feishu:sw:{session_id}; fallback to sender_id for display.\n user_id = (\n meta.get(\"feishu_sender_id\") or payload.get(\"user_id\") or sender_id\n )\n request = self.build_agent_request_from_user_content(\n channel_id=channel_id,\n sender_id=user_id,\n session_id=session_id,\n content_parts=content_parts,\n channel_meta=meta,\n )\n # Ensure channel_meta is on request for _before_consume_process\n # (AgentRequest may not have the field; base also sets from payload).\n setattr(request, \"channel_meta\", meta)\n return request\n\n def merge_native_items(self, items: List[Any]) -> Any:\n \"\"\"\n Merge same-session native payloads: concat content_parts, last meta.\n \"\"\"\n if not items:\n return None\n first = items[0] if isinstance(items[0], dict) else {}\n merged_parts: List[Any] = []\n for it in items:\n p = it if isinstance(it, dict) else {}\n merged_parts.extend(p.get(\"content_parts\") or [])\n last = items[-1] if isinstance(items[-1], dict) else {}\n return {\n \"channel_id\": first.get(\"channel_id\") or self.channel,\n \"sender_id\": last.get(\"sender_id\", first.get(\"sender_id\", \"\")),\n \"user_id\": last.get(\"user_id\", first.get(\"user_id\", \"\")),\n \"session_id\": last.get(\"session_id\", first.get(\"session_id\", \"\")),\n \"content_parts\": merged_parts,\n \"meta\": dict(last.get(\"meta\") or {}),\n }\n\n def to_handle_from_target(self, *, user_id: str, session_id: str) -> str:\n # Key by short session_id so cron/job can use same id to look up.\n if session_id:\n return f\"feishu:sw:{session_id}\"\n return f\"feishu:open_id:{user_id}\"\n\n def _route_from_handle(self, to_handle: str) -> Dict[str, str]:\n \"\"\"Parse to_handle -> receive_id_type, receive_id (or session_key for\n feishu:sw:; caller uses _load_receive_id for that).\n \"\"\"\n s = (to_handle or \"\").strip()\n if s.startswith(\"feishu:sw:\"):\n return {\"session_key\": s.replace(\"feishu:sw:\", \"\", 1)}\n if s.startswith(\"feishu:chat_id:\"):\n return {\n \"receive_id_type\": \"chat_id\",\n \"receive_id\": s.replace(\"feishu:chat_id:\", \"\", 1),\n }\n if s.startswith(\"feishu:open_id:\"):\n return {\n \"receive_id_type\": \"open_id\",\n \"receive_id\": s.replace(\"feishu:open_id:\", \"\", 1),\n }\n if s.startswith(\"oc_\"):\n return {\"receive_id_type\": \"chat_id\", \"receive_id\": s}\n if s.startswith(\"ou_\"):\n return {\"receive_id_type\": \"open_id\", \"receive_id\": s}\n return {\"receive_id_type\": \"open_id\", \"receive_id\": s}\n\n async def _get_tenant_access_token(self) -> str:\n \"\"\"Fetch and cache tenant_access_token.\"\"\"\n now = time.time()\n if (\n self._tenant_access_token\n and now\n < self._tenant_access_token_expire_at\n - FEISHU_TOKEN_REFRESH_BEFORE_SECONDS\n ):\n return self._tenant_access_token\n\n async with self._token_lock:\n now = time.time()\n if (\n self._tenant_access_token\n and now\n < self._tenant_access_token_expire_at\n - FEISHU_TOKEN_REFRESH_BEFORE_SECONDS\n ):\n return self._tenant_access_token\n\n url = (\n \"https://open.feishu.cn/open-apis/auth/v3/\"\n \"tenant_access_token/internal\"\n )\n payload = {\n \"app_id\": self.app_id,\n \"app_secret\": self.app_secret,\n }\n async with self._http.post(url, json=payload) as resp:\n data = await resp.json(content_type=None)\n if resp.status >= 400:\n raise RuntimeError(\n f\"Feishu token failed status={resp.status} \"\n f\"body={data}\",\n )\n if data.get(\"code\") != 0:\n raise RuntimeError(\n f\"Feishu token error code={data.get('code')} msg\"\n f\"={data.get('msg')}\",\n )\n token = data.get(\"tenant_access_token\")\n if not token:\n raise RuntimeError(\"Feishu token missing in response\")\n expire = int(data.get(\"expire\", 3600))\n self._tenant_access_token = token\n self._tenant_access_token_expire_at = now + expire\n return token\n\n async def _fetch_bot_open_id(self) -> Optional[str]:\n \"\"\"GET /open-apis/bot/v3/info to get this bot's open_id.\"\"\"\n token = await self._get_tenant_access_token()\n url = \"https://open.feishu.cn/open-apis/bot/v3/info\"\n headers = {\"Authorization\": f\"Bearer {token}\"}\n async with self._http.get(url, headers=headers) as resp:\n data = await resp.json(content_type=None)\n data = data or {}\n if data.get(\"code\", -1) != 0:\n logger.warning(\n \"feishu bot/v3/info error: code=%s msg=%s\",\n data.get(\"code\"),\n data.get(\"msg\"),\n )\n return None\n return (data.get(\"bot\") or {}).get(\"open_id\")\n\n async def _get_user_name_by_open_id(self, open_id: str) -> Optional[str]:\n \"\"\"Fetch user name (nickname) from Feishu Contact API by open_id.\n\n Uses Contact v3 GET /open-apis/contact/v3/users/{user_id} with\n user_id_type=open_id (see Feishu user identity doc:\n https://open.feishu.cn/document/platform-overveiw/basic-concepts/\n user-identity-introduction/open-id).\n Result is cached. Returns None on failure or missing permission.\n \"\"\"\n if not open_id or open_id.startswith(\"unknown_\"):\n return None\n async with self._nickname_cache_lock:\n if open_id in self._nickname_cache:\n return self._nickname_cache[open_id]\n url = (\n \"https://open.feishu.cn/open-apis/contact/v3/users/\"\n f\"{open_id}?user_id_type=open_id\"\n )\n try:\n token = await self._get_tenant_access_token()\n timeout = aiohttp.ClientTimeout(\n total=FEISHU_USER_NAME_FETCH_TIMEOUT,\n )\n async with self._http.get(\n url,\n headers={\"Authorization\": f\"Bearer {token}\"},\n timeout=timeout,\n ) as resp:\n body = await resp.text()\n if resp.status >= 400:\n logger.info(\n \"feishu get user name failed: open_id=%s status=%s\",\n open_id[:20],\n resp.status,\n )\n return None\n try:\n data = json.loads(body) if body else {}\n except json.JSONDecodeError:\n data = {}\n if data.get(\"code\") != 0:\n logger.info(\n \"feishu get user name api error: open_id=%s code=%s \"\n \"msg=%s\",\n open_id[:20],\n data.get(\"code\"),\n data.get(\"msg\", \"\"),\n )\n return None\n # Response per Feishu doc: GET contact/v3/users/{user_id}\n # https://open.feishu.cn/document/server-docs/contact-v3/user/get\n # Body: { \"code\": 0, \"data\": { \"user\": { \"name\": ... } } }\n # \"name\" can be string or i18n object { \"zh_cn\": \"中文\", \"en\": \"en\" }\n user = data.get(\"data\") or {}\n inner = user.get(\"user\") or {}\n name = None\n for obj in (inner, user):\n if not isinstance(obj, dict):\n continue\n raw_name = (\n obj.get(\"name\")\n or obj.get(\"real_name\")\n or obj.get(\n \"nickname\",\n )\n or obj.get(\"name_cn\")\n or obj.get(\"name_en\")\n or obj.get(\n \"en_name\",\n )\n )\n if isinstance(raw_name, str) and raw_name.strip():\n name = raw_name.strip()\n break\n if isinstance(raw_name, dict):\n name = (\n raw_name.get(\"zh_cn\")\n or raw_name.get(\"zh_CN\")\n or raw_name.get(\"zh-Cn\")\n or raw_name.get(\"zh-CN\")\n or raw_name.get(\"en\")\n or (list(raw_name.values()) or [None])[0]\n )\n if name and isinstance(name, str):\n name = name.strip()\n break\n first_val = (list(raw_name.values()) or [None])[0]\n if isinstance(first_val, str) and first_val.strip():\n name = first_val.strip()\n break\n if not name:\n logger.info(\n f\"feishu get user name: no name in response (open_id\"\n f\"={(open_id or '')[:20]}). inner_keys\"\n f\"={list(inner.keys()) if inner else []} - app likely \"\n f\"missing contact name permission. Add scope e.g. \"\n f\"contact:user.base:readonly in Feishu console.\",\n )\n\n if name:\n async with self._nickname_cache_lock:\n if len(self._nickname_cache) >= FEISHU_NICKNAME_CACHE_MAX:\n # Drop oldest: dict has no order, drop arbitrary\n self._nickname_cache.pop(\n next(iter(self._nickname_cache)),\n )\n self._nickname_cache[open_id] = name\n return name\n except asyncio.TimeoutError:\n logger.debug(\n \"feishu get user name timeout: open_id=%s\",\n open_id[:16],\n )\n except Exception:\n logger.debug(\n \"feishu get user name failed: open_id=%s\",\n open_id[:16],\n exc_info=True,\n )\n return None\n\n def _emit_request_threadsafe(self, request: Any) -> None:\n \"\"\"Enqueue request via manager (thread-safe).\"\"\"\n if self._enqueue is not None:\n self._enqueue(request)\n\n def _on_message_sync(self, data: \"P2ImMessageReceiveV1\") -> None:\n \"\"\"Sync handler (called from WebSocket thread).\"\"\"\n if self._closed:\n return\n if not self._loop:\n logger.warning(\"feishu: main loop not set, drop message\")\n return\n if not self._loop.is_running():\n logger.warning(\"feishu: main loop not running, drop message\")\n return\n asyncio.run_coroutine_threadsafe(\n self._on_message(data),\n self._loop,\n )\n\n async def _on_message(self, data: \"P2ImMessageReceiveV1\") -> None:\n \"\"\"Handle one Feishu message: dedup, parse, download media, enqueue.\"\"\"\n if not data or not getattr(data, \"event\", None):\n return\n try:\n event = data.event\n message = getattr(event, \"message\", None)\n sender = getattr(event, \"sender\", None)\n if not message or not sender:\n return\n\n message_id = getattr(message, \"message_id\", None) or \"\"\n message_id = str(message_id).strip()\n if message_id in self._processed_message_ids:\n return\n self._processed_message_ids[message_id] = None\n while len(self._processed_message_ids) > FEISHU_PROCESSED_IDS_MAX:\n self._processed_message_ids.popitem(last=False)\n\n sender_type = getattr(sender, \"sender_type\", \"\") or \"\"\n if sender_type == \"bot\":\n return\n\n sender_id_obj = getattr(sender, \"sender_id\", None)\n sender_id = \"\"\n if sender_id_obj and getattr(sender_id_obj, \"open_id\", None):\n sender_id = str(getattr(sender_id_obj, \"open_id\", \"\")).strip()\n if not sender_id:\n sender_id = f\"unknown_{message_id[:8]}\"\n\n nickname = (\n getattr(sender, \"name\", None)\n or getattr(sender, \"nickname\", None)\n or \"\"\n )\n nickname = nickname.strip() if isinstance(nickname, str) else \"\"\n if not nickname:\n nickname = await self._get_user_name_by_open_id(sender_id)\n sender_display = sender_display_string(nickname, sender_id)\n\n chat_id = str(getattr(message, \"chat_id\", \"\") or \"\").strip()\n chat_type = str(\n getattr(message, \"chat_type\", \"p2p\") or \"p2p\",\n ).strip()\n msg_type = str(\n getattr(message, \"message_type\", \"text\") or \"text\",\n ).strip()\n content_raw = getattr(message, \"content\", None) or \"\"\n\n mentions_raw = getattr(message, \"mentions\", None) or []\n is_bot_mentioned = False\n bot_mention_keys: List[str] = []\n if \"@_all\" in content_raw:\n is_bot_mentioned = True\n if self._bot_open_id and mentions_raw:\n for m in mentions_raw:\n m_id = getattr(m, \"id\", None)\n if not m_id:\n continue\n m_open_id = getattr(m_id, \"open_id\", None) or \"\"\n if m_open_id == self._bot_open_id:\n is_bot_mentioned = True\n key = getattr(m, \"key\", None) or \"\"\n if key:\n bot_mention_keys.append(key)\n\n content_parts: List[Any] = []\n text_parts: List[str] = []\n\n if msg_type == \"text\":\n text = extract_json_key(content_raw, \"text\")\n if text:\n for key in bot_mention_keys:\n text = text.replace(key, \"\")\n text = text.strip()\n if text:\n text_parts.append(text)\n elif msg_type == \"post\":\n text = extract_post_text(content_raw)\n if text:\n text_parts.append(text)\n # Download images in post message\n for img_key in extract_post_image_keys(content_raw):\n url_or_path = await self._download_image_resource(\n message_id,\n img_key,\n )\n if url_or_path:\n content_parts.append(\n ImageContent(\n type=ContentType.IMAGE,\n image_url=url_or_path,\n ),\n )\n else:\n text_parts.append(\"[image: download failed]\")\n # Download media files in post message\n for file_key in extract_post_media_file_keys(content_raw):\n url_or_path = await self._download_file_resource(\n message_id,\n file_key,\n )\n if url_or_path:\n content_parts.append(\n FileContent(\n type=ContentType.FILE,\n file_url=url_or_path,\n ),\n )\n else:\n text_parts.append(\"[media: download failed]\")\n elif msg_type == \"image\":\n image_key = extract_json_key(\n content_raw,\n \"image_key\",\n \"file_key\",\n \"imageKey\",\n \"fileKey\",\n )\n if image_key:\n url_or_path = await self._download_image_resource(\n message_id,\n image_key,\n )\n if url_or_path:\n content_parts.append(\n ImageContent(\n type=ContentType.IMAGE,\n image_url=url_or_path,\n ),\n )\n else:\n text_parts.append(\"[image: download failed]\")\n else:\n text_parts.append(\"[image: missing key]\")\n elif msg_type == \"file\":\n file_key = extract_json_key(\n content_raw,\n \"file_key\",\n \"fileKey\",\n )\n if file_key:\n url_or_path = await self._download_file_resource(\n message_id,\n file_key,\n )\n if url_or_path:\n content_parts.append(\n FileContent(\n type=ContentType.FILE,\n file_url=url_or_path,\n ),\n )\n else:\n text_parts.append(\"[file: download failed]\")\n else:\n text_parts.append(\"[file: missing key]\")\n elif msg_type == \"audio\":\n file_key = extract_json_key(\n content_raw,\n \"file_key\",\n \"fileKey\",\n )\n if file_key:\n url_or_path = await self._download_file_resource(\n message_id,\n file_key,\n filename_hint=\"audio.opus\",\n )\n if url_or_path:\n content_parts.append(\n AudioContent(\n type=ContentType.AUDIO,\n data=url_or_path,\n ),\n )\n else:\n text_parts.append(\"[audio: download failed]\")\n else:\n text_parts.append(\"[audio: missing key]\")\n else:\n text_parts.append(f\"[{msg_type}]\")\n\n text = \"\\n\".join(text_parts).strip() if text_parts else \"\"\n if text:\n content_parts.insert(\n 0,\n TextContent(type=ContentType.TEXT, text=text),\n )\n if not content_parts:\n return\n\n is_group = chat_type == \"group\"\n meta: Dict[str, Any] = {\n \"feishu_message_id\": message_id,\n \"feishu_chat_id\": chat_id,\n \"feishu_chat_type\": chat_type,\n \"feishu_sender_id\": sender_id,\n \"is_group\": is_group,\n }\n receive_id = chat_id if is_group else sender_id\n receive_id_type = \"chat_id\" if is_group else \"open_id\"\n meta[\"feishu_receive_id\"] = receive_id\n meta[\"feishu_receive_id_type\"] = receive_id_type\n if is_bot_mentioned:\n meta[\"bot_mentioned\"] = True\n\n allowed, error_msg = self._check_allowlist(\n sender_id,\n is_group,\n )\n if not allowed:\n logger.info(\n \"feishu allowlist blocked: sender=%s is_group=%s\",\n sender_id,\n is_group,\n )\n await self._send_text(\n receive_id_type,\n receive_id,\n error_msg or \"\",\n )\n return\n\n if not self._check_group_mention(is_group, meta):\n return\n\n await self._add_reaction(message_id, \"Typing\")\n\n session_id = self.resolve_session_id(sender_id, meta)\n native = {\n \"channel_id\": self.channel,\n \"sender_id\": sender_display,\n \"user_id\": sender_display,\n \"session_id\": session_id,\n \"content_parts\": content_parts,\n \"meta\": meta,\n }\n logger.info(\n \"feishu recv from=%s chat=%s msg_id=%s type=%s text_len=%s\",\n sender_display[:40],\n chat_id[:20] if chat_id else \"\",\n message_id[:16] if message_id else \"\",\n msg_type,\n len(text),\n )\n if self._enqueue is not None:\n self._enqueue(native)\n except Exception:\n logger.exception(\"feishu _on_message failed\")\n\n async def _add_reaction(\n self,\n message_id: str,\n emoji_type: str = \"THUMBSUP\",\n ) -> None:\n \"\"\"Add reaction to message (non-blocking).\"\"\"\n if not self._client:\n return\n try:\n loop = asyncio.get_running_loop()\n await loop.run_in_executor(\n None,\n self._add_reaction_sync,\n message_id,\n emoji_type,\n )\n except Exception:\n logger.debug(\n \"feishu add_reaction failed message_id=%s\",\n message_id[:16],\n )\n\n def _add_reaction_sync(self, message_id: str, emoji_type: str) -> None:\n try:\n req = (\n CreateMessageReactionRequest.builder()\n .message_id(\n message_id,\n )\n .request_body(\n CreateMessageReactionRequestBody.builder()\n .reaction_type(\n Emoji.builder().emoji_type(emoji_type).build(),\n )\n .build(),\n )\n .build()\n )\n resp = self._client.im.v1.message_reaction.create(req)\n if not resp.success():\n logger.debug(\n \"feishu reaction failed code=%s msg=%s\",\n getattr(resp, \"code\", \"\"),\n getattr(resp, \"msg\", \"\"),\n )\n except Exception as e:\n logger.debug(\"feishu reaction error: %s\", e)\n\n async def _download_image_resource(\n self,\n message_id: str,\n image_key: str,\n ) -> Optional[str]:\n \"\"\"Download image to media_dir; return local path or None.\"\"\"\n token = await self._get_tenant_access_token()\n url = (\n f\"https://open.feishu.cn/open-apis/im/v1/messages/{message_id}\"\n f\"/resources/{image_key}\"\n )\n headers = {\"Authorization\": f\"Bearer {token}\"}\n try:\n async with self._http.get(\n url,\n params={\"type\": \"image\"},\n headers=headers,\n ) as resp:\n if resp.status >= 400:\n logger.warning(\n \"feishu image download failed status=%s\",\n resp.status,\n )\n return None\n data = await resp.read()\n content_type = (\n resp.headers.get(\"Content-Type\", \"\").split(\";\")[0].strip()\n )\n ext = (mimetypes.guess_extension(content_type) or \".jpg\").lstrip(\n \".\",\n )\n safe_key = (\n \"\".join(c for c in image_key if c.isalnum() or c in \"-_.\")\n or \"img\"\n )\n self._media_dir.mkdir(parents=True, exist_ok=True)\n path = self._media_dir / f\"{message_id}_{safe_key}.{ext}\"\n path.write_bytes(data)\n return str(path)\n except Exception:\n logger.exception(\"feishu _download_image_resource failed\")\n return None\n\n async def _download_file_resource(\n self,\n message_id: str,\n file_key: str,\n filename_hint: str = \"file.bin\",\n ) -> Optional[str]:\n \"\"\"Download file to media_dir; return local path or None.\n Uses message resources API (user-sent files); /im/v1/files only\n allows app-sent files.\n \"\"\"\n token = await self._get_tenant_access_token()\n url = (\n f\"https://open.feishu.cn/open-apis/im/v1/messages/\"\n f\"{message_id}/resources/{file_key}?type=file\"\n )\n headers = {\"Authorization\": f\"Bearer {token}\"}\n try:\n async with self._http.get(url, headers=headers) as resp:\n if resp.status >= 400:\n logger.warning(\n \"feishu file download failed status=%s\",\n resp.status,\n )\n return None\n data = await resp.read()\n disposition = resp.headers.get(\n \"Content-Disposition\",\n \"\",\n )\n content_type = (\n resp.headers.get(\"Content-Type\", \"\").split(\";\")[0].strip()\n )\n filename = filename_hint\n if \"filename=\" in disposition:\n part = (\n disposition.split(\"filename=\", 1)[-1].strip().strip(\"'\\\"\")\n )\n if part:\n part = Path(part).name\n if part.strip():\n filename = part\n # Prevent path traversal: keep only the base name.\n filename = Path(filename).name\n if not filename.strip():\n filename = filename_hint\n # If hint has an extension but chosen filename has none or\n # .bin/.file, force the hint extension so e.g. audio.opus is kept.\n hint_ext = Path(filename_hint).suffix\n if hint_ext and Path(filename).suffix in (\"\", \".bin\", \".file\"):\n filename = (Path(filename).stem or \"file\") + hint_ext\n safe_key = (\n \"\".join(c for c in file_key if c.isalnum() or c in \"-_.\")\n or \"file\"\n )\n self._media_dir.mkdir(parents=True, exist_ok=True)\n path = self._media_dir / f\"{message_id}_{safe_key}_{filename}\"\n path.write_bytes(data)\n if path.suffix in (\".bin\", \".file\") and content_type:\n ext = mimetypes.guess_extension(content_type)\n if ext:\n new_path = path.with_suffix(ext)\n path.rename(new_path)\n path = new_path\n return str(path)\n except Exception:\n logger.exception(\"feishu _download_file_resource failed\")\n return None\n\n def _receive_id_store_path(self) -> Path:\n \"\"\"\n Path to persist receive_id mapping (for cron to resolve after restart).\n\n Uses agent workspace directory if available, otherwise falls back\n to global config directory for backward compatibility.\n \"\"\"\n if self._workspace_dir:\n return self._workspace_dir / \"feishu_receive_ids.json\"\n return get_config_path().parent / \"feishu_receive_ids.json\"\n\n def _load_receive_id_store_from_disk(self) -> None:\n \"\"\"\n Load receive_id mapping from disk into memory\n (call at start or on miss).\n \"\"\"\n path = self._receive_id_store_path()\n if not path.is_file():\n return\n try:\n with open(path, \"r\", encoding=\"utf-8\") as f:\n data = json.load(f)\n if isinstance(data, dict):\n for k, v in data.items():\n if isinstance(v, (list, tuple)) and len(v) >= 2:\n a, b = str(v[0]), str(v[1])\n # Store as (receive_id_type, receive_id).\n # Backward compat: old file has\n # [receive_id, receive_id_type]\n if b in (\"open_id\", \"chat_id\"):\n self._receive_id_store[k] = (b, a)\n else:\n self._receive_id_store[k] = (a, b)\n except Exception:\n logger.debug(\n \"feishu load receive_id store from %s failed\",\n path,\n exc_info=True,\n )\n\n def _save_receive_id_store_to_disk(self) -> None:\n \"\"\"Persist in-memory receive_id store to disk.\"\"\"\n path = self._receive_id_store_path()\n try:\n path.parent.mkdir(parents=True, exist_ok=True)\n # v is (receive_id_type, receive_id)\n with open(path, \"w\", encoding=\"utf-8\") as f:\n json.dump(\n {\n k: [v[0], v[1]] # [receive_id_type, receive_id]\n for k, v in self._receive_id_store.items()\n },\n f,\n indent=2,\n ensure_ascii=False,\n )\n except Exception:\n logger.debug(\n \"feishu save receive_id store to %s failed\",\n path,\n exc_info=True,\n )\n\n async def _save_receive_id(\n self,\n session_id: str,\n receive_id: str,\n receive_id_type: str,\n ) -> None:\n if not session_id or not receive_id:\n return\n async with self._receive_id_lock:\n # Store (receive_id_type, receive_id) to match unpack elsewhere\n self._receive_id_store[session_id] = (receive_id_type, receive_id)\n # Also key by open_id so cron can resolve when session_id is full\n # open_id or when lookup uses open_id as key\n if (\n receive_id_type == \"open_id\"\n and receive_id\n and receive_id != session_id\n ):\n self._receive_id_store[receive_id] = (\n receive_id_type,\n receive_id,\n )\n self._save_receive_id_store_to_disk()\n\n async def _load_receive_id(\n self,\n session_id: str,\n ) -> Optional[Tuple[str, str]]:\n if not session_id:\n return None\n async with self._receive_id_lock:\n out = self._receive_id_store.get(session_id)\n if out is not None:\n return out\n self._load_receive_id_store_from_disk()\n return self._receive_id_store.get(session_id)\n\n def _build_post_content(\n self,\n text: str,\n image_keys: List[str],\n ) -> Dict[str, Any]:\n content_rows: List[List[Dict[str, Any]]] = []\n if text:\n content_rows.append(\n [{\"tag\": \"md\", \"text\": normalize_feishu_md(text)}],\n )\n for image_key in image_keys:\n content_rows.append([{\"tag\": \"img\", \"image_key\": image_key}])\n if not content_rows:\n content_rows = [[{\"tag\": \"md\", \"text\": \"[empty]\"}]]\n return {\n \"zh_cn\": {\n \"content\": content_rows,\n },\n }\n\n def _upload_image_sync(self, data: bytes, filename: str) -> Optional[str]:\n \"\"\"Upload image via lark client; return image_key.\"\"\"\n if not self._client:\n return None\n logger.info(\n \"feishu _upload_image_sync: size=%s filename=%s\",\n len(data),\n filename,\n )\n try:\n import io\n\n req = (\n CreateImageRequest.builder()\n .request_body(\n CreateImageRequestBody.builder()\n .image_type(\"message\")\n .image(io.BytesIO(data))\n .build(),\n )\n .build()\n )\n resp = self._client.im.v1.image.create(req)\n if not resp.success():\n logger.warning(\n \"feishu image upload failed code=%s msg=%s\",\n getattr(resp, \"code\", \"\"),\n getattr(resp, \"msg\", \"\"),\n )\n return None\n key = getattr(resp.data, \"image_key\", None) if resp.data else None\n logger.info(\n \"feishu _upload_image_sync ok: image_key=%s\",\n key[:24] if key else \"None\",\n )\n return key\n except Exception:\n logger.exception(\"feishu _upload_image_sync failed\")\n return None\n\n async def _upload_file(self, path_or_url: str) -> Optional[str]:\n \"\"\"Upload file to Feishu; return file_key. path_or_url can be path.\"\"\"\n token = await self._get_tenant_access_token()\n path = Path(path_or_url)\n if not path.exists():\n if path_or_url.startswith((\"http://\", \"https://\")):\n data = await self._fetch_bytes_from_url(path_or_url)\n if not data:\n return None\n path = self._media_dir / \"upload_temp\"\n path.parent.mkdir(parents=True, exist_ok=True)\n path.write_bytes(data)\n else:\n return None\n size = path.stat().st_size\n if size > FEISHU_FILE_MAX_BYTES:\n logger.warning(\"feishu file too large size=%s\", size)\n return None\n ext = path.suffix.lower().lstrip(\".\")\n file_type = \"stream\"\n if ext in (\n \"pdf\",\n \"doc\",\n \"docx\",\n \"xls\",\n \"xlsx\",\n \"ppt\",\n \"pptx\",\n \"mp4\",\n ):\n file_type = \"doc\" if ext == \"docx\" else ext\n file_type = \"xls\" if ext == \"xlsx\" else file_type\n file_type = \"ppt\" if ext == \"pptx\" else file_type\n mime = mimetypes.guess_type(str(path))[0] or \"application/octet-stream\"\n url = \"https://open.feishu.cn/open-apis/im/v1/files\"\n form = aiohttp.FormData()\n form.add_field(\"file_type\", file_type)\n form.add_field(\"file_name\", path.name)\n form.add_field(\n \"file\",\n path.read_bytes(),\n filename=path.name,\n content_type=mime,\n )\n try:\n async with self._http.post(\n url,\n headers={\"Authorization\": f\"Bearer {token}\"},\n data=form,\n ) as resp:\n data = await resp.json(content_type=None)\n if resp.status >= 400:\n logger.warning(\n \"feishu file upload failed status=%s body=%s\",\n resp.status,\n data,\n )\n return None\n if data.get(\"code\") != 0:\n logger.info(\n \"feishu _upload_file api code=%s msg=%s\",\n data.get(\"code\"),\n data.get(\"msg\"),\n )\n return None\n fk = (data.get(\"data\") or {}).get(\"file_key\")\n logger.info(\n \"feishu _upload_file ok: file_key=%s\",\n fk[:24] if fk else \"None\",\n )\n return fk\n except Exception:\n logger.exception(\"feishu _upload_file failed\")\n return None\n\n async def _fetch_bytes_from_url(self, url: str) -> Optional[bytes]:\n \"\"\"Download binary from URL. Supports http(s):// and file://.\"\"\"\n try:\n path = file_url_to_local_path(url)\n if path is not None:\n return await asyncio.to_thread(Path(path).read_bytes)\n if url.strip().lower().startswith(\"file:\"):\n return None\n async with self._http.get(url) as resp:\n if resp.status >= 400:\n return None\n return await resp.read()\n except Exception:\n logger.exception(\"feishu _fetch_bytes_from_url failed\")\n return None\n\n def _send_message_sync(\n self,\n receive_id_type: str,\n receive_id: str,\n msg_type: str,\n content: str,\n ) -> Optional[str]:\n \"\"\"Send one message (post, image, or file) via lark client.\n\n Returns the message_id on success, None on failure.\n \"\"\"\n if not self._client:\n return None\n logger.info(\n \"feishu _send_message_sync: msg_type=%s receive_id_type=%s \"\n \"content_len=%s\",\n msg_type,\n receive_id_type,\n len(content),\n )\n try:\n req = (\n CreateMessageRequest.builder()\n .receive_id_type(\n receive_id_type,\n )\n .request_body(\n CreateMessageRequestBody.builder()\n .receive_id(receive_id)\n .msg_type(msg_type)\n .content(content)\n .build(),\n )\n .build()\n )\n resp = self._client.im.v1.message.create(req)\n if not resp.success():\n logger.warning(\n \"feishu send failed code=%s msg=%s\",\n getattr(resp, \"code\", \"\"),\n getattr(resp, \"msg\", \"\"),\n )\n return None\n msg_id = (\n getattr(resp.data, \"message_id\", None) if resp.data else None\n )\n logger.info(\n \"feishu _send_message_sync ok: msg_type=%s msg_id=%s\",\n msg_type,\n (msg_id or \"\")[:24],\n )\n return msg_id\n except Exception:\n logger.exception(\"feishu _send_message_sync failed\")\n return None\n\n async def _send_text(\n self,\n receive_id_type: str,\n receive_id: str,\n body: str,\n ) -> Optional[str]:\n \"\"\"Send text as post (md) or interactive card (when body has tables).\n\n Returns the message_id on success, None on failure.\n Body already has bot_prefix if needed.\n When the body contains more than _MAX_TABLES_PER_CARD tables, it\n is split into multiple cards sent sequentially.\n \"\"\"\n has_table = bool(re.search(r\"^\\s*\\|\", body, re.MULTILINE))\n loop = asyncio.get_running_loop()\n if has_table:\n chunks = build_interactive_content_chunks(body)\n last_msg_id: Optional[str] = None\n for chunk in chunks:\n msg_id = await loop.run_in_executor(\n None,\n lambda c=chunk: self._send_message_sync(\n receive_id_type,\n receive_id,\n \"interactive\",\n c,\n ),\n )\n if msg_id is not None:\n last_msg_id = msg_id\n return last_msg_id\n post = self._build_post_content(body, [])\n content = json.dumps(post, ensure_ascii=False)\n return await loop.run_in_executor(\n None,\n lambda: self._send_message_sync(\n receive_id_type,\n receive_id,\n \"post\",\n content,\n ),\n )\n\n async def _part_to_image_bytes(\n self,\n part: OutgoingContentPart,\n ) -> Tuple[Optional[bytes], str]:\n \"\"\"\n Get image bytes from part (url, path, or base64). Return (data, fn).\n \"\"\"\n image_url = getattr(part, \"image_url\", None) or \"\"\n url = (image_url if isinstance(image_url, str) else \"\").strip()\n filename = getattr(part, \"filename\", None) or \"image.png\"\n if url.startswith(\"data:\") and \"base64,\" in url:\n b64 = url\n url = \"\"\n else:\n b64 = None\n if b64:\n raw = (\n b64.split(\"base64,\", 1)[-1].strip()\n if isinstance(b64, str)\n else b64\n )\n try:\n data = base64.b64decode(raw)\n return (data, filename)\n except Exception as e:\n logger.warning(\n \"feishu _part_to_image_bytes base64 decode failed: %s\",\n e,\n )\n return (None, filename)\n if not url and not b64:\n logger.info(\n \"feishu _send_image: part has no image_url/base64\",\n )\n return (None, filename)\n if url.startswith((\"http://\", \"https://\", \"file://\")):\n data = await self._fetch_bytes_from_url(url)\n return (data, filename)\n path = Path(url)\n if path.exists():\n return (path.read_bytes(), filename)\n logger.info(\n \"feishu _send_image: path not found url=%s\",\n url[:80] if url else \"\",\n )\n return (None, filename)\n\n async def _send_image(\n self,\n receive_id_type: str,\n receive_id: str,\n part: OutgoingContentPart,\n ) -> Optional[str]:\n \"\"\"Upload image and send as msg_type=image (image_key) per API.\n\n Returns the message_id on success, None on failure.\n \"\"\"\n logger.info(\n \"feishu _send_image: part type=%s\",\n getattr(part, \"type\", None),\n )\n data, filename = await self._part_to_image_bytes(part)\n if not data:\n logger.info(\n \"feishu _send_image: no image data, skip (url/base64/path)\",\n )\n return None\n loop = asyncio.get_running_loop()\n image_key = await loop.run_in_executor(\n None,\n lambda: self._upload_image_sync(data, filename),\n )\n if not image_key:\n logger.info(\n \"feishu _send_image: upload failed, no image_key\",\n )\n return None\n logger.info(\n \"feishu _send_image: upload ok image_key=%s\",\n image_key[:24] if image_key else \"\",\n )\n content = json.dumps({\"image_key\": image_key}, ensure_ascii=False)\n return await loop.run_in_executor(\n None,\n lambda: self._send_message_sync(\n receive_id_type,\n receive_id,\n \"image\",\n content,\n ),\n )\n\n async def _part_to_file_path_or_url(\n self,\n part: OutgoingContentPart,\n ) -> Optional[str]:\n \"\"\"Resolve part to local path or URL for file upload.\"\"\"\n url = (\n getattr(part, \"file_url\", None)\n or getattr(part, \"image_url\", None)\n or getattr(part, \"video_url\", None)\n or getattr(part, \"data\", None)\n or \"\"\n )\n url = (url or \"\").strip() if isinstance(url, str) else \"\"\n filename = getattr(part, \"filename\", None) or \"file.bin\"\n b64 = None\n if (\n isinstance(url, str)\n and url.startswith(\"data:\")\n and \"base64,\" in url\n ):\n b64 = url\n url = \"\"\n if b64:\n raw = (\n b64.split(\"base64,\", 1)[-1].strip()\n if isinstance(b64, str)\n else b64\n )\n try:\n data = base64.b64decode(raw)\n except Exception as e:\n logger.warning(\n \"feishu _part_to_file_path_or_url base64 decode: %s\",\n e,\n )\n return None\n self._media_dir.mkdir(parents=True, exist_ok=True)\n path = self._media_dir / f\"upload_{id(part)}_{filename}\"\n path.write_bytes(data)\n return str(path)\n if url:\n if url.startswith(\"file://\"):\n local_path = file_url_to_local_path(url)\n if local_path:\n path = Path(local_path)\n if path.exists():\n return str(path)\n else:\n path = Path(url)\n if path.exists():\n return url\n if url.startswith((\"http://\", \"https://\")):\n return url\n logger.info(\n \"feishu _send_file: part has no file_url/url/base64\",\n )\n return None\n\n async def _send_file(\n self,\n receive_id_type: str,\n receive_id: str,\n part: OutgoingContentPart,\n ) -> Optional[str]:\n \"\"\"Upload file and send file message (msg_type=file, file_key).\n\n Returns the message_id on success, None on failure.\n \"\"\"\n logger.info(\n \"feishu _send_file: part type=%s\",\n getattr(part, \"type\", None),\n )\n path_or_url = await self._part_to_file_path_or_url(part)\n if not path_or_url:\n logger.info(\n \"feishu _send_file: no path/url/base64, skip\",\n )\n return None\n file_key = await self._upload_file(path_or_url)\n if not file_key:\n logger.info(\n \"feishu _send_file: upload failed, no file_key\",\n )\n return None\n logger.info(\n \"feishu _send_file: upload ok file_key=%s\",\n file_key[:24] if file_key else \"\",\n )\n content = json.dumps({\"file_key\": file_key}, ensure_ascii=False)\n loop = asyncio.get_running_loop()\n return await loop.run_in_executor(\n None,\n lambda: self._send_message_sync(\n receive_id_type,\n receive_id,\n \"file\",\n content,\n ),\n )\n\n async def _get_receive_for_send(\n self,\n to_handle: str,\n meta: Optional[Dict[str, Any]],\n ) -> Optional[Tuple[str, str]]:\n \"\"\"Resolve (receive_id_type, receive_id) from to_handle or meta.\"\"\"\n m = meta or {}\n rid = m.get(\"feishu_receive_id\")\n rtype = m.get(\"feishu_receive_id_type\", \"open_id\")\n if rid:\n logger.info(\n \"feishu _get_receive_for_send: from meta receive_id_type=%s\",\n rtype,\n )\n return (rtype, rid)\n route = self._route_from_handle(to_handle)\n session_key = route.get(\"session_key\")\n logger.info(\n \"feishu _get_receive_for_send: to_handle=%s route=%s \"\n \"session_key=%s\",\n (to_handle or \"\")[:60],\n list(route.keys()) if route else [],\n (session_key or \"\")[:40] if session_key else None,\n )\n if session_key:\n recv = await self._load_receive_id(session_key)\n if recv is not None:\n logger.info(\n \"feishu _get_receive_for_send: loaded from store \"\n \"receive_id_type=%s\",\n recv[0],\n )\n return recv\n # Fallback: session_key may be old-format \"feishu:open_id:ou_xxx\"\n if session_key.startswith(\"feishu:open_id:\"):\n rid = session_key.replace(\"feishu:open_id:\", \"\", 1).strip()\n if rid:\n logger.info(\n \"feishu _get_receive_for_send: fallback open_id\",\n )\n return (\"open_id\", rid)\n # Fallback: session_key may be display \"nickname#last4\" (e.g. from\n # cron target.user_id); try match by open_id ending with last4\n if \"#\" in session_key:\n suffix = session_key.split(\"#\", 1)[-1].strip()\n if len(suffix) >= 4:\n async with self._receive_id_lock:\n for _, v in self._receive_id_store.items():\n # v is (receive_id_type, receive_id)\n if v[1] and str(v[1]).endswith(suffix):\n logger.info(\n \"feishu _get_receive_for_send: \"\n \"fallback match by suffix %s\",\n suffix,\n )\n return v\n logger.warning(\n \"feishu _get_receive_for_send: no store entry for \"\n \"session_key=%s (user must have chatted first or add \"\n \"feishu_receive_id in dispatch.meta)\",\n (session_key or \"\")[:40],\n )\n rid = route.get(\"receive_id\")\n rtype = route.get(\"receive_id_type\", \"open_id\")\n if rid:\n return (rtype, rid)\n recv = await self._load_receive_id(to_handle)\n if recv is None:\n logger.warning(\n \"feishu _get_receive_for_send: _load_receive_id(%s) returned \"\n \"None\",\n (to_handle or \"\")[:40],\n )\n return recv\n\n async def send_content_parts( # type: ignore[override]\n self,\n to_handle: str,\n parts: List[OutgoingContentPart],\n meta: Optional[Dict[str, Any]] = None,\n ) -> Optional[str]:\n \"\"\"Send text as post (md), then images, then files.\n\n Returns the message_id of the last successfully sent message,\n or None if nothing was sent.\n \"\"\"\n if not self.enabled:\n return None\n recv = await self._get_receive_for_send(to_handle, meta)\n if not recv:\n logger.warning(\n \"feishu send_content_parts: no receive_id for to_handle=%s \"\n \"(cron will not send; ensure user chatted once or set \"\n \"dispatch.meta.feishu_receive_id)\",\n to_handle[:50] if to_handle else \"\",\n )\n return None\n receive_id_type, receive_id = recv\n logger.info(\n \"feishu send_content_parts: resolved receive_id_type=%s \"\n \"receive_id=%s...\",\n receive_id_type,\n (receive_id or \"\")[:20],\n )\n prefix = (meta or {}).get(\"bot_prefix\", \"\") or self.bot_prefix or \"\"\n text_parts: List[str] = []\n media_parts: List[OutgoingContentPart] = []\n for p in parts:\n t = getattr(p, \"type\", None) or (\n p.get(\"type\") if isinstance(p, dict) else None\n )\n text_val = getattr(p, \"text\", None) or (\n p.get(\"text\") if isinstance(p, dict) else None\n )\n refusal_val = getattr(p, \"refusal\", None) or (\n p.get(\"refusal\") if isinstance(p, dict) else None\n )\n if t == ContentType.TEXT and text_val:\n text_parts.append(text_val or \"\")\n elif t == ContentType.REFUSAL and refusal_val:\n text_parts.append(refusal_val or \"\")\n elif t in (\n ContentType.IMAGE,\n ContentType.FILE,\n ContentType.VIDEO,\n ContentType.AUDIO,\n ):\n media_parts.append(p)\n body = \"\\n\".join(text_parts).strip()\n logger.info(\n \"feishu send_content_parts: to_handle=%s text_parts=%s \"\n \"media_count=%s media_types=%s\",\n to_handle[:40] if to_handle else \"\",\n len(text_parts),\n len(media_parts),\n [getattr(m, \"type\", None) for m in media_parts],\n )\n if prefix and body:\n body = prefix + body\n last_message_id: Optional[str] = None\n if body:\n last_message_id = await self._send_text(\n receive_id_type,\n receive_id,\n body,\n )\n for part in media_parts:\n pt = getattr(part, \"type\", None)\n if pt == ContentType.IMAGE:\n msg_id = await self._send_image(\n receive_id_type,\n receive_id,\n part,\n )\n logger.info(\n \"feishu send_content_parts: image sent ok=%s\",\n bool(msg_id),\n )\n if msg_id:\n last_message_id = msg_id\n elif pt in (\n ContentType.FILE,\n ContentType.VIDEO,\n ContentType.AUDIO,\n ):\n msg_id = await self._send_file(\n receive_id_type,\n receive_id,\n part,\n )\n logger.info(\n \"feishu send_content_parts: file sent ok=%s type=%s\",\n bool(msg_id),\n pt,\n )\n if msg_id:\n last_message_id = msg_id\n return last_message_id\n\n async def _run_process_loop(\n self,\n request: Any,\n to_handle: str,\n send_meta: Dict[str, Any],\n ) -> None:\n \"\"\"Override to track the last sent message_id across all events\n and add a DONE reaction after the full reply is complete.\n \"\"\"\n last_message_id: Optional[str] = None\n last_response = None\n try:\n async for event in self._process(request):\n obj = getattr(event, \"object\", None)\n status = getattr(event, \"status\", None)\n if obj == \"message\" and status == RunStatus.Completed:\n parts = self._message_to_content_parts(event)\n if parts:\n msg_id = await self.send_content_parts(\n to_handle,\n parts,\n send_meta,\n )\n if msg_id:\n last_message_id = msg_id\n elif obj == \"response\":\n last_response = event\n await self.on_event_response(request, event)\n err_msg = self._get_response_error_message(last_response)\n if err_msg:\n await self._on_consume_error(\n request,\n to_handle,\n f\"Error: {err_msg}\",\n )\n elif last_message_id:\n await self._add_reaction(last_message_id, \"DONE\")\n if self._on_reply_sent:\n args = self.get_on_reply_sent_args(request, to_handle)\n self._on_reply_sent(self.channel, *args)\n except Exception:\n logger.exception(\"channel consume_one failed\")\n await self._on_consume_error(\n request,\n to_handle,\n \"An error occurred while processing your request.\",\n )\n\n async def send(\n self,\n to_handle: str,\n text: str,\n meta: Optional[Dict[str, Any]] = None,\n ) -> None:\n \"\"\"Proactive send: resolve receive_id and send text as post.\"\"\"\n if not self.enabled:\n return\n recv = await self._get_receive_for_send(to_handle, meta)\n if not recv:\n logger.warning(\n \"feishu send: no receive_id for to_handle=%s\",\n to_handle[:50] if to_handle else \"\",\n )\n return\n receive_id_type, receive_id = recv\n prefix = (meta or {}).get(\"bot_prefix\", \"\") or self.bot_prefix or \"\"\n body = (prefix + text) if text else prefix\n if body:\n await self._send_text(receive_id_type, receive_id, body)\n\n def get_to_handle_from_request(self, request: Any) -> str:\n \"\"\"Feishu sends by session_id; return feishu:sw: or feishu:open_id:\n so _route_from_handle resolves session_key and we load full receive_id.\n \"\"\"\n session_id = getattr(request, \"session_id\", \"\") or \"\"\n user_id = getattr(request, \"user_id\", \"\") or \"\"\n if session_id:\n return f\"feishu:sw:{session_id}\"\n if user_id:\n return f\"feishu:open_id:{user_id}\"\n return \"\"\n\n def get_on_reply_sent_args(\n self,\n request: Any,\n to_handle: str,\n ) -> tuple:\n \"\"\"Feishu callback expects (user_id, session_id).\"\"\"\n return (\n getattr(request, \"user_id\", \"\") or \"\",\n getattr(request, \"session_id\", \"\") or \"\",\n )\n\n async def _before_consume_process(self, request: Any) -> None:\n \"\"\"Save receive_id from webhook meta for later send.\"\"\"\n meta = getattr(request, \"channel_meta\", None) or {}\n receive_id = meta.get(\"feishu_receive_id\")\n receive_id_type = meta.get(\"feishu_receive_id_type\", \"open_id\")\n if receive_id and getattr(request, \"session_id\", None):\n await self._save_receive_id(\n request.session_id,\n receive_id,\n receive_id_type,\n )\n\n def _run_ws_forever(self) -> None:\n # lark-oapi ws.Client uses a module-level event loop; when start()\n # runs in this thread it must use this thread's loop, not main's.\n self._ws_loop = asyncio.new_event_loop()\n asyncio.set_event_loop(self._ws_loop)\n old_ws_client_loop = None\n try:\n import lark_oapi.ws.client as ws_client\n\n # Save old loop value to restore later (for multi-instance)\n old_ws_client_loop = getattr(ws_client, \"loop\", None)\n ws_client.loop = self._ws_loop\n except ImportError:\n pass\n try:\n if self._ws_client:\n logger.info(\"feishu WebSocket connecting (long connection)...\")\n self._ws_client.start()\n except RuntimeError as e:\n # Normal shutdown: loop.stop() causes run_until_complete to raise\n # \"Event loop stopped before Future completed.\"\n if \"Event loop stopped\" in str(e):\n logger.debug(\"feishu WebSocket stopped normally: %s\", e)\n else:\n logger.exception(\"feishu WebSocket thread failed\")\n except Exception:\n logger.exception(\"feishu WebSocket thread failed\")\n finally:\n # Graceful cleanup: disconnect, cancel tasks, close loop\n if self._ws_loop and not self._ws_loop.is_closed():\n try:\n # 1. Disconnect WebSocket\n if self._ws_client and hasattr(\n self._ws_client,\n \"_disconnect\",\n ):\n try:\n self._ws_loop.run_until_complete(\n self._ws_client._disconnect(),\n )\n logger.debug(\n \"feishu WebSocket disconnected gracefully\",\n )\n except Exception:\n logger.debug(\n \"feishu ws disconnect failed\",\n exc_info=True,\n )\n\n # 2. Cancel all running tasks\n pending = [\n t\n for t in asyncio.all_tasks(self._ws_loop)\n if not t.done()\n ]\n for task in pending:\n task.cancel()\n if pending:\n self._ws_loop.run_until_complete(\n asyncio.gather(*pending, return_exceptions=True),\n )\n logger.debug(f\"feishu cancelled {len(pending)} tasks\")\n except Exception:\n logger.debug(\"feishu ws cleanup failed\", exc_info=True)\n\n # Restore ws_client.loop to avoid affecting other instances.\n # ws_client.loop is a module-level global variable shared\n # across all FeishuChannel instances. We must restore it to\n # the previous value (or None if it was our loop) to avoid\n # breaking other running instances or new instances during\n # reload.\n try:\n import lark_oapi.ws.client as ws_client\n\n # Only restore if current loop is still ours\n if getattr(ws_client, \"loop\", None) is self._ws_loop:\n ws_client.loop = old_ws_client_loop\n except Exception:\n pass\n\n # Close event loop\n try:\n if self._ws_loop and not self._ws_loop.is_closed():\n self._ws_loop.close()\n except Exception:\n logger.debug(\"feishu ws loop close failed\", exc_info=True)\n self._ws_loop = None\n self._stop_event.set()\n\n async def start(self) -> None:\n if not self.enabled:\n logger.debug(\"feishu channel disabled\")\n return\n self._closed = False\n self._load_receive_id_store_from_disk()\n if lark is None:\n raise RuntimeError(\n \"Feishu channel enabled but lark-oapi is not installed. \"\n \"Run: pip install lark-oapi\",\n )\n if not self.app_id or not self.app_secret:\n raise RuntimeError(\n \"FEISHU_APP_ID and FEISHU_APP_SECRET are required when \"\n \"feishu channel is enabled.\",\n )\n self._loop = asyncio.get_running_loop()\n self._client = (\n lark.Client.builder()\n .app_id(self.app_id)\n .app_secret(\n self.app_secret,\n )\n .log_level(lark.LogLevel.INFO)\n .build()\n )\n event_handler = (\n lark.EventDispatcherHandler.builder(\n self.encrypt_key,\n self.verification_token,\n )\n .register_p2_im_message_receive_v1(self._on_message_sync)\n .build()\n )\n self._ws_client = lark.ws.Client(\n self.app_id,\n self.app_secret,\n event_handler=event_handler,\n log_level=lark.LogLevel.INFO,\n )\n self._stop_event.clear()\n self._ws_thread = threading.Thread(\n target=self._run_ws_forever,\n daemon=True,\n )\n self._ws_thread.start()\n if self._http is None:\n self._http = aiohttp.ClientSession()\n try:\n self._bot_open_id = await self._fetch_bot_open_id()\n logger.info(\n \"feishu: bot open_id=%s\",\n self._bot_open_id[:12] if self._bot_open_id else \"?\",\n )\n except Exception:\n logger.warning(\n \"feishu: failed to fetch bot open_id (non-fatal)\",\n )\n logger.info(\"feishu channel started (app_id=%s)\", self.app_id[:12])\n\n async def stop(self) -> None:\n if not self.enabled:\n return\n\n self._closed = True\n self._stop_event.set()\n\n # Stop the WebSocket event loop - cleanup happens in _run_ws_forever\n # finally block (disconnect, cancel tasks, close loop)\n if self._ws_loop and not self._ws_loop.is_closed():\n try:\n self._ws_loop.call_soon_threadsafe(self._ws_loop.stop)\n except Exception:\n logger.debug(\"feishu ws_loop.stop failed\", exc_info=True)\n\n if self._ws_thread:\n self._ws_thread.join(timeout=5)\n if self._ws_thread.is_alive():\n logger.warning(\"feishu ws thread did not stop within timeout\")\n\n if self._http is not None:\n await self._http.close()\n self._http = None\n\n self._client = None\n self._ws_client = None\n self._ws_thread = None\n self._ws_loop = None\n logger.info(\"feishu channel stopped\")\n" }, { "path": "src/copaw/app/channels/feishu/constants.py", "content": "# -*- coding: utf-8 -*-\n\"\"\"Feishu channel constants.\"\"\"\n\n# Token cache: refresh 1 min before expire\nFEISHU_TOKEN_REFRESH_BEFORE_SECONDS = 60\n\n# Max size for Feishu file upload (30MB)\nFEISHU_FILE_MAX_BYTES = 30 * 1024 * 1024\n\n# Dedup cache max size\nFEISHU_PROCESSED_IDS_MAX = 1000\n\n# Nickname cache max size (open_id -> name from Contact API)\nFEISHU_NICKNAME_CACHE_MAX = 500\n\n# Short suffix length for session_id (from chat_id or open_id)\nFEISHU_SESSION_ID_SUFFIX_LEN = 8\n\n# Timeout for Contact API when fetching user name by open_id (seconds)\nFEISHU_USER_NAME_FETCH_TIMEOUT = 2\n" }, { "path": "src/copaw/app/channels/feishu/utils.py", "content": "# -*- coding: utf-8 -*-\n\"\"\"Feishu channel helpers (session id, sender display, markdown, table).\"\"\"\n\nimport json\nimport re\nfrom typing import Any, Dict, List, Optional\n\nfrom .constants import FEISHU_SESSION_ID_SUFFIX_LEN\n\n\ndef short_session_id_from_full_id(full_id: str) -> str:\n \"\"\"Use last N chars of full_id (chat_id or open_id) as session_id.\"\"\"\n n = FEISHU_SESSION_ID_SUFFIX_LEN\n return full_id[-n:] if len(full_id) >= n else full_id\n\n\ndef sender_display_string(\n nickname: Optional[str],\n sender_id: str,\n) -> str:\n \"\"\"Build sender display as nickname#last4(sender_id), like DingTalk.\"\"\"\n nick = (nickname or \"\").strip() if isinstance(nickname, str) else \"\"\n sid = (sender_id or \"\").strip()\n suffix = sid[-4:] if len(sid) >= 4 else (sid or \"????\")\n return f\"{(nick or 'unknown')}#{suffix}\"\n\n\ndef extract_json_key(content: Optional[str], *keys: str) -> Optional[str]:\n \"\"\"Parse JSON content and return first present key.\"\"\"\n if not content:\n return None\n try:\n data = json.loads(content)\n except json.JSONDecodeError:\n return None\n for k in keys:\n v = data.get(k) or data.get(k.replace(\"_\", \"\").lower())\n if v:\n return str(v).strip()\n return None\n\n\ndef extract_post_text(content: Optional[str]) -> Optional[str]:\n # pylint: disable=too-many-branches\n \"\"\"Extract plain text from Feishu post message content.\"\"\"\n if not content:\n return None\n try:\n data = json.loads(content)\n except json.JSONDecodeError:\n return None\n\n if not isinstance(data, dict):\n return None\n\n parts: list[str] = []\n\n # Extract title if present\n title = data.get(\"title\")\n if title and isinstance(title, str) and title.strip():\n parts.append(title.strip())\n\n # Extract text from content blocks\n content_blocks = data.get(\"content\") or []\n if isinstance(content_blocks, list):\n for block in content_blocks:\n if not isinstance(block, list):\n continue\n for item in block:\n if not isinstance(item, dict):\n continue\n tag = item.get(\"tag\")\n # text, code_block, md tags have text field\n if tag in {\"text\", \"code_block\", \"md\"}:\n text = item.get(\"text\")\n if isinstance(text, str) and text.strip():\n parts.append(text.strip())\n # a tag: text + href as markdown link\n elif tag == \"a\":\n text = item.get(\"text\", \"\")\n href = item.get(\"href\", \"\")\n if href:\n parts.append(f\"[{text}]({href})\" if text else href)\n elif text:\n parts.append(text.strip())\n # at tag uses user_name\n elif tag == \"at\":\n user_name = item.get(\"user_name\") or item.get(\"user_id\")\n if isinstance(user_name, str) and user_name.strip():\n parts.append(f\"@{user_name.strip()}\")\n\n return \" \".join(parts) if parts else None\n\n\ndef _extract_post_keys(\n content: Optional[str],\n tag: str,\n key_name: str,\n) -> list[str]:\n \"\"\"Extract key_name values from items matching tag in post content.\"\"\"\n if not content:\n return []\n try:\n data = json.loads(content)\n except json.JSONDecodeError:\n return []\n if not isinstance(data, dict):\n return []\n keys: list[str] = []\n content_blocks = data.get(\"content\") or []\n if isinstance(content_blocks, list):\n for block in content_blocks:\n if not isinstance(block, list):\n continue\n for item in block:\n if not isinstance(item, dict):\n continue\n if item.get(\"tag\") == tag:\n key = item.get(key_name)\n if isinstance(key, str) and key.strip():\n keys.append(key.strip())\n return keys\n\n\ndef extract_post_image_keys(content: Optional[str]) -> list[str]:\n \"\"\"Extract image_key list from Feishu post message content.\"\"\"\n return _extract_post_keys(content, \"img\", \"image_key\")\n\n\ndef extract_post_media_file_keys(content: Optional[str]) -> list[str]:\n \"\"\"Extract file_key list from ``tag=media`` blocks in post content.\"\"\"\n return _extract_post_keys(content, \"media\", \"file_key\")\n\n\ndef normalize_feishu_md(text: str) -> str:\n \"\"\"\n Light markdown normalization for Feishu post (avoid broken rendering).\n \"\"\"\n if not text or not text.strip():\n return text\n # Ensure newline before code fence so Feishu parses it\n text = re.sub(r\"([^\\n])(```)\", r\"\\1\\n\\2\", text)\n return text\n\n\ndef _parse_md_table(table_lines: List[str]) -> Optional[Dict[str, Any]]:\n \"\"\"Parse GFM table lines into a Feishu native table component dict.\"\"\"\n # Filter out empty lines kept in block\n lines = [ln for ln in table_lines if ln.strip()]\n if len(lines) < 2:\n return None\n # Row 0: header, Row 1: separator (---|---), Row 2+: data rows\n sep_idx = None\n for i, ln in enumerate(lines):\n # Separator row: only contains |, -, :, spaces\n if re.match(r\"^\\s*\\|[\\s\\-\\:\\|]+\\|\\s*$\", ln):\n sep_idx = i\n break\n if sep_idx is None or sep_idx == 0:\n return None\n\n def split_row(line: str) -> List[str]:\n # Strip leading/trailing | and split\n stripped = line.strip()\n if stripped.startswith(\"|\"):\n stripped = stripped[1:]\n if stripped.endswith(\"|\"):\n stripped = stripped[:-1]\n return [c.strip() for c in stripped.split(\"|\")]\n\n headers = split_row(lines[0])\n if not headers:\n return None\n # Build column keys (safe ASCII slugs)\n col_keys = [f\"col{i}\" for i in range(len(headers))]\n\n # Parse alignment from separator line (e.g., |:---|:--:|---:|)\n def parse_alignment(sep_line: str) -> List[str]:\n cells = split_row(sep_line)\n alignments = []\n for cell in cells:\n stripped = cell.strip()\n if stripped.startswith(\":\") and stripped.endswith(\":\"):\n alignments.append(\"center\")\n elif stripped.endswith(\":\"):\n alignments.append(\"right\")\n else:\n alignments.append(\"left\")\n return alignments\n\n alignments = (\n parse_alignment(lines[sep_idx])\n if sep_idx is not None\n else [\"left\"] * len(headers)\n )\n\n # Build column definitions with auto width and parsed alignment.\n columns = [\n {\n \"name\": col_keys[i],\n \"display_name\": headers[i],\n \"width\": \"auto\",\n \"horizontal_align\": alignments[i]\n if i < len(alignments)\n else \"left\",\n }\n for i in range(len(headers))\n ]\n rows = []\n for line in lines[sep_idx + 1 :]:\n cells = split_row(line)\n row: Dict[str, Any] = {}\n for i, key in enumerate(col_keys):\n cell_text = cells[i] if i < len(cells) else \"\"\n # Strip Markdown emphasis; table cells are plain strings.\n cell_text = re.sub(r\"[*_]{1,2}(.+?)[*_]{1,2}\", r\"\\1\", cell_text)\n row[key] = cell_text\n rows.append(row)\n if not rows:\n return None\n return {\n \"tag\": \"table\",\n \"page_size\": min(max(len(rows), 10), 50),\n \"columns\": columns,\n \"rows\": rows,\n }\n\n\ndef _convert_md_headings_to_bold(text: str) -> str:\n \"\"\"Convert Markdown headings (##, ###, etc.) to bold text.\"\"\"\n return re.sub(r\"^#{1,6}\\s+(.+)$\", r\"**\\1**\", text, flags=re.MULTILINE)\n\n\n_MAX_TABLES_PER_CARD = 5\n\n\ndef _build_elements(text: str) -> List[Dict[str, Any]]:\n \"\"\"Parse text into a list of card elements (table or markdown).\"\"\"\n lines = text.split(\"\\n\")\n elements: List[Dict[str, Any]] = []\n i = 0\n while i < len(lines):\n line = lines[i]\n if re.match(r\"^\\s*\\|\", line):\n table_block: List[str] = []\n while i < len(lines) and re.match(\n r\"^\\s*\\|\",\n lines[i],\n ):\n table_block.append(lines[i])\n i += 1\n table_elem = _parse_md_table(table_block)\n if table_elem:\n elements.append(table_elem)\n else:\n fallback = _convert_md_headings_to_bold(\n \"\\n\".join(table_block),\n )\n elements.append(\n {\"tag\": \"markdown\", \"content\": fallback},\n )\n else:\n text_block: List[str] = []\n while i < len(lines) and not re.match(\n r\"^\\s*\\|\",\n lines[i],\n ):\n text_block.append(lines[i])\n i += 1\n content = \"\\n\".join(text_block).strip()\n if content:\n content = _convert_md_headings_to_bold(content)\n elements.append(\n {\"tag\": \"markdown\", \"content\": content},\n )\n if not elements:\n elements = [\n {\n \"tag\": \"markdown\",\n \"content\": _convert_md_headings_to_bold(text),\n },\n ]\n return elements\n\n\ndef _split_elements(\n elements: List[Dict[str, Any]],\n) -> List[List[Dict[str, Any]]]:\n \"\"\"Split elements into chunks, each with at most _MAX_TABLES_PER_CARD.\"\"\"\n chunks: List[List[Dict[str, Any]]] = []\n current: List[Dict[str, Any]] = []\n # Non-table elements buffered until we know which chunk they belong to.\n pending: List[Dict[str, Any]] = []\n table_count = 0\n for elem in elements:\n if elem.get(\"tag\") == \"table\":\n if table_count >= _MAX_TABLES_PER_CARD:\n # Flush current chunk; pending text belongs to next chunk.\n chunks.append(current)\n current = list(pending)\n table_count = 0\n else:\n current.extend(pending)\n pending = []\n current.append(elem)\n table_count += 1\n else:\n pending.append(elem)\n # Remaining pending text follows the last table chunk.\n current.extend(pending)\n if current:\n chunks.append(current)\n return chunks\n\n\ndef build_interactive_content(text: str) -> str:\n \"\"\"Build an interactive card JSON with mixed markdown + native table.\"\"\"\n elements = _build_elements(text)\n card = {\"elements\": elements}\n return json.dumps(card, ensure_ascii=False)\n\n\ndef build_interactive_content_chunks(text: str) -> List[str]:\n \"\"\"Build card JSONs, split when table count exceeds the limit.\"\"\"\n elements = _build_elements(text)\n chunks = _split_elements(elements)\n return [\n json.dumps({\"elements\": chunk}, ensure_ascii=False) for chunk in chunks\n ]\n" }, { "path": "src/copaw/app/channels/imessage/__init__.py", "content": "# -*- coding: utf-8 -*-\n\"\"\"iMessage channel package.\"\"\"\nfrom .channel import IMessageChannel\n\n__all__ = [\"IMessageChannel\"]\n" }, { "path": "src/copaw/app/channels/imessage/channel.py", "content": "# -*- coding: utf-8 -*-\n# pylint:disable=too-many-return-statements\nfrom __future__ import annotations\n\nimport logging\nimport os\nimport time\nimport sqlite3\nimport subprocess\nimport threading\nimport shutil\nimport asyncio\nimport base64\nimport hashlib\nfrom pathlib import Path\nfrom typing import Any, Dict, Optional, List\n\nfrom agentscope_runtime.engine.schemas.agent_schemas import (\n TextContent,\n ContentType,\n)\n\nfrom ....config.config import IMessageChannelConfig\nfrom ....constant import DEFAULT_MEDIA_DIR\nfrom ..utils import file_url_to_local_path\nfrom ....agents.utils.file_handling import download_file_from_url\n\nfrom ..base import (\n BaseChannel,\n OnReplySent,\n ProcessHandler,\n OutgoingContentPart,\n)\n\nlogger = logging.getLogger(__name__)\n\n\nclass IMessageChannel(BaseChannel):\n channel = \"imessage\"\n\n def __init__(\n self,\n process: ProcessHandler,\n enabled: bool,\n db_path: str,\n poll_sec: float,\n bot_prefix: str,\n media_dir: str = \"\",\n max_decoded_size: int = 10 * 1024 * 1024, # 10MB default\n on_reply_sent: OnReplySent = None,\n show_tool_details: bool = True,\n filter_tool_messages: bool = False,\n filter_thinking: bool = False,\n ):\n super().__init__(\n process,\n on_reply_sent=on_reply_sent,\n show_tool_details=show_tool_details,\n filter_tool_messages=filter_tool_messages,\n filter_thinking=filter_thinking,\n )\n self.enabled = enabled\n self.db_path = os.path.expanduser(db_path)\n self.poll_sec = poll_sec\n self.bot_prefix = bot_prefix\n\n # Create media directory for downloaded files\n self._media_dir = (\n Path(media_dir).expanduser() if media_dir else DEFAULT_MEDIA_DIR\n )\n self._media_dir.mkdir(parents=True, exist_ok=True)\n\n # Base64 data size limit\n self.max_decoded_size = max_decoded_size\n\n self._imsg_path: Optional[str] = None\n self._stop_event = threading.Event()\n self._thread: Optional[threading.Thread] = None\n\n @classmethod\n def from_env(\n cls,\n process: ProcessHandler,\n on_reply_sent: OnReplySent = None,\n ) -> \"IMessageChannel\":\n return cls(\n process=process,\n enabled=os.getenv(\"IMESSAGE_CHANNEL_ENABLED\", \"1\") == \"1\",\n db_path=os.getenv(\n \"IMESSAGE_DB_PATH\",\n \"~/Library/Messages/chat.db\",\n ),\n poll_sec=float(os.getenv(\"IMESSAGE_POLL_SEC\", \"1.0\")),\n bot_prefix=os.getenv(\"IMESSAGE_BOT_PREFIX\", \"[BOT] \"),\n media_dir=os.getenv(\"IMESSAGE_MEDIA_DIR\", \"\"),\n max_decoded_size=int(\n os.getenv(\"IMESSAGE_MAX_DECODED_SIZE\", \"10485760\"),\n ), # 10MB\n on_reply_sent=on_reply_sent,\n )\n\n @classmethod\n def from_config(\n cls,\n process: ProcessHandler,\n config: IMessageChannelConfig,\n on_reply_sent: OnReplySent = None,\n show_tool_details: bool = True,\n filter_tool_messages: bool = False,\n filter_thinking: bool = False,\n ) -> \"IMessageChannel\":\n return cls(\n process=process,\n enabled=config.enabled,\n db_path=config.db_path or \"~/Library/Messages/chat.db\",\n poll_sec=config.poll_sec,\n bot_prefix=config.bot_prefix or \"[BOT] \",\n media_dir=config.media_dir if config.media_dir else \"\",\n max_decoded_size=config.max_decoded_size,\n on_reply_sent=on_reply_sent,\n show_tool_details=show_tool_details,\n filter_tool_messages=filter_tool_messages,\n filter_thinking=filter_thinking,\n )\n\n def _ensure_imsg(self) -> str:\n path = shutil.which(\"imsg\")\n if not path:\n raise RuntimeError(\n \"Cannot find executable: imsg. Install it with:\\n\"\n \" brew install steipete/tap/imsg\\n\"\n \"Then verify:\\n\"\n \" which imsg\\n\",\n )\n return path\n\n def _send_sync(\n self,\n to_handle: str,\n text: str,\n file_path: Optional[str] = None,\n ) -> None:\n if not self._imsg_path:\n raise RuntimeError(\n \"iMessage channel not initialized (imsg path missing).\",\n )\n # Capture stdout/stderr so imsg's \"sent\" (or similar) does not\n # appear in our process output.\n cmd = [self._imsg_path, \"send\", \"--to\", to_handle]\n if text:\n cmd.extend([\"--text\", text])\n if file_path:\n cmd.extend([\"--file\", file_path])\n\n result = subprocess.run(\n cmd,\n capture_output=True,\n text=True,\n check=False,\n )\n if result.returncode != 0:\n logger.warning(\n \"imsg send failed: returncode=%s stderr=%r\",\n result.returncode,\n (result.stderr or \"\").strip() or None,\n )\n result.check_returncode()\n\n def _emit_request_threadsafe(self, request: Any) -> None:\n \"\"\"Enqueue request via manager (thread-safe).\"\"\"\n if self._enqueue is not None:\n self._enqueue(request)\n\n def _watcher_loop(self) -> None:\n logger.info(\n \"watcher thread started (poll=%.2fs, db=%s)\",\n self.poll_sec,\n self.db_path,\n )\n\n conn = sqlite3.connect(f\"file:{self.db_path}?mode=ro\", uri=True)\n conn.row_factory = sqlite3.Row\n last_rowid = conn.execute(\n \"SELECT IFNULL(MAX(ROWID),0) FROM message\",\n ).fetchone()[0]\n\n try:\n while not self._stop_event.is_set():\n try:\n rows = conn.execute(\n \"\"\"\nSELECT m.ROWID, m.text, m.is_from_me, c.ROWID as chat_rowid, h.id as sender\nFROM message m\nJOIN chat_message_join cmj ON cmj.message_id = m.ROWID\nJOIN chat c ON c.ROWID = cmj.chat_id\nLEFT JOIN handle h ON h.ROWID = m.handle_id\nWHERE m.ROWID > ?\nORDER BY m.ROWID ASC\n\"\"\",\n (last_rowid,),\n ).fetchall()\n\n for r in rows:\n last_rowid = r[\"ROWID\"]\n if r[\"is_from_me\"] == 1:\n continue\n text = r[\"text\"]\n if not text or str(text).startswith(self.bot_prefix):\n continue\n sender = (r[\"sender\"] or \"\").strip()\n if not sender:\n continue\n\n content_parts = [\n TextContent(\n type=ContentType.TEXT,\n text=str(text) if text else \"\",\n ),\n ]\n meta = {\n \"chat_rowid\": str(r[\"chat_rowid\"]),\n \"rowid\": int(r[\"ROWID\"]),\n }\n native = {\n \"channel_id\": self.channel,\n \"sender_id\": sender,\n \"content_parts\": content_parts,\n \"meta\": meta,\n }\n request = self.build_agent_request_from_native(native)\n request.channel_meta = meta\n logger.info(\n \"recv from=%s rowid=%s text=%r\",\n sender,\n r[\"ROWID\"],\n text,\n )\n self._emit_request_threadsafe(request)\n\n except Exception:\n logger.exception(\"poll iteration failed\")\n\n time.sleep(self.poll_sec)\n finally:\n conn.close()\n logger.info(\"watcher thread stopped\")\n\n def build_agent_request_from_native(self, native_payload: Any) -> Any:\n \"\"\"Build AgentRequest from imessage native dict (runtime content).\"\"\"\n payload = native_payload if isinstance(native_payload, dict) else {}\n channel_id = payload.get(\"channel_id\") or self.channel\n sender_id = payload.get(\"sender_id\") or \"\"\n content_parts = payload.get(\"content_parts\") or []\n meta = payload.get(\"meta\") or {}\n session_id = self.resolve_session_id(sender_id, meta)\n request = self.build_agent_request_from_user_content(\n channel_id=channel_id,\n sender_id=sender_id,\n session_id=session_id,\n content_parts=content_parts,\n channel_meta=meta,\n )\n return request\n\n async def _on_consume_error(\n self,\n request: Any,\n to_handle: str,\n err_text: str,\n ) -> None:\n \"\"\"Send error via imessage _send_sync (sync API).\"\"\"\n await asyncio.to_thread(self._send_sync, to_handle, err_text)\n\n async def start(self) -> None:\n if not self.enabled:\n logger.debug(\"disabled by env IMESSAGE_ENABLED=0\")\n return\n\n self._imsg_path = self._ensure_imsg()\n logger.info(f\"IMessage channel started with binary: {self._imsg_path}\")\n\n self._stop_event.clear()\n self._thread = threading.Thread(target=self._watcher_loop, daemon=True)\n self._thread.start()\n\n async def stop(self) -> None:\n if not self.enabled:\n return\n\n self._stop_event.set()\n if self._thread:\n self._thread.join(timeout=5)\n\n async def send(\n self,\n to_handle: str,\n text: str,\n meta: Optional[Dict[str, Any]] = None,\n file_path: Optional[str] = None,\n ) -> None:\n if not self.enabled:\n return\n await asyncio.to_thread(self._send_sync, to_handle, text, file_path)\n\n async def send_content_parts(\n self,\n to_handle: str,\n parts: List[OutgoingContentPart],\n meta: Optional[Dict[str, Any]] = None,\n ) -> None:\n \"\"\"\n Send a list of content parts.\n For iMessage: send text and media as separate messages.\n \"\"\"\n if not parts:\n return\n\n text_parts: List[str] = []\n media_parts: List[OutgoingContentPart] = []\n\n for p in parts:\n t = getattr(p, \"type\", None)\n if t == ContentType.TEXT:\n text_val = getattr(p, \"text\", None)\n if text_val:\n text_parts.append(text_val)\n elif t == ContentType.REFUSAL:\n refusal_val = getattr(p, \"refusal\", None)\n if refusal_val:\n text_parts.append(refusal_val)\n elif t in (\n ContentType.IMAGE,\n ContentType.VIDEO,\n ContentType.AUDIO,\n ContentType.FILE,\n ):\n media_parts.append(p)\n\n body = (meta or {}).get(\"bot_prefix\", \"\") + \"\\n\".join(text_parts)\n\n # Send text message first (if any)\n if body.strip():\n preview = body[:120] + \"...\" if len(body) > 120 else body\n logger.debug(\n f\"imessage send_content_parts: to_handle={to_handle} \"\n f\"body_len={len(body)} preview={preview}\",\n )\n await self.send(to_handle, body.strip(), meta)\n\n # Send media parts\n for media_part in media_parts:\n try:\n await self.send_media(to_handle, media_part, meta)\n except Exception as exc:\n # Fallback: send a textual placeholder if media delivery fails\n logger.warning(\n \"imessage send_content_parts: \"\n \"send_media failed for %s: %s\",\n getattr(media_part, \"type\", None),\n exc,\n )\n # Try to extract a useful URL or identifier from the media part\n url_candidates = [\n getattr(media_part, \"url\", None),\n getattr(media_part, \"file_url\", None),\n getattr(media_part, \"image_url\", None),\n getattr(media_part, \"audio_url\", None),\n getattr(media_part, \"video_url\", None),\n ]\n fallback_url = next((u for u in url_candidates if u), None)\n if fallback_url:\n fallback_text = f\"[File: {fallback_url}]\"\n else:\n content_type = getattr(\n getattr(media_part, \"type\", None),\n \"value\",\n getattr(media_part, \"type\", None),\n )\n fallback_text = (\n f\"[File could not be sent ({content_type})]\"\n )\n await self.send(to_handle, fallback_text, meta)\n\n def _extract_url_and_filename(self, part: OutgoingContentPart):\n \"\"\"Extract URL and filename hint from media part based on\n content type.\"\"\"\n url = None\n filename_hint = \"media_file\"\n t = getattr(part, \"type\", None)\n\n if t == ContentType.IMAGE:\n url = getattr(part, \"image_url\", None)\n filename_hint = \"image\"\n elif t == ContentType.FILE:\n url = getattr(part, \"file_url\", None) or getattr(\n part,\n \"file_id\",\n None,\n )\n filename_hint = getattr(part, \"filename\", \"file\")\n elif t == ContentType.VIDEO:\n url = getattr(part, \"video_url\", None)\n filename_hint = \"video\"\n elif t == ContentType.AUDIO:\n url = getattr(part, \"audio_url\", None) or getattr(\n part,\n \"data\",\n None,\n )\n filename_hint = \"audio\"\n\n return url, filename_hint, t\n\n def _get_file_extension(\n self,\n content_type: Any,\n filename_hint: str,\n ) -> str:\n \"\"\"Get appropriate file extension based on content type.\"\"\"\n # Sanitize filename_hint first to prevent path\n # traversal in extension extraction\n sanitized_hint = self._sanitize_filename(filename_hint)\n if \".\" in sanitized_hint:\n return Path(sanitized_hint).suffix\n elif content_type == ContentType.IMAGE:\n return \".jpg\"\n elif content_type == ContentType.AUDIO:\n return \".mp3\"\n elif content_type == ContentType.VIDEO:\n return \".mp4\"\n else:\n return \".bin\"\n\n def _sanitize_filename(self, filename: str) -> str:\n \"\"\"\n Sanitize filename to prevent path traversal attacks.\n - Extract basename only (remove any path components)\n - Allow only alphanumeric characters, underscores, hyphens, and dots\n - Replace invalid characters with underscores\n - Ensure the result is not empty\n \"\"\"\n # Extract basename to remove any path separators\n basename = Path(filename).name\n\n # If basename is empty (e.g., filename was just a path\n # separator), use default\n if not basename:\n return \"media_file\"\n\n # Allow only safe characters: alphanumeric, underscore, hyphen, dot\n import re\n\n sanitized = re.sub(r\"[^a-zA-Z0-9._-]\", \"_\", basename)\n\n # Ensure it doesn't start or end with dots or hyphens\n # (which could be problematic)\n sanitized = sanitized.strip(\"._-\")\n\n # If after sanitization it's empty, use default\n if not sanitized:\n return \"media_file\"\n\n return sanitized\n\n async def _handle_local_file(self, url: str) -> Optional[str]:\n \"\"\"Handle local file paths.\"\"\"\n local_path = file_url_to_local_path(url)\n if local_path and Path(local_path).exists():\n logger.info(f\"imessage send_media: using local file {local_path}\")\n return local_path\n\n path_obj = Path(url).expanduser()\n if path_obj.exists():\n local_path = str(path_obj.resolve())\n logger.info(\n f\"imessage send_media: using plain file path {local_path}\",\n )\n return local_path\n\n logger.warning(f\"imessage send_media: file not found {url}\")\n return None\n\n async def _handle_remote_url(\n self,\n url: str,\n filename_hint: str,\n content_type: Any,\n ) -> Optional[str]:\n \"\"\"Handle remote HTTP/HTTPS URLs.\"\"\"\n try:\n url_hash = hashlib.md5(url.encode()).hexdigest()[:16]\n ext = self._get_file_extension(content_type, filename_hint)\n safe_basename = self._sanitize_filename(filename_hint)\n safe_filename = f\"{safe_basename}_{url_hash}{ext}\"\n local_path = await download_file_from_url(\n url,\n filename=safe_filename,\n download_dir=str(self._media_dir),\n )\n logger.info(\n f\"imessage send_media: downloaded {url} to {local_path}\",\n )\n return local_path\n except Exception as e:\n logger.error(f\"imessage send_media: failed to download {url}: {e}\")\n return None\n\n async def _handle_data_url(\n self,\n url: str,\n content_type: Any,\n filename_hint: str,\n ) -> Optional[str]:\n \"\"\"Handle base64 data URLs.\"\"\"\n try:\n if \"base64,\" in url:\n b64_data = url.split(\"base64,\", 1)[-1]\n if content_type == ContentType.IMAGE:\n ext = \".png\" if \"image/png\" in url else \".jpg\"\n elif content_type == ContentType.AUDIO:\n ext = \".mp3\"\n elif content_type == ContentType.VIDEO:\n ext = \".mp4\"\n else:\n ext = \".bin\"\n\n # Add validation and size limits for base64 data\n MAX_DECODED_SIZE = self.max_decoded_size\n\n # Validate base64 format and get decoded size\n # without full decode\n try:\n # Get approximate decoded size: (n*3)/4 where n\n # is length of base64 string\n b64_length = len(b64_data)\n # Remove padding for calculation\n padding = b64_data.count(\"=\", -2)\n approx_decoded_size = (b64_length * 3) // 4 - padding\n\n if approx_decoded_size > MAX_DECODED_SIZE:\n logger.warning(\n \"imessage send_media: base64 data too large \"\n f\"({approx_decoded_size} bytes > \"\n f\"{MAX_DECODED_SIZE} bytes limit)\",\n )\n return None\n\n # Validate and decode with proper error handling\n file_data = base64.b64decode(b64_data, validate=True)\n\n if len(file_data) > MAX_DECODED_SIZE:\n logger.warning(\n \"imessage send_media: decoded data too large \"\n f\"({len(file_data)} bytes > {MAX_DECODED_SIZE} \"\n \"bytes limit)\",\n )\n return None\n\n except Exception as e:\n logger.error(\n f\"imessage send_media: invalid base64 data: {e}\",\n )\n return None\n\n url_hash = hashlib.md5(b64_data.encode()).hexdigest()[:16]\n safe_basename = self._sanitize_filename(filename_hint)\n safe_filename = f\"{safe_basename}_{url_hash}{ext}\"\n local_path = str(self._media_dir / safe_filename)\n\n Path(local_path).write_bytes(file_data)\n logger.info(\n f\"imessage send_media: saved base64 data to {local_path}\",\n )\n return local_path\n else:\n logger.warning(\n \"imessage send_media: unsupported data URL \"\n f\"format: {url[:50]}...\",\n )\n return None\n except Exception as e:\n logger.error(\n f\"imessage send_media: failed to process base64 data: {e}\",\n )\n return None\n\n async def send_media(\n self,\n to_handle: str,\n part: OutgoingContentPart,\n meta: Optional[Dict[str, Any]] = None,\n ) -> None:\n \"\"\"\n Send a single media part (image, video, audio, file).\n Downloads remote URLs to local files first, then sends via imsg.\n \"\"\"\n if not self.enabled:\n return\n\n # Extract URL or data from the media part\n url, filename_hint, content_type = self._extract_url_and_filename(part)\n\n if not url:\n logger.warning(\n \"imessage send_media: no URL found for media \"\n f\"type {content_type}\",\n )\n return\n\n # Handle different URL types\n local_path = None\n\n if isinstance(url, str):\n if url.startswith((\"http://\", \"https://\")):\n local_path = await self._handle_remote_url(\n url,\n filename_hint,\n content_type,\n )\n elif url.startswith(\"data:\"):\n local_path = await self._handle_data_url(\n url,\n content_type,\n filename_hint,\n )\n else:\n local_path = await self._handle_local_file(url)\n\n if local_path and Path(local_path).exists():\n logger.info(f\"imessage sending media file: {local_path}\")\n await self.send(to_handle, \"\", meta, local_path)\n else:\n logger.warning(\n \"imessage send_media: could not resolve valid file \"\n f\"path for {url}\",\n )\n" }, { "path": "src/copaw/app/channels/manager.py", "content": "# -*- coding: utf-8 -*-\n# pylint: disable=protected-access\n# ChannelManager is the framework owner of BaseChannel and must call\n# _is_native_payload and _consume_one_request as part of the contract.\n\nfrom __future__ import annotations\n\nimport asyncio\nimport logging\nfrom pathlib import Path\n\nfrom typing import (\n Callable,\n List,\n Optional,\n Any,\n Dict,\n Set,\n Tuple,\n TYPE_CHECKING,\n)\n\nfrom .base import BaseChannel, ContentType, ProcessHandler, TextContent\nfrom .registry import get_channel_registry\nfrom ...config import get_available_channels\n\nif TYPE_CHECKING:\n from ....config.config import Config\n\nlogger = logging.getLogger(__name__)\n\n# Callback when user reply was sent: (channel, user_id, session_id)\nOnLastDispatch = Optional[Callable[[str, str, str], None]]\n\n# Default max size per channel queue\n_CHANNEL_QUEUE_MAXSIZE = 1000\n\n# Workers per channel: drain same-session from queue and process in parallel\n_CONSUMER_WORKERS_PER_CHANNEL = 4\n\n\ndef _drain_same_key(\n q: asyncio.Queue,\n ch: BaseChannel,\n key: str,\n first_payload: Any,\n) -> List[Any]:\n \"\"\"Drain queue of payloads with same debounce key; return batch.\"\"\"\n batch = [first_payload]\n put_back: List[Any] = []\n while True:\n try:\n p = q.get_nowait()\n except asyncio.QueueEmpty:\n break\n if ch.get_debounce_key(p) == key:\n batch.append(p)\n else:\n put_back.append(p)\n for p in put_back:\n q.put_nowait(p)\n return batch\n\n\nasync def _process_batch(ch: BaseChannel, batch: List[Any]) -> None:\n \"\"\"Merge if needed and process one payload (native or request).\"\"\"\n if ch.channel == \"dingtalk\" and batch and ch._is_native_payload(batch[0]):\n first = batch[0] if isinstance(batch[0], dict) else {}\n logger.info(\n \"manager _process_batch dingtalk: batch_len=%s first_has_sw=%s\",\n len(batch),\n bool(first.get(\"session_webhook\")),\n )\n if len(batch) > 1 and ch._is_native_payload(batch[0]):\n merged = ch.merge_native_items(batch)\n if ch.channel == \"dingtalk\" and isinstance(merged, dict):\n logger.info(\n \"manager _process_batch dingtalk merged: has_sw=%s\",\n bool(merged.get(\"session_webhook\")),\n )\n await ch._consume_one_request(merged)\n elif len(batch) > 1:\n merged = ch.merge_requests(batch)\n if merged is not None:\n await ch._consume_one_request(merged)\n else:\n await ch.consume_one(batch[0])\n elif ch._is_native_payload(batch[0]):\n await ch._consume_one_request(batch[0])\n else:\n await ch.consume_one(batch[0])\n\n\ndef _put_pending_merged(\n ch: BaseChannel,\n q: asyncio.Queue,\n pending: List[Any],\n) -> None:\n \"\"\"Merge pending items if multiple and put one or more on queue.\"\"\"\n if not pending:\n return\n merged = None\n if len(pending) > 1 and ch._is_native_payload(pending[0]):\n merged = ch.merge_native_items(pending)\n elif len(pending) > 1:\n merged = ch.merge_requests(pending)\n if merged is not None:\n q.put_nowait(merged)\n else:\n for p in pending:\n q.put_nowait(p)\n\n\nclass ChannelManager:\n \"\"\"Owns queues and consumer loops; channels define how to consume via\n consume_one(). Enqueue via enqueue(channel_id, payload) (thread-safe).\n \"\"\"\n\n def __init__(self, channels: List[BaseChannel]):\n self.channels = channels\n self._lock = asyncio.Lock()\n self._queues: Dict[str, asyncio.Queue] = {}\n self._consumer_tasks: List[asyncio.Task[None]] = []\n self._loop: Optional[asyncio.AbstractEventLoop] = None\n # Session in progress: (channel_id, debounce_key) -> True while worker\n # is processing. New payloads for that key go to _pending, merged\n # when worker finishes.\n self._in_progress: Set[Tuple[str, str]] = set()\n self._pending: Dict[Tuple[str, str], List[Any]] = {}\n # Per-key lock: same session is claimed by one worker for drain so\n # [image1, text] are not split across workers (avoids no-text\n # debounce reordering and duplicate content in AgentRequest).\n self._key_locks: Dict[Tuple[str, str], asyncio.Lock] = {}\n\n @classmethod\n def from_env(\n cls,\n process: ProcessHandler,\n on_last_dispatch: OnLastDispatch = None,\n ) -> \"ChannelManager\":\n \"\"\"\n Create channels from env and inject unified process\n (AgentRequest -> Event stream).\n process is typically runner.stream_query, handled by AgentApp's\n process endpoint.\n on_last_dispatch: called when a user send+reply was sent.\n \"\"\"\n available = get_available_channels()\n registry = get_channel_registry()\n channels: list[BaseChannel] = [\n ch_cls.from_env(process, on_reply_sent=on_last_dispatch)\n for key, ch_cls in registry.items()\n if key in available\n ]\n return cls(channels)\n\n @classmethod\n def from_config(\n cls,\n process: ProcessHandler,\n config: \"Config\",\n on_last_dispatch: OnLastDispatch = None,\n workspace_dir: Path | None = None,\n ) -> \"ChannelManager\":\n \"\"\"Create channels from config (config.json or agent.json).\n\n Args:\n process: Process handler for agent communication\n config: Configuration object with channels\n on_last_dispatch: Callback for dispatch events\n workspace_dir: Agent workspace directory for channel state files\n \"\"\"\n available = get_available_channels()\n ch = config.channels\n show_tool_details = getattr(config, \"show_tool_details\", True)\n extra = getattr(ch, \"__pydantic_extra__\", None) or {}\n\n channels: list[BaseChannel] = []\n for key, ch_cls in get_channel_registry().items():\n if key not in available:\n continue\n ch_cfg = getattr(ch, key, None)\n if ch_cfg is None and key in extra:\n ch_cfg = extra[key]\n if ch_cfg is None:\n continue\n if isinstance(ch_cfg, dict):\n from types import SimpleNamespace\n from ...config.config import BaseChannelConfig\n\n defaults = BaseChannelConfig().model_dump()\n defaults.update(ch_cfg)\n ch_cfg = SimpleNamespace(**defaults)\n\n # Check if channel is enabled\n enabled = getattr(ch_cfg, \"enabled\", False)\n if not enabled:\n continue\n\n filter_tool_messages = getattr(\n ch_cfg,\n \"filter_tool_messages\",\n False,\n )\n filter_thinking = getattr(\n ch_cfg,\n \"filter_thinking\",\n False,\n )\n\n from_config_kwargs = {\n \"process\": process,\n \"config\": ch_cfg,\n \"on_reply_sent\": on_last_dispatch,\n \"show_tool_details\": show_tool_details,\n \"filter_tool_messages\": filter_tool_messages,\n \"filter_thinking\": filter_thinking,\n \"workspace_dir\": workspace_dir,\n }\n\n # Only pass kwargs that the channel's from_config accepts\n import inspect\n\n sig = inspect.signature(ch_cls.from_config)\n if any(\n p.kind == inspect.Parameter.VAR_KEYWORD\n for p in sig.parameters.values()\n ):\n filtered_kwargs = from_config_kwargs\n else:\n filtered_kwargs = {\n k: v\n for k, v in from_config_kwargs.items()\n if k in sig.parameters\n }\n\n try:\n channels.append(ch_cls.from_config(**filtered_kwargs))\n except Exception as e:\n logger.warning(\n \"Failed to initialize channel '%s', skipping: %s\",\n key,\n e,\n )\n continue\n\n return cls(channels)\n\n def _make_enqueue_cb(self, channel_id: str) -> Callable[[Any], None]:\n \"\"\"Return a callback that enqueues payload for the given channel.\"\"\"\n\n def cb(payload: Any) -> None:\n self.enqueue(channel_id, payload)\n\n return cb\n\n def _enqueue_one(self, channel_id: str, payload: Any) -> None:\n \"\"\"Run on event loop: enqueue or append to pending if session in\n progress.\n \"\"\"\n q = self._queues.get(channel_id)\n if not q:\n logger.debug(\"enqueue: no queue for channel=%s\", channel_id)\n return\n ch = next(\n (c for c in self.channels if c.channel == channel_id),\n None,\n )\n if not ch:\n q.put_nowait(payload)\n return\n key = ch.get_debounce_key(payload)\n if channel_id == \"dingtalk\" and isinstance(payload, dict):\n logger.info(\n \"manager _enqueue_one dingtalk: key=%s in_progress=%s \"\n \"payload_has_sw=%s -> %s\",\n key,\n (channel_id, key) in self._in_progress,\n bool(payload.get(\"session_webhook\")),\n \"pending\"\n if (channel_id, key) in self._in_progress\n else \"queue\",\n )\n if (channel_id, key) in self._in_progress:\n self._pending.setdefault((channel_id, key), []).append(payload)\n return\n q.put_nowait(payload)\n\n def enqueue(self, channel_id: str, payload: Any) -> None:\n \"\"\"Enqueue a payload for the channel. Thread-safe (e.g. from sync\n WebSocket or polling thread). If this session is already being\n processed, payload is held in pending and merged when the worker\n finishes. Call after start_all().\n \"\"\"\n if not self._queues.get(channel_id):\n logger.debug(\"enqueue: no queue for channel=%s\", channel_id)\n return\n if self._loop is None:\n logger.warning(\"enqueue: loop not set for channel=%s\", channel_id)\n return\n self._loop.call_soon_threadsafe(\n self._enqueue_one,\n channel_id,\n payload,\n )\n\n async def _consume_channel_loop(\n self,\n channel_id: str,\n worker_index: int,\n ) -> None:\n \"\"\"\n Run one consumer worker: pop payload, drain queue of same session,\n mark session in progress, merge batch (native or requests), process\n once, then flush any pending for this session (merged) back to queue.\n Multiple workers per channel allow different sessions in parallel.\n \"\"\"\n q = self._queues.get(channel_id)\n if not q:\n return\n while True:\n try:\n payload = await q.get()\n ch = await self.get_channel(channel_id)\n if not ch:\n continue\n key = ch.get_debounce_key(payload)\n key_lock = self._key_locks.setdefault(\n (channel_id, key),\n asyncio.Lock(),\n )\n async with key_lock:\n self._in_progress.add((channel_id, key))\n batch = _drain_same_key(q, ch, key, payload)\n try:\n await _process_batch(ch, batch)\n finally:\n self._in_progress.discard((channel_id, key))\n pending = self._pending.pop((channel_id, key), [])\n _put_pending_merged(ch, q, pending)\n except asyncio.CancelledError:\n break\n except Exception:\n logger.exception(\n \"channel consume_one failed: channel=%s worker=%s\",\n channel_id,\n worker_index,\n )\n\n async def start_all(self) -> None:\n self._loop = asyncio.get_running_loop()\n async with self._lock:\n snapshot = list(self.channels)\n for ch in snapshot:\n if getattr(ch, \"uses_manager_queue\", True):\n self._queues[ch.channel] = asyncio.Queue(\n maxsize=_CHANNEL_QUEUE_MAXSIZE,\n )\n ch.set_enqueue(self._make_enqueue_cb(ch.channel))\n for ch in snapshot:\n if ch.channel in self._queues:\n for w in range(_CONSUMER_WORKERS_PER_CHANNEL):\n task = asyncio.create_task(\n self._consume_channel_loop(ch.channel, w),\n name=f\"channel_consumer_{ch.channel}_{w}\",\n )\n self._consumer_tasks.append(task)\n logger.debug(\n \"starting channels=%s queues=%s\",\n [g.channel for g in snapshot],\n list(self._queues.keys()),\n )\n for g in snapshot:\n try:\n await g.start()\n except Exception:\n logger.exception(f\"failed to start channels={g.channel}\")\n\n async def stop_all(self) -> None:\n self._in_progress.clear()\n self._pending.clear()\n for task in self._consumer_tasks:\n task.cancel()\n if self._consumer_tasks:\n _, pending = await asyncio.wait(\n self._consumer_tasks,\n timeout=5.0,\n return_when=asyncio.ALL_COMPLETED,\n )\n if pending:\n logger.warning(\n \"stop_all: %s consumer task(s) still pending after 5s\",\n len(pending),\n )\n self._consumer_tasks.clear()\n self._queues.clear()\n async with self._lock:\n snapshot = list(self.channels)\n for ch in snapshot:\n ch.set_enqueue(None)\n\n async def _stop(ch):\n try:\n await ch.stop()\n except asyncio.CancelledError:\n pass\n except Exception:\n logger.exception(f\"failed to stop channels={ch.channel}\")\n\n await asyncio.gather(*[_stop(g) for g in reversed(snapshot)])\n\n async def get_channel(self, channel: str) -> Optional[BaseChannel]:\n async with self._lock:\n for ch in self.channels:\n if ch.channel == channel:\n return ch\n return None\n\n async def replace_channel(\n self,\n new_channel: BaseChannel,\n ) -> None:\n \"\"\"Replace a single channel by name.\n\n Flow: ensure queue+enqueue for new channel → start new (outside lock)\n → swap + stop old (inside lock). Lock only guards the swap+stop.\n\n Args:\n new_channel: New channel instance to replace with\n \"\"\"\n new_channel_name = new_channel.channel\n # 1) Ensure queue and enqueue callback before start() so the channel\n # (e.g. DingTalk) registers its handler with a valid callback.\n if new_channel_name not in self._queues:\n if getattr(new_channel, \"uses_manager_queue\", True):\n self._queues[new_channel_name] = asyncio.Queue(\n maxsize=_CHANNEL_QUEUE_MAXSIZE,\n )\n for w in range(_CONSUMER_WORKERS_PER_CHANNEL):\n task = asyncio.create_task(\n self._consume_channel_loop(new_channel_name, w),\n name=f\"channel_consumer_{new_channel_name}_{w}\",\n )\n self._consumer_tasks.append(task)\n new_channel.set_enqueue(self._make_enqueue_cb(new_channel_name))\n\n # 2) Start new channel outside lock (may be slow, e.g. DingTalk stream)\n logger.info(f\"Pre-starting new channel: {new_channel_name}\")\n try:\n await new_channel.start()\n except Exception:\n logger.exception(\n f\"Failed to start new channel: {new_channel_name}\",\n )\n try:\n await new_channel.stop()\n except Exception:\n pass\n raise\n\n # 3) Swap + stop old inside lock\n async with self._lock:\n old_channel = None\n for i, ch in enumerate(self.channels):\n if ch.channel == new_channel_name:\n old_channel = ch\n self.channels[i] = new_channel\n break\n\n if old_channel is None:\n logger.info(f\"Adding new channel: {new_channel_name}\")\n self.channels.append(new_channel)\n else:\n logger.info(f\"Stopping old channel: {old_channel.channel}\")\n try:\n await old_channel.stop()\n except asyncio.CancelledError:\n pass\n except Exception:\n logger.exception(\n f\"Failed to stop old channel: {old_channel.channel}\",\n )\n\n async def send_event(\n self,\n *,\n channel: str,\n user_id: str,\n session_id: str,\n event: Any,\n meta: Optional[Dict[str, Any]] = None,\n ) -> None:\n ch = await self.get_channel(channel)\n if not ch:\n raise KeyError(f\"channel not found: {channel}\")\n merged_meta = dict(meta or {})\n merged_meta[\"session_id\"] = session_id\n merged_meta[\"user_id\"] = user_id\n bot_prefix = getattr(ch, \"bot_prefix\", None) or getattr(\n ch,\n \"_bot_prefix\",\n None,\n )\n if bot_prefix and \"bot_prefix\" not in merged_meta:\n merged_meta[\"bot_prefix\"] = bot_prefix\n await ch.send_event(\n user_id=user_id,\n session_id=session_id,\n event=event,\n meta=merged_meta,\n )\n\n async def send_text(\n self,\n *,\n channel: str,\n user_id: str,\n session_id: str,\n text: str,\n meta: Optional[Dict[str, Any]] = None,\n ) -> None:\n \"\"\"Send plain text to a specific channel\n (used for scheduled jobs like task_type='text').\n \"\"\"\n ch = await self.get_channel(channel.lower())\n if not ch:\n raise KeyError(f\"channel not found: {channel}\")\n\n # Convert (user_id, session_id) into the channel-specific target handle\n to_handle = ch.to_handle_from_target(\n user_id=user_id,\n session_id=session_id,\n )\n ch_name = getattr(ch, \"channel\", channel)\n logger.info(\n \"channel send_text: channel=%s user_id=%s session_id=%s \"\n \"to_handle=%s\",\n ch_name,\n (user_id or \"\")[:40],\n (session_id or \"\")[:40],\n (to_handle or \"\")[:60],\n )\n\n # Keep the same behavior as the agent pipeline:\n # if the channel has a fixed bot prefix, merge it into meta so\n # send_content_parts can use it.\n merged_meta = dict(meta or {})\n bot_prefix = getattr(ch, \"bot_prefix\", None) or getattr(\n ch,\n \"_bot_prefix\",\n None,\n )\n if bot_prefix and \"bot_prefix\" not in merged_meta:\n merged_meta[\"bot_prefix\"] = bot_prefix\n merged_meta[\"session_id\"] = session_id\n merged_meta[\"user_id\"] = user_id\n\n # Send as content parts (single text part; use TextContent so channel\n # getattr(p, \"type\") / getattr(p, \"text\") work)\n await ch.send_content_parts(\n to_handle,\n [TextContent(type=ContentType.TEXT, text=text)],\n merged_meta,\n )\n" }, { "path": "src/copaw/app/channels/matrix/__init__.py", "content": "# -*- coding: utf-8 -*-\nfrom .channel import MatrixChannel\n\n__all__ = [\"MatrixChannel\"]\n" }, { "path": "src/copaw/app/channels/matrix/channel.py", "content": "# -*- coding: utf-8 -*-\n\"\"\"Matrix channel implementation using matrix-nio.\"\"\"\n\nimport asyncio\nimport logging\nimport mimetypes\nimport tempfile\nfrom pathlib import Path\nfrom typing import Any, Dict, List, Optional\nfrom urllib.parse import urlparse\n\nimport aiohttp\nfrom agentscope_runtime.engine.schemas.agent_schemas import (\n AgentRequest,\n AudioContent,\n ContentType,\n FileContent,\n ImageContent,\n TextContent,\n VideoContent,\n)\nfrom nio import (\n AsyncClient,\n MatrixRoom,\n RoomMessageAudio,\n RoomMessageFile,\n RoomMessageImage,\n RoomMessageText,\n RoomMessageVideo,\n RoomSendError,\n UploadError,\n)\n\nfrom ....config.config import MatrixConfig\nfrom ..base import (\n BaseChannel,\n OnReplySent,\n OutgoingContentPart,\n ProcessHandler,\n)\n\nlogger = logging.getLogger(__name__)\n\n\nclass MatrixChannel(BaseChannel):\n channel = \"matrix\"\n uses_manager_queue = True\n\n def __init__(\n self,\n process: ProcessHandler,\n enabled: bool,\n homeserver: str,\n user_id: str,\n access_token: str,\n on_reply_sent: OnReplySent = None,\n show_tool_details: bool = True,\n filter_tool_messages: bool = False,\n filter_thinking: bool = False,\n bot_prefix: str = \"\",\n dm_policy: str = \"open\",\n group_policy: str = \"open\",\n allow_from: Optional[list] = None,\n deny_message: str = \"\",\n require_mention: bool = False,\n **_kwargs: Any,\n ) -> None:\n super().__init__(\n process=process,\n on_reply_sent=on_reply_sent,\n show_tool_details=show_tool_details,\n filter_tool_messages=filter_tool_messages,\n filter_thinking=filter_thinking,\n dm_policy=dm_policy,\n group_policy=group_policy,\n allow_from=allow_from,\n deny_message=deny_message,\n require_mention=require_mention,\n )\n self.enabled = enabled\n self.homeserver = homeserver.rstrip(\"/\")\n self.user_id = user_id\n self.access_token = access_token\n self.bot_prefix = bot_prefix\n self.client: Optional[AsyncClient] = None\n self._sync_task: Optional[asyncio.Task] = None\n\n def _mxc_to_http(self, mxc_url: str) -> str:\n \"\"\"Convert mxc://server/media_id to an authenticated HTTP URL.\"\"\"\n if not mxc_url.startswith(\"mxc://\"):\n return mxc_url\n rest = mxc_url[len(\"mxc://\") :]\n parts = rest.split(\"/\", 1)\n if len(parts) != 2:\n return mxc_url\n server, media_id = parts\n return (\n f\"{self.homeserver}/_matrix/media/v3/download/\"\n f\"{server}/{media_id}\"\n f\"?access_token={self.access_token}\"\n )\n\n def _check_allowlist(\n self,\n sender_id: str,\n is_group: bool = False,\n ) -> tuple:\n policy = self.group_policy if is_group else self.dm_policy\n if policy == \"open\":\n return True, \"\"\n if self.allow_from and sender_id in self.allow_from:\n return True, \"\"\n return False, self.deny_message\n\n @classmethod\n def from_env(\n cls,\n process: ProcessHandler,\n on_reply_sent: OnReplySent = None,\n ) -> \"MatrixChannel\":\n raise NotImplementedError(\n \"Matrix channel must be configured via config file.\",\n )\n\n @classmethod\n def from_config(\n cls,\n process: ProcessHandler,\n config: MatrixConfig,\n on_reply_sent: OnReplySent = None,\n show_tool_details: bool = True,\n filter_tool_messages: bool = False,\n filter_thinking: bool = False,\n ) -> \"MatrixChannel\":\n return cls(\n process=process,\n enabled=config.enabled,\n homeserver=config.homeserver,\n user_id=config.user_id,\n access_token=config.access_token,\n on_reply_sent=on_reply_sent,\n show_tool_details=show_tool_details,\n filter_tool_messages=filter_tool_messages,\n filter_thinking=filter_thinking,\n bot_prefix=config.bot_prefix,\n dm_policy=config.dm_policy,\n group_policy=config.group_policy,\n allow_from=config.allow_from,\n deny_message=config.deny_message,\n require_mention=config.require_mention,\n )\n\n def build_agent_request_from_native(\n self,\n native_payload: Any,\n ) -> AgentRequest:\n room_id = native_payload[\"room_id\"]\n sender = native_payload[\"sender\"]\n content_parts = native_payload.get(\"content_parts\") or []\n\n if not content_parts:\n body = native_payload.get(\"body\", \"\")\n content_parts = [TextContent(type=ContentType.TEXT, text=body)]\n\n session_id = self.resolve_session_id(room_id)\n request = self.build_agent_request_from_user_content(\n channel_id=self.channel,\n sender_id=sender,\n session_id=session_id,\n content_parts=content_parts,\n channel_meta={\"room_id\": room_id},\n )\n return request\n\n def get_to_handle_from_request(self, request: AgentRequest) -> str:\n session_id = getattr(request, \"session_id\", \"\") or \"\"\n if session_id.startswith(\"matrix:\"):\n return session_id[len(\"matrix:\") :]\n meta = getattr(request, \"channel_meta\", {}) or {}\n return meta.get(\"room_id\", getattr(request, \"user_id\", \"\"))\n\n async def _handle_event(\n self,\n room: MatrixRoom,\n sender: str,\n content_parts: List[Any],\n bot_mentioned: bool = False,\n ) -> None:\n \"\"\"Apply access control and enqueue a payload.\"\"\"\n is_group = len(room.users) > 2\n meta = {\n \"room_id\": room.room_id,\n \"is_group\": is_group,\n \"bot_mentioned\": bot_mentioned,\n }\n\n allowed, deny_msg = self._check_allowlist(sender, is_group=is_group)\n if not allowed:\n if deny_msg:\n await self.send(room.room_id, deny_msg)\n return\n\n if not self._check_group_mention(is_group, meta):\n return\n\n payload = {\n \"room_id\": room.room_id,\n \"sender\": sender,\n \"content_parts\": content_parts,\n \"meta\": meta,\n }\n if self._enqueue:\n self._enqueue(payload)\n\n async def _message_callback(\n self,\n room: MatrixRoom,\n event: RoomMessageText,\n ) -> None:\n if event.sender == self.user_id:\n return\n\n logger.info(\n \"Matrix received text from %s in %s: %s\",\n event.sender,\n room.room_id,\n event.body,\n )\n\n # Detect @-mention for require_mention support\n localpart = self.user_id.split(\":\")[0].lstrip(\"@\")\n bot_mentioned = self.user_id in event.body or localpart in event.body\n\n content_parts = [TextContent(type=ContentType.TEXT, text=event.body)]\n await self._handle_event(\n room,\n event.sender,\n content_parts,\n bot_mentioned=bot_mentioned,\n )\n\n async def _media_callback(\n self,\n room: MatrixRoom,\n event: Any,\n ) -> None:\n if event.sender == self.user_id:\n return\n\n mxc_url = getattr(event, \"url\", \"\") or \"\"\n filename = getattr(event, \"body\", \"file\") or \"file\"\n http_url = self._mxc_to_http(mxc_url) if mxc_url else \"\"\n\n logger.info(\n \"Matrix received media from %s in %s: %s\",\n event.sender,\n room.room_id,\n filename,\n )\n\n content_parts: List[Any] = []\n if isinstance(event, RoomMessageImage):\n content_parts.append(\n ImageContent(type=ContentType.IMAGE, image_url=http_url),\n )\n elif isinstance(event, RoomMessageVideo):\n content_parts.append(\n VideoContent(type=ContentType.VIDEO, video_url=http_url),\n )\n elif isinstance(event, RoomMessageAudio):\n content_parts.append(\n AudioContent(type=ContentType.AUDIO, data=http_url),\n )\n else:\n content_parts.append(\n FileContent(type=ContentType.FILE, file_url=http_url),\n )\n\n await self._handle_event(room, event.sender, content_parts)\n\n async def send_content_parts(\n self,\n to_handle: str,\n parts: List[OutgoingContentPart],\n meta: Optional[Dict[str, Any]] = None,\n ) -> None:\n media_types = {\n ContentType.IMAGE,\n ContentType.VIDEO,\n ContentType.AUDIO,\n ContentType.FILE,\n }\n text_parts = [\n p\n for p in (parts or [])\n if getattr(p, \"type\", None) not in media_types\n ]\n media_parts = [\n p for p in (parts or []) if getattr(p, \"type\", None) in media_types\n ]\n if text_parts:\n await super().send_content_parts(to_handle, text_parts, meta)\n for m in media_parts:\n await self.send_media(to_handle, m, meta)\n\n async def send_media( # pylint: disable=too-many-branches\n self,\n to_handle: str,\n part: OutgoingContentPart,\n meta: Optional[Dict[str, Any]] = None,\n ) -> None:\n \"\"\"Upload a file to the homeserver and send it as a room message.\"\"\"\n if not self.client:\n logger.error(\"Matrix client not initialized, cannot send media\")\n return\n\n url = (\n getattr(part, \"image_url\", None)\n or getattr(part, \"video_url\", None)\n or getattr(part, \"data\", None)\n or getattr(part, \"file_url\", None)\n )\n if not url:\n return\n\n ctype = getattr(part, \"type\", None)\n if ctype == ContentType.IMAGE:\n msgtype = \"m.image\"\n elif ctype == ContentType.VIDEO:\n msgtype = \"m.video\"\n elif ctype == ContentType.AUDIO:\n msgtype = \"m.audio\"\n else:\n msgtype = \"m.file\"\n\n temp_path = None\n try:\n if url.startswith(\"file://\"):\n file_path = Path(url[7:])\n mime = (\n mimetypes.guess_type(str(file_path))[0]\n or \"application/octet-stream\"\n )\n filename = file_path.name\n data = file_path.read_bytes()\n elif url.startswith((\"http://\", \"https://\")):\n async with aiohttp.ClientSession() as session:\n async with session.get(url) as resp:\n if resp.status != 200:\n logger.warning(\n \"Matrix send_media: download failed\"\n \" status=%d url=%s\",\n resp.status,\n url[:80],\n )\n return\n data = await resp.read()\n mime = (\n resp.content_type\n or mimetypes.guess_type(\n urlparse(url).path,\n )[0]\n or \"application/octet-stream\"\n )\n parsed_path = urlparse(url).path\n filename = Path(parsed_path).name or \"file\"\n else:\n logger.warning(\n \"Matrix send_media: unsupported URL scheme: %s\",\n url[:40],\n )\n return\n\n suffix = Path(filename).suffix or (\n mimetypes.guess_extension(mime) or \"\"\n )\n with tempfile.NamedTemporaryFile(\n delete=False,\n suffix=suffix,\n ) as tmp:\n tmp.write(data)\n temp_path = tmp.name\n\n with open(temp_path, \"rb\") as f:\n upload_resp, _ = await self.client.upload(\n f,\n content_type=mime,\n filename=filename,\n filesize=len(data),\n )\n\n if isinstance(upload_resp, UploadError):\n logger.error(\"Matrix upload failed: %s\", upload_resp)\n return\n\n content = {\n \"msgtype\": msgtype,\n \"body\": filename,\n \"url\": upload_resp.content_uri,\n \"info\": {\"mimetype\": mime, \"size\": len(data)},\n }\n send_resp = await self.client.room_send(\n room_id=to_handle,\n message_type=\"m.room.message\",\n content=content,\n )\n if isinstance(send_resp, RoomSendError):\n logger.error(\n \"Matrix room_send media failed: %s\",\n send_resp,\n )\n\n except Exception as e: # pylint: disable=broad-except\n logger.error(\"Matrix send_media error: %s\", e, exc_info=True)\n finally:\n if temp_path:\n Path(temp_path).unlink(missing_ok=True)\n\n async def start(self) -> None:\n if (\n not self.enabled\n or not self.homeserver\n or not self.user_id\n or not self.access_token\n ):\n logger.info(\n \"Matrix channel not configured or disabled. Skipping start.\",\n )\n return\n\n self.client = AsyncClient(self.homeserver, self.user_id)\n self.client.access_token = self.access_token\n\n self.client.add_event_callback(\n self._message_callback,\n RoomMessageText,\n )\n self.client.add_event_callback(\n self._media_callback,\n RoomMessageImage,\n )\n self.client.add_event_callback(\n self._media_callback,\n RoomMessageVideo,\n )\n self.client.add_event_callback(\n self._media_callback,\n RoomMessageAudio,\n )\n self.client.add_event_callback(\n self._media_callback,\n RoomMessageFile,\n )\n\n logger.info(\n \"Starting Matrix client for %s on %s\",\n self.user_id,\n self.homeserver,\n )\n\n async def sync_loop() -> None:\n try:\n await self.client.sync_forever(\n timeout=30000,\n full_state=True,\n )\n except asyncio.CancelledError:\n pass\n except Exception as e: # pylint: disable=broad-except\n logger.error(\n \"Matrix sync loop error: %s\",\n e,\n exc_info=True,\n )\n\n self._sync_task = asyncio.create_task(sync_loop())\n\n async def stop(self) -> None:\n if self._sync_task:\n self._sync_task.cancel()\n if self.client:\n await self.client.close()\n logger.info(\"Matrix channel stopped.\")\n\n async def send(\n self,\n to_handle: str,\n text: str,\n meta: Optional[Dict[str, Any]] = None,\n ) -> None:\n if not self.client:\n logger.error(\"Matrix client not initialized, cannot send message\")\n return\n\n if not text:\n return\n\n logger.info(\n \"Matrix sending to room=%s text_len=%d\",\n to_handle,\n len(text),\n )\n resp = await self.client.room_send(\n room_id=to_handle,\n message_type=\"m.room.message\",\n content={\n \"msgtype\": \"m.text\",\n \"body\": text,\n },\n )\n if isinstance(resp, RoomSendError):\n logger.error(\"Matrix room_send failed: %s\", resp)\n" }, { "path": "src/copaw/app/channels/mattermost/__init__.py", "content": "# -*- coding: utf-8 -*-\nfrom .channel import MattermostChannel\n\n__all__ = [\"MattermostChannel\"]\n" }, { "path": "src/copaw/app/channels/mattermost/channel.py", "content": "# -*- coding: utf-8 -*-\n# pylint: disable=too-many-instance-attributes,too-many-arguments\n\"\"\"Mattermost channel: WebSocket event listener + REST API replies.\"\"\"\nfrom __future__ import annotations\n\nimport asyncio\nimport json\nimport logging\nimport re\nimport uuid\nfrom pathlib import Path\nfrom typing import Any, Optional, Union\n\nimport httpx\nfrom agentscope_runtime.engine.schemas.agent_schemas import (\n ContentType,\n FileContent,\n ImageContent,\n TextContent,\n)\n\nfrom ....config.config import MattermostConfig as MattermostChannelConfig\nfrom ....constant import WORKING_DIR\nfrom ..base import (\n BaseChannel,\n OnReplySent,\n OutgoingContentPart,\n ProcessHandler,\n)\n\nlogger = logging.getLogger(__name__)\n\nMATTERMOST_POST_CHUNK_SIZE = 4000 # chars per post (hard limit ~16383)\n\n_DEFAULT_MEDIA_DIR = WORKING_DIR / \"media\" / \"mattermost\"\n_TYPING_TIMEOUT_S = 180\n\n_IMAGE_SUFFIXES = {\".jpg\", \".jpeg\", \".png\", \".gif\", \".webp\", \".bmp\", \".tiff\"}\n_AUDIO_SUFFIXES = {\".mp3\", \".wav\", \".m4a\", \".aac\", \".ogg\", \".flac\"}\n_VIDEO_SUFFIXES = {\".mp4\", \".mov\", \".mkv\", \".webm\", \".avi\"}\n\n\nasync def _download_mattermost_file(\n *,\n http: httpx.AsyncClient,\n url: str,\n file_id: str,\n media_dir: Path,\n filename_hint: str = \"\",\n) -> Optional[str]:\n \"\"\"Stream-download a Mattermost file to local media_dir; return path.\"\"\"\n try:\n media_dir.mkdir(parents=True, exist_ok=True)\n suffix = Path(filename_hint).suffix if filename_hint else \"\"\n local_name = f\"{uuid.uuid4().hex[:12]}{suffix or '.bin'}\"\n local_path = media_dir / local_name\n async with http.stream(\"GET\", url) as resp:\n if resp.status_code != 200:\n logger.warning(\n \"mattermost: download %s returned %s\",\n file_id,\n resp.status_code,\n )\n return None\n with open(local_path, \"wb\") as fh:\n async for chunk in resp.aiter_bytes(65536):\n fh.write(chunk)\n return str(local_path)\n except Exception:\n logger.exception(\"mattermost: download failed for file_id=%s\", file_id)\n return None\n\n\nclass MattermostChannel(BaseChannel):\n \"\"\"Mattermost channel: WebSocket listener + REST API replies.\n\n Session model\n -------------\n - DM (channel_type == 'D') → session_id = mattermost_dm:{mm_channel_id}\n - Group/Channel (threaded) → session_id = mattermost_thread:{root_id}\n\n Native payload format\n ---------------------\n {\n \"channel_id\": \"mattermost\", # framework channel type key\n \"sender_id\": \"\",\n \"content_parts\": [...], # TextContent / ImageContent / …\n \"meta\": {\n \"mm_channel_id\": \"\",\n \"root_id\": \"\",\n \"channel_type\": \"D\" | \"O\" | \"P\" | …,\n \"post_id\": \"\",\n },\n }\n \"\"\"\n\n channel = \"mattermost\"\n uses_manager_queue = True\n\n def __init__(\n self,\n process: ProcessHandler,\n enabled: bool,\n url: str,\n bot_token: str,\n bot_prefix: str = \"\",\n media_dir: str = \"\",\n show_typing: Optional[bool] = None,\n thread_follow_without_mention: bool = False,\n on_reply_sent: OnReplySent = None,\n show_tool_details: bool = True,\n filter_tool_messages: bool = False,\n filter_thinking: bool = False,\n dm_policy: str = \"open\",\n group_policy: str = \"open\",\n allow_from: Optional[list] = None,\n deny_message: str = \"\",\n ):\n super().__init__(\n process,\n on_reply_sent=on_reply_sent,\n show_tool_details=show_tool_details,\n filter_tool_messages=filter_tool_messages,\n filter_thinking=filter_thinking,\n dm_policy=dm_policy,\n group_policy=group_policy,\n allow_from=allow_from,\n deny_message=deny_message,\n )\n self.enabled = enabled\n self.bot_prefix = bot_prefix\n self._url = url.rstrip(\"/\")\n self._bot_token = bot_token\n self._media_dir = (\n Path(media_dir).expanduser() if media_dir else _DEFAULT_MEDIA_DIR\n )\n self._show_typing = show_typing if show_typing is not None else True\n self._thread_follow = thread_follow_without_mention\n\n # Runtime state\n self._bot_id: str = \"\"\n self._bot_username: str = \"\"\n self._task: Optional[asyncio.Task] = None\n self._typing_tasks: dict[str, asyncio.Task] = {}\n self._participated_threads: set[str] = set()\n self._seen_sessions: set[str] = set()\n\n # Reuse a single HTTP client (BaseChannel._http field)\n # Only Authorization header — Content-Type is set per-request by httpx\n # (json= → application/json, files= → multipart/form-data)\n self._http = httpx.AsyncClient(\n headers={\"Authorization\": f\"Bearer {self._bot_token}\"},\n timeout=30.0,\n follow_redirects=True,\n )\n\n if self.enabled and not self._url:\n logger.warning(\"mattermost: enabled but url is empty — disabled\")\n self.enabled = False\n if self.enabled and not self._bot_token:\n logger.warning(\n \"mattermost: enabled but bot_token is empty — disabled\",\n )\n self.enabled = False\n\n # ------------------------------------------------------------------\n # Construction helpers\n # ------------------------------------------------------------------\n\n @classmethod\n def from_config(\n cls,\n process: ProcessHandler,\n config: Union[MattermostChannelConfig, dict],\n on_reply_sent: OnReplySent = None,\n show_tool_details: bool = True,\n filter_tool_messages: bool = False,\n filter_thinking: bool = False,\n ) -> \"MattermostChannel\":\n if isinstance(config, dict):\n c = config\n else:\n c = config.model_dump()\n\n def _s(key: str) -> str:\n return (c.get(key) or \"\").strip()\n\n return cls(\n process=process,\n enabled=bool(c.get(\"enabled\", False)),\n url=_s(\"url\"),\n bot_token=_s(\"bot_token\"),\n bot_prefix=_s(\"bot_prefix\"),\n media_dir=_s(\"media_dir\"),\n show_typing=c.get(\"show_typing\"),\n thread_follow_without_mention=bool(\n c.get(\"thread_follow_without_mention\", False),\n ),\n on_reply_sent=on_reply_sent,\n show_tool_details=show_tool_details,\n filter_tool_messages=filter_tool_messages,\n filter_thinking=filter_thinking,\n dm_policy=c.get(\"dm_policy\") or \"open\",\n group_policy=c.get(\"group_policy\") or \"open\",\n allow_from=c.get(\"allow_from\") or [],\n deny_message=c.get(\"deny_message\") or \"\",\n )\n\n @classmethod\n def from_env(\n cls,\n process: ProcessHandler,\n on_reply_sent: OnReplySent = None,\n ) -> \"MattermostChannel\":\n import os\n\n allow_from_env = os.getenv(\"MATTERMOST_ALLOW_FROM\", \"\")\n allow_from = (\n [s.strip() for s in allow_from_env.split(\",\") if s.strip()]\n if allow_from_env\n else []\n )\n return cls(\n process=process,\n enabled=os.getenv(\"MATTERMOST_CHANNEL_ENABLED\", \"0\") == \"1\",\n url=os.getenv(\"MATTERMOST_URL\", \"\"),\n bot_token=os.getenv(\"MATTERMOST_BOT_TOKEN\", \"\"),\n bot_prefix=os.getenv(\"MATTERMOST_BOT_PREFIX\", \"\"),\n media_dir=os.getenv(\"MATTERMOST_MEDIA_DIR\", \"\"),\n show_typing=os.getenv(\"MATTERMOST_SHOW_TYPING\", \"1\") == \"1\",\n thread_follow_without_mention=(\n os.getenv(\"MATTERMOST_THREAD_FOLLOW\", \"0\") == \"1\"\n ),\n on_reply_sent=on_reply_sent,\n dm_policy=os.getenv(\"MATTERMOST_DM_POLICY\", \"open\"),\n group_policy=os.getenv(\"MATTERMOST_GROUP_POLICY\", \"open\"),\n allow_from=allow_from,\n deny_message=os.getenv(\"MATTERMOST_DENY_MESSAGE\", \"\"),\n )\n\n # ------------------------------------------------------------------\n # Lifecycle\n # ------------------------------------------------------------------\n\n async def start(self) -> None:\n if not self.enabled:\n logger.debug(\"mattermost: start() skipped (enabled=false)\")\n return\n self._task = asyncio.create_task(\n self._run(),\n name=\"mattermost_websocket\",\n )\n logger.info(\"mattermost: channel started (websocket task created)\")\n\n async def stop(self) -> None:\n if not self.enabled:\n return\n for cid in list(self._typing_tasks):\n self._stop_typing(cid)\n if self._task:\n self._task.cancel()\n try:\n await asyncio.wait_for(self._task, timeout=10)\n except (asyncio.CancelledError, asyncio.TimeoutError, Exception):\n pass\n self._task = None\n try:\n await self._http.aclose()\n except Exception:\n pass\n\n # ------------------------------------------------------------------\n # WebSocket loop\n # ------------------------------------------------------------------\n\n async def _init_bot_info(self) -> bool:\n \"\"\"Fetch and cache bot_id / bot_username. Returns True on success.\"\"\"\n try:\n resp = await self._http.get(f\"{self._url}/api/v4/users/me\")\n if resp.status_code == 200:\n data = resp.json()\n self._bot_id = data.get(\"id\", \"\")\n self._bot_username = data.get(\"username\", \"\")\n logger.info(\n \"mattermost: bot ready — id=%s username=@%s\",\n self._bot_id,\n self._bot_username,\n )\n return True\n logger.error(\n \"mattermost: /users/me returned %s — check bot_token\",\n resp.status_code,\n )\n except Exception:\n logger.exception(\"mattermost: failed to fetch bot info\")\n return False\n\n async def _run(self) -> None:\n \"\"\"Top-level task: fetch bot info, then enter WS reconnect loop.\"\"\"\n if not await self._init_bot_info():\n logger.error(\"mattermost: cannot start — bot info fetch failed\")\n return\n await self._websocket_loop()\n\n async def _websocket_loop(self) -> None:\n \"\"\"WebSocket listener with exponential backoff reconnect.\"\"\"\n try:\n import websockets # type: ignore\n except ImportError:\n logger.error(\n \"mattermost: 'websockets' not installed. \"\n \"Run: uv pip install websockets\",\n )\n return\n\n ws_url = (\n self._url.replace(\"http://\", \"ws://\").replace(\"https://\", \"wss://\")\n + \"/api/v4/websocket\"\n )\n reconnect_delay = 1\n\n while True:\n seq = 1\n try:\n async with websockets.connect(\n ws_url,\n ping_interval=20,\n ping_timeout=20,\n ) as ws:\n auth_req = {\n \"seq\": seq,\n \"action\": \"authentication_challenge\",\n \"data\": {\"token\": self._bot_token},\n }\n await ws.send(json.dumps(auth_req))\n reconnect_delay = 1 # reset on successful connect\n logger.info(\n \"mattermost: websocket connected and authenticated\",\n )\n\n async for raw in ws:\n data = json.loads(raw)\n if data.get(\"event\") == \"posted\":\n asyncio.create_task(self._on_posted_event(data))\n\n except asyncio.CancelledError:\n logger.debug(\"mattermost: websocket loop cancelled\")\n return\n except Exception as exc:\n logger.warning(\n \"mattermost: websocket error: %s — retrying in %ds\",\n exc,\n reconnect_delay,\n )\n await asyncio.sleep(reconnect_delay)\n reconnect_delay = min(reconnect_delay * 2, 60)\n\n # ------------------------------------------------------------------\n # Message event helper\n # ------------------------------------------------------------------\n\n def _is_triggered(self, post: dict, channel_type: str) -> bool:\n \"\"\"Check if the bot should respond to this post.\"\"\"\n sender_id = post.get(\"user_id\", \"\")\n if sender_id == self._bot_id:\n return False\n\n message_text = post.get(\"message\", \"\")\n original_root_id = post.get(\"root_id\", \"\")\n\n is_dm = channel_type == \"D\"\n bot_mention = f\"@{self._bot_username}\"\n is_mentioned = bool(\n self._bot_username and bot_mention.lower() in message_text.lower(),\n )\n is_in_thread = bool(original_root_id)\n thread_followed = (\n self._thread_follow\n and is_in_thread\n and original_root_id in self._participated_threads\n )\n return is_dm or is_mentioned or thread_followed\n\n async def _get_context_prefix(\n self,\n session_id: str,\n mm_channel_id: str,\n original_root_id: str,\n post_id: str,\n is_dm: bool,\n ) -> str:\n \"\"\"Fetch history context if needed.\"\"\"\n if is_dm:\n if session_id not in self._seen_sessions:\n self._seen_sessions.add(session_id)\n logger.info(\n \"mattermost: first DM contact on %s — \"\n \"fetching channel history\",\n session_id,\n )\n return await self._fetch_channel_history(mm_channel_id)\n elif original_root_id:\n logger.info(\"mattermost: fetching thread gap for %s\", session_id)\n return await self._fetch_thread_history(\n original_root_id,\n triggering_post_id=post_id,\n )\n else:\n if session_id not in self._seen_sessions:\n self._seen_sessions.add(session_id)\n logger.info(\n \"mattermost: new thread on %s — \"\n \"fetching channel history as background\",\n session_id,\n )\n return await self._fetch_channel_history(\n mm_channel_id,\n per_page=10,\n )\n return \"\"\n\n async def _process_attachments(self, post: dict) -> list[Any]:\n \"\"\"Download and wrap attachments.\"\"\"\n parts = []\n file_ids: list[str] = post.get(\"file_ids\") or []\n # Build filename hints from post metadata when available\n metadata = post.get(\"metadata\") or {}\n file_infos: list[dict] = metadata.get(\"files\") or []\n hint_map: dict[str, str] = {\n fi.get(\"id\", \"\"): fi.get(\"name\", \"\")\n for fi in file_infos\n if fi.get(\"id\")\n }\n for fid in file_ids:\n local_path = await self._download_file(\n fid,\n filename_hint=hint_map.get(fid, \"\"),\n )\n if local_path:\n suffix = Path(local_path).suffix.lower()\n if suffix in _IMAGE_SUFFIXES:\n parts.append(\n ImageContent(\n type=ContentType.IMAGE,\n image_url=local_path,\n ),\n )\n else:\n parts.append(\n FileContent(\n type=ContentType.FILE,\n file_url=local_path,\n ),\n )\n return parts\n\n # ------------------------------------------------------------------\n # Message event handler\n # ------------------------------------------------------------------\n\n async def _on_posted_event(self, event_data: dict) -> None:\n \"\"\"Handle one 'posted' WebSocket event end-to-end.\"\"\"\n raw_post = event_data.get(\"data\", {}).get(\"post\", \"{}\")\n post: dict = json.loads(raw_post)\n channel_type: str = event_data.get(\"data\", {}).get(\"channel_type\", \"\")\n\n if not self._is_triggered(post, channel_type):\n return\n\n sender_id: str = post.get(\"user_id\", \"\")\n mm_channel_id: str = post.get(\"channel_id\", \"\")\n post_id: str = post.get(\"id\", \"\")\n message_text: str = post.get(\"message\", \"\")\n original_root_id: str = post.get(\"root_id\", \"\")\n is_dm = channel_type == \"D\"\n\n # ACL check\n allowed, error_msg = self._check_allowlist(sender_id, not is_dm)\n if not allowed:\n logger.info(\n \"mattermost allowlist blocked: sender=%s\",\n sender_id,\n )\n if error_msg:\n target_root = original_root_id or post_id\n await self._post_message(\n mm_channel_id,\n error_msg,\n target_root,\n )\n return\n\n # 3. Determine effective root_id and session_id\n #\n # DM: session always tied to the DM channel (unified memory).\n # root_id is preserved so replies land inside the thread when\n # the user triggered from within one; flat otherwise.\n #\n # Channel: each thread is its own session.\n # A flat @mention seeds a new thread (root_id = post_id).\n if is_dm:\n target_root_id = (\n original_root_id # \"\" for flat DM, non-empty for thread\n )\n session_id = f\"mattermost_dm:{mm_channel_id}\"\n else:\n target_root_id = original_root_id if original_root_id else post_id\n session_id = f\"mattermost_thread:{target_root_id}\"\n\n # 4. Start typing indicator loop\n if self._show_typing:\n self._start_typing(mm_channel_id, target_root_id)\n\n # 5. Clean @mention from text\n bot_mention = f\"@{self._bot_username}\"\n clean_text = re.sub(\n re.escape(bot_mention),\n \"\",\n message_text,\n flags=re.IGNORECASE,\n ).strip()\n\n # 6. Context fetching\n context_prefix = await self._get_context_prefix(\n session_id,\n mm_channel_id,\n original_root_id,\n post_id,\n is_dm,\n )\n\n # 7. Build content_parts\n content_parts: list[Any] = []\n\n if context_prefix:\n content_parts.append(\n TextContent(type=ContentType.TEXT, text=context_prefix),\n )\n if clean_text:\n content_parts.append(\n TextContent(type=ContentType.TEXT, text=clean_text),\n )\n\n # 8. Download and classify attachments\n content_parts.extend(await self._process_attachments(post))\n\n if not content_parts:\n content_parts.append(TextContent(type=ContentType.TEXT, text=\"\"))\n\n # 9. Enqueue native payload\n native = {\n \"channel_id\": self.channel, # \"mattermost\" — framework key\n \"sender_id\": sender_id,\n \"content_parts\": content_parts,\n \"meta\": {\n \"mm_channel_id\": mm_channel_id,\n \"root_id\": target_root_id,\n \"channel_type\": channel_type,\n \"post_id\": post_id,\n },\n }\n if self._enqueue is not None:\n self._enqueue(native)\n else:\n logger.warning(\"mattermost: _enqueue not set, message dropped\")\n self._stop_typing(mm_channel_id)\n return\n\n # 10. Record thread participation\n if target_root_id:\n self._participated_threads.add(target_root_id)\n\n # ------------------------------------------------------------------\n # ------------------------------------------------------------------\n\n def _start_typing(self, mm_channel_id: str, root_id: str = \"\") -> None:\n \"\"\"Start (or restart) the typing indicator loop for a channel.\"\"\"\n self._stop_typing(mm_channel_id)\n self._typing_tasks[mm_channel_id] = asyncio.create_task(\n self._typing_loop(mm_channel_id, root_id),\n )\n\n def _stop_typing(self, mm_channel_id: str) -> None:\n \"\"\"Cancel the typing indicator loop for a channel.\"\"\"\n task = self._typing_tasks.pop(mm_channel_id, None)\n if task and not task.done():\n task.cancel()\n\n async def _typing_loop(\n self,\n mm_channel_id: str,\n root_id: str = \"\",\n ) -> None:\n \"\"\"Send 'typing' status every 4 s until cancelled.\n\n Mattermost typing state expires in ~5 s so we refresh at 4 s.\n Safety timeout at _TYPING_TIMEOUT_S to avoid infinite loops.\n \"\"\"\n try:\n deadline = asyncio.get_event_loop().time() + _TYPING_TIMEOUT_S\n while True:\n try:\n await self._http.post(\n f\"{self._url}/api/v4/users/{self._bot_id}/typing\",\n json={\n \"channel_id\": mm_channel_id,\n \"parent_id\": root_id,\n },\n )\n except Exception:\n logger.debug(\"mattermost: typing indicator send failed\")\n await asyncio.sleep(4)\n if asyncio.get_event_loop().time() >= deadline:\n break\n except asyncio.CancelledError:\n pass\n finally:\n if self._typing_tasks.get(mm_channel_id) is asyncio.current_task():\n self._typing_tasks.pop(mm_channel_id, None)\n\n def _get_thread_target_order(\n self,\n order: list[str],\n posts: dict,\n last_bot_idx: int,\n ) -> tuple[list[str], str]:\n \"\"\"Helper to determine the slice of thread posts to show as context.\"\"\"\n if last_bot_idx >= 0:\n # Bot has replied before.\n # Walk backwards to find the start of the consecutive bot-reply seq\n bot_seq_start = last_bot_idx\n while bot_seq_start > 0:\n prev_pid = order[bot_seq_start - 1]\n if posts.get(prev_pid, {}).get(\"user_id\") != self._bot_id:\n break\n bot_seq_start -= 1\n\n # The user trigger that produced this bot reply sequence is\n # the post immediately before it.\n trigger_idx = bot_seq_start - 1\n\n # Gap = all NON-bot posts after the trigger (inclusive of\n # messages posted during bot processing AND after bot reply).\n if trigger_idx >= 0:\n gap = [\n pid\n for pid in order[trigger_idx + 1 :]\n if posts.get(pid, {}).get(\"user_id\") != self._bot_id\n ]\n else:\n # Bot reply sequence starts at the very beginning\n gap = [\n pid\n for pid in order\n if posts.get(pid, {}).get(\"user_id\") != self._bot_id\n ]\n return gap, \"[Thread context supplement (unprocessed by bot)]\"\n\n # Bot joining this thread for the first time: full history\n return order, \"[Thread history]\"\n\n # ------------------------------------------------------------------\n # History helpers (lazy context — first session contact only)\n # ------------------------------------------------------------------\n\n async def _fetch_thread_history(\n self,\n root_id: str,\n triggering_post_id: str = \"\",\n ) -> str:\n \"\"\"Pull thread posts and return a formatted context prefix.\n\n Smart fetch strategy:\n - If bot has never replied in this thread: return all posts\n (bot is joining the thread for the first time).\n - If bot has replied before: return only the \"unseen\" user\n messages — i.e. messages the bot hasn't processed yet.\n This includes messages posted *during* bot processing\n (which land chronologically before the bot reply) as well\n as messages posted after the bot reply.\n\n In all cases the triggering post itself is excluded (it is sent\n separately as the main user message).\n \"\"\"\n try:\n resp = await self._http.get(\n f\"{self._url}/api/v4/posts/{root_id}/thread\",\n )\n if resp.status_code != 200:\n return \"\"\n data = resp.json()\n order: list[str] = list(data.get(\"order\", []))\n posts: dict = data.get(\"posts\", {})\n\n # Sort by create_at to guarantee chronological order\n # (thread API order direction may differ across MM versions)\n order.sort(key=lambda pid: posts.get(pid, {}).get(\"create_at\", 0))\n\n # Exclude the triggering post (processed as main message)\n if triggering_post_id:\n order = [pid for pid in order if pid != triggering_post_id]\n\n # Find the last bot reply to determine the \"gap\" start\n last_bot_idx = -1\n for i, pid in enumerate(order):\n if posts.get(pid, {}).get(\"user_id\") == self._bot_id:\n last_bot_idx = i\n\n target_order, label = self._get_thread_target_order(\n order,\n posts,\n last_bot_idx,\n )\n\n lines = [label]\n for pid in target_order:\n p = posts.get(pid, {})\n role = \"Bot\" if p.get(\"user_id\") == self._bot_id else \"User\"\n msg = p.get(\"message\", \"\").strip()\n if msg:\n lines.append(f\"{role}: {msg}\")\n if len(lines) == 1:\n return \"\" # only label, no actual content\n lines.append(\n \"[The above is supplementary context, \"\n \"please answer based on existing memory]\",\n )\n return \"\\n\".join(lines)\n except Exception:\n logger.exception(\"mattermost: fetch thread history failed\")\n return \"\"\n\n async def _fetch_channel_history(\n self,\n mm_channel_id: str,\n per_page: int = 20,\n ) -> str:\n \"\"\"Pull recent DM posts and return a formatted prefix string.\"\"\"\n try:\n resp = await self._http.get(\n f\"{self._url}/api/v4/channels/{mm_channel_id}/posts\",\n params={\"per_page\": per_page},\n )\n if resp.status_code == 200:\n data = resp.json()\n order: list[str] = list(data.get(\"order\", []))\n posts: dict = data.get(\"posts\", {})\n order.reverse()\n lines = [f\"[Recent {per_page} DM context messages]\"]\n for pid in order:\n p = posts.get(pid, {})\n role = (\n \"Bot\" if p.get(\"user_id\") == self._bot_id else \"User\"\n )\n msg = p.get(\"message\", \"\").strip()\n if msg:\n lines.append(f\"{role}: {msg}\")\n lines.append(\n \"[History ended, please answer the following questions \"\n \"based on the above context]\",\n )\n return \"\\n\".join(lines)\n except Exception:\n logger.exception(\"mattermost: fetch channel history failed\")\n return \"\"\n\n # ------------------------------------------------------------------\n # File helpers\n # ------------------------------------------------------------------\n\n async def _download_file(\n self,\n file_id: str,\n filename_hint: str = \"\",\n ) -> Optional[str]:\n \"\"\"Download a Mattermost attachment; return local path or None.\"\"\"\n return await _download_mattermost_file(\n http=self._http,\n url=f\"{self._url}/api/v4/files/{file_id}\",\n file_id=file_id,\n media_dir=self._media_dir,\n filename_hint=filename_hint,\n )\n\n async def _upload_file(\n self,\n mm_channel_id: str,\n local_path: str,\n ) -> Optional[str]:\n \"\"\"Upload a local file; return Mattermost file_id or None.\n\n Uses multipart/form-data — httpx sets the Content-Type boundary\n automatically when 'files=' is passed, so we do NOT include\n Content-Type: application/json in this request.\n \"\"\"\n path = Path(local_path)\n if not path.exists():\n logger.warning(\n \"mattermost: upload — file not found: %s\",\n local_path,\n )\n return None\n try:\n with open(path, \"rb\") as fh:\n resp = await self._http.post(\n f\"{self._url}/api/v4/files\",\n params={\"channel_id\": mm_channel_id},\n files={\"files\": (path.name, fh)},\n # No json= here; httpx handles Content-Type automatically\n )\n if resp.status_code in (200, 201):\n file_infos = resp.json().get(\"file_infos\", [])\n if file_infos:\n return file_infos[0].get(\"id\")\n logger.warning(\n \"mattermost: file upload failed %s: %s\",\n resp.status_code,\n resp.text[:200],\n )\n except Exception:\n logger.exception(\"mattermost: upload failed for %s\", local_path)\n return None\n\n # ------------------------------------------------------------------\n # Internal post helper\n # ------------------------------------------------------------------\n\n async def _post_message(\n self,\n mm_channel_id: str,\n text: str,\n root_id: str = \"\",\n file_ids: Optional[list[str]] = None,\n ) -> bool:\n \"\"\"Call POST /api/v4/posts. Returns True on success.\"\"\"\n payload: dict[str, Any] = {\n \"channel_id\": mm_channel_id,\n \"message\": text,\n \"root_id\": root_id,\n }\n if file_ids:\n payload[\"file_ids\"] = file_ids\n try:\n resp = await self._http.post(\n f\"{self._url}/api/v4/posts\",\n json=payload,\n )\n if resp.status_code == 201:\n return True\n logger.error(\n \"mattermost: post failed %s: %s\",\n resp.status_code,\n resp.text[:300],\n )\n except Exception:\n logger.exception(\"mattermost: _post_message error\")\n return False\n\n # ------------------------------------------------------------------\n # Send interface\n # ------------------------------------------------------------------\n\n def _chunk_text(self, text: str) -> list[str]:\n \"\"\"Split text at boundaries under post size limit.\"\"\"\n if not text or len(text) <= MATTERMOST_POST_CHUNK_SIZE:\n return [text] if text else []\n chunks: list[str] = []\n rest = text\n while rest:\n if len(rest) <= MATTERMOST_POST_CHUNK_SIZE:\n chunks.append(rest)\n break\n chunk = rest[:MATTERMOST_POST_CHUNK_SIZE]\n last_nl = chunk.rfind(\"\\n\")\n if last_nl > MATTERMOST_POST_CHUNK_SIZE // 2:\n chunk = chunk[: last_nl + 1]\n else:\n last_space = chunk.rfind(\" \")\n if last_space > MATTERMOST_POST_CHUNK_SIZE // 2:\n chunk = chunk[: last_space + 1]\n chunks.append(chunk)\n rest = rest[len(chunk) :].lstrip(\"\\n \")\n return chunks\n\n async def send(\n self,\n to_handle: str,\n text: str,\n meta: Optional[dict] = None,\n ) -> None:\n \"\"\"Send text reply to Mattermost.\n\n to_handle = mm_channel_id (resolved by get_to_handle_from_request).\n root_id from meta guarantees the reply threads correctly.\n \"\"\"\n if not self.enabled:\n return\n meta = meta or {}\n mm_channel_id = meta.get(\"mm_channel_id\") or to_handle\n root_id: str = meta.get(\"root_id\") or \"\"\n if not mm_channel_id:\n logger.warning(\n \"mattermost send: no mm_channel_id in meta or to_handle\",\n )\n return\n self._stop_typing(mm_channel_id)\n for chunk in self._chunk_text(text):\n await self._post_message(mm_channel_id, chunk, root_id)\n\n async def send_media(\n self,\n to_handle: str,\n part: OutgoingContentPart,\n meta: Optional[dict] = None,\n ) -> None:\n \"\"\"Upload a local file and post it as a Mattermost attachment.\"\"\"\n if not self.enabled:\n return\n meta = meta or {}\n mm_channel_id = meta.get(\"mm_channel_id\") or to_handle\n root_id: str = meta.get(\"root_id\") or \"\"\n if not mm_channel_id:\n logger.warning(\"mattermost send_media: no mm_channel_id\")\n return\n self._stop_typing(mm_channel_id)\n\n part_type = getattr(part, \"type\", None)\n local_path: Optional[str] = None\n if part_type == ContentType.IMAGE:\n local_path = getattr(part, \"image_url\", None)\n elif part_type == ContentType.VIDEO:\n local_path = getattr(part, \"video_url\", None)\n elif part_type == ContentType.FILE:\n local_path = getattr(part, \"file_url\", None)\n elif part_type == ContentType.AUDIO:\n local_path = getattr(part, \"data\", None)\n\n if not local_path:\n return\n if local_path.startswith(\"file://\"):\n local_path = local_path[len(\"file://\") :]\n\n file_id = await self._upload_file(mm_channel_id, local_path)\n if file_id:\n await self._post_message(mm_channel_id, \"\", root_id, [file_id])\n else:\n # Fallback: send file path as plain text\n await self._post_message(\n mm_channel_id,\n f\"[Attachment: {local_path}]\",\n root_id,\n )\n\n # ------------------------------------------------------------------\n # BaseChannel interface\n # ------------------------------------------------------------------\n\n def resolve_session_id(\n self,\n sender_id: str,\n channel_meta: Optional[dict] = None,\n ) -> str:\n \"\"\"Map meta to session_id.\n\n DM → mattermost_dm:{mm_channel_id}\n Group/Thread → mattermost_thread:{root_id or post_id}\n \"\"\"\n meta = channel_meta or {}\n channel_type = meta.get(\"channel_type\", \"\")\n mm_channel_id = meta.get(\"mm_channel_id\", \"\")\n root_id = meta.get(\"root_id\", \"\")\n post_id = meta.get(\"post_id\", \"\")\n\n if channel_type == \"D\":\n return f\"mattermost_dm:{mm_channel_id}\"\n effective_root = root_id if root_id else post_id\n return f\"mattermost_thread:{effective_root}\"\n\n def build_agent_request_from_native(self, native_payload: Any) -> Any:\n \"\"\"Convert Mattermost native dict → AgentRequest.\"\"\"\n payload = native_payload if isinstance(native_payload, dict) else {}\n channel_id = payload.get(\"channel_id\") or self.channel\n sender_id = payload.get(\"sender_id\") or \"\"\n content_parts = payload.get(\"content_parts\") or []\n meta = payload.get(\"meta\") or {}\n session_id = self.resolve_session_id(sender_id, meta)\n request = self.build_agent_request_from_user_content(\n channel_id=channel_id,\n sender_id=sender_id,\n session_id=session_id,\n content_parts=content_parts,\n channel_meta=meta,\n )\n request.user_id = sender_id\n request.channel_meta = meta\n return request\n\n def get_to_handle_from_request(self, request: Any) -> str:\n \"\"\"Return mm_channel_id for the send() call.\"\"\"\n meta = getattr(request, \"channel_meta\", None) or {}\n mm_channel_id = meta.get(\"mm_channel_id\")\n if mm_channel_id:\n return str(mm_channel_id)\n # Fallback: extract from DM session_id\n sid = getattr(request, \"session_id\", \"\")\n if sid.startswith(\"mattermost_dm:\"):\n return sid.split(\":\", 1)[-1]\n return getattr(request, \"user_id\", \"\") or \"\"\n\n def to_handle_from_target(self, *, user_id: str, session_id: str) -> str:\n \"\"\"Cron/proactive dispatch: resolve send target from session_id.\"\"\"\n if session_id.startswith(\"mattermost_dm:\"):\n return session_id.split(\":\", 1)[-1]\n return user_id\n" }, { "path": "src/copaw/app/channels/mqtt/__init__.py", "content": "# -*- coding: utf-8 -*-\n\"\"\"MQTT channel package.\"\"\"\nfrom .channel import MQTTChannel\n\n__all__ = [\"MQTTChannel\"]\n" }, { "path": "src/copaw/app/channels/mqtt/channel.py", "content": "# -*- coding: utf-8 -*-\n\"\"\"MQTT Channel for IoT devices and robots\"\"\"\nfrom __future__ import annotations\n\nimport json\nimport logging\nimport threading\nfrom typing import Any, Optional, Union\n\nimport paho.mqtt.client as mqtt\nfrom paho.mqtt import MQTTException\n\nfrom agentscope_runtime.engine.schemas.agent_schemas import (\n TextContent,\n ContentType,\n)\n\nfrom ....config.config import MQTTConfig as MQTTChannelConfig\nfrom ..base import (\n BaseChannel,\n OnReplySent,\n ProcessHandler,\n OutgoingContentPart,\n)\n\nlogger = logging.getLogger(__name__)\n\n\nclass MQTTChannel(BaseChannel):\n \"\"\"MQTT Channel for IoT devices and robots\"\"\"\n\n channel = \"mqtt\"\n uses_manager_queue = True\n\n def __init__(\n self,\n process: ProcessHandler,\n enabled: bool,\n host: str,\n port: int,\n transport: str,\n username: str,\n password: str,\n subscribe_topic: str,\n publish_topic: str,\n bot_prefix: str,\n clean_session: bool = True,\n qos: int = 2,\n tls_enabled: bool = False,\n tls_ca_certs: Optional[str] = None,\n tls_certfile: Optional[str] = None,\n tls_keyfile: Optional[str] = None,\n on_reply_sent: OnReplySent = None,\n show_tool_details: bool = True,\n filter_tool_messages: bool = False,\n filter_thinking: bool = False,\n ):\n super().__init__(\n process,\n on_reply_sent=on_reply_sent,\n show_tool_details=show_tool_details,\n filter_tool_messages=filter_tool_messages,\n filter_thinking=filter_thinking,\n )\n\n self.enabled = enabled\n self.host = host\n self.port = port\n self.transport = transport\n self.username = username\n self.password = password\n self.subscribe_topic = subscribe_topic\n self.publish_topic = publish_topic\n self.bot_prefix = bot_prefix\n self.tls_enabled = tls_enabled\n self.tls_ca_certs = tls_ca_certs\n self.tls_certfile = tls_certfile\n self.tls_keyfile = tls_keyfile\n self.clean_session = clean_session\n self.qos = qos\n self.client: Optional[mqtt.Client] = None\n self.connected = False\n self._thread: Optional[threading.Thread] = None\n\n @classmethod\n def from_env(\n cls,\n process: ProcessHandler,\n on_reply_sent: OnReplySent = None,\n ) -> \"MQTTChannel\":\n import os\n\n port_str = os.getenv(\"MQTT_PORT\", \"1883\")\n port = int(port_str) if port_str.isdigit() else 1883\n\n clean_session = os.getenv(\"MQTT_CLEAN_SESSION\", \"1\") == \"1\"\n qos_str = os.getenv(\"MQTT_QOS\", \"2\")\n qos = int(qos_str) if qos_str.isdigit() else 0\n\n return cls(\n process=process,\n enabled=os.getenv(\"MQTT_CHANNEL_ENABLED\", \"0\") == \"1\",\n host=os.getenv(\"MQTT_HOST\", \"\"),\n port=port,\n transport=os.getenv(\"MQTT_TRANSPORT\", \"mqtt\"),\n username=os.getenv(\"MQTT_USERNAME\", \"\"),\n password=os.getenv(\"MQTT_PASSWORD\", \"\"),\n subscribe_topic=os.getenv(\"MQTT_SUBSCRIBE_TOPIC\", \"\"),\n publish_topic=os.getenv(\"MQTT_PUBLISH_TOPIC\", \"\"),\n bot_prefix=os.getenv(\"MQTT_BOT_PREFIX\", \"\"),\n clean_session=clean_session,\n qos=qos,\n tls_enabled=os.getenv(\"MQTT_TLS_ENABLED\", \"0\") == \"1\",\n tls_ca_certs=os.getenv(\"MQTT_TLS_CA_CERTS\"),\n tls_certfile=os.getenv(\"MQTT_TLS_CERTFILE\"),\n tls_keyfile=os.getenv(\"MQTT_TLS_KEYFILE\"),\n on_reply_sent=on_reply_sent,\n )\n\n @classmethod\n def from_config(\n cls,\n process: ProcessHandler,\n config: Union[MQTTChannelConfig, dict],\n on_reply_sent: OnReplySent = None,\n show_tool_details: bool = True,\n filter_tool_messages: bool = False,\n filter_thinking: bool = False,\n ) -> \"MQTTChannel\":\n if isinstance(config, dict):\n port_val = config.get(\"port\", 1883)\n port = (\n int(port_val)\n if isinstance(port_val, (str, int)) and str(port_val).isdigit()\n else 1883\n )\n\n clean_session = bool(config.get(\"clean_session\", True))\n qos_val = config.get(\"qos\", 2)\n qos = (\n int(qos_val)\n if isinstance(qos_val, (str, int)) and str(qos_val).isdigit()\n else 0\n )\n\n return cls(\n process=process,\n enabled=bool(config.get(\"enabled\", False)),\n host=(config.get(\"host\") or \"\").strip(),\n port=port,\n username=(config.get(\"username\") or \"\").strip(),\n password=(config.get(\"password\") or \"\").strip(),\n subscribe_topic=(config.get(\"subscribe_topic\") or \"\").strip(),\n publish_topic=(config.get(\"publish_topic\") or \"\").strip(),\n bot_prefix=(config.get(\"bot_prefix\") or \"\").strip(),\n clean_session=clean_session,\n qos=qos,\n tls_enabled=bool(config.get(\"tls_enabled\", False)),\n tls_ca_certs=config.get(\"tls_ca_certs\"),\n tls_certfile=config.get(\"tls_certfile\"),\n tls_keyfile=config.get(\"tls_keyfile\"),\n transport=config.get(\"transport\", \"tcp\"),\n on_reply_sent=on_reply_sent,\n show_tool_details=show_tool_details,\n filter_tool_messages=filter_tool_messages,\n filter_thinking=filter_thinking,\n )\n port = int(config.port) if config.port else 1883\n\n clean_session = getattr(config, \"clean_session\", True)\n qos = getattr(config, \"qos\", 2)\n\n return cls(\n process=process,\n enabled=config.enabled,\n host=config.host or \"\",\n port=port,\n username=config.username or \"\",\n password=config.password or \"\",\n subscribe_topic=config.subscribe_topic or \"\",\n publish_topic=config.publish_topic or \"\",\n bot_prefix=config.bot_prefix or \"\",\n clean_session=clean_session,\n qos=qos,\n transport=getattr(config, \"transport\", \"\"),\n tls_enabled=getattr(config, \"tls_enabled\", False),\n tls_ca_certs=getattr(config, \"tls_ca_certs\", None),\n tls_certfile=getattr(config, \"tls_certfile\", None),\n tls_keyfile=getattr(config, \"tls_keyfile\", None),\n on_reply_sent=on_reply_sent,\n show_tool_details=show_tool_details,\n filter_tool_messages=filter_tool_messages,\n filter_thinking=filter_thinking,\n )\n\n def _validate_config(self):\n \"\"\"Validate required MQTT config\"\"\"\n if not self.host:\n raise ValueError(\"MQTT host is required\")\n if not self.subscribe_topic:\n raise ValueError(\"MQTT subscribe_topic is required\")\n if not self.publish_topic:\n raise ValueError(\"MQTT publish_topic is required\")\n\n def _on_connect(\n self,\n client,\n _userdata,\n _flags,\n reason_code,\n _properties=None,\n ):\n if reason_code == 0:\n self.connected = True\n logger.info(\"MQTT connected\")\n client.subscribe(self.subscribe_topic, qos=self.qos)\n logger.info(\n f\"Subscribed to {self.subscribe_topic} with QoS={self.qos}\",\n )\n else:\n logger.error(f\"MQTT connect failed, return code {reason_code}\")\n\n def _on_disconnect(\n self,\n _client,\n _userdata,\n _flags,\n _reason,\n _properties=None,\n ):\n self.connected = False\n if _reason != 0:\n logger.warning(f\"MQTT disconnected unexpectedly, code={_reason}\")\n\n def _on_message(self, _client, _userdata, msg):\n try:\n payload = msg.payload.decode(\"utf-8\").strip()\n data = {}\n try:\n data = json.loads(payload)\n content = data.get(\"text\", \"\")\n except json.JSONDecodeError:\n content = payload\n\n if not content:\n logger.error(f\"Error MQTT message: {msg.topic} - {payload}\")\n return\n\n client_id = data.get(\"redirect_client_id\")\n if not client_id:\n parts = msg.topic.split(\"/\")\n if len(parts) >= 2:\n client_id = parts[1]\n if not client_id:\n client_id = \"unknown-client\"\n logger.warning(\n f\"MQTT: No client_id found in topic or payload: \"\n f\"{msg.topic}\",\n )\n\n logger.info(f\"MQTT [{client_id}] >> {content}\")\n\n content_parts = [TextContent(type=ContentType.TEXT, text=content)]\n native = {\n \"channel_id\": self.channel,\n \"sender_id\": client_id,\n \"content_parts\": content_parts,\n \"meta\": {\n \"topic\": msg.topic,\n \"client_id\": client_id,\n \"raw_payload\": payload,\n },\n }\n\n if self._enqueue is not None:\n self._enqueue(native)\n else:\n logger.warning(\"MQTT: _enqueue not set, message dropped\")\n\n except Exception as e:\n logger.error(\n f\"Error processing MQTT message: {str(e)}\",\n exc_info=True,\n )\n\n async def start(self) -> None:\n if not self.enabled:\n logger.debug(\"MQTT: start() skipped (enabled=false)\")\n return\n\n try:\n self._validate_config()\n except ValueError as e:\n logger.error(f\"MQTT config validation failed: {str(e)}\")\n return\n\n logger.info(\"Starting MQTT channel...\")\n import uuid\n\n client_id = f\"copaw-mqtt-{uuid.uuid4()}\"\n self.client = mqtt.Client(\n client_id=client_id,\n protocol=mqtt.MQTTv311,\n callback_api_version=mqtt.CallbackAPIVersion.VERSION2,\n transport=self.transport,\n clean_session=self.clean_session,\n )\n\n if self.username and self.password:\n self.client.username_pw_set(self.username, self.password)\n\n if self.tls_enabled:\n logger.info(\"MQTT: Enabling TLS\")\n self.client.tls_set(\n ca_certs=self.tls_ca_certs,\n certfile=self.tls_certfile,\n keyfile=self.tls_keyfile,\n )\n\n self.client.reconnect_delay_set(min_delay=1, max_delay=10)\n self.client.on_connect = self._on_connect\n self.client.on_message = self._on_message\n self.client.on_disconnect = self._on_disconnect\n\n try:\n self.client.connect(self.host, self.port, keepalive=60)\n logger.info(\n f\"MQTT connecting to {self.host}:{self.port} \"\n f\"{'(TLS enabled)' if self.tls_enabled else ''} \"\n f\"(transport: {self.transport})\",\n )\n except MQTTException as e:\n logger.error(f\"MQTT connect failed: {str(e)}\")\n return\n\n self.client.loop_start()\n\n logger.info(\"MQTT channel started\")\n logger.info(f\"Subscribing to: {self.subscribe_topic}\")\n logger.info(f\"Publishing to: {self.publish_topic}\")\n logger.info(f\"Using transport: {self.transport}\")\n logger.info(f\"Clean session: {self.clean_session}\")\n logger.info(f\"QoS level: {self.qos}\")\n\n async def stop(self) -> None:\n logger.info(\"Stopping MQTT channel...\")\n if self.client:\n self.client.loop_stop()\n self.client.disconnect()\n self.client = None\n self.connected = False\n logger.info(\"MQTT channel stopped\")\n\n async def send(\n self,\n to_handle: str,\n text: str,\n meta: Optional[dict] = None,\n ) -> None:\n if not self.enabled or not self.client or not self.connected:\n return\n\n try:\n client_id = to_handle\n if meta and \"client_id\" in meta:\n client_id = meta[\"client_id\"]\n\n if not client_id:\n logger.warning(\"MQTT send: no client_id\")\n return\n\n send_topic = self.publish_topic.format(client_id=client_id)\n self.client.publish(send_topic, text, qos=self.qos)\n logger.info(f\"MQTT [{client_id}] << {text} (QoS={self.qos})\")\n\n except Exception as e:\n logger.error(f\"Failed to send MQTT message: {str(e)}\")\n\n async def send_media(\n self,\n to_handle: str,\n part: OutgoingContentPart,\n meta: Optional[dict] = None,\n ) -> None:\n if not self.enabled or not self.client or not self.connected:\n return\n\n try:\n client_id = to_handle\n if meta and \"client_id\" in meta:\n client_id = meta[\"client_id\"]\n\n if not client_id:\n logger.warning(\"MQTT send_media: no client_id\")\n return\n\n send_topic = self.publish_topic.format(client_id=client_id)\n part_type = getattr(part, \"type\", None)\n\n if part_type == ContentType.IMAGE:\n img_url = getattr(part, \"image_url\", \"\")\n self.client.publish(\n send_topic,\n f\"[Image] {img_url}\",\n qos=self.qos,\n )\n elif part_type == ContentType.VIDEO:\n vid_url = getattr(part, \"video_url\", \"\")\n self.client.publish(\n send_topic,\n f\"[Video] {vid_url}\",\n qos=self.qos,\n )\n elif part_type == ContentType.AUDIO:\n self.client.publish(send_topic, \"[Audio]\", qos=self.qos)\n elif part_type == ContentType.FILE:\n file_url = getattr(part, \"file_url\", \"\") or getattr(\n part,\n \"file_id\",\n \"\",\n )\n self.client.publish(\n send_topic,\n f\"[File] {file_url}\",\n qos=self.qos,\n )\n\n except Exception as e:\n logger.error(f\"Failed to send MQTT media: {str(e)}\")\n\n def resolve_session_id(\n self,\n sender_id: str,\n channel_meta: Optional[dict] = None,\n ) -> str:\n return f\"mqtt:{sender_id}\"\n\n def get_to_handle_from_request(self, request: Any) -> str:\n meta = getattr(request, \"channel_meta\", None) or {}\n client_id = meta.get(\"client_id\")\n if client_id:\n return str(client_id)\n sid = getattr(request, \"session_id\", \"\")\n if sid.startswith(\"mqtt:\"):\n return sid.split(\":\", 1)[-1]\n return getattr(request, \"user_id\", \"\") or \"\"\n\n def build_agent_request_from_native(self, native_payload: Any) -> Any:\n payload = native_payload if isinstance(native_payload, dict) else {}\n channel_id = payload.get(\"channel_id\") or self.channel\n sender_id = payload.get(\"sender_id\") or \"\"\n content_parts = payload.get(\"content_parts\") or []\n meta = payload.get(\"meta\") or {}\n session_id = self.resolve_session_id(sender_id, meta)\n user_id = str(meta.get(\"client_id\") or sender_id)\n request = self.build_agent_request_from_user_content(\n channel_id=channel_id,\n sender_id=sender_id,\n session_id=session_id,\n content_parts=content_parts,\n channel_meta=meta,\n )\n request.user_id = user_id\n request.channel_meta = meta\n return request\n\n def to_handle_from_target(self, *, user_id: str, session_id: str) -> str:\n if session_id.startswith(\"mqtt:\"):\n return session_id.split(\":\", 1)[-1]\n return user_id\n" }, { "path": "src/copaw/app/channels/qq/__init__.py", "content": "# -*- coding: utf-8 -*-\n\"\"\"QQ channel package.\"\"\"\nfrom .channel import QQChannel\n\n__all__ = [\"QQChannel\"]\n" }, { "path": "src/copaw/app/channels/qq/channel.py", "content": "# -*- coding: utf-8 -*-\n# pylint: disable=too-many-branches,too-many-statements\n\"\"\"QQ Channel.\n\nQQ uses WebSocket for incoming events and HTTP API for replies.\nNo request-reply coupling: handler enqueues Incoming, consumer processes\nand sends reply via send_c2c_message / send_channel_message /\nsend_group_message.\nRich media read (images, videos, files)\n\"\"\"\n\nfrom __future__ import annotations\n\nimport asyncio\nimport json\nimport logging\nimport os\nimport re\nimport threading\nimport time\nfrom dataclasses import dataclass\nfrom pathlib import Path\nfrom typing import Any, Dict, List, Optional, Tuple\n\nimport aiohttp\n\nfrom agentscope_runtime.engine.schemas.agent_schemas import (\n TextContent,\n ImageContent,\n VideoContent,\n AudioContent,\n FileContent,\n ContentType,\n)\n\nfrom ....config.config import QQConfig as QQChannelConfig\nfrom ....constant import WORKING_DIR\n\nfrom ..base import (\n BaseChannel,\n OnReplySent,\n OutgoingContentPart,\n ProcessHandler,\n)\n\nlogger = logging.getLogger(__name__)\n\n# QQ Bot WebSocket op codes\nOP_DISPATCH = 0\nOP_HEARTBEAT = 1\nOP_IDENTIFY = 2\nOP_RESUME = 6\nOP_RECONNECT = 7\nOP_INVALID_SESSION = 9\nOP_HELLO = 10\nOP_HEARTBEAT_ACK = 11\n\n# Intents\nINTENT_PUBLIC_GUILD_MESSAGES = 1 << 30\nINTENT_DIRECT_MESSAGE = 1 << 12\nINTENT_GROUP_AND_C2C = 1 << 25\nINTENT_GUILD_MEMBERS = 1 << 1\n\nRECONNECT_DELAYS = [1, 2, 5, 10, 30, 60]\nRATE_LIMIT_DELAY = 60\nMAX_RECONNECT_ATTEMPTS = 100\nQUICK_DISCONNECT_THRESHOLD = 5\nMAX_QUICK_DISCONNECT_COUNT = 3\n\nDEFAULT_API_BASE = \"https://api.sgroup.qq.com\"\nTOKEN_URL = \"https://bots.qq.com/app/getAppAccessToken\"\n_URL_PATTERN = re.compile(r\"https?://[^\\s]+|www\\.[^\\s]+\", re.IGNORECASE)\n# More aggressive pattern: also catches bare domains like 12306.cn, google.com\n_BARE_DOMAIN_PATTERN = re.compile(\n r\"https?://[^\\s]+|www\\.[^\\s]+\"\n r\"|\\b[\\w][\\w.-]*\\.\"\n r\"(?:com|cn|org|net|edu|gov|io|co|cc|tv|me|info|biz|app|dev|top|xyz\"\n r\"|site|vip|shop|tech|club|pro|live|mobi|asia|wiki)\"\n r\"(?:\\.[a-z]{2,3})?\\b(?:/[^\\s]*)?\",\n re.IGNORECASE,\n)\n_IMAGE_TAG_PATTERN = re.compile(r\"\\[Image: (https?://[^\\]]+)\\]\", re.IGNORECASE)\n\n# Rich media paths\n_DEFAULT_MEDIA_DIR = WORKING_DIR / \"media\" / \"qq\"\n\n\n# ---------------------------------------------------------------------------\n# Message event spec: describes how each WS event type maps to meta fields\n# ---------------------------------------------------------------------------\n\n\n@dataclass(frozen=True)\nclass _MessageEventSpec:\n \"\"\"Describes the per-event-type differences for WS message dispatch.\"\"\"\n\n message_type: str\n sender_keys: Tuple[str, ...]\n extra_meta_keys: Tuple[str, ...] = ()\n\n\n_MESSAGE_EVENT_SPECS: Dict[str, _MessageEventSpec] = {\n \"C2C_MESSAGE_CREATE\": _MessageEventSpec(\n message_type=\"c2c\",\n sender_keys=(\"user_openid\", \"id\"),\n ),\n \"AT_MESSAGE_CREATE\": _MessageEventSpec(\n message_type=\"guild\",\n sender_keys=(\"id\", \"username\"),\n extra_meta_keys=(\"channel_id\", \"guild_id\"),\n ),\n \"DIRECT_MESSAGE_CREATE\": _MessageEventSpec(\n message_type=\"dm\",\n sender_keys=(\"id\", \"username\"),\n extra_meta_keys=(\"channel_id\", \"guild_id\"),\n ),\n \"GROUP_AT_MESSAGE_CREATE\": _MessageEventSpec(\n message_type=\"group\",\n sender_keys=(\"member_openid\", \"id\"),\n extra_meta_keys=(\"group_openid\",),\n ),\n}\n\n\n# ---------------------------------------------------------------------------\n# WebSocket state & heartbeat helpers\n# ---------------------------------------------------------------------------\n\n\n@dataclass\nclass _WSState:\n \"\"\"Mutable state carried across reconnect attempts.\"\"\"\n\n session_id: Optional[str] = None\n last_seq: Optional[int] = None\n reconnect_attempts: int = 0\n last_connect_time: float = 0.0\n quick_disconnect_count: int = 0\n identify_fail_count: int = 0\n should_refresh_token: bool = False\n\n\nclass _HeartbeatController:\n \"\"\"Manages recurring WebSocket heartbeat via threading.Timer.\"\"\"\n\n def __init__(\n self,\n ws: Any,\n stop_event: threading.Event,\n state: _WSState,\n ) -> None:\n self._ws = ws\n self._stop_event = stop_event\n self._state = state\n self._timer: Optional[threading.Timer] = None\n self._interval: Optional[float] = None\n\n def start(self, interval_ms: float) -> None:\n self._interval = interval_ms\n self._schedule()\n\n def stop(self) -> None:\n if self._timer:\n self._timer.cancel()\n self._timer = None\n\n def _schedule(self) -> None:\n if self._interval is None or self._stop_event.is_set():\n return\n self._timer = threading.Timer(\n self._interval / 1000.0,\n self._send_ping,\n )\n self._timer.daemon = True\n self._timer.start()\n\n def _send_ping(self) -> None:\n if self._stop_event.is_set():\n return\n try:\n if self._ws.connected:\n self._ws.send(\n json.dumps(\n {\"op\": OP_HEARTBEAT, \"d\": self._state.last_seq},\n ),\n )\n logger.debug(\"qq heartbeat sent\")\n except Exception:\n pass\n self._schedule()\n\n\nclass QQApiError(RuntimeError):\n \"\"\"HTTP error returned by QQ API.\"\"\"\n\n def __init__(self, path: str, status: int, data: Any):\n self.path = path\n self.status = status\n self.data = data\n super().__init__(f\"API {path} {status}: {data}\")\n\n\ndef _sanitize_qq_text(text: str) -> tuple[str, bool]:\n \"\"\"QQ API disallows URL links in plain messages.\n\n Return the sanitized text and whether any URL was removed.\n \"\"\"\n if not text:\n return \"\", False\n sanitized, count = _URL_PATTERN.subn(\"[链接已省略]\", text)\n return sanitized, count > 0\n\n\ndef _aggressive_sanitize_qq_text(text: str) -> tuple[str, bool]:\n \"\"\"More aggressive URL stripping – also catches bare domain patterns.\n\n Used as a second-level fallback when QQ still rejects the message\n because of URL-like content that ``_sanitize_qq_text`` did not catch.\n \"\"\"\n if not text:\n return \"\", False\n sanitized, count = _BARE_DOMAIN_PATTERN.subn(\"[链接已省略]\", text)\n return sanitized, count > 0\n\n\ndef _is_url_content_error(exc: Exception) -> bool:\n \"\"\"Return *True* if QQ rejected the message because it contains a URL.\"\"\"\n if not isinstance(exc, QQApiError):\n return False\n try:\n payload_text = json.dumps(exc.data, ensure_ascii=False).lower()\n except Exception:\n payload_text = str(exc.data).lower()\n return (\n \"304003\" in payload_text\n or \"40034028\" in payload_text\n or \"不允许包含url\" in payload_text\n )\n\n\ndef _as_bool(value: Any) -> bool:\n if isinstance(value, bool):\n return value\n if isinstance(value, str):\n return value.strip().lower() in {\"1\", \"true\", \"yes\", \"on\"}\n return bool(value)\n\n\ndef _should_plaintext_fallback_from_markdown(exc: Exception) -> bool:\n \"\"\"Only fallback for explicit markdown payload validation failures.\"\"\"\n if not isinstance(exc, QQApiError):\n return False\n if exc.status < 400 or exc.status >= 500:\n return False\n try:\n payload_text = json.dumps(exc.data, ensure_ascii=False).lower()\n except Exception:\n payload_text = str(exc.data).lower()\n\n # Check for markdown-related error messages or codes\n return (\n \"markdown\" in payload_text\n or \"msg_type\" in payload_text\n or \"msg type\" in payload_text\n or \"message type\" in payload_text\n or \"50056\" in payload_text # 不允许发送原生 markdown\n or \"不允许发送原生 markdown\" in payload_text\n or \"40034012\" in payload_text # err_code for markdown not allowed\n )\n\n\ndef _get_api_base() -> str:\n \"\"\"API root address (e.g. sandbox: https://sandbox.api.sgroup.qq.com)\"\"\"\n return os.getenv(\"QQ_API_BASE\", DEFAULT_API_BASE).rstrip(\"/\")\n\n\ndef _get_channel_url_sync(access_token: str) -> str:\n import urllib.error\n import urllib.request\n\n url = f\"{_get_api_base()}/gateway\"\n req = urllib.request.Request(\n url,\n headers={\n \"Authorization\": f\"QQBot {access_token}\",\n \"Content-Type\": \"application/json\",\n },\n method=\"GET\",\n )\n try:\n with urllib.request.urlopen(req, timeout=15) as resp:\n data = json.loads(resp.read().decode())\n except urllib.error.HTTPError as e:\n body = \"\"\n try:\n body = e.read().decode() if e.fp else \"\"\n except Exception:\n pass\n msg = f\"HTTP {e.code}: {e.reason}\"\n if body:\n msg += f\" | body: {body[:500]}\"\n raise RuntimeError(f\"Failed to get channel url: {msg}\") from e\n except Exception as e:\n raise RuntimeError(f\"Failed to get channel url: {e}\") from e\n channel_url = data.get(\"url\")\n if not channel_url:\n raise RuntimeError(f\"No url in channel response: {data}\")\n return channel_url\n\n\n_msg_seq: Dict[str, int] = {}\n_msg_seq_lock = threading.Lock()\n\n\ndef _get_next_msg_seq(msg_id: str) -> int:\n with _msg_seq_lock:\n n = _msg_seq.get(msg_id, 0) + 1\n _msg_seq[msg_id] = n\n if len(_msg_seq) > 1000:\n for k in list(_msg_seq.keys())[:500]:\n del _msg_seq[k]\n return n\n\n\nasync def _api_request_async(\n session: Any,\n access_token: str,\n method: str,\n path: str,\n body: Optional[Dict[str, Any]] = None,\n) -> Dict[str, Any]:\n url = f\"{_get_api_base()}{path}\"\n kwargs = {\n \"headers\": {\n \"Authorization\": f\"QQBot {access_token}\",\n \"Content-Type\": \"application/json\",\n },\n }\n if body is not None:\n kwargs[\"json\"] = body\n async with session.request(method, url, **kwargs) as resp:\n data = await resp.json()\n if resp.status >= 400:\n raise QQApiError(path=path, status=resp.status, data=data)\n return data\n\n\nasync def _send_message_async(\n session: Any,\n access_token: str,\n path: str,\n content: str,\n msg_id: Optional[str] = None,\n use_markdown: bool = False,\n use_msg_seq: bool = True,\n seq_key: str = \"\",\n) -> None:\n \"\"\"Send a text message to QQ API.\n\n Args:\n path: API path, e.g. /v2/users/{openid}/messages\n use_msg_seq: c2c and group need msg_seq+msg_type;\n channel messages do not.\n seq_key: key for msg_seq counter (e.g. msg_id or \"c2c\")\n \"\"\"\n if use_markdown:\n body: Dict[str, Any] = {\n \"markdown\": {\"content\": content},\n }\n if use_msg_seq:\n body[\"msg_type\"] = 2\n else:\n body = {\"content\": content}\n if use_msg_seq:\n body[\"msg_type\"] = 0\n if use_msg_seq:\n body[\"msg_seq\"] = _get_next_msg_seq(\n msg_id or seq_key,\n )\n if msg_id:\n body[\"msg_id\"] = msg_id\n await _api_request_async(\n session,\n access_token,\n \"POST\",\n path,\n body,\n )\n\n\n_MEDIA_PATH_PREFIX = {\n \"c2c\": \"/v2/users\",\n \"group\": \"/v2/groups\",\n}\n\n\ndef _media_path(\n message_type: str,\n openid: str,\n suffix: str,\n) -> Optional[str]:\n \"\"\"Build media API path or return None if unsupported.\"\"\"\n prefix = _MEDIA_PATH_PREFIX.get(message_type)\n if not prefix:\n return None\n return f\"{prefix}/{openid}/{suffix}\"\n\n\nasync def _upload_media_async(\n session: Any,\n access_token: str,\n openid: str,\n media_type: int,\n url: str,\n message_type: str = \"c2c\",\n) -> Optional[str]:\n \"\"\"Upload media to QQ rich media server.\n\n Returns file_info if success, None otherwise.\n \"\"\"\n path = _media_path(message_type, openid, \"files\")\n if not path:\n logger.warning(\"Unsupported type for media upload: %s\", message_type)\n return None\n try:\n response = await _api_request_async(\n session,\n access_token,\n \"POST\",\n path,\n {\"file_type\": media_type, \"url\": url, \"srv_send_msg\": False},\n )\n return response.get(\"file_info\")\n except Exception:\n logger.exception(\"Failed to upload media from url: %s\", url)\n return None\n\n\nasync def _send_media_message_async(\n session: Any,\n access_token: str,\n openid: str,\n file_info: str,\n msg_id: Optional[str] = None,\n message_type: str = \"c2c\",\n) -> None:\n \"\"\"Send rich media message.\"\"\"\n path = _media_path(message_type, openid, \"messages\")\n if not path:\n logger.warning(\"Unsupported type for media send: %s\", message_type)\n return\n body: Dict[str, Any] = {\n \"msg_type\": 7,\n \"media\": {\"file_info\": file_info},\n \"msg_seq\": _get_next_msg_seq(msg_id or f\"{message_type}_media\"),\n }\n if msg_id:\n body[\"msg_id\"] = msg_id\n await _api_request_async(\n session,\n access_token,\n \"POST\",\n path,\n body,\n )\n\n\nasync def _download_qq_file(\n *,\n http_session: aiohttp.ClientSession,\n file_url: str,\n media_dir: Path,\n filename_hint: str = \"\",\n) -> Optional[str]:\n \"\"\"Download a QQ file to local media_dir; return local path.\"\"\"\n try:\n if not filename_hint:\n logger.warning(\"filename is empty\")\n return None\n\n # Sanitize filename to prevent path traversal\n safe_filename = Path(filename_hint).name\n\n media_dir.mkdir(parents=True, exist_ok=True)\n local_path = media_dir / safe_filename\n async with http_session.get(file_url) as resp:\n if resp.status != 200:\n logger.warning(\n \"qq download failed: status=%s url=%s\",\n resp.status,\n file_url,\n )\n return None\n content = await resp.read()\n with open(str(local_path), \"wb\") as f:\n f.write(content)\n return str(local_path)\n except Exception:\n logger.exception(\"qq download failed for url=%s\", file_url)\n return None\n\n\nclass QQChannel(BaseChannel):\n \"\"\"QQ Channel:\n WebSocket events -> Incoming -> process -> HTTP API reply.\n \"\"\"\n\n channel = \"qq\"\n\n def __init__(\n self,\n process: ProcessHandler,\n enabled: bool,\n app_id: str,\n client_secret: str,\n bot_prefix: str = \"\",\n markdown_enabled: bool = True,\n on_reply_sent: OnReplySent = None,\n show_tool_details: bool = True,\n filter_tool_messages: bool = False,\n filter_thinking: bool = False,\n media_dir: str = \"\",\n ):\n super().__init__(\n process,\n on_reply_sent=on_reply_sent,\n show_tool_details=show_tool_details,\n filter_tool_messages=filter_tool_messages,\n filter_thinking=filter_thinking,\n )\n self.enabled = enabled\n self.app_id = app_id\n self.client_secret = client_secret\n self.bot_prefix = bot_prefix\n self._markdown_enabled = markdown_enabled\n self._media_dir = (\n Path(media_dir).expanduser() if media_dir else _DEFAULT_MEDIA_DIR\n )\n\n self._loop: Optional[asyncio.AbstractEventLoop] = None\n self._ws_thread: Optional[threading.Thread] = None\n self._stop_event = threading.Event()\n self._account_id = \"default\"\n self._token_cache: Optional[Dict[str, Any]] = None\n self._token_lock = threading.Lock()\n\n self._http: Optional[aiohttp.ClientSession] = None\n\n def _get_access_token_sync(self) -> str:\n \"\"\"Sync get access_token for WebSocket thread. Instance-level cache.\"\"\"\n with self._token_lock:\n if (\n self._token_cache\n and time.time() < self._token_cache[\"expires_at\"] - 300\n ):\n return self._token_cache[\"token\"]\n try:\n import urllib.request\n\n req = urllib.request.Request(\n TOKEN_URL,\n data=json.dumps(\n {\"appId\": self.app_id, \"clientSecret\": self.client_secret},\n ).encode(),\n headers={\"Content-Type\": \"application/json\"},\n method=\"POST\",\n )\n with urllib.request.urlopen(req, timeout=15) as resp:\n data = json.loads(resp.read().decode())\n except Exception as e:\n raise RuntimeError(f\"Failed to get access_token: {e}\") from e\n token = data.get(\"access_token\")\n if not token:\n raise RuntimeError(f\"No access_token in response: {data}\")\n expires_in = data.get(\"expires_in\", 7200)\n if isinstance(expires_in, str):\n expires_in = int(expires_in)\n with self._token_lock:\n self._token_cache = {\n \"token\": token,\n \"expires_at\": time.time() + expires_in,\n }\n return token\n\n async def _get_access_token_async(self) -> str:\n \"\"\"Async get token for send. Instance-level cache.\"\"\"\n with self._token_lock:\n if (\n self._token_cache\n and time.time() < self._token_cache[\"expires_at\"] - 300\n ):\n return self._token_cache[\"token\"]\n async with self._http.post(\n TOKEN_URL,\n json={\"appId\": self.app_id, \"clientSecret\": self.client_secret},\n headers={\"Content-Type\": \"application/json\"},\n ) as resp:\n if resp.status >= 400:\n text = await resp.text()\n raise RuntimeError(\n f\"Token request failed {resp.status}: {text}\",\n )\n data = await resp.json()\n token = data.get(\"access_token\")\n if not token:\n raise RuntimeError(f\"No access_token: {data}\")\n expires_in = data.get(\"expires_in\", 7200)\n if isinstance(expires_in, str):\n expires_in = int(expires_in)\n with self._token_lock:\n self._token_cache = {\n \"token\": token,\n \"expires_at\": time.time() + expires_in,\n }\n return token\n\n def _clear_token_cache(self) -> None:\n with self._token_lock:\n self._token_cache = None\n\n @classmethod\n def from_env(\n cls,\n process: ProcessHandler,\n on_reply_sent: OnReplySent = None,\n ) -> \"QQChannel\":\n return cls(\n process=process,\n enabled=os.getenv(\"QQ_CHANNEL_ENABLED\", \"1\") == \"1\",\n app_id=os.getenv(\"QQ_APP_ID\", \"\"),\n client_secret=os.getenv(\"QQ_CLIENT_SECRET\", \"\"),\n bot_prefix=os.getenv(\"QQ_BOT_PREFIX\", \"\"),\n markdown_enabled=_as_bool(os.getenv(\"QQ_MARKDOWN_ENABLED\", \"1\")),\n on_reply_sent=on_reply_sent,\n )\n\n @classmethod\n def from_config(\n cls,\n process: ProcessHandler,\n config: QQChannelConfig,\n on_reply_sent: OnReplySent = None,\n show_tool_details: bool = True,\n filter_tool_messages: bool = False,\n filter_thinking: bool = False,\n ) -> \"QQChannel\":\n return cls(\n process=process,\n enabled=config.enabled,\n app_id=config.app_id or \"\",\n client_secret=config.client_secret or \"\",\n bot_prefix=config.bot_prefix or \"\",\n markdown_enabled=getattr(config, \"markdown_enabled\", True),\n on_reply_sent=on_reply_sent,\n show_tool_details=show_tool_details,\n filter_tool_messages=filter_tool_messages,\n filter_thinking=filter_thinking,\n media_dir=getattr(config, \"media_dir\", \"\"),\n )\n\n def _resolve_send_path(\n self,\n message_type: str,\n sender_id: str,\n channel_id: Optional[str],\n group_openid: Optional[str],\n guild_id: Optional[str] = None,\n ) -> tuple[str, bool, str]:\n \"\"\"Return (api_path, use_msg_seq, seq_key).\"\"\"\n if message_type == \"dm\" and guild_id:\n return (\n f\"/dms/{guild_id}/messages\",\n False,\n \"\",\n )\n if message_type == \"group\" and group_openid:\n return (\n f\"/v2/groups/{group_openid}/messages\",\n True,\n \"group\",\n )\n if message_type == \"guild\" and channel_id:\n return (\n f\"/channels/{channel_id}/messages\",\n False,\n \"\",\n )\n # c2c or fallback\n return (\n f\"/v2/users/{sender_id}/messages\",\n True,\n \"c2c\",\n )\n\n async def _dispatch_text(\n self,\n message_type: str,\n sender_id: str,\n channel_id: Optional[str],\n group_openid: Optional[str],\n text: str,\n msg_id: Optional[str],\n token: str,\n markdown: bool,\n guild_id: Optional[str] = None,\n ) -> None:\n \"\"\"Route a text message to the correct QQ send API.\"\"\"\n path, use_seq, seq_key = self._resolve_send_path(\n message_type,\n sender_id,\n channel_id,\n group_openid,\n guild_id=guild_id,\n )\n await _send_message_async(\n self._http,\n token,\n path,\n text,\n msg_id,\n use_markdown=markdown,\n use_msg_seq=use_seq,\n seq_key=seq_key,\n )\n\n async def _send_text_with_fallback(\n self,\n message_type: str,\n sender_id: str,\n channel_id: Optional[str],\n group_openid: Optional[str],\n text: str,\n msg_id: Optional[str],\n token: str,\n use_markdown: bool,\n guild_id: Optional[str] = None,\n ) -> bool:\n \"\"\"Send text with multi-level fallback.\n\n Fallback chain:\n 1. Send as-is (markdown or plain)\n 2. If markdown fails with validation -> plain text\n 3. If plain text fails with URL error -> aggressive URL strip\n\n Returns True if text was sent successfully.\n \"\"\"\n try:\n await self._dispatch_text(\n message_type,\n sender_id,\n channel_id,\n group_openid,\n text,\n msg_id,\n token,\n use_markdown,\n guild_id=guild_id,\n )\n return True\n except Exception as exc:\n if not use_markdown:\n return await self._try_aggressive_url_fallback(\n exc,\n text,\n message_type,\n sender_id,\n channel_id,\n group_openid,\n msg_id,\n token,\n guild_id,\n )\n if not _should_plaintext_fallback_from_markdown(exc):\n logger.exception(\n \"send text failed with markdown; \"\n \"skip fallback to avoid duplicates\",\n )\n return False\n logger.exception(\n \"send text failed with markdown payload validation; \"\n \"fallback to plain text\",\n )\n\n fallback_text, had_url = _sanitize_qq_text(text)\n if had_url:\n logger.info(\n \"qq send fallback: stripped URL content \"\n \"for API compatibility\",\n )\n try:\n await self._dispatch_text(\n message_type,\n sender_id,\n channel_id,\n group_openid,\n fallback_text,\n msg_id,\n token,\n False,\n guild_id=guild_id,\n )\n return True\n except Exception as exc2:\n return await self._try_aggressive_url_fallback(\n exc2,\n text,\n message_type,\n sender_id,\n channel_id,\n group_openid,\n msg_id,\n token,\n guild_id,\n )\n\n async def _try_aggressive_url_fallback(\n self,\n exc: Exception,\n original_text: str,\n message_type: str,\n sender_id: str,\n channel_id: Optional[str],\n group_openid: Optional[str],\n msg_id: Optional[str],\n token: str,\n guild_id: Optional[str],\n ) -> bool:\n \"\"\"Attempt aggressive URL stripping if QQ rejected URL content.\"\"\"\n if not _is_url_content_error(exc):\n logger.exception(\"send text failed\")\n return False\n logger.warning(\n \"send text failed due to URL content; \"\n \"trying aggressive URL stripping\",\n )\n aggressive_text, _ = _aggressive_sanitize_qq_text(\n original_text,\n )\n try:\n await self._dispatch_text(\n message_type,\n sender_id,\n channel_id,\n group_openid,\n aggressive_text,\n msg_id,\n token,\n False,\n guild_id=guild_id,\n )\n return True\n except Exception:\n logger.exception(\n \"send text aggressive fallback failed\",\n )\n return False\n\n async def _send_images(\n self,\n image_urls: List[str],\n message_type: str,\n target_openid: Optional[str],\n msg_id: Optional[str],\n token: str,\n text_already_sent: bool,\n ) -> None:\n \"\"\"Upload and send images via QQ rich media API.\"\"\"\n if not image_urls or message_type not in (\"c2c\", \"group\"):\n return\n if not target_openid:\n return\n for image_url in image_urls:\n try:\n file_info = await _upload_media_async(\n self._http,\n token,\n target_openid,\n media_type=1,\n url=image_url,\n message_type=message_type,\n )\n if not file_info:\n logger.warning(\n f\"Failed to upload image, skipping: {image_url}\",\n )\n continue\n await _send_media_message_async(\n self._http,\n token,\n target_openid,\n file_info,\n msg_id if not text_already_sent else None,\n message_type=message_type,\n )\n logger.info(f\"Successfully sent image: {image_url}\")\n except Exception:\n logger.exception(f\"Failed to send image: {image_url}\")\n\n async def send(\n self,\n to_handle: str,\n text: str,\n meta: Optional[Dict[str, Any]] = None,\n ) -> None:\n \"\"\"Send one text via QQ HTTP API.\n Routes by meta or to_handle (group:/channel:/openid).\n \"\"\"\n if not self.enabled or not text.strip():\n return\n text = text.strip()\n meta = meta or {}\n use_markdown = _as_bool(\n meta.get(\"markdown_enabled\", self._markdown_enabled),\n )\n if not use_markdown:\n text, had_url = _sanitize_qq_text(text)\n if had_url:\n logger.info(\n \"qq send: stripped URL content for API compatibility\",\n )\n message_type = meta.get(\"message_type\")\n msg_id = meta.get(\"message_id\")\n sender_id = meta.get(\"sender_id\") or to_handle\n channel_id = meta.get(\"channel_id\")\n group_openid = meta.get(\"group_openid\")\n guild_id = meta.get(\"guild_id\")\n if message_type is None:\n if to_handle.startswith(\"group:\"):\n message_type = \"group\"\n group_openid = to_handle[6:]\n elif to_handle.startswith(\"channel:\"):\n message_type = \"guild\"\n channel_id = to_handle[8:]\n else:\n message_type = \"c2c\"\n try:\n token = await self._get_access_token_async()\n except Exception:\n logger.exception(\"get access_token failed\")\n return\n\n image_urls = _IMAGE_TAG_PATTERN.findall(text)\n clean_text = _IMAGE_TAG_PATTERN.sub(\"\", text).strip()\n\n text_sent = False\n if clean_text:\n text_sent = await self._send_text_with_fallback(\n message_type,\n sender_id,\n channel_id,\n group_openid,\n clean_text,\n msg_id,\n token,\n use_markdown,\n guild_id=guild_id,\n )\n\n target_openid = sender_id if message_type == \"c2c\" else group_openid\n await self._send_images(\n image_urls,\n message_type,\n target_openid,\n msg_id,\n token,\n text_sent,\n )\n\n _EXT_TYPE_MAP = {\n \".jpg\": \"image\",\n \".jpeg\": \"image\",\n \".png\": \"image\",\n \".gif\": \"image\",\n \".webp\": \"image\",\n \".bmp\": \"image\",\n \".mp4\": \"video\",\n \".avi\": \"video\",\n \".mov\": \"video\",\n \".mkv\": \"video\",\n \".webm\": \"video\",\n \".mpeg\": \"video\",\n \".mp3\": \"audio\",\n \".wav\": \"audio\",\n \".ogg\": \"audio\",\n \".m4a\": \"audio\",\n \".aac\": \"audio\",\n \".wma\": \"audio\",\n }\n\n def _resolve_attachment_type(\n self,\n att_type: str,\n file_name: str,\n ) -> str:\n \"\"\"Resolve attachment type from content_type or extension.\"\"\"\n if not att_type:\n ext = Path(file_name).suffix.lower()\n return self._EXT_TYPE_MAP.get(ext, \"file\")\n if att_type == \"voice\":\n return \"audio\"\n if att_type in (\"image\", \"video\", \"audio\", \"file\"):\n return att_type\n mime = att_type.split(\";\")[0].strip().lower()\n for prefix in (\"image/\", \"video/\", \"audio/\"):\n if mime.startswith(prefix):\n return prefix.rstrip(\"/\")\n return \"file\"\n\n def _download_attachment_sync(\n self,\n url: str,\n file_name: str,\n ) -> Optional[str]:\n \"\"\"Download attachment via event loop; return local path.\"\"\"\n loop = self._loop\n if not (loop and loop.is_running()):\n return url\n try:\n future = asyncio.run_coroutine_threadsafe(\n _download_qq_file(\n http_session=self._http,\n file_url=url,\n media_dir=self._media_dir,\n filename_hint=file_name,\n ),\n loop,\n )\n return future.result(timeout=30)\n except Exception:\n logger.exception(\"failed to download attachment\")\n return None\n\n @staticmethod\n def _make_content_part(\n resolved_type: str,\n local_path: str,\n file_name: str,\n ) -> Optional[OutgoingContentPart]:\n \"\"\"Build a typed content part from resolved type.\"\"\"\n if resolved_type == \"image\":\n return ImageContent(\n type=ContentType.IMAGE,\n image_url=local_path,\n )\n if resolved_type == \"video\":\n return VideoContent(\n type=ContentType.VIDEO,\n video_url=local_path,\n )\n if resolved_type == \"audio\":\n return AudioContent(\n type=ContentType.AUDIO,\n data=local_path,\n )\n if resolved_type == \"file\":\n return FileContent(\n type=ContentType.FILE,\n filename=file_name,\n file_url=local_path,\n )\n return None\n\n def _parse_qq_attachments(\n self,\n attachments: List[Dict[str, Any]],\n ) -> List[OutgoingContentPart]:\n \"\"\"Parse QQ message attachments to content parts.\"\"\"\n parts: List[OutgoingContentPart] = []\n if not attachments or not self._http:\n return parts\n for att in attachments:\n url = att.get(\"url\", \"\")\n file_name = att.get(\"filename\", \"\")\n if not url:\n continue\n att_type = att.get(\n \"content_type\",\n att.get(\"type\", \"\"),\n )\n resolved = self._resolve_attachment_type(\n att_type,\n file_name,\n )\n local_path = self._download_attachment_sync(\n url,\n file_name,\n )\n if not local_path:\n continue\n part = self._make_content_part(\n resolved,\n local_path,\n file_name,\n )\n if part:\n parts.append(part)\n return parts\n\n def build_agent_request_from_native(self, native_payload: Any) -> Any:\n \"\"\"Build AgentRequest from QQ native dict (runtime content_parts).\n\n Parses attachments from QQ messages and converts them to\n ImageContent, VideoContent, AudioContent, FileContent.\n \"\"\"\n payload = native_payload if isinstance(native_payload, dict) else {}\n channel_id = payload.get(\"channel_id\") or self.channel\n sender_id = payload.get(\"sender_id\") or \"\"\n content_parts = payload.get(\"content_parts\") or []\n meta = payload.get(\"meta\") or {}\n attachments = meta.get(\"attachments\") or []\n if attachments:\n media_parts = self._parse_qq_attachments(attachments)\n content_parts = list(content_parts) + media_parts\n session_id = self.resolve_session_id(sender_id, meta)\n return self.build_agent_request_from_user_content(\n channel_id=channel_id,\n sender_id=sender_id,\n session_id=session_id,\n content_parts=content_parts,\n channel_meta=meta,\n )\n\n # ------------------------------------------------------------------\n # WebSocket: message event handling\n # ------------------------------------------------------------------\n\n def _handle_msg_event(\n self,\n event_type: str,\n d: Dict[str, Any],\n ) -> None:\n \"\"\"Handle one WS message event via spec lookup.\"\"\"\n spec = _MESSAGE_EVENT_SPECS.get(event_type)\n if spec is None:\n return\n author = d.get(\"author\") or {}\n text = (d.get(\"content\") or \"\").strip()\n if not text and not d.get(\"attachments\"):\n return\n if self.bot_prefix and text.startswith(self.bot_prefix):\n return\n sender = \"\"\n for key in spec.sender_keys:\n sender = author.get(key) or \"\"\n if sender:\n break\n if not sender:\n return\n msg_id = d.get(\"id\", \"\")\n att = d.get(\"attachments\") or []\n meta: Dict[str, Any] = {\n \"message_type\": spec.message_type,\n \"message_id\": msg_id,\n \"sender_id\": sender,\n \"incoming_raw\": d,\n \"attachments\": att,\n }\n for key in spec.extra_meta_keys:\n meta[key] = d.get(key, \"\")\n native = {\n \"channel_id\": \"qq\",\n \"sender_id\": sender,\n \"content_parts\": [\n TextContent(type=ContentType.TEXT, text=text),\n ],\n \"meta\": meta,\n }\n request = self.build_agent_request_from_native(native)\n request.channel_meta = meta\n if self._enqueue is not None:\n self._enqueue(request)\n extra_vals = tuple(meta.get(k, \"\") for k in spec.extra_meta_keys)\n extra_str = \"\".join(\n f\" {k}={v}\" for k, v in zip(spec.extra_meta_keys, extra_vals)\n )\n logger.info(\n \"qq recv %s from=%s%s text=%r\",\n spec.message_type,\n sender,\n extra_str,\n text[:100],\n )\n\n # ------------------------------------------------------------------\n # WebSocket: payload dispatch\n # ------------------------------------------------------------------\n\n def _handle_ws_payload(\n self,\n payload: Dict[str, Any],\n ws: Any,\n token: str,\n state: _WSState,\n hb: _HeartbeatController,\n ) -> Optional[str]:\n \"\"\"Process one WS payload.\n\n Return \"break\" to exit loop, else None.\n \"\"\"\n op = payload.get(\"op\")\n d = payload.get(\"d\")\n s = payload.get(\"s\")\n t = payload.get(\"t\")\n if s is not None:\n state.last_seq = s\n\n if op == OP_HELLO:\n hi = d or {}\n interval = hi.get(\"heartbeat_interval\", 45000)\n if state.session_id and state.last_seq is not None:\n ws.send(\n json.dumps(\n {\n \"op\": OP_RESUME,\n \"d\": {\n \"token\": f\"QQBot {token}\",\n \"session_id\": state.session_id,\n \"seq\": state.last_seq,\n },\n },\n ),\n )\n else:\n intents = INTENT_PUBLIC_GUILD_MESSAGES | INTENT_GUILD_MEMBERS\n if state.identify_fail_count < 3:\n intents |= INTENT_DIRECT_MESSAGE | INTENT_GROUP_AND_C2C\n ws.send(\n json.dumps(\n {\n \"op\": OP_IDENTIFY,\n \"d\": {\n \"token\": f\"QQBot {token}\",\n \"intents\": intents,\n \"shard\": [0, 1],\n },\n },\n ),\n )\n hb.start(interval)\n return None\n\n if op == OP_DISPATCH:\n if t == \"READY\":\n state.session_id = (d or {}).get(\"session_id\")\n state.identify_fail_count = 0\n state.reconnect_attempts = 0\n state.last_connect_time = time.time()\n logger.info(\"qq ready session_id=%s\", state.session_id)\n elif t == \"RESUMED\":\n logger.info(\"qq session resumed\")\n elif t in _MESSAGE_EVENT_SPECS:\n self._handle_msg_event(t, d or {})\n return None\n\n if op == OP_HEARTBEAT_ACK:\n logger.debug(\"qq heartbeat ack\")\n return None\n\n if op == OP_RECONNECT:\n logger.info(\"qq server requested reconnect\")\n return \"break\"\n\n if op == OP_INVALID_SESSION:\n can_resume = d\n logger.error(\"qq invalid session can_resume=%s\", can_resume)\n if not can_resume:\n state.session_id = None\n state.last_seq = None\n state.identify_fail_count += 1\n state.should_refresh_token = True\n return \"break\"\n\n return None\n\n # ------------------------------------------------------------------\n # WebSocket: reconnect delay\n # ------------------------------------------------------------------\n\n def _compute_reconnect_delay(self, state: _WSState) -> float:\n \"\"\"Compute delay before next reconnect, updating state counters.\"\"\"\n elapsed = (\n time.time() - state.last_connect_time\n if state.last_connect_time\n else None\n )\n if elapsed is not None and elapsed < QUICK_DISCONNECT_THRESHOLD:\n state.quick_disconnect_count += 1\n if state.quick_disconnect_count >= MAX_QUICK_DISCONNECT_COUNT:\n state.session_id = None\n state.last_seq = None\n state.should_refresh_token = True\n state.quick_disconnect_count = 0\n state.reconnect_attempts = min(\n state.reconnect_attempts,\n len(RECONNECT_DELAYS) - 1,\n )\n return RATE_LIMIT_DELAY\n else:\n state.quick_disconnect_count = 0\n return RECONNECT_DELAYS[\n min(state.reconnect_attempts, len(RECONNECT_DELAYS) - 1)\n ]\n\n # ------------------------------------------------------------------\n # WebSocket: single connection attempt\n # ------------------------------------------------------------------\n\n def _ws_connect_once(\n self,\n state: _WSState,\n websocket: Any,\n ) -> bool:\n \"\"\"Run one WS connection.\n\n Return True to reconnect, False to stop.\n \"\"\"\n if self._stop_event.is_set():\n return False\n if state.should_refresh_token:\n self._clear_token_cache()\n state.should_refresh_token = False\n try:\n token = self._get_access_token_sync()\n url = _get_channel_url_sync(token)\n except Exception as e:\n logger.warning(\"qq get token/gateway failed: %s\", e)\n return True\n logger.info(\"qq connecting to %s\", url)\n try:\n ws = websocket.create_connection(url)\n except Exception as e:\n logger.warning(\"qq ws connect failed: %s\", e)\n return True\n\n hb = _HeartbeatController(ws, self._stop_event, state)\n try:\n while not self._stop_event.is_set():\n raw = ws.recv()\n if not raw:\n break\n action = self._handle_ws_payload(\n json.loads(raw),\n ws,\n token,\n state,\n hb,\n )\n if action == \"break\":\n break\n except websocket.WebSocketConnectionClosedException:\n pass\n except Exception as e:\n logger.exception(\"qq ws loop: %s\", e)\n finally:\n hb.stop()\n try:\n ws.close()\n except Exception:\n pass\n\n delay = self._compute_reconnect_delay(state)\n state.reconnect_attempts += 1\n if state.reconnect_attempts >= MAX_RECONNECT_ATTEMPTS:\n logger.error(\"qq max reconnect attempts reached\")\n return False\n logger.info(\n \"qq reconnecting in %ss (attempt %s)\",\n delay,\n state.reconnect_attempts,\n )\n self._stop_event.wait(timeout=delay)\n return not self._stop_event.is_set()\n\n # ------------------------------------------------------------------\n # WebSocket: main loop\n # ------------------------------------------------------------------\n\n def _run_ws_forever(self) -> None:\n try:\n import websocket\n except ImportError:\n logger.error(\n \"websocket-client not installed. pip install websocket-client\",\n )\n return\n state = _WSState()\n while self._ws_connect_once(state, websocket):\n pass\n self._stop_event.set()\n logger.info(\"qq ws thread stopped\")\n\n async def start(self) -> None:\n if not self.enabled:\n logger.debug(\"qq channel disabled by QQ_CHANNEL_ENABLED=0\")\n return\n if not self.app_id or not self.client_secret:\n raise RuntimeError(\n \"QQ_APP_ID and QQ_CLIENT_SECRET are required when \"\n \"channel is enabled.\",\n )\n self._loop = asyncio.get_running_loop()\n self._stop_event.clear()\n self._ws_thread = threading.Thread(\n target=self._run_ws_forever,\n daemon=True,\n )\n self._ws_thread.start()\n if self._http is None:\n self._http = aiohttp.ClientSession()\n\n async def stop(self) -> None:\n if not self.enabled:\n return\n self._stop_event.set()\n if self._ws_thread:\n self._ws_thread.join(timeout=8)\n if self._http is not None:\n await self._http.close()\n self._http = None\n" }, { "path": "src/copaw/app/channels/registry.py", "content": "# -*- coding: utf-8 -*-\n\"\"\"Channel registry: built-in + custom channels from working dir.\"\"\"\nfrom __future__ import annotations\n\nimport importlib\nimport logging\nimport sys\nimport threading\nfrom typing import TYPE_CHECKING\n\nfrom ...constant import CUSTOM_CHANNELS_DIR\nfrom .base import BaseChannel\n\nif TYPE_CHECKING:\n pass\n\nlogger = logging.getLogger(__name__)\n\n_BUILTIN_SPECS: dict[str, tuple[str, str]] = {\n \"imessage\": (\".imessage\", \"IMessageChannel\"),\n \"discord\": (\".discord_\", \"DiscordChannel\"),\n \"dingtalk\": (\".dingtalk\", \"DingTalkChannel\"),\n \"feishu\": (\".feishu\", \"FeishuChannel\"),\n \"qq\": (\".qq\", \"QQChannel\"),\n \"telegram\": (\".telegram\", \"TelegramChannel\"),\n \"mattermost\": (\".mattermost\", \"MattermostChannel\"),\n \"mqtt\": (\".mqtt\", \"MQTTChannel\"),\n \"console\": (\".console\", \"ConsoleChannel\"),\n \"matrix\": (\".matrix\", \"MatrixChannel\"),\n \"voice\": (\".voice\", \"VoiceChannel\"),\n \"wecom\": (\".wecom\", \"WecomChannel\"),\n \"xiaoyi\": (\".xiaoyi\", \"XiaoYiChannel\"),\n}\n\n# Required channels must load; failures are raised, not skipped.\n_REQUIRED_CHANNEL_KEYS: frozenset[str] = frozenset({\"console\"})\n\n_BUILTIN_CHANNEL_CACHE: dict[str, type[BaseChannel]] | None = None\n_BUILTIN_CHANNEL_CACHE_LOCK = threading.Lock()\n\n\ndef _load_builtin_channels() -> dict[str, type[BaseChannel]]:\n \"\"\"Load built-in channels safely.\n\n A single optional dependency failure should not break CLI startup.\n \"\"\"\n out: dict[str, type[BaseChannel]] = {}\n for key, (module_name, class_name) in _BUILTIN_SPECS.items():\n try:\n mod = importlib.import_module(module_name, package=__package__)\n cls = getattr(mod, class_name)\n if not (\n isinstance(cls, type)\n and issubclass(cls, BaseChannel)\n and cls is not BaseChannel\n ):\n raise TypeError(\n f\"{module_name}.{class_name} is not a BaseChannel subtype\",\n )\n except Exception:\n if key in _REQUIRED_CHANNEL_KEYS:\n logger.error(\n 'failed to load required built-in channel \"%s\"',\n key,\n exc_info=True,\n )\n raise\n logger.debug(\n \"built-in channel unavailable: %s\",\n key,\n exc_info=True,\n )\n continue\n out[key] = cls\n return out\n\n\ndef _get_cached_builtin_channels() -> dict[str, type[BaseChannel]]:\n \"\"\"Return cached built-in channels (loaded once per process).\"\"\"\n global _BUILTIN_CHANNEL_CACHE\n with _BUILTIN_CHANNEL_CACHE_LOCK:\n if _BUILTIN_CHANNEL_CACHE is None:\n _BUILTIN_CHANNEL_CACHE = _load_builtin_channels()\n return dict(_BUILTIN_CHANNEL_CACHE)\n\n\ndef clear_builtin_channel_cache() -> None:\n \"\"\"Reset built-in channel cache. Primarily for tests.\"\"\"\n global _BUILTIN_CHANNEL_CACHE\n with _BUILTIN_CHANNEL_CACHE_LOCK:\n _BUILTIN_CHANNEL_CACHE = None\n\n\ndef _discover_custom_channels() -> dict[str, type[BaseChannel]]:\n \"\"\"Load channel classes from CUSTOM_CHANNELS_DIR.\"\"\"\n out: dict[str, type[BaseChannel]] = {}\n if not CUSTOM_CHANNELS_DIR.is_dir():\n return out\n\n dir_str = str(CUSTOM_CHANNELS_DIR)\n if dir_str not in sys.path:\n sys.path.insert(0, dir_str)\n\n for path in sorted(CUSTOM_CHANNELS_DIR.iterdir()):\n if path.suffix == \".py\" and path.stem != \"__init__\":\n name = path.stem\n elif path.is_dir() and (path / \"__init__.py\").exists():\n name = path.name\n else:\n continue\n try:\n mod = importlib.import_module(name)\n except Exception:\n logger.exception(\"failed to load custom channel: %s\", name)\n continue\n for obj in vars(mod).values():\n if (\n isinstance(obj, type)\n and issubclass(obj, BaseChannel)\n and obj is not BaseChannel\n ):\n key = getattr(obj, \"channel\", None)\n if key:\n out[key] = obj\n logger.debug(\"custom channel registered: %s\", key)\n return out\n\n\nBUILTIN_CHANNEL_KEYS = frozenset(_BUILTIN_SPECS.keys())\n\n\ndef get_channel_registry() -> dict[str, type[BaseChannel]]:\n \"\"\"Built-in channel classes + custom channels from custom_channels/.\"\"\"\n out = _get_cached_builtin_channels()\n out.update(_discover_custom_channels())\n return out\n" }, { "path": "src/copaw/app/channels/renderer.py", "content": "# -*- coding: utf-8 -*-\n# pylint: disable=too-many-branches,too-many-statements\n\"\"\"\nPluggable message renderer: Message -> sendable parts (runtime Content).\nStyle/capabilities control markdown, emoji, code fence.\n\"\"\"\nfrom __future__ import annotations\n\nimport json\nimport logging\nfrom dataclasses import dataclass\nfrom typing import Any, List, Union\n\nfrom agentscope_runtime.engine.schemas.agent_schemas import (\n AudioContent,\n ContentType,\n FileContent,\n ImageContent,\n RefusalContent,\n TextContent,\n VideoContent,\n)\n\nlogger = logging.getLogger(__name__)\n\n# Same union as base.OutgoingContentPart (renderer must not import base).\n_OutgoingPart = Union[\n TextContent,\n ImageContent,\n VideoContent,\n AudioContent,\n FileContent,\n RefusalContent,\n]\n\n\n@dataclass\nclass RenderStyle:\n \"\"\"Channel capabilities for rendering (no hardcoded markdown/emoji).\"\"\"\n\n show_tool_details: bool = True\n supports_markdown: bool = True\n supports_code_fence: bool = True\n use_emoji: bool = True\n filter_tool_messages: bool = False\n filter_thinking: bool = False\n internal_tools: frozenset = frozenset()\n\n\ndef _fmt_tool_call(\n name: str,\n args_preview: str,\n style: RenderStyle,\n) -> str:\n if style.supports_markdown and style.use_emoji:\n return f\"🔧 **{name}**\\n```\\n{args_preview}\\n```\"\n if style.supports_markdown:\n return f\"**{name}**\\n```\\n{args_preview}\\n```\"\n if style.supports_code_fence:\n return f\"{name}\\n```\\n{args_preview}\\n```\"\n return f\"{name}: {args_preview}\"\n\n\ndef _fmt_tool_output_label(name: str, style: RenderStyle) -> str:\n if style.use_emoji:\n return f\"✅ **{name}**:\"\n if style.supports_markdown:\n return f\"**{name}**:\"\n return f\"{name}:\"\n\n\ndef _fmt_code_block(preview: str, style: RenderStyle) -> str:\n if style.supports_code_fence:\n return f\"\\n```\\n{preview}\\n```\"\n return f\"\\n{preview}\"\n\n\nclass MessageRenderer:\n \"\"\"\n Converts a Message (object=='message') into sendable parts.\n Style controls markdown/emoji/code fence; no hardcoded format.\n \"\"\"\n\n def __init__(self, style: RenderStyle | None = None):\n self.style = style or RenderStyle()\n\n def message_to_parts(self, message: Any) -> List[_OutgoingPart]:\n \"\"\"Convert Message to list of sendable parts (runtime Content).\"\"\"\n from agentscope_runtime.engine.schemas.agent_schemas import MessageType\n\n msg_type = getattr(message, \"type\", None)\n content = getattr(message, \"content\", None) or []\n s = self.style\n\n if s.filter_thinking and msg_type == MessageType.REASONING:\n return []\n\n logger.debug(\n \"renderer message_to_parts: msg_type=%s content_len=%s\",\n msg_type,\n len(content),\n )\n\n def _parts_for_tool_call(content_list: list) -> List[_OutgoingPart]:\n out: List[_OutgoingPart] = []\n for c in content_list:\n if getattr(c, \"type\", None) != ContentType.DATA:\n continue\n data = getattr(c, \"data\", None) or {}\n name = data.get(\"name\") or \"tool\"\n if s.show_tool_details:\n args = data.get(\"arguments\") or \"{}\"\n args_preview = (\n args[:200] + \"...\" if len(args) > 200 else args\n )\n else:\n args_preview = \"...\"\n text = _fmt_tool_call(name, args_preview, s)\n out.append(TextContent(text=text))\n return out\n\n def _blocks_to_parts(blocks: list) -> List[_OutgoingPart]:\n result: List[_OutgoingPart] = []\n for b in blocks:\n if not isinstance(b, dict):\n continue\n btype = b.get(\"type\")\n if btype == \"text\" and b.get(\"text\"):\n result.append(TextContent(text=b[\"text\"]))\n continue\n if btype in (\"image\", \"audio\", \"video\", \"file\"):\n src = b.get(\"source\") or {}\n stype = src.get(\"type\")\n url = None\n if stype == \"url\" and src.get(\"url\"):\n url = src[\"url\"]\n elif stype == \"base64\" and src.get(\"data\"):\n mt = (\n src.get(\"media_type\") or \"application/octet-stream\"\n )\n url = f\"data:{mt};base64,{src['data']}\"\n if url:\n if btype == \"image\":\n result.append(ImageContent(image_url=url))\n elif btype == \"video\":\n result.append(VideoContent(video_url=url))\n elif btype == \"audio\":\n result.append(\n AudioContent(\n data=url,\n format=b.get(\"media_type\"),\n ),\n )\n else:\n result.append(\n FileContent(\n file_url=url,\n filename=b.get(\"filename\"),\n ),\n )\n if btype == \"thinking\" and b.get(\"thinking\"):\n if not s.filter_thinking:\n result.append(TextContent(text=b[\"thinking\"]))\n return result\n\n def _parts_for_tool_output(content_list: list) -> List[_OutgoingPart]:\n out: List[_OutgoingPart] = []\n for c in content_list:\n if getattr(c, \"type\", None) != ContentType.DATA:\n continue\n data = getattr(c, \"data\", None) or {}\n name = data.get(\"name\") or \"tool\"\n output = data.get(\"output\", \"\")\n\n try:\n output = json.loads(output)\n except json.JSONDecodeError:\n pass\n\n if isinstance(output, list):\n block_parts = _blocks_to_parts(output)\n if s.show_tool_details:\n out.append(\n TextContent(\n text=_fmt_tool_output_label(name, s),\n ),\n )\n out.extend(block_parts)\n else:\n media_types = (\n ContentType.IMAGE,\n ContentType.AUDIO,\n ContentType.VIDEO,\n ContentType.FILE,\n )\n # Internal tools (e.g. view_image) produce\n # media for the LLM, not the user — skip.\n media_parts = (\n []\n if name in s.internal_tools\n else [\n p\n for p in block_parts\n if getattr(p, \"type\", None) in media_types\n ]\n )\n out.extend(media_parts)\n if not media_parts:\n out.append(\n TextContent(\n text=_fmt_tool_output_label(name, s)\n + _fmt_code_block(\"...\", s),\n ),\n )\n continue\n\n if isinstance(output, str):\n preview = (\n (output[:500] + \"...\" if len(output) > 500 else output)\n if s.show_tool_details\n else \"...\"\n )\n out.append(\n TextContent(\n text=_fmt_tool_output_label(name, s)\n + _fmt_code_block(preview, s),\n ),\n )\n continue\n\n if output is not None:\n raw = str(output)\n preview = (\n (raw[:500] + \"...\" if len(raw) > 500 else raw)\n if s.show_tool_details\n else \"...\"\n )\n out.append(\n TextContent(\n text=_fmt_tool_output_label(name, s)\n + _fmt_code_block(preview, s),\n ),\n )\n return out\n\n if msg_type in (\n MessageType.FUNCTION_CALL,\n MessageType.PLUGIN_CALL,\n MessageType.MCP_TOOL_CALL,\n ):\n if s.filter_tool_messages:\n return []\n parts = _parts_for_tool_call(content)\n if not parts:\n parts = [TextContent(text=f\"[{msg_type}]\")]\n return parts\n\n if msg_type in (\n MessageType.FUNCTION_CALL_OUTPUT,\n MessageType.PLUGIN_CALL_OUTPUT,\n MessageType.MCP_TOOL_CALL_OUTPUT,\n ):\n if s.filter_tool_messages:\n media_types = (\n ContentType.IMAGE,\n ContentType.AUDIO,\n ContentType.VIDEO,\n ContentType.FILE,\n )\n media_parts = []\n for c in content:\n if getattr(c, \"type\", None) != ContentType.DATA:\n continue\n data = getattr(c, \"data\", None) or {}\n name = data.get(\"name\") or \"tool\"\n if name in s.internal_tools:\n continue\n output = data.get(\"output\", \"\")\n try:\n output = json.loads(output)\n except json.JSONDecodeError:\n pass\n if isinstance(output, list):\n block_parts = _blocks_to_parts(output)\n media_parts.extend(\n [\n p\n for p in block_parts\n if getattr(p, \"type\", None) in media_types\n ],\n )\n return media_parts\n parts = _parts_for_tool_output(content)\n if not parts:\n parts = [TextContent(text=f\"[{msg_type}]\")]\n return parts\n\n result: List[_OutgoingPart] = []\n for c in content:\n ctype = getattr(c, \"type\", None)\n if ctype == ContentType.TEXT and getattr(c, \"text\", None):\n result.append(TextContent(text=c.text))\n elif ctype == ContentType.REFUSAL and getattr(c, \"refusal\", None):\n result.append(RefusalContent(refusal=c.refusal))\n elif ctype == ContentType.IMAGE and getattr(c, \"image_url\", None):\n result.append(ImageContent(image_url=c.image_url))\n elif ctype == ContentType.VIDEO and getattr(c, \"video_url\", None):\n result.append(VideoContent(video_url=c.video_url))\n elif ctype == ContentType.AUDIO:\n data = getattr(c, \"data\", None)\n fmt = getattr(c, \"format\", None)\n if data:\n result.append(AudioContent(data=data, format=fmt))\n elif ctype == ContentType.FILE:\n result.append(\n FileContent(\n file_url=getattr(c, \"file_url\", None),\n file_id=getattr(c, \"file_id\", None),\n filename=getattr(c, \"filename\", None),\n file_data=getattr(c, \"file_data\", None),\n ),\n )\n elif ctype == ContentType.DATA and getattr(c, \"data\", None):\n data = c.data\n if isinstance(data, dict):\n name = data.get(\"name\")\n output = data.get(\"output\")\n args = data.get(\"arguments\")\n if name is not None and (\n output is not None or args is not None\n ):\n if not s.show_tool_details:\n preview = \"...\"\n elif output is not None:\n preview = str(output)[:500] + (\n \"...\" if len(str(output)) > 500 else \"\"\n )\n else:\n preview = str(args)[:200] + (\n \"...\" if len(str(args)) > 200 else \"\"\n )\n result.append(\n TextContent(\n text=_fmt_tool_output_label(name, s)\n + _fmt_code_block(preview, s),\n ),\n )\n if not result and msg_type:\n result = [TextContent(text=f\"[Message type: {msg_type}]\")]\n return result\n\n def parts_to_text(\n self,\n parts: List[_OutgoingPart],\n prefix: str = \"\",\n ) -> str:\n \"\"\"Merge text/refusal parts and append media as fallback text.\"\"\"\n text_parts: List[str] = []\n for p in parts:\n t = getattr(p, \"type\", None)\n if t == ContentType.TEXT and getattr(p, \"text\", None):\n text_parts.append(p.text or \"\")\n elif t == ContentType.REFUSAL and getattr(p, \"refusal\", None):\n text_parts.append(p.refusal or \"\")\n body = \"\\n\".join(text_parts) if text_parts else \"\"\n if prefix and body:\n body = prefix + body\n for p in parts:\n t = getattr(p, \"type\", None)\n if t == ContentType.IMAGE and getattr(p, \"image_url\", None):\n body += f\"\\n[Image: {p.image_url}]\"\n elif t == ContentType.VIDEO and getattr(p, \"video_url\", None):\n body += f\"\\n[Video: {p.video_url}]\"\n elif t == ContentType.FILE:\n file_ref = getattr(p, \"file_url\", None) or getattr(\n p,\n \"file_id\",\n None,\n )\n body += f\"\\n[File: {file_ref}]\"\n elif t == ContentType.AUDIO and getattr(p, \"data\", None):\n body += \"\\n[Audio]\"\n return body.strip()\n" }, { "path": "src/copaw/app/channels/schema.py", "content": "# -*- coding: utf-8 -*-\n\"\"\"\nChannel schema: channel type identifiers, routing (ChannelAddress),\nand conversion protocol.\n\"\"\"\nfrom __future__ import annotations\n\nfrom dataclasses import dataclass\nfrom typing import Any, Dict, Optional, Protocol, runtime_checkable\n\n\n@dataclass\nclass ChannelAddress:\n \"\"\"\n Unified routing for send: kind + id + extra.\n Replaces ad-hoc meta keys (channel_id, user_id, session_webhook, etc.).\n \"\"\"\n\n kind: str # \"dm\" | \"channel\" | \"webhook\" | \"console\" | ...\n id: str\n extra: Optional[Dict[str, Any]] = None\n\n def to_handle(self) -> str:\n \"\"\"String handle for to_handle (e.g. discord:ch:123).\"\"\"\n if self.extra and \"to_handle\" in self.extra:\n return str(self.extra[\"to_handle\"])\n return f\"{self.kind}:{self.id}\"\n\n\n# Built-in channel type identifiers. Plugin channels use arbitrary str keys.\nBUILTIN_CHANNEL_TYPES = (\n \"imessage\",\n \"discord\",\n \"dingtalk\",\n \"feishu\",\n \"qq\",\n \"telegram\",\n \"mqtt\",\n \"console\",\n \"voice\",\n \"xiaoyi\",\n)\n\n# ChannelType is str to allow plugin channels; built-in set above.\nChannelType = str\n\n# Default channel when none is specified (runner / config).\nDEFAULT_CHANNEL: ChannelType = \"console\"\n\n\n@runtime_checkable\nclass ChannelMessageConverter(Protocol):\n \"\"\"\n Protocol for channel message conversion.\n Channels convert native payloads to AgentRequest and send responses.\n \"\"\"\n\n def build_agent_request_from_native(self, native_payload: Any) -> Any:\n \"\"\"\n Convert this channel's native message payload to AgentRequest.\n Use runtime Message and Content types; no intermediate envelope.\n \"\"\"\n\n async def send_response(\n self,\n to_handle: str,\n response: Any,\n meta: Optional[dict] = None,\n ) -> None:\n \"\"\"Convert AgentResponse to channel reply and send.\"\"\"\n" }, { "path": "src/copaw/app/channels/telegram/__init__.py", "content": "# -*- coding: utf-8 -*-\n\"\"\"Telegram channel package.\"\"\"\nfrom .channel import TelegramChannel\n\n__all__ = [\"TelegramChannel\"]\n" }, { "path": "src/copaw/app/channels/telegram/channel.py", "content": "# -*- coding: utf-8 -*-\n# pylint: disable=too-many-branches\n\"\"\"Telegram channel: Bot API with polling; receive/send via chat_id.\"\"\"\n\nfrom __future__ import annotations\n\nimport asyncio\nimport html\nimport logging\nimport re\nimport uuid\nfrom pathlib import Path\nfrom typing import Any, Optional, Union\n\nfrom telegram import BotCommand\nfrom telegram.constants import ParseMode\nfrom telegram.error import (\n BadRequest,\n Forbidden,\n InvalidToken,\n NetworkError,\n RetryAfter,\n TimedOut,\n)\n\nfrom agentscope_runtime.engine.schemas.agent_schemas import (\n TextContent,\n ImageContent,\n VideoContent,\n AudioContent,\n FileContent,\n ContentType,\n)\n\nfrom ....config.config import TelegramConfig as TelegramChannelConfig\nfrom ....constant import WORKING_DIR\nfrom .format_html import markdown_to_telegram_html\nfrom ..utils import file_url_to_local_path\nfrom ..base import (\n BaseChannel,\n OnReplySent,\n ProcessHandler,\n OutgoingContentPart,\n)\n\nlogger = logging.getLogger(__name__)\n\nTELEGRAM_MAX_MESSAGE_LENGTH = 4096\nTELEGRAM_SEND_CHUNK_SIZE = 4000\nTELEGRAM_MAX_FILE_SIZE_BYTES = (\n 50 * 1024 * 1024\n) # 50 MB – Telegram bot upload limit\n\n_DEFAULT_MEDIA_DIR = WORKING_DIR / \"media\" / \"telegram\"\n_TYPING_TIMEOUT_S = 180\n\n_RECONNECT_INITIAL_S = 2.0\n_RECONNECT_MAX_S = 30.0\n_RECONNECT_FACTOR = 1.8\n_POLL_WATCHDOG_INTERVAL_S = 30\n\n_MEDIA_ATTRS: list[tuple[str, type, Any, str]] = [\n (\"document\", FileContent, ContentType.FILE, \"file_url\"),\n (\"video\", VideoContent, ContentType.VIDEO, \"video_url\"),\n (\"voice\", AudioContent, ContentType.AUDIO, \"data\"),\n (\"audio\", AudioContent, ContentType.AUDIO, \"data\"),\n]\n\n\nclass _FileTooLargeError(Exception):\n \"\"\"Raised when a local media file exceeds Telegram's upload size limit.\"\"\"\n\n\nclass _MediaFileUnavailableError(Exception):\n \"\"\"Raised when a media file cannot be found or resolved.\"\"\"\n\n\nasync def _download_telegram_file(\n *,\n bot: Any,\n file_id: str,\n media_dir: Path,\n filename_hint: str = \"\",\n) -> Optional[str]:\n \"\"\"Download a Telegram file to local media_dir; return local path.\n\n Never exposes the bot token in the returned path.\n \"\"\"\n try:\n from telegram.error import TelegramError\n\n tg_file = await bot.get_file(file_id)\n except TelegramError:\n logger.exception(\"telegram: get_file failed for file_id=%s\", file_id)\n return None\n\n try:\n media_dir.mkdir(parents=True, exist_ok=True)\n suffix = \"\"\n file_path = (getattr(tg_file, \"file_path\", None) or \"\").strip()\n if file_path:\n suffix = Path(file_path).suffix\n if filename_hint and not suffix:\n suffix = Path(filename_hint).suffix\n local_name = f\"{uuid.uuid4().hex[:12]}{suffix or '.bin'}\"\n local_path = media_dir / local_name\n await tg_file.download_to_drive(str(local_path))\n return str(local_path)\n except Exception:\n logger.exception(\"telegram: download failed for file_id=%s\", file_id)\n return None\n\n\nasync def _resolve_telegram_file_url(\n *,\n bot: Any,\n file_id: str,\n bot_token: str,\n) -> str:\n \"\"\"Resolve the remote URL for a Telegram file.\n\n Returns the file URL (either Telegram API URL or external URL).\n Never exposes the bot token in the returned URL.\n \"\"\"\n try:\n from telegram.error import TelegramError\n\n tg_file = await bot.get_file(file_id)\n except TelegramError:\n logger.exception(\"telegram: get_file failed for file_id=%s\", file_id)\n return \"\"\n file_path = getattr(tg_file, \"file_path\", None) or \"\"\n if not file_path:\n return \"\"\n if file_path.startswith(\"http\"):\n return file_path\n return f\"https://api.telegram.org/file/bot{bot_token}/{file_path}\"\n\n\nasync def _build_content_parts_from_message(\n update: Any,\n *,\n bot: Any,\n media_dir: Path,\n) -> tuple[list, bool, bool]:\n \"\"\"Build runtime content_parts from Telegram message.\n\n Returns (content_parts, has_bot_command, is_bot_mentioned).\n \"\"\"\n message = getattr(update, \"message\", None) or getattr(\n update,\n \"edited_message\",\n )\n if not message:\n return [], False, False\n\n content_parts: list[Any] = []\n text = (\n getattr(message, \"text\", None) or getattr(message, \"caption\") or \"\"\n ).strip()\n\n entities = (\n getattr(message, \"entities\", None)\n or getattr(message, \"caption_entities\", None)\n or []\n )\n has_bot_command = False\n is_bot_mentioned = False\n bot_username = getattr(bot, \"username\", None) or \"\"\n\n if entities:\n for entity in entities:\n etype = getattr(entity, \"type\", None)\n if etype == \"bot_command\":\n has_bot_command = True\n elif etype == \"mention\" and bot_username:\n offset = getattr(entity, \"offset\", 0)\n length = getattr(entity, \"length\", 0)\n mentioned = text[offset : offset + length]\n if mentioned.lower() == f\"@{bot_username.lower()}\":\n is_bot_mentioned = True\n elif etype == \"text_mention\":\n euser = getattr(entity, \"user\", None)\n if euser and str(\n getattr(euser, \"id\", \"\"),\n ) == str(bot.id):\n is_bot_mentioned = True\n\n if is_bot_mentioned and bot_username and text:\n text = re.sub(\n rf\"@{re.escape(bot_username)}\\b\",\n \"\",\n text,\n flags=re.IGNORECASE,\n ).strip()\n\n if text:\n content_parts.append(TextContent(type=ContentType.TEXT, text=text))\n\n photo = getattr(message, \"photo\", None)\n if photo and len(photo) > 0:\n largest = photo[-1]\n file_id = getattr(largest, \"file_id\", None)\n if file_id:\n local_path = await _download_telegram_file(\n bot=bot,\n file_id=file_id,\n media_dir=media_dir,\n filename_hint=\"photo.jpg\",\n )\n if local_path:\n file_url = Path(local_path).resolve().as_uri()\n content_parts.append(\n ImageContent(type=ContentType.IMAGE, image_url=file_url),\n )\n\n for attr_name, content_cls, content_type, url_field in _MEDIA_ATTRS:\n media_obj = getattr(message, attr_name, None)\n if not media_obj:\n continue\n file_id = getattr(media_obj, \"file_id\", None)\n if not file_id:\n continue\n file_name = getattr(media_obj, \"file_name\", None) or attr_name\n local_path = await _download_telegram_file(\n bot=bot,\n file_id=file_id,\n media_dir=media_dir,\n filename_hint=file_name,\n )\n if local_path:\n file_url = Path(local_path).resolve().as_uri()\n content_parts.append(\n content_cls(type=content_type, **{url_field: file_url}),\n )\n\n return content_parts, has_bot_command, is_bot_mentioned\n\n\ndef _message_meta(update: Any) -> dict:\n \"\"\"Extract chat_id, user_id, etc. from Telegram update.\"\"\"\n message = getattr(update, \"message\", None) or getattr(\n update,\n \"edited_message\",\n )\n if not message:\n return {}\n chat = getattr(message, \"chat\", None)\n user = getattr(message, \"from_user\", None)\n chat_id = str(getattr(chat, \"id\", \"\")) if chat else \"\"\n user_id = str(getattr(user, \"id\", \"\")) if user else \"\"\n username = (getattr(user, \"username\", None) or \"\") if user else \"\"\n chat_type = getattr(chat, \"type\", \"\") if chat else \"\"\n return {\n \"chat_id\": chat_id,\n \"user_id\": user_id,\n \"username\": username,\n \"message_id\": str(getattr(message, \"message_id\", \"\")),\n \"is_group\": chat_type in (\"group\", \"supergroup\", \"channel\"),\n \"message_thread_id\": getattr(message, \"message_thread_id\", None),\n }\n\n\nclass TelegramChannel(BaseChannel):\n \"\"\"Telegram channel: Bot API polling; session_id = telegram:{chat_id}.\"\"\"\n\n channel = \"telegram\"\n uses_manager_queue = True\n\n def __init__(\n self,\n process: ProcessHandler,\n enabled: bool,\n bot_token: str,\n http_proxy: str,\n http_proxy_auth: str,\n bot_prefix: str,\n on_reply_sent: OnReplySent = None,\n show_tool_details: bool = True,\n media_dir: str = \"\",\n workspace_dir: Path | None = None,\n show_typing: bool = True,\n filter_tool_messages: bool = False,\n filter_thinking: bool = False,\n dm_policy: str = \"open\",\n group_policy: str = \"open\",\n allow_from: Optional[list] = None,\n deny_message: str = \"\",\n require_mention: bool = False,\n ):\n super().__init__(\n process,\n on_reply_sent=on_reply_sent,\n show_tool_details=show_tool_details,\n filter_tool_messages=filter_tool_messages,\n filter_thinking=filter_thinking,\n dm_policy=dm_policy,\n group_policy=group_policy,\n allow_from=allow_from,\n deny_message=deny_message,\n require_mention=require_mention,\n )\n self.enabled = enabled\n self._bot_token = bot_token\n self._http_proxy = http_proxy or \"\"\n self._http_proxy_auth = http_proxy_auth or \"\"\n self.bot_prefix = bot_prefix\n self._media_dir = (\n Path(media_dir).expanduser() if media_dir else _DEFAULT_MEDIA_DIR\n )\n self._workspace_dir = (\n Path(workspace_dir).expanduser() if workspace_dir else None\n )\n self._show_typing = show_typing\n self._typing_tasks: dict[str, asyncio.Task] = {}\n self._task: Optional[asyncio.Task] = None\n self._application = None\n if self.enabled and self._bot_token:\n try:\n self._application = self._build_application()\n logger.info(\n \"telegram: channel initialized (polling will start)\",\n )\n except Exception:\n logger.exception(\"telegram: failed to build application\")\n self._application = None\n else:\n if self.enabled and not self._bot_token:\n logger.info(\"telegram: channel disabled (bot_token empty)\")\n elif not self.enabled:\n logger.debug(\n \"telegram: channel disabled (enabled=false in config)\",\n )\n\n def _build_application(self):\n from telegram import Update\n from telegram.ext import (\n Application,\n ContextTypes,\n MessageHandler,\n filters,\n )\n\n def proxy_url() -> Optional[str]:\n if not self._http_proxy:\n return None\n if self._http_proxy_auth:\n if \"://\" in self._http_proxy:\n prefix, rest = self._http_proxy.split(\"://\", 1)\n return f\"{prefix}://{self._http_proxy_auth}@{rest}\"\n return f\"http://{self._http_proxy_auth}@{self._http_proxy}\"\n return self._http_proxy\n\n builder = Application.builder().token(self._bot_token)\n proxy = proxy_url()\n if proxy:\n builder = builder.proxy(proxy).get_updates_proxy(proxy)\n\n app = builder.build()\n\n async def handle_message(\n update: Update,\n context: ContextTypes.DEFAULT_TYPE,\n ) -> None:\n if not update.message and not getattr(\n update,\n \"edited_message\",\n None,\n ):\n return\n (\n content_parts,\n has_bot_command,\n is_bot_mentioned,\n ) = await _build_content_parts_from_message(\n update,\n bot=context.bot,\n media_dir=self._media_dir,\n )\n if not content_parts:\n logger.debug(\"telegram: ignore non-content message\")\n return\n meta = _message_meta(update)\n if has_bot_command:\n meta[\"has_bot_command\"] = True\n if is_bot_mentioned:\n meta[\"bot_mentioned\"] = True\n chat_id = meta.get(\"chat_id\", \"\")\n user = getattr(\n update.message or getattr(update, \"edited_message\"),\n \"from_user\",\n None,\n )\n sender_id = str(getattr(user, \"id\", \"\")) if user else chat_id\n is_group = meta.get(\"is_group\", False)\n\n allowed, error_msg = self._check_allowlist(\n sender_id,\n is_group,\n )\n if not allowed:\n logger.info(\n \"telegram allowlist blocked: sender=%s is_group=%s\",\n sender_id,\n is_group,\n )\n try:\n await context.bot.send_message(\n chat_id=chat_id,\n text=error_msg,\n )\n except Exception:\n logger.debug(\n \"telegram reject failed chat_id=%s\",\n chat_id,\n )\n return\n\n if not self._check_group_mention(is_group, meta):\n return\n\n native = {\n \"channel_id\": self.channel,\n \"sender_id\": sender_id,\n \"content_parts\": content_parts,\n \"meta\": meta,\n }\n if self._enqueue is not None:\n self._start_typing(chat_id)\n self._enqueue(native)\n else:\n logger.warning(\"telegram: _enqueue not set, message dropped\")\n\n app.add_handler(MessageHandler(filters.ALL, handle_message))\n return app\n\n def _apply_no_text_debounce(\n self,\n session_id: str,\n content_parts: list[Any],\n ) -> tuple[bool, list[Any]]:\n \"\"\"Process media-only Telegram messages without waiting for text.\"\"\"\n has_media = any(\n getattr(part, \"type\", None)\n not in (ContentType.TEXT, ContentType.REFUSAL)\n for part in content_parts\n )\n if has_media:\n pending = self._pending_content_by_session.pop(session_id, [])\n return True, pending + list(content_parts)\n return super()._apply_no_text_debounce(session_id, content_parts)\n\n @classmethod\n def from_env(\n cls,\n process: ProcessHandler,\n on_reply_sent: OnReplySent = None,\n ) -> \"TelegramChannel\":\n import os\n\n allow_from_env = os.getenv(\"TELEGRAM_ALLOW_FROM\", \"\")\n allow_from = (\n [s.strip() for s in allow_from_env.split(\",\") if s.strip()]\n if allow_from_env\n else []\n )\n return cls(\n process=process,\n enabled=os.getenv(\"TELEGRAM_CHANNEL_ENABLED\", \"0\") == \"1\",\n bot_token=os.getenv(\"TELEGRAM_BOT_TOKEN\", \"\"),\n http_proxy=os.getenv(\"TELEGRAM_HTTP_PROXY\", \"\"),\n http_proxy_auth=os.getenv(\"TELEGRAM_HTTP_PROXY_AUTH\", \"\"),\n bot_prefix=os.getenv(\"TELEGRAM_BOT_PREFIX\", \"\"),\n on_reply_sent=on_reply_sent,\n show_typing=os.getenv(\"TELEGRAM_SHOW_TYPING\", \"1\") == \"1\",\n dm_policy=os.getenv(\"TELEGRAM_DM_POLICY\", \"open\"),\n group_policy=os.getenv(\"TELEGRAM_GROUP_POLICY\", \"open\"),\n allow_from=allow_from,\n deny_message=os.getenv(\"TELEGRAM_DENY_MESSAGE\", \"\"),\n require_mention=os.getenv(\"TELEGRAM_REQUIRE_MENTION\", \"0\") == \"1\",\n )\n\n @classmethod\n def from_config(\n cls,\n process: ProcessHandler,\n config: Union[TelegramChannelConfig, dict],\n on_reply_sent: OnReplySent = None,\n show_tool_details: bool = True,\n filter_tool_messages: bool = False,\n filter_thinking: bool = False,\n workspace_dir: Path | None = None,\n ) -> \"TelegramChannel\":\n if isinstance(config, dict):\n c = config\n else:\n c = config.model_dump()\n\n def _get_str(key: str) -> str:\n return (c.get(key) or \"\").strip()\n\n show_typing = c.get(\"show_typing\")\n if show_typing is None:\n show_typing = True\n\n return cls(\n process=process,\n enabled=bool(c.get(\"enabled\", False)),\n bot_token=_get_str(\"bot_token\"),\n http_proxy=_get_str(\"http_proxy\"),\n http_proxy_auth=_get_str(\"http_proxy_auth\"),\n bot_prefix=_get_str(\"bot_prefix\"),\n on_reply_sent=on_reply_sent,\n show_tool_details=show_tool_details,\n filter_tool_messages=filter_tool_messages,\n filter_thinking=filter_thinking,\n workspace_dir=workspace_dir,\n show_typing=show_typing,\n dm_policy=c.get(\"dm_policy\") or \"open\",\n group_policy=c.get(\"group_policy\") or \"open\",\n allow_from=c.get(\"allow_from\") or [],\n deny_message=c.get(\"deny_message\") or \"\",\n require_mention=c.get(\"require_mention\", False),\n )\n\n def _chunk_text(self, text: str) -> list[str]:\n \"\"\"Split text into chunks under Telegram's message length limit.\"\"\"\n if not text or len(text) <= TELEGRAM_SEND_CHUNK_SIZE:\n return [text] if text else []\n chunks: list[str] = []\n rest = text\n while rest:\n if len(rest) <= TELEGRAM_SEND_CHUNK_SIZE:\n chunks.append(rest)\n break\n chunk = rest[:TELEGRAM_SEND_CHUNK_SIZE]\n last_nl = chunk.rfind(\"\\n\")\n if last_nl > TELEGRAM_SEND_CHUNK_SIZE // 2:\n chunk = chunk[: last_nl + 1]\n else:\n last_space = chunk.rfind(\" \")\n if last_space > TELEGRAM_SEND_CHUNK_SIZE // 2:\n chunk = chunk[: last_space + 1]\n chunks.append(chunk)\n rest = rest[len(chunk) :].lstrip(\"\\n \")\n return chunks\n\n async def _send_chat_action(\n self,\n chat_id: str,\n action: str = \"typing\",\n ) -> None:\n \"\"\"Send chat action (typing, uploading_photo, etc.) to Telegram.\"\"\"\n if not self.enabled or not self._application:\n return\n bot = self._application.bot\n if not bot:\n return\n try:\n await bot.send_chat_action(chat_id=chat_id, action=action)\n except Exception:\n logger.debug(\n \"telegram send_chat_action failed for chat_id=%s\",\n chat_id,\n )\n\n def _start_typing(self, chat_id: str) -> None:\n \"\"\"Start the typing indicator loop for a chat.\"\"\"\n if not self._show_typing:\n return\n self._stop_typing(chat_id)\n self._typing_tasks[chat_id] = asyncio.create_task(\n self._typing_loop(chat_id),\n )\n\n def _stop_typing(self, chat_id: str) -> None:\n \"\"\"Stop the typing indicator for a chat.\"\"\"\n task = self._typing_tasks.pop(chat_id, None)\n if task and not task.done():\n task.cancel()\n\n async def _typing_loop(self, chat_id: str) -> None:\n \"\"\"Repeatedly send 'typing' action every 4s until cancelled.\"\"\"\n try:\n deadline = asyncio.get_event_loop().time() + _TYPING_TIMEOUT_S\n while self._application:\n await self._send_chat_action(chat_id, \"typing\")\n await asyncio.sleep(4)\n if asyncio.get_event_loop().time() >= deadline:\n break\n except asyncio.CancelledError:\n pass\n finally:\n if self._typing_tasks.get(chat_id) is asyncio.current_task():\n self._typing_tasks.pop(chat_id, None)\n\n async def send(\n self,\n to_handle: str,\n text: str,\n meta: Optional[dict] = None,\n ) -> None:\n \"\"\"Send text to chat_id (to_handle or meta['chat_id']).\"\"\"\n if not self.enabled or not self._application:\n return\n if meta is None:\n meta = {}\n chat_id = meta.get(\"chat_id\") or to_handle\n if not chat_id:\n logger.warning(\"telegram send: no chat_id in to_handle or meta\")\n return\n bot = self._application.bot\n if not bot:\n return\n message_thread_id = meta.get(\"message_thread_id\")\n self._stop_typing(chat_id)\n chunks = self._chunk_text(text)\n for chunk in chunks:\n html_chunk = markdown_to_telegram_html(chunk)\n try:\n kwargs = {\n \"chat_id\": chat_id,\n \"text\": html_chunk,\n \"parse_mode\": ParseMode.HTML,\n }\n if message_thread_id is not None:\n kwargs[\"message_thread_id\"] = message_thread_id\n await bot.send_message(**kwargs)\n except BadRequest as exc:\n logger.warning(\n \"telegram HTML send failed, trying plain text: %s\",\n exc,\n )\n try:\n plain_chunk = html.unescape(\n re.sub(r\"<[^>]+>\", \"\", html_chunk),\n )\n kwargs = {\n \"chat_id\": chat_id,\n \"text\": plain_chunk,\n }\n if message_thread_id is not None:\n kwargs[\"message_thread_id\"] = message_thread_id\n await bot.send_message(**kwargs)\n except Exception:\n logger.exception(\"telegram send_message fallback failed\")\n return\n except Exception:\n logger.exception(\"telegram send_message failed\")\n return\n\n async def send_media( # pylint: disable=too-many-statements\n self,\n to_handle: str,\n part: OutgoingContentPart,\n meta: Optional[dict] = None,\n ) -> None:\n \"\"\"Send a media part (image, video, audio, file) to chat_id.\"\"\"\n if not self.enabled or not self._application:\n return\n meta = meta or {}\n chat_id = meta.get(\"chat_id\") or to_handle\n if not chat_id:\n logger.warning(\n \"telegram send_media: no chat_id in to_handle or meta\",\n )\n return\n bot = self._application.bot\n if not bot:\n return\n message_thread_id = meta.get(\"message_thread_id\")\n self._stop_typing(chat_id)\n\n part_type = getattr(part, \"type\", None)\n try:\n if part_type == ContentType.IMAGE:\n image_url = getattr(part, \"image_url\", None)\n await self._send_media_value(\n bot=bot,\n chat_id=chat_id,\n value=image_url,\n method_name=\"send_photo\",\n payload_name=\"photo\",\n message_thread_id=message_thread_id,\n )\n elif part_type == ContentType.VIDEO:\n video_url = getattr(part, \"video_url\", None)\n await self._send_media_value(\n bot=bot,\n chat_id=chat_id,\n value=video_url,\n method_name=\"send_video\",\n payload_name=\"video\",\n message_thread_id=message_thread_id,\n )\n elif part_type == ContentType.AUDIO:\n audio_data = getattr(part, \"data\", None)\n await self._send_media_value(\n bot=bot,\n chat_id=chat_id,\n value=audio_data,\n method_name=\"send_audio\",\n payload_name=\"audio\",\n message_thread_id=message_thread_id,\n )\n elif part_type == ContentType.FILE:\n file_url = getattr(part, \"file_url\", None)\n await self._send_media_value(\n bot=bot,\n chat_id=chat_id,\n value=file_url,\n method_name=\"send_document\",\n payload_name=\"document\",\n message_thread_id=message_thread_id,\n )\n except _FileTooLargeError as exc:\n logger.warning(\"telegram send_media: file too large: %s\", exc)\n await self.send(to_handle, str(exc), meta)\n except _MediaFileUnavailableError as exc:\n logger.warning(\"telegram send_media: file unavailable: %s\", exc)\n await self.send(to_handle, str(exc), meta)\n except BadRequest as exc:\n logger.warning(\"telegram send_media: bad request: %s\", exc)\n await self.send(\n to_handle,\n f\"Telegram rejected the file: {exc}\",\n meta,\n )\n except TimedOut as exc:\n logger.warning(\"telegram send_media: timed out: %s\", exc)\n await self.send(\n to_handle,\n \"File upload timed out. \"\n \"The file may be too large (Telegram bot limit: 50 MB).\",\n meta,\n )\n except RetryAfter as exc:\n logger.warning(\"telegram send_media: rate limited: %s\", exc)\n await self.send(\n to_handle,\n f\"Too many requests. Please try again later. ({exc})\",\n meta,\n )\n except Forbidden as exc:\n logger.warning(\"telegram send_media: forbidden: %s\", exc)\n await self.send(\n to_handle,\n \"The bot does not have permission to send media in this chat.\",\n meta,\n )\n except NetworkError as exc:\n logger.warning(\"telegram send_media: network error: %s\", exc)\n await self.send(\n to_handle,\n \"Network error. Failed to send file, please try again later.\",\n meta,\n )\n except OSError as exc:\n logger.warning(\"telegram send_media: OS error: %s\", exc)\n error_detail = str(exc) or repr(exc)\n await self.send(\n to_handle,\n f\"Failed to read the file, cannot send ({error_detail}).\",\n meta,\n )\n except Exception:\n logger.exception(\"telegram send_media failed\")\n\n async def _send_media_value(\n self,\n *,\n bot: Any,\n chat_id: str,\n value: Any,\n method_name: str,\n payload_name: str,\n message_thread_id: Optional[int],\n ) -> None:\n \"\"\"Send media from URL or local file path.\"\"\"\n if not value:\n return\n if isinstance(value, str) and value.startswith(\"file://\"):\n raw_path = file_url_to_local_path(value)\n if not raw_path:\n logger.warning(\n \"telegram: could not resolve file URL: %s\",\n value,\n )\n raise _MediaFileUnavailableError(\n \"Could not resolve media file from URL.\",\n )\n local_path = Path(raw_path).resolve()\n if not local_path.exists():\n logger.warning(\n \"telegram: media file not found at path: %s\",\n local_path,\n )\n raise _MediaFileUnavailableError(\n f\"Media file not found: {local_path.name}\",\n )\n file_size = local_path.stat().st_size\n if file_size > TELEGRAM_MAX_FILE_SIZE_BYTES:\n file_size_mb = file_size / (1024 * 1024)\n raise _FileTooLargeError(\n f\"File too large to send via Telegram: {local_path.name} \"\n f\"({file_size_mb:.1f} MB, Telegram bot limit: 50 MB)\",\n )\n try:\n with open(local_path, \"rb\") as media_file:\n await self._send_media_payload(\n bot=bot,\n chat_id=chat_id,\n method_name=method_name,\n payload_name=payload_name,\n payload=media_file,\n message_thread_id=message_thread_id,\n )\n except OSError as exc:\n logger.warning(\n \"telegram: failed to open media file: %s: %s\",\n local_path,\n exc,\n )\n raise\n return\n await self._send_media_payload(\n bot=bot,\n chat_id=chat_id,\n method_name=method_name,\n payload_name=payload_name,\n payload=value,\n message_thread_id=message_thread_id,\n )\n\n async def _send_media_payload(\n self,\n *,\n bot: Any,\n chat_id: str,\n method_name: str,\n payload_name: str,\n payload: Any,\n message_thread_id: Optional[int],\n ) -> None:\n \"\"\"Send a prepared Telegram media payload.\"\"\"\n if not payload:\n return\n kwargs = {\n \"chat_id\": chat_id,\n payload_name: payload,\n }\n if message_thread_id is not None:\n kwargs[\"message_thread_id\"] = message_thread_id\n await getattr(bot, method_name)(**kwargs)\n\n async def _polling_cycle(self, app) -> None:\n \"\"\"Run one polling lifecycle: init → poll → watchdog.\"\"\"\n\n def _on_poll_error(exc) -> None:\n app.create_task(\n app.process_error(error=exc, update=None),\n )\n\n await app.initialize()\n\n commands = [\n BotCommand(\n command=\"start\",\n description=\"Start a new conversation\",\n ),\n BotCommand(\n command=\"new\",\n description=\"Start a new conversation (clear memory)\",\n ),\n BotCommand(\n command=\"compact\",\n description=\"Compact conversation memory\",\n ),\n BotCommand(\n command=\"clear\",\n description=\"Clear conversation history\",\n ),\n BotCommand(\n command=\"history\",\n description=\"Show conversation history\",\n ),\n ]\n try:\n await app.bot.set_my_commands(commands)\n logger.info(\n \"telegram: registered %d bot commands\",\n len(commands),\n )\n except Exception:\n logger.warning(\n \"telegram: failed to register commands (non-fatal)\",\n )\n\n await app.updater.start_polling(\n bootstrap_retries=-1,\n allowed_updates=[\"message\", \"edited_message\"],\n error_callback=_on_poll_error,\n )\n await app.start()\n logger.info(\"telegram: polling started (receiving updates)\")\n\n while getattr(app.updater, \"running\", False):\n await asyncio.sleep(_POLL_WATCHDOG_INTERVAL_S)\n\n logger.warning(\"telegram: updater stopped unexpectedly\")\n\n @staticmethod\n async def _teardown_application(app) -> None:\n \"\"\"Cleanly shut down a Telegram Application instance.\"\"\"\n try:\n updater = getattr(app, \"updater\", None)\n if updater and getattr(updater, \"running\", False):\n await updater.stop()\n if getattr(app, \"running\", False):\n await app.stop()\n await app.shutdown()\n except Exception as exc:\n logger.debug(\"telegram teardown: %s\", exc)\n\n async def _run_polling(self) -> None:\n \"\"\"Run Telegram polling with automatic reconnection.\n\n Do not use run_polling() — it calls run_until_complete() and\n fails when the event loop is already running (FastAPI/uvicorn).\n \"\"\"\n if not self.enabled or not self._bot_token:\n return\n\n delay = _RECONNECT_INITIAL_S\n while True:\n try:\n self._application = self._build_application()\n await self._polling_cycle(self._application)\n delay = _RECONNECT_INITIAL_S\n except asyncio.CancelledError:\n logger.debug(\"telegram: polling cancelled\")\n raise\n except InvalidToken:\n logger.error(\n \"telegram: invalid bot token — not retrying\",\n )\n return\n except Exception:\n logger.exception(\n \"telegram: polling failed (check token, network, \"\n \"proxy; in China you may need TELEGRAM_HTTP_PROXY)\",\n )\n finally:\n if self._application:\n await self._teardown_application(\n self._application,\n )\n self._application = None\n\n logger.info(\n \"telegram: reconnecting in %.1fs\",\n delay,\n )\n await asyncio.sleep(delay)\n delay = min(delay * _RECONNECT_FACTOR, _RECONNECT_MAX_S)\n\n async def start(self) -> None:\n if not self.enabled or not self._bot_token:\n logger.debug(\n \"telegram: start() skipped (enabled=%s, token=%s)\",\n self.enabled,\n \"set\" if self._bot_token else \"empty\",\n )\n return\n self._task = asyncio.create_task(\n self._run_polling(),\n name=\"telegram_polling\",\n )\n logger.info(\"telegram: channel started (polling task created)\")\n\n async def stop(self) -> None:\n if not self.enabled:\n return\n if self._task:\n self._task.cancel()\n try:\n await asyncio.wait_for(self._task, timeout=10)\n except (asyncio.CancelledError, asyncio.TimeoutError, Exception):\n pass\n self._task = None\n for cid in list(self._typing_tasks):\n self._stop_typing(cid)\n if self._application:\n await self._teardown_application(self._application)\n\n def resolve_session_id(\n self,\n sender_id: str,\n channel_meta: Optional[dict] = None,\n ) -> str:\n \"\"\"Session by chat_id (one session per chat).\"\"\"\n meta = channel_meta or {}\n chat_id = meta.get(\"chat_id\")\n if chat_id:\n return f\"telegram:{chat_id}\"\n return f\"telegram:{sender_id}\"\n\n def get_to_handle_from_request(self, request: Any) -> str:\n \"\"\"Send target is chat_id from meta or session_id suffix.\"\"\"\n meta = getattr(request, \"channel_meta\", None) or {}\n chat_id = meta.get(\"chat_id\")\n if chat_id:\n return str(chat_id)\n sid = getattr(request, \"session_id\", \"\")\n if sid.startswith(\"telegram:\"):\n return sid.split(\":\", 1)[-1]\n return getattr(request, \"user_id\", \"\") or \"\"\n\n def build_agent_request_from_native(self, native_payload: Any) -> Any:\n \"\"\"Build AgentRequest from Telegram native dict.\"\"\"\n payload = native_payload if isinstance(native_payload, dict) else {}\n channel_id = payload.get(\"channel_id\") or self.channel\n sender_id = payload.get(\"sender_id\") or \"\"\n content_parts = payload.get(\"content_parts\") or []\n meta = payload.get(\"meta\") or {}\n session_id = self.resolve_session_id(sender_id, meta)\n user_id = str(meta.get(\"user_id\") or sender_id)\n request = self.build_agent_request_from_user_content(\n channel_id=channel_id,\n sender_id=sender_id,\n session_id=session_id,\n content_parts=content_parts,\n channel_meta=meta,\n )\n request.user_id = user_id\n request.channel_meta = meta\n return request\n\n def to_handle_from_target(self, *, user_id: str, session_id: str) -> str:\n \"\"\"Cron dispatch: use session_id suffix as chat_id.\"\"\"\n if session_id.startswith(\"telegram:\"):\n return session_id.split(\":\", 1)[-1]\n return user_id\n" }, { "path": "src/copaw/app/channels/telegram/format_html.py", "content": "# -*- coding: utf-8 -*-\n\"\"\"Convert standard Markdown to Telegram-compatible HTML.\n\nTelegram Bot API supports a subset of HTML tags:\n , , , , , 
    , , , 
    \n\nStandard Markdown (as produced by LLMs) uses **bold**, *italic*, `code`,\n```code blocks```, [links](url), > blockquotes, etc.\n\nThis module bridges the gap.\n\"\"\"\nfrom __future__ import annotations\n\nimport re\n\n\ndef _escape_html(text: str) -> str:\n    \"\"\"Escape the three HTML-significant characters.\"\"\"\n    return text.replace(\"&\", \"&\").replace(\"<\", \"<\").replace(\">\", \">\")\n\n\ndef markdown_to_telegram_html(text: str) -> str:\n    \"\"\"Convert standard Markdown text to Telegram Bot API HTML.\n\n    The function handles:\n    - Fenced code blocks (``` ```)\n    - Inline code (` `)\n    - Links [text](url)\n    - Headers (# … ######) → bold\n    - Horizontal rules (---, ***, ___) → ———\n    - Blockquotes (> …) → 
    \n    - Unordered lists (* / - ) → •\n    - Spoilers (||text||) → \n    - Bold (**text**), Italic (*text*), Bold+Italic (***text***)\n    - Strikethrough (~~text~~)\n    \"\"\"\n    if not text:\n        return text\n\n    placeholders: list[str] = []\n\n    def _ph(html_fragment: str) -> str:\n        idx = len(placeholders)\n        placeholders.append(html_fragment)\n        return f\"\\x00PH{idx}\\x00\"\n\n    # ── Phase 1: extract protected regions ──────────────────────────────\n\n    # Fenced code blocks  ```lang\\n…\\n```\n    def _code_block(m: re.Match) -> str:\n        lang = (m.group(1) or \"\").strip()\n        code = _escape_html(m.group(2))\n        if lang:\n            return _ph(\n                f'
    '\n                f\"{code}
    \",\n            )\n        return _ph(f\"
    {code}
    \")\n\n    text = re.sub(\n        r\"```(\\w*)\\n?(.*?)```\",\n        _code_block,\n        text,\n        flags=re.DOTALL,\n    )\n\n    # Inline code `…`\n    def _inline_code(m: re.Match) -> str:\n        return _ph(f\"{_escape_html(m.group(1))}\")\n\n    text = re.sub(r\"`([^`\\n]+)`\", _inline_code, text)\n\n    # Links [text](url) — protect URLs from escaping\n    def _link(m: re.Match) -> str:\n        link_text = _escape_html(m.group(1))\n        url = m.group(2)  # URL should not have its & double-escaped\n        # Only escape < and > in URL, keep & as-is for query params\n        url = url.replace(\"<\", \"%3C\").replace(\">\", \"%3E\")\n        return _ph(f'    {link_text}')\n\n    text = re.sub(r\"\\[([^\\]]+)\\]\\(([^)]+)\\)\", _link, text)\n\n    # ── Phase 2: escape HTML in remaining text ─────────────────────────\n    text = _escape_html(text)\n\n    # ── Phase 3: structural (block-level) elements ─────────────────────\n\n    # Horizontal rules  (*** / --- / ___ on their own line)\n    text = re.sub(r\"^[\\*\\-_]{3,}\\s*$\", \"———\", text, flags=re.MULTILINE)\n\n    # Headers  # … ###### → text\n    text = re.sub(\n        r\"^#{1,6}\\s+(.+?)$\",\n        r\"\\1\",\n        text,\n        flags=re.MULTILINE,\n    )\n\n    # Blockquotes: consecutive lines starting with \">\"\n    # After _escape_html, the \">\" became \">\"\n    lines = text.split(\"\\n\")\n    result_lines: list[str] = []\n    quote_buf: list[str] = []\n\n    def _flush_quote() -> None:\n        if quote_buf:\n            inner = \"\\n\".join(quote_buf)\n            result_lines.append(f\"
    {inner}
    \")\n            quote_buf.clear()\n\n    for line in lines:\n        stripped = line.lstrip()\n        if stripped.startswith(\"> \"):\n            quote_buf.append(stripped[5:])\n        elif stripped == \">\":\n            quote_buf.append(\"\")\n        else:\n            _flush_quote()\n            result_lines.append(line)\n    _flush_quote()\n    text = \"\\n\".join(result_lines)\n\n    # Unordered list markers:  * / - at line start → •\n    text = re.sub(\n        r\"^(\\s*)[\\*\\-]\\s+\",\n        r\"\\1• \",\n        text,\n        flags=re.MULTILINE,\n    )\n\n    # ── Phase 4: inline formatting ─────────────────────────────────────\n\n    # Spoilers  ||text||\n    text = re.sub(\n        r\"\\|\\|(.+?)\\|\\|\",\n        r\"\\1\",\n        text,\n    )\n\n    # Bold + Italic  ***text***\n    text = re.sub(r\"\\*{3}(.+?)\\*{3}\", r\"\\1\", text)\n\n    # Bold  **text**\n    text = re.sub(r\"\\*{2}(.+?)\\*{2}\", r\"\\1\", text)\n\n    # Bold  __text__  (Markdown alternate)\n    text = re.sub(r\"__(.+?)__\", r\"\\1\", text)\n\n    # Italic  *text*  (not at word boundary to avoid false positives)\n    text = re.sub(r\"(?\\1    \", text)\n\n    # Italic  _text_\n    text = re.sub(r\"(?\\1\", text)\n\n    # Strikethrough  ~~text~~\n    text = re.sub(r\"~~(.+?)~~\", r\"\\1\", text)\n\n    # ── Phase 5: restore placeholders ──────────────────────────────────\n    for idx, content in enumerate(placeholders):\n        text = text.replace(f\"\\x00PH{idx}\\x00\", content)\n\n    return text\n\n\ndef strip_markdown(text: str) -> str:\n    \"\"\"Strip Markdown formatting, returning clean plain text for fallback.\n\n    Used when both HTML and MarkdownV2 sending fail.\n    \"\"\"\n    if not text:\n        return text\n    # Remove fenced code block markers (keep content)\n    text = re.sub(r\"```\\w*\\n?\", \"\", text)\n    # Remove inline code backticks\n    text = re.sub(r\"`([^`]+)`\", r\"\\1\", text)\n    # Remove header markers\n    text = re.sub(r\"^#{1,6}\\s+\", \"\", text, flags=re.MULTILINE)\n    # Horizontal rules → visual separator\n    text = re.sub(r\"^[\\*\\-_]{3,}\\s*$\", \"———\", text, flags=re.MULTILINE)\n    # Remove bold/italic markers\n    text = re.sub(r\"\\*{1,3}(.+?)\\*{1,3}\", r\"\\1\", text)\n    text = re.sub(r\"_{1,2}(.+?)_{1,2}\", r\"\\1\", text)\n    # Remove strikethrough markers\n    text = re.sub(r\"~~(.+?)~~\", r\"\\1\", text)\n    # Remove spoiler markers\n    text = re.sub(r\"\\|\\|(.+?)\\|\\|\", r\"\\1\", text)\n    # Links → text (url)\n    text = re.sub(r\"\\[([^\\]]+)\\]\\(([^)]+)\\)\", r\"\\1 (\\2)\", text)\n    # Remove blockquote markers\n    text = re.sub(r\"^>\\s?\", \"\", text, flags=re.MULTILINE)\n    # Convert unordered list markers\n    text = re.sub(r\"^(\\s*)[\\*\\-]\\s+\", r\"\\1• \", text, flags=re.MULTILINE)\n    return text\n"
  },
  {
    "path": "src/copaw/app/channels/utils.py",
    "content": "# -*- coding: utf-8 -*-\n# pylint: disable=too-many-return-statements\n\"\"\"\nBridge between channels and AgentApp process: factory to build\nProcessHandler from runner. Shared helpers for channels (e.g. file URL).\n\"\"\"\nfrom __future__ import annotations\n\nimport os\nfrom typing import Any, Optional\nfrom urllib.parse import urlparse\nfrom urllib.request import url2pathname\n\n\ndef file_url_to_local_path(url: str) -> Optional[str]:\n    \"\"\"Convert file:// URL or plain local path to local path string.\n\n    Supports:\n    - file:// URL (all platforms): file:///path, file://D:/path,\n      file://D:\\\\path (Windows two-slash).\n    - Plain local path: D:\\\\path, /tmp/foo (no scheme). Pass-through after\n      stripping whitespace; no existence check (caller may use Path().exists).\n\n    Returns None only when url is clearly not a local file (e.g. http(s) URL)\n    or file URL could not be resolved to a non-empty path.\n    \"\"\"\n    if not url or not isinstance(url, str):\n        return None\n    s = url.strip()\n    if not s:\n        return None\n    parsed = urlparse(s)\n    if parsed.scheme == \"file\":\n        path = url2pathname(parsed.path)\n        if not path and parsed.netloc:\n            path = url2pathname(parsed.netloc.replace(\"\\\\\", \"/\"))\n        elif (\n            path\n            and parsed.netloc\n            and len(parsed.netloc) == 1\n            and os.name == \"nt\"\n        ):\n            path = f\"{parsed.netloc}:{path}\"\n        return path if path else None\n    if parsed.scheme in (\"http\", \"https\"):\n        return None\n    if not parsed.scheme:\n        return s\n    if (\n        os.name == \"nt\"\n        and len(parsed.scheme) == 1\n        and parsed.path.startswith(\"\\\\\")\n    ):\n        return s\n    return None\n\n\ndef make_process_from_runner(runner: Any):\n    \"\"\"\n    Use runner.stream_query as the channel's process.\n\n    Each channel does: native -> build_agent_request_from_native()\n        -> process(request) -> send on each completed message.\n    process is runner.stream_query, same as AgentApp's /process endpoint.\n\n    Usage::\n        process = make_process_from_runner(runner)\n        manager = ChannelManager.from_env(process)\n    \"\"\"\n    return runner.stream_query\n"
  },
  {
    "path": "src/copaw/app/channels/voice/__init__.py",
    "content": "# -*- coding: utf-8 -*-\n\"\"\"Voice channel: Twilio ConversationRelay + Cloudflare Tunnel.\"\"\"\n\nfrom .channel import VoiceChannel  # noqa: F401\n\n__all__ = [\"VoiceChannel\"]\n"
  },
  {
    "path": "src/copaw/app/channels/voice/channel.py",
    "content": "# -*- coding: utf-8 -*-\n\"\"\"Voice Channel: Twilio ConversationRelay + Cloudflare Tunnel.\"\"\"\nfrom __future__ import annotations\n\nimport collections\nimport logging\nimport secrets\nfrom typing import Any, Dict, Optional\n\nfrom ..base import BaseChannel, OnReplySent, ProcessHandler\nfrom .session import CallSessionManager\nfrom .twilio_manager import TwilioManager\n\nlogger = logging.getLogger(__name__)\n\n\nclass VoiceChannel(BaseChannel):\n    \"\"\"CoPaw Voice channel backed by Twilio ConversationRelay.\n\n    ``uses_manager_queue = False`` because voice calls are long-lived\n    WebSocket sessions -- the ConversationRelay handler runs its own\n    async loop per call.\n    \"\"\"\n\n    channel = \"voice\"\n    uses_manager_queue = False\n\n    def __init__(\n        self,\n        process: ProcessHandler,\n        on_reply_sent: OnReplySent = None,\n        show_tool_details: bool = True,\n        filter_tool_messages: bool = False,\n        filter_thinking: bool = False,\n    ) -> None:\n        super().__init__(\n            process,\n            on_reply_sent,\n            show_tool_details,\n            filter_tool_messages=filter_tool_messages,\n            filter_thinking=filter_thinking,\n        )\n        self.session_mgr = CallSessionManager()\n        self.twilio_mgr: Optional[TwilioManager] = None\n        self.tunnel_mgr = None  # CloudflareTunnelDriver, set by from_config\n        self._config: Any = None\n        self._enabled = False\n        self._pending_ws_tokens: collections.OrderedDict[\n            str,\n            None,\n        ] = collections.OrderedDict()\n\n    @classmethod\n    def from_config(\n        cls,\n        process: ProcessHandler,\n        config: Any,\n        on_reply_sent: OnReplySent = None,\n        show_tool_details: bool = True,\n        filter_tool_messages: bool = False,\n        filter_thinking: bool = False,\n    ) -> \"VoiceChannel\":\n        instance = cls(\n            process,\n            on_reply_sent,\n            show_tool_details,\n            filter_tool_messages=filter_tool_messages,\n            filter_thinking=filter_thinking,\n        )\n        instance._config = config\n        instance._enabled = getattr(config, \"enabled\", False)\n\n        sid = getattr(config, \"twilio_account_sid\", \"\")\n        token = getattr(config, \"twilio_auth_token\", \"\")\n        if sid and token:\n            instance.twilio_mgr = TwilioManager(sid, token)\n\n        # Tunnel driver is created lazily on start()\n        return instance\n\n    async def start(self) -> None:\n        \"\"\"Start the voice channel: tunnel + Twilio webhook.\"\"\"\n        if not self._enabled:\n            logger.info(\"Voice channel disabled, skipping start\")\n            return\n\n        if not self.twilio_mgr:\n            logger.warning(\n                \"Voice channel enabled but Twilio credentials missing\",\n            )\n            return\n\n        phone_number_sid = getattr(self._config, \"phone_number_sid\", \"\")\n        if not phone_number_sid:\n            logger.warning(\n                \"Voice channel enabled but phone_number_sid not configured\",\n            )\n            return\n\n        # Start Cloudflare tunnel pointing at the app's serving port\n        from copaw.tunnel import CloudflareTunnelDriver\n        from copaw.config.utils import read_last_api\n\n        self.tunnel_mgr = CloudflareTunnelDriver()\n        api_info = read_last_api()\n        local_port = api_info[1] if api_info else 8088\n\n        try:\n            tunnel_info = await self.tunnel_mgr.start(local_port)\n        except Exception:\n            logger.exception(\"Failed to start Cloudflare tunnel\")\n            return\n\n        # Configure Twilio webhook + status callback\n        base_url = tunnel_info.public_url\n        webhook_url = f\"{base_url}/voice/incoming\"\n        status_cb_url = f\"{base_url}/voice/status-callback\"\n        try:\n            await self.twilio_mgr.configure_voice_webhook(\n                phone_number_sid,\n                webhook_url,\n                status_callback_url=status_cb_url,\n            )\n        except Exception:\n            logger.exception(\n                \"Failed to configure Twilio webhook; stopping tunnel\",\n            )\n            await self.tunnel_mgr.stop()\n            self.tunnel_mgr = None\n            return\n\n        logger.info(\n            \"Voice channel started: tunnel=%s phone=%s\",\n            tunnel_info.public_url,\n            getattr(self._config, \"phone_number\", \"\"),\n        )\n\n    async def stop(self) -> None:\n        \"\"\"Stop the voice channel: close sessions + tunnel.\"\"\"\n        for session in self.session_mgr.active_sessions():\n            try:\n                await session.handler.close()\n            except Exception:\n                logger.exception(\n                    \"Error closing session handler: call_sid=%s\",\n                    session.call_sid,\n                )\n            finally:\n                self.session_mgr.end_session(session.call_sid)\n\n        if self.tunnel_mgr:\n            try:\n                await self.tunnel_mgr.stop()\n            except Exception:\n                logger.exception(\"Error stopping tunnel\")\n\n        logger.info(\"Voice channel stopped\")\n\n    async def send(\n        self,\n        to_handle: str,\n        text: str,\n        meta: Optional[Dict[str, Any]] = None,\n    ) -> None:\n        \"\"\"Send text to an active call session (by call_sid).\"\"\"\n        # to_handle is the call_sid for voice\n        session = self.session_mgr.get_session(to_handle)\n        if session and session.status == \"active\":\n            await session.handler.send_text(text)\n\n    def build_agent_request_from_native(\n        self,\n        native_payload: Any,\n    ) -> Any:\n        \"\"\"Convert a voice payload dict to AgentRequest.\"\"\"\n        from agentscope_runtime.engine.schemas.agent_schemas import (\n            AgentRequest,\n            Message,\n            MessageType,\n            Role,\n            TextContent,\n            ContentType,\n        )\n\n        text = native_payload.get(\"transcript\", \"\")\n        session_id = native_payload.get(\"session_id\", \"\")\n        user_id = native_payload.get(\"from_number\", \"\")\n\n        msg = Message(\n            type=MessageType.MESSAGE,\n            role=Role.USER,\n            content=[TextContent(type=ContentType.TEXT, text=text)],\n        )\n        return AgentRequest(\n            session_id=session_id,\n            user_id=user_id,\n            input=[msg],\n            channel=self.channel,\n        )\n\n    @property\n    def config(self) -> Any:\n        \"\"\"Public accessor for the channel configuration.\"\"\"\n        return self._config\n\n    @property\n    def process(self) -> ProcessHandler:\n        \"\"\"Public accessor for the process handler.\"\"\"\n        return self._process\n\n    _MAX_PENDING_TOKENS = 100\n\n    def create_ws_token(self) -> str:\n        \"\"\"Generate a single-use token for WebSocket authentication.\"\"\"\n        # Evict oldest tokens if the dict grows too large (e.g. calls\n        # that generated TwiML but never connected via WebSocket).\n        while len(self._pending_ws_tokens) >= self._MAX_PENDING_TOKENS:\n            self._pending_ws_tokens.popitem(last=False)\n        token = secrets.token_urlsafe(32)\n        self._pending_ws_tokens[token] = None\n        return token\n\n    def validate_ws_token(self, token: str) -> bool:\n        \"\"\"Validate and consume a single-use WebSocket token.\"\"\"\n        return self._pending_ws_tokens.pop(token, ...) is not ...\n\n    def get_tunnel_url(self) -> str | None:\n        \"\"\"Return the current tunnel public URL.\"\"\"\n        if self.tunnel_mgr:\n            return self.tunnel_mgr.get_public_url()\n        return None\n\n    def get_tunnel_wss_url(self) -> str | None:\n        \"\"\"Return the current tunnel WSS URL.\"\"\"\n        if self.tunnel_mgr:\n            info = self.tunnel_mgr.get_info()\n            if info:\n                return info.public_wss_url\n        return None\n"
  },
  {
    "path": "src/copaw/app/channels/voice/conversation_relay.py",
    "content": "# -*- coding: utf-8 -*-\n\"\"\"ConversationRelay WebSocket handler for a single call.\"\"\"\nfrom __future__ import annotations\n\nimport json\nimport logging\nfrom typing import TYPE_CHECKING, Any\n\nfrom agentscope_runtime.engine.schemas.agent_schemas import (\n    ContentType,\n    MessageType,\n    RunStatus,\n)\n\nfrom fastapi import WebSocketDisconnect\n\nfrom .session import CallSessionManager\n\nif TYPE_CHECKING:\n    from fastapi import WebSocket\n\n    from ..base import ProcessHandler\n\nlogger = logging.getLogger(__name__)\n\n_ERROR_MSG = \"I'm having trouble right now. Please try again.\"\n\n\nclass ConversationRelayHandler:\n    \"\"\"Handle one call's WebSocket session with Twilio ConversationRelay.\n\n    Twilio -> CoPaw messages:\n        ``{\"type\":\"setup\",  \"callSid\":\"CA...\", \"from\":\"+1...\", ...}``\n        ``{\"type\":\"prompt\", \"voicePrompt\":\"transcribed text\"}``\n        ``{\"type\":\"interrupt\", \"utteranceUntilInterrupt\":\"...\", ...}``\n        ``{\"type\":\"dtmf\",   \"digit\":\"5\"}``\n\n    CoPaw -> Twilio messages:\n        ``{\"type\":\"text\", \"token\":\"chunk\", \"last\":false}``\n        ``{\"type\":\"text\", \"token\":\"\",      \"last\":true}``\n        ``{\"type\":\"end\"}``\n    \"\"\"\n\n    def __init__(\n        self,\n        ws: \"WebSocket\",\n        process: \"ProcessHandler\",\n        session_mgr: CallSessionManager,\n        channel_type: str = \"voice\",\n    ) -> None:\n        self.ws = ws\n        self._process = process\n        self._session_mgr = session_mgr\n        self._channel_type = channel_type\n\n        self.call_sid: str = \"\"\n        self.caller_info: dict[str, str] = {}\n        self._closed = False\n\n    async def handle(self) -> None:\n        \"\"\"Main loop: receive and dispatch messages from Twilio.\"\"\"\n        try:\n            while not self._closed:\n                raw = await self.ws.receive_text()\n                try:\n                    msg = json.loads(raw)\n                except json.JSONDecodeError:\n                    logger.warning(\"Bad JSON from Twilio WS: %s\", raw[:200])\n                    continue\n\n                msg_type = msg.get(\"type\")\n                match msg_type:\n                    case \"setup\":\n                        await self._handle_setup(msg)\n                    case \"prompt\":\n                        await self._handle_prompt(msg)\n                    case \"interrupt\":\n                        await self._handle_interrupt(msg)\n                    case \"dtmf\":\n                        await self._handle_dtmf(msg)\n                    case _:\n                        logger.debug(\"Unknown WS message type: %s\", msg_type)\n        except WebSocketDisconnect:\n            logger.info(\n                \"ConversationRelay WS disconnected: call_sid=%s\",\n                self.call_sid,\n            )\n        except Exception:\n            if not self._closed:\n                logger.exception(\n                    \"Unexpected error in ConversationRelay: call_sid=%s\",\n                    self.call_sid,\n                )\n        finally:\n            self._closed = True\n            try:\n                await self.ws.close()\n            except Exception:\n                pass\n            if self.call_sid:\n                self._session_mgr.end_session(self.call_sid)\n\n    async def _handle_setup(self, msg: dict) -> None:\n        \"\"\"Process the initial ``setup`` message from Twilio.\"\"\"\n        self.call_sid = msg.get(\"callSid\", \"\")\n        self.caller_info = {\n            \"from\": msg.get(\"from\", \"\"),\n            \"to\": msg.get(\"to\", \"\"),\n        }\n        logger.info(\n            \"Call setup: call_sid=%s from=%s to=%s\",\n            self.call_sid,\n            self.caller_info.get(\"from\"),\n            self.caller_info.get(\"to\"),\n        )\n        if not self.call_sid:\n            logger.warning(\"Setup message missing callSid, closing connection\")\n            await self.close()\n            return\n        self._session_mgr.create_session(\n            call_sid=self.call_sid,\n            handler=self,\n            from_number=self.caller_info.get(\"from\", \"\"),\n            to_number=self.caller_info.get(\"to\", \"\"),\n        )\n\n    async def _handle_prompt(self, msg: dict) -> None:\n        \"\"\"Process a ``prompt`` (user speech transcript) from Twilio.\"\"\"\n        user_text = msg.get(\"voicePrompt\", \"\")\n        if not user_text.strip():\n            return\n\n        logger.info(\n            \"Voice prompt: call_sid=%s text=%s\",\n            self.call_sid,\n            user_text[:100],\n        )\n\n        request = self._build_agent_request(user_text)\n\n        # Process through CoPaw agent and stream response to Twilio.\n        await self._process_and_stream(request)\n\n    async def _handle_interrupt(self, msg: dict) -> None:\n        \"\"\"Process an ``interrupt`` message -- caller started speaking.\"\"\"\n        spoken = msg.get(\"utteranceUntilInterrupt\", \"\")\n        logger.info(\n            \"Call interrupted: call_sid=%s spoken_so_far=%s\",\n            self.call_sid,\n            spoken[:100],\n        )\n        # We log the interruption but don't truncate context.\n        # Future: truncate assistant message to what was actually spoken.\n\n    async def _handle_dtmf(self, msg: dict) -> None:\n        \"\"\"Process a ``dtmf`` message (keypad press).\"\"\"\n        digit = msg.get(\"digit\", \"\")\n        logger.info(\n            \"DTMF received: call_sid=%s digit=%s\",\n            self.call_sid,\n            digit,\n        )\n\n    def _build_agent_request(self, text: str) -> Any:\n        \"\"\"Build an AgentRequest from user speech text.\"\"\"\n        from agentscope_runtime.engine.schemas.agent_schemas import (\n            AgentRequest,\n            Message,\n            Role,\n            TextContent,\n        )\n\n        msg = Message(\n            type=MessageType.MESSAGE,\n            role=Role.USER,\n            content=[TextContent(type=ContentType.TEXT, text=text)],\n        )\n        return AgentRequest(\n            session_id=f\"voice:{self.call_sid}\",\n            user_id=self.caller_info.get(\"from\", \"\"),\n            input=[msg],\n            channel=self._channel_type,\n        )\n\n    async def _process_and_stream(self, request: Any) -> None:\n        \"\"\"Run the request through the agent, streaming tokens to Twilio.\n\n        Each completed message is sent immediately followed by a\n        ``last=true`` marker so Twilio can start TTS playback without\n        waiting for the entire agent event stream to finish.\n        \"\"\"\n        try:\n            async for event in self._process(request):\n                if self._closed:\n                    break\n                obj = getattr(event, \"object\", None)\n                status = getattr(event, \"status\", None)\n\n                if obj == \"message\" and status == RunStatus.Completed:\n                    text = self._extract_text_from_event(event)\n                    if text:\n                        await self._send_token(text, last=False)\n                        await self._send_token(\"\", last=True)\n                elif obj == \"response\":\n                    err = getattr(event, \"error\", None)\n                    if err:\n                        err_msg = getattr(err, \"message\", str(err))\n                        logger.error(\n                            \"Agent error: call_sid=%s error=%s\",\n                            self.call_sid,\n                            err_msg,\n                        )\n                        await self._send_token(\n                            _ERROR_MSG,\n                            last=False,\n                        )\n                        await self._send_token(\"\", last=True)\n        except Exception:\n            logger.exception(\n                \"Error processing voice request: call_sid=%s\",\n                self.call_sid,\n            )\n            if not self._closed:\n                await self._send_token(_ERROR_MSG, last=False)\n                await self._send_token(\"\", last=True)\n\n    @staticmethod\n    def _extract_text_from_event(event: Any) -> str:\n        \"\"\"Extract plain text from a completed message event.\"\"\"\n        content = getattr(event, \"content\", None)\n        if not content:\n            return \"\"\n\n        parts: list[str] = []\n        for c in content:\n            ct = getattr(c, \"type\", None)\n            if ct == ContentType.TEXT:\n                text = getattr(c, \"text\", None)\n                if text:\n                    parts.append(text.strip())\n            elif ct == ContentType.REFUSAL:\n                refusal = getattr(c, \"refusal\", None)\n                if refusal:\n                    parts.append(refusal.strip())\n        return \" \".join(parts)\n\n    async def _send_token(\n        self,\n        token: str,\n        *,\n        last: bool = False,\n    ) -> None:\n        \"\"\"Send a single text token to Twilio for TTS playback.\"\"\"\n        if self._closed:\n            return\n        try:\n            await self.ws.send_text(\n                json.dumps(\n                    {\"type\": \"text\", \"token\": token, \"last\": last},\n                ),\n            )\n        except Exception:\n            logger.warning(\n                \"Failed to send text to Twilio WS: call_sid=%s\",\n                self.call_sid,\n            )\n            self._closed = True\n\n    async def send_text(self, text: str) -> None:\n        \"\"\"Send text to Twilio for TTS playback (convenience wrapper).\"\"\"\n        await self._send_token(text, last=True)\n\n    async def close(self) -> None:\n        \"\"\"Send end signal and close the WebSocket.\"\"\"\n        if self._closed:\n            return\n        self._closed = True\n        try:\n            await self.ws.send_text(json.dumps({\"type\": \"end\"}))\n        except Exception:\n            logger.exception(\"Failed to send end frame in ConversationRelay\")\n        finally:\n            try:\n                await self.ws.close()\n            except Exception:\n                logger.exception(\n                    \"Failed to close WebSocket in ConversationRelay\",\n                )\n"
  },
  {
    "path": "src/copaw/app/channels/voice/session.py",
    "content": "# -*- coding: utf-8 -*-\n\"\"\"Call session management for the Voice channel.\"\"\"\nfrom __future__ import annotations\n\nimport logging\nfrom dataclasses import dataclass\nfrom datetime import datetime, timezone\nfrom typing import TYPE_CHECKING, Optional\n\nif TYPE_CHECKING:\n    from .conversation_relay import ConversationRelayHandler\n\nlogger = logging.getLogger(__name__)\n\n\n@dataclass\nclass CallSession:\n    \"\"\"One active or ended phone call.\"\"\"\n\n    call_sid: str\n    from_number: str\n    to_number: str\n    started_at: datetime\n    handler: ConversationRelayHandler\n    status: str = \"active\"  # active | ended | failed\n\n\nclass CallSessionManager:\n    \"\"\"Registry of active call sessions.\"\"\"\n\n    def __init__(self) -> None:\n        self._sessions: dict[str, CallSession] = {}\n\n    def create_session(\n        self,\n        call_sid: str,\n        handler: \"ConversationRelayHandler\",\n        from_number: str = \"\",\n        to_number: str = \"\",\n    ) -> CallSession:\n        session = CallSession(\n            call_sid=call_sid,\n            from_number=from_number,\n            to_number=to_number,\n            started_at=datetime.now(timezone.utc),\n            handler=handler,\n        )\n        self._sessions[call_sid] = session\n        logger.info(\n            \"Call session created: call_sid=%s from=%s\",\n            call_sid,\n            from_number,\n        )\n        return session\n\n    def get_session(self, call_sid: str) -> Optional[CallSession]:\n        return self._sessions.get(call_sid)\n\n    def end_session(self, call_sid: str) -> None:\n        session = self._sessions.pop(call_sid, None)\n        if session:\n            session.status = \"ended\"\n            logger.info(\"Call session ended: call_sid=%s\", call_sid)\n\n    def active_sessions(self) -> list[CallSession]:\n        return [s for s in self._sessions.values() if s.status == \"active\"]\n\n    def active_count(self) -> int:\n        return sum(1 for s in self._sessions.values() if s.status == \"active\")\n\n    def all_sessions(self) -> list[CallSession]:\n        return list(self._sessions.values())\n"
  },
  {
    "path": "src/copaw/app/channels/voice/twilio_manager.py",
    "content": "# -*- coding: utf-8 -*-\n\"\"\"Twilio API wrapper for the Voice channel.\"\"\"\nfrom __future__ import annotations\n\nimport asyncio\nimport logging\nfrom functools import partial\n\nlogger = logging.getLogger(__name__)\n\n\nclass TwilioManager:\n    \"\"\"Async wrapper around the synchronous ``twilio`` Python SDK.\"\"\"\n\n    def __init__(self, account_sid: str, auth_token: str) -> None:\n        self._account_sid = account_sid\n        self._auth_token = auth_token\n        self._client = None  # lazy init\n\n    def _get_client(self):\n        if self._client is None:\n            from twilio.rest import Client\n\n            self._client = Client(self._account_sid, self._auth_token)\n        return self._client\n\n    async def _run_sync(self, fn, *args, **kwargs):\n        loop = asyncio.get_running_loop()\n        return await loop.run_in_executor(None, partial(fn, *args, **kwargs))\n\n    async def configure_voice_webhook(\n        self,\n        phone_number_sid: str,\n        webhook_url: str,\n        status_callback_url: str = \"\",\n    ) -> None:\n        \"\"\"Update the voice webhook URL on an existing phone number.\"\"\"\n        client = self._get_client()\n\n        def _configure():\n            kwargs = {\n                \"voice_url\": webhook_url,\n                \"voice_method\": \"POST\",\n            }\n            if status_callback_url:\n                kwargs[\"status_callback\"] = status_callback_url\n                kwargs[\"status_callback_method\"] = \"POST\"\n            client.incoming_phone_numbers(phone_number_sid).update(\n                **kwargs,\n            )\n\n        await asyncio.wait_for(self._run_sync(_configure), timeout=30)\n        logger.info(\n            \"Twilio webhook configured: sid=%s url=%s\",\n            phone_number_sid,\n            webhook_url,\n        )\n"
  },
  {
    "path": "src/copaw/app/channels/voice/twiml.py",
    "content": "# -*- coding: utf-8 -*-\n\"\"\"TwiML generation helpers for the Voice channel.\"\"\"\nfrom __future__ import annotations\n\nimport xml.etree.ElementTree as ET\n\n\ndef build_conversation_relay_twiml(\n    ws_url: str,\n    *,\n    welcome_greeting: str = \"Hi! This is CoPaw. How can I help you?\",\n    tts_provider: str = \"google\",\n    tts_voice: str = \"en-US-Journey-D\",\n    stt_provider: str = \"deepgram\",\n    language: str = \"en-US\",\n    interruptible: bool = True,\n) -> str:\n    \"\"\"Build TwiML ```` that connects to ConversationRelay.\n\n    Returns an XML string suitable as an HTTP response to Twilio's\n    incoming call webhook.\n    \"\"\"\n    response_el = ET.Element(\"Response\")\n    connect_el = ET.SubElement(response_el, \"Connect\")\n    ET.SubElement(\n        connect_el,\n        \"ConversationRelay\",\n        url=ws_url,\n        welcomeGreeting=welcome_greeting,\n        ttsProvider=tts_provider,\n        voice=tts_voice,\n        transcriptionProvider=stt_provider,\n        language=language,\n        interruptible=str(interruptible).lower(),\n    )\n    xml_body = ET.tostring(response_el, encoding=\"unicode\")\n    return f'{xml_body}'\n\n\ndef build_busy_twiml(\n    message: str = \"CoPaw is on another call. Please try again later.\",\n) -> str:\n    \"\"\"Build TwiML that speaks a busy message.\n\n    Twilio automatically ends the call after all verbs complete.\n    \"\"\"\n    response_el = ET.Element(\"Response\")\n    say_el = ET.SubElement(response_el, \"Say\")\n    say_el.text = message\n    xml_body = ET.tostring(response_el, encoding=\"unicode\")\n    return f'{xml_body}'\n\n\ndef build_error_twiml(\n    message: str = \"An error occurred. Please try again later.\",\n) -> str:\n    \"\"\"Build TwiML that speaks an error message.\n\n    Twilio automatically ends the call after all verbs complete.\n    \"\"\"\n    return build_busy_twiml(message)\n"
  },
  {
    "path": "src/copaw/app/channels/wecom/__init__.py",
    "content": "# -*- coding: utf-8 -*-\n\"\"\"WeCom (Enterprise WeChat) channel package.\"\"\"\n\nfrom .channel import WecomChannel\n\n__all__ = [\"WecomChannel\"]\n"
  },
  {
    "path": "src/copaw/app/channels/wecom/channel.py",
    "content": "# -*- coding: utf-8 -*-\n# pylint: disable=too-many-statements,too-many-branches\n# pylint: disable=too-many-return-statements,too-many-instance-attributes\n# pylint: disable=too-many-nested-blocks\n\"\"\"WeCom (Enterprise WeChat) Channel.\n\nUses the aibot WebSocket SDK to receive messages from WeCom AI Bot.\nSends replies via the same WebSocket channel using stream mode\n(reply_stream). Supports text, image, voice, file, and mixed messages.\n\"\"\"\n\nfrom __future__ import annotations\n\nimport asyncio\nimport hashlib\nimport logging\nimport os\nimport sys\nimport threading\nfrom collections import OrderedDict\nfrom pathlib import Path\nfrom typing import Any, Dict, List, Optional\n\nfrom agentscope_runtime.engine.schemas.agent_schemas import (\n    AgentRequest,\n    FileContent,\n    ImageContent,\n    TextContent,\n)\nfrom aibot import WSClient, WSClientOptions, generate_req_id\n\nfrom ....constant import DEFAULT_MEDIA_DIR\nfrom ..base import (\n    BaseChannel,\n    ContentType,\n    OnReplySent,\n    OutgoingContentPart,\n    ProcessHandler,\n)\nfrom .utils import format_markdown_tables\n\nlogger = logging.getLogger(__name__)\n\n# Max number of processed message_ids to keep for dedup.\n_WECOM_PROCESSED_IDS_MAX = 2000\n\n\nclass WecomChannel(BaseChannel):\n    \"\"\"WeCom AI Bot channel: WebSocket receive and send.\n\n    Session: for single-chat session_id = wecom:, for group-chat\n    wecom:group:. The frame from the SDK is stored in meta so\n    we can call reply_stream back through the same connection.\n    \"\"\"\n\n    channel = \"wecom\"\n\n    def __init__(\n        self,\n        process: ProcessHandler,\n        enabled: bool,\n        bot_id: str,\n        secret: str,\n        bot_prefix: str = \"[BOT] \",\n        media_dir: str = \"\",\n        welcome_text: str = \"\",\n        on_reply_sent: OnReplySent = None,\n        show_tool_details: bool = True,\n        filter_tool_messages: bool = False,\n        filter_thinking: bool = False,\n        dm_policy: str = \"open\",\n        group_policy: str = \"open\",\n        allow_from: Optional[List[str]] = None,\n        deny_message: str = \"\",\n        max_reconnect_attempts: int = -1,\n    ):\n        super().__init__(\n            process,\n            on_reply_sent=on_reply_sent,\n            show_tool_details=show_tool_details,\n            filter_tool_messages=filter_tool_messages,\n            filter_thinking=filter_thinking,\n            dm_policy=dm_policy,\n            group_policy=group_policy,\n            allow_from=allow_from,\n            deny_message=deny_message,\n        )\n        self.enabled = enabled\n        self.bot_id = bot_id\n        self.secret = secret\n        self.bot_prefix = bot_prefix\n        self.welcome_text = welcome_text\n        self._media_dir = (\n            Path(media_dir).expanduser() if media_dir else DEFAULT_MEDIA_DIR\n        )\n        self._max_reconnect_attempts = max_reconnect_attempts\n\n        self._client: Any = None\n        self._loop: Optional[asyncio.AbstractEventLoop] = None\n        self._ws_loop: Optional[asyncio.AbstractEventLoop] = None\n        self._ws_thread: Optional[threading.Thread] = None\n\n        # message_id dedup (ordered dict, trimmed when over limit)\n        self._processed_message_ids: OrderedDict[str, None] = OrderedDict()\n        self._processed_ids_lock = threading.Lock()\n\n    @classmethod\n    def from_env(\n        cls,\n        process: ProcessHandler,\n        on_reply_sent: OnReplySent = None,\n    ) -> \"WecomChannel\":\n        allow_from_env = os.getenv(\"WECOM_ALLOW_FROM\", \"\")\n        allow_from = (\n            [s.strip() for s in allow_from_env.split(\",\") if s.strip()]\n            if allow_from_env\n            else []\n        )\n        return cls(\n            process=process,\n            enabled=os.getenv(\"WECOM_CHANNEL_ENABLED\", \"0\") == \"1\",\n            bot_id=os.getenv(\"WECOM_BOT_ID\", \"\"),\n            secret=os.getenv(\"WECOM_SECRET\", \"\"),\n            bot_prefix=os.getenv(\"WECOM_BOT_PREFIX\", \"[BOT] \"),\n            media_dir=os.getenv(\"WECOM_MEDIA_DIR\", \"\"),\n            on_reply_sent=on_reply_sent,\n            dm_policy=os.getenv(\"WECOM_DM_POLICY\", \"open\"),\n            group_policy=os.getenv(\"WECOM_GROUP_POLICY\", \"open\"),\n            allow_from=allow_from,\n            deny_message=os.getenv(\"WECOM_DENY_MESSAGE\", \"\"),\n            max_reconnect_attempts=int(\n                os.getenv(\"WECOM_MAX_RECONNECT_ATTEMPTS\", \"-1\"),\n            ),\n        )\n\n    @classmethod\n    def from_config(\n        cls,\n        process: ProcessHandler,\n        config: Any,\n        on_reply_sent: OnReplySent = None,\n        show_tool_details: bool = True,\n        filter_tool_messages: bool = False,\n        filter_thinking: bool = False,\n    ) -> \"WecomChannel\":\n        return cls(\n            process=process,\n            enabled=getattr(config, \"enabled\", False),\n            bot_id=getattr(config, \"bot_id\", \"\") or \"\",\n            secret=getattr(config, \"secret\", \"\") or \"\",\n            bot_prefix=getattr(config, \"bot_prefix\", \"[BOT] \") or \"[BOT] \",\n            media_dir=getattr(config, \"media_dir\", None) or \"\",\n            welcome_text=getattr(config, \"welcome_text\", \"\") or \"\",\n            on_reply_sent=on_reply_sent,\n            show_tool_details=show_tool_details,\n            filter_tool_messages=filter_tool_messages,\n            filter_thinking=filter_thinking,\n            dm_policy=getattr(config, \"dm_policy\", \"open\") or \"open\",\n            group_policy=getattr(config, \"group_policy\", \"open\") or \"open\",\n            allow_from=getattr(config, \"allow_from\", []) or [],\n            deny_message=getattr(config, \"deny_message\", \"\") or \"\",\n            max_reconnect_attempts=int(\n                -1\n                if getattr(config, \"max_reconnect_attempts\", None) is None\n                else getattr(config, \"max_reconnect_attempts\"),\n            ),\n        )\n\n    # ------------------------------------------------------------------\n    # Session / handle helpers\n    # ------------------------------------------------------------------\n\n    def resolve_session_id(\n        self,\n        sender_id: str,\n        channel_meta: Optional[Dict[str, Any]] = None,\n    ) -> str:\n        \"\"\"Build session_id from meta or sender_id.\"\"\"\n        meta = channel_meta or {}\n        chatid = (meta.get(\"wecom_chatid\") or \"\").strip()\n        chat_type = (meta.get(\"wecom_chat_type\") or \"single\").strip()\n        if chat_type == \"group\" and chatid:\n            return f\"wecom:group:{chatid}\"\n        if sender_id:\n            return f\"wecom:{sender_id}\"\n        return f\"wecom:{chatid or 'unknown'}\"\n\n    @staticmethod\n    def _parse_chatid_from_handle(to_handle: str) -> str:\n        \"\"\"Extract chatid/userid from a to_handle string.\n\n        - ``wecom:group:`` → ````\n        - ``wecom:``       → ````\n        \"\"\"\n        h = (to_handle or \"\").strip()\n        if h.startswith(\"wecom:group:\"):\n            return h[len(\"wecom:group:\") :]\n        if h.startswith(\"wecom:\"):\n            return h[len(\"wecom:\") :]\n        return h\n\n    def to_handle_from_target(self, *, user_id: str, session_id: str) -> str:\n        \"\"\"Return send handle; session_id takes priority.\"\"\"\n        return session_id or f\"wecom:{user_id}\"\n\n    def get_to_handle_from_request(self, request: Any) -> str:\n        session_id = getattr(request, \"session_id\", \"\") or \"\"\n        user_id = getattr(request, \"user_id\", \"\") or \"\"\n        return session_id or f\"wecom:{user_id}\"\n\n    def get_on_reply_sent_args(\n        self,\n        request: Any,\n        to_handle: str,\n    ) -> tuple:\n        return (\n            getattr(request, \"user_id\", \"\") or \"\",\n            getattr(request, \"session_id\", \"\") or \"\",\n        )\n\n    def build_agent_request_from_native(\n        self,\n        native_payload: Any,\n    ) -> \"AgentRequest\":\n        \"\"\"Build AgentRequest from a wecom native dict.\"\"\"\n        payload = native_payload if isinstance(native_payload, dict) else {}\n        channel_id = payload.get(\"channel_id\") or self.channel\n        sender_id = payload.get(\"sender_id\") or \"\"\n        content_parts = payload.get(\"content_parts\") or []\n        meta = payload.get(\"meta\") or {}\n        session_id = payload.get(\"session_id\") or self.resolve_session_id(\n            sender_id,\n            meta,\n        )\n        user_id = payload[\"user_id\"] if \"user_id\" in payload else sender_id\n        request = self.build_agent_request_from_user_content(\n            channel_id=channel_id,\n            sender_id=user_id,\n            session_id=session_id,\n            content_parts=content_parts,\n            channel_meta=meta,\n        )\n        setattr(request, \"channel_meta\", meta)\n        return request\n\n    def merge_native_items(self, items: List[Any]) -> Any:\n        \"\"\"Merge same-session native payloads: concat content_parts.\"\"\"\n        if not items:\n            return None\n        first = items[0] if isinstance(items[0], dict) else {}\n        merged_parts: List[Any] = []\n        for it in items:\n            p = it if isinstance(it, dict) else {}\n            merged_parts.extend(p.get(\"content_parts\") or [])\n        last = items[-1] if isinstance(items[-1], dict) else {}\n        return {\n            \"channel_id\": first.get(\"channel_id\") or self.channel,\n            \"sender_id\": last.get(\n                \"sender_id\",\n                first.get(\"sender_id\", \"\"),\n            ),\n            \"user_id\": last.get(\"user_id\", first.get(\"user_id\", \"\")),\n            \"session_id\": last.get(\n                \"session_id\",\n                first.get(\"session_id\", \"\"),\n            ),\n            \"content_parts\": merged_parts,\n            \"meta\": dict(last.get(\"meta\") or {}),\n        }\n\n    # ------------------------------------------------------------------\n    # Message dedup helper\n    # ------------------------------------------------------------------\n\n    def _is_duplicate(self, msg_id: str) -> bool:\n        \"\"\"Return True if msg_id was already seen; record it.\"\"\"\n        with self._processed_ids_lock:\n            if msg_id in self._processed_message_ids:\n                return True\n            self._processed_message_ids[msg_id] = None\n            while len(self._processed_message_ids) > _WECOM_PROCESSED_IDS_MAX:\n                self._processed_message_ids.popitem(last=False)\n        return False\n\n    # ------------------------------------------------------------------\n    # Incoming message handlers (called from WS thread, dispatch to loop)\n    # ------------------------------------------------------------------\n\n    def _on_message_sync(self, frame: Any) -> None:\n        \"\"\"Sync handler called from SDK event; dispatches to async loop.\"\"\"\n        if not self._loop or not self._loop.is_running():\n            logger.warning(\"wecom: main loop not set/running, drop message\")\n            return\n        asyncio.run_coroutine_threadsafe(\n            self._on_message(frame),\n            self._loop,\n        )\n\n    async def _on_message(self, frame: Any) -> None:\n        \"\"\"Parse and enqueue one incoming message.\"\"\"\n        try:\n            body = frame.get(\"body\") or {}\n            msgtype = body.get(\"msgtype\") or \"\"\n            sender_id = (body.get(\"from\") or {}).get(\"userid\", \"\")\n            chatid = body.get(\"chatid\", \"\")\n            chat_type = body.get(\"chattype\", \"single\")\n\n            # Build unique message id for dedup\n            msg_id = (\n                body.get(\"msgid\") or \"\"\n            ) or f\"{sender_id}_{body.get('send_time', '')}\"\n            if msg_id and self._is_duplicate(msg_id):\n                return\n\n            content_parts: List[Any] = []\n            text_parts: List[str] = []\n\n            if msgtype == \"text\":\n                text = (body.get(\"text\") or {}).get(\"content\", \"\").strip()\n                if text:\n                    text_parts.append(text)\n\n            elif msgtype == \"image\":\n                img_info = body.get(\"image\") or {}\n                url = img_info.get(\"url\") or \"\"\n                aes_key = img_info.get(\"aeskey\") or \"\"\n                if url:\n                    path = await self._download_media(\n                        url,\n                        aes_key=aes_key,\n                        filename_hint=\"image.jpg\",\n                    )\n                    if path:\n                        content_parts.append(\n                            ImageContent(\n                                type=ContentType.IMAGE,\n                                image_url=path,\n                            ),\n                        )\n                    else:\n                        text_parts.append(\"[image: download failed]\")\n                else:\n                    text_parts.append(\"[image: no url]\")\n\n            elif msgtype == \"voice\":\n                voice_info = body.get(\"voice\") or {}\n                # Use ASR text from WeCom; no need to download audio\n                asr_text = voice_info.get(\"content\", \"\").strip()\n                if asr_text:\n                    text_parts.append(asr_text)\n                else:\n                    text_parts.append(\"[voice: no text]\")\n\n            elif msgtype == \"file\":\n                file_info = body.get(\"file\") or {}\n                url = file_info.get(\"url\") or \"\"\n                aes_key = file_info.get(\"aeskey\") or \"\"\n                filename = file_info.get(\"filename\") or \"file.bin\"\n                if url:\n                    path = await self._download_media(\n                        url,\n                        aes_key=aes_key,\n                        filename_hint=filename,\n                    )\n                    if path:\n                        content_parts.append(\n                            FileContent(\n                                type=ContentType.FILE,\n                                file_url=path,\n                            ),\n                        )\n                    else:\n                        text_parts.append(\"[file: download failed]\")\n                else:\n                    text_parts.append(\"[file: no url]\")\n\n            elif msgtype == \"mixed\":\n                # Mixed: list of items, each has msgtype, text or image\n                mixed_items = body.get(\"mixed\", {}).get(\"msg_item\", [])\n                for item in mixed_items:\n                    itype = item.get(\"msgtype\") or \"\"\n                    if itype == \"text\":\n                        t = item.get(\"text\", {}).get(\"content\", \"\").strip()\n                        if t:\n                            text_parts.append(t)\n                    elif itype == \"image\":\n                        img = item.get(\"image\") or {}\n                        url = img.get(\"url\") or \"\"\n                        aes_key = img.get(\"aeskey\") or \"\"\n                        if url:\n                            path = await self._download_media(\n                                url,\n                                aes_key=aes_key,\n                                filename_hint=\"image.jpg\",\n                            )\n                            if path:\n                                content_parts.append(\n                                    ImageContent(\n                                        type=ContentType.IMAGE,\n                                        image_url=path,\n                                    ),\n                                )\n                            else:\n                                text_parts.append(\"[image: download failed]\")\n            else:\n                text_parts.append(f\"[{msgtype}]\")\n\n            text = \"\\n\".join(text_parts).strip()\n            if text:\n                content_parts.insert(\n                    0,\n                    TextContent(type=ContentType.TEXT, text=text),\n                )\n            if not content_parts:\n                return\n\n            is_group = chat_type == \"group\"\n            meta: Dict[str, Any] = {\n                \"wecom_sender_id\": sender_id,\n                \"wecom_chatid\": chatid,\n                \"wecom_chat_type\": chat_type,\n                \"wecom_frame\": frame,\n                \"is_group\": is_group,\n            }\n\n            allowed, error_msg = self._check_allowlist(sender_id, is_group)\n            if not allowed:\n                logger.info(\n                    \"wecom allowlist blocked: sender=%s is_group=%s\",\n                    sender_id,\n                    is_group,\n                )\n                await self._send_text_via_frame(\n                    frame,\n                    error_msg or \"Access denied.\",\n                )\n                return\n\n            # Send \"processing\" indicator only if message has text content\n            processing_stream_id = \"\"\n            if text_parts and self._client:\n                processing_stream_id = generate_req_id(\"stream\")\n                try:\n                    await self._client.reply_stream(\n                        frame,\n                        stream_id=processing_stream_id,\n                        content=\"🤔 思考中...\",\n                        finish=False,\n                    )\n                except Exception:\n                    logger.debug(\"wecom failed to send processing indicator\")\n\n            session_id = self.resolve_session_id(sender_id, meta)\n            if processing_stream_id:\n                meta[\"wecom_processing_stream_id\"] = processing_stream_id\n            native = {\n                \"channel_id\": self.channel,\n                \"sender_id\": sender_id,\n                # Group chats share one session; omit user_id so the\n                # session file is keyed by session_id only.\n                \"user_id\": \"\" if is_group else sender_id,\n                \"session_id\": session_id,\n                \"content_parts\": content_parts,\n                \"meta\": meta,\n            }\n            logger.info(\n                \"wecom recv: sender=%s chatid=%s msgtype=%s text_len=%s\",\n                sender_id[:20],\n                (chatid or \"\")[:20],\n                msgtype,\n                len(text),\n            )\n            if self._enqueue is not None:\n                self._enqueue(native)\n        except Exception:\n            logger.exception(\"wecom _on_message failed\")\n\n    def _on_enter_chat_sync(self, frame: Any) -> None:\n        \"\"\"Sync handler called from SDK event; dispatches to async loop.\"\"\"\n        if not self._loop or not self._loop.is_running():\n            logger.warning(\"wecom: main loop not set/running, drop enter_chat\")\n            return\n        asyncio.run_coroutine_threadsafe(\n            self._on_enter_chat(frame),\n            self._loop,\n        )\n\n    async def _on_enter_chat(self, frame: Any) -> None:\n        \"\"\"Handle enter_chat event; send welcome reply if configured.\"\"\"\n        logger.info(\"wecom enter_chat event\")\n        if not self.welcome_text or not self._client:\n            return\n        await self._client.reply_welcome(\n            frame,\n            {\"msgtype\": \"text\", \"text\": {\"content\": self.welcome_text}},\n        )\n\n    # ------------------------------------------------------------------\n    # File download helper\n    # ------------------------------------------------------------------\n\n    async def _download_media(\n        self,\n        url: str,\n        aes_key: str = \"\",\n        filename_hint: str = \"file.bin\",\n    ) -> Optional[str]:\n        \"\"\"Download (and optionally decrypt) media; return local path.\"\"\"\n        if not self._client:\n            return None\n        try:\n            data, filename = await self._client.download_file(\n                url,\n                aes_key or None,\n            )\n            fn = filename or filename_hint\n            # Determine extension from hint if file has none\n            hint_ext = Path(filename_hint).suffix\n            if hint_ext and Path(fn).suffix in (\"\", \".bin\", \".file\"):\n                fn = (Path(fn).stem or \"file\") + hint_ext\n            self._media_dir.mkdir(parents=True, exist_ok=True)\n            safe_name = (\n                \"\".join(c for c in fn if c.isalnum() or c in \"-_.\") or \"media\"\n            )\n            url_hash = hashlib.md5(url.encode()).hexdigest()[:8]\n            path = self._media_dir / f\"wecom_{url_hash}_{safe_name}\"\n            path.write_bytes(data)\n            return str(path)\n        except Exception:\n            logger.exception(\"wecom _download_media failed url=%s\", url[:60])\n            return None\n\n    # ------------------------------------------------------------------\n    # Send helpers\n    # ------------------------------------------------------------------\n\n    async def _send_text_via_frame(\n        self,\n        frame: Any,\n        text: str,\n        stream_id: str = \"\",\n    ) -> None:\n        \"\"\"Send a text reply using the SDK reply method (stream finish).\n\n        Args:\n            frame: WebSocket frame from the incoming message.\n            text: Content to send.\n            stream_id: Optional stream ID to overwrite existing message.\n                       If empty, a new UUID is generated.\n        \"\"\"\n        if not self._client or not text:\n            return\n        try:\n            sid = stream_id or generate_req_id(\"stream\")\n            await self._client.reply_stream(\n                frame,\n                stream_id=sid,\n                content=text,\n                finish=True,\n            )\n        except Exception:\n            logger.exception(\"wecom _send_text_via_frame failed\")\n\n    async def _send_image_via_send_message(\n        self,\n        chatid: str,\n        part: OutgoingContentPart,\n    ) -> None:\n        \"\"\"Send image as markdown inline (best-effort via send_message).\"\"\"\n        if not self._client or not chatid:\n            return\n        image_url = getattr(part, \"image_url\", \"\") or \"\"\n        if not image_url:\n            return\n        # WeCom does not support uploading images via WS; use markdown link\n        try:\n            await self._client.send_message(\n                chatid,\n                {\n                    \"msgtype\": \"markdown\",\n                    \"markdown\": {\"content\": f\"![image]({image_url})\"},\n                },\n            )\n        except Exception:\n            logger.exception(\"wecom _send_image_via_send_message failed\")\n\n    async def send_content_parts(\n        self,\n        to_handle: str,\n        parts: List[OutgoingContentPart],\n        meta: Optional[Dict[str, Any]] = None,\n    ) -> None:\n        \"\"\"Send text (stream) and media parts back to WeCom.\"\"\"\n        if not self.enabled:\n            return\n        m = meta or {}\n        frame = m.get(\"wecom_frame\")\n        chatid = (\n            m.get(\"wecom_chatid\")\n            or self._parse_chatid_from_handle(to_handle)\n            or \"\"\n        )\n\n        prefix = m.get(\"bot_prefix\", \"\") or self.bot_prefix or \"\"\n        text_parts: List[str] = []\n        media_parts: List[OutgoingContentPart] = []\n\n        for p in parts:\n            t = getattr(p, \"type\", None) or (\n                p.get(\"type\") if isinstance(p, dict) else None\n            )\n            text_val = getattr(p, \"text\", None) or (\n                p.get(\"text\") if isinstance(p, dict) else None\n            )\n            refusal_val = getattr(p, \"refusal\", None) or (\n                p.get(\"refusal\") if isinstance(p, dict) else None\n            )\n            if t == ContentType.TEXT and text_val:\n                text_parts.append(text_val)\n            elif t == ContentType.REFUSAL and refusal_val:\n                text_parts.append(refusal_val)\n            elif t in (\n                ContentType.IMAGE,\n                ContentType.FILE,\n                ContentType.VIDEO,\n                ContentType.AUDIO,\n            ):\n                media_parts.append(p)\n\n        body = \"\\n\".join(text_parts).strip()\n        if prefix and body:\n            body = prefix + body\n\n        # Format markdown tables for WeCom compatibility\n        body = format_markdown_tables(body)\n\n        # Use processing stream_id to overwrite \"thinking...\" indicator\n        # Only first reply uses it; subsequent replies get new stream_id\n        processing_sid = m.pop(\"wecom_processing_stream_id\", \"\")\n\n        if body and frame:\n            await self._send_text_via_frame(frame, body, processing_sid)\n        elif body and chatid:\n            # Proactive send without an inbound frame\n            try:\n                await self._client.send_message(\n                    chatid,\n                    {\n                        \"msgtype\": \"markdown\",\n                        \"markdown\": {\"content\": body},\n                    },\n                )\n            except Exception:\n                logger.exception(\"wecom send_content_parts proactive failed\")\n\n        # # the SDK does not support sending media files.\n        # for part in media_parts:\n        #     pt = getattr(part, \"type\", None)\n        #     if pt == ContentType.IMAGE and chatid:\n        #         await self._send_image_via_send_message(chatid, part)\n        #     elif pt in (\n        #         ContentType.FILE, ContentType.AUDIO, ContentType.VIDEO\n        #     ):\n        #         # Send file path/url as markdown link (WS channel limitation)\n        #         file_url = (\n        #             getattr(part, \"file_url\", \"\")\n        #             or getattr(part, \"video_url\", \"\")\n        #             or \"\"\n        #         )\n        #         if file_url and chatid:\n        #             filename = Path(file_url).name or \"file\"\n        #             try:\n        #                 await self._client.send_message(\n        #                     chatid,\n        #                     {\n        #                         \"msgtype\": \"markdown\",\n        #                         \"markdown\": {\n        #                             \"content\": f\"[{filename}]({file_url})\"\n        #                         },\n        #                     },\n        #                 )\n        #             except Exception:\n        #                 logger.exception(\n        #                     \"wecom send_content_parts file link failed\"\n        #                 )\n\n    async def send(\n        self,\n        to_handle: str,\n        text: str,\n        meta: Optional[Dict[str, Any]] = None,\n    ) -> None:\n        \"\"\"Proactive send: use send_message with markdown body.\"\"\"\n        if not self.enabled:\n            return\n        m = meta or {}\n        chatid = (\n            m.get(\"wecom_chatid\")\n            or self._parse_chatid_from_handle(to_handle)\n            or \"\"\n        )\n        frame = m.get(\"wecom_frame\")\n        prefix = m.get(\"bot_prefix\", \"\") or self.bot_prefix or \"\"\n        body = (prefix + text) if text else prefix\n\n        if not body:\n            return\n\n        if frame:\n            await self._send_text_via_frame(frame, body)\n        elif chatid and self._client:\n            try:\n                await self._client.send_message(\n                    chatid,\n                    {\n                        \"msgtype\": \"markdown\",\n                        \"markdown\": {\"content\": body},\n                    },\n                )\n            except Exception:\n                logger.exception(\n                    \"wecom send proactive failed chatid=%s\",\n                    chatid,\n                )\n        else:\n            logger.warning(\n                \"wecom send: no frame/chatid for to_handle=%s\",\n                (to_handle or \"\")[:40],\n            )\n\n    # ------------------------------------------------------------------\n    # Lifecycle\n    # ------------------------------------------------------------------\n\n    def _run_ws_forever(self) -> None:\n        \"\"\"Background thread: run SDK event loop forever.\"\"\"\n        # macOS/Python 3.12+ fix: use SelectorEventLoop explicitly\n        if sys.platform == \"darwin\":\n            ws_loop = asyncio.SelectorEventLoop()\n        else:\n            ws_loop = asyncio.new_event_loop()\n        asyncio.set_event_loop(ws_loop)\n        self._ws_loop = ws_loop\n\n        # Set thread name for debugging\n        threading.current_thread().name = \"wecom-ws\"\n\n        try:\n            # Run connection in the new loop\n            ws_loop.run_until_complete(self._client.connect())\n            ws_loop.run_forever()\n        except Exception:\n            logger.exception(\"wecom WebSocket thread failed\")\n        finally:\n            try:\n                # Cancel all pending tasks\n                pending = asyncio.all_tasks(ws_loop)\n                for task in pending:\n                    task.cancel()\n                if pending:\n                    ws_loop.run_until_complete(\n                        asyncio.gather(*pending, return_exceptions=True),\n                    )\n                ws_loop.run_until_complete(ws_loop.shutdown_asyncgens())\n                ws_loop.close()\n            except Exception:\n                pass\n            self._ws_loop = None\n\n    async def start(self) -> None:\n        if not self.enabled:\n            logger.debug(\"wecom channel disabled\")\n            return\n\n        if not self.bot_id or not self.secret:\n            raise RuntimeError(\n                \"WECOM_BOT_ID and WECOM_SECRET are required when \"\n                \"the wecom channel is enabled.\",\n            )\n\n        self._loop = asyncio.get_running_loop()\n        options = WSClientOptions(\n            bot_id=self.bot_id,\n            secret=self.secret,\n            max_reconnect_attempts=self._max_reconnect_attempts,\n        )\n        self._client = WSClient(options)\n\n        # Register event handlers\n        self._client.on(\"message\", self._on_message_sync)\n        self._client.on(\"event.enter_chat\", self._on_enter_chat_sync)\n\n        self._ws_thread = threading.Thread(\n            target=self._run_ws_forever,\n            daemon=True,\n            name=\"wecom-ws\",\n        )\n        self._ws_thread.start()\n        logger.info(\n            \"wecom channel started (bot_id=%s)\",\n            (self.bot_id or \"\")[:12],\n        )\n\n    async def stop(self) -> None:\n        if not self.enabled:\n            return\n        if self._client:\n            try:\n                self._client.disconnect()\n            except Exception:\n                pass\n        if self._ws_loop is not None:\n            try:\n                self._ws_loop.call_soon_threadsafe(self._ws_loop.stop)\n            except Exception:\n                pass\n        if self._ws_thread:\n            self._ws_thread.join(timeout=5)\n        self._client = None\n        logger.info(\"wecom channel stopped\")\n"
  },
  {
    "path": "src/copaw/app/channels/wecom/utils.py",
    "content": "# -*- coding: utf-8 -*-\n\"\"\"WeCom channel utilities.\"\"\"\nfrom __future__ import annotations\n\nimport re\nfrom typing import List\n\n\ndef format_markdown_tables(text: str) -> str:\n    \"\"\"Format GFM markdown tables for WeCom compatibility.\n\n    WeCom requires table columns to be properly aligned.\n    This function normalizes table formatting.\n\n    Args:\n        text: Input markdown text possibly containing tables.\n\n    Returns:\n        Text with formatted tables.\n    \"\"\"\n    lines = text.split(\"\\n\")\n    result: List[str] = []\n    i = 0\n    in_code_fence = False\n    while i < len(lines):\n        line = lines[i]\n        stripped = line.strip()\n        # Track fenced code blocks (```), pass through inside lines unchanged.\n        if stripped.startswith(\"```\"):\n            in_code_fence = not in_code_fence\n            result.append(line)\n            i += 1\n            continue\n        if in_code_fence:\n            result.append(line)\n            i += 1\n            continue\n        # Detect table start (line with |) when not inside a code fence\n        if \"|\" in line:\n            # Collect table lines\n            table_lines: List[str] = []\n            while (\n                i < len(lines)\n                and \"|\" in lines[i]\n                and not lines[i].strip().startswith(\"```\")\n            ):\n                table_lines.append(lines[i])\n                i += 1\n            # Format and add table\n            if table_lines:\n                result.extend(_format_table(table_lines))\n            continue\n        result.append(line)\n        i += 1\n    return \"\\n\".join(result)\n\n\ndef _format_table(lines: List[str]) -> List[str]:\n    \"\"\"Format a single markdown table.\"\"\"\n    if not lines:\n        return lines\n\n    # Check if second row is separator (contains only -, :, |, spaces)\n    sep_pattern = re.compile(r\"^[\\s\\-:|]+$\")\n    has_separator = len(lines) >= 2 and sep_pattern.match(lines[1]) is not None\n\n    # Parse cells, skipping the separator row (it will be rebuilt)\n    rows: List[List[str]] = []\n    for idx, line in enumerate(lines):\n        if has_separator and idx == 1:\n            continue  # Skip separator row; rebuild it from column widths\n        cells = [c.strip() for c in line.split(\"|\")]\n        # Remove empty first/last cells from leading/trailing |\n        if cells and not cells[0]:\n            cells = cells[1:]\n        if cells and not cells[-1]:\n            cells = cells[:-1]\n        if cells:\n            rows.append(cells)\n\n    if not rows:\n        return lines\n\n    # Calculate column widths\n    col_count = max(len(r) for r in rows)\n    widths: List[int] = [0] * col_count\n    for row in rows:\n        for j in range(col_count):\n            cell = row[j] if j < len(row) else \"\"\n            widths[j] = max(widths[j], len(cell))\n\n    # Format rows with proper padding, inserting separator after header\n    formatted: List[str] = []\n    for idx, row in enumerate(rows):\n        padded = [\n            (row[j] if j < len(row) else \"\").ljust(widths[j])\n            for j in range(col_count)\n        ]\n        formatted.append(\"| \" + \" | \".join(padded) + \" |\")\n        if idx == 0:\n            sep = (\n                \"| \"\n                + \" | \".join(\"-\" * max(3, widths[j]) for j in range(col_count))\n                + \" |\"\n            )\n            formatted.append(sep)\n\n    return formatted\n"
  },
  {
    "path": "src/copaw/app/channels/xiaoyi/__init__.py",
    "content": "# -*- coding: utf-8 -*-\n\"\"\"XiaoYi channel module.\n\nXiaoYi (小艺) is Huawei's voice assistant platform.\nThis module implements A2A (Agent-to-Agent) protocol support.\n\"\"\"\n\nfrom .channel import XiaoYiChannel\nfrom .auth import generate_auth_headers\nfrom .constants import DEFAULT_WS_URL\n\n__all__ = [\n    \"XiaoYiChannel\",\n    \"generate_auth_headers\",\n    \"DEFAULT_WS_URL\",\n]\n"
  },
  {
    "path": "src/copaw/app/channels/xiaoyi/auth.py",
    "content": "# -*- coding: utf-8 -*-\n\"\"\"\nXiaoYi authentication using AK/SK mechanism.\n\"\"\"\n\nfrom __future__ import annotations\n\nimport base64\nimport hashlib\nimport hmac\nimport time\nfrom typing import Dict\n\n\ndef generate_signature(sk: str, timestamp: str) -> str:\n    \"\"\"Generate HMAC-SHA256 signature.\n\n    Format: Base64(HMAC-SHA256(secretKey, timestamp))\n\n    Args:\n        sk: Secret Key\n        timestamp: Timestamp as string (milliseconds)\n\n    Returns:\n        Base64 encoded signature\n    \"\"\"\n    hmac_obj = hmac.new(sk.encode(), timestamp.encode(), hashlib.sha256)\n    return base64.b64encode(hmac_obj.digest()).decode()\n\n\ndef generate_auth_headers(ak: str, sk: str, agent_id: str) -> Dict[str, str]:\n    \"\"\"Generate WebSocket authentication headers.\n\n    Args:\n        ak: Access Key\n        sk: Secret Key\n        agent_id: Agent ID\n\n    Returns:\n        Dict of headers for WebSocket connection\n    \"\"\"\n    timestamp = str(int(time.time() * 1000))\n    signature = generate_signature(sk, timestamp)\n\n    return {\n        \"x-access-key\": ak,\n        \"x-sign\": signature,\n        \"x-ts\": timestamp,\n        \"x-agent-id\": agent_id,\n    }\n"
  },
  {
    "path": "src/copaw/app/channels/xiaoyi/channel.py",
    "content": "# -*- coding: utf-8 -*-\n\"\"\"XiaoYi Channel implementation.\n\nXiaoYi uses A2A (Agent-to-Agent) protocol over WebSocket.\n\"\"\"\n\nfrom __future__ import annotations\n\nimport asyncio\nimport json\nimport logging\nimport uuid\nfrom pathlib import Path\nfrom typing import Any, Dict, List, Optional, TYPE_CHECKING\n\nimport aiohttp\n\nfrom agentscope_runtime.engine.schemas.agent_schemas import (\n    FileContent,\n    ImageContent,\n    ContentType,\n    TextContent,\n)\n\nfrom ....config.config import XiaoYiConfig as XiaoYiChannelConfig\nfrom ....constant import DEFAULT_MEDIA_DIR\nfrom ..base import (\n    BaseChannel,\n    OnReplySent,\n    OutgoingContentPart,\n    ProcessHandler,\n)\nfrom .auth import generate_auth_headers\nfrom .constants import (\n    CONNECTION_TIMEOUT,\n    DEFAULT_TASK_TIMEOUT_MS,\n    HEARTBEAT_INTERVAL,\n    MAX_RECONNECT_ATTEMPTS,\n    RECONNECT_DELAYS,\n    TEXT_CHUNK_LIMIT,\n)\nfrom .utils import download_file\n\nlogger = logging.getLogger(__name__)\n\nif TYPE_CHECKING:\n    from agentscope_runtime.engine.schemas.agent_schemas import AgentRequest\n\n\n# Class-level registry to track active connections per agent_id\n_active_connections: Dict[str, \"XiaoYiChannel\"] = {}\n_active_connections_lock = asyncio.Lock()\n\n\nclass XiaoYiChannel(BaseChannel):\n    \"\"\"XiaoYi channel using A2A protocol over WebSocket.\n\n    This channel connects to XiaoYi server as a WebSocket client\n    and handles A2A (Agent-to-Agent) protocol messages.\n    \"\"\"\n\n    channel = \"xiaoyi\"\n    uses_manager_queue = True\n\n    def __init__(\n        self,\n        process: ProcessHandler,\n        enabled: bool,\n        ak: str,\n        sk: str,\n        agent_id: str,\n        ws_url: str,\n        task_timeout_ms: int = DEFAULT_TASK_TIMEOUT_MS,\n        on_reply_sent: OnReplySent = None,\n        show_tool_details: bool = True,\n        filter_tool_messages: bool = False,\n        filter_thinking: bool = False,\n        bot_prefix: str = \"\",\n        media_dir: str = \"\",\n        workspace_dir: Path | None = None,\n    ):\n        super().__init__(\n            process,\n            on_reply_sent=on_reply_sent,\n            show_tool_details=show_tool_details,\n            filter_tool_messages=filter_tool_messages,\n            filter_thinking=filter_thinking,\n        )\n\n        self.enabled = enabled\n        self.ak = ak\n        self.sk = sk\n        self.agent_id = agent_id\n        self.ws_url = ws_url\n        self.task_timeout_ms = task_timeout_ms\n        self.bot_prefix = bot_prefix\n\n        # Workspace directory for agent-specific storage\n        self._workspace_dir = (\n            Path(workspace_dir).expanduser() if workspace_dir else None\n        )\n\n        # Use workspace-specific media dir if workspace_dir is provided\n        if not media_dir and self._workspace_dir:\n            self._media_dir = self._workspace_dir / \"media\"\n        elif media_dir:\n            self._media_dir = Path(media_dir).expanduser()\n        else:\n            self._media_dir = DEFAULT_MEDIA_DIR / \"xiaoyi\"\n        self._media_dir.mkdir(parents=True, exist_ok=True)\n\n        # WebSocket state\n        self._ws: Optional[aiohttp.ClientWebSocketResponse] = None\n        self._session: Optional[aiohttp.ClientSession] = None\n        self._connected = False\n        self._reconnect_attempts = 0\n        self._stopping = False  # Flag to prevent reconnect during stop\n\n        # Session -> task_id mapping\n        self._session_task_map: Dict[str, str] = {}\n\n        # Heartbeat task\n        self._heartbeat_task: Optional[asyncio.Task] = None\n\n        # Receive loop task\n        self._receive_task: Optional[asyncio.Task] = None\n\n    @classmethod\n    def from_env(\n        cls,\n        process: ProcessHandler,\n        on_reply_sent: OnReplySent = None,\n    ) -> \"XiaoYiChannel\":\n        \"\"\"Create channel from environment variables.\"\"\"\n        import os\n\n        return cls(\n            process=process,\n            enabled=os.getenv(\"XIAOYI_CHANNEL_ENABLED\", \"0\") == \"1\",\n            ak=os.getenv(\"XIAOYI_AK\", \"\"),\n            sk=os.getenv(\"XIAOYI_SK\", \"\"),\n            agent_id=os.getenv(\"XIAOYI_AGENT_ID\", \"\"),\n            ws_url=os.getenv(\n                \"XIAOYI_WS_URL\",\n                \"wss://hag.cloud.huawei.com/openclaw/v1/ws/link\",\n            ),\n            on_reply_sent=on_reply_sent,\n            media_dir=os.getenv(\"XIAOYI_MEDIA_DIR\", \"\"),\n        )\n\n    @classmethod\n    def from_config(\n        cls,\n        process: ProcessHandler,\n        config: XiaoYiChannelConfig,\n        on_reply_sent: OnReplySent = None,\n        show_tool_details: bool = True,\n        filter_tool_messages: bool = False,\n        filter_thinking: bool = False,\n        workspace_dir: Path | None = None,\n    ) -> \"XiaoYiChannel\":\n        if isinstance(config, dict):\n            return cls(\n                process=process,\n                enabled=config.get(\"enabled\", False),\n                ak=config.get(\"ak\", \"\"),\n                sk=config.get(\"sk\", \"\"),\n                agent_id=config.get(\"agent_id\", \"\"),\n                ws_url=config.get(\n                    \"ws_url\",\n                    \"wss://hag.cloud.huawei.com/openclaw/v1/ws/link\",\n                ),\n                task_timeout_ms=config.get(\n                    \"task_timeout_ms\",\n                    DEFAULT_TASK_TIMEOUT_MS,\n                ),\n                on_reply_sent=on_reply_sent,\n                show_tool_details=show_tool_details,\n                filter_tool_messages=filter_tool_messages,\n                filter_thinking=filter_thinking,\n                bot_prefix=config.get(\"bot_prefix\", \"\"),\n                media_dir=config.get(\"media_dir\", \"\"),\n                workspace_dir=workspace_dir,\n            )\n\n        return cls(\n            process=process,\n            enabled=config.enabled,\n            ak=config.ak,\n            sk=config.sk,\n            agent_id=config.agent_id,\n            ws_url=config.ws_url,\n            task_timeout_ms=config.task_timeout_ms,\n            on_reply_sent=on_reply_sent,\n            show_tool_details=show_tool_details,\n            filter_tool_messages=filter_tool_messages,\n            filter_thinking=filter_thinking,\n            bot_prefix=config.bot_prefix,\n            media_dir=getattr(config, \"media_dir\", \"\"),\n            workspace_dir=workspace_dir,\n        )\n\n    def _validate_config(self) -> None:\n        \"\"\"Validate required configuration.\"\"\"\n        if not self.ak:\n            raise ValueError(\"XiaoYi AK (Access Key) is required\")\n        if not self.sk:\n            raise ValueError(\"XiaoYi SK (Secret Key) is required\")\n        if not self.agent_id:\n            raise ValueError(\"XiaoYi Agent ID is required\")\n\n    async def start(self) -> None:\n        \"\"\"Start WebSocket connection.\"\"\"\n        if not self.enabled:\n            logger.debug(\"XiaoYi: start() skipped (enabled=false)\")\n            return\n\n        try:\n            self._validate_config()\n        except ValueError as e:\n            logger.error(f\"XiaoYi config validation failed: {e}\")\n            return\n\n        # Check if there's already an active connection for this agent_id\n        # and reuse it if only filter settings changed\n        global _active_connections\n        should_connect = True\n        async with _active_connections_lock:\n            existing = _active_connections.get(self.agent_id)\n            if (\n                existing is not None\n                and existing is not self\n                and existing._connected  # pylint: disable=protected-access\n            ):\n                # pylint: disable=protected-access\n                # Found active connection - update settings\n                logger.info(\n                    \"XiaoYi: Updating settings for existing \"\n                    f\"connection agent_id={self.agent_id}\",\n                )\n                # Update render style settings on the existing channel\n                existing._render_style.filter_tool_messages = (\n                    self._render_style.filter_tool_messages\n                )\n                existing._render_style.filter_thinking = (\n                    self._render_style.filter_thinking\n                )\n                existing._render_style.show_tool_details = (\n                    self._render_style.show_tool_details\n                )\n                # Re-register this instance\n                # (so the new instance becomes the active one)\n                _active_connections[self.agent_id] = self\n                # Copy the WebSocket state to this instance\n                self._ws = existing._ws\n                self._session = existing._session\n                self._connected = existing._connected\n                self._heartbeat_task = existing._heartbeat_task\n                self._receive_task = existing._receive_task\n                self._session_task_map = existing._session_task_map\n                # Mark old instance as not owning the connection anymore\n                existing._ws = None\n                existing._session = None\n                existing._connected = False\n                existing._heartbeat_task = None\n                existing._receive_task = None\n                should_connect = False\n\n        if not should_connect:\n            logger.info(\n                \"XiaoYi: Reused existing connection with updated settings\",\n            )\n            return\n\n        # No existing connection or can't reuse - start new connection\n        await self._wait_and_register_connection()\n\n        logger.info(f\"XiaoYi: Connecting to {self.ws_url}...\")\n\n        try:\n            await self._connect()\n        except Exception as e:\n            logger.error(f\"XiaoYi connection failed: {e}\")\n            # Unregister on failure\n            await self._unregister_connection()\n            self._schedule_reconnect()\n\n    async def _wait_and_register_connection(self) -> None:\n        \"\"\"Stop any existing connection with same agent_id, then register.\"\"\"\n        global _active_connections\n\n        # First, get existing connection and remove it from registry\n        existing = None\n        async with _active_connections_lock:\n            existing = _active_connections.get(self.agent_id)\n            if existing is not None and existing is not self:\n                # Remove from registry immediately\n                _active_connections.pop(self.agent_id, None)\n            # Register this instance\n            _active_connections[self.agent_id] = self\n\n        # Now stop the old connection outside the lock\n        if existing is not None and existing is not self:\n            # pylint: disable=protected-access\n            logger.info(\n                \"XiaoYi: Stopping old connection for \"\n                f\"agent_id={self.agent_id}\",\n            )\n            try:\n                # Set stopping flag FIRST to prevent any reconnect\n                existing._stopping = True\n                existing._connected = False\n                # Cancel tasks and wait for them to finish\n                if existing._heartbeat_task:\n                    existing._heartbeat_task.cancel()\n                    try:\n                        await existing._heartbeat_task\n                    except asyncio.CancelledError:\n                        pass\n                if existing._receive_task:\n                    existing._receive_task.cancel()\n                    try:\n                        await existing._receive_task\n                    except asyncio.CancelledError:\n                        pass\n                # Close WebSocket\n                if existing._ws:\n                    await existing._ws.close()\n                if existing._session:\n                    await existing._session.close()\n                logger.debug(\"XiaoYi: Old connection stopped\")\n            except Exception as e:\n                logger.debug(f\"XiaoYi: Error stopping old connection: {e}\")\n\n        logger.debug(\n            f\"XiaoYi: Registered connection for agent_id={self.agent_id}\",\n        )\n\n    async def _unregister_connection(self) -> None:\n        \"\"\"Unregister this connection from active connections.\"\"\"\n        global _active_connections\n        async with _active_connections_lock:\n            if _active_connections.get(self.agent_id) is self:\n                _active_connections.pop(self.agent_id, None)\n                logger.debug(\n                    \"XiaoYi: Unregistered connection for \"\n                    f\"agent_id={self.agent_id}\",\n                )\n\n    async def _connect(self) -> None:\n        \"\"\"Establish WebSocket connection.\"\"\"\n        headers = generate_auth_headers(self.ak, self.sk, self.agent_id)\n\n        # Clean up any existing session first\n        await self._cleanup_session()\n\n        self._session = aiohttp.ClientSession()\n        ws_timeout = aiohttp.ClientWSTimeout(ws_close=CONNECTION_TIMEOUT)\n\n        try:\n            self._ws = await self._session.ws_connect(\n                self.ws_url,\n                headers=headers,\n                timeout=ws_timeout,\n            )\n\n            self._connected = True\n            self._reconnect_attempts = 0\n            logger.info(\"XiaoYi: WebSocket connected\")\n\n            # Send init message\n            await self._send_init_message()\n\n            # Start heartbeat\n            self._heartbeat_task = asyncio.create_task(self._heartbeat_loop())\n\n            # Start receive loop\n            self._receive_task = asyncio.create_task(self._receive_loop())\n\n        except Exception as e:\n            logger.error(f\"XiaoYi: WebSocket connection error: {e}\")\n            self._connected = False\n            raise\n\n    async def _send_init_message(self) -> None:\n        \"\"\"Send init message to server.\"\"\"\n        if not self._ws:\n            return\n\n        init_msg = {\n            \"msgType\": \"clawd_bot_init\",\n            \"agentId\": self.agent_id,\n        }\n\n        try:\n            await self._ws.send_json(init_msg)\n        except Exception as e:\n            logger.error(f\"XiaoYi: Failed to send init message: {e}\")\n\n    async def _heartbeat_loop(self) -> None:\n        \"\"\"Send heartbeat messages periodically.\"\"\"\n        while self._connected and self._ws:\n            try:\n                await asyncio.sleep(HEARTBEAT_INTERVAL)\n\n                if not self._connected or not self._ws:\n                    break\n\n                heartbeat_msg = {\n                    \"msgType\": \"heartbeat\",\n                    \"agentId\": self.agent_id,\n                }\n\n                await self._ws.send_json(heartbeat_msg)\n\n            except asyncio.CancelledError:\n                break\n            except Exception as e:\n                logger.error(f\"XiaoYi: Heartbeat error: {e}\")\n                break\n\n    async def _receive_loop(self) -> None:\n        \"\"\"Receive and process messages from WebSocket.\"\"\"\n        if not self._ws:\n            return\n\n        try:\n            async for msg in self._ws:\n                if msg.type == aiohttp.WSMsgType.TEXT:\n                    await self._handle_message(msg.data)\n                elif msg.type == aiohttp.WSMsgType.ERROR:\n                    logger.error(\n                        f\"XiaoYi: WebSocket error: {self._ws.exception()}\",\n                    )\n                    break\n                elif msg.type == aiohttp.WSMsgType.CLOSED:\n                    logger.info(\"XiaoYi: WebSocket closed\")\n                    break\n        except asyncio.CancelledError:\n            pass\n        except Exception as e:\n            logger.error(f\"XiaoYi: Receive loop error: {e}\")\n        finally:\n            self._connected = False\n            # Only reconnect if not stopping\n            if not self._stopping:\n                self._schedule_reconnect()\n\n    async def _handle_message(self, data: str) -> None:\n        \"\"\"Handle incoming WebSocket message.\"\"\"\n        try:\n            message = json.loads(data)\n            logger.debug(\n                \"XiaoYi: Received message: \"\n                f\"{json.dumps(message, indent=2)}\",\n            )\n\n            # Validate agent_id\n            if message.get(\"agentId\") and message[\"agentId\"] != self.agent_id:\n                logger.warning(\n                    \"XiaoYi: Mismatched agentId \"\n                    f\"{message['agentId']}, expected {self.agent_id}\",\n                )\n                return\n\n            # Handle clear context\n            if (\n                message.get(\"method\") == \"clearContext\"\n                or message.get(\"action\") == \"clear\"\n            ):\n                await self._handle_clear_context(message)\n                return\n\n            # Handle tasks cancel\n            if (\n                message.get(\"method\") == \"tasks/cancel\"\n                or message.get(\"action\") == \"tasks/cancel\"\n            ):\n                await self._handle_tasks_cancel(message)\n                return\n\n            # Handle A2A request\n            if message.get(\"method\") == \"message/stream\":\n                await self._handle_a2a_request(message)\n\n        except json.JSONDecodeError as e:\n            logger.error(f\"XiaoYi: Failed to parse message: {e}\")\n        except Exception as e:\n            logger.error(f\"XiaoYi: Error handling message: {e}\", exc_info=True)\n\n    async def _handle_a2a_request(self, message: Dict[str, Any]) -> None:\n        \"\"\"Handle A2A request message.\"\"\"\n        try:\n            session_id = message.get(\"params\", {}).get(\n                \"sessionId\",\n            ) or message.get(\"sessionId\")\n            task_id = message.get(\"params\", {}).get(\"id\") or message.get(\"id\")\n\n            if not session_id:\n                logger.warning(\"XiaoYi: No sessionId in message\")\n                return\n\n            self._session_task_map[session_id] = task_id\n\n            # Extract content parts\n            text_parts: List[str] = []\n            content_parts: List[Any] = []\n            params = message.get(\"params\", {})\n            msg = params.get(\"message\", {})\n            parts = msg.get(\"parts\", [])\n\n            for part in parts:\n                kind = part.get(\"kind\")\n                if kind == \"text\" and part.get(\"text\"):\n                    text_parts.append(part[\"text\"])\n                elif kind == \"file\":\n                    await self._process_file_part(\n                        part,\n                        text_parts,\n                        content_parts,\n                    )\n\n            # Build content\n            text_content = \" \".join(text_parts).strip()\n            if text_content:\n                content_parts.insert(\n                    0,\n                    TextContent(type=ContentType.TEXT, text=text_content),\n                )\n\n            if not content_parts:\n                logger.debug(\"XiaoYi: Empty message content, skipping\")\n                return\n\n            native = {\n                \"channel_id\": self.channel,\n                \"sender_id\": session_id,\n                \"content_parts\": content_parts,\n                \"meta\": {\n                    \"session_id\": session_id,\n                    \"task_id\": task_id,\n                    \"message_id\": message.get(\"id\"),\n                },\n            }\n\n            if self._enqueue:\n                self._enqueue(native)\n            else:\n                logger.warning(\"XiaoYi: _enqueue not set, message dropped\")\n\n        except Exception as e:\n            logger.error(\n                f\"XiaoYi: Error handling A2A request: {e}\",\n                exc_info=True,\n            )\n\n    async def _process_file_part(\n        self,\n        part: Dict[str, Any],\n        text_parts: List[str],\n        content_parts: List[Any],\n    ) -> None:\n        \"\"\"Process a file part from A2A message.\"\"\"\n        file_info = part.get(\"file\", {})\n        file_url = file_info.get(\"uri\", \"\")\n        filename = file_info.get(\"name\", \"file\")\n        mime_type = file_info.get(\"mimeType\", \"\")\n\n        if not file_url:\n            return\n\n        local_path = await download_file(\n            url=file_url,\n            media_dir=self._media_dir,\n            filename=filename,\n        )\n\n        if not local_path:\n            text_parts.append(f\"[{filename}: download failed]\")\n            return\n\n        if mime_type.startswith(\"image/\"):\n            content_parts.append(\n                ImageContent(\n                    type=ContentType.IMAGE,\n                    image_url=local_path,\n                ),\n            )\n        else:\n            content_parts.append(\n                FileContent(\n                    type=ContentType.FILE,\n                    file_url=local_path,\n                    filename=filename,\n                ),\n            )\n\n    async def _handle_clear_context(self, message: Dict[str, Any]) -> None:\n        \"\"\"Handle clear context message.\"\"\"\n        session_id = message.get(\"sessionId\") or \"\"\n        request_id = message.get(\"id\") or \"\"\n\n        logger.info(f\"XiaoYi: Clear context for session {session_id}\")\n\n        # Send clear response\n        await self._send_clear_context_response(request_id, session_id)\n\n        # Clean up session\n        if session_id:\n            self._session_task_map.pop(session_id, None)\n\n    async def _handle_tasks_cancel(self, message: Dict[str, Any]) -> None:\n        \"\"\"Handle tasks cancel message.\"\"\"\n        session_id = message.get(\"sessionId\") or \"\"\n        request_id = message.get(\"id\") or \"\"\n        task_id = message.get(\"taskId\") or request_id\n\n        logger.info(f\"XiaoYi: Cancel task {task_id} for session {session_id}\")\n\n        # Send cancel response\n        await self._send_tasks_cancel_response(request_id, session_id)\n\n    async def _send_clear_context_response(\n        self,\n        request_id: str,\n        session_id: str,\n        success: bool = True,\n    ) -> None:\n        \"\"\"Send clear context response.\"\"\"\n        if not self._ws or not self._connected:\n            return\n\n        json_rpc_response = {\n            \"jsonrpc\": \"2.0\",\n            \"id\": request_id,\n            \"result\": {\n                \"status\": {\"state\": \"cleared\" if success else \"failed\"},\n            },\n        }\n\n        msg = {\n            \"msgType\": \"agent_response\",\n            \"agentId\": self.agent_id,\n            \"sessionId\": session_id,\n            \"taskId\": request_id,\n            \"msgDetail\": json.dumps(json_rpc_response),\n        }\n\n        try:\n            await self._ws.send_json(msg)\n        except Exception as e:\n            logger.error(f\"XiaoYi: Failed to send clear context response: {e}\")\n\n    async def _send_tasks_cancel_response(\n        self,\n        request_id: str,\n        session_id: str,\n        success: bool = True,\n    ) -> None:\n        \"\"\"Send tasks cancel response.\"\"\"\n        if not self._ws or not self._connected:\n            return\n\n        json_rpc_response = {\n            \"jsonrpc\": \"2.0\",\n            \"id\": request_id,\n            \"result\": {\n                \"id\": request_id,\n                \"status\": {\"state\": \"canceled\" if success else \"failed\"},\n            },\n        }\n\n        msg = {\n            \"msgType\": \"agent_response\",\n            \"agentId\": self.agent_id,\n            \"sessionId\": session_id,\n            \"taskId\": request_id,\n            \"msgDetail\": json.dumps(json_rpc_response),\n        }\n\n        try:\n            await self._ws.send_json(msg)\n        except Exception as e:\n            logger.error(f\"XiaoYi: Failed to send cancel response: {e}\")\n\n    def _schedule_reconnect(self) -> None:\n        \"\"\"Schedule reconnection attempt.\"\"\"\n        if self._stopping:\n            return\n\n        if self._reconnect_attempts >= MAX_RECONNECT_ATTEMPTS:\n            logger.error(\"XiaoYi: Max reconnect attempts reached\")\n            return\n\n        delay_idx = min(self._reconnect_attempts, len(RECONNECT_DELAYS) - 1)\n        delay = RECONNECT_DELAYS[delay_idx]\n        self._reconnect_attempts += 1\n\n        logger.info(\n            \"XiaoYi: Reconnecting in \"\n            f\"{delay}s (attempt {self._reconnect_attempts})\",\n        )\n\n        async def reconnect():\n            await asyncio.sleep(delay)\n            if self._stopping or self._connected:\n                return\n\n            # Clean up old session before reconnecting\n            await self._cleanup_session()\n\n            try:\n                await self._connect()\n                logger.info(\"XiaoYi: Reconnected successfully\")\n            except Exception as e:\n                logger.error(f\"XiaoYi: Reconnect failed: {e}\")\n                self._schedule_reconnect()\n\n        asyncio.create_task(reconnect())\n\n    async def _cleanup_session(self) -> None:\n        \"\"\"Clean up WebSocket and session.\"\"\"\n        if self._ws:\n            try:\n                await self._ws.close()\n            except Exception:\n                pass\n            self._ws = None\n\n        if self._session:\n            try:\n                await self._session.close()\n            except Exception:\n                pass\n            self._session = None\n\n    async def stop(self) -> None:\n        \"\"\"Stop WebSocket connection.\"\"\"\n        logger.info(\"XiaoYi: Stopping channel...\")\n\n        self._stopping = True  # Prevent reconnect during stop\n        self._connected = False\n\n        # Cancel tasks\n        if self._heartbeat_task:\n            self._heartbeat_task.cancel()\n            try:\n                await self._heartbeat_task\n            except asyncio.CancelledError:\n                pass\n            self._heartbeat_task = None\n\n        if self._receive_task:\n            self._receive_task.cancel()\n            try:\n                await self._receive_task\n            except asyncio.CancelledError:\n                pass\n            self._receive_task = None\n\n        # Close WebSocket\n        if self._ws:\n            await self._ws.close()\n            self._ws = None\n\n        # Close session\n        if self._session:\n            await self._session.close()\n            self._session = None\n\n        # Unregister from active connections\n        await self._unregister_connection()\n\n        # Keep _stopping = True to prevent any reconnection attempts\n        # This channel instance will not be reused after stop\n        logger.info(\"XiaoYi: Channel stopped\")\n\n    async def send(\n        self,\n        to_handle: str,\n        text: str,\n        meta: Optional[Dict[str, Any]] = None,\n    ) -> None:\n        \"\"\"Send text message via WebSocket.\n\n        For A2A protocol with append=true, messages are chunked\n        at TEXT_CHUNK_LIMIT characters to avoid WebSocket disconnection\n        on large messages.\n        \"\"\"\n        if not self.enabled or not self._ws or not self._connected:\n            logger.warning(\"XiaoYi: Cannot send - not connected\")\n            return\n\n        meta = meta or {}\n        session_id = meta.get(\"session_id\") or to_handle\n        task_id = meta.get(\"task_id\") or self._session_task_map.get(session_id)\n\n        if not task_id:\n            logger.warning(f\"XiaoYi: No task_id for session {session_id}\")\n            return\n\n        # Don't send empty text\n        if not text or not text.strip():\n            return\n\n        # Get or create message ID for this session\n        message_id = meta.get(\"message_id\", str(uuid.uuid4()))\n\n        # Chunk text if too large\n        chunks = self._chunk_text(text)\n\n        for chunk in chunks:\n            await self._send_chunk(session_id, task_id, message_id, chunk)\n\n    def _chunk_text(self, text: str) -> List[str]:\n        \"\"\"Split text into chunks of TEXT_CHUNK_LIMIT size.\"\"\"\n        if len(text) <= TEXT_CHUNK_LIMIT:\n            return [text]\n\n        chunks = []\n        # Try to split at newlines for better readability\n        lines = text.split(\"\\n\")\n        current_chunk = \"\"\n\n        for line in lines:\n            # If single line is too long, split it\n            if len(line) > TEXT_CHUNK_LIMIT:\n                # First add any accumulated chunk\n                if current_chunk:\n                    chunks.append(current_chunk.rstrip(\"\\n\"))\n                    current_chunk = \"\"\n\n                # Split long line into chunks\n                for i in range(0, len(line), TEXT_CHUNK_LIMIT):\n                    chunks.append(line[i : i + TEXT_CHUNK_LIMIT])\n            else:\n                # Check if adding this line would exceed limit\n                test_chunk = (\n                    current_chunk + \"\\n\" + line if current_chunk else line\n                )\n                if len(test_chunk) > TEXT_CHUNK_LIMIT:\n                    if current_chunk:\n                        chunks.append(current_chunk)\n                    current_chunk = line\n                else:\n                    current_chunk = test_chunk\n\n        if current_chunk:\n            chunks.append(current_chunk)\n\n        return chunks\n\n    def _build_artifact_msg(\n        self,\n        session_id: str,\n        task_id: str,\n        message_id: str,\n        parts: List[Dict[str, Any]],\n        last_chunk: bool = False,\n        final: bool = False,\n    ) -> Dict[str, Any]:\n        \"\"\"Build artifact-update message for XiaoYi A2A protocol.\"\"\"\n        artifact_id = f\"artifact_{uuid.uuid4().hex[:16]}\"\n        json_rpc_response = {\n            \"jsonrpc\": \"2.0\",\n            \"id\": message_id,\n            \"result\": {\n                \"taskId\": task_id,\n                \"kind\": \"artifact-update\",\n                \"append\": True,\n                \"lastChunk\": last_chunk,\n                \"final\": final,\n                \"artifact\": {\n                    \"artifactId\": artifact_id,\n                    \"parts\": parts,\n                },\n            },\n        }\n        return {\n            \"msgType\": \"agent_response\",\n            \"agentId\": self.agent_id,\n            \"sessionId\": session_id,\n            \"taskId\": task_id,\n            \"msgDetail\": json.dumps(json_rpc_response),\n        }\n\n    async def _send_chunk(\n        self,\n        session_id: str,\n        task_id: str,\n        message_id: str,\n        text: str,\n    ) -> None:\n        \"\"\"Send a single text chunk via WebSocket.\"\"\"\n        if not self._ws or not self._connected:\n            return\n        msg = self._build_artifact_msg(\n            session_id,\n            task_id,\n            message_id,\n            [{\"kind\": \"text\", \"text\": text}],\n        )\n        try:\n            await self._ws.send_json(msg)\n        except Exception as e:\n            logger.error(f\"XiaoYi: Failed to send chunk: {e}\")\n\n    async def _send_reasoning_chunk(\n        self,\n        session_id: str,\n        task_id: str,\n        message_id: str,\n        reasoning_text: str,\n    ) -> None:\n        \"\"\"Send a reasoning/thinking chunk via WebSocket.\"\"\"\n        if not self._ws or not self._connected:\n            return\n        msg = self._build_artifact_msg(\n            session_id,\n            task_id,\n            message_id,\n            [{\"kind\": \"reasoningText\", \"reasoningText\": reasoning_text}],\n        )\n        try:\n            await self._ws.send_json(msg)\n        except Exception as e:\n            logger.error(f\"XiaoYi: Failed to send reasoning chunk: {e}\")\n\n    async def send_final_message(\n        self,\n        session_id: str,\n        task_id: str,\n        message_id: str,\n    ) -> None:\n        \"\"\"Send final empty message to end the stream.\"\"\"\n        if not self.enabled or not self._ws or not self._connected:\n            return\n        msg = self._build_artifact_msg(\n            session_id,\n            task_id,\n            message_id,\n            [{\"kind\": \"text\", \"text\": \"\"}],\n            last_chunk=True,\n            final=True,\n        )\n        try:\n            await self._ws.send_json(msg)\n        except Exception as e:\n            logger.error(f\"XiaoYi: Failed to send final message: {e}\")\n\n    async def send_media(\n        self,\n        to_handle: str,\n        part: OutgoingContentPart,\n        meta: Optional[Dict[str, Any]] = None,\n    ) -> None:\n        \"\"\"Send media message via WebSocket.\"\"\"\n        if not self.enabled or not self._ws or not self._connected:\n            return\n\n        meta = meta or {}\n        session_id = meta.get(\"session_id\") or to_handle\n        task_id = meta.get(\"task_id\") or self._session_task_map.get(session_id)\n\n        if not task_id:\n            return\n\n        part_type = getattr(part, \"type\", None)\n\n        if part_type == ContentType.IMAGE:\n            artifact_part = {\n                \"kind\": \"file\",\n                \"file\": {\n                    \"name\": \"image\",\n                    \"mimeType\": \"image/png\",\n                    \"uri\": getattr(part, \"image_url\", \"\"),\n                },\n            }\n        elif part_type == ContentType.VIDEO:\n            artifact_part = {\n                \"kind\": \"file\",\n                \"file\": {\n                    \"name\": \"video\",\n                    \"mimeType\": \"video/mp4\",\n                    \"uri\": getattr(part, \"video_url\", \"\"),\n                },\n            }\n        elif part_type == ContentType.FILE:\n            artifact_part = {\n                \"kind\": \"file\",\n                \"file\": {\n                    \"name\": getattr(part, \"file_name\", \"file\"),\n                    \"mimeType\": \"application/octet-stream\",\n                    \"uri\": getattr(part, \"file_url\", \"\"),\n                },\n            }\n        else:\n            return\n\n        msg = self._build_artifact_msg(\n            session_id,\n            task_id,\n            str(uuid.uuid4()),\n            [artifact_part],\n            last_chunk=True,\n            final=True,\n        )\n        try:\n            await self._ws.send_json(msg)\n        except Exception as e:\n            logger.error(f\"XiaoYi: Failed to send media: {e}\")\n\n    def _extract_xiaoyi_parts(\n        self,\n        message: Any,\n    ) -> List[Dict[str, Any]]:\n        # pylint: disable=too-many-branches,too-many-statements\n        # pylint: disable=too-many-nested-blocks\n        \"\"\"Extract parts from message with proper XiaoYi kinds.\n\n        XiaoYi supports:\n        - kind=\"reasoningText\": For thinking/reasoning content\n        - kind=\"text\": For regular text content\n        \"\"\"\n        from agentscope_runtime.engine.schemas.agent_schemas import (\n            MessageType,\n        )\n\n        msg_type = getattr(message, \"type\", None)\n        content = getattr(message, \"content\", None) or []\n        parts = []\n\n        # Check if this is a reasoning/thinking message type\n        if msg_type == MessageType.REASONING:\n            # Check if thinking is filtered\n            if self._render_style.filter_thinking:\n                return []\n            for c in content:\n                text = getattr(c, \"text\", None)\n                if text:\n                    # Add newline separator for each thinking content\n                    parts.append(\n                        {\n                            \"kind\": \"reasoningText\",\n                            \"reasoningText\": text + \"\\n\",\n                        },\n                    )\n            return parts\n\n        # Process each content item\n        for c in content:\n            ctype = getattr(c, \"type\", None)\n\n            # Handle thinking blocks (inside DATA content as dict)\n            if ctype == ContentType.DATA:\n                data = getattr(c, \"data\", None)\n                if isinstance(data, dict):\n                    # Check for thinking content in blocks\n                    blocks = data.get(\"blocks\", [])\n                    if (\n                        isinstance(blocks, list)\n                        and not self._render_style.filter_thinking\n                    ):\n                        for block in blocks:\n                            if (\n                                isinstance(block, dict)\n                                and block.get(\"type\") == \"thinking\"\n                            ):\n                                thinking_text = block.get(\"thinking\", \"\")\n                                if thinking_text:\n                                    # Add newline separator\n                                    parts.append(\n                                        {\n                                            \"kind\": \"reasoningText\",\n                                            \"reasoningText\": thinking_text\n                                            + \"\\n\",\n                                        },\n                                    )\n\n            # Handle TEXT type (regular message content)\n            # Add leading newline to separate from previous content\n            if ctype == ContentType.TEXT and getattr(c, \"text\", None):\n                text = c.text\n                # Add leading newlines if not already present\n                if not text.startswith(\"\\n\"):\n                    text = \"\\n\\n\" + text\n                parts.append({\"kind\": \"text\", \"text\": text})\n\n            # Handle REFUSAL type\n            elif ctype == ContentType.REFUSAL and getattr(c, \"refusal\", None):\n                parts.append({\"kind\": \"text\", \"text\": c.refusal})\n\n        # Handle tool call/output messages\n        # with complete, independent formatting\n        # Check if tool messages should be filtered\n        if self._render_style.filter_tool_messages:\n            if msg_type in (\n                MessageType.FUNCTION_CALL,\n                MessageType.PLUGIN_CALL,\n                MessageType.MCP_TOOL_CALL,\n                MessageType.FUNCTION_CALL_OUTPUT,\n                MessageType.PLUGIN_CALL_OUTPUT,\n                MessageType.MCP_TOOL_CALL_OUTPUT,\n            ):\n                return []\n\n        if msg_type in (\n            MessageType.FUNCTION_CALL,\n            MessageType.PLUGIN_CALL,\n            MessageType.MCP_TOOL_CALL,\n        ):\n            # Tool call: format as \"🔧 **name**\" + code block with args\n            for c in content:\n                if getattr(c, \"type\", None) != ContentType.DATA:\n                    continue\n                data = getattr(c, \"data\", None)\n                if not isinstance(data, dict):\n                    continue\n                name = data.get(\"name\") or \"tool\"\n                args = data.get(\"arguments\") or \"{}\"\n                # Complete, independent formatting for each tool call\n                formatted = f\"\\n\\n🔧 **{name}**\\n```\\n{args}\\n```\\n\"\n                parts.append({\"kind\": \"text\", \"text\": formatted})\n            return parts\n\n        if msg_type in (\n            MessageType.FUNCTION_CALL_OUTPUT,\n            MessageType.PLUGIN_CALL_OUTPUT,\n            MessageType.MCP_TOOL_CALL_OUTPUT,\n        ):\n            # Tool output: format as \"✅ **name**\" + code block with result\n            for c in content:\n                if getattr(c, \"type\", None) != ContentType.DATA:\n                    continue\n                data = getattr(c, \"data\", None)\n                if not isinstance(data, dict):\n                    continue\n                name = data.get(\"name\") or \"tool\"\n                output = data.get(\"output\", \"\")\n\n                # Parse output and format as JSON\n                try:\n                    if isinstance(output, str):\n                        parsed = json.loads(output)\n                    else:\n                        parsed = output\n\n                    # Handle list format like [{'type': 'text', 'text': '...'}]\n                    if isinstance(parsed, list):\n                        texts = []\n                        for item in parsed:\n                            if (\n                                isinstance(item, dict)\n                                and item.get(\"type\") == \"text\"\n                            ):\n                                texts.append(item.get(\"text\", \"\"))\n                        output_str = \"\\n\".join(texts) if texts else str(parsed)\n                    elif isinstance(parsed, dict):\n                        output_str = json.dumps(\n                            parsed,\n                            ensure_ascii=False,\n                            indent=2,\n                        )\n                    else:\n                        output_str = str(parsed)\n                except (json.JSONDecodeError, TypeError):\n                    output_str = str(output) if output else \"\"\n\n                # Truncate if too long\n                if len(output_str) > 500:\n                    output_str = output_str[:500] + \"...\"\n\n                # Escape backticks in output\n                # to avoid breaking code blocks\n                output_str = output_str.replace(\"```\", \"\\\\`\\\\`\\\\`\")\n\n                # Complete, independent formatting\n                # for each tool output\n                # Ensure code block is properly closed\n                formatted = f\"\\n\\n✅ **{name}**\\n```\\n{output_str}\\n```\\n\"\n                parts.append({\"kind\": \"text\", \"text\": formatted})\n            return parts\n\n        # If no parts extracted, use renderer as fallback\n        if not parts:\n            rendered_parts = self._renderer.message_to_parts(message)\n            for rp in rendered_parts:\n                if getattr(rp, \"type\", None) == ContentType.TEXT:\n                    text = getattr(rp, \"text\", \"\")\n                    if text:\n                        parts.append({\"kind\": \"text\", \"text\": text})\n\n        return parts\n\n    async def send_xiaoyi_parts(\n        self,\n        to_handle: str,\n        parts: List[Dict[str, Any]],\n        meta: Optional[Dict[str, Any]] = None,\n    ) -> None:\n        # pylint: disable=too-many-branches,too-many-nested-blocks\n        \"\"\"Send parts with XiaoYi-specific format.\n\n        Each part is a dict with:\n        - kind: \"text\" or \"reasoningText\"\n        - text/reasoningText: the content string\n        \"\"\"\n        if not self.enabled or not self._ws or not self._connected:\n            logger.warning(\"XiaoYi: Cannot send - not connected\")\n            return\n\n        meta = meta or {}\n        session_id = meta.get(\"session_id\") or to_handle\n        task_id = meta.get(\"task_id\") or self._session_task_map.get(session_id)\n\n        if not task_id:\n            logger.warning(f\"XiaoYi: No task_id for session {session_id}\")\n            return\n\n        message_id = meta.get(\"message_id\", str(uuid.uuid4()))\n\n        # Build artifact parts for XiaoYi\n        artifact_parts = []\n        for part in parts:\n            kind = part.get(\"kind\", \"text\")\n            if kind == \"reasoningText\":\n                artifact_parts.append(\n                    {\n                        \"kind\": \"reasoningText\",\n                        \"reasoningText\": part.get(\"reasoningText\", \"\"),\n                    },\n                )\n            elif kind == \"text\":\n                artifact_parts.append(\n                    {\n                        \"kind\": \"text\",\n                        \"text\": part.get(\"text\", \"\"),\n                    },\n                )\n\n        if not artifact_parts:\n            return\n\n        # Check if any part exceeds chunk limit\n        max_part_len = max(\n            len(p.get(\"text\", \"\") or p.get(\"reasoningText\", \"\"))\n            for p in artifact_parts\n        )\n\n        if max_part_len > TEXT_CHUNK_LIMIT:\n            # Chunk each part separately, preserving kind\n            for part in artifact_parts:\n                kind = part.get(\"kind\", \"text\")\n                content = part.get(\"text\", \"\") or part.get(\"reasoningText\", \"\")\n                if len(content) > TEXT_CHUNK_LIMIT:\n                    chunks = self._chunk_text(content)\n                    for chunk in chunks:\n                        if kind == \"reasoningText\":\n                            await self._send_reasoning_chunk(\n                                session_id,\n                                task_id,\n                                message_id,\n                                chunk,\n                            )\n                        else:\n                            await self._send_chunk(\n                                session_id,\n                                task_id,\n                                message_id,\n                                chunk,\n                            )\n                else:\n                    # Send small parts as-is\n                    if kind == \"reasoningText\":\n                        await self._send_reasoning_chunk(\n                            session_id,\n                            task_id,\n                            message_id,\n                            content,\n                        )\n                    else:\n                        await self._send_chunk(\n                            session_id,\n                            task_id,\n                            message_id,\n                            content,\n                        )\n            return\n\n        # Send as single message with proper parts\n        msg = self._build_artifact_msg(\n            session_id,\n            task_id,\n            message_id,\n            artifact_parts,\n        )\n        try:\n            await self._ws.send_json(msg)\n        except Exception as e:\n            logger.error(f\"XiaoYi: Failed to send parts: {e}\")\n\n    async def on_event_message_completed(\n        self,\n        request: \"AgentRequest\",\n        to_handle: str,\n        event: Any,\n        send_meta: Dict[str, Any],\n    ) -> None:\n        \"\"\"Override to handle XiaoYi-specific message formatting.\n\n        Separates thinking/reasoning content from regular text.\n        \"\"\"\n        # Extract parts with proper kinds\n        parts = self._extract_xiaoyi_parts(event)\n\n        if not parts:\n            logger.debug(\"XiaoYi: No parts to send for message\")\n            return\n\n        # Send with XiaoYi format\n        await self.send_xiaoyi_parts(to_handle, parts, send_meta)\n\n    def resolve_session_id(\n        self,\n        sender_id: str,\n        channel_meta: Optional[Dict[str, Any]] = None,\n    ) -> str:\n        \"\"\"Resolve session ID from sender and meta.\"\"\"\n        if channel_meta and channel_meta.get(\"session_id\"):\n            return f\"xiaoyi:{channel_meta['session_id']}\"\n        return f\"xiaoyi:{sender_id}\"\n\n    def get_to_handle_from_request(self, request: \"AgentRequest\") -> str:\n        \"\"\"Get send target from request.\"\"\"\n        meta = getattr(request, \"channel_meta\", None) or {}\n        if meta.get(\"session_id\"):\n            return meta[\"session_id\"]\n        return getattr(request, \"user_id\", \"\") or \"\"\n\n    def build_agent_request_from_native(\n        self,\n        native_payload: Any,\n    ) -> \"AgentRequest\":\n        \"\"\"Build AgentRequest from native payload.\"\"\"\n        payload = native_payload if isinstance(native_payload, dict) else {}\n\n        channel_id = payload.get(\"channel_id\") or self.channel\n        sender_id = payload.get(\"sender_id\") or \"\"\n        content_parts = payload.get(\"content_parts\") or []\n        meta = payload.get(\"meta\") or {}\n\n        session_id = self.resolve_session_id(sender_id, meta)\n\n        request = self.build_agent_request_from_user_content(\n            channel_id=channel_id,\n            sender_id=sender_id,\n            session_id=session_id,\n            content_parts=content_parts,\n            channel_meta=meta,\n        )\n        request.user_id = sender_id\n        request.channel_meta = meta\n        return request\n\n    def to_handle_from_target(self, *, user_id: str, session_id: str) -> str:\n        \"\"\"Map dispatch target to channel-specific to_handle.\"\"\"\n        if session_id.startswith(\"xiaoyi:\"):\n            return session_id.split(\":\", 1)[-1]\n        return user_id\n\n    async def _run_process_loop(\n        self,\n        request: \"AgentRequest\",\n        to_handle: str,\n        send_meta: Dict[str, Any],\n    ) -> None:\n        \"\"\"Run process and send events. Override to send final message.\"\"\"\n        from agentscope_runtime.engine.schemas.agent_schemas import RunStatus\n\n        last_response = None\n        session_id = send_meta.get(\"session_id\") or to_handle\n\n        try:\n            async for event in self._process(request):\n                obj = getattr(event, \"object\", None)\n                status = getattr(event, \"status\", None)\n                if obj == \"message\" and status == RunStatus.Completed:\n                    await self.on_event_message_completed(\n                        request,\n                        to_handle,\n                        event,\n                        send_meta,\n                    )\n                elif obj == \"response\":\n                    last_response = event\n                    await self.on_event_response(request, event)\n\n            # Send final message to end the stream\n            task_id = send_meta.get(\"task_id\") or self._session_task_map.get(\n                session_id,\n            )\n            message_id = str(uuid.uuid4())\n\n            if task_id and session_id:\n                await self.send_final_message(session_id, task_id, message_id)\n\n            err_msg = self._get_response_error_message(last_response)\n            if err_msg:\n                await self._on_consume_error(\n                    request,\n                    to_handle,\n                    f\"Error: {err_msg}\",\n                )\n            if self._on_reply_sent:\n                args = self.get_on_reply_sent_args(request, to_handle)\n                self._on_reply_sent(self.channel, *args)\n        except Exception:\n            logger.exception(\"XiaoYi channel consume_one failed\")\n            await self._on_consume_error(\n                request,\n                to_handle,\n                \"An error occurred while processing your request.\",\n            )\n"
  },
  {
    "path": "src/copaw/app/channels/xiaoyi/constants.py",
    "content": "# -*- coding: utf-8 -*-\n\"\"\"XiaoYi channel constants.\"\"\"\n\n# Default WebSocket URL\nDEFAULT_WS_URL = \"wss://hag.cloud.huawei.com/openclaw/v1/ws/link\"\n\n# Heartbeat interval (seconds)\nHEARTBEAT_INTERVAL = 30\n\n# Reconnect delays (seconds)\nRECONNECT_DELAYS = [1, 2, 5, 10, 30, 60]\nMAX_RECONNECT_ATTEMPTS = 50\n\n# Connection timeout (seconds)\nCONNECTION_TIMEOUT = 30\n\n# Task timeout (milliseconds)\nDEFAULT_TASK_TIMEOUT_MS = 3600000  # 1 hour\n\n# Maximum text chunk size (characters)\n# Larger messages will be split to avoid WebSocket disconnection\nTEXT_CHUNK_LIMIT = 4000\n"
  },
  {
    "path": "src/copaw/app/channels/xiaoyi/utils.py",
    "content": "# -*- coding: utf-8 -*-\n\"\"\"XiaoYi channel utilities for file handling.\"\"\"\n\nimport mimetypes\nfrom pathlib import Path\nfrom typing import Optional\n\nimport aiohttp\n\n\nasync def download_file(\n    url: str,\n    media_dir: Path,\n    filename: str,\n) -> Optional[str]:\n    \"\"\"Download file from URL to media_dir, return local path.\"\"\"\n    media_dir.mkdir(parents=True, exist_ok=True)\n\n    async with aiohttp.ClientSession() as session:\n        try:\n            async with session.get(url) as resp:\n                if resp.status >= 400:\n                    return None\n\n                data = await resp.read()\n                content_type = (\n                    resp.headers.get(\"Content-Type\", \"\").split(\";\")[0].strip()\n                )\n\n                # Determine extension\n                ext = \"\"\n                if content_type:\n                    ext = mimetypes.guess_extension(content_type) or \"\"\n                if not ext:\n                    ext = Path(filename).suffix or \".bin\"\n\n                # Build safe filename\n                safe_name = \"\".join(\n                    c for c in filename if c.isalnum() or c in \"-_.\"\n                )\n                if not safe_name:\n                    safe_name = \"file\"\n\n                # Ensure unique extension\n                if not Path(safe_name).suffix and ext:\n                    safe_name = f\"{Path(safe_name).stem}{ext}\"\n\n                path = media_dir / safe_name\n                path.write_bytes(data)\n                return str(path)\n\n        except Exception:\n            return None\n"
  },
  {
    "path": "src/copaw/app/console_push_store.py",
    "content": "# -*- coding: utf-8 -*-\n\"\"\"In-memory store for console channel push messages (e.g. cron text).\n\nBounded: at most _MAX_MESSAGES kept; messages older than _MAX_AGE_SECONDS\nare dropped when reading. Frontend dedupes by id and caps its seen set.\n\"\"\"\nfrom __future__ import annotations\n\nimport asyncio\nimport time\nimport uuid\nfrom typing import Any, Dict, List\n\n# Single list: each item has id, text, ts, session_id and optional metadata.\n# Bounded by count and age.\n_list: List[Dict[str, Any]] = []\n_lock = asyncio.Lock()\n_MAX_AGE_SECONDS = 60\n_MAX_MESSAGES = 500\n\n\nasync def append(session_id: str, text: str, *, sticky: bool = False) -> None:\n    \"\"\"Append a message (bounded: oldest dropped if over _MAX_MESSAGES).\"\"\"\n    if not session_id or not text:\n        return\n    async with _lock:\n        _list.append(\n            {\n                \"id\": str(uuid.uuid4()),\n                \"text\": text,\n                \"sticky\": sticky,\n                \"ts\": time.time(),\n                \"session_id\": session_id,\n            },\n        )\n        if len(_list) > _MAX_MESSAGES:\n            _list.sort(key=lambda m: m[\"ts\"])\n            del _list[: len(_list) - _MAX_MESSAGES]\n\n\nasync def take(session_id: str) -> List[Dict[str, Any]]:\n    \"\"\"Return and remove all messages for the session.\"\"\"\n    if not session_id:\n        return []\n    async with _lock:\n        out = [m for m in _list if m.get(\"session_id\") == session_id]\n        _list[:] = [m for m in _list if m.get(\"session_id\") != session_id]\n        return _strip_ts(out)\n\n\nasync def take_all() -> List[Dict[str, Any]]:\n    \"\"\"Return and remove all messages.\"\"\"\n    async with _lock:\n        out = list(_list)\n        _list.clear()\n        return _strip_ts(out)\n\n\ndef _strip_ts(msgs: List[Dict[str, Any]]) -> List[Dict[str, Any]]:\n    return [\n        {\n            \"id\": m[\"id\"],\n            \"text\": m[\"text\"],\n            \"sticky\": bool(m.get(\"sticky\", False)),\n        }\n        for m in msgs\n    ]\n\n\nasync def get_recent(\n    max_age_seconds: int = _MAX_AGE_SECONDS,\n) -> List[Dict[str, Any]]:\n    \"\"\"\n    Return recent messages (not consumed). Drop older than max_age_seconds\n    from store to bound memory.\n    \"\"\"\n    now = time.time()\n    cutoff = now - max_age_seconds\n    async with _lock:\n        out = [m for m in _list if m[\"ts\"] >= cutoff]\n        _list[:] = out\n        return _strip_ts(out)\n"
  },
  {
    "path": "src/copaw/app/crons/__init__.py",
    "content": ""
  },
  {
    "path": "src/copaw/app/crons/api.py",
    "content": "# -*- coding: utf-8 -*-\nfrom __future__ import annotations\n\nimport uuid\nfrom fastapi import APIRouter, Depends, HTTPException, Request\n\nfrom .manager import CronManager\nfrom .models import CronJobSpec, CronJobView\n\nrouter = APIRouter(prefix=\"/cron\", tags=[\"cron\"])\n\n\nasync def get_cron_manager(\n    request: Request,\n) -> CronManager:\n    \"\"\"Get cron manager for the active agent.\"\"\"\n    from ..agent_context import get_agent_for_request\n\n    workspace = await get_agent_for_request(request)\n    if workspace.cron_manager is None:\n        raise HTTPException(\n            status_code=500,\n            detail=\"CronManager not initialized\",\n        )\n    return workspace.cron_manager\n\n\n@router.get(\"/jobs\", response_model=list[CronJobSpec])\nasync def list_jobs(mgr: CronManager = Depends(get_cron_manager)):\n    return await mgr.list_jobs()\n\n\n@router.get(\"/jobs/{job_id}\", response_model=CronJobView)\nasync def get_job(job_id: str, mgr: CronManager = Depends(get_cron_manager)):\n    job = await mgr.get_job(job_id)\n    if not job:\n        raise HTTPException(status_code=404, detail=\"job not found\")\n    return CronJobView(spec=job, state=mgr.get_state(job_id))\n\n\n@router.post(\"/jobs\", response_model=CronJobSpec)\nasync def create_job(\n    spec: CronJobSpec,\n    mgr: CronManager = Depends(get_cron_manager),\n):\n    # server generates id; ignore client-provided spec.id\n    job_id = str(uuid.uuid4())\n    created = spec.model_copy(update={\"id\": job_id})\n    await mgr.create_or_replace_job(created)\n    return created\n\n\n@router.put(\"/jobs/{job_id}\", response_model=CronJobSpec)\nasync def replace_job(\n    job_id: str,\n    spec: CronJobSpec,\n    mgr: CronManager = Depends(get_cron_manager),\n):\n    if spec.id != job_id:\n        raise HTTPException(status_code=400, detail=\"job_id mismatch\")\n    await mgr.create_or_replace_job(spec)\n    return spec\n\n\n@router.delete(\"/jobs/{job_id}\")\nasync def delete_job(\n    job_id: str,\n    mgr: CronManager = Depends(get_cron_manager),\n):\n    ok = await mgr.delete_job(job_id)\n    if not ok:\n        raise HTTPException(status_code=404, detail=\"job not found\")\n    return {\"deleted\": True}\n\n\n@router.post(\"/jobs/{job_id}/pause\")\nasync def pause_job(job_id: str, mgr: CronManager = Depends(get_cron_manager)):\n    try:\n        await mgr.pause_job(job_id)\n    except Exception as e:\n        raise HTTPException(status_code=400, detail=str(e)) from e\n    return {\"paused\": True}\n\n\n@router.post(\"/jobs/{job_id}/resume\")\nasync def resume_job(\n    job_id: str,\n    mgr: CronManager = Depends(get_cron_manager),\n):\n    try:\n        await mgr.resume_job(job_id)\n    except Exception as e:\n        raise HTTPException(status_code=400, detail=str(e)) from e\n    return {\"resumed\": True}\n\n\n@router.post(\"/jobs/{job_id}/run\")\nasync def run_job(job_id: str, mgr: CronManager = Depends(get_cron_manager)):\n    try:\n        await mgr.run_job(job_id)\n    except KeyError as e:\n        raise HTTPException(status_code=404, detail=\"job not found\") from e\n    except Exception as e:\n        raise HTTPException(status_code=500, detail=str(e)) from e\n    return {\"started\": True}\n\n\n@router.get(\"/jobs/{job_id}/state\")\nasync def get_job_state(\n    job_id: str,\n    mgr: CronManager = Depends(get_cron_manager),\n):\n    job = await mgr.get_job(job_id)\n    if not job:\n        raise HTTPException(status_code=404, detail=\"job not found\")\n    return mgr.get_state(job_id).model_dump(mode=\"json\")\n"
  },
  {
    "path": "src/copaw/app/crons/executor.py",
    "content": "# -*- coding: utf-8 -*-\nfrom __future__ import annotations\n\nimport asyncio\nimport logging\nfrom typing import Any, Dict\n\nfrom .models import CronJobSpec\n\nlogger = logging.getLogger(__name__)\n\n\nclass CronExecutor:\n    def __init__(self, *, runner: Any, channel_manager: Any):\n        self._runner = runner\n        self._channel_manager = channel_manager\n\n    async def execute(self, job: CronJobSpec) -> None:\n        \"\"\"Execute one job once.\n\n        - task_type text: send fixed text to channel\n        - task_type agent: ask agent with prompt, send reply to channel (\n            stream_query + send_event)\n        \"\"\"\n        target_user_id = job.dispatch.target.user_id\n        target_session_id = job.dispatch.target.session_id\n        dispatch_meta: Dict[str, Any] = dict(job.dispatch.meta or {})\n        logger.info(\n            \"cron execute: job_id=%s channel=%s task_type=%s \"\n            \"target_user_id=%s target_session_id=%s\",\n            job.id,\n            job.dispatch.channel,\n            job.task_type,\n            target_user_id[:40] if target_user_id else \"\",\n            target_session_id[:40] if target_session_id else \"\",\n        )\n\n        if job.task_type == \"text\" and job.text:\n            logger.info(\n                \"cron send_text: job_id=%s channel=%s len=%s\",\n                job.id,\n                job.dispatch.channel,\n                len(job.text or \"\"),\n            )\n            await self._channel_manager.send_text(\n                channel=job.dispatch.channel,\n                user_id=target_user_id,\n                session_id=target_session_id,\n                text=job.text.strip(),\n                meta=dispatch_meta,\n            )\n            return\n\n        # agent: run request as the dispatch target user so context matches\n        logger.info(\n            \"cron agent: job_id=%s channel=%s stream_query then send_event\",\n            job.id,\n            job.dispatch.channel,\n        )\n        assert job.request is not None\n        req: Dict[str, Any] = job.request.model_dump(mode=\"json\")\n        req[\"user_id\"] = target_user_id or \"cron\"\n        req[\"session_id\"] = target_session_id or f\"cron:{job.id}\"\n\n        async def _run() -> None:\n            async for event in self._runner.stream_query(req):\n                await self._channel_manager.send_event(\n                    channel=job.dispatch.channel,\n                    user_id=target_user_id,\n                    session_id=target_session_id,\n                    event=event,\n                    meta=dispatch_meta,\n                )\n\n        try:\n            await asyncio.wait_for(\n                _run(),\n                timeout=job.runtime.timeout_seconds,\n            )\n        except asyncio.TimeoutError:\n            logger.warning(\n                \"cron execute: job_id=%s timed out after %ss\",\n                job.id,\n                job.runtime.timeout_seconds,\n            )\n            raise\n        except asyncio.CancelledError:\n            logger.info(\"cron execute: job_id=%s cancelled\", job.id)\n            raise\n"
  },
  {
    "path": "src/copaw/app/crons/heartbeat.py",
    "content": "# -*- coding: utf-8 -*-\n\"\"\"\nHeartbeat: run agent with HEARTBEAT.md as query at interval.\nUses config functions (get_heartbeat_config, get_heartbeat_query_path,\nload_config) for paths and settings.\n\"\"\"\nfrom __future__ import annotations\n\nimport asyncio\nimport logging\nimport re\nfrom datetime import datetime, time, timezone\nfrom pathlib import Path\nfrom zoneinfo import ZoneInfo, ZoneInfoNotFoundError\nfrom typing import Any, Dict, Optional\n\nfrom ...config import (\n    get_heartbeat_config,\n    get_heartbeat_query_path,\n    load_config,\n)\nfrom ...constant import HEARTBEAT_FILE, HEARTBEAT_TARGET_LAST\n\nlogger = logging.getLogger(__name__)\n\n# Pattern for \"30m\", \"1h\", \"2h30m\", \"90s\"\n_EVERY_PATTERN = re.compile(\n    r\"^(?:(?P\\d+)h)?(?:(?P\\d+)m)?(?:(?P\\d+)s)?$\",\n    re.IGNORECASE,\n)\n\n\ndef parse_heartbeat_every(every: str) -> int:\n    \"\"\"Parse interval string (e.g. '30m', '1h') to total seconds.\"\"\"\n    every = (every or \"\").strip()\n    if not every:\n        return 30 * 60  # default 30 min\n    m = _EVERY_PATTERN.match(every)\n    if not m:\n        logger.warning(\"heartbeat every=%r invalid, using 30m\", every)\n        return 30 * 60\n    hours = int(m.group(\"hours\") or 0)\n    minutes = int(m.group(\"minutes\") or 0)\n    seconds = int(m.group(\"seconds\") or 0)\n    total = hours * 3600 + minutes * 60 + seconds\n    if total <= 0:\n        return 30 * 60\n    return total\n\n\ndef _in_active_hours(active_hours: Any) -> bool:\n    \"\"\"Return True if the current time in user timezone is within\n    [start, end].\n    \"\"\"\n    if (\n        not active_hours\n        or not hasattr(active_hours, \"start\")\n        or not hasattr(active_hours, \"end\")\n    ):\n        return True\n    try:\n        start_parts = active_hours.start.strip().split(\":\")\n        end_parts = active_hours.end.strip().split(\":\")\n        start_t = time(\n            int(start_parts[0]),\n            int(start_parts[1]) if len(start_parts) > 1 else 0,\n        )\n        end_t = time(\n            int(end_parts[0]),\n            int(end_parts[1]) if len(end_parts) > 1 else 0,\n        )\n    except (ValueError, IndexError, AttributeError):\n        return True\n    user_tz = load_config().user_timezone or \"UTC\"\n    try:\n        now = datetime.now(ZoneInfo(user_tz)).time()\n    except (ZoneInfoNotFoundError, KeyError):\n        logger.warning(\n            \"Invalid timezone %r in config, falling back to UTC\"\n            \" for heartbeat active hours check.\",\n            user_tz,\n        )\n        now = datetime.now(timezone.utc).time()\n    if start_t <= end_t:\n        return start_t <= now <= end_t\n    return now >= start_t or now <= end_t\n\n\nasync def run_heartbeat_once(\n    *,\n    runner: Any,\n    channel_manager: Any,\n    agent_id: Optional[str] = None,\n    workspace_dir: Optional[Path] = None,\n) -> None:\n    \"\"\"\n    Run one heartbeat: read HEARTBEAT.md from workspace, run agent,\n    optionally dispatch to last channel (target=last).\n\n    Args:\n        runner: Agent runner instance\n        channel_manager: Channel manager instance\n        agent_id: Agent ID for loading config\n        workspace_dir: Workspace directory for reading HEARTBEAT.md\n    \"\"\"\n    from ...config.config import load_agent_config\n\n    hb = get_heartbeat_config(agent_id)\n    if not _in_active_hours(hb.active_hours):\n        logger.debug(\"heartbeat skipped: outside active hours\")\n        return\n\n    # Use workspace_dir if provided, otherwise fall back to global path\n    if workspace_dir:\n        path = Path(workspace_dir) / HEARTBEAT_FILE\n    else:\n        path = get_heartbeat_query_path()\n\n    if not path.is_file():\n        logger.debug(\"heartbeat skipped: no file at %s\", path)\n        return\n\n    query_text = path.read_text(encoding=\"utf-8\").strip()\n    if not query_text:\n        logger.debug(\"heartbeat skipped: empty query file\")\n        return\n\n    # Build request: single user message with query text\n    req: Dict[str, Any] = {\n        \"input\": [\n            {\n                \"role\": \"user\",\n                \"content\": [{\"type\": \"text\", \"text\": query_text}],\n            },\n        ],\n        \"session_id\": \"main\",\n        \"user_id\": \"main\",\n    }\n\n    # Get last_dispatch from agent config if agent_id provided\n    last_dispatch = None\n    if agent_id:\n        try:\n            agent_config = load_agent_config(agent_id)\n            last_dispatch = agent_config.last_dispatch\n        except Exception:\n            pass\n    else:\n        # Legacy: try root config\n        config = load_config()\n        last_dispatch = config.last_dispatch\n\n    target = (hb.target or \"\").strip().lower()\n    if target == HEARTBEAT_TARGET_LAST and last_dispatch:\n        ld = last_dispatch\n        if ld.channel and (ld.user_id or ld.session_id):\n\n            async def _run_and_dispatch() -> None:\n                async for event in runner.stream_query(req):\n                    await channel_manager.send_event(\n                        channel=ld.channel,\n                        user_id=ld.user_id,\n                        session_id=ld.session_id,\n                        event=event,\n                        meta={},\n                    )\n\n            try:\n                await asyncio.wait_for(_run_and_dispatch(), timeout=120)\n            except asyncio.TimeoutError:\n                logger.warning(\"heartbeat run timed out\")\n            return\n\n    # target main or no last_dispatch: run agent only, no dispatch\n    async def _run_only() -> None:\n        async for _ in runner.stream_query(req):\n            pass\n\n    try:\n        await asyncio.wait_for(_run_only(), timeout=120)\n    except asyncio.TimeoutError:\n        logger.warning(\"heartbeat run timed out\")\n"
  },
  {
    "path": "src/copaw/app/crons/manager.py",
    "content": "# -*- coding: utf-8 -*-\nfrom __future__ import annotations\n\nimport asyncio\nimport logging\nfrom dataclasses import dataclass\nfrom datetime import datetime, timezone\nfrom typing import Any, Dict, Optional\n\nfrom apscheduler.schedulers.asyncio import AsyncIOScheduler\nfrom apscheduler.triggers.cron import CronTrigger\nfrom apscheduler.triggers.interval import IntervalTrigger\n\nfrom ...config import get_heartbeat_config\n\nfrom ..console_push_store import append as push_store_append\nfrom .executor import CronExecutor\nfrom .heartbeat import parse_heartbeat_every, run_heartbeat_once\nfrom .models import CronJobSpec, CronJobState\nfrom .repo.base import BaseJobRepository\n\nHEARTBEAT_JOB_ID = \"_heartbeat\"\n\nlogger = logging.getLogger(__name__)\n\n\n@dataclass\nclass _Runtime:\n    sem: asyncio.Semaphore\n\n\nclass CronManager:\n    def __init__(\n        self,\n        *,\n        repo: BaseJobRepository,\n        runner: Any,\n        channel_manager: Any,\n        timezone: str = \"UTC\",  # pylint: disable=redefined-outer-name\n        agent_id: Optional[str] = None,\n    ):\n        self._repo = repo\n        self._runner = runner\n        self._channel_manager = channel_manager\n        self._agent_id = agent_id\n        self._scheduler = AsyncIOScheduler(timezone=timezone)\n        self._executor = CronExecutor(\n            runner=runner,\n            channel_manager=channel_manager,\n        )\n\n        self._lock = asyncio.Lock()\n        self._states: Dict[str, CronJobState] = {}\n        self._rt: Dict[str, _Runtime] = {}\n        self._started = False\n\n    async def start(self) -> None:\n        async with self._lock:\n            if self._started:\n                return\n            jobs_file = await self._repo.load()\n\n            self._scheduler.start()\n            for job in jobs_file.jobs:\n                try:\n                    await self._register_or_update(job)\n                except Exception as e:  # pylint: disable=broad-except\n                    logger.warning(\n                        \"Skipping invalid cron job during startup: \"\n                        \"job_id=%s name=%s cron=%s error=%s\",\n                        job.id,\n                        job.name,\n                        job.schedule.cron,\n                        repr(e),\n                    )\n                    if job.enabled:\n                        disabled_job = job.model_copy(\n                            update={\"enabled\": False},\n                        )\n                        await self._repo.upsert_job(disabled_job)\n                        logger.warning(\n                            \"Auto-disabled invalid cron job: \"\n                            \"job_id=%s name=%s\",\n                            job.id,\n                            job.name,\n                        )\n\n            # Heartbeat: one interval job when enabled in config\n            hb = get_heartbeat_config(self._agent_id)\n            if getattr(hb, \"enabled\", False):\n                interval_seconds = parse_heartbeat_every(hb.every)\n                self._scheduler.add_job(\n                    self._heartbeat_callback,\n                    trigger=IntervalTrigger(seconds=interval_seconds),\n                    id=HEARTBEAT_JOB_ID,\n                    replace_existing=True,\n                )\n                logger.info(\n                    f\"Heartbeat job scheduled for agent {self._agent_id}: \"\n                    f\"every={hb.every} (interval={interval_seconds}s)\",\n                )\n\n            self._started = True\n\n    async def stop(self) -> None:\n        async with self._lock:\n            if not self._started:\n                return\n            self._scheduler.shutdown(wait=False)\n            self._started = False\n\n    # ----- read/state -----\n\n    async def list_jobs(self) -> list[CronJobSpec]:\n        return await self._repo.list_jobs()\n\n    async def get_job(self, job_id: str) -> Optional[CronJobSpec]:\n        return await self._repo.get_job(job_id)\n\n    def get_state(self, job_id: str) -> CronJobState:\n        return self._states.get(job_id, CronJobState())\n\n    # ----- write/control -----\n\n    async def create_or_replace_job(self, spec: CronJobSpec) -> None:\n        async with self._lock:\n            await self._repo.upsert_job(spec)\n            if self._started:\n                await self._register_or_update(spec)\n\n    async def delete_job(self, job_id: str) -> bool:\n        async with self._lock:\n            if self._started and self._scheduler.get_job(job_id):\n                self._scheduler.remove_job(job_id)\n            self._states.pop(job_id, None)\n            self._rt.pop(job_id, None)\n            return await self._repo.delete_job(job_id)\n\n    async def pause_job(self, job_id: str) -> None:\n        async with self._lock:\n            self._scheduler.pause_job(job_id)\n\n    async def resume_job(self, job_id: str) -> None:\n        async with self._lock:\n            self._scheduler.resume_job(job_id)\n\n    async def reschedule_heartbeat(self) -> None:\n        \"\"\"Reload heartbeat config and update or remove the heartbeat job.\n\n        Note: CronManager should always be started during workspace\n        initialization, so this method assumes self._started is True.\n        \"\"\"\n        async with self._lock:\n            if not self._started:\n                logger.warning(\n                    f\"CronManager not started for agent {self._agent_id}, \"\n                    f\"cannot reschedule heartbeat. This should not happen.\",\n                )\n                return\n\n            hb = get_heartbeat_config(self._agent_id)\n\n            # Remove existing heartbeat job if present\n            if self._scheduler.get_job(HEARTBEAT_JOB_ID):\n                self._scheduler.remove_job(HEARTBEAT_JOB_ID)\n\n            # Add heartbeat job if enabled\n            if getattr(hb, \"enabled\", False):\n                interval_seconds = parse_heartbeat_every(hb.every)\n                self._scheduler.add_job(\n                    self._heartbeat_callback,\n                    trigger=IntervalTrigger(seconds=interval_seconds),\n                    id=HEARTBEAT_JOB_ID,\n                    replace_existing=True,\n                )\n                logger.info(\n                    \"heartbeat rescheduled: every=%s (interval=%ss)\",\n                    hb.every,\n                    interval_seconds,\n                )\n            else:\n                logger.info(\"heartbeat disabled, job removed\")\n\n    async def run_job(self, job_id: str) -> None:\n        \"\"\"Trigger a job to run in the background (fire-and-forget).\n\n        Raises KeyError if the job does not exist.\n        The actual execution happens asynchronously; errors are logged\n        and reflected in the job state but NOT propagated to the caller.\n        \"\"\"\n        job = await self._repo.get_job(job_id)\n        if not job:\n            raise KeyError(f\"Job not found: {job_id}\")\n        logger.info(\n            \"cron run_job (async): job_id=%s channel=%s task_type=%s \"\n            \"target_user_id=%s target_session_id=%s\",\n            job_id,\n            job.dispatch.channel,\n            job.task_type,\n            (job.dispatch.target.user_id or \"\")[:40],\n            (job.dispatch.target.session_id or \"\")[:40],\n        )\n        task = asyncio.create_task(\n            self._execute_once(job),\n            name=f\"cron-run-{job_id}\",\n        )\n        task.add_done_callback(lambda t: self._task_done_cb(t, job))\n\n    # ----- callbacks -----\n\n    def _task_done_cb(self, task: asyncio.Task, job: CronJobSpec) -> None:\n        \"\"\"Suppress and log exceptions from fire-and-forget tasks.\n\n        On failure, push an error message to the console push store so\n        the frontend can display it.\n        \"\"\"\n        if task.cancelled():\n            return\n        exc = task.exception()\n        if exc is not None:\n            logger.error(\n                \"cron background task %s failed: %s\",\n                task.get_name(),\n                repr(exc),\n            )\n            # Push error to the console for the frontend to display\n            session_id = job.dispatch.target.session_id\n            if session_id:\n                error_text = f\"❌ Cron job [{job.name}] failed: {exc}\"\n                asyncio.ensure_future(\n                    push_store_append(session_id, error_text),\n                )\n\n    # ----- internal -----\n\n    async def _register_or_update(self, spec: CronJobSpec) -> None:\n        # Validate and build trigger first. If cron is invalid, fail fast\n        # without mutating scheduler/runtime state.\n        trigger = self._build_trigger(spec)\n\n        # per-job concurrency semaphore\n        self._rt[spec.id] = _Runtime(\n            sem=asyncio.Semaphore(spec.runtime.max_concurrency),\n        )\n\n        # replace existing\n        if self._scheduler.get_job(spec.id):\n            self._scheduler.remove_job(spec.id)\n\n        self._scheduler.add_job(\n            self._scheduled_callback,\n            trigger=trigger,\n            id=spec.id,\n            args=[spec.id],\n            misfire_grace_time=spec.runtime.misfire_grace_seconds,\n            replace_existing=True,\n        )\n\n        if not spec.enabled:\n            self._scheduler.pause_job(spec.id)\n\n        # update next_run\n        aps_job = self._scheduler.get_job(spec.id)\n        st = self._states.get(spec.id, CronJobState())\n        st.next_run_at = aps_job.next_run_time if aps_job else None\n        self._states[spec.id] = st\n\n    def _build_trigger(self, spec: CronJobSpec) -> CronTrigger:\n        # enforce 5 fields (no seconds)\n        parts = [p for p in spec.schedule.cron.split() if p]\n        if len(parts) != 5:\n            raise ValueError(\n                f\"cron must have 5 fields, got {len(parts)}:\"\n                f\" {spec.schedule.cron}\",\n            )\n\n        minute, hour, day, month, day_of_week = parts\n        return CronTrigger(\n            minute=minute,\n            hour=hour,\n            day=day,\n            month=month,\n            day_of_week=day_of_week,\n            timezone=spec.schedule.timezone,\n        )\n\n    async def _scheduled_callback(self, job_id: str) -> None:\n        job = await self._repo.get_job(job_id)\n        if not job:\n            return\n\n        await self._execute_once(job)\n\n        # refresh next_run\n        aps_job = self._scheduler.get_job(job_id)\n        st = self._states.get(job_id, CronJobState())\n        st.next_run_at = aps_job.next_run_time if aps_job else None\n        self._states[job_id] = st\n\n    async def _heartbeat_callback(self) -> None:\n        \"\"\"Run one heartbeat (HEARTBEAT.md as query, optional dispatch).\"\"\"\n        try:\n            # Get workspace_dir from runner if available\n            workspace_dir = None\n            if hasattr(self._runner, \"workspace_dir\"):\n                workspace_dir = self._runner.workspace_dir\n\n            await run_heartbeat_once(\n                runner=self._runner,\n                channel_manager=self._channel_manager,\n                agent_id=self._agent_id,\n                workspace_dir=workspace_dir,\n            )\n        except asyncio.CancelledError:\n            logger.info(\"heartbeat cancelled\")\n            raise\n        except Exception:  # pylint: disable=broad-except\n            logger.exception(\"heartbeat run failed\")\n\n    async def _execute_once(self, job: CronJobSpec) -> None:\n        rt = self._rt.get(job.id)\n        if not rt:\n            rt = _Runtime(sem=asyncio.Semaphore(job.runtime.max_concurrency))\n            self._rt[job.id] = rt\n\n        async with rt.sem:\n            st = self._states.get(job.id, CronJobState())\n            st.last_status = \"running\"\n            self._states[job.id] = st\n\n            try:\n                await self._executor.execute(job)\n                st.last_status = \"success\"\n                st.last_error = None\n                logger.info(\n                    \"cron _execute_once: job_id=%s status=success\",\n                    job.id,\n                )\n            except asyncio.CancelledError:\n                st.last_status = \"cancelled\"\n                st.last_error = \"Job was cancelled\"\n                logger.info(\n                    \"cron _execute_once: job_id=%s status=cancelled\",\n                    job.id,\n                )\n                raise\n            except Exception as e:  # pylint: disable=broad-except\n                st.last_status = \"error\"\n                st.last_error = repr(e)\n                logger.warning(\n                    \"cron _execute_once: job_id=%s status=error error=%s\",\n                    job.id,\n                    repr(e),\n                )\n                raise\n            finally:\n                st.last_run_at = datetime.now(timezone.utc)\n                self._states[job.id] = st\n"
  },
  {
    "path": "src/copaw/app/crons/models.py",
    "content": "# -*- coding: utf-8 -*-\nfrom __future__ import annotations\n\nfrom datetime import datetime\nfrom typing import Any, Dict, Literal, Optional\n\nfrom pydantic import (\n    BaseModel,\n    ConfigDict,\n    Field,\n    field_validator,\n    model_validator,\n)\n\nfrom ..channels.schema import DEFAULT_CHANNEL\n\n# ---------------------------------------------------------------------------\n# APScheduler v3 uses ISO 8601 weekday numbering (0=Mon … 6=Sun) for\n# CronTrigger(day_of_week=...), while standard crontab uses 0=Sun … 6=Sat.\n# from_crontab() does NOT convert either.  Three-letter English abbreviations\n# (mon, tue, …, sun) are unambiguous in both systems, so we normalise the\n# 5th cron field to abbreviations at validation time.\n# ---------------------------------------------------------------------------\n\n_CRONTAB_NUM_TO_NAME: dict[str, str] = {\n    \"0\": \"sun\",\n    \"1\": \"mon\",\n    \"2\": \"tue\",\n    \"3\": \"wed\",\n    \"4\": \"thu\",\n    \"5\": \"fri\",\n    \"6\": \"sat\",\n    \"7\": \"sun\",\n}\n\n\ndef _crontab_dow_to_name(field: str) -> str:\n    \"\"\"Convert the day-of-week field from crontab numbers to abbreviations.\n\n    Handles: ``*``, single values, comma-separated lists, and ranges.\n    Already-named values (``mon``, ``tue``, …) are passed through unchanged.\n    \"\"\"\n    if field == \"*\":\n        return field\n\n    def _convert_token(tok: str) -> str:\n        if \"/\" in tok:\n            base, step = tok.rsplit(\"/\", 1)\n            return f\"{_convert_token(base)}/{step}\"\n        if \"-\" in tok:\n            parts = tok.split(\"-\", 1)\n            return \"-\".join(_CRONTAB_NUM_TO_NAME.get(p, p) for p in parts)\n        return _CRONTAB_NUM_TO_NAME.get(tok, tok)\n\n    return \",\".join(_convert_token(t) for t in field.split(\",\"))\n\n\nclass ScheduleSpec(BaseModel):\n    type: Literal[\"cron\"] = \"cron\"\n    cron: str = Field(...)\n    timezone: str = \"UTC\"\n\n    @field_validator(\"cron\")\n    @classmethod\n    def normalize_cron_5_fields(cls, v: str) -> str:\n        parts = [p for p in v.split() if p]\n        if len(parts) == 5:\n            parts[4] = _crontab_dow_to_name(parts[4])\n            return \" \".join(parts)\n\n        if len(parts) == 4:\n            # treat as: hour dom month dow\n            hour, dom, month, dow = parts\n            return f\"0 {hour} {dom} {month} {_crontab_dow_to_name(dow)}\"\n\n        if len(parts) == 3:\n            # treat as: dom month dow\n            dom, month, dow = parts\n            return f\"0 0 {dom} {month} {_crontab_dow_to_name(dow)}\"\n\n        # 6 fields (seconds) or too short: reject\n        raise ValueError(\n            \"cron must have 5 fields \"\n            \"(or 4/3 fields that can be normalized); seconds not supported.\",\n        )\n\n\nclass DispatchTarget(BaseModel):\n    user_id: str\n    session_id: str\n\n\nclass DispatchSpec(BaseModel):\n    type: Literal[\"channel\"] = \"channel\"\n    channel: str = Field(default=DEFAULT_CHANNEL)\n    target: DispatchTarget\n    mode: Literal[\"stream\", \"final\"] = Field(default=\"stream\")\n    meta: Dict[str, Any] = Field(default_factory=dict)\n\n\nclass JobRuntimeSpec(BaseModel):\n    max_concurrency: int = Field(default=1, ge=1)\n    timeout_seconds: int = Field(default=120, ge=1)\n    misfire_grace_seconds: int = Field(default=60, ge=0)\n\n\nclass CronJobRequest(BaseModel):\n    \"\"\"Passthrough payload to runner.stream_query(request=...).\n\n    This is aligned with AgentRequest(extra=\"allow\"). We keep it permissive.\n    \"\"\"\n\n    model_config = ConfigDict(extra=\"allow\")\n\n    input: Any\n    session_id: Optional[str] = None\n    user_id: Optional[str] = None\n\n\nTaskType = Literal[\"text\", \"agent\"]\n\n\nclass CronJobSpec(BaseModel):\n    id: str\n    name: str\n    enabled: bool = True\n\n    schedule: ScheduleSpec\n    task_type: TaskType = \"agent\"\n    text: Optional[str] = None\n    request: Optional[CronJobRequest] = None\n    dispatch: DispatchSpec\n\n    runtime: JobRuntimeSpec = Field(default_factory=JobRuntimeSpec)\n    meta: Dict[str, Any] = Field(default_factory=dict)\n\n    @model_validator(mode=\"after\")\n    def _validate_task_type_fields(self) -> \"CronJobSpec\":\n        if self.task_type == \"text\":\n            if not (self.text and self.text.strip()):\n                raise ValueError(\"task_type is text but text is empty\")\n        elif self.task_type == \"agent\":\n            if self.request is None:\n                raise ValueError(\"task_type is agent but request is missing\")\n            # Keep request.user_id and request.session_id in sync with target\n            target = self.dispatch.target\n            self.request = self.request.model_copy(\n                update={\n                    \"user_id\": target.user_id,\n                    \"session_id\": target.session_id,\n                },\n            )\n        return self\n\n\nclass JobsFile(BaseModel):\n    version: int = 1\n    jobs: list[CronJobSpec] = Field(default_factory=list)\n\n\nclass CronJobState(BaseModel):\n    next_run_at: Optional[datetime] = None\n    last_run_at: Optional[datetime] = None\n    last_status: Optional[\n        Literal[\"success\", \"error\", \"running\", \"skipped\", \"cancelled\"]\n    ] = None\n    last_error: Optional[str] = None\n\n\nclass CronJobView(BaseModel):\n    spec: CronJobSpec\n    state: CronJobState = Field(default_factory=CronJobState)\n"
  },
  {
    "path": "src/copaw/app/crons/repo/__init__.py",
    "content": "# -*- coding: utf-8 -*-\nfrom .base import BaseJobRepository\nfrom .json_repo import JsonJobRepository\n\n__all__ = [\"BaseJobRepository\", \"JsonJobRepository\"]\n"
  },
  {
    "path": "src/copaw/app/crons/repo/base.py",
    "content": "# -*- coding: utf-8 -*-\nfrom __future__ import annotations\n\nfrom abc import ABC, abstractmethod\nfrom typing import Optional\n\nfrom ..models import CronJobSpec, JobsFile\n\n\nclass BaseJobRepository(ABC):\n    \"\"\"Abstract repository for cron job specs persistence.\"\"\"\n\n    @abstractmethod\n    async def load(self) -> JobsFile:\n        \"\"\"Load all jobs from storage.\"\"\"\n        raise NotImplementedError\n\n    @abstractmethod\n    async def save(self, jobs_file: JobsFile) -> None:\n        \"\"\"Persist all jobs to storage (should be atomic if possible).\"\"\"\n        raise NotImplementedError\n\n    # ---- Optional but commonly needed convenience ops ----\n\n    async def list_jobs(self) -> list[CronJobSpec]:\n        jf = await self.load()\n        return jf.jobs\n\n    async def get_job(self, job_id: str) -> Optional[CronJobSpec]:\n        jf = await self.load()\n        for job in jf.jobs:\n            if job.id == job_id:\n                return job\n        return None\n\n    async def upsert_job(self, spec: CronJobSpec) -> None:\n        jf = await self.load()\n        for i, j in enumerate(jf.jobs):\n            if j.id == spec.id:\n                jf.jobs[i] = spec\n                break\n        else:\n            jf.jobs.append(spec)\n        await self.save(jf)\n\n    async def delete_job(self, job_id: str) -> bool:\n        jf = await self.load()\n        before = len(jf.jobs)\n        jf.jobs = [j for j in jf.jobs if j.id != job_id]\n        if len(jf.jobs) == before:\n            return False\n        await self.save(jf)\n        return True\n"
  },
  {
    "path": "src/copaw/app/crons/repo/json_repo.py",
    "content": "# -*- coding: utf-8 -*-\nfrom __future__ import annotations\n\nimport json\nimport shutil\nfrom pathlib import Path\n\nfrom .base import BaseJobRepository\nfrom ..models import JobsFile\n\n\nclass JsonJobRepository(BaseJobRepository):\n    \"\"\"jobs.json repository (single-file storage).\n\n    Notes:\n    - Single-machine, no cross-process lock.\n    - Atomic write: write tmp then replace.\n    \"\"\"\n\n    def __init__(self, path: Path | str):\n        if isinstance(path, str):\n            path = Path(path)\n        self._path = path.expanduser()\n\n    @property\n    def path(self) -> Path:\n        return self._path\n\n    async def load(self) -> JobsFile:\n        if not self._path.exists():\n            return JobsFile(version=1, jobs=[])\n\n        data = json.loads(self._path.read_text(encoding=\"utf-8\"))\n        return JobsFile.model_validate(data)\n\n    async def save(self, jobs_file: JobsFile) -> None:\n        self._path.parent.mkdir(parents=True, exist_ok=True)\n\n        tmp_path = self._path.with_suffix(self._path.suffix + \".tmp\")\n        payload = jobs_file.model_dump(mode=\"json\")\n\n        tmp_path.write_text(\n            json.dumps(payload, ensure_ascii=False, indent=2, sort_keys=True),\n            encoding=\"utf-8\",\n        )\n        shutil.move(str(tmp_path), str(self._path))\n"
  },
  {
    "path": "src/copaw/app/download_task_store.py",
    "content": "# -*- coding: utf-8 -*-\n\"\"\"In-memory store for tracking background model download tasks.\n\nMultiple downloads can run concurrently. Completed/failed results are retained\nuntil explicitly cleared so the frontend can poll for the final state.\n\"\"\"\nfrom __future__ import annotations\n\nimport asyncio\nimport time\nimport uuid\nfrom enum import Enum\nfrom typing import Any, Dict, List, Optional\n\nfrom pydantic import BaseModel, Field\n\n\nclass DownloadTaskStatus(str, Enum):\n    PENDING = \"pending\"\n    DOWNLOADING = \"downloading\"\n    COMPLETED = \"completed\"\n    FAILED = \"failed\"\n    CANCELLED = \"cancelled\"\n\n\nclass DownloadTask(BaseModel):\n    task_id: str = Field(default_factory=lambda: str(uuid.uuid4()))\n    repo_id: str\n    filename: Optional[str] = None\n    backend: str\n    source: str\n    status: DownloadTaskStatus = DownloadTaskStatus.PENDING\n    error: Optional[str] = None\n    result: Optional[Dict[str, Any]] = None\n    created_at: float = Field(default_factory=time.time)\n    updated_at: float = Field(default_factory=time.time)\n\n\n_tasks: Dict[str, DownloadTask] = {}\n_lock = asyncio.Lock()\n\n\nasync def create_task(\n    repo_id: str,\n    filename: Optional[str],\n    backend: str,\n    source: str,\n) -> DownloadTask:\n    \"\"\"Create a new pending download task.\"\"\"\n    async with _lock:\n        task = DownloadTask(\n            repo_id=repo_id,\n            filename=filename,\n            backend=backend,\n            source=source,\n        )\n        _tasks[task.task_id] = task\n        return task\n\n\nasync def get_tasks(backend: Optional[str] = None) -> List[DownloadTask]:\n    \"\"\"Return all tasks, optionally filtered by backend.\"\"\"\n    async with _lock:\n        tasks = list(_tasks.values())\n    if backend:\n        tasks = [t for t in tasks if t.backend == backend]\n    return tasks\n\n\nasync def get_task(task_id: str) -> Optional[DownloadTask]:\n    \"\"\"Return a specific task by ID.\"\"\"\n    async with _lock:\n        return _tasks.get(task_id)\n\n\nasync def update_status(\n    task_id: str,\n    status: DownloadTaskStatus,\n    *,\n    error: Optional[str] = None,\n    result: Optional[Dict[str, Any]] = None,\n) -> None:\n    \"\"\"Update the status of a task. No-op if task_id doesn't exist.\"\"\"\n    async with _lock:\n        task = _tasks.get(task_id)\n        if task is None:\n            return\n        task.status = status\n        task.updated_at = time.time()\n        if error is not None:\n            task.error = error\n        if result is not None:\n            task.result = result\n\n\nasync def cancel_task(task_id: str) -> bool:\n    \"\"\"Cancel a pending or downloading task.\n\n    Returns True if cancelled, False if task not found or not cancellable.\n    \"\"\"\n    async with _lock:\n        task = _tasks.get(task_id)\n        if task is None:\n            return False\n        if task.status not in (\n            DownloadTaskStatus.PENDING,\n            DownloadTaskStatus.DOWNLOADING,\n        ):\n            return False\n        task.status = DownloadTaskStatus.CANCELLED\n        task.updated_at = time.time()\n        return True\n\n\nasync def clear_completed(backend: Optional[str] = None) -> None:\n    \"\"\"Remove tasks in a terminal state (completed/failed/cancelled).\"\"\"\n    async with _lock:\n        to_remove = [\n            tid\n            for tid, t in _tasks.items()\n            if t.status\n            in (\n                DownloadTaskStatus.COMPLETED,\n                DownloadTaskStatus.FAILED,\n                DownloadTaskStatus.CANCELLED,\n            )\n            and (backend is None or t.backend == backend)\n        ]\n        for tid in to_remove:\n            del _tasks[tid]\n"
  },
  {
    "path": "src/copaw/app/mcp/__init__.py",
    "content": "# -*- coding: utf-8 -*-\n\"\"\"MCP (Model Context Protocol) client management module.\n\nThis module provides hot-reloadable MCP client management,\ncompletely independent from other app components.\n\"\"\"\n\nfrom .manager import MCPClientManager\nfrom .watcher import MCPConfigWatcher\n\n__all__ = [\n    \"MCPClientManager\",\n    \"MCPConfigWatcher\",\n]\n"
  },
  {
    "path": "src/copaw/app/mcp/manager.py",
    "content": "# -*- coding: utf-8 -*-\n\"\"\"MCP client manager for hot-reloadable client lifecycle management.\n\nThis module provides centralized management of MCP clients with support\nfor runtime updates without restarting the application.\n\"\"\"\n\nfrom __future__ import annotations\n\nimport asyncio\nimport logging\nimport os\nfrom typing import Any, Dict, List, TYPE_CHECKING\n\nfrom agentscope.mcp import HttpStatefulClient, StdIOStatefulClient\n\nif TYPE_CHECKING:\n    from ...config.config import MCPClientConfig, MCPConfig\n\nlogger = logging.getLogger(__name__)\n\n\nclass MCPClientManager:\n    \"\"\"Manages MCP clients with hot-reload support.\n\n    This manager handles the lifecycle of MCP clients, including:\n    - Initial loading from config\n    - Runtime replacement when config changes\n    - Cleanup on shutdown\n\n    Design pattern mirrors ChannelManager for consistency.\n    \"\"\"\n\n    def __init__(self) -> None:\n        \"\"\"Initialize an empty MCP client manager.\"\"\"\n        self._clients: Dict[str, Any] = {}\n        self._lock = asyncio.Lock()\n\n    async def init_from_config(self, config: \"MCPConfig\") -> None:\n        \"\"\"Initialize clients from configuration.\n\n        Args:\n            config: MCP configuration containing client definitions\n        \"\"\"\n        logger.debug(\"Initializing MCP clients from config\")\n        for key, client_config in config.clients.items():\n            if not client_config.enabled:\n                logger.debug(f\"MCP client '{key}' is disabled, skipping\")\n                continue\n\n            try:\n                await self._add_client(key, client_config)\n                logger.debug(f\"MCP client '{key}' initialized successfully\")\n            except BaseException as e:\n                if isinstance(e, (KeyboardInterrupt, SystemExit)):\n                    raise\n                logger.warning(\n                    f\"Failed to initialize MCP client '{key}': {e}\",\n                    exc_info=True,\n                )\n\n    async def get_clients(self) -> List[Any]:\n        \"\"\"Get list of all active MCP clients.\n\n        This method is called by the runner on each query to get\n        the latest set of clients.\n\n        Returns:\n            List of connected MCP client instances\n        \"\"\"\n        async with self._lock:\n            return [\n                client\n                for client in self._clients.values()\n                if client is not None\n            ]\n\n    async def replace_client(\n        self,\n        key: str,\n        client_config: \"MCPClientConfig\",\n        timeout: float = 60.0,\n    ) -> None:\n        \"\"\"Replace or add a client with new configuration.\n\n        Flow: connect new (outside lock) → swap + close old (inside lock).\n        This ensures minimal lock holding time.\n\n        Args:\n            key: Client identifier (from config)\n            client_config: New client configuration\n            timeout: Connection timeout in seconds (default 60s)\n        \"\"\"\n        # 1. Create and connect new client outside lock (may be slow)\n        logger.debug(f\"Connecting new MCP client: {key}\")\n        new_client = self._build_client(client_config)\n\n        try:\n            # Add timeout to prevent indefinite blocking\n            await asyncio.wait_for(new_client.connect(), timeout=timeout)\n        except asyncio.TimeoutError:\n            logger.warning(\n                f\"Timeout connecting MCP client '{key}' after {timeout}s\",\n            )\n            try:\n                await new_client.close()\n            except Exception:\n                pass\n            raise\n        except Exception as e:\n            logger.warning(f\"Failed to connect MCP client '{key}': {e}\")\n            try:\n                await new_client.close()\n            except Exception:\n                pass\n            raise\n\n        # 2. Swap and close old client inside lock\n        async with self._lock:\n            old_client = self._clients.get(key)\n            self._clients[key] = new_client\n\n            if old_client is not None:\n                logger.debug(f\"Closing old MCP client: {key}\")\n                try:\n                    await old_client.close()\n                except Exception as e:\n                    logger.warning(\n                        f\"Error closing old MCP client '{key}': {e}\",\n                    )\n            else:\n                logger.debug(f\"Added new MCP client: {key}\")\n\n    async def remove_client(self, key: str) -> None:\n        \"\"\"Remove and close a client.\n\n        Args:\n            key: Client identifier to remove\n        \"\"\"\n        async with self._lock:\n            old_client = self._clients.pop(key, None)\n\n        if old_client is not None:\n            logger.debug(f\"Removing MCP client: {key}\")\n            try:\n                await old_client.close()\n            except Exception as e:\n                logger.warning(f\"Error closing MCP client '{key}': {e}\")\n\n    async def close_all(self) -> None:\n        \"\"\"Close all MCP clients.\n\n        Called during application shutdown.\n        \"\"\"\n        async with self._lock:\n            clients_snapshot = list(self._clients.items())\n            self._clients.clear()\n\n        logger.debug(\"Closing all MCP clients\")\n        for key, client in clients_snapshot:\n            if client is not None:\n                try:\n                    await client.close()\n                except Exception as e:\n                    logger.warning(f\"Error closing MCP client '{key}': {e}\")\n\n    async def _add_client(\n        self,\n        key: str,\n        client_config: \"MCPClientConfig\",\n        timeout: float = 60.0,\n    ) -> None:\n        \"\"\"Add a new client (used during initial setup).\n\n        Args:\n            key: Client identifier\n            client_config: Client configuration\n            timeout: Connection timeout in seconds (default 60s)\n        \"\"\"\n        client = self._build_client(client_config)\n\n        # Add timeout to prevent indefinite blocking\n        await asyncio.wait_for(client.connect(), timeout=timeout)\n\n        async with self._lock:\n            self._clients[key] = client\n\n    @staticmethod\n    def _build_client(client_config: \"MCPClientConfig\") -> Any:\n        \"\"\"Build MCP client instance by configured transport.\"\"\"\n        rebuild_info = {\n            \"name\": client_config.name,\n            \"transport\": client_config.transport,\n            \"url\": client_config.url,\n            \"headers\": client_config.headers or None,\n            \"command\": client_config.command,\n            \"args\": list(client_config.args),\n            \"env\": dict(client_config.env),\n            \"cwd\": client_config.cwd or None,\n        }\n\n        if client_config.transport == \"stdio\":\n            client = StdIOStatefulClient(\n                name=client_config.name,\n                command=client_config.command,\n                args=client_config.args,\n                env=client_config.env,\n                cwd=client_config.cwd or None,\n            )\n            setattr(client, \"_copaw_rebuild_info\", rebuild_info)\n            return client\n\n        headers = client_config.headers\n        if headers:\n            headers = {k: os.path.expandvars(v) for k, v in headers.items()}\n\n        client = HttpStatefulClient(\n            name=client_config.name,\n            transport=client_config.transport,\n            url=client_config.url,\n            headers=headers or None,\n        )\n        setattr(client, \"_copaw_rebuild_info\", rebuild_info)\n        return client\n"
  },
  {
    "path": "src/copaw/app/mcp/watcher.py",
    "content": "# -*- coding: utf-8 -*-\n\"\"\"Independent watcher for MCP configuration changes.\n\nThis module provides a self-contained config watcher specifically for MCP,\nwithout coupling to the main ConfigWatcher or other components.\n\"\"\"\n\nfrom __future__ import annotations\n\nimport asyncio\nimport logging\nfrom pathlib import Path\nfrom typing import Callable, Optional, TYPE_CHECKING, Dict\n\nfrom .manager import MCPClientManager\n\nif TYPE_CHECKING:\n    from ...config.config import MCPConfig\n\nlogger = logging.getLogger(__name__)\n\n# How often to poll (seconds)\nDEFAULT_POLL_INTERVAL = 2.0\n\n\nclass MCPConfigWatcher:\n    \"\"\"Watch MCP configuration and hot-reload clients on changes.\n\n    This is a standalone watcher that can be used independently or\n    integrated with the main ConfigWatcher.\n    \"\"\"\n\n    def __init__(\n        self,\n        mcp_manager: MCPClientManager,\n        config_loader: Callable,\n        poll_interval: float = DEFAULT_POLL_INTERVAL,\n        config_path: Optional[Path] = None,\n    ):\n        \"\"\"Initialize MCP config watcher.\n\n        Args:\n            mcp_manager: The MCP client manager to update\n            config_loader: Function to load config, should return Config\n                           object with .mcp attribute (or MCPConfig)\n            poll_interval: How often to check for changes (seconds)\n            config_path: Path to config file (for mtime checking)\n        \"\"\"\n        self._mcp_manager = mcp_manager\n        self._config_loader = config_loader\n        self._poll_interval = poll_interval\n        self._config_path = config_path\n        self._task: Optional[asyncio.Task] = None\n\n        # Snapshot of last known MCP config (for diffing)\n        self._last_mcp: Optional[\"MCPConfig\"] = None\n        self._last_mcp_hash: Optional[int] = None\n        # mtime of config file at last check\n        self._last_mtime: float = 0.0\n\n        # Track ongoing reload tasks to prevent blocking\n        self._reload_task: Optional[asyncio.Task] = None\n\n        # Track failed reload attempts per client to prevent infinite retries\n        # Format: {client_key: (retry_count, last_config_hash)}\n        self._client_failures: Dict[str, tuple[int, int]] = {}\n        self._max_retries: int = 3\n\n    async def start(self) -> None:\n        \"\"\"Take initial snapshot and start the polling task.\"\"\"\n        self._snapshot()\n        self._task = asyncio.create_task(\n            self._poll_loop(),\n            name=\"mcp_config_watcher\",\n        )\n        logger.debug(\n            \"MCPConfigWatcher started (poll=%.1fs)\",\n            self._poll_interval,\n        )\n\n    async def stop(self) -> None:\n        \"\"\"Stop the polling task and wait for any ongoing reload.\"\"\"\n        if self._task:\n            self._task.cancel()\n            try:\n                await self._task\n            except asyncio.CancelledError:\n                pass\n            self._task = None\n\n        # Wait for ongoing reload to complete\n        if self._reload_task and not self._reload_task.done():\n            logger.debug(\n                \"MCPConfigWatcher: waiting for reload task to complete\",\n            )\n            try:\n                await asyncio.wait_for(self._reload_task, timeout=5.0)\n            except asyncio.TimeoutError:\n                logger.warning(\n                    \"MCPConfigWatcher: reload task did not finish in time\",\n                )\n                self._reload_task.cancel()\n            except Exception:\n                pass\n\n        logger.debug(\"MCPConfigWatcher stopped\")\n\n    # ------------------------------------------------------------------\n    # Internal methods\n    # ------------------------------------------------------------------\n\n    def _snapshot(self) -> None:\n        \"\"\"Load current MCP config and record mtime + hash.\"\"\"\n        if self._config_path:\n            try:\n                self._last_mtime = self._config_path.stat().st_mtime\n            except FileNotFoundError:\n                self._last_mtime = 0.0\n\n        try:\n            mcp_config = self._load_mcp_config()\n            self._last_mcp = mcp_config.model_copy(deep=True)\n            self._last_mcp_hash = self._mcp_hash(mcp_config)\n        except Exception:\n            logger.warning(\"MCPConfigWatcher: failed to load initial config\")\n            self._last_mcp = None\n            self._last_mcp_hash = None\n\n    def _load_mcp_config(self) -> \"MCPConfig\":\n        \"\"\"Load MCP config using the provided loader.\"\"\"\n        config = self._config_loader()\n        # Support both Config object with .mcp or direct MCPConfig\n        if hasattr(config, \"mcp\"):\n            return config.mcp\n        return config\n\n    @staticmethod\n    def _mcp_hash(mcp_config: \"MCPConfig\") -> int:\n        \"\"\"Fast hash of MCP config for quick change detection.\"\"\"\n        return hash(str(mcp_config.model_dump(mode=\"json\")))\n\n    async def _poll_loop(self) -> None:\n        \"\"\"Main polling loop.\"\"\"\n        while True:\n            try:\n                await asyncio.sleep(self._poll_interval)\n                await self._check()\n            except Exception:\n                logger.exception(\"MCPConfigWatcher: poll iteration failed\")\n\n    async def _check(self) -> None:\n        \"\"\"Check for config changes and reload if needed.\"\"\"\n        # 1) Check mtime if config path is provided\n        if self._config_path:\n            try:\n                mtime = self._config_path.stat().st_mtime\n            except FileNotFoundError:\n                return\n            if mtime == self._last_mtime:\n                return\n            self._last_mtime = mtime\n\n        # 2) Load new config; quick-reject if MCP section unchanged\n        try:\n            new_mcp = self._load_mcp_config()\n        except Exception:\n            logger.debug(\"MCPConfigWatcher: failed to parse config\")\n            return\n\n        new_hash = self._mcp_hash(new_mcp)\n        if new_hash == self._last_mcp_hash:\n            return  # No changes\n\n        # 3) Check if previous reload is still running\n        if self._reload_task and not self._reload_task.done():\n            logger.debug(\n                \"MCPConfigWatcher: skipping reload, \"\n                \"previous reload still in progress\",\n            )\n            return\n\n        # 4) Trigger non-blocking reload in background task\n        logger.debug(\n            \"MCPConfigWatcher: detected config changes, starting reload\",\n        )\n        self._reload_task = asyncio.create_task(\n            self._reload_changed_clients_wrapper(new_mcp),\n            name=\"mcp_reload_task\",\n        )\n        # Note: Snapshot is updated by the background task on success\n\n    async def _reload_changed_clients_wrapper(\n        self,\n        new_mcp: \"MCPConfig\",\n    ) -> None:\n        \"\"\"Wrapper for reload that handles exceptions without crashing watcher.\n\n        Updates snapshot only on successful reload to allow retry on failure.\n        Tracks failed attempts per client to prevent infinite retries.\n\n        Args:\n            new_mcp: New MCP configuration\n        \"\"\"\n        new_hash = self._mcp_hash(new_mcp)\n\n        try:\n            await self._reload_changed_clients(new_mcp)\n            # Success: update snapshot\n            self._last_mcp = new_mcp.model_copy(deep=True)\n            self._last_mcp_hash = new_hash\n            logger.debug(\"MCPConfigWatcher: reload completed successfully\")\n        except Exception:\n            logger.warning(\"MCPConfigWatcher: reload task failed\")\n\n    async def _reload_changed_clients(self, new_mcp: \"MCPConfig\") -> None:\n        \"\"\"Compare old and new MCP configs and reload changed clients.\n\n        Args:\n            new_mcp: New MCP configuration\n        \"\"\"\n        old_mcp = self._last_mcp\n        old_clients = old_mcp.clients if old_mcp else {}\n\n        # Check for new or changed clients\n        for key, new_cfg in new_mcp.clients.items():\n            old_cfg = old_clients.get(key)\n            await self._handle_client_update(key, old_cfg, new_cfg)\n\n        # Remove clients that no longer exist in config\n        for key in old_clients:\n            if key not in new_mcp.clients:\n                await self._handle_client_removal(key)\n\n    async def _handle_client_update(\n        self,\n        key: str,\n        old_cfg,\n        new_cfg,\n    ) -> None:\n        \"\"\"Handle update for a single client.\"\"\"\n        # Client disabled: remove if it was previously enabled\n        if not new_cfg.enabled:\n            if old_cfg and old_cfg.enabled:\n                logger.debug(\n                    \"MCPConfigWatcher: client '%s' disabled, removing\",\n                    key,\n                )\n                try:\n                    await self._mcp_manager.remove_client(key)\n                    self._client_failures.pop(key, None)\n                except Exception:\n                    logger.debug(\n                        \"MCPConfigWatcher: failed to remove client '%s'\",\n                        key,\n                    )\n            return\n\n        # Client enabled: check if config changed\n        if old_cfg != new_cfg:\n            await self._reload_single_client(key, new_cfg)\n\n    async def _reload_single_client(self, key: str, new_cfg) -> None:\n        \"\"\"Reload a single client with retry tracking.\"\"\"\n        client_hash = hash(str(new_cfg.model_dump(mode=\"json\")))\n\n        # Check if this client should be skipped\n        if self._should_skip_client(key, client_hash):\n            return\n\n        logger.debug(\n            \"MCPConfigWatcher: client '%s' config changed, reloading\",\n            key,\n        )\n        try:\n            await self._mcp_manager.replace_client(key, new_cfg)\n            logger.debug(\n                \"MCPConfigWatcher: client '%s' reloaded successfully\",\n                key,\n            )\n            self._client_failures.pop(key, None)\n        except Exception:\n            self._track_client_failure(key, client_hash)\n\n    def _should_skip_client(self, key: str, client_hash: int) -> bool:\n        \"\"\"Check if client should be skipped due to failures.\"\"\"\n        if key in self._client_failures:\n            retry_count, last_hash = self._client_failures[key]\n            if last_hash == client_hash and retry_count >= self._max_retries:\n                logger.debug(\n                    f\"MCPConfigWatcher: skipping client '{key}', \"\n                    f\"failed {retry_count} times. \"\n                    f\"Modify config to retry.\",\n                )\n                return True\n        return False\n\n    def _track_client_failure(self, key: str, client_hash: int) -> None:\n        \"\"\"Track failure for a specific client.\"\"\"\n        if key in self._client_failures:\n            old_count, old_hash = self._client_failures[key]\n            new_count = old_count + 1 if old_hash == client_hash else 1\n        else:\n            new_count = 1\n\n        self._client_failures[key] = (new_count, client_hash)\n\n        if new_count >= self._max_retries:\n            logger.warning(\n                f\"MCPConfigWatcher: client '{key}' failed \"\n                f\"{new_count} times, giving up. \"\n                f\"Fix config and modify to retry.\",\n            )\n        else:\n            logger.debug(\n                f\"MCPConfigWatcher: failed to reload \"\n                f\"client '{key}' \"\n                f\"(attempt {new_count}/{self._max_retries})\",\n            )\n\n    async def _handle_client_removal(self, key: str) -> None:\n        \"\"\"Handle removal of a client from config.\"\"\"\n        logger.debug(\n            \"MCPConfigWatcher: client '%s' removed from config\",\n            key,\n        )\n        try:\n            await self._mcp_manager.remove_client(key)\n            self._client_failures.pop(key, None)\n        except Exception:\n            logger.debug(\n                \"MCPConfigWatcher: failed to remove client '%s'\",\n                key,\n            )\n"
  },
  {
    "path": "src/copaw/app/migration.py",
    "content": "# -*- coding: utf-8 -*-\n\"\"\"Configuration migration utilities for multi-agent support.\n\nHandles migration from legacy single-agent config to new multi-agent structure.\n\"\"\"\nimport json\nimport logging\nimport shutil\nfrom pathlib import Path\n\nfrom ..config.config import (\n    AgentProfileConfig,\n    AgentProfileRef,\n    AgentsConfig,\n    AgentsRunningConfig,\n    AgentsLLMRoutingConfig,\n)\nfrom ..constant import WORKING_DIR\nfrom ..config.utils import load_config, save_config\n\nlogger = logging.getLogger(__name__)\n\n# Workspace items to migrate: (name, is_directory)\n_WORKSPACE_ITEMS_TO_MIGRATE = [\n    # Directories\n    (\"sessions\", True),\n    (\"memory\", True),\n    (\"active_skills\", True),\n    (\"customized_skills\", True),\n    # Files\n    (\"chats.json\", False),\n    (\"jobs.json\", False),\n    (\"feishu_receive_ids.json\", False),\n    (\"dingtalk_session_webhooks.json\", False),\n    # Markdown files\n    (\"AGENTS.md\", False),\n    (\"SOUL.md\", False),\n    (\"PROFILE.md\", False),\n    (\"HEARTBEAT.md\", False),\n    (\"MEMORY.md\", False),\n    (\"BOOTSTRAP.md\", False),\n]\n\n\ndef migrate_legacy_workspace_to_default_agent() -> bool:\n    \"\"\"Migrate legacy single-agent workspace to default agent workspace.\n\n    This function:\n    1. Checks if migration is needed\n    2. Creates default agent workspace\n    3. Migrates legacy workspace files and directories\n    4. Creates agent.json with legacy configuration\n    5. Updates root config.json to new structure\n\n    Returns:\n        bool: True if migration was performed, False if already migrated\n    \"\"\"\n    try:\n        config = load_config()\n    except Exception as e:\n        logger.error(f\"Failed to load config: {e}\")\n        return False\n\n    # Check if already migrated\n    # Skip if:\n    # 1. Multiple agents already exist (multi-agent config), OR\n    # 2. Default agent has agent.json (already migrated)\n    if len(config.agents.profiles) > 1:\n        logger.debug(\n            f\"Multi-agent config already exists \"\n            f\"({len(config.agents.profiles)} agents), skipping migration\",\n        )\n        return False\n\n    if \"default\" in config.agents.profiles:\n        agent_ref = config.agents.profiles[\"default\"]\n        if isinstance(agent_ref, AgentProfileRef):\n            workspace_dir = Path(agent_ref.workspace_dir).expanduser()\n            agent_config_path = workspace_dir / \"agent.json\"\n            if agent_config_path.exists():\n                logger.debug(\n                    \"Default agent already migrated, skipping migration\",\n                )\n                return False\n\n    logger.info(\"=\" * 60)\n    logger.info(\"Migrating legacy config to multi-agent structure...\")\n    logger.info(\"=\" * 60)\n\n    # Extract legacy agent configuration\n    legacy_agents = config.agents\n\n    # Create default agent workspace\n    default_workspace = Path(f\"{WORKING_DIR}/workspaces/default\").expanduser()\n    default_workspace.mkdir(parents=True, exist_ok=True)\n    logger.info(f\"Created default agent workspace: {default_workspace}\")\n\n    # Build default agent configuration from legacy settings\n    default_agent_config = AgentProfileConfig(\n        id=\"default\",\n        name=\"Default Agent\",\n        description=\"Default CoPaw agent (migrated from legacy config)\",\n        workspace_dir=str(default_workspace),\n        channels=config.channels if hasattr(config, \"channels\") else None,\n        mcp=config.mcp if hasattr(config, \"mcp\") else None,\n        heartbeat=(\n            legacy_agents.defaults.heartbeat\n            if hasattr(legacy_agents, \"defaults\") and legacy_agents.defaults\n            else None\n        ),\n        running=(\n            legacy_agents.running\n            if hasattr(legacy_agents, \"running\") and legacy_agents.running\n            else AgentsRunningConfig()\n        ),\n        llm_routing=(\n            legacy_agents.llm_routing\n            if hasattr(legacy_agents, \"llm_routing\")\n            and legacy_agents.llm_routing\n            else AgentsLLMRoutingConfig()\n        ),\n        system_prompt_files=(\n            legacy_agents.system_prompt_files\n            if hasattr(legacy_agents, \"system_prompt_files\")\n            and legacy_agents.system_prompt_files\n            else [\"AGENTS.md\", \"SOUL.md\", \"PROFILE.md\"]\n        ),\n        tools=config.tools if hasattr(config, \"tools\") else None,\n        security=config.security if hasattr(config, \"security\") else None,\n    )\n\n    # Save default agent configuration to workspace/agent.json\n    agent_config_path = default_workspace / \"agent.json\"\n    with open(agent_config_path, \"w\", encoding=\"utf-8\") as f:\n        json.dump(\n            default_agent_config.model_dump(exclude_none=True),\n            f,\n            ensure_ascii=False,\n            indent=2,\n        )\n    logger.info(f\"Created agent config: {agent_config_path}\")\n\n    migrated_items = []\n\n    _migrate_workspace_items_from_source(\n        WORKING_DIR,\n        default_workspace,\n        migrated_items,\n    )\n\n    if migrated_items:\n        logger.info(f\"Migrated workspace items: {', '.join(migrated_items)}\")\n\n    # Update root config.json to new structure\n    # CRITICAL: Preserve legacy agent fields in root config for downgrade\n    # compatibility. Old versions expect these fields to have valid values.\n    config.agents = AgentsConfig(\n        active_agent=\"default\",\n        profiles={\n            \"default\": AgentProfileRef(\n                id=\"default\",\n                workspace_dir=str(default_workspace),\n            ),\n        },\n        # Preserve legacy fields with values from migrated agent config\n        running=default_agent_config.running,\n        llm_routing=default_agent_config.llm_routing,\n        language=default_agent_config.language,\n        system_prompt_files=default_agent_config.system_prompt_files,\n    )\n\n    # IMPORTANT: Keep original config fields in root config.json for\n    # backward compatibility. If user downgrades, old version can still\n    # use these fields. New version will prioritize agent.json.\n    # DO NOT clear: channels, mcp, tools, security fields\n\n    save_config(config)\n    logger.info(\n        \"Updated root config.json to multi-agent structure \"\n        \"(kept original fields for backward compatibility)\",\n    )\n\n    logger.info(\"=\" * 60)\n    logger.info(\"Migration completed successfully!\")\n    logger.info(f\"  Default agent workspace: {default_workspace}\")\n    logger.info(f\"  Default agent config: {agent_config_path}\")\n    logger.info(\"=\" * 60)\n\n    return True\n\n\ndef _migrate_workspace_item(\n    old_path: Path,\n    new_path: Path,\n    item_name: str,\n    migrated_items: list,\n) -> None:\n    \"\"\"Migrate a single workspace item (file or directory).\n\n    Args:\n        old_path: Source path\n        new_path: Destination path\n        item_name: Name for logging\n        migrated_items: List to append migrated item names\n    \"\"\"\n    if not old_path.exists():\n        return\n\n    if new_path.exists():\n        logger.debug(f\"Skipping {item_name} (already exists in new location)\")\n        return\n\n    try:\n        if old_path.is_dir():\n            shutil.copytree(old_path, new_path)\n        else:\n            new_path.parent.mkdir(parents=True, exist_ok=True)\n            shutil.copy2(old_path, new_path)\n\n        migrated_items.append(item_name)\n        logger.debug(f\"Migrated {item_name}\")\n    except Exception as e:\n        logger.warning(f\"Failed to migrate {item_name}: {e}\")\n\n\ndef _migrate_workspace_items_from_source(\n    source_dir: Path,\n    target_dir: Path,\n    migrated_items: list,\n) -> None:\n    \"\"\"Migrate all workspace items from a single source directory.\n\n    Args:\n        source_dir: Source directory (e.g., ~/.copaw or WORKING_DIR)\n        target_dir: Target directory (e.g., workspaces/default/)\n        migrated_items: List to append migrated item names\n    \"\"\"\n    for item_name, _ in _WORKSPACE_ITEMS_TO_MIGRATE:\n        _migrate_workspace_item(\n            source_dir / item_name,\n            target_dir / item_name,\n            item_name,\n            migrated_items,\n        )\n\n\ndef ensure_default_agent_exists() -> None:\n    \"\"\"Ensure that the default agent exists in config.\n\n    This function is called on startup to verify the default agent\n    is properly configured. If not, it will be created.\n    Also ensures necessary workspace files exist (chats.json, jobs.json).\n    \"\"\"\n    config = load_config()\n\n    # Get or determine default workspace path\n    if \"default\" in config.agents.profiles:\n        agent_ref = config.agents.profiles[\"default\"]\n        default_workspace = Path(agent_ref.workspace_dir).expanduser()\n        agent_existed = True\n    else:\n        default_workspace = Path(\n            f\"{WORKING_DIR}/workspaces/default\",\n        ).expanduser()\n        agent_existed = False\n\n    # Ensure workspace directory exists\n    default_workspace.mkdir(parents=True, exist_ok=True)\n\n    # Always ensure chats.json exists (even if agent already registered)\n    chats_file = default_workspace / \"chats.json\"\n    if not chats_file.exists():\n        with open(chats_file, \"w\", encoding=\"utf-8\") as f:\n            json.dump(\n                {\"version\": 1, \"chats\": []},\n                f,\n                ensure_ascii=False,\n                indent=2,\n            )\n        logger.debug(\"Created chats.json for default agent\")\n\n    # Always ensure jobs.json exists (even if agent already registered)\n    jobs_file = default_workspace / \"jobs.json\"\n    if not jobs_file.exists():\n        with open(jobs_file, \"w\", encoding=\"utf-8\") as f:\n            json.dump(\n                {\"version\": 1, \"jobs\": []},\n                f,\n                ensure_ascii=False,\n                indent=2,\n            )\n        logger.debug(\"Created jobs.json for default agent\")\n\n    # Only update config if agent didn't exist\n    if not agent_existed:\n        logger.info(\"Creating default agent...\")\n\n        # Add default agent reference to config\n        config.agents.profiles[\"default\"] = AgentProfileRef(\n            id=\"default\",\n            workspace_dir=str(default_workspace),\n        )\n\n        # Set as active if no active agent\n        if not config.agents.active_agent:\n            config.agents.active_agent = \"default\"\n\n        save_config(config)\n        logger.info(\n            f\"Created default agent with workspace: {default_workspace}\",\n        )\n"
  },
  {
    "path": "src/copaw/app/multi_agent_manager.py",
    "content": "# -*- coding: utf-8 -*-\n\"\"\"MultiAgentManager: Manages multiple agent workspaces with lazy loading.\n\nProvides centralized management for multiple Workspace objects,\nincluding lazy loading, lifecycle management, and hot reloading.\n\"\"\"\nimport asyncio\nimport logging\nfrom typing import Dict, Set\n\nfrom .workspace import Workspace\nfrom ..config.utils import load_config\n\nlogger = logging.getLogger(__name__)\n\n\nclass MultiAgentManager:\n    \"\"\"Manages multiple agent workspaces.\n\n    Features:\n    - Lazy loading: Workspaces are created only when first requested\n    - Lifecycle management: Start, stop, reload workspaces\n    - Thread-safe: Uses async lock for concurrent access\n    - Hot reload: Reload individual workspaces without affecting others\n    \"\"\"\n\n    def __init__(self):\n        \"\"\"Initialize multi-agent manager.\"\"\"\n        self.agents: Dict[str, Workspace] = {}\n        self._lock = asyncio.Lock()\n        self._cleanup_tasks: Set[asyncio.Task] = set()\n        logger.debug(\"MultiAgentManager initialized\")\n\n    async def get_agent(self, agent_id: str) -> Workspace:\n        \"\"\"Get agent workspace by ID (lazy loading).\n\n        If workspace doesn't exist in memory, it will be created and started.\n        Thread-safe using async lock.\n\n        Args:\n            agent_id: Agent ID to retrieve\n\n        Returns:\n            Workspace: The requested workspace instance\n\n        Raises:\n            ValueError: If agent ID not found in configuration\n        \"\"\"\n        async with self._lock:\n            # Return existing agent if already loaded\n            if agent_id in self.agents:\n                logger.debug(f\"Returning cached agent: {agent_id}\")\n                return self.agents[agent_id]\n\n            # Load configuration to get agent reference\n            config = load_config()\n\n            if agent_id not in config.agents.profiles:\n                raise ValueError(\n                    f\"Agent '{agent_id}' not found in configuration. \"\n                    f\"Available agents: {list(config.agents.profiles.keys())}\",\n                )\n\n            agent_ref = config.agents.profiles[agent_id]\n\n            # Create and start new workspace\n            logger.info(f\"Creating new workspace: {agent_id}\")\n            instance = Workspace(\n                agent_id=agent_id,\n                workspace_dir=agent_ref.workspace_dir,\n            )\n\n            try:\n                await instance.start()\n                instance.set_manager(self)  # Set manager reference\n                self.agents[agent_id] = instance\n                logger.info(f\"Workspace created and started: {agent_id}\")\n                return instance\n            except Exception as e:\n                logger.error(f\"Failed to start workspace {agent_id}: {e}\")\n                raise\n\n    async def _graceful_stop_old_instance(\n        self,\n        old_instance: Workspace,\n        agent_id: str,\n    ) -> None:\n        \"\"\"Gracefully stop old instance after checking for active tasks.\n\n        If active tasks exist, schedule delayed cleanup in background.\n        Otherwise, stop immediately.\n\n        Args:\n            old_instance: The old workspace instance to stop\n            agent_id: Agent ID for logging\n        \"\"\"\n        has_active = await old_instance.task_tracker.has_active_tasks()\n\n        if has_active:\n            # Active tasks - schedule delayed cleanup in background\n            active_tasks = await old_instance.task_tracker.list_active_tasks()\n            logger.info(\n                f\"Old workspace instance has {len(active_tasks)} active \"\n                f\"task(s): {active_tasks}. Scheduling delayed cleanup for \"\n                f\"{agent_id}.\",\n            )\n\n            async def delayed_cleanup():\n                \"\"\"Wait for tasks to complete, then stop old instance.\"\"\"\n                try:\n                    # Wait up to 1 minutes for tasks to complete\n                    completed = await old_instance.task_tracker.wait_all_done(\n                        timeout=60.0,\n                    )\n                    if completed:\n                        logger.info(\n                            f\"All tasks completed for old instance \"\n                            f\"{agent_id}. Stopping now.\",\n                        )\n                    else:\n                        logger.warning(\n                            f\"Timeout waiting for tasks to complete for \"\n                            f\"{agent_id}. Forcing stop after 5 minutes.\",\n                        )\n\n                    await old_instance.stop(final=False)\n                    logger.info(\n                        f\"Old workspace instance stopped: {agent_id}. \"\n                        f\"Delayed cleanup completed.\",\n                    )\n                except Exception as e:\n                    logger.warning(\n                        f\"Error during delayed cleanup for {agent_id}: {e}. \"\n                        f\"New instance is serving requests.\",\n                    )\n\n            # Create background task for delayed cleanup and track it\n            cleanup_task = asyncio.create_task(delayed_cleanup())\n            self._cleanup_tasks.add(cleanup_task)\n\n            def _on_cleanup_done(task: asyncio.Task) -> None:\n                \"\"\"Remove task from tracking set and log errors.\"\"\"\n                self._cleanup_tasks.discard(task)\n                if task.cancelled():\n                    logger.info(\n                        f\"Delayed cleanup task for {agent_id} was cancelled.\",\n                    )\n                    return\n                exc = task.exception()\n                if exc is not None:\n                    logger.warning(\n                        f\"Error in delayed cleanup task for {agent_id}: \"\n                        f\"{exc}.\",\n                    )\n\n            cleanup_task.add_done_callback(_on_cleanup_done)\n            logger.info(\n                f\"Zero-downtime reload completed: {agent_id}. \"\n                f\"Old instance cleanup scheduled in background.\",\n            )\n        else:\n            # No active tasks - stop immediately\n            logger.debug(\n                f\"No active tasks in old instance {agent_id}. \"\n                f\"Stopping immediately.\",\n            )\n            try:\n                await old_instance.stop(final=False)\n                logger.info(\n                    f\"Old workspace instance stopped: {agent_id}. \"\n                    f\"Zero-downtime reload completed.\",\n                )\n            except Exception as e:\n                logger.warning(\n                    f\"Failed to stop old workspace instance for \"\n                    f\"{agent_id}: {e}. \"\n                    f\"New instance is active and serving requests.\",\n                )\n\n    async def stop_agent(self, agent_id: str) -> bool:\n        \"\"\"Stop a specific agent instance.\n\n        Args:\n            agent_id: Agent ID to stop\n\n        Returns:\n            bool: True if agent was stopped, False if not running\n        \"\"\"\n        async with self._lock:\n            if agent_id not in self.agents:\n                logger.warning(f\"Agent not running: {agent_id}\")\n                return False\n\n            instance = self.agents[agent_id]\n            await instance.stop()\n            del self.agents[agent_id]\n            logger.info(f\"Agent stopped and removed: {agent_id}\")\n            return True\n\n    async def reload_agent(self, agent_id: str) -> bool:\n        \"\"\"Reload a specific agent instance with zero-downtime.\n\n        This method performs a seamless reload by:\n        1. Creating and fully starting a new workspace instance (no lock)\n        2. Atomically replacing the old instance with the new one (with lock)\n        3. Gracefully stopping the old instance (no lock):\n           - If active tasks exist: schedule delayed cleanup in background\n           - If no active tasks: stop immediately\n\n        The lock is only held during the atomic swap to minimize blocking\n        time for other agent operations.\n\n        This ensures that:\n        - New requests are immediately handled by the new instance\n        - Ongoing SSE/streaming tasks continue uninterrupted\n        - Other agents remain accessible during reload\n        - The manager returns quickly without waiting for old tasks\n        - Old instance is automatically cleaned up after tasks complete\n\n        Args:\n            agent_id: Agent ID to reload\n\n        Returns:\n            bool: True if agent was reloaded, False if not running\n        \"\"\"\n        # Step 1: Check if agent exists (quick check with lock)\n        async with self._lock:\n            if agent_id not in self.agents:\n                logger.debug(\n                    f\"Agent not running, will be loaded on next \"\n                    f\"request: {agent_id}\",\n                )\n                return False\n            old_instance = self.agents[agent_id]\n\n        logger.info(f\"Reloading agent (zero-downtime): {agent_id}\")\n\n        # Step 2: Load configuration (outside lock)\n        config = load_config()\n        if agent_id not in config.agents.profiles:\n            logger.error(\n                f\"Agent '{agent_id}' not found in configuration \"\n                f\"during reload\",\n            )\n            return False\n\n        agent_ref = config.agents.profiles[agent_id]\n\n        # Step 3: Create and start new workspace instance (outside lock)\n        # This is the slow part, but doesn't block other agents\n        logger.info(f\"Creating new workspace instance: {agent_id}\")\n        new_instance = Workspace(\n            agent_id=agent_id,\n            workspace_dir=agent_ref.workspace_dir,\n        )\n\n        # Step 3.5: Set reusable components from old instance (if any)\n        async with self._lock:\n            old_instance = self.agents.get(agent_id)\n\n        if old_instance:\n            # Get all reusable services from old instance's ServiceManager\n            # pylint: disable=protected-access\n            reusable = old_instance._service_manager.get_reusable_services()\n            # pylint: enable=protected-access\n\n            if reusable:\n                await new_instance.set_reusable_components(reusable)\n                logger.info(\n                    f\"Set reusable components for {agent_id}: \"\n                    f\"{list(reusable.keys())}\",\n                )\n\n        try:\n            await new_instance.start()\n            new_instance.set_manager(self)  # Set manager reference\n            logger.info(f\"New workspace instance started: {agent_id}\")\n        except Exception as e:\n            logger.exception(\n                f\"Failed to start new workspace instance for {agent_id}: {e}\",\n            )\n            # Try to clean up the failed new instance\n            try:\n                await new_instance.stop()\n            except Exception:\n                pass  # Best effort cleanup\n            # Old instance is still running and serving requests\n            return False\n\n        # Step 4: Atomic swap (minimal lock time)\n        # From this point, reload is considered successful\n        async with self._lock:\n            # Double-check agent still exists\n            if agent_id not in self.agents:\n                logger.warning(\n                    f\"Agent {agent_id} was removed during reload, \"\n                    f\"stopping new instance\",\n                )\n                await new_instance.stop()\n                return False\n\n            # Swap instances atomically\n            old_instance = self.agents[agent_id]\n            self.agents[agent_id] = new_instance\n            logger.info(f\"Workspace instance replaced: {agent_id}\")\n\n        # Step 5: Gracefully stop old instance (outside lock)\n        # Delegates to helper method to avoid too-many-statements\n        await self._graceful_stop_old_instance(old_instance, agent_id)\n\n        return True\n\n    async def cancel_all_cleanup_tasks(self) -> None:\n        \"\"\"Cancel and await all pending delayed cleanup tasks.\n\n        This ensures that any in-progress background cleanups are either\n        completed or cleanly cancelled before the manager is torn down.\n        Called by stop_all() during shutdown.\n        \"\"\"\n        if not self._cleanup_tasks:\n            return\n\n        logger.info(\n            f\"Cancelling {len(self._cleanup_tasks)} pending cleanup \"\n            f\"task(s)...\",\n        )\n        tasks = list(self._cleanup_tasks)\n        self._cleanup_tasks.clear()\n\n        for task in tasks:\n            if not task.done():\n                task.cancel()\n\n        # Await completion of all tasks, collecting exceptions\n        await asyncio.gather(*tasks, return_exceptions=True)\n        logger.info(\"All cleanup tasks cancelled/completed\")\n\n    async def stop_all(self):\n        \"\"\"Stop all agent instances.\n\n        Called during application shutdown to clean up resources.\n        Cancels any pending delayed cleanup tasks and stops all agents.\n        \"\"\"\n        logger.info(f\"Stopping all agents ({len(self.agents)} running)...\")\n\n        # First, cancel pending cleanup tasks to avoid orphaned instances\n        await self.cancel_all_cleanup_tasks()\n\n        # Create list of agent IDs to avoid modifying dict during iteration\n        agent_ids = list(self.agents.keys())\n\n        for agent_id in agent_ids:\n            try:\n                instance = self.agents[agent_id]\n                await instance.stop()\n                logger.debug(f\"Agent stopped: {agent_id}\")\n            except Exception as e:\n                logger.error(f\"Error stopping agent {agent_id}: {e}\")\n\n        self.agents.clear()\n        logger.info(\"All agents stopped\")\n\n    def list_loaded_agents(self) -> list[str]:\n        \"\"\"List currently loaded agent IDs.\n\n        Returns:\n            list[str]: List of loaded agent IDs\n        \"\"\"\n        return list(self.agents.keys())\n\n    def is_agent_loaded(self, agent_id: str) -> bool:\n        \"\"\"Check if agent is currently loaded.\n\n        Args:\n            agent_id: Agent ID to check\n\n        Returns:\n            bool: True if agent is loaded and running\n        \"\"\"\n        return agent_id in self.agents\n\n    async def preload_agent(self, agent_id: str) -> bool:\n        \"\"\"Preload an agent instance during startup.\n\n        Args:\n            agent_id: Agent ID to preload\n\n        Returns:\n            bool: True if successfully preloaded, False if failed\n        \"\"\"\n        try:\n            await self.get_agent(agent_id)\n            logger.info(f\"Successfully preloaded agent: {agent_id}\")\n            return True\n        except Exception as e:\n            logger.error(f\"Failed to preload agent {agent_id}: {e}\")\n            return False\n\n    async def start_all_configured_agents(self) -> dict[str, bool]:\n        \"\"\"Start all agents defined in configuration concurrently.\n\n        This method loads the current configuration and starts all\n        configured agents in parallel for optimal performance.\n\n        Returns:\n            dict[str, bool]: Mapping of agent_id to success status\n        \"\"\"\n        config = load_config()\n        agent_ids = list(config.agents.profiles.keys())\n\n        if not agent_ids:\n            logger.warning(\"No agents configured in config\")\n            return {}\n\n        logger.info(f\"Starting {len(agent_ids)} configured agent(s)\")\n\n        async def start_single_agent(agent_id: str) -> tuple[str, bool]:\n            \"\"\"Start a single agent with error handling.\"\"\"\n            try:\n                logger.info(f\"Starting agent: {agent_id}\")\n                await self.preload_agent(agent_id)\n                logger.info(f\"Agent started successfully: {agent_id}\")\n                return (agent_id, True)\n            except Exception as e:\n                logger.error(\n                    f\"Failed to start agent {agent_id}: {e}. \"\n                    f\"Continuing with other agents...\",\n                )\n                return (agent_id, False)\n\n        # Start all agents concurrently\n        results = await asyncio.gather(\n            *[start_single_agent(agent_id) for agent_id in agent_ids],\n            return_exceptions=False,\n        )\n\n        # Build result mapping\n        result_map = dict(results)\n        success_count = sum(1 for success in result_map.values() if success)\n        logger.info(\n            f\"Agent startup complete: {success_count}/{len(agent_ids)} \"\n            f\"agents started successfully\",\n        )\n\n        return result_map\n\n    def __repr__(self) -> str:\n        \"\"\"String representation of manager.\"\"\"\n        loaded = list(self.agents.keys())\n        return f\"MultiAgentManager(loaded_agents={loaded})\"\n"
  },
  {
    "path": "src/copaw/app/routers/__init__.py",
    "content": "# -*- coding: utf-8 -*-\n\"\"\"API routers.\"\"\"\nfrom fastapi import APIRouter\n\nfrom .agent import router as agent_router\nfrom .agents import router as agents_router\nfrom .config import router as config_router\nfrom .local_models import router as local_models_router\nfrom .providers import router as providers_router\nfrom .skills import router as skills_router\nfrom .skills_stream import router as skills_stream_router\nfrom .workspace import router as workspace_router\nfrom .envs import router as envs_router\nfrom .ollama_models import router as ollama_models_router\nfrom .mcp import router as mcp_router\nfrom .tools import router as tools_router\nfrom ..crons.api import router as cron_router\nfrom ..runner.api import router as runner_router\nfrom .console import router as console_router\nfrom .token_usage import router as token_usage_router\nfrom .auth import router as auth_router\n\nrouter = APIRouter()\n\nrouter.include_router(agents_router)\nrouter.include_router(agent_router)\nrouter.include_router(config_router)\nrouter.include_router(console_router)\nrouter.include_router(cron_router)\nrouter.include_router(local_models_router)\nrouter.include_router(mcp_router)\nrouter.include_router(ollama_models_router)\nrouter.include_router(providers_router)\nrouter.include_router(runner_router)\nrouter.include_router(skills_router)\nrouter.include_router(skills_stream_router)\nrouter.include_router(tools_router)\nrouter.include_router(workspace_router)\nrouter.include_router(envs_router)\nrouter.include_router(token_usage_router)\nrouter.include_router(auth_router)\n\n\ndef create_agent_scoped_router() -> APIRouter:\n    \"\"\"Create agent-scoped router that wraps existing routers.\n\n    Returns:\n        APIRouter with all routers mounted under /agents/{agentId}/\n    \"\"\"\n    from .agent_scoped import create_agent_scoped_router as _create\n\n    return _create()\n\n\n__all__ = [\"router\", \"create_agent_scoped_router\"]\n"
  },
  {
    "path": "src/copaw/app/routers/agent.py",
    "content": "# -*- coding: utf-8 -*-\n\"\"\"Agent file management API.\"\"\"\n\nimport asyncio\nimport logging\n\nfrom fastapi import APIRouter, Body, HTTPException, Request\nfrom pydantic import BaseModel, Field\n\nfrom ...config import (\n    load_config,\n    save_config,\n    AgentsRunningConfig,\n)\nfrom ...config.config import load_agent_config, save_agent_config\nfrom ...agents.memory.agent_md_manager import AgentMdManager\nfrom ...agents.utils import copy_md_files\nfrom ..agent_context import get_agent_for_request\n\nrouter = APIRouter(prefix=\"/agent\", tags=[\"agent\"])\n\n\nclass MdFileInfo(BaseModel):\n    \"\"\"Markdown file metadata.\"\"\"\n\n    filename: str = Field(..., description=\"File name\")\n    path: str = Field(..., description=\"File path\")\n    size: int = Field(..., description=\"Size in bytes\")\n    created_time: str = Field(..., description=\"Created time\")\n    modified_time: str = Field(..., description=\"Modified time\")\n\n\nclass MdFileContent(BaseModel):\n    \"\"\"Markdown file content.\"\"\"\n\n    content: str = Field(..., description=\"File content\")\n\n\n@router.get(\n    \"/files\",\n    response_model=list[MdFileInfo],\n    summary=\"List working files\",\n    description=\"List all working files (uses active agent)\",\n)\nasync def list_working_files(\n    request: Request,\n) -> list[MdFileInfo]:\n    \"\"\"List working directory markdown files.\"\"\"\n    try:\n        workspace = await get_agent_for_request(request)\n        workspace_manager = AgentMdManager(\n            str(workspace.workspace_dir),\n        )\n        files = [\n            MdFileInfo.model_validate(file)\n            for file in workspace_manager.list_working_mds()\n        ]\n        return files\n    except Exception as exc:\n        raise HTTPException(status_code=500, detail=str(exc)) from exc\n\n\n@router.get(\n    \"/files/{md_name}\",\n    response_model=MdFileContent,\n    summary=\"Read a working file\",\n    description=\"Read a working markdown file (uses active agent)\",\n)\nasync def read_working_file(\n    md_name: str,\n    request: Request,\n) -> MdFileContent:\n    \"\"\"Read a working directory markdown file.\"\"\"\n    try:\n        workspace = await get_agent_for_request(request)\n        workspace_manager = AgentMdManager(\n            str(workspace.workspace_dir),\n        )\n        content = workspace_manager.read_working_md(md_name)\n        return MdFileContent(content=content)\n    except FileNotFoundError as exc:\n        raise HTTPException(status_code=404, detail=str(exc)) from exc\n    except Exception as exc:\n        raise HTTPException(status_code=500, detail=str(exc)) from exc\n\n\n@router.put(\n    \"/files/{md_name}\",\n    response_model=dict,\n    summary=\"Write a working file\",\n    description=\"Create or update a working file (uses active agent)\",\n)\nasync def write_working_file(\n    md_name: str,\n    body: MdFileContent,\n    request: Request,\n) -> dict:\n    \"\"\"Write a working directory markdown file.\"\"\"\n    try:\n        workspace = await get_agent_for_request(request)\n        workspace_manager = AgentMdManager(\n            str(workspace.workspace_dir),\n        )\n        workspace_manager.write_working_md(md_name, body.content)\n        return {\"written\": True}\n    except Exception as exc:\n        raise HTTPException(status_code=500, detail=str(exc)) from exc\n\n\n@router.get(\n    \"/memory\",\n    response_model=list[MdFileInfo],\n    summary=\"List memory files\",\n    description=\"List all memory files (uses active agent)\",\n)\nasync def list_memory_files(\n    request: Request,\n) -> list[MdFileInfo]:\n    \"\"\"List memory directory markdown files.\"\"\"\n    try:\n        workspace = await get_agent_for_request(request)\n        workspace_manager = AgentMdManager(\n            str(workspace.workspace_dir),\n        )\n        files = [\n            MdFileInfo.model_validate(file)\n            for file in workspace_manager.list_memory_mds()\n        ]\n        return files\n    except Exception as exc:\n        raise HTTPException(status_code=500, detail=str(exc)) from exc\n\n\n@router.get(\n    \"/memory/{md_name}\",\n    response_model=MdFileContent,\n    summary=\"Read a memory file\",\n    description=\"Read a memory markdown file (uses active agent)\",\n)\nasync def read_memory_file(\n    md_name: str,\n    request: Request,\n) -> MdFileContent:\n    \"\"\"Read a memory directory markdown file.\"\"\"\n    try:\n        workspace = await get_agent_for_request(request)\n        workspace_manager = AgentMdManager(\n            str(workspace.workspace_dir),\n        )\n        content = workspace_manager.read_memory_md(md_name)\n        return MdFileContent(content=content)\n    except FileNotFoundError as exc:\n        raise HTTPException(status_code=404, detail=str(exc)) from exc\n    except Exception as exc:\n        raise HTTPException(status_code=500, detail=str(exc)) from exc\n\n\n@router.put(\n    \"/memory/{md_name}\",\n    response_model=dict,\n    summary=\"Write a memory file\",\n    description=\"Create or update a memory file (uses active agent)\",\n)\nasync def write_memory_file(\n    md_name: str,\n    body: MdFileContent,\n    request: Request,\n) -> dict:\n    \"\"\"Write a memory directory markdown file.\"\"\"\n    try:\n        workspace = await get_agent_for_request(request)\n        workspace_manager = AgentMdManager(\n            str(workspace.workspace_dir),\n        )\n        workspace_manager.write_memory_md(md_name, body.content)\n        return {\"written\": True}\n    except Exception as exc:\n        raise HTTPException(status_code=500, detail=str(exc)) from exc\n\n\n@router.get(\n    \"/language\",\n    summary=\"Get agent language\",\n    description=\"Get the language setting for agent MD files (en/zh/ru)\",\n)\nasync def get_agent_language(request: Request) -> dict:\n    \"\"\"Get agent language setting for current agent.\"\"\"\n    workspace = await get_agent_for_request(request)\n    agent_config = load_agent_config(workspace.agent_id)\n    return {\n        \"language\": agent_config.language,\n        \"agent_id\": workspace.agent_id,\n    }\n\n\n@router.put(\n    \"/language\",\n    summary=\"Update agent language\",\n    description=(\n        \"Update the language for agent MD files (en/zh/ru). \"\n        \"Optionally copies MD files for the new language to agent workspace.\"\n    ),\n)\nasync def put_agent_language(\n    request: Request,\n    body: dict = Body(\n        ...,\n        description='Language setting, e.g. {\"language\": \"zh\"}',\n    ),\n) -> dict:\n    \"\"\"\n    Update agent language and optionally re-copy MD files to agent workspace.\n    \"\"\"\n    language = (body.get(\"language\") or \"\").strip().lower()\n    valid = {\"zh\", \"en\", \"ru\"}\n    if language not in valid:\n        raise HTTPException(\n            status_code=400,\n            detail=(\n                f\"Invalid language '{language}'. \"\n                f\"Must be one of: {', '.join(sorted(valid))}\"\n            ),\n        )\n\n    # Get current agent's workspace\n    workspace = await get_agent_for_request(request)\n    agent_id = workspace.agent_id\n\n    # Load agent config\n    agent_config = load_agent_config(agent_id)\n    old_language = agent_config.language\n\n    # Update agent's language\n    agent_config.language = language\n    save_agent_config(agent_id, agent_config)\n\n    copied_files: list[str] = []\n    if old_language != language:\n        # Copy MD files to agent's workspace directory\n        copied_files = (\n            copy_md_files(\n                language,\n                workspace_dir=workspace.workspace_dir,\n            )\n            or []\n        )\n\n    return {\n        \"language\": language,\n        \"copied_files\": copied_files,\n        \"agent_id\": agent_id,\n    }\n\n\n@router.get(\n    \"/audio-mode\",\n    summary=\"Get audio mode\",\n    description=(\n        \"Get the audio handling mode for incoming voice messages. \"\n        'Values: \"auto\", \"native\".'\n    ),\n)\nasync def get_audio_mode() -> dict:\n    \"\"\"Get audio mode setting.\"\"\"\n    config = load_config()\n    return {\"audio_mode\": config.agents.audio_mode}\n\n\n@router.put(\n    \"/audio-mode\",\n    summary=\"Update audio mode\",\n    description=(\n        \"Update how incoming audio/voice messages are handled. \"\n        '\"auto\": transcribe if provider available, else file placeholder; '\n        '\"native\": send audio directly to model (may need ffmpeg).'\n    ),\n)\nasync def put_audio_mode(\n    body: dict = Body(\n        ...,\n        description='Audio mode, e.g. {\"audio_mode\": \"auto\"}',\n    ),\n) -> dict:\n    \"\"\"Update audio mode setting.\"\"\"\n    raw = body.get(\"audio_mode\")\n    audio_mode = (str(raw) if raw is not None else \"\").strip().lower()\n    valid = {\"auto\", \"native\"}\n    if audio_mode not in valid:\n        raise HTTPException(\n            status_code=400,\n            detail=(\n                f\"Invalid audio_mode '{audio_mode}'. \"\n                f\"Must be one of: {', '.join(sorted(valid))}\"\n            ),\n        )\n    config = load_config()\n    config.agents.audio_mode = audio_mode\n    save_config(config)\n    return {\"audio_mode\": audio_mode}\n\n\n@router.get(\n    \"/transcription-provider-type\",\n    summary=\"Get transcription provider type\",\n    description=(\n        \"Get the transcription provider type. \"\n        'Values: \"disabled\", \"whisper_api\", \"local_whisper\".'\n    ),\n)\nasync def get_transcription_provider_type() -> dict:\n    \"\"\"Get transcription provider type setting.\"\"\"\n    config = load_config()\n    return {\n        \"transcription_provider_type\": (\n            config.agents.transcription_provider_type\n        ),\n    }\n\n\n@router.put(\n    \"/transcription-provider-type\",\n    summary=\"Set transcription provider type\",\n    description=(\n        \"Set the transcription provider type. \"\n        '\"disabled\": no transcription; '\n        '\"whisper_api\": remote Whisper endpoint; '\n        '\"local_whisper\": locally installed openai-whisper.'\n    ),\n)\nasync def put_transcription_provider_type(\n    body: dict = Body(\n        ...,\n        description=(\n            \"Provider type, e.g. \"\n            '{\"transcription_provider_type\": \"whisper_api\"}'\n        ),\n    ),\n) -> dict:\n    \"\"\"Set the transcription provider type.\"\"\"\n    raw = body.get(\"transcription_provider_type\")\n    provider_type = (str(raw) if raw is not None else \"\").strip().lower()\n    valid = {\"disabled\", \"whisper_api\", \"local_whisper\"}\n    if provider_type not in valid:\n        raise HTTPException(\n            status_code=400,\n            detail=(\n                f\"Invalid transcription_provider_type '{provider_type}'. \"\n                f\"Must be one of: {', '.join(sorted(valid))}\"\n            ),\n        )\n    config = load_config()\n    config.agents.transcription_provider_type = provider_type\n    save_config(config)\n    return {\"transcription_provider_type\": provider_type}\n\n\n@router.get(\n    \"/local-whisper-status\",\n    summary=\"Check local whisper availability\",\n    description=(\n        \"Check whether the local whisper provider can be used. \"\n        \"Returns availability of ffmpeg and openai-whisper.\"\n    ),\n)\nasync def get_local_whisper_status() -> dict:\n    \"\"\"Check local whisper dependencies.\"\"\"\n    from ...agents.utils.audio_transcription import (\n        check_local_whisper_available,\n    )\n\n    return check_local_whisper_available()\n\n\n@router.get(\n    \"/transcription-providers\",\n    summary=\"List transcription providers\",\n    description=(\n        \"List providers capable of audio transcription (Whisper API). \"\n        \"Returns available providers and the configured selection.\"\n    ),\n)\nasync def get_transcription_providers() -> dict:\n    \"\"\"List transcription-capable providers and configured selection.\"\"\"\n    from ...agents.utils.audio_transcription import (\n        get_configured_transcription_provider_id,\n        list_transcription_providers,\n    )\n\n    return {\n        \"providers\": list_transcription_providers(),\n        \"configured_provider_id\": (get_configured_transcription_provider_id()),\n    }\n\n\n@router.put(\n    \"/transcription-provider\",\n    summary=\"Set transcription provider\",\n    description=(\n        \"Set the provider to use for audio transcription. \"\n        'Use empty string \"\" to unset.'\n    ),\n)\nasync def put_transcription_provider(\n    body: dict = Body(\n        ...,\n        description=(\n            'Provider ID, e.g. {\"provider_id\": \"openai\"} '\n            'or {\"provider_id\": \"\"} to unset'\n        ),\n    ),\n) -> dict:\n    \"\"\"Set the transcription provider.\"\"\"\n    provider_id = (body.get(\"provider_id\") or \"\").strip()\n    config = load_config()\n    config.agents.transcription_provider_id = provider_id\n    save_config(config)\n    return {\"provider_id\": provider_id}\n\n\n@router.get(\n    \"/running-config\",\n    response_model=AgentsRunningConfig,\n    summary=\"Get agent running config\",\n    description=\"Get running configuration for active agent\",\n)\nasync def get_agents_running_config(\n    request: Request,\n) -> AgentsRunningConfig:\n    \"\"\"Get agent running configuration.\"\"\"\n    workspace = await get_agent_for_request(request)\n    agent_config = load_agent_config(workspace.agent_id)\n    return agent_config.running or AgentsRunningConfig()\n\n\n@router.put(\n    \"/running-config\",\n    response_model=AgentsRunningConfig,\n    summary=\"Update agent running config\",\n    description=\"Update running configuration for active agent\",\n)\nasync def put_agents_running_config(\n    running_config: AgentsRunningConfig = Body(\n        ...,\n        description=\"Updated agent running configuration\",\n    ),\n    request: Request = None,\n) -> AgentsRunningConfig:\n    \"\"\"Update agent running configuration.\"\"\"\n    workspace = await get_agent_for_request(request)\n    agent_config = load_agent_config(workspace.agent_id)\n    agent_config.running = running_config\n    save_agent_config(workspace.agent_id, agent_config)\n\n    # Hot reload config (async, non-blocking)\n    # IMPORTANT: Get manager and agent_id before creating background task\n    # to avoid accessing request/workspace after their lifecycle ends\n    manager = request.app.state.multi_agent_manager\n    agent_id = workspace.agent_id\n\n    async def reload_in_background():\n        try:\n            await manager.reload_agent(agent_id)\n        except Exception as e:\n            logging.getLogger(__name__).warning(\n                f\"Background reload failed: {e}\",\n            )\n\n    asyncio.create_task(reload_in_background())\n\n    return running_config\n\n\n@router.get(\n    \"/system-prompt-files\",\n    response_model=list[str],\n    summary=\"Get system prompt files\",\n    description=\"Get system prompt files for active agent\",\n)\nasync def get_system_prompt_files(\n    request: Request,\n) -> list[str]:\n    \"\"\"Get list of enabled system prompt files.\"\"\"\n    workspace = await get_agent_for_request(request)\n    agent_config = load_agent_config(workspace.agent_id)\n    return agent_config.system_prompt_files or []\n\n\n@router.put(\n    \"/system-prompt-files\",\n    response_model=list[str],\n    summary=\"Update system prompt files\",\n    description=\"Update system prompt files for active agent\",\n)\nasync def put_system_prompt_files(\n    files: list[str] = Body(\n        ...,\n        description=\"Markdown filenames to load into system prompt\",\n    ),\n    request: Request = None,\n) -> list[str]:\n    \"\"\"Update list of enabled system prompt files.\"\"\"\n    workspace = await get_agent_for_request(request)\n    agent_config = load_agent_config(workspace.agent_id)\n    agent_config.system_prompt_files = files\n    save_agent_config(workspace.agent_id, agent_config)\n\n    # Hot reload config (async, non-blocking)\n    # IMPORTANT: Get manager before creating background task to avoid\n    # accessing request object after its lifecycle ends\n    manager = request.app.state.multi_agent_manager\n    agent_id = workspace.agent_id\n\n    async def reload_in_background():\n        try:\n            await manager.reload_agent(agent_id)\n        except Exception as e:\n            logging.getLogger(__name__).warning(\n                f\"Background reload failed: {e}\",\n            )\n\n    asyncio.create_task(reload_in_background())\n\n    return files\n"
  },
  {
    "path": "src/copaw/app/routers/agent_scoped.py",
    "content": "# -*- coding: utf-8 -*-\n\"\"\"Agent-scoped router that wraps existing routers under /agents/{agentId}/\n\nThis provides agent isolation by injecting agentId into request.state,\nallowing downstream APIs to access the correct agent context.\n\"\"\"\nfrom fastapi import APIRouter, Request\nfrom starlette.middleware.base import (\n    BaseHTTPMiddleware,\n    RequestResponseEndpoint,\n)\nfrom starlette.responses import Response\n\n\nclass AgentContextMiddleware(BaseHTTPMiddleware):\n    \"\"\"Middleware to inject agentId into request.state.\"\"\"\n\n    async def dispatch(\n        self,\n        request: Request,\n        call_next: RequestResponseEndpoint,\n    ) -> Response:\n        \"\"\"Extract agentId from path/header and inject into context.\"\"\"\n        import logging\n        from ..agent_context import set_current_agent_id\n\n        logger = logging.getLogger(__name__)\n        agent_id = None\n\n        # Priority 1: Extract agentId from path: /api/agents/{agentId}/...\n        path_parts = request.url.path.split(\"/\")\n        if len(path_parts) >= 4 and path_parts[1] == \"api\":\n            if path_parts[2] == \"agents\":\n                agent_id = path_parts[3]\n                request.state.agent_id = agent_id\n                logger.debug(\n                    f\"AgentContextMiddleware: agent_id={agent_id} \"\n                    f\"from path={request.url.path}\",\n                )\n\n        # Priority 2: Check X-Agent-Id header\n        if not agent_id:\n            agent_id = request.headers.get(\"X-Agent-Id\")\n\n        # Set agent_id in context variable for use by runners\n        if agent_id:\n            set_current_agent_id(agent_id)\n\n        response = await call_next(request)\n        return response\n\n\ndef create_agent_scoped_router() -> APIRouter:\n    \"\"\"Create router that wraps all existing routers under /{agentId}/\n\n    Returns:\n        APIRouter with all sub-routers mounted under /{agentId}/\n    \"\"\"\n    from .agent import router as agent_router\n    from .skills import router as skills_router\n    from .tools import router as tools_router\n    from .config import router as config_router\n    from .mcp import router as mcp_router\n    from .workspace import router as workspace_router\n    from ..crons.api import router as cron_router\n    from ..runner.api import router as chats_router\n    from .console import router as console_router\n\n    # Create parent router with agentId parameter\n    router = APIRouter(prefix=\"/agents/{agentId}\", tags=[\"agent-scoped\"])\n\n    # Include all agent-specific sub-routers (they keep their own prefixes)\n    # /agents/{agentId}/agent/* -> agent_router\n    # /agents/{agentId}/chats/* -> chats_router\n    # /agents/{agentId}/config/* -> config_router (channels, heartbeat)\n    # /agents/{agentId}/cron/* -> cron_router\n    # /agents/{agentId}/mcp/* -> mcp_router\n    # /agents/{agentId}/skills/* -> skills_router\n    # /agents/{agentId}/tools/* -> tools_router\n    # /agents/{agentId}/workspace/* -> workspace_router\n    router.include_router(agent_router)\n    router.include_router(chats_router)\n    router.include_router(config_router)\n    router.include_router(cron_router)\n    router.include_router(mcp_router)\n    router.include_router(skills_router)\n    router.include_router(tools_router)\n    router.include_router(workspace_router)\n    router.include_router(console_router)\n\n    return router\n"
  },
  {
    "path": "src/copaw/app/routers/agents.py",
    "content": "# -*- coding: utf-8 -*-\n\"\"\"Multi-agent management API.\n\nProvides RESTful API for managing multiple agent instances.\n\"\"\"\nimport asyncio\nimport json\nimport logging\nfrom pathlib import Path\nfrom fastapi import APIRouter, Body, HTTPException, Request\nfrom fastapi import Path as PathParam\nfrom pydantic import BaseModel\n\nfrom ...config.config import (\n    AgentProfileConfig,\n    AgentProfileRef,\n    load_agent_config,\n    save_agent_config,\n    generate_short_agent_id,\n)\nfrom ...config.utils import load_config, save_config\nfrom ...agents.memory.agent_md_manager import AgentMdManager\nfrom ..multi_agent_manager import MultiAgentManager\nfrom ...constant import WORKING_DIR\n\nlogger = logging.getLogger(__name__)\n\nrouter = APIRouter(prefix=\"/agents\", tags=[\"agents\"])\n\n\nclass AgentSummary(BaseModel):\n    \"\"\"Agent summary information.\"\"\"\n\n    id: str\n    name: str\n    description: str\n    workspace_dir: str\n\n\nclass AgentListResponse(BaseModel):\n    \"\"\"Response for listing agents.\"\"\"\n\n    agents: list[AgentSummary]\n\n\nclass CreateAgentRequest(BaseModel):\n    \"\"\"Request model for creating a new agent (id is auto-generated).\"\"\"\n\n    name: str\n    description: str = \"\"\n    workspace_dir: str | None = None\n    language: str = \"en\"\n\n\nclass MdFileInfo(BaseModel):\n    \"\"\"Markdown file metadata.\"\"\"\n\n    filename: str\n    path: str\n    size: int\n    created_time: str\n    modified_time: str\n\n\nclass MdFileContent(BaseModel):\n    \"\"\"Markdown file content.\"\"\"\n\n    content: str\n\n\ndef _get_multi_agent_manager(request: Request) -> MultiAgentManager:\n    \"\"\"Get MultiAgentManager from app state.\"\"\"\n    if not hasattr(request.app.state, \"multi_agent_manager\"):\n        raise HTTPException(\n            status_code=500,\n            detail=\"MultiAgentManager not initialized\",\n        )\n    return request.app.state.multi_agent_manager\n\n\n@router.get(\n    \"\",\n    response_model=AgentListResponse,\n    summary=\"List all agents\",\n    description=\"Get list of all configured agents\",\n)\nasync def list_agents() -> AgentListResponse:\n    \"\"\"List all configured agents.\"\"\"\n    config = load_config()\n\n    agents = []\n    for agent_id, agent_ref in config.agents.profiles.items():\n        # Load agent config to get name and description\n        try:\n            agent_config = load_agent_config(agent_id)\n            agents.append(\n                AgentSummary(\n                    id=agent_id,\n                    name=agent_config.name,\n                    description=agent_config.description,\n                    workspace_dir=agent_ref.workspace_dir,\n                ),\n            )\n        except Exception:  # noqa: E722\n            # If agent config load fails, use basic info\n            agents.append(\n                AgentSummary(\n                    id=agent_id,\n                    name=agent_id.title(),\n                    description=\"\",\n                    workspace_dir=agent_ref.workspace_dir,\n                ),\n            )\n\n    return AgentListResponse(\n        agents=agents,\n    )\n\n\n@router.get(\n    \"/{agentId}\",\n    response_model=AgentProfileConfig,\n    summary=\"Get agent details\",\n    description=\"Get complete configuration for a specific agent\",\n)\nasync def get_agent(agentId: str = PathParam(...)) -> AgentProfileConfig:\n    \"\"\"Get agent configuration.\"\"\"\n    try:\n        agent_config = load_agent_config(agentId)\n        return agent_config\n    except ValueError as e:\n        raise HTTPException(status_code=404, detail=str(e)) from e\n    except Exception as e:\n        raise HTTPException(status_code=500, detail=str(e)) from e\n\n\n@router.post(\n    \"\",\n    response_model=AgentProfileRef,\n    status_code=201,\n    summary=\"Create new agent\",\n    description=\"Create a new agent (ID is auto-generated by server)\",\n)\nasync def create_agent(\n    request: CreateAgentRequest = Body(...),\n) -> AgentProfileRef:\n    \"\"\"Create a new agent with auto-generated ID.\"\"\"\n    config = load_config()\n\n    # Always generate a unique short UUID (6 characters)\n    max_attempts = 10\n    new_id = None\n    for _ in range(max_attempts):\n        candidate_id = generate_short_agent_id()\n        if candidate_id not in config.agents.profiles:\n            new_id = candidate_id\n            break\n\n    if new_id is None:\n        raise HTTPException(\n            status_code=500,\n            detail=\"Failed to generate unique agent ID after 10 attempts\",\n        )\n\n    # Create workspace directory\n    workspace_dir = Path(\n        request.workspace_dir or f\"{WORKING_DIR}/workspaces/{new_id}\",\n    ).expanduser()\n    workspace_dir.mkdir(parents=True, exist_ok=True)\n\n    # Build complete agent config with generated ID\n    from ...config.config import (\n        ChannelConfig,\n        MCPConfig,\n        HeartbeatConfig,\n        ToolsConfig,\n    )\n\n    agent_config = AgentProfileConfig(\n        id=new_id,\n        name=request.name,\n        description=request.description,\n        workspace_dir=str(workspace_dir),\n        language=request.language,\n        channels=ChannelConfig(),\n        mcp=MCPConfig(),\n        heartbeat=HeartbeatConfig(),\n        tools=ToolsConfig(),\n    )\n\n    # Initialize workspace with default files\n    _initialize_agent_workspace(workspace_dir, agent_config)\n\n    # Save agent configuration to workspace/agent.json\n    agent_ref = AgentProfileRef(\n        id=new_id,\n        workspace_dir=str(workspace_dir),\n    )\n\n    # Add to root config\n    config.agents.profiles[new_id] = agent_ref\n    save_config(config)\n\n    # Save agent config to workspace\n    save_agent_config(new_id, agent_config)\n\n    logger.info(f\"Created new agent: {new_id} (name={request.name})\")\n\n    return agent_ref\n\n\n@router.put(\n    \"/{agentId}\",\n    response_model=AgentProfileConfig,\n    summary=\"Update agent\",\n    description=\"Update agent configuration and trigger reload\",\n)\nasync def update_agent(\n    agentId: str = PathParam(...),\n    agent_config: AgentProfileConfig = Body(...),\n    request: Request = None,\n) -> AgentProfileConfig:\n    \"\"\"Update agent configuration.\"\"\"\n    config = load_config()\n\n    if agentId not in config.agents.profiles:\n        raise HTTPException(\n            status_code=404,\n            detail=f\"Agent '{agentId}' not found\",\n        )\n\n    # Load existing complete configuration\n    existing_config = load_agent_config(agentId)\n\n    # Merge updates: only update fields that are explicitly set\n    update_data = agent_config.model_dump(exclude_unset=True)\n    for key, value in update_data.items():\n        if key != \"id\":\n            setattr(existing_config, key, value)\n\n    # Ensure ID doesn't change\n    existing_config.id = agentId\n\n    # Save merged configuration\n    save_agent_config(agentId, existing_config)\n\n    # Trigger hot reload if agent is running (async, non-blocking)\n    # IMPORTANT: Get manager before creating background task to avoid\n    # accessing request object after its lifecycle ends\n    manager = _get_multi_agent_manager(request)\n\n    async def reload_in_background():\n        try:\n            await manager.reload_agent(agentId)\n        except Exception as e:\n            logger.warning(f\"Background reload failed for {agentId}: {e}\")\n\n    asyncio.create_task(reload_in_background())\n\n    return agent_config\n\n\n@router.delete(\n    \"/{agentId}\",\n    summary=\"Delete agent\",\n    description=\"Delete agent and workspace (cannot delete default agent)\",\n)\nasync def delete_agent(\n    agentId: str = PathParam(...),\n    request: Request = None,\n) -> dict:\n    \"\"\"Delete an agent.\"\"\"\n    config = load_config()\n\n    if agentId not in config.agents.profiles:\n        raise HTTPException(\n            status_code=404,\n            detail=f\"Agent '{agentId}' not found\",\n        )\n\n    if agentId == \"default\":\n        raise HTTPException(\n            status_code=400,\n            detail=\"Cannot delete the default agent\",\n        )\n\n    # Stop agent instance if running\n    manager = _get_multi_agent_manager(request)\n    await manager.stop_agent(agentId)\n\n    # Remove from config\n    del config.agents.profiles[agentId]\n    save_config(config)\n\n    # Note: We don't delete the workspace directory for safety\n    # Users can manually delete it if needed\n\n    return {\"success\": True, \"agent_id\": agentId}\n\n\n@router.get(\n    \"/{agentId}/files\",\n    response_model=list[MdFileInfo],\n    summary=\"List agent workspace files\",\n    description=\"List all markdown files in agent's workspace\",\n)\nasync def list_agent_files(\n    agentId: str = PathParam(...),\n    request: Request = None,\n) -> list[MdFileInfo]:\n    \"\"\"List agent workspace files.\"\"\"\n    manager = _get_multi_agent_manager(request)\n\n    try:\n        workspace = await manager.get_agent(agentId)\n    except ValueError as e:\n        raise HTTPException(status_code=404, detail=str(e)) from e\n\n    workspace_manager = AgentMdManager(str(workspace.workspace_dir))\n\n    try:\n        files = [\n            MdFileInfo.model_validate(file)\n            for file in workspace_manager.list_working_mds()\n        ]\n        return files\n    except Exception as e:\n        raise HTTPException(status_code=500, detail=str(e)) from e\n\n\n@router.get(\n    \"/{agentId}/files/{filename}\",\n    response_model=MdFileContent,\n    summary=\"Read agent workspace file\",\n    description=\"Read a markdown file from agent's workspace\",\n)\nasync def read_agent_file(\n    agentId: str = PathParam(...),\n    filename: str = PathParam(...),\n    request: Request = None,\n) -> MdFileContent:\n    \"\"\"Read agent workspace file.\"\"\"\n    manager = _get_multi_agent_manager(request)\n\n    try:\n        workspace = await manager.get_agent(agentId)\n    except ValueError as e:\n        raise HTTPException(status_code=404, detail=str(e)) from e\n\n    workspace_manager = AgentMdManager(str(workspace.workspace_dir))\n\n    try:\n        content = workspace_manager.read_working_md(filename)\n        return MdFileContent(content=content)\n    except FileNotFoundError as exc:\n        raise HTTPException(\n            status_code=404,\n            detail=f\"File '{filename}' not found\",\n        ) from exc\n    except Exception as e:\n        raise HTTPException(status_code=500, detail=str(e)) from e\n\n\n@router.put(\n    \"/{agentId}/files/{filename}\",\n    response_model=dict,\n    summary=\"Write agent workspace file\",\n    description=\"Create or update a markdown file in agent's workspace\",\n)\nasync def write_agent_file(\n    agentId: str = PathParam(...),\n    filename: str = PathParam(...),\n    file_content: MdFileContent = Body(...),\n    request: Request = None,\n) -> dict:\n    \"\"\"Write agent workspace file.\"\"\"\n    manager = _get_multi_agent_manager(request)\n\n    try:\n        workspace = await manager.get_agent(agentId)\n    except ValueError as e:\n        raise HTTPException(status_code=404, detail=str(e)) from e\n\n    workspace_manager = AgentMdManager(str(workspace.workspace_dir))\n\n    try:\n        workspace_manager.write_working_md(filename, file_content.content)\n        return {\"written\": True, \"filename\": filename}\n    except Exception as e:\n        raise HTTPException(status_code=500, detail=str(e)) from e\n\n\n@router.get(\n    \"/{agentId}/memory\",\n    response_model=list[MdFileInfo],\n    summary=\"List agent memory files\",\n    description=\"List all memory files for an agent\",\n)\nasync def list_agent_memory(\n    agentId: str = PathParam(...),\n    request: Request = None,\n) -> list[MdFileInfo]:\n    \"\"\"List agent memory files.\"\"\"\n    manager = _get_multi_agent_manager(request)\n\n    try:\n        workspace = await manager.get_agent(agentId)\n    except ValueError as e:\n        raise HTTPException(status_code=404, detail=str(e)) from e\n\n    workspace_manager = AgentMdManager(str(workspace.workspace_dir))\n\n    try:\n        files = [\n            MdFileInfo.model_validate(file)\n            for file in workspace_manager.list_memory_mds()\n        ]\n        return files\n    except Exception as e:\n        raise HTTPException(status_code=500, detail=str(e)) from e\n\n\ndef _initialize_agent_workspace(  # pylint: disable=too-many-branches\n    workspace_dir: Path,\n    agent_config: AgentProfileConfig,  # pylint: disable=unused-argument\n) -> None:\n    \"\"\"Initialize agent workspace (similar to copaw init --defaults).\n\n    Args:\n        workspace_dir: Path to agent workspace\n        agent_config: Agent configuration (reserved for future use)\n    \"\"\"\n    import shutil\n    from ...config import load_config as load_global_config\n\n    # Create essential subdirectories\n    (workspace_dir / \"sessions\").mkdir(exist_ok=True)\n    (workspace_dir / \"memory\").mkdir(exist_ok=True)\n    (workspace_dir / \"active_skills\").mkdir(exist_ok=True)\n    (workspace_dir / \"customized_skills\").mkdir(exist_ok=True)\n\n    # Get language from global config\n    config = load_global_config()\n    language = config.agents.language or \"zh\"\n\n    # Copy MD files from agents/md_files/{language}/ to workspace\n    md_files_dir = (\n        Path(__file__).parent.parent.parent / \"agents\" / \"md_files\" / language\n    )\n    if md_files_dir.exists():\n        for md_file in md_files_dir.glob(\"*.md\"):\n            target_file = workspace_dir / md_file.name\n            if not target_file.exists():\n                try:\n                    shutil.copy2(md_file, target_file)\n                except Exception as e:\n                    logger.warning(\n                        f\"Failed to copy {md_file.name}: {e}\",\n                    )\n\n    # Create HEARTBEAT.md if not exists\n    heartbeat_file = workspace_dir / \"HEARTBEAT.md\"\n    if not heartbeat_file.exists():\n        DEFAULT_HEARTBEAT_MDS = {\n            \"zh\": \"\"\"# Heartbeat checklist\n- 扫描收件箱紧急邮件\n- 查看未来 2h 的日历\n- 检查待办是否卡住\n- 若安静超过 8h，轻量 check-in\n\"\"\",\n            \"en\": \"\"\"# Heartbeat checklist\n- Scan inbox for urgent email\n- Check calendar for next 2h\n- Check tasks for blockers\n- Light check-in if quiet for 8h\n\"\"\",\n            \"ru\": \"\"\"# Heartbeat checklist\n- Проверить входящие на срочные письма\n- Просмотреть календарь на ближайшие 2 часа\n- Проверить задачи на наличие блокировок\n- Лёгкая проверка при отсутствии активности более 8 часов\n\"\"\",\n        }\n        heartbeat_content = DEFAULT_HEARTBEAT_MDS.get(\n            language,\n            DEFAULT_HEARTBEAT_MDS[\"en\"],\n        )\n        with open(heartbeat_file, \"w\", encoding=\"utf-8\") as f:\n            f.write(heartbeat_content.strip())\n\n    # Copy builtin skills to agent's active_skills directory\n    builtin_skills_dir = (\n        Path(__file__).parent.parent.parent / \"agents\" / \"skills\"\n    )\n    if builtin_skills_dir.exists():\n        for skill_dir in builtin_skills_dir.iterdir():\n            if skill_dir.is_dir() and (skill_dir / \"SKILL.md\").exists():\n                target_skill_dir = (\n                    workspace_dir / \"active_skills\" / skill_dir.name\n                )\n                if not target_skill_dir.exists():\n                    try:\n                        shutil.copytree(skill_dir, target_skill_dir)\n                    except Exception as e:\n                        logger.warning(\n                            f\"Failed to copy skill {skill_dir.name}: {e}\",\n                        )\n\n    # Create empty jobs.json for cron jobs\n    jobs_file = workspace_dir / \"jobs.json\"\n    if not jobs_file.exists():\n        with open(jobs_file, \"w\", encoding=\"utf-8\") as f:\n            json.dump(\n                {\"version\": 1, \"jobs\": []},\n                f,\n                ensure_ascii=False,\n                indent=2,\n            )\n\n    # Create empty chats.json for chat history\n    chats_file = workspace_dir / \"chats.json\"\n    if not chats_file.exists():\n        with open(chats_file, \"w\", encoding=\"utf-8\") as f:\n            json.dump(\n                {\"version\": 1, \"chats\": []},\n                f,\n                ensure_ascii=False,\n                indent=2,\n            )\n\n    # Create empty token_usage.json\n    token_usage_file = workspace_dir / \"token_usage.json\"\n    if not token_usage_file.exists():\n        with open(token_usage_file, \"w\", encoding=\"utf-8\") as f:\n            f.write(\"[]\")\n"
  },
  {
    "path": "src/copaw/app/routers/auth.py",
    "content": "# -*- coding: utf-8 -*-\n\"\"\"Authentication API endpoints.\"\"\"\nfrom __future__ import annotations\n\nimport os\n\nfrom fastapi import APIRouter, HTTPException, Request\nfrom pydantic import BaseModel\n\nfrom ..auth import (\n    authenticate,\n    has_registered_users,\n    is_auth_enabled,\n    register_user,\n    verify_token,\n)\n\nrouter = APIRouter(prefix=\"/auth\", tags=[\"auth\"])\n\n\nclass LoginRequest(BaseModel):\n    username: str\n    password: str\n\n\nclass LoginResponse(BaseModel):\n    token: str\n    username: str\n\n\nclass RegisterRequest(BaseModel):\n    username: str\n    password: str\n\n\nclass AuthStatusResponse(BaseModel):\n    enabled: bool\n    has_users: bool\n\n\n@router.post(\"/login\")\nasync def login(req: LoginRequest):\n    \"\"\"Authenticate with username and password.\"\"\"\n    if not is_auth_enabled():\n        return LoginResponse(token=\"\", username=\"\")\n\n    token = authenticate(req.username, req.password)\n    if token is None:\n        raise HTTPException(status_code=401, detail=\"Invalid credentials\")\n\n    return LoginResponse(token=token, username=req.username)\n\n\n@router.post(\"/register\")\nasync def register(req: RegisterRequest):\n    \"\"\"Register the single user account (only allowed once).\"\"\"\n    env_flag = os.environ.get(\"COPAW_AUTH_ENABLED\", \"\").strip().lower()\n    if env_flag not in (\"true\", \"1\", \"yes\"):\n        raise HTTPException(\n            status_code=403,\n            detail=\"Authentication is not enabled\",\n        )\n\n    if has_registered_users():\n        raise HTTPException(\n            status_code=403,\n            detail=\"User already registered\",\n        )\n\n    if not req.username.strip() or not req.password.strip():\n        raise HTTPException(\n            status_code=400,\n            detail=\"Username and password are required\",\n        )\n\n    token = register_user(req.username.strip(), req.password)\n    if token is None:\n        raise HTTPException(\n            status_code=409,\n            detail=\"Registration failed\",\n        )\n\n    return LoginResponse(token=token, username=req.username.strip())\n\n\n@router.get(\"/status\")\nasync def auth_status():\n    \"\"\"Check if authentication is enabled and whether a user exists.\"\"\"\n    return AuthStatusResponse(\n        enabled=is_auth_enabled(),\n        has_users=has_registered_users(),\n    )\n\n\n@router.get(\"/verify\")\nasync def verify(request: Request):\n    \"\"\"Verify that the caller's Bearer token is still valid.\"\"\"\n    if not is_auth_enabled():\n        return {\"valid\": True, \"username\": \"\"}\n\n    auth_header = request.headers.get(\"Authorization\", \"\")\n    token = auth_header[7:] if auth_header.startswith(\"Bearer \") else \"\"\n    if not token:\n        raise HTTPException(status_code=401, detail=\"No token provided\")\n\n    username = verify_token(token)\n    if username is None:\n        raise HTTPException(\n            status_code=401,\n            detail=\"Invalid or expired token\",\n        )\n\n    return {\"valid\": True, \"username\": username}\n"
  },
  {
    "path": "src/copaw/app/routers/config.py",
    "content": "# -*- coding: utf-8 -*-\n\nfrom datetime import datetime, timezone\nfrom typing import Any, List\n\nfrom fastapi import APIRouter, Body, HTTPException, Path, Request\nfrom pydantic import BaseModel\n\nfrom ...config import (\n    load_config,\n    save_config,\n    ChannelConfig,\n    ChannelConfigUnion,\n    get_available_channels,\n    ToolGuardConfig,\n    ToolGuardRuleConfig,\n)\nfrom ..channels.registry import BUILTIN_CHANNEL_KEYS\nfrom ...config.config import (\n    AgentsLLMRoutingConfig,\n    ConsoleConfig,\n    DingTalkConfig,\n    DiscordConfig,\n    FeishuConfig,\n    HeartbeatConfig,\n    IMessageChannelConfig,\n    MatrixConfig,\n    MattermostConfig,\n    MQTTConfig,\n    QQConfig,\n    SkillScannerConfig,\n    SkillScannerWhitelistEntry,\n    TelegramConfig,\n    VoiceChannelConfig,\n    WecomConfig,\n)\n\nfrom .schemas_config import HeartbeatBody\n\nrouter = APIRouter(prefix=\"/config\", tags=[\"config\"])\n\n\n_CHANNEL_CONFIG_CLASS_MAP = {\n    \"telegram\": TelegramConfig,\n    \"dingtalk\": DingTalkConfig,\n    \"discord\": DiscordConfig,\n    \"feishu\": FeishuConfig,\n    \"qq\": QQConfig,\n    \"imessage\": IMessageChannelConfig,\n    \"console\": ConsoleConfig,\n    \"voice\": VoiceChannelConfig,\n    \"mattermost\": MattermostConfig,\n    \"mqtt\": MQTTConfig,\n    \"matrix\": MatrixConfig,\n    \"wecom\": WecomConfig,\n}\n\n\n@router.get(\n    \"/channels\",\n    summary=\"List all channels\",\n    description=\"Retrieve configuration for all available channels\",\n)\nasync def list_channels(request: Request) -> dict:\n    \"\"\"List all channel configs (filtered by available channels).\"\"\"\n    from ..agent_context import get_agent_for_request\n\n    agent = await get_agent_for_request(request)\n    agent_config = agent.config\n    available = get_available_channels()\n\n    # Get channel configs from agent's config (with fallback to empty)\n    channels_config = agent_config.channels\n    if channels_config is None:\n        # No channels config yet, use empty defaults\n        all_configs = {}\n    else:\n        all_configs = channels_config.model_dump()\n        extra = getattr(channels_config, \"__pydantic_extra__\", None) or {}\n        all_configs.update(extra)\n\n    # Return all available channels (use default config if not saved)\n    result = {}\n    for key in available:\n        if key in all_configs:\n            channel_data = (\n                dict(all_configs[key])\n                if isinstance(all_configs[key], dict)\n                else all_configs[key]\n            )\n        else:\n            # Channel registered but no config saved yet, use empty default\n            channel_data = {\"enabled\": False, \"bot_prefix\": \"\"}\n        if isinstance(channel_data, dict):\n            channel_data[\"isBuiltin\"] = key in BUILTIN_CHANNEL_KEYS\n        result[key] = channel_data\n\n    return result\n\n\n@router.get(\n    \"/channels/types\",\n    summary=\"List channel types\",\n    description=\"Return all available channel type identifiers\",\n)\nasync def list_channel_types() -> List[str]:\n    \"\"\"Return available channel type identifiers (env-filtered).\"\"\"\n    return list(get_available_channels())\n\n\n@router.put(\n    \"/channels\",\n    response_model=ChannelConfig,\n    summary=\"Update all channels\",\n    description=\"Update configuration for all channels at once\",\n)\nasync def put_channels(\n    request: Request,\n    channels_config: ChannelConfig = Body(\n        ...,\n        description=\"Complete channel configuration\",\n    ),\n) -> ChannelConfig:\n    \"\"\"Update all channel configs.\"\"\"\n    from ..agent_context import get_agent_for_request\n    from ...config.config import save_agent_config\n\n    agent = await get_agent_for_request(request)\n    agent.config.channels = channels_config\n    save_agent_config(agent.agent_id, agent.config)\n\n    # Hot reload config (async, non-blocking)\n    # IMPORTANT: Get manager and agent_id before creating background task\n    # to avoid accessing request/workspace after their lifecycle ends\n    import asyncio\n\n    manager = request.app.state.multi_agent_manager\n    agent_id = agent.agent_id\n\n    async def reload_in_background():\n        try:\n            await manager.reload_agent(agent_id)\n        except Exception as e:\n            import logging\n\n            logging.getLogger(__name__).warning(\n                f\"Background reload failed: {e}\",\n            )\n\n    asyncio.create_task(reload_in_background())\n\n    return channels_config\n\n\n@router.get(\n    \"/channels/{channel_name}\",\n    response_model=ChannelConfigUnion,\n    summary=\"Get channel config\",\n    description=\"Retrieve configuration for a specific channel by name\",\n)\nasync def get_channel(\n    request: Request,\n    channel_name: str = Path(\n        ...,\n        description=\"Name of the channel to retrieve\",\n        min_length=1,\n    ),\n) -> ChannelConfigUnion:\n    \"\"\"Get a specific channel config by name.\"\"\"\n    from ..agent_context import get_agent_for_request\n\n    available = get_available_channels()\n    if channel_name not in available:\n        raise HTTPException(\n            status_code=404,\n            detail=f\"Channel '{channel_name}' not found\",\n        )\n\n    agent = await get_agent_for_request(request)\n    channels = agent.config.channels\n    if channels is None:\n        raise HTTPException(\n            status_code=404,\n            detail=f\"Channel '{channel_name}' not configured\",\n        )\n\n    single_channel_config = getattr(channels, channel_name, None)\n    if single_channel_config is None:\n        extra = getattr(channels, \"__pydantic_extra__\", None) or {}\n        single_channel_config = extra.get(channel_name)\n    if single_channel_config is None:\n        raise HTTPException(\n            status_code=404,\n            detail=f\"Channel '{channel_name}' not found\",\n        )\n    return single_channel_config\n\n\n@router.put(\n    \"/channels/{channel_name}\",\n    response_model=ChannelConfigUnion,\n    summary=\"Update channel config\",\n    description=\"Update configuration for a specific channel by name\",\n)\nasync def put_channel(\n    request: Request,\n    channel_name: str = Path(\n        ...,\n        description=\"Name of the channel to update\",\n        min_length=1,\n    ),\n    single_channel_config: dict = Body(\n        ...,\n        description=\"Updated channel configuration\",\n    ),\n) -> ChannelConfigUnion:\n    \"\"\"Update a specific channel config by name.\"\"\"\n    from ..agent_context import get_agent_for_request\n    from ...config.config import save_agent_config\n\n    available = get_available_channels()\n    if channel_name not in available:\n        raise HTTPException(\n            status_code=404,\n            detail=f\"Channel '{channel_name}' not found\",\n        )\n\n    agent = await get_agent_for_request(request)\n\n    # Initialize channels if not exists\n    if agent.config.channels is None:\n        agent.config.channels = ChannelConfig()\n\n    config_class = _CHANNEL_CONFIG_CLASS_MAP.get(channel_name)\n    if config_class is not None:\n        channel_config = config_class(**single_channel_config)\n    else:\n        # For custom channels, just use the dict\n        channel_config = single_channel_config\n\n    # Set channel config in agent's config\n    setattr(agent.config.channels, channel_name, channel_config)\n    save_agent_config(agent.agent_id, agent.config)\n\n    # Hot reload config (async, non-blocking)\n    # IMPORTANT: Get manager and agent_id before creating background task\n    # to avoid accessing request/workspace after their lifecycle ends\n    import asyncio\n\n    manager = request.app.state.multi_agent_manager\n    agent_id = agent.agent_id\n\n    async def reload_in_background():\n        try:\n            await manager.reload_agent(agent_id)\n        except Exception as e:\n            import logging\n\n            logging.getLogger(__name__).warning(\n                f\"Background reload failed: {e}\",\n            )\n\n    asyncio.create_task(reload_in_background())\n\n    return channel_config\n\n\n@router.get(\n    \"/heartbeat\",\n    summary=\"Get heartbeat config\",\n    description=\"Return current heartbeat config (interval, target, etc.)\",\n)\nasync def get_heartbeat(request: Request) -> Any:\n    \"\"\"Return effective heartbeat config (from file or default).\"\"\"\n    from ..agent_context import get_agent_for_request\n    from ...config.config import HeartbeatConfig as HeartbeatConfigModel\n\n    agent = await get_agent_for_request(request)\n    hb = agent.config.heartbeat\n    if hb is None:\n        # Use default if not configured\n        hb = HeartbeatConfigModel()\n    return hb.model_dump(mode=\"json\", by_alias=True)\n\n\n@router.put(\n    \"/heartbeat\",\n    summary=\"Update heartbeat config\",\n    description=\"Update heartbeat and hot-reload the scheduler\",\n)\nasync def put_heartbeat(\n    request: Request,\n    body: HeartbeatBody = Body(..., description=\"Heartbeat configuration\"),\n) -> Any:\n    \"\"\"Update heartbeat config and reschedule the heartbeat job.\"\"\"\n    from ..agent_context import get_agent_for_request\n    from ...config.config import save_agent_config\n\n    agent = await get_agent_for_request(request)\n    hb = HeartbeatConfig(\n        enabled=body.enabled,\n        every=body.every,\n        target=body.target,\n        active_hours=body.active_hours,\n    )\n    agent.config.heartbeat = hb\n    save_agent_config(agent.agent_id, agent.config)\n\n    # Reschedule heartbeat (async, non-blocking)\n    import asyncio\n\n    async def reschedule_in_background():\n        try:\n            if agent.cron_manager is not None:\n                await agent.cron_manager.reschedule_heartbeat()\n        except Exception as e:\n            import logging\n\n            logging.getLogger(__name__).warning(\n                f\"Background reschedule failed: {e}\",\n            )\n\n    asyncio.create_task(reschedule_in_background())\n\n    return hb.model_dump(mode=\"json\", by_alias=True)\n\n\n@router.get(\n    \"/agents/llm-routing\",\n    response_model=AgentsLLMRoutingConfig,\n    summary=\"Get agent LLM routing settings\",\n)\nasync def get_agents_llm_routing() -> AgentsLLMRoutingConfig:\n    config = load_config()\n    return config.agents.llm_routing\n\n\n@router.put(\n    \"/agents/llm-routing\",\n    response_model=AgentsLLMRoutingConfig,\n    summary=\"Update agent LLM routing settings\",\n)\nasync def put_agents_llm_routing(\n    body: AgentsLLMRoutingConfig = Body(...),\n) -> AgentsLLMRoutingConfig:\n    config = load_config()\n    config.agents.llm_routing = body\n    save_config(config)\n    return body\n\n\n# ── User Timezone ────────────────────────────────────────────────────\n\n\n@router.get(\n    \"/user-timezone\",\n    summary=\"Get user timezone\",\n    description=\"Return the configured user IANA timezone\",\n)\nasync def get_user_timezone() -> dict:\n    config = load_config()\n    return {\"timezone\": config.user_timezone}\n\n\n@router.put(\n    \"/user-timezone\",\n    summary=\"Update user timezone\",\n    description=\"Set the user IANA timezone\",\n)\nasync def put_user_timezone(\n    body: dict = Body(..., description=\"Body with 'timezone' key\"),\n) -> dict:\n    tz = body.get(\"timezone\", \"\").strip()\n    if not tz:\n        raise HTTPException(status_code=400, detail=\"timezone is required\")\n    config = load_config()\n    config.user_timezone = tz\n    save_config(config)\n    return {\"timezone\": tz}\n\n\n# ── Security / Tool Guard ────────────────────────────────────────────\n\n\n@router.get(\n    \"/security/tool-guard\",\n    response_model=ToolGuardConfig,\n    summary=\"Get tool guard settings\",\n)\nasync def get_tool_guard() -> ToolGuardConfig:\n    config = load_config()\n    return config.security.tool_guard\n\n\n@router.put(\n    \"/security/tool-guard\",\n    response_model=ToolGuardConfig,\n    summary=\"Update tool guard settings\",\n)\nasync def put_tool_guard(\n    body: ToolGuardConfig = Body(...),\n) -> ToolGuardConfig:\n    config = load_config()\n    config.security.tool_guard = body\n    save_config(config)\n\n    from ...security.tool_guard.engine import get_guard_engine\n\n    engine = get_guard_engine()\n    engine.enabled = body.enabled\n    engine.reload_rules()\n\n    return body\n\n\n@router.get(\n    \"/security/tool-guard/builtin-rules\",\n    response_model=List[ToolGuardRuleConfig],\n    summary=\"List built-in guard rules from YAML files\",\n)\nasync def get_builtin_rules() -> List[ToolGuardRuleConfig]:\n    from ...security.tool_guard.guardians.rule_guardian import (\n        load_rules_from_directory,\n    )\n\n    rules = load_rules_from_directory()\n    return [\n        ToolGuardRuleConfig(\n            id=r.id,\n            tools=r.tools,\n            params=r.params,\n            category=r.category.value,\n            severity=r.severity.value,\n            patterns=r.patterns,\n            exclude_patterns=r.exclude_patterns,\n            description=r.description,\n            remediation=r.remediation,\n        )\n        for r in rules\n    ]\n\n\n# ── Security / Skill Scanner ────────────────────────────────────────\n\n\n@router.get(\n    \"/security/skill-scanner\",\n    response_model=SkillScannerConfig,\n    summary=\"Get skill scanner settings\",\n)\nasync def get_skill_scanner() -> SkillScannerConfig:\n    config = load_config()\n    return config.security.skill_scanner\n\n\n@router.put(\n    \"/security/skill-scanner\",\n    response_model=SkillScannerConfig,\n    summary=\"Update skill scanner settings\",\n)\nasync def put_skill_scanner(\n    body: SkillScannerConfig = Body(...),\n) -> SkillScannerConfig:\n    config = load_config()\n    config.security.skill_scanner = body\n    save_config(config)\n    return body\n\n\n@router.get(\n    \"/security/skill-scanner/blocked-history\",\n    summary=\"Get blocked skills history\",\n)\nasync def get_blocked_history() -> list:\n    from ...security.skill_scanner import get_blocked_history as _get_history\n\n    records = _get_history()\n    return [r.to_dict() for r in records]\n\n\n@router.delete(\n    \"/security/skill-scanner/blocked-history\",\n    summary=\"Clear all blocked skills history\",\n)\nasync def delete_blocked_history() -> dict:\n    from ...security.skill_scanner import clear_blocked_history\n\n    clear_blocked_history()\n    return {\"cleared\": True}\n\n\n@router.delete(\n    \"/security/skill-scanner/blocked-history/{index}\",\n    summary=\"Remove a single blocked history entry\",\n)\nasync def delete_blocked_entry(\n    index: int = Path(..., ge=0),\n) -> dict:\n    from ...security.skill_scanner import remove_blocked_entry\n\n    ok = remove_blocked_entry(index)\n    if not ok:\n        raise HTTPException(status_code=404, detail=\"Entry not found\")\n    return {\"removed\": True}\n\n\nclass WhitelistAddRequest(BaseModel):\n    skill_name: str\n    content_hash: str = \"\"\n\n\n@router.post(\n    \"/security/skill-scanner/whitelist\",\n    summary=\"Add a skill to the whitelist\",\n)\nasync def add_to_whitelist(\n    body: WhitelistAddRequest = Body(...),\n) -> dict:\n    skill_name = body.skill_name.strip()\n    content_hash = body.content_hash\n    if not skill_name:\n        raise HTTPException(status_code=400, detail=\"skill_name is required\")\n\n    config = load_config()\n    scanner_cfg = config.security.skill_scanner\n\n    for entry in scanner_cfg.whitelist:\n        if entry.skill_name == skill_name:\n            raise HTTPException(\n                status_code=409,\n                detail=f\"Skill '{skill_name}' is already whitelisted\",\n            )\n\n    scanner_cfg.whitelist.append(\n        SkillScannerWhitelistEntry(\n            skill_name=skill_name,\n            content_hash=content_hash,\n            added_at=datetime.now(timezone.utc).isoformat(),\n        ),\n    )\n    save_config(config)\n    return {\"whitelisted\": True, \"skill_name\": skill_name}\n\n\n@router.delete(\n    \"/security/skill-scanner/whitelist/{skill_name}\",\n    summary=\"Remove a skill from the whitelist\",\n)\nasync def remove_from_whitelist(\n    skill_name: str = Path(..., min_length=1),\n) -> dict:\n    config = load_config()\n    scanner_cfg = config.security.skill_scanner\n    original_len = len(scanner_cfg.whitelist)\n    scanner_cfg.whitelist = [\n        e for e in scanner_cfg.whitelist if e.skill_name != skill_name\n    ]\n    if len(scanner_cfg.whitelist) == original_len:\n        raise HTTPException(\n            status_code=404,\n            detail=f\"Skill '{skill_name}' not found in whitelist\",\n        )\n    save_config(config)\n    return {\"removed\": True, \"skill_name\": skill_name}\n"
  },
  {
    "path": "src/copaw/app/routers/console.py",
    "content": "# -*- coding: utf-8 -*-\n\"\"\"Console APIs: push messages, chat, and file upload for chat.\"\"\"\nfrom __future__ import annotations\n\nimport json\nimport logging\nimport re\nimport uuid\nfrom pathlib import Path\nfrom typing import AsyncGenerator, Union\n\nfrom fastapi import APIRouter, File, HTTPException, Query, Request, UploadFile\nfrom starlette.responses import FileResponse, StreamingResponse\n\nfrom agentscope_runtime.engine.schemas.agent_schemas import AgentRequest\nfrom ..agent_context import get_agent_for_request\n\n\nlogger = logging.getLogger(__name__)\n\nrouter = APIRouter(prefix=\"/console\", tags=[\"console\"])\n\nMAX_UPLOAD_BYTES = 10 * 1024 * 1024\n\n\ndef _safe_filename(name: str) -> str:\n    \"\"\"Safe basename, alphanumeric/./-/_, max 200 chars.\"\"\"\n    base = Path(name).name if name else \"file\"\n    return re.sub(r\"[^\\w.\\-]\", \"_\", base)[:200] or \"file\"\n\n\ndef _extract_session_and_payload(request_data: Union[AgentRequest, dict]):\n    \"\"\"Extract run_key (ChatSpec.id), session_id, and native payload.\n\n    run_key must be ChatSpec.id (chat_id) so it matches list_chats/get_chat.\n    \"\"\"\n    if isinstance(request_data, AgentRequest):\n        channel_id = request_data.channel or \"console\"\n        sender_id = request_data.user_id or \"default\"\n        session_id = request_data.session_id or \"default\"\n        content_parts = (\n            list(request_data.input[0].content) if request_data.input else []\n        )\n    else:\n        channel_id = request_data.get(\"channel\", \"console\")\n        sender_id = request_data.get(\"user_id\", \"default\")\n        session_id = request_data.get(\"session_id\", \"default\")\n        input_data = request_data.get(\"input\", [])\n        content_parts = []\n        for content_part in input_data:\n            if hasattr(content_part, \"content\"):\n                content_parts.extend(list(content_part.content or []))\n            elif isinstance(content_part, dict) and \"content\" in content_part:\n                content_parts.extend(content_part[\"content\"] or [])\n\n    native_payload = {\n        \"channel_id\": channel_id,\n        \"sender_id\": sender_id,\n        \"content_parts\": content_parts,\n        \"meta\": {\n            \"session_id\": session_id,\n            \"user_id\": sender_id,\n        },\n    }\n    return native_payload\n\n\n@router.post(\n    \"/chat\",\n    status_code=200,\n    summary=\"Chat with console (streaming response)\",\n    description=\"Agent API Request Format. See runtime.agentscope.io. \"\n    \"Use body.reconnect=true to attach to a running stream.\",\n)\nasync def post_console_chat(\n    request_data: Union[AgentRequest, dict],\n    request: Request,\n) -> StreamingResponse:\n    \"\"\"Stream agent response. Run continues in background after disconnect.\n    Stop via POST /console/chat/stop. Reconnect with body.reconnect=true.\n    \"\"\"\n    workspace = await get_agent_for_request(request)\n    console_channel = await workspace.channel_manager.get_channel(\"console\")\n    if console_channel is None:\n        raise HTTPException(\n            status_code=503,\n            detail=\"Channel Console not found\",\n        )\n    try:\n        native_payload = _extract_session_and_payload(request_data)\n    except ValueError as e:\n        raise HTTPException(status_code=400, detail=str(e)) from e\n    session_id = console_channel.resolve_session_id(\n        sender_id=native_payload[\"sender_id\"],\n        channel_meta=native_payload[\"meta\"],\n    )\n    name = \"New Chat\"\n    if len(native_payload[\"content_parts\"]) > 0:\n        content = native_payload[\"content_parts\"][0]\n        if content:\n            name = content.text[:10]\n        else:\n            name = \"Media Message\"\n    chat = await workspace.chat_manager.get_or_create_chat(\n        session_id,\n        native_payload[\"sender_id\"],\n        native_payload[\"channel_id\"],\n        name=name,\n    )\n    tracker = workspace.task_tracker\n\n    is_reconnect = False\n    if isinstance(request_data, dict):\n        is_reconnect = request_data.get(\"reconnect\") is True\n\n    if is_reconnect:\n        queue = await tracker.attach(chat.id)\n        if queue is None:\n            raise HTTPException(\n                status_code=404,\n                detail=\"No running chat for this session\",\n            )\n    else:\n        queue, _ = await tracker.attach_or_start(\n            chat.id,\n            native_payload,\n            console_channel.stream_one,\n        )\n\n    async def event_generator() -> AsyncGenerator[str, None]:\n        try:\n            async for event_data in tracker.stream_from_queue(queue):\n                yield event_data\n        except Exception as e:\n            logger.exception(\"Console chat stream error\")\n            yield f\"data: {json.dumps({'error': str(e)})}\\n\\n\"\n\n    return StreamingResponse(\n        event_generator(),\n        media_type=\"text/event-stream\",\n        headers={\n            \"Cache-Control\": \"no-cache\",\n            \"Connection\": \"keep-alive\",\n        },\n    )\n\n\n@router.post(\n    \"/chat/stop\",\n    status_code=200,\n    summary=\"Stop running console chat\",\n)\nasync def post_console_chat_stop(\n    request: Request,\n    chat_id: str = Query(..., description=\"Chat id (ChatSpec.id) to stop\"),\n) -> dict:\n    \"\"\"Stop the running chat. Only stops when called.\"\"\"\n    workspace = await get_agent_for_request(request)\n    stopped = await workspace.task_tracker.request_stop(chat_id)\n    return {\"stopped\": stopped}\n\n\n@router.post(\"/upload\", response_model=dict, summary=\"Upload file for chat\")\nasync def post_console_upload(\n    request: Request,\n    file: UploadFile = File(..., description=\"File to attach\"),\n) -> dict:\n    \"\"\"Save to console channel media_dir.\"\"\"\n\n    workspace = await get_agent_for_request(request)\n    console_channel = await workspace.channel_manager.get_channel(\"console\")\n    if console_channel is None:\n        raise HTTPException(\n            status_code=503,\n            detail=\"Channel Console not found\",\n        )\n    media_dir = console_channel.media_dir\n    media_dir.mkdir(parents=True, exist_ok=True)\n    data = await file.read()\n    if len(data) > MAX_UPLOAD_BYTES:\n        raise HTTPException(\n            status_code=400,\n            detail=\"File too large (max \"\n            f\"{MAX_UPLOAD_BYTES // (1024 * 1024)} MB)\",\n        )\n    safe_name = _safe_filename(file.filename or \"file\")\n    stored_name = f\"{uuid.uuid4().hex}_{safe_name}\"\n    (media_dir / stored_name).write_bytes(data)\n    return {\n        \"url\": stored_name,\n        \"file_name\": safe_name,\n        \"size\": len(data),\n    }\n\n\n@router.get(\"/files/{agent_id}/{filename}\", summary=\"Serve uploaded chat file\")\nasync def get_console_file(\n    request: Request,\n    agent_id: str,\n    filename: str,\n):\n    \"\"\"Serve file from console channel media_dir.\"\"\"\n\n    if \"/\" in filename or \"..\" in filename:\n        raise HTTPException(status_code=400, detail=\"Invalid filename\")\n    workspace = await get_agent_for_request(request)\n    if workspace.agent_id != agent_id:\n        raise HTTPException(status_code=404, detail=\"Not found\")\n    console_channel = await workspace.channel_manager.get_channel(\"console\")\n    if console_channel is None:\n        raise HTTPException(\n            status_code=503,\n            detail=\"Channel Console not found\",\n        )\n    media_dir = console_channel.media_dir\n    path = (media_dir / filename).resolve()\n    try:\n        path.relative_to(media_dir)\n    except ValueError:\n        raise HTTPException(status_code=404, detail=\"Not found\") from None\n    if not path.is_file():\n        raise HTTPException(status_code=404, detail=\"Not found\")\n    return FileResponse(path, filename=filename)\n\n\n@router.get(\"/push-messages\")\nasync def get_push_messages(\n    session_id: str | None = Query(None, description=\"Optional session id\"),\n):\n    \"\"\"\n    Return pending push messages. Without session_id: recent messages\n    (all sessions, last 60s), not consumed so every tab sees them.\n    \"\"\"\n    from ..console_push_store import get_recent, take\n\n    if session_id:\n        messages = await take(session_id)\n    else:\n        messages = await get_recent()\n    return {\"messages\": messages}\n"
  },
  {
    "path": "src/copaw/app/routers/envs.py",
    "content": "# -*- coding: utf-8 -*-\n\"\"\"API endpoints for environment variable management.\"\"\"\nfrom __future__ import annotations\n\nfrom typing import Dict, List\n\nfrom fastapi import APIRouter, HTTPException\nfrom pydantic import BaseModel, Field\n\nfrom ...envs import load_envs, save_envs, delete_env_var\n\nrouter = APIRouter(prefix=\"/envs\", tags=[\"envs\"])\n\n\n# ------------------------------------------------------------------\n# Request / Response models\n# ------------------------------------------------------------------\n\n\nclass EnvVar(BaseModel):\n    \"\"\"Single environment variable.\"\"\"\n\n    key: str = Field(..., description=\"Variable name\")\n    value: str = Field(..., description=\"Variable value\")\n\n\n# ------------------------------------------------------------------\n# Endpoints\n# ------------------------------------------------------------------\n\n\n@router.get(\n    \"\",\n    response_model=List[EnvVar],\n    summary=\"List all environment variables\",\n)\nasync def list_envs() -> List[EnvVar]:\n    \"\"\"Return all configured env vars.\"\"\"\n    envs = load_envs()\n    return [EnvVar(key=k, value=v) for k, v in sorted(envs.items())]\n\n\n@router.put(\n    \"\",\n    response_model=List[EnvVar],\n    summary=\"Batch save environment variables\",\n    description=\"Replace all environment variables with \"\n    \"the provided dict. Keys not present are removed.\",\n)\nasync def batch_save_envs(\n    body: Dict[str, str],\n) -> List[EnvVar]:\n    \"\"\"Batch save – full replacement of all env vars.\"\"\"\n    # Validate keys\n    for key in body:\n        if not key.strip():\n            raise HTTPException(\n                400,\n                detail=\"Key cannot be empty\",\n            )\n    cleaned = {k.strip(): v for k, v in body.items()}\n    save_envs(cleaned)\n    return [EnvVar(key=k, value=v) for k, v in sorted(cleaned.items())]\n\n\n@router.delete(\n    \"/{key}\",\n    response_model=List[EnvVar],\n    summary=\"Delete an environment variable\",\n)\nasync def delete_env(key: str) -> List[EnvVar]:\n    \"\"\"Delete a single env var.\"\"\"\n    envs = load_envs()\n    if key not in envs:\n        raise HTTPException(\n            404,\n            detail=f\"Env var '{key}' not found\",\n        )\n    envs = delete_env_var(key)\n    return [EnvVar(key=k, value=v) for k, v in sorted(envs.items())]\n"
  },
  {
    "path": "src/copaw/app/routers/local_models.py",
    "content": "# -*- coding: utf-8 -*-\n\"\"\"API endpoints for local model management.\"\"\"\n\nfrom __future__ import annotations\n\nimport asyncio\nimport logging\nfrom typing import Dict, List, Optional\n\nfrom fastapi import APIRouter, HTTPException\nfrom pydantic import BaseModel, Field\n\nfrom ..download_task_store import (\n    DownloadTask,\n    DownloadTaskStatus,\n    cancel_task,\n    clear_completed,\n    create_task,\n    get_task,\n    get_tasks,\n    update_status,\n)\nfrom ...providers import ProviderManager\n\nlogger = logging.getLogger(__name__)\n\nrouter = APIRouter(prefix=\"/local-models\", tags=[\"local-models\"])\n\n_background_tasks: Dict[str, asyncio.Task] = {}\n_background_tasks_lock = asyncio.Lock()\n\n\nclass DownloadRequest(BaseModel):\n    repo_id: str = Field(..., description=\"Hugging Face or ModelScope repo ID\")\n    filename: Optional[str] = Field(\n        None,\n        description=\"Specific file to download\",\n    )\n    backend: str = Field(\"llamacpp\", description=\"Backend: llamacpp or mlx\")\n    source: str = Field(\n        \"huggingface\",\n        description=\"Source: huggingface or modelscope\",\n    )\n\n\nclass LocalModelResponse(BaseModel):\n    id: str\n    repo_id: str\n    filename: str\n    backend: str\n    source: str\n    file_size: int\n    local_path: str\n    display_name: str\n\n\nclass DownloadTaskResponse(BaseModel):\n    task_id: str\n    status: str\n    repo_id: str\n    filename: Optional[str] = None\n    backend: str\n    source: str\n    error: Optional[str] = None\n    result: Optional[LocalModelResponse] = None\n\n\ndef _task_to_response(task: DownloadTask) -> DownloadTaskResponse:\n    result = None\n    if task.result:\n        result = LocalModelResponse(**task.result)\n    return DownloadTaskResponse(\n        task_id=task.task_id,\n        status=task.status.value,\n        repo_id=task.repo_id,\n        filename=task.filename,\n        backend=task.backend,\n        source=task.source,\n        error=task.error,\n        result=result,\n    )\n\n\nasync def _register_background_task(task_id: str, task: asyncio.Task) -> None:\n    async with _background_tasks_lock:\n        _background_tasks[task_id] = task\n\n\nasync def _pop_background_task(task_id: str) -> Optional[asyncio.Task]:\n    async with _background_tasks_lock:\n        return _background_tasks.pop(task_id, None)\n\n\n@router.get(\n    \"\",\n    response_model=List[LocalModelResponse],\n    summary=\"List downloaded local models\",\n)\nasync def list_local(\n    backend: Optional[str] = None,\n) -> List[LocalModelResponse]:\n    try:\n        from ...local_models import list_local_models, BackendType\n    except ImportError:\n        return []\n\n    backend_type = BackendType(backend) if backend else None\n    return [\n        LocalModelResponse(\n            id=m.id,\n            repo_id=m.repo_id,\n            filename=m.filename,\n            backend=m.backend.value,\n            source=m.source.value,\n            file_size=m.file_size,\n            local_path=m.local_path,\n            display_name=m.display_name,\n        )\n        for m in list_local_models(backend=backend_type)\n    ]\n\n\n@router.post(\n    \"/download\",\n    response_model=DownloadTaskResponse,\n    summary=\"Start a background model download\",\n)\nasync def download_model(\n    body: DownloadRequest,\n) -> DownloadTaskResponse:\n    \"\"\"Start a background download. Returns a task_id immediately.\"\"\"\n    try:\n        from ...local_models import BackendType, DownloadSource\n    except ImportError as exc:\n        raise HTTPException(\n            status_code=501,\n            detail=(\n                \"Local model dependencies not installed. \"\n                \"Install with: pip install 'copaw[local]'\"\n            ),\n        ) from exc\n\n    # Validate enum values early\n    try:\n        BackendType(body.backend)\n        DownloadSource(body.source)\n    except ValueError as exc:\n        raise HTTPException(status_code=400, detail=str(exc)) from exc\n\n    await clear_completed(backend=body.backend)\n    task = await create_task(\n        repo_id=body.repo_id,\n        filename=body.filename,\n        backend=body.backend,\n        source=body.source,\n    )\n\n    background_task = asyncio.create_task(\n        _run_download_in_background(\n            task_id=task.task_id,\n            body=body,\n        ),\n        name=f\"model-download-{task.task_id}\",\n    )\n    await _register_background_task(task.task_id, background_task)\n\n    return _task_to_response(task)\n\n\nasync def _run_download_in_background(\n    task_id: str,\n    body: DownloadRequest,\n) -> None:\n    \"\"\"Execute the download in a thread and update task status.\"\"\"\n    from ..console_push_store import append as push_store_append\n    from ...local_models import BackendType, DownloadSource, LocalModelManager\n\n    # Check if task was cancelled before starting\n    task = await get_task(task_id)\n    if task and task.status == DownloadTaskStatus.CANCELLED:\n        logger.info(\"Task %s was cancelled before download started\", task_id)\n        await _pop_background_task(task_id)\n        return\n\n    await update_status(task_id, DownloadTaskStatus.DOWNLOADING)\n\n    try:\n        loop = asyncio.get_running_loop()\n        # Periodically check if task was cancelled during download\n        # We run the download in executor, but check cancellation status\n        info = await loop.run_in_executor(\n            None,\n            lambda: LocalModelManager.download_model_sync(\n                repo_id=body.repo_id,\n                filename=body.filename,\n                backend=BackendType(body.backend),\n                source=DownloadSource(body.source),\n            ),\n        )\n\n        # Check if cancelled after download completes but before marking\n        # complete\n        task = await get_task(task_id)\n        if task and task.status == DownloadTaskStatus.CANCELLED:\n            logger.info(\n                \"Task %s was cancelled after download, cleaning up\",\n                task_id,\n            )\n            # Try to delete the downloaded model\n            try:\n                from ...local_models import delete_local_model\n\n                delete_local_model(info.id)\n            except Exception:\n                pass\n            await _pop_background_task(task_id)\n            return\n\n        result_dict = {\n            \"id\": info.id,\n            \"repo_id\": info.repo_id,\n            \"filename\": info.filename,\n            \"backend\": info.backend.value,\n            \"source\": info.source.value,\n            \"file_size\": info.file_size,\n            \"local_path\": info.local_path,\n            \"display_name\": info.display_name,\n        }\n        await update_status(\n            task_id,\n            DownloadTaskStatus.COMPLETED,\n            result=result_dict,\n        )\n        await push_store_append(\n            \"console\",\n            f\"Model downloaded: {info.display_name}\",\n        )\n        ProviderManager.get_instance().update_local_models()\n    except asyncio.CancelledError:\n        await update_status(task_id, DownloadTaskStatus.CANCELLED)\n        logger.info(\"Local model download task %s cancelled\", task_id)\n        raise\n    except Exception as exc:\n        logger.exception(\"Background model download failed: %s\", exc)\n        await update_status(\n            task_id,\n            DownloadTaskStatus.FAILED,\n            error=str(exc),\n        )\n        await push_store_append(\n            \"console\",\n            f\"Model download failed: {body.repo_id} — {exc}\",\n        )\n    finally:\n        await _pop_background_task(task_id)\n\n\n@router.get(\n    \"/download-status\",\n    response_model=List[DownloadTaskResponse],\n    summary=\"Get active download tasks\",\n)\nasync def get_download_status(\n    backend: Optional[str] = None,\n) -> List[DownloadTaskResponse]:\n    tasks = await get_tasks(backend=backend)\n    return [_task_to_response(t) for t in tasks]\n\n\n@router.delete(\n    \"/{model_id:path}\",\n    summary=\"Delete a downloaded local model\",\n)\nasync def delete_local(model_id: str) -> dict:\n    try:\n        from ...local_models import delete_local_model\n    except ImportError as exc:\n        raise HTTPException(\n            status_code=501,\n            detail=\"Local model dependencies not installed.\",\n        ) from exc\n\n    try:\n        delete_local_model(model_id)\n    except ValueError as exc:\n        raise HTTPException(status_code=404, detail=str(exc)) from exc\n\n    ProviderManager.get_instance().update_local_models()\n\n    return {\"status\": \"deleted\", \"model_id\": model_id}\n\n\nasync def _cancel_download_task(task_id: str) -> dict:\n    \"\"\"Cancel a pending or downloading task and stop its\n    background coroutine.\"\"\"\n    success = await cancel_task(task_id)\n    if not success:\n        raise HTTPException(\n            status_code=404,\n            detail=(\n                \"Task not found or not cancellable \"\n                \"(already completed/failed/cancelled)\"\n            ),\n        )\n\n    background_task = await _pop_background_task(task_id)\n    if background_task and not background_task.done():\n        background_task.cancel()\n\n    return {\"status\": \"cancelled\", \"task_id\": task_id}\n\n\n@router.post(\n    \"/cancel-download/{task_id}\",\n    summary=\"Cancel an active download task\",\n)\nasync def cancel_download(task_id: str) -> dict:\n    \"\"\"Cancel a pending or downloading task.\"\"\"\n    return await _cancel_download_task(task_id)\n"
  },
  {
    "path": "src/copaw/app/routers/mcp.py",
    "content": "# -*- coding: utf-8 -*-\n\"\"\"API routes for MCP (Model Context Protocol) clients management.\"\"\"\n\nfrom __future__ import annotations\n\nfrom typing import Dict, List, Optional, Literal\n\nfrom fastapi import APIRouter, Body, HTTPException, Path, Request\nfrom pydantic import BaseModel, Field\n\nfrom ...config.config import MCPClientConfig\n\nrouter = APIRouter(prefix=\"/mcp\", tags=[\"mcp\"])\n\n\nclass MCPClientInfo(BaseModel):\n    \"\"\"MCP client information for API responses.\"\"\"\n\n    key: str = Field(..., description=\"Unique client key identifier\")\n    name: str = Field(..., description=\"Client display name\")\n    description: str = Field(default=\"\", description=\"Client description\")\n    enabled: bool = Field(..., description=\"Whether the client is enabled\")\n    transport: Literal[\"stdio\", \"streamable_http\", \"sse\"] = Field(\n        ...,\n        description=\"MCP transport type\",\n    )\n    url: str = Field(\n        default=\"\",\n        description=\"Remote MCP endpoint URL (for HTTP/SSE transports)\",\n    )\n    headers: Dict[str, str] = Field(\n        default_factory=dict,\n        description=\"HTTP headers for remote transport\",\n    )\n    command: str = Field(\n        default=\"\",\n        description=\"Command to launch the MCP server\",\n    )\n    args: List[str] = Field(\n        default_factory=list,\n        description=\"Command-line arguments\",\n    )\n    env: Dict[str, str] = Field(\n        default_factory=dict,\n        description=\"Environment variables\",\n    )\n    cwd: str = Field(\n        default=\"\",\n        description=\"Working directory for stdio MCP command\",\n    )\n\n\nclass MCPClientCreateRequest(BaseModel):\n    \"\"\"Request body for creating/updating an MCP client.\"\"\"\n\n    name: str = Field(..., description=\"Client display name\")\n    description: str = Field(default=\"\", description=\"Client description\")\n    enabled: bool = Field(\n        default=True,\n        description=\"Whether to enable the client\",\n    )\n    transport: Literal[\"stdio\", \"streamable_http\", \"sse\"] = Field(\n        default=\"stdio\",\n        description=\"MCP transport type\",\n    )\n    url: str = Field(\n        default=\"\",\n        description=\"Remote MCP endpoint URL (for HTTP/SSE transports)\",\n    )\n    headers: Dict[str, str] = Field(\n        default_factory=dict,\n        description=\"HTTP headers for remote transport\",\n    )\n    command: str = Field(\n        default=\"\",\n        description=\"Command to launch the MCP server\",\n    )\n    args: List[str] = Field(\n        default_factory=list,\n        description=\"Command-line arguments\",\n    )\n    env: Dict[str, str] = Field(\n        default_factory=dict,\n        description=\"Environment variables\",\n    )\n    cwd: str = Field(\n        default=\"\",\n        description=\"Working directory for stdio MCP command\",\n    )\n\n\nclass MCPClientUpdateRequest(BaseModel):\n    \"\"\"Request body for updating an MCP client (all fields optional).\"\"\"\n\n    name: Optional[str] = Field(None, description=\"Client display name\")\n    description: Optional[str] = Field(None, description=\"Client description\")\n    enabled: Optional[bool] = Field(\n        None,\n        description=\"Whether to enable the client\",\n    )\n    transport: Optional[Literal[\"stdio\", \"streamable_http\", \"sse\"]] = Field(\n        None,\n        description=\"MCP transport type\",\n    )\n    url: Optional[str] = Field(\n        None,\n        description=\"Remote MCP endpoint URL (for HTTP/SSE transports)\",\n    )\n    headers: Optional[Dict[str, str]] = Field(\n        None,\n        description=\"HTTP headers for remote transport\",\n    )\n    command: Optional[str] = Field(\n        None,\n        description=\"Command to launch the MCP server\",\n    )\n    args: Optional[List[str]] = Field(\n        None,\n        description=\"Command-line arguments\",\n    )\n    env: Optional[Dict[str, str]] = Field(\n        None,\n        description=\"Environment variables\",\n    )\n    cwd: Optional[str] = Field(\n        None,\n        description=\"Working directory for stdio MCP command\",\n    )\n\n\ndef _mask_env_value(value: str) -> str:\n    \"\"\"\n    Mask environment variable value showing first 2-3 chars and last 4 chars.\n\n    Examples:\n        sk-proj-1234567890abcdefghij1234 -> sk-****************************1234\n        abc123456789xyz -> ab***********xyz (if no dash)\n        my-api-key-value -> my-************lue\n        short123 -> ******** (8 chars or less, fully masked)\n    \"\"\"\n    if not value:\n        return value\n\n    length = len(value)\n    if length <= 8:\n        # For short values, just mask everything\n        return \"*\" * length\n\n    # Show first 2-3 characters (3 if there's a dash at position 2)\n    prefix_len = 3 if length > 2 and value[2] == \"-\" else 2\n    prefix = value[:prefix_len]\n\n    # Show last 4 characters\n    suffix = value[-4:]\n\n    # Calculate masked section length (at least 4 asterisks)\n    masked_len = max(length - prefix_len - 4, 4)\n\n    return f\"{prefix}{'*' * masked_len}{suffix}\"\n\n\ndef _build_client_info(key: str, client: MCPClientConfig) -> MCPClientInfo:\n    \"\"\"Build MCPClientInfo from config with masked env values.\"\"\"\n    # Mask environment variable values for security\n    masked_env = (\n        {k: _mask_env_value(v) for k, v in client.env.items()}\n        if client.env\n        else {}\n    )\n    masked_headers = (\n        {k: _mask_env_value(v) for k, v in client.headers.items()}\n        if client.headers\n        else {}\n    )\n\n    return MCPClientInfo(\n        key=key,\n        name=client.name,\n        description=client.description,\n        enabled=client.enabled,\n        transport=client.transport,\n        url=client.url,\n        headers=masked_headers,\n        command=client.command,\n        args=client.args,\n        env=masked_env,\n        cwd=client.cwd,\n    )\n\n\n@router.get(\n    \"\",\n    response_model=List[MCPClientInfo],\n    summary=\"List all MCP clients\",\n)\nasync def list_mcp_clients(request: Request) -> List[MCPClientInfo]:\n    \"\"\"Get list of all configured MCP clients.\"\"\"\n    from ..agent_context import get_agent_for_request\n\n    agent = await get_agent_for_request(request)\n    mcp_config = agent.config.mcp\n    if mcp_config is None or not mcp_config.clients:\n        return []\n\n    return [\n        _build_client_info(key, client)\n        for key, client in mcp_config.clients.items()\n    ]\n\n\n@router.get(\n    \"/{client_key}\",\n    response_model=MCPClientInfo,\n    summary=\"Get MCP client details\",\n)\nasync def get_mcp_client(\n    request: Request,\n    client_key: str = Path(...),\n) -> MCPClientInfo:\n    \"\"\"Get details of a specific MCP client.\"\"\"\n    from ..agent_context import get_agent_for_request\n\n    agent = await get_agent_for_request(request)\n    mcp_config = agent.config.mcp\n    if mcp_config is None:\n        raise HTTPException(404, detail=f\"MCP client '{client_key}' not found\")\n\n    client = mcp_config.clients.get(client_key)\n    if client is None:\n        raise HTTPException(404, detail=f\"MCP client '{client_key}' not found\")\n    return _build_client_info(client_key, client)\n\n\n@router.post(\n    \"\",\n    response_model=MCPClientInfo,\n    summary=\"Create a new MCP client\",\n    status_code=201,\n)\nasync def create_mcp_client(\n    request: Request,\n    client_key: str = Body(..., embed=True),\n    client: MCPClientCreateRequest = Body(..., embed=True),\n) -> MCPClientInfo:\n    \"\"\"Create a new MCP client configuration.\"\"\"\n    from ..agent_context import get_agent_for_request\n    from ...config.config import save_agent_config, MCPConfig\n\n    agent = await get_agent_for_request(request)\n\n    # Initialize mcp config if not exists\n    if agent.config.mcp is None:\n        agent.config.mcp = MCPConfig(clients={})\n\n    # Check if client already exists\n    if client_key in agent.config.mcp.clients:\n        raise HTTPException(\n            400,\n            detail=f\"MCP client '{client_key}' already exists. Use PUT to \"\n            f\"update.\",\n        )\n\n    # Create new client config\n    new_client = MCPClientConfig(\n        name=client.name,\n        description=client.description,\n        enabled=client.enabled,\n        transport=client.transport,\n        url=client.url,\n        headers=client.headers,\n        command=client.command,\n        args=client.args,\n        env=client.env,\n        cwd=client.cwd,\n    )\n\n    # Add to agent's config and save\n    agent.config.mcp.clients[client_key] = new_client\n    save_agent_config(agent.agent_id, agent.config)\n\n    # Hot reload config (async, non-blocking)\n    # IMPORTANT: Get manager and agent_id before creating background task\n    # to avoid accessing request/workspace after their lifecycle ends\n    import asyncio\n\n    manager = request.app.state.multi_agent_manager\n    agent_id = agent.agent_id\n\n    async def reload_in_background():\n        try:\n            await manager.reload_agent(agent_id)\n        except Exception as e:\n            import logging\n\n            logging.getLogger(__name__).warning(\n                f\"Background reload failed: {e}\",\n            )\n\n    asyncio.create_task(reload_in_background())\n\n    return _build_client_info(client_key, new_client)\n\n\n@router.put(\n    \"/{client_key}\",\n    response_model=MCPClientInfo,\n    summary=\"Update an MCP client\",\n)\nasync def update_mcp_client(\n    request: Request,\n    client_key: str = Path(...),\n    updates: MCPClientUpdateRequest = Body(...),\n) -> MCPClientInfo:\n    \"\"\"Update an existing MCP client configuration.\"\"\"\n    from ..agent_context import get_agent_for_request\n    from ...config.config import save_agent_config\n\n    agent = await get_agent_for_request(request)\n\n    if agent.config.mcp is None or client_key not in agent.config.mcp.clients:\n        raise HTTPException(404, detail=f\"MCP client '{client_key}' not found\")\n\n    existing = agent.config.mcp.clients[client_key]\n\n    # Update fields if provided\n    update_data = updates.model_dump(exclude_unset=True)\n\n    # Special handling for env: merge with existing, don't replace\n    if \"env\" in update_data and update_data[\"env\"] is not None:\n        updated_env = existing.env.copy() if existing.env else {}\n        updated_env.update(update_data[\"env\"])\n        update_data[\"env\"] = updated_env\n\n    merged_data = existing.model_dump(mode=\"json\")\n    merged_data.update(update_data)\n    updated_client = MCPClientConfig.model_validate(merged_data)\n    agent.config.mcp.clients[client_key] = updated_client\n\n    # Save updated config\n    save_agent_config(agent.agent_id, agent.config)\n\n    # Hot reload config (async, non-blocking)\n    # IMPORTANT: Get manager and agent_id before creating background task\n    # to avoid accessing request/workspace after their lifecycle ends\n    import asyncio\n\n    manager = request.app.state.multi_agent_manager\n    agent_id = agent.agent_id\n\n    async def reload_in_background():\n        try:\n            await manager.reload_agent(agent_id)\n        except Exception as e:\n            import logging\n\n            logging.getLogger(__name__).warning(\n                f\"Background reload failed: {e}\",\n            )\n\n    asyncio.create_task(reload_in_background())\n\n    return _build_client_info(client_key, updated_client)\n\n\n@router.patch(\n    \"/{client_key}/toggle\",\n    response_model=MCPClientInfo,\n    summary=\"Toggle MCP client enabled status\",\n)\nasync def toggle_mcp_client(\n    request: Request,\n    client_key: str = Path(...),\n) -> MCPClientInfo:\n    \"\"\"Toggle the enabled status of an MCP client.\"\"\"\n    from ..agent_context import get_agent_for_request\n    from ...config.config import save_agent_config\n\n    agent = await get_agent_for_request(request)\n\n    if agent.config.mcp is None or client_key not in agent.config.mcp.clients:\n        raise HTTPException(404, detail=f\"MCP client '{client_key}' not found\")\n\n    client = agent.config.mcp.clients[client_key]\n\n    # Toggle enabled status\n    client.enabled = not client.enabled\n    save_agent_config(agent.agent_id, agent.config)\n\n    # Hot reload config (async, non-blocking)\n    # IMPORTANT: Get manager and agent_id before creating background task\n    # to avoid accessing request/workspace after their lifecycle ends\n    import asyncio\n\n    manager = request.app.state.multi_agent_manager\n    agent_id = agent.agent_id\n\n    async def reload_in_background():\n        try:\n            await manager.reload_agent(agent_id)\n        except Exception as e:\n            import logging\n\n            logging.getLogger(__name__).warning(\n                f\"Background reload failed: {e}\",\n            )\n\n    asyncio.create_task(reload_in_background())\n\n    return _build_client_info(client_key, client)\n\n\n@router.delete(\n    \"/{client_key}\",\n    response_model=Dict[str, str],\n    summary=\"Delete an MCP client\",\n)\nasync def delete_mcp_client(\n    request: Request,\n    client_key: str = Path(...),\n) -> Dict[str, str]:\n    \"\"\"Delete an MCP client configuration.\"\"\"\n    from ..agent_context import get_agent_for_request\n    from ...config.config import save_agent_config\n\n    agent = await get_agent_for_request(request)\n\n    if agent.config.mcp is None or client_key not in agent.config.mcp.clients:\n        raise HTTPException(404, detail=f\"MCP client '{client_key}' not found\")\n\n    # Remove client\n    del agent.config.mcp.clients[client_key]\n    save_agent_config(agent.agent_id, agent.config)\n\n    # Hot reload config (async, non-blocking)\n    # IMPORTANT: Get manager and agent_id before creating background task\n    # to avoid accessing request/workspace after their lifecycle ends\n    import asyncio\n\n    manager = request.app.state.multi_agent_manager\n    agent_id = agent.agent_id\n\n    async def reload_in_background():\n        try:\n            await manager.reload_agent(agent_id)\n        except Exception as e:\n            import logging\n\n            logging.getLogger(__name__).warning(\n                f\"Background reload failed: {e}\",\n            )\n\n    asyncio.create_task(reload_in_background())\n\n    return {\"message\": f\"MCP client '{client_key}' deleted successfully\"}\n"
  },
  {
    "path": "src/copaw/app/routers/ollama_models.py",
    "content": "# -*- coding: utf-8 -*-\n\"\"\"API endpoints for Ollama model management.\n\nThis router mirrors the local_models router but delegates lifecycle operations\n(list / pull / delete) to the Ollama daemon via OllamaModelManager. Downloads\nrun in the background and their status can be polled by the frontend.\n\"\"\"\n\nfrom __future__ import annotations\n\nimport asyncio\nimport logging\nfrom typing import Dict, List, Optional\n\nfrom fastapi import APIRouter, HTTPException, Request\nfrom pydantic import BaseModel, Field\n\nfrom ..download_task_store import (\n    DownloadTask,\n    DownloadTaskStatus,\n    get_task,\n    clear_completed,\n    create_task,\n    get_tasks,\n    update_status,\n    cancel_task,\n)\n\nfrom ...providers.provider import ModelInfo\nfrom ...providers.provider_manager import PROVIDER_OLLAMA\n\nlogger = logging.getLogger(__name__)\n\nrouter = APIRouter(prefix=\"/ollama-models\", tags=[\"ollama-models\"])\n\n_background_tasks: Dict[str, asyncio.Task] = {}\n_background_tasks_lock = asyncio.Lock()\n\n\nclass OllamaDownloadRequest(BaseModel):\n    name: str = Field(..., description=\"Ollama model name, e.g. 'llama3:8b'\")\n\n\nclass OllamaModelResponse(BaseModel):\n    name: str\n    size: int\n    digest: Optional[str] = None\n    modified_at: Optional[str] = None\n\n\nclass OllamaDownloadTaskResponse(BaseModel):\n    task_id: str\n    status: str\n    name: str\n    error: Optional[str] = None\n    result: Optional[OllamaModelResponse] = None\n\n\ndef _is_ollama_connection_error(exc: Exception) -> bool:\n    \"\"\"Return True when the exception indicates Ollama daemon is unreachable.\n\n    The ollama SDK may raise different exception types depending on version.\n    We keep detection tolerant by checking both type and message patterns.\n    \"\"\"\n    if isinstance(exc, ConnectionError):\n        return True\n    msg = str(exc).lower()\n    return \"failed to connect to ollama\" in msg or \"connection refused\" in msg\n\n\ndef _task_to_response(task: DownloadTask) -> OllamaDownloadTaskResponse:\n    result = None\n    if task.result:\n        result = OllamaModelResponse(**task.result)\n    return OllamaDownloadTaskResponse(\n        task_id=task.task_id,\n        status=task.status.value,\n        name=task.repo_id,  # store model name in repo_id for reuse\n        error=task.error,\n        result=result,\n    )\n\n\nasync def _register_background_task(task_id: str, task: asyncio.Task) -> None:\n    async with _background_tasks_lock:\n        _background_tasks[task_id] = task\n\n\nasync def _pop_background_task(task_id: str) -> Optional[asyncio.Task]:\n    async with _background_tasks_lock:\n        return _background_tasks.pop(task_id, None)\n\n\nasync def _run_ollama_download_in_background(\n    task_id: str,\n    model_name: str,\n    ollama_provider,\n) -> None:\n    task = await get_task(task_id)\n    if task and task.status == DownloadTaskStatus.CANCELLED:\n        logger.info(\"Ollama download task %s cancelled before start\", task_id)\n        await _pop_background_task(task_id)\n        return\n\n    await update_status(task_id, DownloadTaskStatus.DOWNLOADING)\n\n    try:\n        await ollama_provider.add_model(\n            ModelInfo(id=model_name, name=model_name),\n        )\n\n        task = await get_task(task_id)\n        if task and task.status == DownloadTaskStatus.CANCELLED:\n            logger.info(\n                \"Ollama download task %s cancelled during execution\",\n                task_id,\n            )\n            await _pop_background_task(task_id)\n            return\n\n        await update_status(\n            task_id,\n            DownloadTaskStatus.COMPLETED,\n            result={\n                \"name\": model_name,\n                \"size\": 0,\n                \"digest\": None,\n                \"modified_at\": None,\n            },\n        )\n    except asyncio.CancelledError:\n        await update_status(task_id, DownloadTaskStatus.CANCELLED)\n        logger.info(\"Ollama download task %s cancelled\", task_id)\n        raise\n    except (\n        ImportError,\n        ValueError,\n        RuntimeError,\n        OSError,\n        ConnectionError,\n    ) as exc:\n        logger.exception(\"Ollama background download failed: %s\", exc)\n        await update_status(\n            task_id,\n            DownloadTaskStatus.FAILED,\n            error=str(exc),\n        )\n    finally:\n        await _pop_background_task(task_id)\n\n\n@router.get(\n    \"\",\n    response_model=List[OllamaModelResponse],\n    summary=\"List Ollama models\",\n)\nasync def list_ollama_models(\n    request: Request,\n) -> List[OllamaModelResponse]:\n    \"\"\"Return the current Ollama model list via the SDK.\n\n    If the Ollama SDK is not installed, returns HTTP 501.\n    \"\"\"\n    p = request.app.state.provider_manager.get_provider(\n        PROVIDER_OLLAMA.id,\n    )\n    try:\n        models = await p._client().list()  # pylint: disable=protected-access\n    except ImportError as exc:\n        raise HTTPException(\n            status_code=501,\n            detail=\"Ollama Python SDK not installed. Install with: \"\n            \"pip install 'copaw[ollama]'\",\n        ) from exc\n    except (ValueError, RuntimeError, OSError, ConnectionError) as exc:\n        logger.exception(\"Failed to list Ollama models\")\n        raise HTTPException(\n            status_code=500,\n            detail=f\"Failed to list Ollama models: {exc}\",\n        ) from exc\n\n    return [\n        OllamaModelResponse(\n            name=m.model,\n            size=m.size,\n            digest=m.digest,\n            modified_at=str(m.modified_at),\n        )\n        for m in models.models\n    ]\n\n\n@router.post(\n    \"/download\",\n    response_model=OllamaDownloadTaskResponse,\n    summary=\"Start a background Ollama model pull\",\n)\nasync def download_ollama_model(\n    request: Request,\n    body: OllamaDownloadRequest,\n) -> OllamaDownloadTaskResponse:\n    \"\"\"Start a background pull via Ollama SDK.\n\n    Returns a task_id immediately; the frontend can poll /download-status\n    to track progress.\n    \"\"\"\n    ollama_provider = request.app.state.provider_manager.get_provider(\n        PROVIDER_OLLAMA.id,\n    )\n\n    await clear_completed(backend=PROVIDER_OLLAMA.id)\n    task = await create_task(\n        repo_id=body.name,\n        filename=None,\n        backend=PROVIDER_OLLAMA.id,\n        source=\"ollama\",\n    )\n\n    background_task = asyncio.create_task(\n        _run_ollama_download_in_background(\n            task_id=task.task_id,\n            model_name=body.name,\n            ollama_provider=ollama_provider,\n        ),\n        name=f\"ollama-download-{task.task_id}\",\n    )\n    await _register_background_task(task.task_id, background_task)\n\n    return _task_to_response(task)\n\n\n@router.get(\n    \"/download-status\",\n    response_model=List[OllamaDownloadTaskResponse],\n    summary=\"Get Ollama download tasks\",\n)\nasync def get_ollama_download_status() -> List[OllamaDownloadTaskResponse]:\n    \"\"\"Return all Ollama-related download tasks.\"\"\"\n    tasks = await get_tasks(backend=PROVIDER_OLLAMA.id)\n    return [_task_to_response(t) for t in tasks]\n\n\n@router.delete(\n    \"/download/{task_id}\",\n    summary=\"Cancel an Ollama download task\",\n)\nasync def cancel_ollama_download(task_id: str) -> dict:\n    \"\"\"Cancel a pending or downloading Ollama model pull.\"\"\"\n    success = await cancel_task(task_id)\n    if not success:\n        raise HTTPException(\n            status_code=404,\n            detail=(\n                \"Task not found or not cancellable \"\n                \"(already completed/failed/cancelled)\"\n            ),\n        )\n\n    background_task = await _pop_background_task(task_id)\n    if background_task and not background_task.done():\n        background_task.cancel()\n\n    return {\"status\": \"cancelled\", \"task_id\": task_id}\n\n\n@router.delete(\n    \"/{name:path}\",\n    summary=\"Delete an Ollama model\",\n)\nasync def delete_ollama_model(\n    request: Request,\n    name: str,\n) -> dict:\n    \"\"\"Delete an Ollama model via the SDK.\"\"\"\n    ollama_provider = request.app.state.provider_manager.get_provider(\n        PROVIDER_OLLAMA.id,\n    )\n\n    try:\n        await ollama_provider.delete_model(model_id=name)  # type: ignore\n    except ImportError as exc:\n        raise HTTPException(\n            status_code=501,\n            detail=\"Ollama SDK not installed. Install with: \"\n            \"pip install 'copaw[ollama]'\",\n        ) from exc\n    except (ValueError, RuntimeError, OSError, ConnectionError) as exc:\n        logger.exception(\"Failed to delete Ollama model: %s\", exc)\n        raise HTTPException(status_code=400, detail=str(exc)) from exc\n    return {\"status\": \"deleted\", \"name\": name}\n"
  },
  {
    "path": "src/copaw/app/routers/providers.py",
    "content": "# -*- coding: utf-8 -*-\n\"\"\"API routes for LLM providers and models.\"\"\"\n\nfrom __future__ import annotations\n\nimport logging\nfrom typing import List, Literal, Optional\nfrom copy import deepcopy\n\nfrom fastapi import APIRouter, Body, Depends, HTTPException, Path, Request\nfrom pydantic import BaseModel, Field\n\nfrom ..agent_context import get_agent_for_request\nfrom ...config.config import load_agent_config, save_agent_config\nfrom ...providers.provider import ProviderInfo, ModelInfo\nfrom ...providers.provider_manager import ActiveModelsInfo, ProviderManager\nfrom ...providers.models import ModelSlotConfig\n\n\nlogger = logging.getLogger(__name__)\n\nrouter = APIRouter(prefix=\"/models\", tags=[\"models\"])\n\nChatModelName = Literal[\n    \"OpenAIChatModel\",\n    \"AnthropicChatModel\",\n    \"GeminiChatModel\",\n]\n\n\ndef get_provider_manager(request: Request) -> ProviderManager:\n    \"\"\"Get the provider manager from app state.\n\n    Args:\n        request: FastAPI request object\n    \"\"\"\n    provider_manager = getattr(request.app.state, \"provider_manager\", None)\n    if provider_manager is None:\n        provider_manager = ProviderManager.get_instance()\n    return provider_manager\n\n\nclass ProviderConfigRequest(BaseModel):\n    api_key: Optional[str] = Field(default=None)\n    base_url: Optional[str] = Field(default=None)\n    chat_model: Optional[ChatModelName] = Field(\n        default=None,\n        description=\"Chat model class name for protocol selection\",\n    )\n    generate_kwargs: Optional[dict] = Field(\n        default_factory=dict,\n        description=(\n            \"Configuration in json format, will be expanded \"\n            \"and passed to generation calls \"\n            \"(e.g., openai.chat.completions, anthropic.messages).\"\n        ),\n    )\n\n\nclass ModelSlotRequest(BaseModel):\n    provider_id: str = Field(..., description=\"Provider to use\")\n    model: str = Field(..., description=\"Model identifier\")\n\n\nclass CreateCustomProviderRequest(BaseModel):\n    id: str = Field(...)\n    name: str = Field(...)\n    default_base_url: str = Field(default=\"\")\n    api_key_prefix: str = Field(default=\"\")\n    chat_model: ChatModelName = Field(default=\"OpenAIChatModel\")\n    models: List[ModelInfo] = Field(default_factory=list)\n\n\nclass AddModelRequest(BaseModel):\n    id: str = Field(...)\n    name: str = Field(...)\n\n\n@router.get(\n    \"\",\n    response_model=List[ProviderInfo],\n    summary=\"List all providers\",\n)\nasync def list_all_providers(\n    manager: ProviderManager = Depends(get_provider_manager),\n) -> List[ProviderInfo]:\n    return await manager.list_provider_info()\n\n\n@router.put(\n    \"/{provider_id}/config\",\n    response_model=ProviderInfo,\n    summary=\"Configure a provider\",\n)\nasync def configure_provider(\n    manager: ProviderManager = Depends(get_provider_manager),\n    provider_id: str = Path(...),\n    body: ProviderConfigRequest = Body(...),\n) -> ProviderInfo:\n    ok = manager.update_provider(\n        provider_id,\n        {\n            \"api_key\": body.api_key,\n            \"base_url\": body.base_url,\n            \"chat_model\": body.chat_model,\n            \"generate_kwargs\": body.generate_kwargs,\n        },\n    )\n    if not ok:\n        raise HTTPException(\n            status_code=404,\n            detail=f\"Provider '{provider_id}' not found\",\n        )\n\n    provider_info = await manager.get_provider_info(provider_id)\n    if provider_info is None:\n        raise HTTPException(\n            status_code=404,\n            detail=f\"Provider '{provider_id}' not found after update\",\n        )\n    return provider_info\n\n\n@router.post(\n    \"/custom-providers\",\n    response_model=ProviderInfo,\n    summary=\"Create a custom provider\",\n    status_code=201,\n)\nasync def create_custom_provider_endpoint(\n    manager: ProviderManager = Depends(get_provider_manager),\n    body: CreateCustomProviderRequest = Body(...),\n) -> ProviderInfo:\n    try:\n        provider_info = await manager.add_custom_provider(\n            ProviderInfo(\n                id=body.id,\n                name=body.name,\n                base_url=body.default_base_url,\n                api_key_prefix=body.api_key_prefix,\n                chat_model=body.chat_model,\n                extra_models=body.models,\n            ),\n        )\n    except ValueError as exc:\n        raise HTTPException(status_code=400, detail=str(exc)) from exc\n\n    return provider_info\n\n\nclass TestConnectionResponse(BaseModel):\n    success: bool = Field(..., description=\"Whether the test passed\")\n    message: str = Field(..., description=\"Human-readable result message\")\n\n\nclass TestProviderRequest(BaseModel):\n    api_key: Optional[str] = Field(\n        default=None,\n        description=\"Optional API key to test\",\n    )\n    base_url: Optional[str] = Field(\n        default=None,\n        description=\"Optional Base URL to test\",\n    )\n    chat_model: Optional[ChatModelName] = Field(\n        default=None,\n        description=\"Optional chat model class to test protocol behavior\",\n    )\n\n\nclass TestModelRequest(BaseModel):\n    model_id: str = Field(..., description=\"Model ID to test\")\n\n\nclass DiscoverModelsRequest(BaseModel):\n    api_key: Optional[str] = Field(\n        default=None,\n        description=\"Optional API key to use for discovery\",\n    )\n    base_url: Optional[str] = Field(\n        default=None,\n        description=\"Optional Base URL to use for discovery\",\n    )\n    chat_model: Optional[ChatModelName] = Field(\n        default=None,\n        description=\"Optional chat model class to use for discovery\",\n    )\n\n\nclass DiscoverModelsResponse(BaseModel):\n    success: bool = Field(..., description=\"Whether discovery succeeded\")\n    models: List[ModelInfo] = Field(\n        default_factory=list,\n        description=\"Discovered models\",\n    )\n    message: str = Field(\n        default=\"\",\n        description=\"Human-readable result message\",\n    )\n    added_count: int = Field(\n        default=0,\n        description=\"How many new models were added into provider config\",\n    )\n\n\n@router.post(\n    \"/{provider_id}/test\",\n    response_model=TestConnectionResponse,\n    summary=\"Test provider connection\",\n)\nasync def test_provider(\n    manager: ProviderManager = Depends(get_provider_manager),\n    provider_id: str = Path(...),\n    body: Optional[TestProviderRequest] = Body(default=None),\n) -> TestConnectionResponse:\n    \"\"\"Test if a provider's URL and API key are valid.\"\"\"\n    try:\n        provider = manager.get_provider(provider_id)\n        if provider is None:\n            raise ValueError(f\"Provider '{provider_id}' not found\")\n        # Ensure we don't accidentally modify provider config during test\n        tmp_provider = deepcopy(provider)\n        if body and body.api_key:\n            tmp_provider.api_key = body.api_key\n        if body and body.base_url:\n            tmp_provider.base_url = body.base_url\n        ok, msg = await tmp_provider.check_connection()\n        return TestConnectionResponse(\n            success=ok,\n            message=\"Connection successful\"\n            if ok\n            else f\"Connection failed: {msg}\",\n        )\n    except ValueError as exc:\n        raise HTTPException(status_code=404, detail=str(exc)) from exc\n\n\n@router.post(\n    \"/{provider_id}/discover\",\n    response_model=DiscoverModelsResponse,\n    summary=\"Discover available models from provider\",\n)\nasync def discover_models(\n    manager: ProviderManager = Depends(get_provider_manager),\n    provider_id: str = Path(...),\n    body: Optional[DiscoverModelsRequest] = Body(default=None),\n) -> DiscoverModelsResponse:\n    try:\n        ok = manager.update_provider(\n            provider_id,\n            {\n                \"api_key\": body.api_key if body else None,\n                \"base_url\": body.base_url if body else None,\n            },\n        )\n        if not ok:\n            raise HTTPException(\n                status_code=404,\n                detail=f\"Provider '{provider_id}' not found\",\n            )\n        try:\n            result = await manager.fetch_provider_models(\n                provider_id,\n            )\n            success = True\n        except Exception:\n            result = []\n            success = False\n        return DiscoverModelsResponse(success=success, models=result)\n    except ValueError as exc:\n        raise HTTPException(status_code=404, detail=str(exc)) from exc\n\n\n@router.post(\n    \"/{provider_id}/models/test\",\n    response_model=TestConnectionResponse,\n    summary=\"Test a specific model\",\n)\nasync def test_model(\n    manager: ProviderManager = Depends(get_provider_manager),\n    provider_id: str = Path(...),\n    body: TestModelRequest = Body(...),\n) -> TestConnectionResponse:\n    \"\"\"Test if a specific model works with the configured provider.\"\"\"\n    try:\n        provider = manager.get_provider(provider_id)\n        if provider is None:\n            raise ValueError(f\"Provider '{provider_id}' not found\")\n        ok, msg = await provider.check_model_connection(model_id=body.model_id)\n        return TestConnectionResponse(\n            success=ok,\n            message=(\n                \"Model connection successful\"\n                if ok\n                else f\"Model connection failed: {msg}\"\n            ),\n        )\n    except ValueError as exc:\n        raise HTTPException(status_code=404, detail=str(exc)) from exc\n\n\n@router.delete(\n    \"/custom-providers/{provider_id}\",\n    response_model=List[ProviderInfo],\n    summary=\"Delete a custom provider\",\n)\nasync def delete_custom_provider_endpoint(\n    manager: ProviderManager = Depends(get_provider_manager),\n    provider_id: str = Path(...),\n) -> List[ProviderInfo]:\n    try:\n        ok = manager.remove_custom_provider(provider_id)\n        if not ok:\n            raise ValueError(f\"Custom Provider '{provider_id}' not found\")\n    except ValueError as exc:\n        raise HTTPException(status_code=400, detail=str(exc)) from exc\n    return await manager.list_provider_info()\n\n\n@router.post(\n    \"/{provider_id}/models\",\n    response_model=ProviderInfo,\n    summary=\"Add a model to a provider\",\n    status_code=201,\n)\nasync def add_model_endpoint(\n    manager: ProviderManager = Depends(get_provider_manager),\n    provider_id: str = Path(...),\n    body: AddModelRequest = Body(...),\n) -> ProviderInfo:\n    try:\n        provider = await manager.add_model_to_provider(\n            provider_id=provider_id,\n            model_info=ModelInfo(id=body.id, name=body.name),\n        )  # Validate provider exists and add model\n    except ValueError as exc:\n        raise HTTPException(status_code=404, detail=str(exc)) from exc\n    return provider\n\n\n@router.delete(\n    \"/{provider_id}/models/{model_id:path}\",\n    response_model=ProviderInfo,\n    summary=\"Remove a model from a provider\",\n)\nasync def remove_model_endpoint(\n    manager: ProviderManager = Depends(get_provider_manager),\n    provider_id: str = Path(...),\n    model_id: str = Path(...),\n) -> ProviderInfo:\n    try:\n        provider = await manager.delete_model_from_provider(\n            provider_id=provider_id,\n            model_id=model_id,\n        )  # Validate provider and model exist and delete\n    except ValueError as exc:\n        raise HTTPException(status_code=400, detail=str(exc)) from exc\n    return provider\n\n\n@router.get(\n    \"/active\",\n    response_model=ActiveModelsInfo,\n    summary=\"Get active LLM\",\n)\nasync def get_active_models(\n    request: Request,\n    manager: ProviderManager = Depends(get_provider_manager),\n) -> ActiveModelsInfo:\n    \"\"\"Get active model (agent-specific or global fallback).\"\"\"\n    # Try to get agent-specific active model\n    try:\n        workspace = await get_agent_for_request(request)\n        logger.debug(\n            f\"get_active_models: got workspace.agent_id={workspace.agent_id}\",\n        )\n        agent_config = load_agent_config(workspace.agent_id)\n        logger.debug(\n            f\"get_active_models: agent_config.active_model=\"\n            f\"{agent_config.active_model}\",\n        )\n        if agent_config.active_model:\n            logger.info(\n                f\"Returning agent-specific model for {workspace.agent_id}: \"\n                f\"{agent_config.active_model}\",\n            )\n            return ActiveModelsInfo(active_llm=agent_config.active_model)\n    except Exception as e:\n        logger.warning(\n            f\"Failed to get agent-specific model: {e}\",\n            exc_info=True,\n        )\n\n    # Fallback to global active model\n    global_model = manager.get_active_model()\n    logger.info(f\"Returning global model: {global_model}\")\n    return ActiveModelsInfo(active_llm=global_model)\n\n\n@router.put(\n    \"/active\",\n    response_model=ActiveModelsInfo,\n    summary=\"Set active LLM\",\n)\nasync def set_active_model(\n    request: Request,\n    manager: ProviderManager = Depends(get_provider_manager),\n    body: ModelSlotRequest = Body(...),\n) -> ActiveModelsInfo:\n    \"\"\"Set active model for current agent.\"\"\"\n    # Validate provider and model exist\n    try:\n        await manager.activate_model(body.provider_id, body.model)\n    except ValueError as exc:\n        message = str(exc)\n        lower_msg = message.lower()\n        if \"provider\" in lower_msg and \"not found\" in lower_msg:\n            raise HTTPException(status_code=404, detail=message) from exc\n        raise HTTPException(status_code=400, detail=message) from exc\n\n    # Save to agent config\n    try:\n        workspace = await get_agent_for_request(request)\n        agent_config = load_agent_config(workspace.agent_id)\n        agent_config.active_model = ModelSlotConfig(\n            provider_id=body.provider_id,\n            model=body.model,\n        )\n        save_agent_config(workspace.agent_id, agent_config)\n    except Exception as e:\n        # Log warning but don't fail the request\n        logger.warning(\n            f\"Failed to save active model to agent config: {e}\",\n        )\n\n    return ActiveModelsInfo(active_llm=manager.get_active_model())\n"
  },
  {
    "path": "src/copaw/app/routers/schemas_config.py",
    "content": "# -*- coding: utf-8 -*-\n\"\"\"Request/response schemas for config API endpoints.\"\"\"\n\nfrom typing import Optional\n\nfrom pydantic import BaseModel, Field\n\nfrom ...config.config import ActiveHoursConfig\n\n\nclass HeartbeatBody(BaseModel):\n    \"\"\"Request body for PUT /config/heartbeat.\"\"\"\n\n    enabled: bool = False\n    every: str = \"6h\"\n    target: str = \"main\"\n    active_hours: Optional[ActiveHoursConfig] = Field(\n        default=None,\n        alias=\"activeHours\",\n    )\n\n    model_config = {\"populate_by_name\": True, \"extra\": \"allow\"}\n"
  },
  {
    "path": "src/copaw/app/routers/skills.py",
    "content": "# -*- coding: utf-8 -*-\nimport asyncio\nimport logging\nimport threading\nimport time\nimport uuid\nfrom enum import Enum\nfrom typing import Any\nfrom pathlib import Path\nfrom fastapi import APIRouter, HTTPException, Request, UploadFile, File\nfrom fastapi.responses import JSONResponse\nfrom pydantic import BaseModel, Field\nfrom ...agents.skills_manager import (\n    SkillService,\n    SkillInfo,\n)\nfrom ...agents.skills_hub import (\n    SkillImportCancelled,\n    search_hub_skills,\n    install_skill_from_hub,\n)\nfrom ...security.skill_scanner import SkillScanError\n\n\nlogger = logging.getLogger(__name__)\n\n\ndef _scan_error_response(exc: SkillScanError) -> JSONResponse:\n    \"\"\"Build a 422 response with structured scan findings.\"\"\"\n    result = exc.result\n    return JSONResponse(\n        status_code=422,\n        content={\n            \"type\": \"security_scan_failed\",\n            \"detail\": str(exc),\n            \"skill_name\": result.skill_name,\n            \"max_severity\": result.max_severity.value,\n            \"findings\": [\n                {\n                    \"severity\": f.severity.value,\n                    \"title\": f.title,\n                    \"description\": f.description,\n                    \"file_path\": f.file_path,\n                    \"line_number\": f.line_number,\n                    \"rule_id\": f.rule_id,\n                }\n                for f in result.findings\n            ],\n        },\n    )\n\n\nclass SkillSpec(SkillInfo):\n    enabled: bool = False\n\n\nclass CreateSkillRequest(BaseModel):\n    name: str = Field(..., description=\"Skill name\")\n    content: str = Field(..., description=\"Skill content (SKILL.md)\")\n    references: dict[str, Any] | None = Field(\n        None,\n        description=\"Optional tree structure for references/. \"\n        \"Can be flat {filename: content} or nested \"\n        \"{dirname: {filename: content}}\",\n    )\n    scripts: dict[str, Any] | None = Field(\n        None,\n        description=\"Optional tree structure for scripts/. \"\n        \"Can be flat {filename: content} or nested \"\n        \"{dirname: {filename: content}}\",\n    )\n\n\nclass HubSkillSpec(BaseModel):\n    slug: str\n    name: str\n    description: str = \"\"\n    version: str = \"\"\n    source_url: str = \"\"\n\n\nclass HubInstallRequest(BaseModel):\n    bundle_url: str = Field(..., description=\"Skill URL\")\n    version: str = Field(default=\"\", description=\"Optional version tag\")\n    enable: bool = Field(default=True, description=\"Enable after import\")\n    overwrite: bool = Field(\n        default=False,\n        description=\"Overwrite existing customized skill\",\n    )\n\n\nclass HubInstallTaskStatus(str, Enum):\n    PENDING = \"pending\"\n    IMPORTING = \"importing\"\n    COMPLETED = \"completed\"\n    FAILED = \"failed\"\n    CANCELLED = \"cancelled\"\n\n\nclass HubInstallTask(BaseModel):\n    task_id: str = Field(default_factory=lambda: str(uuid.uuid4()))\n    bundle_url: str\n    version: str = \"\"\n    enable: bool = True\n    overwrite: bool = False\n    status: HubInstallTaskStatus = HubInstallTaskStatus.PENDING\n    error: str | None = None\n    result: dict[str, Any] | None = None\n    created_at: float = Field(default_factory=time.time)\n    updated_at: float = Field(default_factory=time.time)\n\n\n_hub_install_tasks: dict[str, HubInstallTask] = {}\n_hub_install_runtime_tasks: dict[str, asyncio.Task] = {}\n_hub_install_cancel_events: dict[str, threading.Event] = {}\n_hub_install_lock = asyncio.Lock()\n\n\nrouter = APIRouter(prefix=\"/skills\", tags=[\"skills\"])\n\n\n@router.get(\"\")\nasync def list_skills(\n    request: Request,\n) -> list[SkillSpec]:\n    \"\"\"List all skills for active agent.\"\"\"\n    from ..agent_context import get_agent_for_request\n\n    workspace = await get_agent_for_request(request)\n    workspace_dir = Path(workspace.workspace_dir)\n    skill_service = SkillService(workspace_dir)\n\n    # Get all skills (builtin + customized)\n    all_skills = skill_service.list_all_skills()\n\n    # Get active skills to determine enabled status\n    active_skills_dir = workspace_dir / \"active_skills\"\n    active_skill_names = set()\n    if active_skills_dir.exists():\n        active_skill_names = {\n            d.name\n            for d in active_skills_dir.iterdir()\n            if d.is_dir() and (d / \"SKILL.md\").exists()\n        }\n\n    # Convert to SkillSpec with enabled status\n    skills_spec = [\n        SkillSpec(\n            name=skill.name,\n            description=skill.description,\n            content=skill.content,\n            source=skill.source,\n            path=skill.path,\n            references=skill.references,\n            scripts=skill.scripts,\n            enabled=skill.name in active_skill_names,\n        )\n        for skill in all_skills\n    ]\n\n    return skills_spec\n\n\n@router.get(\"/available\")\nasync def get_available_skills(\n    request: Request,\n) -> list[SkillSpec]:\n    \"\"\"List available (enabled) skills for active agent.\"\"\"\n    from ..agent_context import get_agent_for_request\n\n    workspace = await get_agent_for_request(request)\n    workspace_dir = Path(workspace.workspace_dir)\n    skill_service = SkillService(workspace_dir)\n\n    # Get available (active) skills\n    available_skills = skill_service.list_available_skills()\n\n    # Convert to SkillSpec\n    skills_spec = [\n        SkillSpec(\n            name=skill.name,\n            description=skill.description,\n            content=skill.content,\n            source=skill.source,\n            path=skill.path,\n            references=skill.references,\n            scripts=skill.scripts,\n            enabled=True,\n        )\n        for skill in available_skills\n    ]\n\n    return skills_spec\n\n\n@router.get(\"/hub/search\")\nasync def search_hub(\n    q: str = \"\",\n    limit: int = 20,\n) -> list[HubSkillSpec]:\n    results = search_hub_skills(q, limit=limit)\n    return [\n        HubSkillSpec(\n            slug=item.slug,\n            name=item.name,\n            description=item.description,\n            version=item.version,\n            source_url=item.source_url,\n        )\n        for item in results\n    ]\n\n\nasync def _hub_task_set_status(\n    task_id: str,\n    status: HubInstallTaskStatus,\n    *,\n    error: str | None = None,\n    result: dict[str, Any] | None = None,\n) -> None:\n    async with _hub_install_lock:\n        task = _hub_install_tasks.get(task_id)\n        if task is None:\n            return\n        task.status = status\n        task.updated_at = time.time()\n        if error is not None:\n            task.error = error\n        if result is not None:\n            task.result = result\n\n\nasync def _hub_task_get(task_id: str) -> HubInstallTask | None:\n    async with _hub_install_lock:\n        return _hub_install_tasks.get(task_id)\n\n\nasync def _hub_task_register_runtime(task_id: str, task: asyncio.Task) -> None:\n    async with _hub_install_lock:\n        _hub_install_runtime_tasks[task_id] = task\n\n\nasync def _hub_task_pop_runtime(task_id: str) -> asyncio.Task | None:\n    async with _hub_install_lock:\n        return _hub_install_runtime_tasks.pop(task_id, None)\n\n\ndef _cleanup_imported_skill(workspace_dir: Path, skill_name: str) -> None:\n    \"\"\"Best-effort cleanup for cancelled skill imports.\"\"\"\n    if not skill_name:\n        return\n    try:\n        skill_service = SkillService(workspace_dir)\n        skill_service.disable_skill(skill_name)\n        skill_service.delete_skill(skill_name)\n    except Exception as e:  # pylint: disable=broad-except\n        logger.warning(\n            \"Cleanup after cancelled import failed for '%s': %s\",\n            skill_name,\n            e,\n        )\n\n\nasync def _run_hub_install_task(\n    *,\n    task_id: str,\n    workspace_dir: Path,\n    body: HubInstallRequest,\n    cancel_event: threading.Event,\n) -> None:\n    await _hub_task_set_status(task_id, HubInstallTaskStatus.IMPORTING)\n    result_payload: dict[str, Any] | None = None\n    imported_skill_name: str | None = None\n    try:\n        loop = asyncio.get_running_loop()\n        result = await loop.run_in_executor(\n            None,\n            lambda: install_skill_from_hub(\n                workspace_dir=workspace_dir,\n                bundle_url=body.bundle_url,\n                version=body.version,\n                enable=body.enable,\n                overwrite=body.overwrite,\n                cancel_checker=cancel_event.is_set,\n            ),\n        )\n        result_payload = {\n            \"installed\": True,\n            \"name\": result.name,\n            \"enabled\": result.enabled,\n            \"source_url\": result.source_url,\n        }\n        imported_skill_name = result.name\n        if cancel_event.is_set():\n            _cleanup_imported_skill(workspace_dir, result.name)\n            await _hub_task_set_status(\n                task_id,\n                HubInstallTaskStatus.CANCELLED,\n                result={\n                    \"installed\": False,\n                    \"name\": result.name,\n                    \"enabled\": False,\n                    \"source_url\": result.source_url,\n                },\n            )\n            return\n        await _hub_task_set_status(\n            task_id,\n            HubInstallTaskStatus.COMPLETED,\n            result=result_payload,\n        )\n    except SkillImportCancelled:\n        if imported_skill_name:\n            _cleanup_imported_skill(workspace_dir, imported_skill_name)\n        await _hub_task_set_status(task_id, HubInstallTaskStatus.CANCELLED)\n    except SkillScanError as e:\n        await _hub_task_set_status(\n            task_id,\n            HubInstallTaskStatus.FAILED,\n            error=str(e),\n        )\n    except ValueError as e:\n        await _hub_task_set_status(\n            task_id,\n            HubInstallTaskStatus.FAILED,\n            error=str(e),\n        )\n    except RuntimeError as e:\n        await _hub_task_set_status(\n            task_id,\n            HubInstallTaskStatus.FAILED,\n            error=str(e),\n        )\n    except Exception as e:  # pylint: disable=broad-except\n        await _hub_task_set_status(\n            task_id,\n            HubInstallTaskStatus.FAILED,\n            error=f\"Skill hub import failed: {e}\",\n        )\n    finally:\n        await _hub_task_pop_runtime(task_id)\n\n\n@router.post(\"/hub/install\")\nasync def install_from_hub(\n    request_body: HubInstallRequest,\n    request: Request,\n):\n    from ..agent_context import get_agent_for_request\n\n    workspace = await get_agent_for_request(request)\n    workspace_dir = Path(workspace.workspace_dir)\n\n    try:\n        result = install_skill_from_hub(\n            workspace_dir=workspace_dir,\n            bundle_url=request_body.bundle_url,\n            version=request_body.version,\n            enable=request_body.enable,\n            overwrite=request_body.overwrite,\n        )\n    except SkillScanError as e:\n        return _scan_error_response(e)\n    except ValueError as e:\n        detail = str(e)\n        logger.warning(\n            \"Skill hub install 400: bundle_url=%s detail=%s\",\n            (request_body.bundle_url or \"\")[:80],\n            detail,\n        )\n        raise HTTPException(status_code=400, detail=detail) from e\n    except RuntimeError as e:\n        detail = str(e)\n        logger.exception(\n            \"Skill hub install failed (upstream/rate limit): %s\",\n            e,\n        )\n        raise HTTPException(status_code=502, detail=detail) from e\n    except Exception as e:\n        detail = f\"Skill hub import failed: {e}\"\n        logger.exception(\"Skill hub import failed: %s\", e)\n        raise HTTPException(status_code=502, detail=detail) from e\n    return {\n        \"installed\": True,\n        \"name\": result.name,\n        \"enabled\": result.enabled,\n        \"source_url\": result.source_url,\n    }\n\n\n@router.post(\"/hub/install/start\", response_model=HubInstallTask)\nasync def start_install_from_hub(\n    request_body: HubInstallRequest,\n    request: Request,\n) -> HubInstallTask:\n    from ..agent_context import get_agent_for_request\n\n    workspace = await get_agent_for_request(request)\n    workspace_dir = Path(workspace.workspace_dir)\n    task = HubInstallTask(\n        bundle_url=request_body.bundle_url,\n        version=request_body.version,\n        enable=request_body.enable,\n        overwrite=request_body.overwrite,\n    )\n    cancel_event = threading.Event()\n    async with _hub_install_lock:\n        _hub_install_tasks[task.task_id] = task\n        _hub_install_cancel_events[task.task_id] = cancel_event\n\n    runtime_task = asyncio.create_task(\n        _run_hub_install_task(\n            task_id=task.task_id,\n            workspace_dir=workspace_dir,\n            body=request_body,\n            cancel_event=cancel_event,\n        ),\n        name=f\"skill-hub-install-{task.task_id}\",\n    )\n    await _hub_task_register_runtime(task.task_id, runtime_task)\n    return task\n\n\n@router.get(\"/hub/install/status/{task_id}\", response_model=HubInstallTask)\nasync def get_hub_install_status(task_id: str) -> HubInstallTask:\n    task = await _hub_task_get(task_id)\n    if task is None:\n        raise HTTPException(status_code=404, detail=\"install task not found\")\n    return task\n\n\n@router.post(\"/hub/install/cancel/{task_id}\")\nasync def cancel_hub_install(task_id: str) -> dict[str, Any]:\n    async with _hub_install_lock:\n        task = _hub_install_tasks.get(task_id)\n        if task is None:\n            raise HTTPException(\n                status_code=404,\n                detail=\"install task not found\",\n            )\n        if task.status in (\n            HubInstallTaskStatus.COMPLETED,\n            HubInstallTaskStatus.FAILED,\n            HubInstallTaskStatus.CANCELLED,\n        ):\n            return {\"task_id\": task_id, \"status\": task.status.value}\n        cancel_event = _hub_install_cancel_events.get(task_id)\n        if cancel_event is not None:\n            cancel_event.set()\n        task.status = HubInstallTaskStatus.CANCELLED\n        task.updated_at = time.time()\n    return {\"task_id\": task_id, \"status\": \"cancelled\"}\n\n\n_ALLOWED_ZIP_TYPES = {\n    \"application/zip\",\n    \"application/x-zip-compressed\",\n    \"application/octet-stream\",\n}\n_MAX_UPLOAD_BYTES = 100 * 1024 * 1024  # 100 MB\n\n\n@router.post(\"/upload\")\nasync def upload_skill_zip(\n    request: Request,\n    file: UploadFile = File(...),\n    enable: bool = False,\n    overwrite: bool = False,\n):\n    \"\"\"Import skill(s) from an uploaded zip file.\"\"\"\n    from ..agent_context import get_agent_for_request\n\n    if file.content_type and file.content_type not in _ALLOWED_ZIP_TYPES:\n        raise HTTPException(\n            status_code=400,\n            detail=(\n                \"Expected a zip file, \"\n                f\"got content-type: {file.content_type}\"\n            ),\n        )\n\n    data = await file.read()\n    if len(data) > _MAX_UPLOAD_BYTES:\n        raise HTTPException(\n            status_code=400,\n            detail=(\n                f\"File too large ({len(data) // (1024 * 1024)} MB). \"\n                f\"Maximum is {_MAX_UPLOAD_BYTES // (1024 * 1024)} MB.\"\n            ),\n        )\n\n    workspace = await get_agent_for_request(request)\n    workspace_dir = Path(workspace.workspace_dir)\n    skill_service = SkillService(workspace_dir)\n\n    try:\n        result = await asyncio.to_thread(\n            skill_service.import_from_zip,\n            data,\n            overwrite,\n            enable,\n        )\n    except SkillScanError as e:\n        return _scan_error_response(e)\n    except ValueError as e:\n        raise HTTPException(status_code=400, detail=str(e)) from e\n    except Exception as e:\n        logger.exception(\"Zip skill upload failed: %s\", e)\n        raise HTTPException(\n            status_code=500,\n            detail=\"Skill upload failed\",\n        ) from e\n\n    return result\n\n\n@router.post(\"/batch-disable\")\nasync def batch_disable_skills(\n    skill_name: list[str],\n    request: Request,\n) -> None:\n    from ..agent_context import get_agent_for_request\n\n    workspace = await get_agent_for_request(request)\n    workspace_dir = Path(workspace.workspace_dir)\n    skill_service = SkillService(workspace_dir)\n\n    for skill in skill_name:\n        skill_service.disable_skill(skill)\n\n\n@router.post(\"/batch-enable\")\nasync def batch_enable_skills(\n    skill_name: list[str],\n    request: Request,\n):\n    from ..agent_context import get_agent_for_request\n\n    workspace = await get_agent_for_request(request)\n    workspace_dir = Path(workspace.workspace_dir)\n    skill_service = SkillService(workspace_dir)\n\n    blocked: list[dict] = []\n    for skill in skill_name:\n        try:\n            skill_service.enable_skill(skill)\n        except SkillScanError as e:\n            blocked.append(\n                {\n                    \"skill_name\": skill,\n                    \"max_severity\": e.result.max_severity.value,\n                    \"detail\": str(e),\n                },\n            )\n    if blocked:\n        return JSONResponse(\n            status_code=422,\n            content={\n                \"type\": \"security_scan_failed\",\n                \"detail\": (\n                    f\"{len(blocked)} skill(s) blocked by security scan\"\n                ),\n                \"blocked_skills\": blocked,\n            },\n        )\n\n\n@router.post(\"\")\nasync def create_skill(\n    request_body: CreateSkillRequest,\n    request: Request,\n):\n    from ..agent_context import get_agent_for_request\n\n    workspace = await get_agent_for_request(request)\n    workspace_dir = Path(workspace.workspace_dir)\n    skill_service = SkillService(workspace_dir)\n\n    try:\n        result = skill_service.create_skill(\n            name=request_body.name,\n            content=request_body.content,\n            references=request_body.references,\n            scripts=request_body.scripts,\n        )\n    except SkillScanError as e:\n        return _scan_error_response(e)\n    return {\"created\": result}\n\n\n@router.post(\"/{skill_name}/disable\")\nasync def disable_skill(\n    skill_name: str,\n    request: Request = None,\n):\n    \"\"\"Disable skill for active agent.\"\"\"\n    from ..agent_context import get_agent_for_request\n    import shutil\n\n    workspace = await get_agent_for_request(request)\n    workspace_dir = Path(workspace.workspace_dir)\n    active_skill_dir = workspace_dir / \"active_skills\" / skill_name\n\n    if active_skill_dir.exists():\n        shutil.rmtree(active_skill_dir)\n\n        # Hot reload config (async, non-blocking)\n        # IMPORTANT: Get manager and agent_id before creating background task\n        # to avoid accessing request/workspace after their lifecycle ends\n        manager = request.app.state.multi_agent_manager\n        agent_id = workspace.agent_id\n\n        async def reload_in_background():\n            try:\n                await manager.reload_agent(agent_id)\n            except Exception as e:\n                logger.warning(f\"Background reload failed: {e}\")\n\n        asyncio.create_task(reload_in_background())\n\n        return {\"disabled\": True}\n\n    return {\"disabled\": False}\n\n\n@router.post(\"/{skill_name}/enable\")\nasync def enable_skill(\n    skill_name: str,\n    request: Request = None,\n):\n    \"\"\"Enable skill for active agent.\"\"\"\n    from ..agent_context import get_agent_for_request\n    import shutil\n\n    workspace = await get_agent_for_request(request)\n    workspace_dir = Path(workspace.workspace_dir)\n    active_skill_dir = workspace_dir / \"active_skills\" / skill_name\n\n    # If already enabled, skip\n    if active_skill_dir.exists():\n        return {\"enabled\": True}\n\n    # Find skill from builtin or customized\n    builtin_skill_dir = (\n        Path(__file__).parent.parent.parent / \"agents\" / \"skills\" / skill_name\n    )\n    customized_skill_dir = workspace_dir / \"customized_skills\" / skill_name\n\n    source_dir = None\n    if customized_skill_dir.exists():\n        source_dir = customized_skill_dir\n    elif builtin_skill_dir.exists():\n        source_dir = builtin_skill_dir\n\n    if not source_dir or not (source_dir / \"SKILL.md\").exists():\n        raise HTTPException(\n            status_code=404,\n            detail=f\"Skill '{skill_name}' not found\",\n        )\n\n    # --- Security scan (pre-activation) --------------------------------\n    try:\n        from ...security.skill_scanner import scan_skill_directory\n\n        scan_skill_directory(source_dir, skill_name=skill_name)\n    except SkillScanError as e:\n        return _scan_error_response(e)\n    except Exception as scan_exc:\n        logger.warning(\n            \"Security scan error for skill '%s' (non-fatal): %s\",\n            skill_name,\n            scan_exc,\n        )\n    # -------------------------------------------------------------------\n\n    # Copy to active_skills\n    shutil.copytree(source_dir, active_skill_dir)\n\n    # Hot reload config (async, non-blocking)\n    # IMPORTANT: Get manager and agent_id before creating background task\n    # to avoid accessing request/workspace after their lifecycle ends\n    manager = request.app.state.multi_agent_manager\n    agent_id = workspace.agent_id\n\n    async def reload_in_background():\n        try:\n            await manager.reload_agent(agent_id)\n        except Exception as e:\n            logger.warning(f\"Background reload failed: {e}\")\n\n    asyncio.create_task(reload_in_background())\n\n    return {\"enabled\": True}\n\n\n@router.delete(\"/{skill_name}\")\nasync def delete_skill(\n    skill_name: str,\n    request: Request,\n):\n    \"\"\"Delete a skill from customized_skills directory permanently.\n\n    This only deletes skills from customized_skills directory.\n    Built-in skills cannot be deleted.\n    \"\"\"\n    from ..agent_context import get_agent_for_request\n\n    workspace = await get_agent_for_request(request)\n    workspace_dir = Path(workspace.workspace_dir)\n    skill_service = SkillService(workspace_dir)\n\n    result = skill_service.delete_skill(skill_name)\n    return {\"deleted\": result}\n\n\n@router.get(\"/{skill_name}/files/{source}/{file_path:path}\")\nasync def load_skill_file(\n    skill_name: str,\n    source: str,\n    file_path: str,\n    request: Request,\n):\n    \"\"\"Load a specific file from a skill's references or scripts directory.\n\n    Args:\n        skill_name: Name of the skill\n        source: Source directory (\"builtin\" or \"customized\")\n        file_path: Path relative to skill directory, must start with\n                   \"references/\" or \"scripts/\"\n\n    Returns:\n        File content as string, or None if not found\n\n        Example:\n\n            GET /skills/my_skill/files/customized/references/doc.md\n\n            GET /skills/builtin_skill/files/builtin/scripts/utils/helper.py\n\n    \"\"\"\n    from ..agent_context import get_agent_for_request\n\n    workspace = await get_agent_for_request(request)\n    workspace_dir = Path(workspace.workspace_dir)\n    skill_service = SkillService(workspace_dir)\n\n    content = skill_service.load_skill_file(\n        skill_name=skill_name,\n        file_path=file_path,\n        source=source,\n    )\n    return {\"content\": content}\n"
  },
  {
    "path": "src/copaw/app/routers/skills_stream.py",
    "content": "# -*- coding: utf-8 -*-\n# flake8: noqa: E501\n\"\"\"\nStreaming AI skill optimization API\n\"\"\"\nimport json\nimport logging\n\nfrom fastapi import APIRouter\nfrom fastapi.responses import StreamingResponse\nfrom pydantic import BaseModel, Field\n\nfrom ...agents.model_factory import create_model_and_formatter\n\n\nlogger = logging.getLogger(__name__)\n\n\ndef get_model():\n    \"\"\"Get the active chat model instance.\n\n    Returns:\n        Chat model instance or None if not configured\n    \"\"\"\n    try:\n        model, _ = create_model_and_formatter()\n        return model\n    except Exception as e:\n        logger.warning(\"Failed to get model: %s\", e)\n        return None\n\n\n# System prompts for different languages\nSYSTEM_PROMPTS = {\n    \"en\": \"\"\"You are an AI skill optimization expert. Please optimize the following skill content.\n\n## Output Format Requirements\nOutput the skill content directly. Do NOT use code block markers (like ```yaml or ```). Do NOT add any explanations.\n\n## Optimization Rules\n1. Keep the frontmatter structure (--- enclosed header section)\n2. name field: lowercase with underscores\n3. description field: clear and concise, no more than 80 characters\n4. Body content: use Markdown format, well-structured\n5. Total length: keep within 500 characters\n\n## Example Output\n---\nname: weather_query\ndescription: Query weather info for a city, returns temperature, humidity, wind\n---\n\n## Features\nQuery real-time weather data.\n\n## Usage\nUser inputs city name, returns weather information.\n\n---\nPlease optimize this skill:\"\"\",\n    \"zh\": \"\"\"你是AI技能优化专家。请优化以下技能内容。\n\n## 输出格式要求\n直接输出技能内容，禁止使用代码块标记（如 ```yaml 或 ```），禁止添加任何解释说明。\n\n## 优化规则\n1. 保持frontmatter结构（--- 包围的头部区域）\n2. name字段：英文小写下划线命名\n3. description字段：简洁清晰，不超过80字\n4. 正文用Markdown格式，结构清晰\n5. 总长度控制在500字以内\n\n## 示例输出\n---\nname: weather_query\ndescription: 查询指定城市天气信息，返回温度、湿度、风力等数据\n---\n\n## 功能\n查询实时天气数据。\n\n## 使用\n输入城市名，返回天气信息。\n\n---\n请优化此技能:\"\"\",\n    \"ru\": \"\"\"Вы эксперт по оптимизации AI-навыков. Пожалуйста, оптимизируйте навык.\n\n## Требования к формату вывода\nВыводите содержимое навыка напрямую. НЕ используйте маркеры блока кода.\n\n## Правила оптимизации\n1. Сохраните структуру frontmatter (раздел заголовка, заключённый в ---)\n2. Поле name: строчные буквы с подчёркиванием\n3. Поле description: чёткое и краткое, не более 80 символов\n4. Основное содержимое: используйте формат Markdown\n5. Общая длина: не более 500 символов\n\n## Пример вывода\n---\nname: weather_query\ndescription: Запрос погоды для города, возвращает температуру и влажность\n---\n\n## Функции\nЗапрос данных о погоде в реальном времени.\n\n## Использование\nПользователь вводит город, возвращается информация о погоде.\n\n---\nПожалуйста, оптимизируйте этот навык:\"\"\",\n}\n\n\nclass AIOptimizeSkillRequest(BaseModel):\n    content: str = Field(..., description=\"Current skill content to optimize\")\n    language: str = Field(\n        default=\"en\",\n        description=\"Language for optimization (en, zh, ru)\",\n    )\n\n\nrouter = APIRouter(tags=[\"skills\"])\n\n\ndef _extract_text_from_chunk(chunk) -> str:\n    \"\"\"Extract text content from a response chunk.\n\n    Args:\n        chunk: Response chunk from the model\n\n    Returns:\n        Extracted text string or empty string\n    \"\"\"\n    if not hasattr(chunk, \"content\"):\n        return \"\"\n\n    if isinstance(chunk.content, str):\n        return chunk.content\n\n    if isinstance(chunk.content, list):\n        for item in chunk.content:\n            if isinstance(item, dict) and \"text\" in item:\n                return item[\"text\"]\n\n    return \"\"\n\n\ndef _extract_text_from_response(response) -> str:\n    \"\"\"Extract text from a non-streaming response.\n\n    Args:\n        response: Non-streaming response from the model\n\n    Returns:\n        Extracted text string or empty string\n    \"\"\"\n    if hasattr(response, \"text\"):\n        return response.text\n    if isinstance(response, str):\n        return response\n    return \"\"\n\n\n@router.post(\"/skills/ai/optimize/stream\")\nasync def ai_optimize_skill_stream(request: AIOptimizeSkillRequest):\n    \"\"\"Use AI to optimize an existing skill with streaming response.\n\n    Args:\n        request: Contains current skill content and language preference\n\n    Returns:\n        StreamingResponse with optimized skill content (text deltas)\n    \"\"\"\n\n    async def generate():\n        try:\n            model = get_model()\n            if not model:\n                error_msg = json.dumps(\n                    {\n                        \"error\": (\n                            \"No AI model configured. \"\n                            \"Please configure in Settings.\"\n                        ),\n                    },\n                )\n                yield f\"data: {error_msg}\\n\\n\"\n                return\n\n            system_prompt = SYSTEM_PROMPTS.get(\n                request.language,\n                SYSTEM_PROMPTS[\"en\"],\n            )\n\n            messages = [\n                {\"role\": \"system\", \"content\": system_prompt},\n                {\"role\": \"user\", \"content\": request.content},\n            ]\n\n            response = await model(messages)\n            accumulated = \"\"\n\n            if hasattr(response, \"__aiter__\"):\n                async for chunk in response:\n                    text = _extract_text_from_chunk(chunk)\n\n                    if text and len(text) > len(accumulated):\n                        delta = text[len(accumulated) :]\n                        accumulated = text\n                        data = json.dumps(\n                            {\"text\": delta},\n                            ensure_ascii=False,\n                        )\n                        yield f\"data: {data}\\n\\n\"\n            else:\n                text = _extract_text_from_response(response)\n                if text:\n                    data = json.dumps(\n                        {\"text\": text},\n                        ensure_ascii=False,\n                    )\n                    yield f\"data: {data}\\n\\n\"\n\n            yield f\"data: {json.dumps({'done': True})}\\n\\n\"\n\n        except Exception as e:\n            logger.exception(\"AI skill optimization failed: %s\", e)\n            error_msg = json.dumps(\n                {\"error\": f\"Failed to optimize skill: {str(e)}\"},\n                ensure_ascii=False,\n            )\n            yield f\"data: {error_msg}\\n\\n\"\n\n    return StreamingResponse(\n        generate(),\n        media_type=\"text/event-stream\",\n        headers={\n            \"Cache-Control\": \"no-cache\",\n            \"Connection\": \"keep-alive\",\n            \"X-Accel-Buffering\": \"no\",\n        },\n    )\n"
  },
  {
    "path": "src/copaw/app/routers/token_usage.py",
    "content": "# -*- coding: utf-8 -*-\n\"\"\"Token usage API for console and skill tool.\"\"\"\n\nfrom datetime import date, timedelta\n\nfrom fastapi import APIRouter, Query\n\nfrom ...token_usage import get_token_usage_manager, TokenUsageSummary\n\nrouter = APIRouter(prefix=\"/token-usage\", tags=[\"token-usage\"])\n\n\ndef _parse_date(s: str | None) -> date | None:\n    \"\"\"Parse YYYY-MM-DD string to date.\"\"\"\n    if not s:\n        return None\n    try:\n        return date.fromisoformat(s)\n    except (ValueError, TypeError):\n        return None\n\n\n@router.get(\n    \"\",\n    summary=\"Get token usage summary\",\n    description=\"Return token usage aggregated by date, model, and provider\",\n)\nasync def get_token_usage(\n    start_date: str\n    | None = Query(\n        None,\n        description=\"Start date YYYY-MM-DD (inclusive). Default: 30 days ago\",\n    ),\n    end_date: str\n    | None = Query(\n        None,\n        description=\"End date YYYY-MM-DD (inclusive). Default: today\",\n    ),\n    model: str\n    | None = Query(\n        None,\n        description=\"Filter by model name\",\n    ),\n    provider: str\n    | None = Query(\n        None,\n        description=\"Filter by provider ID\",\n    ),\n) -> TokenUsageSummary:\n    \"\"\"Return token usage summary for the given date range.\"\"\"\n    end_d = _parse_date(end_date) or date.today()\n    start_d = _parse_date(start_date) or (end_d - timedelta(days=30))\n    if start_d > end_d:\n        start_d, end_d = end_d, start_d\n\n    return await get_token_usage_manager().get_summary(\n        start_date=start_d,\n        end_date=end_d,\n        model_name=model,\n        provider_id=provider,\n    )\n"
  },
  {
    "path": "src/copaw/app/routers/tools.py",
    "content": "# -*- coding: utf-8 -*-\n\"\"\"API routes for built-in tools management.\"\"\"\n\nfrom __future__ import annotations\n\nfrom typing import List\n\nfrom fastapi import (\n    APIRouter,\n    HTTPException,\n    Path,\n    Request,\n)\nfrom pydantic import BaseModel, Field\n\nfrom ...config import load_config\n\nrouter = APIRouter(prefix=\"/tools\", tags=[\"tools\"])\n\n\nclass ToolInfo(BaseModel):\n    \"\"\"Tool information for API responses.\"\"\"\n\n    name: str = Field(..., description=\"Tool function name\")\n    enabled: bool = Field(..., description=\"Whether the tool is enabled\")\n    description: str = Field(default=\"\", description=\"Tool description\")\n\n\n@router.get(\"\", response_model=List[ToolInfo])\nasync def list_tools(\n    request: Request,\n) -> List[ToolInfo]:\n    \"\"\"List all built-in tools and enabled status for active agent.\n\n    Returns:\n        List of tool information\n    \"\"\"\n    from ..agent_context import get_agent_for_request\n    from ...config.config import load_agent_config\n\n    workspace = await get_agent_for_request(request)\n    agent_config = load_agent_config(workspace.agent_id)\n\n    # Ensure tools config exists with defaults\n    if not agent_config.tools or not agent_config.tools.builtin_tools:\n        # Fallback to global config if agent config has no tools\n        config = load_config()\n        tools_config = config.tools if hasattr(config, \"tools\") else None\n        if not tools_config:\n            return []\n        builtin_tools = tools_config.builtin_tools\n    else:\n        builtin_tools = agent_config.tools.builtin_tools\n\n    tools_list = []\n    for tool_config in builtin_tools.values():\n        tools_list.append(\n            ToolInfo(\n                name=tool_config.name,\n                enabled=tool_config.enabled,\n                description=tool_config.description,\n            ),\n        )\n\n    return tools_list\n\n\n@router.patch(\"/{tool_name}/toggle\", response_model=ToolInfo)\nasync def toggle_tool(\n    tool_name: str = Path(...),\n    request: Request = None,\n) -> ToolInfo:\n    \"\"\"Toggle tool enabled status for active agent.\n\n    Args:\n        tool_name: Tool function name\n        request: FastAPI request\n\n    Returns:\n        Updated tool information\n\n    Raises:\n        HTTPException: If tool not found\n    \"\"\"\n    from ..agent_context import get_agent_for_request\n    from ...config.config import load_agent_config, save_agent_config\n\n    workspace = await get_agent_for_request(request)\n    agent_config = load_agent_config(workspace.agent_id)\n\n    if (\n        not agent_config.tools\n        or tool_name not in agent_config.tools.builtin_tools\n    ):\n        raise HTTPException(\n            status_code=404,\n            detail=f\"Tool '{tool_name}' not found\",\n        )\n\n    # Toggle enabled status\n    tool_config = agent_config.tools.builtin_tools[tool_name]\n    tool_config.enabled = not tool_config.enabled\n\n    # Save agent config\n    save_agent_config(workspace.agent_id, agent_config)\n\n    # Hot reload config (async, non-blocking)\n    # IMPORTANT: Get manager and agent_id before creating background task\n    # to avoid accessing request/workspace after their lifecycle ends\n    import asyncio\n\n    manager = request.app.state.multi_agent_manager\n    agent_id = workspace.agent_id\n\n    async def reload_in_background():\n        try:\n            await manager.reload_agent(agent_id)\n        except Exception as e:\n            import logging\n\n            logging.getLogger(__name__).warning(\n                f\"Background reload failed: {e}\",\n            )\n\n    asyncio.create_task(reload_in_background())\n\n    # Return immediately (optimistic update)\n    return ToolInfo(\n        name=tool_config.name,\n        enabled=tool_config.enabled,\n        description=tool_config.description,\n    )\n"
  },
  {
    "path": "src/copaw/app/routers/voice.py",
    "content": "# -*- coding: utf-8 -*-\n\"\"\"Voice channel router.\n\nExports ``voice_router`` with Twilio-facing endpoints mounted at the app root:\n``/voice/incoming``, ``/voice/ws``, ``/voice/status-callback``.\n\"\"\"\nfrom __future__ import annotations\n\nimport logging\n\nfrom fastapi import (\n    APIRouter,\n    Depends,\n    Request,\n    Response,\n    WebSocket,\n    WebSocketDisconnect,\n)\n\nlogger = logging.getLogger(__name__)\n\n# ---------------------------------------------------------------------------\n# Twilio-facing router (mounted at root level)\n# ---------------------------------------------------------------------------\nvoice_router = APIRouter(tags=[\"voice\"])\n\n\ndef _get_voice_channel(request_or_ws):\n    \"\"\"Retrieve the VoiceChannel from app state, or None.\"\"\"\n    app = getattr(request_or_ws, \"app\", None)\n    if not app:\n        return None\n    cm = getattr(app.state, \"channel_manager\", None)\n    if not cm:\n        return None\n    for ch in cm.channels:\n        if ch.channel == \"voice\":\n            return ch\n    return None\n\n\nasync def _validate_twilio_signature(request: Request) -> None:\n    \"\"\"Validate that the request originated from Twilio.\n\n    Uses Twilio's ``RequestValidator`` to verify the\n    ``X-Twilio-Signature`` header.  If the voice channel has no\n    auth token configured the check is skipped (dev mode).\n    \"\"\"\n    voice_ch = _get_voice_channel(request)\n    if not voice_ch:\n        return\n\n    auth_token = getattr(voice_ch.config, \"twilio_auth_token\", \"\")\n    if not auth_token:\n        # No token configured -- skip validation (local dev)\n        return\n\n    signature = request.headers.get(\"X-Twilio-Signature\", \"\")\n    if not signature:\n        from fastapi import HTTPException\n\n        raise HTTPException(status_code=403, detail=\"Missing Twilio signature\")\n\n    from twilio.request_validator import RequestValidator\n\n    validator = RequestValidator(auth_token)\n    form = await request.form()\n    # Behind a tunnel/reverse-proxy, request.url has the internal scheme\n    # and host.  Reconstruct the public URL that Twilio actually signed\n    # using forwarded headers so signature validation succeeds.\n    proto = request.headers.get(\"x-forwarded-proto\", request.url.scheme)\n    host = request.headers.get(\"x-forwarded-host\", request.url.netloc)\n    url = f\"{proto}://{host}{request.url.path}\"\n    if request.url.query:\n        url = f\"{url}?{request.url.query}\"\n    params = {k: str(v) for k, v in form.items()}\n\n    if not validator.validate(url, params, signature):\n        from fastapi import HTTPException\n\n        raise HTTPException(status_code=403, detail=\"Invalid Twilio signature\")\n\n\n@voice_router.post(\n    \"/voice/incoming\",\n    dependencies=[Depends(_validate_twilio_signature)],\n)\nasync def voice_incoming(request: Request) -> Response:\n    \"\"\"Twilio webhook: return TwiML for an incoming call.\"\"\"\n    from ..channels.voice.twiml import (\n        build_conversation_relay_twiml,\n        build_error_twiml,\n    )\n\n    voice_ch = _get_voice_channel(request)\n    if not voice_ch:\n        twiml = build_error_twiml(\"Voice channel is not available.\")\n        return Response(content=twiml, media_type=\"application/xml\")\n\n    config = voice_ch.config\n\n    # Build the WebSocket URL for ConversationRelay\n    wss_url = voice_ch.get_tunnel_wss_url()\n    if not wss_url:\n        twiml = build_error_twiml(\"Tunnel not available. Please try later.\")\n        return Response(content=twiml, media_type=\"application/xml\")\n\n    token = voice_ch.create_ws_token()\n    ws_url = f\"{wss_url}/voice/ws?token={token}\"\n    twiml = build_conversation_relay_twiml(\n        ws_url,\n        welcome_greeting=getattr(\n            config,\n            \"welcome_greeting\",\n            \"Hi! This is CoPaw. How can I help you?\",\n        ),\n        tts_provider=getattr(config, \"tts_provider\", \"google\"),\n        tts_voice=getattr(config, \"tts_voice\", \"en-US-Journey-D\"),\n        stt_provider=getattr(config, \"stt_provider\", \"deepgram\"),\n        language=getattr(config, \"language\", \"en-US\"),\n    )\n    return Response(content=twiml, media_type=\"application/xml\")\n\n\n@voice_router.websocket(\"/voice/ws\")\nasync def voice_ws(websocket: WebSocket) -> None:\n    \"\"\"ConversationRelay WebSocket endpoint.\n\n    Each connection must present a single-use token (query param) that\n    was generated by ``/voice/incoming`` and embedded in the TwiML.\n    \"\"\"\n    from ..channels.voice.conversation_relay import ConversationRelayHandler\n\n    voice_ch = _get_voice_channel(websocket)\n    if not voice_ch:\n        await websocket.close(code=1008, reason=\"Voice channel not available\")\n        return\n\n    # Validate single-use token before accepting the connection.\n    token = websocket.query_params.get(\"token\", \"\")\n    if not token or not voice_ch.validate_ws_token(token):\n        logger.warning(\"WS connection rejected: invalid or missing token\")\n        await websocket.close(code=1008, reason=\"Invalid token\")\n        return\n\n    await websocket.accept()\n\n    handler = ConversationRelayHandler(\n        ws=websocket,\n        process=voice_ch.process,\n        session_mgr=voice_ch.session_mgr,\n        channel_type=voice_ch.channel,\n    )\n    try:\n        await handler.handle()\n    except WebSocketDisconnect:\n        logger.info(\"Voice WS disconnected: call_sid=%s\", handler.call_sid)\n    finally:\n        if handler.call_sid:\n            voice_ch.session_mgr.end_session(handler.call_sid)\n\n\n@voice_router.post(\n    \"/voice/status-callback\",\n    dependencies=[Depends(_validate_twilio_signature)],\n)\nasync def voice_status_callback(request: Request) -> Response:\n    \"\"\"Twilio call status change webhook.\"\"\"\n    form = await request.form()\n    call_sid = form.get(\"CallSid\", \"\")\n    call_status = form.get(\"CallStatus\", \"\")\n    logger.info(\n        \"Call status callback: call_sid=%s status=%s\",\n        call_sid,\n        call_status,\n    )\n\n    if call_status in (\"completed\", \"busy\", \"no-answer\", \"canceled\", \"failed\"):\n        voice_ch = _get_voice_channel(request)\n        if voice_ch:\n            voice_ch.session_mgr.end_session(str(call_sid))\n\n    return Response(content=\"\", status_code=204)\n"
  },
  {
    "path": "src/copaw/app/routers/workspace.py",
    "content": "# -*- coding: utf-8 -*-\n\"\"\"Workspace API – download / upload the entire WORKING_DIR as a zip.\"\"\"\n\nfrom __future__ import annotations\n\nimport asyncio\nimport io\nimport shutil\nimport tempfile\nimport zipfile\nfrom datetime import datetime, timezone\nfrom pathlib import Path\n\nfrom fastapi import APIRouter, HTTPException, UploadFile, File, Request\nfrom fastapi.responses import StreamingResponse\n\n\nrouter = APIRouter(prefix=\"/workspace\", tags=[\"workspace\"])\n\n\ndef _dir_stats(root: Path) -> tuple[int, int]:\n    \"\"\"Return (file_count, total_size) for *root* recursively.\"\"\"\n    count = 0\n    size = 0\n    if root.is_dir():\n        for p in root.rglob(\"*\"):\n            if p.is_file():\n                count += 1\n                size += p.stat().st_size\n    return count, size\n\n\ndef _zip_directory(root: Path) -> io.BytesIO:\n    \"\"\"Create an in-memory zip archive of *root* and return the buffer.\n\n    All files **and** directories (including empty ones) are included.\n    \"\"\"\n    buf = io.BytesIO()\n    with zipfile.ZipFile(buf, \"w\", zipfile.ZIP_DEFLATED) as zf:\n        for entry in sorted(root.rglob(\"*\")):\n            arcname = entry.relative_to(root).as_posix()\n            if entry.is_file():\n                zf.write(entry, arcname)\n            elif entry.is_dir():\n                # Zip spec: directory entries end with '/'\n                zf.write(entry, arcname + \"/\")\n    buf.seek(0)\n    return buf\n\n\n# ---------------------------------------------------------------------------\n# Helpers\n# ---------------------------------------------------------------------------\n\n\ndef _validate_zip_data(data: bytes, workspace_dir: Path) -> None:\n    \"\"\"Ensure *data* is a valid zip without path-traversal entries.\"\"\"\n    if not zipfile.is_zipfile(io.BytesIO(data)):\n        raise HTTPException(\n            status_code=400,\n            detail=\"Uploaded file is not a valid zip archive\",\n        )\n    with zipfile.ZipFile(io.BytesIO(data)) as zf:\n        for name in zf.namelist():\n            resolved = (workspace_dir / name).resolve()\n            if not str(resolved).startswith(str(workspace_dir)):\n                raise HTTPException(\n                    status_code=400,\n                    detail=f\"Zip contains unsafe path: {name}\",\n                )\n\n\ndef _extract_and_merge_zip(data: bytes, workspace_dir: Path) -> None:\n    \"\"\"Extract zip data and merge into workspace_dir (blocking operation).\"\"\"\n    tmp_dir = None\n    try:\n        tmp_dir = Path(tempfile.mkdtemp(prefix=\"copaw_upload_\"))\n        with zipfile.ZipFile(io.BytesIO(data)) as zf:\n            zf.extractall(tmp_dir)\n\n        top_entries = list(tmp_dir.iterdir())\n        extract_root = tmp_dir\n        if len(top_entries) == 1 and top_entries[0].is_dir():\n            extract_root = top_entries[0]\n\n        workspace_dir.mkdir(parents=True, exist_ok=True)\n\n        for item in extract_root.iterdir():\n            dest = workspace_dir / item.name\n            if item.is_file():\n                shutil.copy2(item, dest)\n            else:\n                if dest.exists() and dest.is_file():\n                    dest.unlink()\n                shutil.copytree(item, dest, dirs_exist_ok=True)\n    finally:\n        if tmp_dir and tmp_dir.is_dir():\n            shutil.rmtree(tmp_dir, ignore_errors=True)\n\n\ndef _validate_and_extract_zip(data: bytes, workspace_dir: Path) -> None:\n    \"\"\"Validate and extract zip data (blocking operation).\"\"\"\n    _validate_zip_data(data, workspace_dir)\n    _extract_and_merge_zip(data, workspace_dir)\n\n\n# ---------------------------------------------------------------------------\n# Endpoints\n# ---------------------------------------------------------------------------\n\n\n@router.get(\n    \"/download\",\n    summary=\"Download workspace as zip\",\n    description=(\n        \"Package the entire agent workspace into a zip archive and stream \"\n        \"it back as a downloadable file.\"\n    ),\n    responses={\n        200: {\n            \"content\": {\"application/zip\": {}},\n            \"description\": \"Zip archive of agent workspace\",\n        },\n    },\n)\nasync def download_workspace(request: Request):\n    \"\"\"Stream agent workspace as a zip file.\"\"\"\n    from ..agent_context import get_agent_for_request\n\n    agent = await get_agent_for_request(request)\n    workspace_dir = agent.workspace_dir\n\n    if not workspace_dir.is_dir():\n        raise HTTPException(\n            status_code=404,\n            detail=f\"Workspace does not exist: {workspace_dir}\",\n        )\n\n    buf = await asyncio.to_thread(_zip_directory, workspace_dir)\n\n    timestamp = datetime.now(timezone.utc).strftime(\"%Y%m%d_%H%M%S\")\n    filename = f\"copaw_workspace_{agent.agent_id}_{timestamp}.zip\"\n\n    return StreamingResponse(\n        buf,\n        media_type=\"application/zip\",\n        headers={\n            \"Content-Disposition\": f'attachment; filename=\"{filename}\"',\n        },\n    )\n\n\n@router.post(\n    \"/upload\",\n    response_model=dict,\n    summary=\"Upload zip and merge into workspace\",\n    description=(\n        \"Upload a zip archive.  Paths present in the zip are merged into \"\n        \"agent workspace (files overwritten, dirs merged).  Paths not in \"\n        \"the zip are left unchanged (e.g. copaw.db, runtime dirs). \"\n        \"Download packs the entire workspace; upload only \"\n        \"overwrites/merges zip contents.\"\n    ),\n)\nasync def upload_workspace(\n    request: Request,\n    file: UploadFile = File(\n        ...,\n        description=\"Zip archive to merge into agent workspace\",\n    ),\n) -> dict:\n    \"\"\"\n    Merge uploaded zip contents into agent workspace (overwrite, not clear).\n    \"\"\"\n    from ..agent_context import get_agent_for_request\n\n    if file.content_type and file.content_type not in (\n        \"application/zip\",\n        \"application/x-zip-compressed\",\n        \"application/octet-stream\",\n    ):\n        raise HTTPException(\n            status_code=400,\n            detail=(\n                f\"Expected a zip file, got content-type: {file.content_type}\"\n            ),\n        )\n\n    agent = await get_agent_for_request(request)\n    workspace_dir = agent.workspace_dir\n    data = await file.read()\n\n    try:\n        await asyncio.to_thread(_validate_and_extract_zip, data, workspace_dir)\n        return {\"success\": True}\n    except HTTPException:\n        raise\n    except Exception as exc:\n        raise HTTPException(\n            status_code=500,\n            detail=f\"Failed to merge workspace: {exc}\",\n        ) from exc\n"
  },
  {
    "path": "src/copaw/app/runner/__init__.py",
    "content": "# -*- coding: utf-8 -*-\n\"\"\"Runner module with chat manager for coordinating repository.\"\"\"\nfrom .runner import AgentRunner\nfrom .api import router\nfrom .manager import ChatManager\nfrom .models import (\n    ChatSpec,\n    ChatHistory,\n    ChatsFile,\n)\nfrom .repo import (\n    BaseChatRepository,\n    JsonChatRepository,\n)\n\n\n__all__ = [\n    # Core classes\n    \"AgentRunner\",\n    \"ChatManager\",\n    # API\n    \"router\",\n    # Models\n    \"ChatSpec\",\n    \"ChatHistory\",\n    \"ChatsFile\",\n    # Chat Repository\n    \"BaseChatRepository\",\n    \"JsonChatRepository\",\n]\n"
  },
  {
    "path": "src/copaw/app/runner/api.py",
    "content": "# -*- coding: utf-8 -*-\n\"\"\"Chat management API.\"\"\"\nfrom __future__ import annotations\nfrom typing import Optional\nfrom uuid import uuid4\nfrom fastapi import APIRouter, Depends, HTTPException, Query, Request\nfrom agentscope.memory import InMemoryMemory\n\nfrom .session import SafeJSONSession\nfrom .manager import ChatManager\nfrom .models import (\n    ChatSpec,\n    ChatHistory,\n)\nfrom .utils import agentscope_msg_to_message\n\n\nrouter = APIRouter(prefix=\"/chats\", tags=[\"chats\"])\n\n\nasync def get_workspace(request: Request):\n    \"\"\"Get the workspace for the active agent.\"\"\"\n    from ..agent_context import get_agent_for_request\n\n    return await get_agent_for_request(request)\n\n\nasync def get_chat_manager(\n    request: Request,\n) -> ChatManager:\n    \"\"\"Get the chat manager for the active agent.\n\n    Args:\n        request: FastAPI request object\n\n    Returns:\n        ChatManager instance for the specified agent\n\n    Raises:\n        HTTPException: If manager is not initialized\n    \"\"\"\n    workspace = await get_workspace(request)\n    return workspace.chat_manager\n\n\nasync def get_session(\n    request: Request,\n) -> SafeJSONSession:\n    \"\"\"Get the session for the active agent.\n\n    Args:\n        request: FastAPI request object\n\n    Returns:\n        SafeJSONSession instance for the specified agent\n\n    Raises:\n        HTTPException: If session is not initialized\n    \"\"\"\n    workspace = await get_workspace(request)\n    return workspace.runner.session\n\n\n@router.get(\"\", response_model=list[ChatSpec])\nasync def list_chats(\n    user_id: Optional[str] = Query(None, description=\"Filter by user ID\"),\n    channel: Optional[str] = Query(None, description=\"Filter by channel\"),\n    mgr: ChatManager = Depends(get_chat_manager),\n    workspace=Depends(get_workspace),\n):\n    \"\"\"List all chats with optional filters.\n\n    Args:\n        user_id: Optional user ID to filter chats\n        channel: Optional channel name to filter chats\n        mgr: Chat manager dependency\n    \"\"\"\n    chats = await mgr.list_chats(user_id=user_id, channel=channel)\n    tracker = workspace.task_tracker\n    result = []\n    for spec in chats:\n        status = await tracker.get_status(spec.id)\n        result.append(spec.model_copy(update={\"status\": status}))\n    return result\n\n\n@router.post(\"\", response_model=ChatSpec)\nasync def create_chat(\n    request: ChatSpec,\n    mgr: ChatManager = Depends(get_chat_manager),\n):\n    \"\"\"Create a new chat.\n\n    Server generates chat_id (UUID) automatically.\n\n    Args:\n        request: Chat creation request\n        mgr: Chat manager dependency\n\n    Returns:\n        Created chat spec with UUID\n    \"\"\"\n    chat_id = str(uuid4())\n    spec = ChatSpec(\n        id=chat_id,\n        name=request.name,\n        session_id=request.session_id,\n        user_id=request.user_id,\n        channel=request.channel,\n        meta=request.meta,\n    )\n    return await mgr.create_chat(spec)\n\n\n@router.post(\"/batch-delete\", response_model=dict)\nasync def batch_delete_chats(\n    chat_ids: list[str],\n    mgr: ChatManager = Depends(get_chat_manager),\n):\n    \"\"\"Delete chats by chat IDs.\n\n    Args:\n        chat_ids: List of chat IDs\n        mgr: Chat manager dependency\n    Returns:\n        True if deleted, False if failed\n\n    \"\"\"\n    deleted = await mgr.delete_chats(chat_ids=chat_ids)\n    return {\"deleted\": deleted}\n\n\n@router.get(\"/{chat_id}\", response_model=ChatHistory)\nasync def get_chat(\n    chat_id: str,\n    mgr: ChatManager = Depends(get_chat_manager),\n    session: SafeJSONSession = Depends(get_session),\n    workspace=Depends(get_workspace),\n):\n    \"\"\"Get detailed information about a specific chat by UUID.\n\n    Args:\n        request: FastAPI request (for agent context)\n        chat_id: Chat UUID\n        mgr: Chat manager dependency\n        session: SafeJSONSession dependency\n\n    Returns:\n        ChatHistory with messages and status (idle/running)\n\n    Raises:\n        HTTPException: If chat not found (404)\n    \"\"\"\n    chat_spec = await mgr.get_chat(chat_id)\n    if not chat_spec:\n        raise HTTPException(\n            status_code=404,\n            detail=f\"Chat not found: {chat_id}\",\n        )\n\n    state = await session.get_session_state_dict(\n        chat_spec.session_id,\n        chat_spec.user_id,\n    )\n    status = await workspace.task_tracker.get_status(chat_id)\n    if not state:\n        return ChatHistory(messages=[], status=status)\n    memories = state.get(\"agent\", {}).get(\"memory\", [])\n    memory = InMemoryMemory()\n    memory.load_state_dict(memories)\n\n    memories = await memory.get_memory()\n    messages = agentscope_msg_to_message(memories)\n    return ChatHistory(messages=messages, status=status)\n\n\n@router.put(\"/{chat_id}\", response_model=ChatSpec)\nasync def update_chat(\n    chat_id: str,\n    spec: ChatSpec,\n    mgr: ChatManager = Depends(get_chat_manager),\n):\n    \"\"\"Update an existing chat.\n\n    Args:\n        chat_id: Chat UUID\n        spec: Updated chat specification\n        mgr: Chat manager dependency\n\n    Returns:\n        Updated chat spec\n\n    Raises:\n        HTTPException: If chat_id mismatch (400) or not found (404)\n    \"\"\"\n    if spec.id != chat_id:\n        raise HTTPException(\n            status_code=400,\n            detail=\"chat_id mismatch\",\n        )\n\n    # Check if exists\n    existing = await mgr.get_chat(chat_id)\n    if not existing:\n        raise HTTPException(\n            status_code=404,\n            detail=f\"Chat not found: {chat_id}\",\n        )\n\n    updated = await mgr.update_chat(spec)\n    return updated\n\n\n@router.delete(\"/{chat_id}\", response_model=dict)\nasync def delete_chat(\n    chat_id: str,\n    mgr: ChatManager = Depends(get_chat_manager),\n):\n    \"\"\"Delete a chat by UUID.\n\n    Note: This only deletes the chat spec (UUID mapping).\n    JSONSession state is NOT deleted.\n\n    Args:\n        chat_id: Chat UUID\n        mgr: Chat manager dependency\n\n    Returns:\n        True if deleted, False if failed\n\n    Raises:\n        HTTPException: If chat not found (404)\n    \"\"\"\n    deleted = await mgr.delete_chats(chat_ids=[chat_id])\n    if not deleted:\n        raise HTTPException(\n            status_code=404,\n            detail=f\"Chat not found: {chat_id}\",\n        )\n    return {\"deleted\": True}\n"
  },
  {
    "path": "src/copaw/app/runner/command_dispatch.py",
    "content": "# -*- coding: utf-8 -*-\n\"\"\"Command dispatch: run command path without creating CoPawAgent.\n\nYields (Msg, last) compatible with query_handler stream.\n\"\"\"\nfrom __future__ import annotations\n\nimport logging\nfrom typing import AsyncIterator\nfrom typing import TYPE_CHECKING\n\nfrom agentscope.message import Msg, TextBlock\n\nfrom .daemon_commands import (\n    DaemonContext,\n    DaemonCommandHandlerMixin,\n    parse_daemon_query,\n)\nfrom ...agents.command_handler import CommandHandler\nfrom ...config.config import load_agent_config\n\nlogger = logging.getLogger(__name__)\n\nif TYPE_CHECKING:\n    from .runner import AgentRunner\n\n\ndef _get_last_user_text(msgs) -> str | None:\n    \"\"\"Extract last user message text from msgs (runtime message list).\"\"\"\n    if not msgs or len(msgs) == 0:\n        return None\n    last = msgs[-1]\n    if hasattr(last, \"get_text_content\"):\n        return last.get_text_content()\n    if isinstance(last, dict):\n        content = last.get(\"content\") or last.get(\"text\")\n        if isinstance(content, str):\n            return content\n        if isinstance(content, list):\n            for block in content:\n                if isinstance(block, dict) and block.get(\"type\") == \"text\":\n                    return block.get(\"text\")\n    return None\n\n\ndef _is_conversation_command(query: str | None) -> bool:\n    \"\"\"True if query is a conversation command (/compact, /new, etc.).\"\"\"\n    if not query or not query.startswith(\"/\"):\n        return False\n    cmd = query.strip().lstrip(\"/\").split()[0] if query.strip() else \"\"\n    return cmd in CommandHandler.SYSTEM_COMMANDS\n\n\ndef _is_command(query: str | None) -> bool:\n    \"\"\"True if query is any known command (daemon or conversation).\"\"\"\n    if not query or not query.startswith(\"/\"):\n        return False\n    if parse_daemon_query(query) is not None:\n        return True\n    return _is_conversation_command(query)\n\n\nasync def run_command_path(\n    request,\n    msgs,\n    runner: AgentRunner,\n) -> AsyncIterator[tuple]:\n    \"\"\"Run command path and yield (msg, last) for each response.\n\n    Args:\n        request: AgentRequest (session_id, user_id, etc.)\n        msgs: List of messages from runtime (last is user input)\n        runner: AgentRunner (session, memory_manager, etc.)\n\n    Yields:\n        (Msg, bool) compatible with query_handler stream\n    \"\"\"\n    query = _get_last_user_text(msgs)\n    if not query:\n        return\n\n    session_id = getattr(request, \"session_id\", \"\") or \"\"\n    user_id = getattr(request, \"user_id\", \"\") or \"\"\n\n    # Daemon path\n    parsed = parse_daemon_query(query)\n    if parsed is not None:\n        handler = DaemonCommandHandlerMixin()\n        manager = getattr(runner, \"_manager\", None)\n        if parsed[0] == \"restart\":\n            logger.info(\n                \"run_command_path: daemon restart, manager=%s\",\n                \"set\" if manager is not None else \"None\",\n            )\n            # Yield hint first so user sees it before restart runs.\n            hint = Msg(\n                name=\"Friday\",\n                role=\"assistant\",\n                content=[\n                    TextBlock(\n                        type=\"text\",\n                        text=(\n                            \"**Restart in progress**\\n\\n\"\n                            \"- Reloading agent with zero-downtime. \"\n                            \"Please wait.\"\n                        ),\n                    ),\n                ],\n            )\n            yield hint, True\n\n        agent_id = runner.agent_id\n        context = DaemonContext(\n            load_config_fn=lambda: load_agent_config(agent_id),\n            memory_manager=runner.memory_manager,\n            manager=manager,\n            agent_id=agent_id,\n            session_id=session_id,\n        )\n        msg = await handler.handle_daemon_command(query, context)\n        yield msg, True\n        logger.info(\"handle_daemon_command %s completed\", query)\n        return\n\n    # Conversation path: lightweight memory + CommandHandler\n    memory = runner.memory_manager.get_in_memory_memory()\n    session_state = await runner.session.get_session_state_dict(\n        session_id=session_id,\n        user_id=user_id,\n    )\n    memory_state = session_state.get(\"agent\", {}).get(\"memory\", {})\n    memory.load_state_dict(memory_state, strict=False)\n\n    conv_handler = CommandHandler(\n        agent_name=\"Friday\",\n        memory=memory,\n        memory_manager=runner.memory_manager,\n        enable_memory_manager=runner.memory_manager is not None,\n    )\n    try:\n        response_msg = await conv_handler.handle_conversation_command(query)\n    except RuntimeError as e:\n        response_msg = Msg(\n            name=\"Friday\",\n            role=\"assistant\",\n            content=[TextBlock(type=\"text\", text=str(e))],\n        )\n    yield response_msg, True\n\n    # Update memory key with session_id & user_id to session,\n    # but only if identifiers are present\n    if session_id and user_id:\n        await runner.session.update_session_state(\n            session_id=session_id,\n            key=\"agent.memory\",\n            value=memory.state_dict(),\n            user_id=user_id,\n        )\n    else:\n        logger.warning(\n            \"Skipping session_state update for conversation\"\n            \" memory due to missing session_id or user_id (session_id=%r, \"\n            \"user_id=%r)\",\n            session_id,\n            user_id,\n        )\n"
  },
  {
    "path": "src/copaw/app/runner/daemon_commands.py",
    "content": "# -*- coding: utf-8 -*-\n\"\"\"Daemon command execution layer and DaemonCommandHandlerMixin.\n\nShared by in-chat /daemon  and CLI `copaw daemon `.\nLogs: tail WORKING_DIR / \"copaw.log\". Restart: in-process reload of channels,\ncron and MCP (no process exit); works on Mac/Windows without a process manager.\n\"\"\"\n# pylint: disable=too-many-return-statements\nfrom __future__ import annotations\n\nimport logging\nfrom dataclasses import dataclass\nfrom pathlib import Path\nfrom typing import Any, Callable, Optional, TYPE_CHECKING\n\nfrom agentscope.message import Msg, TextBlock\n\nfrom ...constant import WORKING_DIR\nfrom ...config import load_config\n\nif TYPE_CHECKING:\n    from ...config.config import AgentProfileConfig\n    from ..multi_agent_manager import MultiAgentManager\n\nlogger = logging.getLogger(__name__)\n\n\nclass RestartInProgressError(Exception):\n    \"\"\"Raised when /daemon restart is invoked while another restart runs.\"\"\"\n\n\nDAEMON_PREFIX = \"/daemon\"\nDAEMON_SUBCOMMANDS = frozenset(\n    {\"status\", \"restart\", \"reload-config\", \"version\", \"logs\", \"approve\"},\n)\n# Short names: /restart -> /daemon restart, etc.\nDAEMON_SHORT_ALIASES = {\n    \"restart\": \"restart\",\n    \"status\": \"status\",\n    \"reload-config\": \"reload-config\",\n    \"reload_config\": \"reload-config\",\n    \"version\": \"version\",\n    \"logs\": \"logs\",\n    \"approve\": \"approve\",\n}\n\n\n@dataclass\nclass DaemonContext:\n    \"\"\"Context for daemon commands (inject deps from runner or CLI).\"\"\"\n\n    working_dir: Path = WORKING_DIR\n    load_config_fn: Callable[[], Any] = load_config\n    memory_manager: Optional[Any] = None\n    # For /daemon restart: manager and agent_id for zero-downtime reload\n    manager: Optional[\"MultiAgentManager\"] = None\n    agent_id: Optional[str] = None\n    # Session ID for approval commands.\n    session_id: str = \"\"\n\n\ndef _get_last_lines(\n    path: Path,\n    lines: int = 100,\n    max_bytes: int = 512 * 1024,\n) -> str:\n    \"\"\"Read last N lines from a text file (tail) with bounded memory.\n\n    Reads at most max_bytes from the end of the file so large logs\n    do not cause high memory usage or latency.\n    \"\"\"\n    path = Path(path)\n    if not path.exists() or not path.is_file():\n        return f\"(Log file not found: {path})\"\n    try:\n        size = path.stat().st_size\n        if size == 0:\n            return \"(empty)\"\n        with open(path, \"rb\") as f:\n            if size <= max_bytes:\n                content = f.read().decode(\"utf-8\", errors=\"replace\")\n            else:\n                f.seek(size - max_bytes)\n                content = f.read().decode(\"utf-8\", errors=\"replace\")\n                first_nl = content.find(\"\\n\")\n                if first_nl != -1:\n                    content = content[first_nl + 1 :]\n                else:\n                    content = \"\"\n        all_lines = content.splitlines()\n        last = all_lines[-lines:] if len(all_lines) > lines else all_lines\n        return \"\\n\".join(last) if last else \"(empty)\"\n    except OSError as e:\n        return f\"(Error reading log: {e})\"\n\n\ndef run_daemon_status(context: DaemonContext) -> str:\n    \"\"\"Return status text (health, config, memory_manager).\"\"\"\n    parts = [\"**Daemon Status**\", \"\"]\n    try:\n        cfg = context.load_config_fn()\n        parts.append(\"- Config loaded: yes\")\n        # Support both AgentProfileConfig (has 'running' directly)\n        # and Config (has 'agents.running')\n        if hasattr(cfg, \"running\"):\n            max_in = getattr(cfg.running, \"max_input_length\", \"N/A\")\n            parts.append(f\"- Max input length: {max_in}\")\n        elif getattr(cfg, \"agents\", None) and getattr(\n            cfg.agents,\n            \"running\",\n            None,\n        ):\n            max_in = getattr(cfg.agents.running, \"max_input_length\", \"N/A\")\n            parts.append(f\"- Max input length: {max_in}\")\n    except Exception as e:\n        parts.append(f\"- Config loaded: no ({e})\")\n\n    parts.append(f\"- Working dir: {context.working_dir}\")\n    if context.memory_manager is not None:\n        parts.append(\"- Memory manager: running\")\n    else:\n        parts.append(\"- Memory manager: not attached\")\n    return \"\\n\".join(parts)\n\n\nasync def run_daemon_restart(context: DaemonContext) -> str:\n    \"\"\"Trigger zero-downtime agent reload or instruct user.\"\"\"\n    if context.manager is not None and context.agent_id is not None:\n        try:\n            success = await context.manager.reload_agent(context.agent_id)\n            if success:\n                return (\n                    \"**Restart completed**\\n\\n\"\n                    \"- Agent reloaded with zero-downtime \"\n                    \"(channels, cron, MCP).\"\n                )\n            else:\n                return (\n                    \"**Restart skipped**\\n\\n\"\n                    \"- Agent not currently loaded. \"\n                    \"Will reload on next request.\"\n                )\n        except Exception as e:\n            return f\"**Restart failed**\\n\\n- {e}\"\n    return (\n        \"**Restart**\\n\\n\"\n        \"- Not running inside app. \"\n        \"Run the app (e.g. `copaw app`) and use /daemon restart in chat, \"\n        \"or restart the process with systemd/supervisor/docker.\"\n    )\n\n\ndef run_daemon_reload_config(context: DaemonContext) -> str:\n    \"\"\"Reload config (re-call load_config); no process restart.\"\"\"\n    try:\n        context.load_config_fn()\n        return (\n            \"**Config reloaded**\\n\\n- load_config() re-invoked successfully.\"\n        )\n    except Exception as e:\n        return f\"**Reload failed**\\n\\n- {e}\"\n\n\ndef run_daemon_version(context: DaemonContext) -> str:\n    \"\"\"Return version and paths.\"\"\"\n    try:\n        from ...__version__ import __version__ as ver\n    except ImportError:\n        ver = \"unknown\"\n    return (\n        f\"**Daemon version**\\n\\n\"\n        f\"- Version: {ver}\\n\"\n        f\"- Working dir: {context.working_dir}\\n\"\n        f\"- Log file: {context.working_dir / 'copaw.log'}\"\n    )\n\n\ndef run_daemon_logs(context: DaemonContext, lines: int = 100) -> str:\n    \"\"\"Tail last N lines from WORKING_DIR / copaw.log.\"\"\"\n    log_path = context.working_dir / \"copaw.log\"\n    content = _get_last_lines(log_path, lines=lines)\n    return f\"**Console log (last {lines} lines)**\\n\\n```\\n{content}\\n```\"\n\n\nasync def run_daemon_approve(\n    _context: DaemonContext,\n    session_id: str = \"\",\n) -> str:\n    \"\"\"Resolve the pending tool-guard approval for *session_id*.\n\n    Called when the user sends ``/daemon approve`` in the chat while a\n    tool-guard approval is pending.  The runner intercepts the message\n    before it reaches this function in most cases, but this serves as\n    a fallback and returns a helpful message when no approval is\n    pending.\n    \"\"\"\n    try:\n        from ..approvals import get_approval_service\n        from ...security.tool_guard.approval import ApprovalDecision\n\n        svc = get_approval_service()\n        pending = await svc.get_pending_by_session(session_id)\n        if pending is None:\n            return (\n                \"**No pending approval**\\n\\n\"\n                \"- There is no tool-guard approval waiting for this \"\n                \"session.\\n\"\n                \"- This command is only valid when a sensitive tool \"\n                \"call is awaiting your review.\"\n            )\n        await svc.resolve_request(\n            pending.request_id,\n            ApprovalDecision.APPROVED,\n        )\n        return (\n            f\"**Tool execution approved** ✅\\n\\n\"\n            f\"- Tool: `{pending.tool_name}`\\n\"\n            f\"- Request: `{pending.request_id[:8]}…`\"\n        )\n    except Exception as exc:\n        logger.warning(\"run_daemon_approve error: %s\", exc, exc_info=True)\n        return f\"**Approve failed**\\n\\n- {exc}\"\n\n\ndef parse_daemon_query(query: str) -> Optional[tuple[str, list[str]]]:\n    \"\"\"Parse /daemon  or /. Return (subcommand, args) or None.\"\"\"\n    if not query or not isinstance(query, str):\n        return None\n    raw = query.strip()\n    if not raw.startswith(\"/\"):\n        return None\n    rest = raw.lstrip(\"/\").strip()\n    if not rest:\n        return None\n    parts = rest.split()\n    first = parts[0].lower() if parts else \"\"\n\n    if first == \"daemon\":\n        if len(parts) < 2:\n            return (\"status\", [])\n        sub = parts[1].lower().replace(\"_\", \"-\")\n        if sub not in DAEMON_SUBCOMMANDS and \"reload\" in sub:\n            sub = \"reload-config\"\n        if sub not in DAEMON_SUBCOMMANDS:\n            return None\n        args = parts[2:] if len(parts) > 2 else []\n        return (sub, args)\n    if first in DAEMON_SHORT_ALIASES:\n        sub = DAEMON_SHORT_ALIASES[first]\n        return (sub, parts[1:] if len(parts) > 1 else [])\n    return None\n\n\nclass DaemonCommandHandlerMixin:\n    \"\"\"Mixin for daemon commands: /daemon status, restart, logs, etc.\"\"\"\n\n    def is_daemon_command(self, query: str | None) -> bool:\n        \"\"\"True if query is /daemon  or short name (/restart, etc.).\"\"\"\n        return parse_daemon_query(query or \"\") is not None\n\n    async def handle_daemon_command(\n        self,\n        query: str,\n        context: DaemonContext,\n    ) -> Msg:\n        \"\"\"Run daemon subcommand; return a single assistant Msg.\"\"\"\n        parsed = parse_daemon_query(query)\n        if not parsed:\n            return Msg(\n                name=\"Friday\",\n                role=\"assistant\",\n                content=[\n                    TextBlock(type=\"text\", text=\"Unknown daemon command.\"),\n                ],\n            )\n        sub, args = parsed\n        if sub == \"status\":\n            text = run_daemon_status(context)\n        elif sub == \"restart\":\n            text = await run_daemon_restart(context)\n        elif sub == \"reload-config\":\n            text = run_daemon_reload_config(context)\n        elif sub == \"version\":\n            text = run_daemon_version(context)\n        elif sub == \"logs\":\n            n = 100\n            for a in args:\n                if a.isdigit():\n                    n = max(1, min(int(a), 2000))\n                    break\n            text = run_daemon_logs(context, lines=n)\n        elif sub == \"approve\":\n            session_id = getattr(context, \"session_id\", \"\") or \"\"\n            text = await run_daemon_approve(context, session_id=session_id)\n        else:\n            text = \"Unknown daemon subcommand.\"\n        logger.info(\"handle_daemon_command %s completed\", query)\n        return Msg(\n            name=\"Friday\",\n            role=\"assistant\",\n            content=[TextBlock(type=\"text\", text=text)],\n        )\n"
  },
  {
    "path": "src/copaw/app/runner/manager.py",
    "content": "# -*- coding: utf-8 -*-\n\"\"\"Chat manager for managing chat specifications.\"\"\"\nfrom __future__ import annotations\n\nimport asyncio\nimport logging\nfrom datetime import datetime, timezone\nfrom typing import Optional\n\nfrom .models import ChatSpec\nfrom .repo import BaseChatRepository\nfrom ..channels.schema import DEFAULT_CHANNEL\n\nlogger = logging.getLogger(__name__)\n\n\nclass ChatManager:\n    \"\"\"Manages chat specifications in repository.\n\n    Only handles ChatSpec CRUD operations.\n    Does NOT manage Redis session state - that's handled by runner's session.\n\n    Similar to CronManager's role in crons module.\n    \"\"\"\n\n    def __init__(\n        self,\n        *,\n        repo: BaseChatRepository,\n    ):\n        \"\"\"Initialize chat manager.\n\n        Args:\n            repo: Chat spec repository for persistence\n        \"\"\"\n        self._repo = repo\n        self._lock = asyncio.Lock()\n        logger.info(\n            f\"ChatManager created with repo path: {repo.path}\",\n        )\n\n    # ----- Read Operations -----\n\n    async def list_chats(\n        self,\n        user_id: Optional[str] = None,\n        channel: Optional[str] = None,\n    ) -> list[ChatSpec]:\n        \"\"\"List chat specs with optional filters.\n\n        Args:\n            user_id: Optional user ID filter\n            channel: Optional channel filter\n\n        Returns:\n            List of chat specifications\n        \"\"\"\n        async with self._lock:\n            logger.debug(\n                f\"list_chats: repo path={self._repo.path}, \"\n                f\"filters: user_id={user_id}, channel={channel}\",\n            )\n            return await self._repo.filter_chats(\n                user_id=user_id,\n                channel=channel,\n            )\n\n    async def get_chat(self, chat_id: str) -> Optional[ChatSpec]:\n        \"\"\"Get chat spec by chat_id (UUID).\n\n        Args:\n            chat_id: Chat UUID\n\n        Returns:\n            Chat spec or None if not found\n        \"\"\"\n        async with self._lock:\n            return await self._repo.get_chat(chat_id)\n\n    async def get_or_create_chat(\n        self,\n        session_id: str,\n        user_id: str,\n        channel: str = DEFAULT_CHANNEL,\n        name: str = \"New Chat\",\n    ) -> ChatSpec:\n        \"\"\"Get existing chat or create new one.\n\n        Useful for auto-registration when chats come from channels.\n\n        Args:\n            session_id: Session identifier (channel:user_id)\n            user_id: User identifier\n            channel: Channel name\n            name: Chat name\n\n        Returns:\n            Chat specification (existing or newly created)\n        \"\"\"\n        async with self._lock:\n            # Try to find existing by session_id\n            logger.debug(\n                f\"get_or_create_chat: Searching for existing chat: \"\n                f\"session_id={session_id}, user_id={user_id}, \"\n                f\"channel={channel}\",\n            )\n            existing = await self._repo.get_chat_by_id(\n                session_id,\n                user_id,\n                channel,\n            )\n            if existing:\n                logger.debug(\n                    f\"get_or_create_chat: Found existing chat: {existing.id}\",\n                )\n                return existing\n\n            # Create new\n            logger.debug(\n                f\"get_or_create_chat: Creating new chat for \"\n                f\"session_id={session_id}\",\n            )\n            spec = ChatSpec(\n                session_id=session_id,\n                user_id=user_id,\n                channel=channel,\n                name=name,\n            )\n            logger.debug(f\"get_or_create_chat: created spec={spec.id}\")\n            # Call internal create without lock (already locked)\n            await self._repo.upsert_chat(spec)\n            logger.debug(\n                f\"Auto-registered new chat: {spec.id} -> {session_id}\",\n            )\n            return spec\n\n    async def create_chat(self, spec: ChatSpec) -> ChatSpec:\n        \"\"\"Create a new chat.\n\n        Args:\n            spec: Chat specification (chat_id will be generated if not set)\n\n        Returns:\n            Chat spec\n        \"\"\"\n        async with self._lock:\n            await self._repo.upsert_chat(spec)\n            return spec\n\n    async def update_chat(self, spec: ChatSpec) -> ChatSpec:\n        \"\"\"Update an existing chat spec.\n\n        Args:\n            spec: Updated chat specification\n\n        Returns:\n            Updated chat spec\n        \"\"\"\n        async with self._lock:\n            spec.updated_at = datetime.now(timezone.utc)\n            await self._repo.upsert_chat(spec)\n            return spec\n\n    async def delete_chats(self, chat_ids: list[str]) -> bool:\n        \"\"\"Delete a chat spec.\n\n        Note: This only deletes the spec. Redis session state is NOT deleted.\n\n        Args:\n            chat_ids: List of chat IDs\n\n        Returns:\n            True if deleted, False if not found\n        \"\"\"\n        async with self._lock:\n            deleted = await self._repo.delete_chats(chat_ids)\n\n            if deleted:\n                logger.debug(f\"Deleted chats: {chat_ids}\")\n\n            return deleted\n\n    async def count_chats(\n        self,\n        user_id: Optional[str] = None,\n        channel: Optional[str] = None,\n    ) -> int:\n        \"\"\"Count chats matching filters.\n\n        Args:\n            user_id: Optional user ID filter\n            channel: Optional channel filter\n\n        Returns:\n            Number of matching chats\n        \"\"\"\n        async with self._lock:\n            chats = await self._repo.filter_chats(\n                user_id=user_id,\n                channel=channel,\n            )\n            return len(chats)\n"
  },
  {
    "path": "src/copaw/app/runner/models.py",
    "content": "# -*- coding: utf-8 -*-\n\"\"\"Chat models for runner with UUID management.\"\"\"\nfrom __future__ import annotations\n\nfrom datetime import datetime, timezone\nfrom typing import Any, Dict\nfrom uuid import uuid4\n\nfrom pydantic import BaseModel, Field\nfrom agentscope_runtime.engine.schemas.agent_schemas import Message\n\nfrom ..channels.schema import DEFAULT_CHANNEL\n\n\nclass ChatSpec(BaseModel):\n    \"\"\"Chat specification with UUID identifier.\n\n    Stored in Redis and can be persisted in JSON file.\n    \"\"\"\n\n    id: str = Field(\n        default_factory=lambda: str(uuid4()),\n        description=\"Chat UUID identifier\",\n    )\n    name: str = Field(default=\"New Chat\", description=\"Chat name\")\n    session_id: str = Field(\n        ...,\n        description=\"Session identifier (channel:user_id format)\",\n    )\n    user_id: str = Field(..., description=\"User identifier\")\n    channel: str = Field(default=DEFAULT_CHANNEL, description=\"Channel name\")\n    created_at: datetime = Field(\n        default_factory=lambda: datetime.now(timezone.utc),\n        description=\"Chat creation timestamp\",\n    )\n    updated_at: datetime = Field(\n        default_factory=lambda: datetime.now(timezone.utc),\n        description=\"Chat last update timestamp\",\n    )\n    meta: Dict[str, Any] = Field(\n        default_factory=dict,\n        description=\"Additional metadata\",\n    )\n    status: str = Field(\n        default=\"idle\",\n        description=\"Conversation status: idle or running\",\n        exclude=True,\n    )\n\n\nclass ChatHistory(BaseModel):\n    \"\"\"Complete chat view with spec and state.\"\"\"\n\n    messages: list[Message] = Field(default_factory=list)\n    status: str = Field(\n        default=\"idle\",\n        description=\"Conversation status: idle or running\",\n    )\n\n\nclass ChatsFile(BaseModel):\n    \"\"\"Chat registry file for JSON repository.\n\n    Stores chat_id (UUID) -> session_id mappings for persistence.\n    \"\"\"\n\n    version: int = 1\n    chats: list[ChatSpec] = Field(default_factory=list)\n"
  },
  {
    "path": "src/copaw/app/runner/query_error_dump.py",
    "content": "# -*- coding: utf-8 -*-\n\"\"\"Write query-handler error log and agent/memory state to a temp JSON file.\"\"\"\nfrom __future__ import annotations\n\nimport json\nimport logging\nimport os\nimport tempfile\nimport traceback\nfrom datetime import datetime, timezone\nfrom typing import Any\n\nfrom ..channels.schema import DEFAULT_CHANNEL\n\nlogger = logging.getLogger(__name__)\n\n\ndef _safe_json_serialize(obj: object) -> object:\n    \"\"\"Convert object to JSON-serializable form; use str() for unknowns.\"\"\"\n    if obj is None or isinstance(obj, (bool, int, float, str)):\n        return obj\n    if isinstance(obj, (list, tuple)):\n        return [_safe_json_serialize(x) for x in obj]\n    if isinstance(obj, dict):\n        return {str(k): _safe_json_serialize(v) for k, v in obj.items()}\n    return str(obj)\n\n\ndef _request_to_dict(request: Any) -> Any:\n    \"\"\"Serialize request to a JSON-serializable dict (Pydantic or vars).\"\"\"\n    if request is None:\n        return None\n    try:\n        raw: dict[str, Any]\n        if hasattr(request, \"model_dump\"):\n            raw = request.model_dump()\n        elif hasattr(request, \"dict\"):\n            raw = request.dict()\n        else:\n            raw = dict(vars(request))\n        if not isinstance(raw, dict):\n            raw = dict(vars(request))\n        return _safe_json_serialize(raw)\n    except Exception:\n        return {\"_serialize_error\": str(request)}\n\n\ndef write_query_error_dump(\n    request: Any,\n    exc: BaseException,\n    locals_: dict,\n) -> str | None:\n    \"\"\"Write error log, traceback and agent/memory state to a temp JSON file.\n\n    Returns the temp file path, or None if write failed.\n    \"\"\"\n    try:\n        request_info: dict[str, Any] = {}\n        request_full: dict[str, Any] | None = None\n        if request is not None:\n            request_info = {\n                \"session_id\": getattr(request, \"session_id\", None),\n                \"user_id\": getattr(request, \"user_id\", None),\n                \"channel\": getattr(request, \"channel\", DEFAULT_CHANNEL),\n            }\n            request_full = _request_to_dict(request)\n        trace_str = traceback.format_exc()\n        agent_state = None\n        agent = locals_.get(\"agent\")\n        if agent is not None:\n            try:\n                if hasattr(agent, \"state_dict\"):\n                    agent_state = _safe_json_serialize(agent.state_dict())\n            except Exception as state_err:\n                agent_state = {\"_serialize_error\": str(state_err)}\n        payload = {\n            \"trace\": trace_str,\n            \"exception_type\": type(exc).__name__,\n            \"exception_message\": str(exc),\n            \"request_info\": request_info,\n            \"request\": request_full,\n            \"agent_state\": agent_state,\n            \"ts_utc\": datetime.now(timezone.utc).strftime(\n                \"%Y-%m-%dT%H:%M:%SZ\",\n            ),\n        }\n        fd, path = tempfile.mkstemp(\n            prefix=\"copaw_query_error_\",\n            suffix=\".json\",\n            dir=tempfile.gettempdir(),\n            text=True,\n        )\n        try:\n            with open(fd, \"w\", encoding=\"utf-8\") as f:\n                json.dump(payload, f, ensure_ascii=False, indent=2)\n            return path\n        finally:\n            try:\n                os.close(fd)\n            except OSError:\n                pass\n    except Exception as dump_err:\n        logger.warning(\"Failed to write query error dump: %s\", dump_err)\n        return None\n"
  },
  {
    "path": "src/copaw/app/runner/repo/__init__.py",
    "content": "# -*- coding: utf-8 -*-\n\"\"\"Chat repository implementations.\"\"\"\nfrom .base import BaseChatRepository\nfrom .json_repo import JsonChatRepository\n\n__all__ = [\"BaseChatRepository\", \"JsonChatRepository\"]\n"
  },
  {
    "path": "src/copaw/app/runner/repo/base.py",
    "content": "# -*- coding: utf-8 -*-\n\"\"\"Chat repository for storing chat/session specs.\"\"\"\nfrom __future__ import annotations\n\nfrom abc import ABC, abstractmethod\nfrom typing import Optional\n\nfrom ..models import ChatSpec, ChatsFile\nfrom ...channels.schema import DEFAULT_CHANNEL\n\n\nclass BaseChatRepository(ABC):\n    \"\"\"Abstract repository for chat specs persistence.\"\"\"\n\n    @abstractmethod\n    async def load(self) -> ChatsFile:\n        \"\"\"Load all chat specs from storage.\"\"\"\n        raise NotImplementedError\n\n    @abstractmethod\n    async def save(self, chats_file: ChatsFile) -> None:\n        \"\"\"Persist all chat specs to storage (should be atomic if possible).\"\"\"\n        raise NotImplementedError\n\n    # ---- Convenience operations ----\n\n    async def list_chats(self) -> list[ChatSpec]:\n        \"\"\"List all chat specifications.\"\"\"\n        cf = await self.load()\n        return cf.chats\n\n    async def get_chat(self, chat_id: str) -> Optional[ChatSpec]:\n        \"\"\"Get chat spec by chat_id (UUID).\n\n        Args:\n            chat_id: Chat UUID\n\n        Returns:\n            ChatSpec or None if not found\n        \"\"\"\n        cf = await self.load()\n        for chat in cf.chats:\n            if chat.id == chat_id:\n                return chat\n        return None\n\n    async def get_chat_by_id(\n        self,\n        session_id: str,\n        user_id: str,\n        channel: str = DEFAULT_CHANNEL,\n    ) -> Optional[ChatSpec]:\n        \"\"\"Get chat spec by session_id and user_id.\n\n        Args:\n            session_id: Session identifier (e.g., \"discord:alice\")\n            user_id: User identifier\n            channel: Channel identifier\n\n        Returns:\n            ChatSpec or None if not found\n        \"\"\"\n        import logging\n\n        logger = logging.getLogger(__name__)\n\n        cf = await self.load()\n\n        logger.debug(\n            f\"get_chat_by_id: Searching in {len(cf.chats)} chats for \"\n            f\"session_id={session_id}, user_id={user_id}, \"\n            f\"channel={channel}\",\n        )\n\n        for chat in cf.chats:\n            if (\n                chat.session_id == session_id\n                and chat.user_id == user_id\n                and chat.channel == channel\n            ):\n                logger.debug(f\"get_chat_by_id: Found match: {chat.id}\")\n                return chat\n\n        logger.debug(\"get_chat_by_id: No match found\")\n        return None\n\n    async def upsert_chat(self, spec: ChatSpec) -> None:\n        \"\"\"Insert or update a chat spec.\n\n        Args:\n            spec: Chat specification to upsert\n        \"\"\"\n        cf = await self.load()\n        for i, c in enumerate(cf.chats):\n            if c.id == spec.id:\n                cf.chats[i] = spec\n                break\n        else:\n            cf.chats.append(spec)\n        await self.save(cf)\n\n    async def delete_chats(self, chat_ids: list[str]) -> bool:\n        \"\"\"Delete a chat spec by chat_id (UUID).\n\n        Args:\n            chat_ids: List of chat IDs\n\n        Returns:\n            True if deleted, False if not found\n        \"\"\"\n        if not chat_ids:\n            return False\n\n        cf = await self.load()\n        before = len(cf.chats)\n        cf.chats = [c for c in cf.chats if c.id not in chat_ids]\n        if len(cf.chats) == before:\n            return False\n        await self.save(cf)\n        return True\n\n    async def filter_chats(\n        self,\n        user_id: Optional[str] = None,\n        channel: Optional[str] = None,\n    ) -> list[ChatSpec]:\n        \"\"\"Filter chats by user_id and/or channel.\n\n        Args:\n            user_id: Optional user ID filter\n            channel: Optional channel filter\n\n        Returns:\n            Filtered list of chat specs\n        \"\"\"\n        cf = await self.load()\n        results = cf.chats\n\n        if user_id is not None:\n            results = [c for c in results if c.user_id == user_id]\n\n        if channel is not None:\n            results = [c for c in results if c.channel == channel]\n\n        return results\n"
  },
  {
    "path": "src/copaw/app/runner/repo/json_repo.py",
    "content": "# -*- coding: utf-8 -*-\n\"\"\"JSON-based chat repository.\"\"\"\nfrom __future__ import annotations\n\nimport json\nimport shutil\nfrom pathlib import Path\n\nfrom .base import BaseChatRepository\nfrom ..models import ChatsFile\n\n\nclass JsonChatRepository(BaseChatRepository):\n    \"\"\"chats.json repository (single-file storage).\n\n    Stores chat_id (UUID) -> session_id mappings in a JSON file.\n    Similar to JsonJobRepository pattern from crons.\n\n    Notes:\n    - Single-machine, no cross-process lock.\n    - Atomic write: write tmp then replace.\n    \"\"\"\n\n    def __init__(self, path: Path | str):\n        \"\"\"Initialize JSON chat repository.\n\n        Args:\n            path: Path to chats.json file\n        \"\"\"\n        if isinstance(path, str):\n            path = Path(path)\n        self._path = path.expanduser()\n\n    @property\n    def path(self) -> Path:\n        \"\"\"Get the repository file path.\"\"\"\n        return self._path\n\n    async def load(self) -> ChatsFile:\n        \"\"\"Load chat specs from JSON file.\n\n        Returns:\n            ChatsFile with all chat specs\n        \"\"\"\n        if not self._path.exists():\n            return ChatsFile(version=1, chats=[])\n\n        data = json.loads(self._path.read_text(encoding=\"utf-8\"))\n        return ChatsFile.model_validate(data)\n\n    async def save(self, chats_file: ChatsFile) -> None:\n        \"\"\"Save chat specs to JSON file atomically.\n\n        Args:\n            chats_file: ChatsFile to persist\n        \"\"\"\n        # Create parent directory if needed\n        self._path.parent.mkdir(parents=True, exist_ok=True)\n\n        # Write to temp file first (atomic write)\n        tmp_path = self._path.with_suffix(self._path.suffix + \".tmp\")\n        payload = chats_file.model_dump(mode=\"json\")\n\n        tmp_path.write_text(\n            json.dumps(payload, ensure_ascii=False, indent=2, sort_keys=True),\n            encoding=\"utf-8\",\n        )\n\n        # Atomic replace (shutil.move handles cross-disk on Windows)\n        shutil.move(str(tmp_path), str(self._path))\n"
  },
  {
    "path": "src/copaw/app/runner/runner.py",
    "content": "# -*- coding: utf-8 -*-\n# pylint: disable=unused-argument too-many-branches too-many-statements\nfrom __future__ import annotations\n\nimport asyncio\nimport json\nimport logging\nimport re\nimport time\nfrom pathlib import Path\nfrom typing import TYPE_CHECKING\n\nfrom agentscope.message import Msg, TextBlock\nfrom agentscope.pipeline import stream_printing_messages\nfrom agentscope_runtime.engine.runner import Runner\nfrom agentscope_runtime.engine.schemas.agent_schemas import AgentRequest\nfrom dotenv import load_dotenv\n\nfrom .command_dispatch import (\n    _get_last_user_text,\n    _is_command,\n    run_command_path,\n)\nfrom .query_error_dump import write_query_error_dump\nfrom .session import SafeJSONSession\nfrom .utils import build_env_context\nfrom ..channels.schema import DEFAULT_CHANNEL\nfrom ...agents.react_agent import CoPawAgent\nfrom ...security.tool_guard.models import TOOL_GUARD_DENIED_MARK\nfrom ...config.config import load_agent_config\nfrom ...constant import (\n    TOOL_GUARD_APPROVAL_TIMEOUT_SECONDS,\n    WORKING_DIR,\n)\nfrom ...security.tool_guard.approval import ApprovalDecision\n\nif TYPE_CHECKING:\n    from ...agents.memory import MemoryManager\n\nlogger = logging.getLogger(__name__)\n\n_APPROVE_RE = re.compile(\n    r\"(?:^|[\\s/])approve(?:\\s|$)|批准|同意\",\n    re.IGNORECASE,\n)\n_DENY_RE = re.compile(\n    r\"not\\s+approve|don'?t\\s+approve|never\\s+approve|不批准|拒绝|别批准|否决\",\n    re.IGNORECASE,\n)\n\n\ndef _is_approval(text: str) -> bool:\n    \"\"\"Return True when *text* expresses approval intent.\n\n    Matches loosely (``approve`` / ``批准`` / ``同意`` anywhere) but rejects\n    negated forms (``not approve``, ``don't approve``, ``不批准``, …).\n    \"\"\"\n    if _DENY_RE.search(text):\n        return False\n    return bool(_APPROVE_RE.search(text))\n\n\nclass AgentRunner(Runner):\n    def __init__(\n        self,\n        agent_id: str = \"default\",\n        workspace_dir: Path | None = None,\n    ) -> None:\n        super().__init__()\n        self.framework_type = \"agentscope\"\n        self.agent_id = agent_id  # Store agent_id for config loading\n        self.workspace_dir = (\n            workspace_dir  # Store workspace_dir for prompt building\n        )\n        self._chat_manager = None  # Store chat_manager reference\n        self._mcp_manager = None  # MCP client manager for hot-reload\n        self.memory_manager: MemoryManager | None = None\n\n    def set_chat_manager(self, chat_manager):\n        \"\"\"Set chat manager for auto-registration.\n\n        Args:\n            chat_manager: ChatManager instance\n        \"\"\"\n        self._chat_manager = chat_manager\n\n    def set_mcp_manager(self, mcp_manager):\n        \"\"\"Set MCP client manager for hot-reload support.\n\n        Args:\n            mcp_manager: MCPClientManager instance\n        \"\"\"\n        self._mcp_manager = mcp_manager\n\n    _APPROVAL_TIMEOUT_SECONDS = TOOL_GUARD_APPROVAL_TIMEOUT_SECONDS\n\n    async def _resolve_pending_approval(\n        self,\n        session_id: str,\n        query: str | None,\n    ) -> tuple[Msg | None, bool]:\n        \"\"\"Check for a pending tool-guard approval for *session_id*.\n\n        Returns ``(response_msg, was_consumed)``:\n\n        - ``(None, False)`` — no pending approval, continue normally.\n        - ``(Msg, True)``   — denied; yield the Msg and stop.\n        - ``(None, True)``  — approved; skip the command path and let\n          the message reach the agent so the LLM can re-call the tool.\n        \"\"\"\n        if not session_id:\n            return None, False\n\n        from ..approvals import get_approval_service\n\n        svc = get_approval_service()\n        pending = await svc.get_pending_by_session(session_id)\n        if pending is None:\n            return None, False\n\n        elapsed = time.time() - pending.created_at\n        if elapsed > self._APPROVAL_TIMEOUT_SECONDS:\n            await svc.resolve_request(\n                pending.request_id,\n                ApprovalDecision.TIMEOUT,\n            )\n            return (\n                Msg(\n                    name=\"Friday\",\n                    role=\"assistant\",\n                    content=[\n                        TextBlock(\n                            type=\"text\",\n                            text=(\n                                f\"⏰ Tool `{pending.tool_name}` approval \"\n                                f\"timed out ({int(elapsed)}s) — denied.\\n\"\n                                f\"工具 `{pending.tool_name}` 审批超时\"\n                                f\"（{int(elapsed)}s），已拒绝执行。\"\n                            ),\n                        ),\n                    ],\n                ),\n                True,\n            )\n\n        normalized = (query or \"\").strip().lower()\n        if _is_approval(normalized):\n            await svc.resolve_request(\n                pending.request_id,\n                ApprovalDecision.APPROVED,\n            )\n            return None, True\n\n        await svc.resolve_request(\n            pending.request_id,\n            ApprovalDecision.DENIED,\n        )\n        return (\n            Msg(\n                name=\"Friday\",\n                role=\"assistant\",\n                content=[\n                    TextBlock(\n                        type=\"text\",\n                        text=(\n                            f\"❌ Tool `{pending.tool_name}` denied.\\n\"\n                            f\"工具 `{pending.tool_name}` 已拒绝执行。\"\n                        ),\n                    ),\n                ],\n            ),\n            True,\n        )\n\n    async def query_handler(\n        self,\n        msgs,\n        request: AgentRequest = None,\n        **kwargs,\n    ):\n        \"\"\"\n        Handle agent query.\n        \"\"\"\n        logger.debug(\n            f\"AgentRunner.query_handler called: agent_id={self.agent_id}, \"\n            f\"msgs={msgs}, request={request}\",\n        )\n        query = _get_last_user_text(msgs)\n        session_id = getattr(request, \"session_id\", \"\") or \"\"\n\n        (\n            approval_response,\n            approval_consumed,\n        ) = await self._resolve_pending_approval(session_id, query)\n        if approval_response is not None:\n            yield approval_response, True\n            user_id = getattr(request, \"user_id\", \"\") or \"\"\n            await self._cleanup_denied_session_memory(\n                session_id,\n                user_id,\n                denial_response=approval_response,\n            )\n            return\n\n        if not approval_consumed and query and _is_command(query):\n            logger.info(\"Command path: %s\", query.strip()[:50])\n            async for msg, last in run_command_path(request, msgs, self):\n                yield msg, last\n            return\n\n        logger.debug(\n            f\"AgentRunner.stream_query: request={request}, \"\n            f\"agent_id={self.agent_id}\",\n        )\n\n        # Set agent context for model creation\n        from ..agent_context import set_current_agent_id\n\n        set_current_agent_id(self.agent_id)\n\n        agent = None\n        chat = None\n        session_state_loaded = False\n        try:\n            session_id = request.session_id\n            user_id = request.user_id\n            channel = getattr(request, \"channel\", DEFAULT_CHANNEL)\n\n            logger.info(\n                \"Handle agent query:\\n%s\",\n                json.dumps(\n                    {\n                        \"session_id\": session_id,\n                        \"user_id\": user_id,\n                        \"channel\": channel,\n                        \"msgs_len\": len(msgs) if msgs else 0,\n                        \"msgs_str\": str(msgs)[:300] + \"...\",\n                    },\n                    ensure_ascii=False,\n                    indent=2,\n                ),\n            )\n\n            env_context = build_env_context(\n                session_id=session_id,\n                user_id=user_id,\n                channel=channel,\n                working_dir=(\n                    str(self.workspace_dir)\n                    if self.workspace_dir\n                    else str(WORKING_DIR)\n                ),\n            )\n\n            # Get MCP clients from manager (hot-reloadable)\n            mcp_clients = []\n            if self._mcp_manager is not None:\n                mcp_clients = await self._mcp_manager.get_clients()\n\n            # Load agent-specific configuration\n            agent_config = load_agent_config(self.agent_id)\n\n            agent = CoPawAgent(\n                agent_config=agent_config,\n                env_context=env_context,\n                mcp_clients=mcp_clients,\n                memory_manager=self.memory_manager,\n                request_context={\n                    \"session_id\": session_id,\n                    \"user_id\": user_id,\n                    \"channel\": channel,\n                    \"agent_id\": self.agent_id,\n                },\n                workspace_dir=self.workspace_dir,\n            )\n            await agent.register_mcp_clients()\n            agent.set_console_output_enabled(enabled=False)\n\n            logger.debug(\n                f\"Agent Query msgs {msgs}\",\n            )\n\n            name = \"New Chat\"\n            if len(msgs) > 0:\n                content = msgs[0].get_text_content()\n                if content:\n                    name = msgs[0].get_text_content()[:10]\n                else:\n                    name = \"Media Message\"\n\n            logger.debug(\n                f\"DEBUG chat_manager status: \"\n                f\"_chat_manager={self._chat_manager}, \"\n                f\"is_none={self._chat_manager is None}, \"\n                f\"agent_id={self.agent_id}\",\n            )\n\n            if self._chat_manager is not None:\n                logger.debug(\n                    f\"Runner: Calling get_or_create_chat for \"\n                    f\"session_id={session_id}, user_id={user_id}, \"\n                    f\"channel={channel}, name={name}\",\n                )\n                chat = await self._chat_manager.get_or_create_chat(\n                    session_id,\n                    user_id,\n                    channel,\n                    name=name,\n                )\n                logger.debug(f\"Runner: Got chat: {chat.id}\")\n            else:\n                logger.warning(\n                    f\"ChatManager is None! Cannot auto-register chat for \"\n                    f\"session_id={session_id}\",\n                )\n\n            try:\n                await self.session.load_session_state(\n                    session_id=session_id,\n                    user_id=user_id,\n                    agent=agent,\n                )\n            except KeyError as e:\n                logger.warning(\n                    \"load_session_state skipped (state schema mismatch): %s; \"\n                    \"will save fresh state on completion to recover file\",\n                    e,\n                )\n            session_state_loaded = True\n\n            # Rebuild system prompt so it always reflects the latest\n            # AGENTS.md / SOUL.md / PROFILE.md, not the stale one saved\n            # in the session state.\n            agent.rebuild_sys_prompt()\n\n            async for msg, last in stream_printing_messages(\n                agents=[agent],\n                coroutine_task=agent(msgs),\n            ):\n                yield msg, last\n\n        except asyncio.CancelledError as exc:\n            logger.info(f\"query_handler: {session_id} cancelled!\")\n            if agent is not None:\n                await agent.interrupt()\n            raise RuntimeError(\"Task has been cancelled!\") from exc\n        except Exception as e:\n            debug_dump_path = write_query_error_dump(\n                request=request,\n                exc=e,\n                locals_=locals(),\n            )\n            path_hint = (\n                f\"\\n(Details:  {debug_dump_path})\" if debug_dump_path else \"\"\n            )\n            logger.exception(f\"Error in query handler: {e}{path_hint}\")\n            if debug_dump_path:\n                setattr(e, \"debug_dump_path\", debug_dump_path)\n                if hasattr(e, \"add_note\"):\n                    e.add_note(\n                        f\"(Details:  {debug_dump_path})\",\n                    )\n                suffix = f\"\\n(Details:  {debug_dump_path})\"\n                e.args = (\n                    (f\"{e.args[0]}{suffix}\" if e.args else suffix.strip()),\n                ) + e.args[1:]\n            raise\n        finally:\n            if agent is not None and session_state_loaded:\n                await self.session.save_session_state(\n                    session_id=session_id,\n                    user_id=user_id,\n                    agent=agent,\n                )\n\n            if self._chat_manager is not None and chat is not None:\n                await self._chat_manager.update_chat(chat)\n\n    async def _cleanup_denied_session_memory(\n        self,\n        session_id: str,\n        user_id: str,\n        denial_response: \"Msg | None\" = None,\n    ) -> None:\n        \"\"\"Clean up session memory after a tool-guard denial.\n\n        In the deny path (no agent is created), this method:\n\n        1. Removes the LLM denial explanation (the assistant message\n           immediately following the last marked entry).\n        2. Strips ``TOOL_GUARD_DENIED_MARK`` from all marks lists so\n           the kept tool-call info becomes normal memory entries.\n        3. Appends *denial_response* (e.g. \"❌ Tool denied\") to the\n           persisted session memory.\n        \"\"\"\n        if not hasattr(self, \"session\") or self.session is None:\n            return\n\n        path = self.session._get_save_path(  # pylint: disable=protected-access\n            session_id,\n            user_id,\n        )\n        if not Path(path).exists():\n            return\n\n        try:\n            with open(\n                path,\n                \"r\",\n                encoding=\"utf-8\",\n                errors=\"surrogatepass\",\n            ) as f:\n                states = json.load(f)\n\n            agent_state = states.get(\"agent\", {})\n            memory_state = agent_state.get(\"memory\", {})\n            content = memory_state.get(\"content\", [])\n\n            if not content:\n                return\n\n            def _is_marked(entry):\n                return (\n                    isinstance(entry, list)\n                    and len(entry) >= 2\n                    and isinstance(entry[1], list)\n                    and TOOL_GUARD_DENIED_MARK in entry[1]\n                )\n\n            last_marked_idx = -1\n            for i, entry in enumerate(content):\n                if _is_marked(entry):\n                    last_marked_idx = i\n\n            modified = False\n\n            if last_marked_idx >= 0 and last_marked_idx + 1 < len(content):\n                next_entry = content[last_marked_idx + 1]\n                if (\n                    isinstance(next_entry, list)\n                    and len(next_entry) >= 1\n                    and isinstance(next_entry[0], dict)\n                    and next_entry[0].get(\"role\") == \"assistant\"\n                ):\n                    del content[last_marked_idx + 1]\n                    modified = True\n\n            for entry in content:\n                if _is_marked(entry):\n                    entry[1].remove(TOOL_GUARD_DENIED_MARK)\n                    modified = True\n\n            if denial_response is not None:\n                ts = getattr(denial_response, \"timestamp\", None)\n                msg_dict = {\n                    \"id\": getattr(denial_response, \"id\", \"\"),\n                    \"name\": getattr(denial_response, \"name\", \"Friday\"),\n                    \"role\": getattr(denial_response, \"role\", \"assistant\"),\n                    \"content\": denial_response.content,\n                    \"metadata\": getattr(\n                        denial_response,\n                        \"metadata\",\n                        None,\n                    ),\n                    \"timestamp\": str(ts) if ts is not None else \"\",\n                }\n                content.append([msg_dict, []])\n                modified = True\n\n            if modified:\n                with open(\n                    path,\n                    \"w\",\n                    encoding=\"utf-8\",\n                    errors=\"surrogatepass\",\n                ) as f:\n                    json.dump(states, f, ensure_ascii=False)\n                logger.info(\n                    \"Tool guard: cleaned up denied session memory in %s\",\n                    path,\n                )\n        except Exception:  # pylint: disable=broad-except\n            logger.warning(\n                \"Failed to clean up denied messages from session %s\",\n                session_id,\n                exc_info=True,\n            )\n\n    async def init_handler(self, *args, **kwargs):\n        \"\"\"\n        Init handler.\n        \"\"\"\n        # Load environment variables from .env file\n        # env_path = Path(__file__).resolve().parents[4] / \".env\"\n        env_path = Path(\"./\") / \".env\"\n        if env_path.exists():\n            load_dotenv(env_path)\n            logger.debug(f\"Loaded environment variables from {env_path}\")\n        else:\n            logger.debug(\n                f\".env file not found at {env_path}, \"\n                \"using existing environment variables\",\n            )\n\n        session_dir = str(\n            (self.workspace_dir if self.workspace_dir else WORKING_DIR)\n            / \"sessions\",\n        )\n        self.session = SafeJSONSession(save_dir=session_dir)\n\n    async def shutdown_handler(self, *args, **kwargs):\n        \"\"\"\n        Shutdown handler.\n        \"\"\"\n"
  },
  {
    "path": "src/copaw/app/runner/session.py",
    "content": "# -*- coding: utf-8 -*-\n\"\"\"Safe JSON session with filename sanitization for cross-platform\ncompatibility.\n\nWindows filenames cannot contain: \\\\ / : * ? \" < > |\nThis module wraps agentscope's SessionBase so that session_id and user_id\nare sanitized before being used as filenames.\n\"\"\"\nimport os\nimport re\nimport json\nimport logging\n\nfrom typing import Union, Sequence\n\nimport aiofiles\nfrom agentscope.session import SessionBase\n\nlogger = logging.getLogger(__name__)\n\n\n# Characters forbidden in Windows filenames\n_UNSAFE_FILENAME_RE = re.compile(r'[\\\\/:*?\"<>|]')\n\n\ndef sanitize_filename(name: str) -> str:\n    \"\"\"Replace characters that are illegal in Windows filenames with ``--``.\n\n    >>> sanitize_filename('discord:dm:12345')\n    'discord--dm--12345'\n    >>> sanitize_filename('normal-name')\n    'normal-name'\n    \"\"\"\n    return _UNSAFE_FILENAME_RE.sub(\"--\", name)\n\n\nclass SafeJSONSession(SessionBase):\n    \"\"\"SessionBase subclass with filename sanitization and async file I/O.\n\n    Overrides all file-reading/writing methods to use :mod:`aiofiles` so\n    that disk I/O does not block the event loop.\n    \"\"\"\n\n    def __init__(\n        self,\n        save_dir: str = \"./\",\n    ) -> None:\n        \"\"\"Initialize the JSON session class.\n\n        Args:\n            save_dir (`str`, defaults to `\"./\"):\n                The directory to save the session state.\n        \"\"\"\n        self.save_dir = save_dir\n\n    def _get_save_path(self, session_id: str, user_id: str) -> str:\n        \"\"\"Return a filesystem-safe save path.\n\n        Overrides the parent implementation to ensure the generated\n        filename is valid on Windows, macOS and Linux.\n        \"\"\"\n        os.makedirs(self.save_dir, exist_ok=True)\n        safe_sid = sanitize_filename(session_id)\n        safe_uid = sanitize_filename(user_id) if user_id else \"\"\n        if safe_uid:\n            file_path = f\"{safe_uid}_{safe_sid}.json\"\n        else:\n            file_path = f\"{safe_sid}.json\"\n        return os.path.join(self.save_dir, file_path)\n\n    async def save_session_state(\n        self,\n        session_id: str,\n        user_id: str = \"\",\n        **state_modules_mapping,\n    ) -> None:\n        \"\"\"Save state modules to a JSON file using async I/O.\"\"\"\n        state_dicts = {\n            name: state_module.state_dict()\n            for name, state_module in state_modules_mapping.items()\n        }\n        session_save_path = self._get_save_path(session_id, user_id=user_id)\n        with open(\n            session_save_path,\n            \"w\",\n            encoding=\"utf-8\",\n        ) as f:\n            f.write(json.dumps(state_dicts, ensure_ascii=False))\n\n        logger.info(\n            \"Saved session state to %s successfully.\",\n            session_save_path,\n        )\n\n    async def load_session_state(\n        self,\n        session_id: str,\n        user_id: str = \"\",\n        allow_not_exist: bool = True,\n        **state_modules_mapping,\n    ) -> None:\n        \"\"\"Load state modules from a JSON file using async I/O.\"\"\"\n        session_save_path = self._get_save_path(session_id, user_id=user_id)\n        if os.path.exists(session_save_path):\n            async with aiofiles.open(\n                session_save_path,\n                \"r\",\n                encoding=\"utf-8\",\n                errors=\"surrogatepass\",\n            ) as f:\n                content = await f.read()\n                states = json.loads(content)\n\n            for name, state_module in state_modules_mapping.items():\n                if name in states:\n                    state_module.load_state_dict(states[name])\n            logger.info(\n                \"Load session state from %s successfully.\",\n                session_save_path,\n            )\n\n        elif allow_not_exist:\n            logger.info(\n                \"Session file %s does not exist. Skip loading session state.\",\n                session_save_path,\n            )\n\n        else:\n            raise ValueError(\n                f\"Failed to load session state for file {session_save_path} \"\n                \"because it does not exist.\",\n            )\n\n    async def update_session_state(\n        self,\n        session_id: str,\n        key: Union[str, Sequence[str]],\n        value,\n        user_id: str = \"\",\n        create_if_not_exist: bool = True,\n    ) -> None:\n        session_save_path = self._get_save_path(session_id, user_id=user_id)\n\n        if os.path.exists(session_save_path):\n            async with aiofiles.open(\n                session_save_path,\n                \"r\",\n                encoding=\"utf-8\",\n                errors=\"surrogatepass\",\n            ) as f:\n                content = await f.read()\n                states = json.loads(content)\n\n        else:\n            if not create_if_not_exist:\n                raise ValueError(\n                    f\"Session file {session_save_path} does not exist.\",\n                )\n            states = {}\n\n        path = key.split(\".\") if isinstance(key, str) else list(key)\n        if not path:\n            raise ValueError(\"key path is empty\")\n\n        cur = states\n        for k in path[:-1]:\n            if k not in cur or not isinstance(cur[k], dict):\n                cur[k] = {}\n            cur = cur[k]\n\n        cur[path[-1]] = value\n\n        with open(\n            session_save_path,\n            \"w\",\n            encoding=\"utf-8\",\n        ) as f:\n            f.write(json.dumps(states, ensure_ascii=False))\n\n        logger.info(\n            \"Updated session state key '%s' in %s successfully.\",\n            key,\n            session_save_path,\n        )\n\n    async def get_session_state_dict(\n        self,\n        session_id: str,\n        user_id: str = \"\",\n        allow_not_exist: bool = True,\n    ) -> dict:\n        \"\"\"Return the session state dict from the JSON file.\n\n        Args:\n            session_id (`str`):\n                The session id.\n            user_id (`str`, default to `\"\"`):\n                The user ID for the storage.\n            allow_not_exist (`bool`, defaults to `True`):\n                Whether to allow the session to not exist. If `False`, raises\n                an error if the session does not exist.\n\n        Returns:\n            `dict`:\n                The session state dict loaded from the JSON file. Returns an\n                empty dict if the file does not exist and\n                `allow_not_exist=True`.\n        \"\"\"\n        session_save_path = self._get_save_path(session_id, user_id=user_id)\n        if os.path.exists(session_save_path):\n            async with aiofiles.open(\n                session_save_path,\n                \"r\",\n                encoding=\"utf-8\",\n                errors=\"surrogatepass\",\n            ) as file:\n                content = await file.read()\n                states = json.loads(content)\n\n            logger.info(\n                \"Get session state dict from %s successfully.\",\n                session_save_path,\n            )\n            return states\n\n        if allow_not_exist:\n            logger.info(\n                \"Session file %s does not exist. Return empty state dict.\",\n                session_save_path,\n            )\n            return {}\n\n        raise ValueError(\n            f\"Failed to get session state for file {session_save_path} \"\n            \"because it does not exist.\",\n        )\n"
  },
  {
    "path": "src/copaw/app/runner/task_tracker.py",
    "content": "# -*- coding: utf-8 -*-\n\"\"\"Task tracker for background runs: streaming, reconnect, multi-subscriber.\n\nrun_key is ChatSpec.id (chat_id). Per run: task, queues, event buffer.\nReconnects get buffer replay + new events. Cleanup when task completes.\n\"\"\"\nfrom __future__ import annotations\n\nimport asyncio\nimport json\nimport logging\nimport weakref\nfrom dataclasses import dataclass, field\nfrom typing import Any, AsyncGenerator, Callable, Coroutine\n\nlogger = logging.getLogger(__name__)\n\n_QUEUE_MAX_SIZE = 4096\n_SENTINEL = None\n\n\n@dataclass\nclass _RunState:\n    \"\"\"Per-run state (task, queues, buffer), guarded by tracker lock.\"\"\"\n\n    task: asyncio.Future\n    queues: list[asyncio.Queue] = field(default_factory=list)\n    buffer: list[str] = field(default_factory=list)\n\n\nclass TaskTracker:\n    \"\"\"Per-workspace tracker: run_key -> RunState.\n\n    All mutations to _runs under _lock. Producer broadcasts under lock.\n    Dead queues pruned when full.\n    \"\"\"\n\n    def __init__(self) -> None:\n        self._lock = asyncio.Lock()\n        self._runs: dict[str, _RunState] = {}\n\n    @property\n    def lock(self) -> asyncio.Lock:\n        return self._lock\n\n    async def get_status(self, run_key: str) -> str:\n        \"\"\"Return ``'idle'`` or ``'running'``.\"\"\"\n        async with self._lock:\n            state = self._runs.get(run_key)\n        if state is None or state.task.done():\n            return \"idle\"\n        return \"running\"\n\n    async def has_active_tasks(self) -> bool:\n        \"\"\"Check if any tasks are currently running.\n\n        Returns:\n            bool: True if any tasks are active, False otherwise\n        \"\"\"\n        async with self._lock:\n            for state in self._runs.values():\n                if not state.task.done():\n                    return True\n            return False\n\n    async def list_active_tasks(self) -> list[str]:\n        \"\"\"List all currently running task keys.\n\n        Returns:\n            list[str]: List of active run_keys\n        \"\"\"\n        async with self._lock:\n            return [\n                run_key\n                for run_key, state in self._runs.items()\n                if not state.task.done()\n            ]\n\n    async def wait_all_done(self, timeout: float = 300.0) -> bool:\n        \"\"\"Wait for all active tasks to complete.\n\n        Args:\n            timeout: Maximum time to wait in seconds (default: 300s = 5min)\n\n        Returns:\n            bool: True if all tasks completed, False if timeout occurred\n        \"\"\"\n\n        async def _wait_loop() -> None:\n            while await self.has_active_tasks():\n                await asyncio.sleep(0.5)\n\n        try:\n            await asyncio.wait_for(_wait_loop(), timeout=timeout)\n            return True\n        except asyncio.TimeoutError:\n            return False\n\n    async def attach(self, run_key: str) -> asyncio.Queue | None:\n        \"\"\"Attach to an existing run.\n\n        Returns a new queue pre-filled with the event buffer, or ``None``\n        if no run is active for *run_key*.\n        \"\"\"\n        async with self._lock:\n            state = self._runs.get(run_key)\n            if state is None or state.task.done():\n                return None\n            q: asyncio.Queue = asyncio.Queue(maxsize=_QUEUE_MAX_SIZE)\n            for sse in state.buffer:\n                q.put_nowait(sse)\n            state.queues.append(q)\n            return q\n\n    async def request_stop(self, run_key: str) -> bool:\n        \"\"\"Cancel the run. Returns ``True`` if it was running.\"\"\"\n        async with self._lock:\n            state = self._runs.get(run_key)\n            if state is None or state.task.done():\n                return False\n            state.task.cancel()\n            return True\n\n    async def attach_or_start(\n        self,\n        run_key: str,\n        payload: Any,\n        stream_fn: Callable[..., Coroutine],\n    ) -> tuple[asyncio.Queue, bool]:\n        \"\"\"Attach to an existing run or start a new one.\n\n        Returns ``(queue, is_new_run)``.\n        \"\"\"\n        async with self._lock:\n            state = self._runs.get(run_key)\n            if state is not None and not state.task.done():\n                q: asyncio.Queue = asyncio.Queue(maxsize=_QUEUE_MAX_SIZE)\n                for sse in state.buffer:\n                    q.put_nowait(sse)\n                state.queues.append(q)\n                return q, False\n\n            my_queue: asyncio.Queue = asyncio.Queue(maxsize=_QUEUE_MAX_SIZE)\n            run = _RunState(\n                task=asyncio.Future(),  # placeholder, replaced below\n                queues=[my_queue],\n                buffer=[],\n            )\n            self._runs[run_key] = run\n\n            tracker_ref = weakref.ref(self)\n\n            async def _producer() -> None:\n                try:\n                    async for sse in stream_fn(payload):\n                        tracker = tracker_ref()\n                        if tracker is None:\n                            return\n                        async with tracker.lock:\n                            run.buffer.append(sse)\n                            alive: list[asyncio.Queue] = []\n                            for q in run.queues:\n                                try:\n                                    q.put_nowait(sse)\n                                    alive.append(q)\n                                except asyncio.QueueFull:\n                                    logger.warning(\n                                        \"dropping subscriber queue (full) \"\n                                        \"run_key=%s\",\n                                        run_key,\n                                    )\n                            # Prune dead queues (full = client not reading)\n                            run.queues = alive\n                except asyncio.CancelledError:\n                    logger.debug(\"run cancelled run_key=%s\", run_key)\n                except Exception:\n                    logger.exception(\"run error run_key=%s\", run_key)\n                    err_sse = (\n                        \"data: \"\n                        f\"{json.dumps({'error': 'internal server error'})}\\n\\n\"\n                    )\n                    tracker = tracker_ref()\n                    if tracker is not None:\n                        async with tracker.lock:\n                            run.buffer.append(err_sse)\n                            for q in run.queues:\n                                try:\n                                    q.put_nowait(err_sse)\n                                except asyncio.QueueFull:\n                                    pass\n                finally:\n                    tracker = tracker_ref()\n                    if tracker is not None:\n                        async with tracker.lock:\n                            for q in run.queues:\n                                try:\n                                    q.put_nowait(_SENTINEL)\n                                except asyncio.QueueFull:\n                                    pass\n                            # pylint: disable=protected-access\n                            tracker._runs.pop(\n                                run_key,\n                                None,\n                            )\n\n            run.task = asyncio.create_task(_producer())\n            return my_queue, True\n\n    @staticmethod\n    async def stream_from_queue(\n        queue: asyncio.Queue,\n    ) -> AsyncGenerator[str, None]:\n        \"\"\"Yield SSE strings from *queue* until the sentinel ``None``.\"\"\"\n        while True:\n            try:\n                event = await queue.get()\n                if event is _SENTINEL:\n                    break\n                yield event\n            except asyncio.CancelledError:\n                break\n"
  },
  {
    "path": "src/copaw/app/runner/utils.py",
    "content": "# -*- coding: utf-8 -*-\nimport json\nimport logging\nimport platform\nimport os\nfrom datetime import datetime, timezone\nfrom typing import List, Optional, Union\nfrom urllib.parse import urlparse\nfrom zoneinfo import ZoneInfo, ZoneInfoNotFoundError\n\nfrom agentscope.message import Msg\nfrom agentscope_runtime.engine.schemas.agent_schemas import (\n    Message,\n    TextContent,\n    ImageContent,\n    AudioContent,\n    VideoContent,\n    FileContent,\n    DataContent,\n    FunctionCall,\n    FunctionCallOutput,\n    MessageType,\n)\n\nfrom ...config import load_config\n\nlogger = logging.getLogger(__name__)\n\n\ndef build_env_context(\n    session_id: Optional[str] = None,\n    user_id: Optional[str] = None,\n    channel: Optional[str] = None,\n    working_dir: Optional[str] = None,\n    add_hint: bool = True,\n) -> str:\n    \"\"\"\n    Build environment context with current request context prepended.\n\n    Args:\n        session_id: Current session ID\n        user_id: Current user ID\n        channel: Current channel name\n        working_dir: Working directory path\n        add_hint: Whether to add hint context\n    Returns:\n        Formatted environment context string\n    \"\"\"\n    parts = []\n    user_tz = load_config().user_timezone or \"UTC\"\n    try:\n        now = datetime.now(ZoneInfo(user_tz))\n    except (ZoneInfoNotFoundError, KeyError):\n        logger.warning(\"Invalid timezone %r, falling back to UTC\", user_tz)\n        now = datetime.now(timezone.utc)\n        user_tz = \"UTC\"\n\n    if session_id is not None:\n        parts.append(f\"- Session ID: {session_id}\")\n    if user_id is not None:\n        parts.append(f\"- User ID: {user_id}\")\n    if channel is not None:\n        parts.append(f\"- Channel: {channel}\")\n\n    parts.append(\n        f\"- OS: {platform.system()} {platform.release()} \"\n        f\"({platform.machine()})\",\n    )\n\n    if working_dir is not None:\n        parts.append(f\"- Working directory: {working_dir}\")\n    parts.append(\n        f\"- Current time: {now.strftime('%Y-%m-%d %H:%M:%S')} \"\n        f\"{user_tz} ({now.strftime('%A')})\",\n    )\n\n    if add_hint:\n        parts.append(\n            \"- Important:\\n\"\n            \"  1. Prefer using skills when completing tasks \"\n            \"(e.g. use the cron skill for scheduled tasks). \"\n            \"Consult the relevant skill documentation if unsure.\\n\"\n            \"  2. When using write_file, if you want to avoid overwriting \"\n            \"existing content, use read_file first to inspect the file, \"\n            \"then use edit_file for partial updates or appending.\",\n        )\n\n    return (\n        \"====================\\n\" + \"\\n\".join(parts) + \"\\n====================\"\n    )\n\n\ndef _is_local_file_url(url: str) -> bool:\n    \"\"\"True if url is a local file reference (file:// or absolute path).\"\"\"\n    if not url or not isinstance(url, str):\n        return False\n    s = url.strip()\n    if not s:\n        return False\n    lower = s.lower()\n\n    # Check for remote URLs\n    if lower.startswith((\"http://\", \"https://\", \"data:\")):\n        return False\n\n    # Check for local file patterns: file://, Unix paths, or Windows drives\n    return (\n        lower.startswith(\"file:\")\n        or (s.startswith(\"/\") and not s.startswith(\"//\"))\n        or (len(s) >= 2 and s[1] == \":\" and s[0].isalpha())\n    )\n\n\ndef _basename_from_url(url: str) -> str:\n    \"\"\"Extract filename from file:// or path.\"\"\"\n    s = url.strip()\n    if s.lower().startswith(\"file:\"):\n        s = s[5:].lstrip(\"/\")\n    return os.path.basename(s.rstrip(\"/\") or \"file\")\n\n\ndef _resolve_content_url(url: str) -> str:\n    \"\"\"If url is local, return filename only; frontend builds URL.\"\"\"\n    if not isinstance(url, str):\n        return url\n    if not _is_local_file_url(url):\n        return url\n    return _basename_from_url(url)\n\n\n# pylint: disable=too-many-branches,too-many-statements\ndef agentscope_msg_to_message(\n    messages: Union[Msg, List[Msg]],\n) -> List[Message]:\n    \"\"\"\n    Convert AgentScope Msg(s) into one or more runtime Message objects.\n\n    Args:\n        messages: AgentScope message(s) from streaming.\n\n    Returns:\n        List[Message]: One or more constructed runtime Message objects.\n    \"\"\"\n    if isinstance(messages, Msg):\n        msgs = [messages]\n    elif isinstance(messages, list):\n        msgs = messages\n    else:\n        raise TypeError(f\"Expected Msg or list[Msg], got {type(messages)}\")\n\n    results: List[Message] = []\n\n    for msg in msgs:\n        role = msg.role or \"assistant\"\n        metadata = {\n            \"original_id\": msg.id,\n            \"original_name\": msg.name,\n            \"metadata\": msg.metadata,\n        }\n\n        if isinstance(msg.content, str):\n            message = Message(type=MessageType.MESSAGE, role=role)\n            message.metadata = metadata\n            text_content = TextContent(\n                delta=False,\n                index=None,\n                text=msg.content,\n            )\n            message.add_content(new_content=text_content)\n            results.append(message)\n            continue\n\n        current_message = None\n        current_type = None\n\n        for block in msg.content:\n            if isinstance(block, dict):\n                btype = block.get(\"type\", \"text\")\n            else:\n                continue\n\n            if btype == \"text\":\n                if current_type != MessageType.MESSAGE:\n                    if current_message:\n                        results.append(current_message.completed())\n                    current_message = Message(\n                        type=MessageType.MESSAGE,\n                        role=role,\n                    )\n                    current_message.metadata = metadata\n                    current_type = MessageType.MESSAGE\n\n                text_content = TextContent(\n                    delta=False,\n                    index=None,\n                    text=block.get(\"text\", \"\"),\n                )\n                current_message.add_content(new_content=text_content)\n\n            elif btype == \"thinking\":\n                if current_type != MessageType.REASONING:\n                    if current_message:\n                        results.append(current_message.completed())\n                    current_message = Message(\n                        type=MessageType.REASONING,\n                        role=role,\n                    )\n                    current_message.metadata = metadata\n                    current_type = MessageType.REASONING\n\n                text_content = TextContent(\n                    delta=False,\n                    index=None,\n                    text=block.get(\"thinking\", \"\"),\n                )\n                current_message.add_content(new_content=text_content)\n\n            elif btype == \"tool_use\":\n                if current_message:\n                    results.append(current_message.completed())\n\n                current_message = Message(\n                    type=MessageType.PLUGIN_CALL,\n                    role=role,\n                )\n                current_message.metadata = metadata\n                current_type = MessageType.PLUGIN_CALL\n\n                if isinstance(block.get(\"input\"), (dict, list)):\n                    arguments = json.dumps(\n                        block.get(\"input\"),\n                        ensure_ascii=False,\n                    )\n                else:\n                    arguments = block.get(\"input\")\n\n                call_data = FunctionCall(\n                    call_id=block.get(\"id\"),\n                    name=block.get(\"name\"),\n                    arguments=arguments,\n                ).model_dump()\n\n                data_content = DataContent(\n                    delta=False,\n                    index=None,\n                    data=call_data,\n                )\n                current_message.add_content(new_content=data_content)\n\n            elif btype == \"tool_result\":\n                if current_message:\n                    results.append(current_message.completed())\n\n                current_message = Message(\n                    type=MessageType.PLUGIN_CALL_OUTPUT,\n                    role=role,\n                )\n                current_message.metadata = metadata\n                current_type = MessageType.PLUGIN_CALL_OUTPUT\n\n                if isinstance(block.get(\"output\"), (dict, list)):\n                    output = json.dumps(\n                        block.get(\"output\"),\n                        ensure_ascii=False,\n                    )\n                else:\n                    output = block.get(\"output\")\n\n                output_data = FunctionCallOutput(\n                    call_id=block.get(\"id\"),\n                    name=block.get(\"name\"),\n                    output=output,\n                ).model_dump(exclude_none=True)\n\n                data_content = DataContent(\n                    delta=False,\n                    index=None,\n                    data=output_data,\n                )\n                current_message.add_content(new_content=data_content)\n\n            elif btype == \"image\":\n                if current_type != MessageType.MESSAGE:\n                    if current_message:\n                        results.append(current_message.completed())\n                    current_message = Message(\n                        type=MessageType.MESSAGE,\n                        role=role,\n                    )\n                    current_message.metadata = metadata\n                    current_type = MessageType.MESSAGE\n\n                kwargs = {}\n                if (\n                    isinstance(block.get(\"source\"), dict)\n                    and block.get(\"source\", {}).get(\"type\") == \"url\"\n                ):\n                    url = block.get(\"source\", {}).get(\"url\")\n                    url = _resolve_content_url(url)\n                    kwargs[\"image_url\"] = url\n\n                elif (\n                    isinstance(block.get(\"source\"), dict)\n                    and block.get(\"source\").get(\"type\") == \"base64\"\n                ):\n                    media_type = block.get(\"source\", {}).get(\n                        \"media_type\",\n                        \"image/jpeg\",\n                    )\n                    base64_data = block.get(\"source\", {}).get(\"data\", \"\")\n                    url = f\"data:{media_type};base64,{base64_data}\"\n                    kwargs[\"image_url\"] = url\n\n                image_content = ImageContent(\n                    delta=False,\n                    index=None,\n                    **kwargs,\n                )\n                current_message.add_content(new_content=image_content)\n\n            elif btype == \"audio\":\n                if current_type != MessageType.MESSAGE:\n                    if current_message:\n                        results.append(current_message.completed())\n                    current_message = Message(\n                        type=MessageType.MESSAGE,\n                        role=role,\n                    )\n                    current_message.metadata = metadata\n                    current_type = MessageType.MESSAGE\n\n                kwargs = {}\n                if (\n                    isinstance(block.get(\"source\"), dict)\n                    and block.get(\"source\", {}).get(\"type\") == \"url\"\n                ):\n                    url = block.get(\"source\", {}).get(\"url\")\n                    url = _resolve_content_url(url)\n                    kwargs[\"data\"] = url\n                    try:\n                        kwargs[\"format\"] = urlparse(url).path.split(\".\")[-1]\n                    except (AttributeError, IndexError, ValueError):\n                        kwargs[\"format\"] = None\n\n                elif (\n                    isinstance(block.get(\"source\"), dict)\n                    and block.get(\"source\").get(\"type\") == \"base64\"\n                ):\n                    media_type = block.get(\"source\", {}).get(\"media_type\")\n                    base64_data = block.get(\"source\", {}).get(\"data\", \"\")\n                    url = f\"data:{media_type};base64,{base64_data}\"\n                    kwargs[\"data\"] = url\n                    kwargs[\"format\"] = media_type\n\n                audio_content = AudioContent(\n                    delta=False,\n                    index=None,\n                    **kwargs,\n                )\n                current_message.add_content(new_content=audio_content)\n\n            elif btype == \"video\":\n                if current_type != MessageType.MESSAGE:\n                    if current_message:\n                        results.append(current_message.completed())\n                    current_message = Message(\n                        type=MessageType.MESSAGE,\n                        role=role,\n                    )\n                    current_message.metadata = metadata\n                    current_type = MessageType.MESSAGE\n\n                kwargs = {}\n                if (\n                    isinstance(block.get(\"source\"), dict)\n                    and block.get(\"source\", {}).get(\"type\") == \"url\"\n                ):\n                    url = block.get(\"source\", {}).get(\"url\")\n                    url = _resolve_content_url(url)\n                    kwargs[\"video_url\"] = url\n\n                elif (\n                    isinstance(block.get(\"source\"), dict)\n                    and block.get(\"source\").get(\"type\") == \"base64\"\n                ):\n                    media_type = block.get(\"source\", {}).get(\n                        \"media_type\",\n                        \"video/mp4\",\n                    )\n                    base64_data = block.get(\"source\", {}).get(\"data\", \"\")\n                    url = f\"data:{media_type};base64,{base64_data}\"\n                    kwargs[\"video_url\"] = url\n\n                video_content = VideoContent(\n                    delta=False,\n                    index=None,\n                    **kwargs,\n                )\n                current_message.add_content(new_content=video_content)\n\n            elif btype == \"file\":\n                if current_type != MessageType.MESSAGE:\n                    if current_message:\n                        results.append(current_message.completed())\n                    current_message = Message(\n                        type=MessageType.MESSAGE,\n                        role=role,\n                    )\n                    current_message.metadata = metadata\n                    current_type = MessageType.MESSAGE\n\n                kwargs = {\n                    \"filename\": block.get(\"filename\"),\n                }\n                if (\n                    isinstance(block.get(\"source\"), dict)\n                    and block.get(\"source\", {}).get(\"type\") == \"url\"\n                ):\n                    url = block.get(\"source\", {}).get(\"url\")\n                    url = _resolve_content_url(url)\n                    kwargs[\"file_url\"] = url\n\n                elif (\n                    isinstance(block.get(\"source\"), dict)\n                    and block.get(\"source\").get(\"type\") == \"base64\"\n                ):\n                    media_type = block.get(\"source\", {}).get(\n                        \"media_type\",\n                        \"application/octet-stream\",\n                    )\n                    base64_data = block.get(\"source\", {}).get(\"data\", \"\")\n                    url = f\"data:{media_type};base64,{base64_data}\"\n                    kwargs[\"file_url\"] = url\n                elif isinstance(block.get(\"source\"), str):\n                    url = _resolve_content_url(block.get(\"source\", \"\"))\n                    kwargs[\"file_url\"] = url\n\n                file_content = FileContent(\n                    delta=False,\n                    index=None,\n                    **kwargs,\n                )\n                current_message.add_content(new_content=file_content)\n\n            else:\n                if current_type != MessageType.MESSAGE:\n                    if current_message:\n                        results.append(current_message.completed())\n                    current_message = Message(\n                        type=MessageType.MESSAGE,\n                        role=role,\n                    )\n                    current_message.metadata = metadata\n                    current_type = MessageType.MESSAGE\n\n                text_content = TextContent(\n                    delta=False,\n                    index=None,\n                    text=str(block),\n                )\n                current_message.add_content(new_content=text_content)\n\n        if current_message:\n            results.append(current_message.completed())\n\n    return results\n"
  },
  {
    "path": "src/copaw/app/workspace/__init__.py",
    "content": "# -*- coding: utf-8 -*-\n\"\"\"Workspace module for agent lifecycle management.\n\nThis module provides unified workspace management including:\n- Workspace: Single agent instance manager\n- ServiceManager: Component lifecycle orchestration\n- ServiceDescriptor: Declarative service configuration\n\"\"\"\n\nfrom .workspace import Workspace\nfrom .service_manager import ServiceManager, ServiceDescriptor\n\n__all__ = [\"Workspace\", \"ServiceManager\", \"ServiceDescriptor\"]\n"
  },
  {
    "path": "src/copaw/app/workspace/service_factories.py",
    "content": "# -*- coding: utf-8 -*-\n\"\"\"Service factory functions for workspace components.\n\nFactory functions are used by Workspace._register_services() to create\nand initialize service components. Extracted from local functions to\nimprove testability and code organization.\n\"\"\"\n\nfrom typing import TYPE_CHECKING\nimport logging\n\nif TYPE_CHECKING:\n    from .workspace import Workspace\n\nlogger = logging.getLogger(__name__)\n\n\nasync def create_mcp_service(ws: \"Workspace\", mcp):\n    \"\"\"Initialize MCP manager and attach to runner.\n\n    Args:\n        ws: Workspace instance\n        mcp: MCPClientManager instance\n    \"\"\"\n    # pylint: disable=protected-access\n    if ws._config.mcp:\n        try:\n            await mcp.init_from_config(ws._config.mcp)\n            logger.debug(f\"MCP initialized for agent: {ws.agent_id}\")\n        except Exception as e:\n            logger.warning(f\"Failed to init MCP: {e}\")\n    ws._service_manager.services[\"runner\"].set_mcp_manager(mcp)\n    # pylint: enable=protected-access\n\n\nasync def create_chat_service(ws: \"Workspace\", service):\n    \"\"\"Create and attach chat manager, or reuse existing one.\n\n    Args:\n        ws: Workspace instance\n        service: Existing ChatManager if reused, None if creating new\n    \"\"\"\n    # pylint: disable=protected-access\n    from ..runner.manager import ChatManager\n    from ..runner.repo.json_repo import JsonChatRepository\n\n    if service is not None:\n        # Reused ChatManager - just wire to new runner\n        cm = service\n        logger.info(f\"Reusing ChatManager for {ws.agent_id}\")\n    else:\n        # Create new ChatManager\n        chats_path = str(ws.workspace_dir / \"chats.json\")\n        chat_repo = JsonChatRepository(chats_path)\n        cm = ChatManager(repo=chat_repo)\n        ws._service_manager.services[\"chat_manager\"] = cm\n        logger.info(f\"ChatManager created: {chats_path}\")\n\n    # Always wire to new runner\n    ws._service_manager.services[\"runner\"].set_chat_manager(cm)\n    # pylint: enable=protected-access\n\n\nasync def create_channel_service(ws: \"Workspace\", _):\n    \"\"\"Create channel manager if configured.\n\n    Args:\n        ws: Workspace instance\n        _: Unused service parameter\n\n    Returns:\n        ChannelManager instance or None if not configured\n    \"\"\"\n    # pylint: disable=protected-access\n    if not ws._config.channels:\n        return None\n\n    from ...config import Config, update_last_dispatch\n    from ..channels.manager import ChannelManager\n    from ..channels.utils import make_process_from_runner\n\n    temp_config = Config(channels=ws._config.channels)\n    runner = ws._service_manager.services[\"runner\"]\n\n    def on_last_dispatch(channel, user_id, session_id):\n        update_last_dispatch(\n            channel=channel,\n            user_id=user_id,\n            session_id=session_id,\n            agent_id=ws.agent_id,\n        )\n\n    cm = ChannelManager.from_config(\n        process=make_process_from_runner(runner),\n        config=temp_config,\n        on_last_dispatch=on_last_dispatch,\n        workspace_dir=ws.workspace_dir,\n    )\n    ws._service_manager.services[\"channel_manager\"] = cm\n    return cm\n    # pylint: enable=protected-access\n\n\nasync def create_agent_config_watcher(ws: \"Workspace\", _):\n    \"\"\"Create agent config watcher if channel/cron exists.\n\n    Args:\n        ws: Workspace instance\n        _: Unused service parameter\n\n    Returns:\n        AgentConfigWatcher instance or None if not needed\n    \"\"\"\n    # pylint: disable=protected-access\n    channel_mgr = ws._service_manager.services.get(\"channel_manager\")\n    cron_mgr = ws._service_manager.services.get(\"cron_manager\")\n\n    if not (channel_mgr or cron_mgr):\n        return None\n\n    from ..agent_config_watcher import AgentConfigWatcher\n\n    watcher = AgentConfigWatcher(\n        agent_id=ws.agent_id,\n        workspace_dir=ws.workspace_dir,\n        channel_manager=channel_mgr,\n        cron_manager=cron_mgr,\n    )\n    ws._service_manager.services[\"agent_config_watcher\"] = watcher\n    return watcher\n    # pylint: enable=protected-access\n\n\nasync def create_mcp_config_watcher(ws: \"Workspace\", _):\n    \"\"\"Create MCP config watcher if MCP manager exists.\n\n    Args:\n        ws: Workspace instance\n        _: Unused service parameter\n\n    Returns:\n        MCPConfigWatcher instance or None if not needed\n    \"\"\"\n    # pylint: disable=protected-access\n    mcp_mgr = ws._service_manager.services.get(\"mcp_manager\")\n    if not mcp_mgr:\n        return None\n\n    from ..mcp.watcher import MCPConfigWatcher\n    from ...config.config import load_agent_config\n\n    def mcp_config_loader():\n        agent_config = load_agent_config(ws.agent_id)\n        return agent_config.mcp\n\n    watcher = MCPConfigWatcher(\n        mcp_manager=mcp_mgr,\n        config_loader=mcp_config_loader,\n        config_path=ws.workspace_dir / \"agent.json\",\n    )\n    ws._service_manager.services[\"mcp_config_watcher\"] = watcher\n    return watcher\n    # pylint: enable=protected-access\n"
  },
  {
    "path": "src/copaw/app/workspace/service_manager.py",
    "content": "# -*- coding: utf-8 -*-\n\"\"\"Service management system for Workspace components.\n\nProvides unified registration, lifecycle management, and dependency handling\nfor all workspace services (MemoryManager, ChatManager, etc.).\n\"\"\"\nfrom __future__ import annotations\n\nimport asyncio\nimport logging\nfrom dataclasses import dataclass, field\nfrom typing import (\n    TYPE_CHECKING,\n    Any,\n    Awaitable,\n    Callable,\n    Dict,\n    List,\n    Optional,\n    Set,\n    Union,\n)\n\nif TYPE_CHECKING:\n    from .workspace import Workspace\n\nlogger = logging.getLogger(__name__)\n\n\n@dataclass\nclass ServiceDescriptor:\n    \"\"\"Descriptor for a workspace service component.\n\n    Defines metadata and lifecycle hooks for a service that can be\n    managed by ServiceManager.\n\n    Attributes:\n        name: Unique service identifier (e.g., 'memory_manager')\n        service_class: Class to instantiate (e.g., MemoryManager)\n        init_args: Callable that returns init kwargs for the service\n        post_init: Optional hook called after creation (for setup logic)\n        start_method: Name of method to call after creation (e.g., 'start')\n        stop_method: Name of method to call during shutdown (e.g., 'stop')\n        reusable: Whether this service can be reused across reloads\n        reload_func: Optional hook called when reusable service is reused\n        dependencies: List of service names that must start before this one\n        priority: Startup priority (lower = earlier, reversed for shutdown)\n        concurrent_init: Whether this can be initialized concurrently\n    \"\"\"\n\n    name: str\n    service_class: Optional[type] = None\n    init_args: Optional[Callable[[Workspace], dict]] = None\n    post_init: Optional[\n        Union[\n            Callable[[Workspace, Any], None],\n            Callable[[Workspace, Any], Awaitable[Any]],\n        ]\n    ] = None\n    start_method: Optional[str] = None\n    stop_method: Optional[str] = None\n    reusable: bool = False\n    reload_func: Optional[\n        Union[\n            Callable[[Workspace, Any], None],\n            Callable[[Workspace, Any], Awaitable[Any]],\n        ]\n    ] = None\n    dependencies: List[str] = field(default_factory=list)\n    priority: int = 100\n    concurrent_init: bool = True\n\n\nclass ServiceManager:\n    \"\"\"Unified manager for workspace service components.\n\n    Handles registration, lifecycle (start/stop), dependency resolution,\n    and component reuse during reload.\n    \"\"\"\n\n    def __init__(self, workspace: Workspace):\n        \"\"\"Initialize service manager.\n\n        Args:\n            workspace: The Workspace instance that owns these services\n        \"\"\"\n        self.workspace = workspace\n        self.services: Dict[str, Any] = {}\n        self.descriptors: Dict[str, ServiceDescriptor] = {}\n        self.reused_services: Set[str] = set()\n\n    def register(self, descriptor: ServiceDescriptor) -> None:\n        \"\"\"Register a service descriptor.\n\n        Args:\n            descriptor: Service descriptor to register\n        \"\"\"\n        if descriptor.name in self.descriptors:\n            logger.warning(\n                f\"Service '{descriptor.name}' already registered, \"\n                f\"overwriting\",\n            )\n        self.descriptors[descriptor.name] = descriptor\n        logger.debug(f\"Registered service: {descriptor.name}\")\n\n    async def set_reusable(self, name: str, instance: Any) -> None:\n        \"\"\"Mark a service instance as reused from previous workspace.\n\n        Must be called before start_all(). If the service descriptor has a\n        reload_func, it will be called with the workspace and instance.\n\n        Args:\n            name: Service name\n            instance: Service instance to reuse\n        \"\"\"\n        if name not in self.descriptors:\n            logger.warning(\n                f\"Unknown service '{name}', cannot mark as reusable\",\n            )\n            return\n\n        descriptor = self.descriptors[name]\n        if not descriptor.reusable:\n            logger.warning(\n                f\"Service '{name}' is not marked as reusable \"\n                f\"in its descriptor\",\n            )\n            return\n\n        self.services[name] = instance\n        self.reused_services.add(name)\n        logger.debug(f\"Marked service '{name}' as reused\")\n\n        # Trigger reload_func if provided\n        if descriptor.reload_func is not None:\n            try:\n                result = descriptor.reload_func(self.workspace, instance)\n                if asyncio.iscoroutine(result):\n                    await result\n                logger.debug(f\"Called reload_func for service '{name}'\")\n            except Exception as e:\n                logger.warning(\n                    f\"Error calling reload_func for service '{name}': {e}\",\n                )\n\n    def get_reusable_services(self) -> Dict[str, Any]:\n        \"\"\"Get all reusable service instances for transfer to new workspace.\n\n        Returns:\n            Dict mapping service names to instances\n        \"\"\"\n        reusable = {}\n        for name, descriptor in self.descriptors.items():\n            if descriptor.reusable and name in self.services:\n                reusable[name] = self.services[name]\n        return reusable\n\n    def _group_by_priority(self) -> Dict[int, List[ServiceDescriptor]]:\n        \"\"\"Group service descriptors by priority.\n\n        Returns:\n            Dict mapping priority to list of descriptors\n        \"\"\"\n        groups: Dict[int, List[ServiceDescriptor]] = {}\n        for descriptor in self.descriptors.values():\n            if descriptor.priority not in groups:\n                groups[descriptor.priority] = []\n            groups[descriptor.priority].append(descriptor)\n        return groups\n\n    async def start_all(self) -> None:\n        \"\"\"Start all registered services in priority order.\n\n        Services with same priority are started concurrently if allowed.\n        Reused services are skipped.\n        \"\"\"\n        logger.debug(\n            f\"Starting {len(self.descriptors)} services \"\n            f\"({len(self.reused_services)} reused)\",\n        )\n\n        priority_groups = self._group_by_priority()\n\n        for priority in sorted(priority_groups.keys()):\n            descriptors = priority_groups[priority]\n\n            # Separate concurrent and sequential services\n            concurrent = [d for d in descriptors if d.concurrent_init]\n            sequential = [d for d in descriptors if not d.concurrent_init]\n\n            # Start concurrent services in parallel\n            if concurrent:\n                await asyncio.gather(\n                    *[self._start_service(desc) for desc in concurrent],\n                )\n\n            # Start sequential services one by one\n            for desc in sequential:\n                await self._start_service(desc)\n\n    async def _start_service(self, descriptor: ServiceDescriptor) -> None:\n        \"\"\"Start a single service.\n\n        Args:\n            descriptor: Service descriptor\n        \"\"\"\n        name = descriptor.name\n        is_reused = name in self.reused_services\n\n        if is_reused:\n            logger.info(\n                f\"Reusing service '{name}' for {self.workspace.agent_id}\",\n            )\n\n        try:\n            service = await self._get_or_create_service(\n                descriptor,\n                is_reused,\n            )\n            service = await self._run_post_init(descriptor, service, name)\n            await self._run_start_method(descriptor, service, is_reused)\n\n        except Exception as e:\n            logger.exception(\n                f\"Failed to start service '{name}' \"\n                f\"for {self.workspace.agent_id}: {e}\",\n            )\n            raise\n\n    async def _get_or_create_service(\n        self,\n        descriptor: ServiceDescriptor,\n        is_reused: bool,\n    ) -> Any:\n        \"\"\"Get existing or create new service instance.\n\n        Args:\n            descriptor: Service descriptor\n            is_reused: Whether service is being reused\n\n        Returns:\n            Service instance or None\n        \"\"\"\n        if is_reused:\n            return self.services.get(descriptor.name)\n\n        logger.debug(f\"Creating service '{descriptor.name}'...\")\n\n        if not descriptor.service_class:\n            return None\n\n        # Get init args from callable\n        init_kwargs = {}\n        if descriptor.init_args:\n            init_kwargs = descriptor.init_args(self.workspace)\n\n        # Instantiate service\n        service = descriptor.service_class(**init_kwargs)\n        self.services[descriptor.name] = service\n        return service\n\n    async def _run_post_init(\n        self,\n        descriptor: ServiceDescriptor,\n        service: Any,\n        name: str,\n    ) -> Any:\n        \"\"\"Run post_init hook and capture returned service.\n\n        Args:\n            descriptor: Service descriptor\n            service: Current service instance (may be None)\n            name: Service name\n\n        Returns:\n            Final service instance\n        \"\"\"\n        if not descriptor.post_init:\n            return service\n\n        result = descriptor.post_init(self.workspace, service)\n        if asyncio.iscoroutine(result):\n            result = await result\n\n        # Capture service from post_init return value or self.services\n        if result is not None:\n            service = result\n            # Ensure it's registered in services dict\n            if name not in self.services:\n                self.services[name] = service\n        elif service is None:\n            # post_init might have registered service in self.services\n            service = self.services.get(name)\n\n        return service\n\n    async def _run_start_method(\n        self,\n        descriptor: ServiceDescriptor,\n        service: Any,\n        is_reused: bool,\n    ) -> None:\n        \"\"\"Run start method on service if applicable.\n\n        Args:\n            descriptor: Service descriptor\n            service: Service instance\n            is_reused: Whether service is being reused\n        \"\"\"\n        if is_reused or not descriptor.start_method or not service:\n            return\n\n        start_fn = getattr(service, descriptor.start_method)\n        if asyncio.iscoroutinefunction(start_fn):\n            await start_fn()\n        else:\n            start_fn()\n\n        logger.debug(\n            f\"Service '{descriptor.name}' started for \"\n            f\"{self.workspace.agent_id}\",\n        )\n\n    async def stop_all(self, final: bool = False) -> None:\n        \"\"\"Stop all services in reverse priority order.\n\n        Args:\n            final: If True, stop ALL services including reusable ones.\n                   If False (default), skip reusable services (for reload).\n\n        Reused services are skipped. Errors are logged but don't stop\n        the shutdown process.\n        \"\"\"\n        logger.debug(\n            f\"Stopping {len(self.services)} services \"\n            f\"({len(self.reused_services)} reused, final={final})\",\n        )\n\n        priority_groups = self._group_by_priority()\n\n        # Stop in reverse priority order\n        for priority in sorted(priority_groups.keys(), reverse=True):\n            descriptors = priority_groups[priority]\n\n            # Stop all services in this priority group concurrently\n            results = await asyncio.gather(\n                *[\n                    self._stop_service(desc, final=final)\n                    for desc in descriptors\n                ],\n                return_exceptions=True,\n            )\n\n            # Log any exceptions that occurred\n            for desc, result in zip(descriptors, results):\n                if isinstance(result, Exception):\n                    logger.warning(\n                        f\"Error stopping service '{desc.name}': {result}\",\n                    )\n\n    async def _stop_service(\n        self,\n        descriptor: ServiceDescriptor,\n        final: bool = False,\n    ) -> None:\n        \"\"\"Stop a single service.\n\n        Args:\n            descriptor: Service descriptor\n            final: If True, stop service even if reusable.\n                   If False, skip reusable services (for reload).\n        \"\"\"\n        name = descriptor.name\n\n        # Skip reusable services UNLESS this is final shutdown\n        # (may be transferred to new instance during reload)\n        if descriptor.reusable and not final:\n            logger.debug(\n                f\"Skipped stopping reusable service '{name}' \"\n                f\"for {self.workspace.agent_id} (will be reused)\",\n            )\n            return\n\n        # Skip services that were reused from previous instance\n        # (they don't belong to this instance)\n        if name in self.reused_services:\n            logger.debug(\n                f\"Skipped stopping reused service '{name}' \"\n                f\"(from previous instance) for {self.workspace.agent_id}\",\n            )\n            return\n\n        service = self.services.get(name)\n        if not service:\n            return\n\n        try:\n            if descriptor.stop_method:\n                stop_fn = getattr(service, descriptor.stop_method, None)\n                if stop_fn:\n                    if asyncio.iscoroutinefunction(stop_fn):\n                        await stop_fn()\n                    else:\n                        stop_fn()\n                    logger.debug(\n                        f\"Service '{name}' stopped \"\n                        f\"for {self.workspace.agent_id}\",\n                    )\n        except Exception as e:\n            logger.warning(\n                f\"Error stopping service '{name}' \"\n                f\"for {self.workspace.agent_id}: {e}\",\n            )\n            raise\n"
  },
  {
    "path": "src/copaw/app/workspace/workspace.py",
    "content": "# -*- coding: utf-8 -*-\n\"\"\"Workspace: Encapsulates a complete independent agent runtime.\n\nEach Workspace represents a standalone agent workspace with its own:\n- Runner (request processing)\n- ChannelManager (communication channels)\n- MemoryManager (conversation memory)\n- MCPClientManager (MCP tool clients)\n- CronManager (scheduled tasks)\n\nAll existing single-agent components are reused without modification.\n\"\"\"\nimport logging\nfrom pathlib import Path\nfrom typing import Optional, TYPE_CHECKING\n\nfrom .service_manager import ServiceDescriptor, ServiceManager\nfrom .service_factories import (\n    create_mcp_service,\n    create_chat_service,\n    create_channel_service,\n    create_agent_config_watcher,\n    create_mcp_config_watcher,\n)\nfrom ..runner import AgentRunner\nfrom ..runner.task_tracker import TaskTracker\nfrom ..mcp import MCPClientManager\nfrom ..crons.manager import CronManager\nfrom ..crons.repo.json_repo import JsonJobRepository\nfrom ...agents.memory import MemoryManager\nfrom ...config.config import load_agent_config\n\nif TYPE_CHECKING:\n    from ..channels.base import BaseChannel\n\nlogger = logging.getLogger(__name__)\n\n\nclass Workspace:\n    \"\"\"Single agent workspace with complete runtime components.\n\n    Each Workspace is an independent agent instance with its own:\n    - Runner: Processes agent requests\n    - ChannelManager: Manages communication channels\n    - MemoryManager: Manages conversation memory\n    - MCPClientManager: Manages MCP tool clients\n    - CronManager: Manages scheduled tasks\n\n    All components use existing single-agent code without modification.\n    \"\"\"\n\n    def __init__(self, agent_id: str, workspace_dir: str):\n        \"\"\"Initialize agent instance.\n\n        Args:\n            agent_id: Unique agent identifier\n            workspace_dir: Path to agent's workspace directory\n        \"\"\"\n        self.agent_id = agent_id\n        self.workspace_dir = Path(workspace_dir).expanduser()\n        self.workspace_dir.mkdir(parents=True, exist_ok=True)\n\n        # Service manager (unified component management)\n        self._service_manager = ServiceManager(self)\n\n        # Non-service state\n        self._config = None  # Loaded before start()\n        self._started = False\n        self._manager = None  # Reference to MultiAgentManager\n        self._task_tracker = TaskTracker()\n\n        # Register all services\n        self._register_services()\n\n        logger.debug(\n            f\"Created Workspace: {agent_id} at {self.workspace_dir}\",\n        )\n\n    # Service access via properties (delegates to ServiceManager)\n    @property\n    def runner(self) -> Optional[AgentRunner]:\n        \"\"\"Get runner instance from ServiceManager.\"\"\"\n        return self._service_manager.services.get(\"runner\")\n\n    @property\n    def memory_manager(self):\n        \"\"\"Get memory manager instance from ServiceManager.\"\"\"\n        return self._service_manager.services.get(\"memory_manager\")\n\n    @property\n    def mcp_manager(self):\n        \"\"\"Get MCP manager instance from ServiceManager.\"\"\"\n        return self._service_manager.services.get(\"mcp_manager\")\n\n    @property\n    def chat_manager(self):\n        \"\"\"Get chat manager instance from ServiceManager.\"\"\"\n        return self._service_manager.services.get(\"chat_manager\")\n\n    @property\n    def channel_manager(self):\n        \"\"\"Get channel manager instance from ServiceManager.\"\"\"\n        return self._service_manager.services.get(\"channel_manager\")\n\n    @property\n    def cron_manager(self):\n        \"\"\"Get cron manager instance from ServiceManager.\"\"\"\n        return self._service_manager.services.get(\"cron_manager\")\n\n    # Non-service state\n    @property\n    def task_tracker(self) -> TaskTracker:\n        \"\"\"Get task tracker for background chat and reconnect.\"\"\"\n        return self._task_tracker\n\n    @property\n    def config(self):\n        \"\"\"Get agent configuration.\"\"\"\n        if self._config is None:\n            self._config = load_agent_config(self.agent_id)\n        return self._config\n\n    def set_manager(self, manager) -> None:\n        \"\"\"Set reference to MultiAgentManager for /daemon restart.\n\n        Args:\n            manager: MultiAgentManager instance\n        \"\"\"\n        self._manager = manager\n        # Pass to runner for /daemon restart command\n        if self.runner is not None:\n            self.runner._manager = manager  # pylint: disable=protected-access\n\n    def _register_services(  # pylint: disable=too-many-statements\n        self,\n    ) -> None:\n        \"\"\"Register all workspace services with ServiceManager.\n\n        Uses declarative ServiceDescriptor configuration to replace\n        hardcoded initialization logic.\n        \"\"\"\n        # pylint: disable=protected-access\n        sm = self._service_manager\n\n        # Priority 10: Runner\n        sm.register(\n            ServiceDescriptor(\n                name=\"runner\",\n                service_class=AgentRunner,\n                init_args=lambda ws: {\n                    \"agent_id\": ws.agent_id,\n                    \"workspace_dir\": ws.workspace_dir,\n                },\n                stop_method=\"stop\",\n                priority=10,\n                concurrent_init=False,\n            ),\n        )\n\n        # Priority 20: Core services (concurrent)\n        sm.register(\n            ServiceDescriptor(\n                name=\"memory_manager\",\n                service_class=MemoryManager,\n                init_args=lambda ws: {\n                    \"working_dir\": str(ws.workspace_dir),\n                    \"agent_id\": ws.agent_id,\n                },\n                post_init=lambda ws, mm: setattr(\n                    ws._service_manager.services[\"runner\"],\n                    \"memory_manager\",\n                    mm,\n                ),\n                start_method=\"start\",\n                stop_method=\"close\",\n                reusable=True,\n                priority=20,\n                concurrent_init=True,\n            ),\n        )\n\n        sm.register(\n            ServiceDescriptor(\n                name=\"mcp_manager\",\n                service_class=MCPClientManager,\n                post_init=create_mcp_service,\n                stop_method=\"close_all\",\n                priority=20,\n                concurrent_init=True,\n            ),\n        )\n\n        sm.register(\n            ServiceDescriptor(\n                name=\"chat_manager\",\n                service_class=None,\n                post_init=create_chat_service,\n                reusable=True,\n                priority=20,\n                concurrent_init=True,\n            ),\n        )\n\n        # Priority 25: Runner start\n        sm.register(\n            ServiceDescriptor(\n                name=\"runner_start\",\n                service_class=None,\n                post_init=lambda ws, _: ws._service_manager.services[\n                    \"runner\"\n                ].start(),\n                priority=25,\n                concurrent_init=False,\n            ),\n        )\n\n        # Priority 30: Channel manager\n        sm.register(\n            ServiceDescriptor(\n                name=\"channel_manager\",\n                service_class=None,\n                post_init=create_channel_service,\n                start_method=\"start_all\",\n                stop_method=\"stop_all\",\n                priority=30,\n                concurrent_init=False,\n            ),\n        )\n\n        # Priority 40: Cron manager\n        sm.register(\n            ServiceDescriptor(\n                name=\"cron_manager\",\n                service_class=CronManager,\n                init_args=lambda ws: {  # pylint: disable=protected-access\n                    \"repo\": JsonJobRepository(\n                        str(ws.workspace_dir / \"jobs.json\"),\n                    ),\n                    \"runner\": ws._service_manager.services[\"runner\"],\n                    \"channel_manager\": ws._service_manager.services.get(\n                        \"channel_manager\",\n                    ),\n                    \"timezone\": \"UTC\",\n                    \"agent_id\": ws.agent_id,\n                },\n                start_method=\"start\",\n                stop_method=\"stop\",\n                priority=40,\n                concurrent_init=False,\n            ),\n        )\n\n        # Priority 50: Agent Config Watcher (conditional)\n        sm.register(\n            ServiceDescriptor(\n                name=\"agent_config_watcher\",\n                service_class=None,\n                post_init=create_agent_config_watcher,\n                start_method=\"start\",\n                stop_method=\"stop\",\n                priority=50,\n                concurrent_init=False,\n            ),\n        )\n\n        # Priority 51: MCP Config Watcher (conditional)\n        sm.register(\n            ServiceDescriptor(\n                name=\"mcp_config_watcher\",\n                service_class=None,\n                post_init=create_mcp_config_watcher,\n                start_method=\"start\",\n                stop_method=\"stop\",\n                priority=51,\n                concurrent_init=False,\n            ),\n        )\n\n    async def set_reusable_components(self, components: dict) -> None:\n        \"\"\"Set components to reuse from previous instance.\n\n        Must be called BEFORE start(). Allows reusing components that support\n        hot-reload without recreating them. If a service has a reload_func,\n        it will be called during this process.\n\n        Args:\n            components: Dict mapping component name to instance.\n                Supported keys:\n                - 'memory_manager': MemoryManager instance\n                - 'chat_manager': ChatManager instance\n\n        Example:\n            new_ws = Workspace(\"default\", workspace_dir)\n            await new_ws.set_reusable_components({\n                'memory_manager': old_ws.memory_manager,\n                'chat_manager': old_ws.chat_manager,\n            })\n            await new_ws.start()\n        \"\"\"\n        if self._started:\n            logger.warning(\n                f\"Cannot set reusable components for already started \"\n                f\"workspace: {self.agent_id}\",\n            )\n            return\n\n        # Delegate to ServiceManager\n        for name, component in components.items():\n            await self._service_manager.set_reusable(name, component)\n\n    async def start(self):\n        \"\"\"Start workspace and initialize all components.\"\"\"\n        if self._started:\n            logger.debug(f\"Workspace already started: {self.agent_id}\")\n            return\n\n        logger.info(f\"Starting workspace: {self.agent_id}\")\n\n        try:\n            # 1. Load agent configuration\n            self._config = load_agent_config(self.agent_id)\n            logger.debug(f\"Loaded config for agent: {self.agent_id}\")\n\n            # 2. Start all services via ServiceManager\n            await self._service_manager.start_all()\n\n            self._started = True\n            logger.info(f\"Workspace started successfully: {self.agent_id}\")\n\n        except Exception as e:\n            logger.error(\n                f\"Failed to start agent instance {self.agent_id}: {e}\",\n            )\n            # Clean up partially started components\n            await self.stop()\n            raise\n\n    async def stop(self, final: bool = True):\n        \"\"\"Stop agent instance and clean up all resources.\n\n        Args:\n            final: If True (default), stop ALL services including reusable.\n                   If False, skip reusable services (for reload scenario).\n        \"\"\"\n        if not self._started:\n            logger.debug(f\"Workspace not started: {self.agent_id}\")\n            return\n\n        logger.info(\n            f\"Stopping agent instance: {self.agent_id} (final={final})\",\n        )\n\n        # Stop all services via ServiceManager (handles reuse automatically)\n        await self._service_manager.stop_all(final=final)\n\n        self._started = False\n        logger.info(f\"Workspace stopped: {self.agent_id}\")\n\n    def __repr__(self) -> str:\n        \"\"\"String representation of workspace.\"\"\"\n        status = \"started\" if self._started else \"stopped\"\n        return (\n            f\"Workspace(id={self.agent_id}, \"\n            f\"workspace={self.workspace_dir}, \"\n            f\"status={status})\"\n        )\n"
  },
  {
    "path": "src/copaw/cli/__init__.py",
    "content": ""
  },
  {
    "path": "src/copaw/cli/app_cmd.py",
    "content": "# -*- coding: utf-8 -*-\nfrom __future__ import annotations\n\nimport logging\nimport os\n\nimport click\nimport uvicorn\n\nfrom ..constant import LOG_LEVEL_ENV\nfrom ..config.utils import write_last_api\nfrom ..utils.logging import setup_logger, SuppressPathAccessLogFilter\n\n\n@click.command(\"app\")\n@click.option(\n    \"--host\",\n    default=\"127.0.0.1\",\n    show_default=True,\n    help=\"Bind host\",\n)\n@click.option(\n    \"--port\",\n    default=8088,\n    type=int,\n    show_default=True,\n    help=\"Bind port\",\n)\n@click.option(\"--reload\", is_flag=True, help=\"Enable auto-reload (dev only)\")\n@click.option(\n    \"--workers\",\n    default=1,\n    type=int,\n    show_default=True,\n    help=\"Worker processes\",\n)\n@click.option(\n    \"--log-level\",\n    default=\"info\",\n    type=click.Choice(\n        [\"critical\", \"error\", \"warning\", \"info\", \"debug\", \"trace\"],\n        case_sensitive=False,\n    ),\n    show_default=True,\n    help=\"Log level\",\n)\n@click.option(\n    \"--hide-access-paths\",\n    multiple=True,\n    default=(\"/console/push-messages\",),\n    show_default=True,\n    help=\"Path substrings to hide from uvicorn access log (repeatable).\",\n)\ndef app_cmd(\n    host: str,\n    port: int,\n    reload: bool,\n    workers: int,\n    log_level: str,\n    hide_access_paths: tuple[str, ...],\n) -> None:\n    \"\"\"Run CoPaw FastAPI app.\"\"\"\n    # Persist last used host/port for other terminals\n    write_last_api(host, port)\n    os.environ[LOG_LEVEL_ENV] = log_level\n\n    # Signal reload mode to browser_control.py for Windows\n    # compatibility: use sync Playwright + ThreadPool only when reload=True\n    if reload:\n        os.environ[\"COPAW_RELOAD_MODE\"] = \"1\"\n    else:\n        os.environ.pop(\"COPAW_RELOAD_MODE\", None)\n\n    setup_logger(log_level)\n    if log_level in (\"debug\", \"trace\"):\n        from .main import log_init_timings\n\n        log_init_timings()\n\n    paths = [p for p in hide_access_paths if p]\n    if paths:\n        logging.getLogger(\"uvicorn.access\").addFilter(\n            SuppressPathAccessLogFilter(paths),\n        )\n\n    uvicorn.run(\n        \"copaw.app._app:app\",\n        host=host,\n        port=port,\n        reload=reload,\n        workers=workers,\n        log_level=log_level,\n    )\n"
  },
  {
    "path": "src/copaw/cli/auth_cmd.py",
    "content": "# -*- coding: utf-8 -*-\nfrom __future__ import annotations\n\nimport secrets\n\nimport click\n\nfrom ..app.auth import (\n    _hash_password,\n    _load_auth_data,\n    _save_auth_data,\n    is_auth_enabled,\n)\n\n\n@click.group(\"auth\", help=\"Manage web authentication.\")\ndef auth_group() -> None:\n    \"\"\"Manage web authentication.\"\"\"\n\n\n@auth_group.command(\"reset-password\")\ndef reset_password_cmd() -> None:\n    \"\"\"Reset the password for the registered web user.\"\"\"\n    if not is_auth_enabled():\n        click.echo(\n            \"Authentication is not enabled.\\n\"\n            \"Set COPAW_AUTH_ENABLED=true to enable it first.\",\n        )\n        return\n\n    data = _load_auth_data()\n\n    if data.get(\"_auth_load_error\"):\n        raise click.ClickException(\n            \"Failed to read auth data. Check auth.json for corruption.\",\n        )\n\n    user = data.get(\"user\")\n    if not user:\n        click.echo(\"No registered user found. Nothing to reset.\")\n        return\n\n    username = user.get(\"username\", \"\")\n    click.echo(f\"Resetting password for user: {username}\")\n\n    new_password = click.prompt(\n        \"New password\",\n        hide_input=True,\n        confirmation_prompt=True,\n    )\n\n    if not new_password or not new_password.strip():\n        raise click.ClickException(\"Password cannot be empty.\")\n\n    pw_hash, salt = _hash_password(new_password)\n    data[\"user\"][\"password_hash\"] = pw_hash\n    data[\"user\"][\"password_salt\"] = salt\n\n    # Invalidate existing tokens by rotating jwt_secret\n    data[\"jwt_secret\"] = secrets.token_hex(32)\n\n    _save_auth_data(data)\n    click.echo(\n        \"✓ Password reset successfully. \"\n        \"All existing sessions have been invalidated.\",\n    )\n"
  },
  {
    "path": "src/copaw/cli/channels_cmd.py",
    "content": "# -*- coding: utf-8 -*-\n\"\"\"CLI channel: list and interactively configure channels in config.json.\"\"\"\nfrom __future__ import annotations\n\nfrom types import SimpleNamespace\nfrom pathlib import Path\n\nimport click\n\nfrom ..config import (\n    get_config_path,\n    load_config,\n    save_config,\n)\nfrom ..config.config import (\n    Config,\n    ConsoleConfig,\n    DiscordConfig,\n    TelegramConfig,\n    DingTalkConfig,\n    FeishuConfig,\n    IMessageChannelConfig,\n    QQConfig,\n    VoiceChannelConfig,\n    load_agent_config,\n    save_agent_config,\n)\nfrom .utils import prompt_confirm, prompt_path, prompt_select\nfrom ..config import get_available_channels\nfrom ..constant import CUSTOM_CHANNELS_DIR\nfrom ..app.channels.registry import (\n    BUILTIN_CHANNEL_KEYS,\n    get_channel_registry,\n)\n\n\n# Fields that contain secrets — display masked in ``list``\n_SECRET_FIELDS = {\n    \"bot_token\",\n    \"client_secret\",\n    \"app_secret\",\n    \"http_proxy_auth\",\n    \"twilio_auth_token\",\n}\n\n_ALL_CHANNEL_NAMES = {\n    \"imessage\": \"iMessage\",\n    \"discord\": \"Discord\",\n    \"telegram\": \"Telegram\",\n    \"dingtalk\": \"DingTalk\",\n    \"feishu\": \"Feishu\",\n    \"qq\": \"QQ\",\n    \"console\": \"Console\",\n    \"voice\": \"Twilio\",\n}\n# Public alias for tests and external use.\nCHANNEL_NAMES = _ALL_CHANNEL_NAMES\n\n# Template for `copaw channels install ` stub (channel key substituted).\nCHANNEL_TEMPLATE = '''# -*- coding: utf-8 -*-\n\"\"\"Custom channel: {key}. Edit and implement required methods.\"\"\"\nfrom __future__ import annotations\n\nimport os\nfrom typing import Any\n\nfrom agentscope_runtime.engine.schemas.agent_schemas import (\n    TextContent,\n    ContentType,\n)\n\nfrom copaw.app.channels.base import BaseChannel\nfrom copaw.app.channels.schema import ChannelType\n\n\nclass CustomChannel(BaseChannel):\n    channel: ChannelType = \"{key}\"\n\n    def __init__(\n        self,\n        process,\n        enabled=True,\n        bot_prefix=\"\",\n        on_reply_sent=None,\n        show_tool_details=True,\n        filter_tool_messages=False,\n        filter_thinking=False,\n        **kwargs,\n    ):\n        super().__init__(\n            process,\n            on_reply_sent=on_reply_sent,\n            show_tool_details=show_tool_details,\n            filter_tool_messages=filter_tool_messages,\n            filter_thinking=filter_thinking,\n        )\n        self.enabled = enabled\n        self.bot_prefix = bot_prefix or \"\"\n\n    @classmethod\n    def from_config(\n        cls,\n        process,\n        config,\n        on_reply_sent=None,\n        show_tool_details=True,\n        **kwargs,\n    ):\n        return cls(\n            process=process,\n            enabled=getattr(config, \"enabled\", True),\n            bot_prefix=getattr(config, \"bot_prefix\", \"\"),\n            on_reply_sent=on_reply_sent,\n            show_tool_details=show_tool_details,\n            filter_tool_messages=kwargs.get(\n                \"filter_tool_messages\",\n                getattr(config, \"filter_tool_messages\", False),\n            ),\n            filter_thinking=kwargs.get(\n                \"filter_thinking\",\n                getattr(config, \"filter_thinking\", False),\n            ),\n        )\n\n    @classmethod\n    def from_env(cls, process, on_reply_sent=None):\n        return cls(process=process, on_reply_sent=on_reply_sent)\n\n    def build_agent_request_from_native(self, native_payload: Any):\n        payload = native_payload if isinstance(native_payload, dict) else {{}}\n        channel_id = payload.get(\"channel_id\") or self.channel\n        sender_id = payload.get(\"sender_id\") or \"\"\n        meta = payload.get(\"meta\") or {{}}\n        session_id = self.resolve_session_id(sender_id, meta)\n        text = payload.get(\"text\", \"\")\n        content_parts = [TextContent(type=ContentType.TEXT, text=text)]\n        request = self.build_agent_request_from_user_content(\n            channel_id=channel_id,\n            sender_id=sender_id,\n            session_id=session_id,\n            content_parts=content_parts,\n            channel_meta=meta,\n        )\n        request.channel_meta = meta\n        return request\n\n    async def start(self):\n        pass\n\n    async def stop(self):\n        pass\n\n    async def send(self, to_handle: str, text: str, meta=None):\n        # Implement: send text to the channel (e.g. HTTP API).\n        pass\n'''\n\n\ndef _get_channel_names() -> dict[str, str]:\n    \"\"\"Return channel key -> display name (built-in + plugins).\"\"\"\n    available = get_available_channels()\n    registry = get_channel_registry()\n    out = {k: v for k, v in _ALL_CHANNEL_NAMES.items() if k in available}\n    for key in available:\n        if key not in out and key in registry:\n            cls = registry[key]\n            out[key] = (\n                getattr(cls, \"display_name\", None)\n                or key.replace(\n                    \"_\",\n                    \" \",\n                ).title()\n            )\n    return out\n\n\ndef _mask(value: str) -> str:\n    \"\"\"Mask a secret value, keeping first 4 chars visible.\"\"\"\n    if not value:\n        return \"(empty)\"\n    if len(value) <= 4:\n        return \"****\"\n    return value[:4] + \"****\"\n\n\n# ── per-channel interactive configurators ──────────────────────────\n\n\ndef configure_imessage(\n    current_config: IMessageChannelConfig,\n) -> IMessageChannelConfig:\n    \"\"\"Configure iMessage channel interactively.\"\"\"\n    click.echo(\"\\n=== Configure iMessage Channel ===\")\n\n    enabled = prompt_confirm(\n        \"Enable iMessage channel?\",\n        default=current_config.enabled,\n    )\n\n    if not enabled:\n        current_config.enabled = False\n        return current_config\n\n    current_config.enabled = True\n\n    bot_prefix = click.prompt(\n        \"Bot prefix (e.g., @bot)\",\n        default=current_config.bot_prefix or \"[BOT]\",\n        type=str,\n    )\n    current_config.bot_prefix = bot_prefix\n\n    db_path = prompt_path(\n        \"iMessage database path\",\n        default=current_config.db_path or \"~/Library/Messages/chat.db\",\n    )\n    current_config.db_path = db_path\n\n    poll_sec = click.prompt(\n        \"Poll interval (seconds)\",\n        default=current_config.poll_sec,\n        type=float,\n    )\n    current_config.poll_sec = poll_sec\n\n    return current_config\n\n\ndef configure_discord(current_config: DiscordConfig) -> DiscordConfig:\n    \"\"\"Configure Discord channel interactively.\"\"\"\n    click.echo(\"\\n=== Configure Discord Channel ===\")\n\n    enabled = prompt_confirm(\n        \"Enable Discord channel?\",\n        default=current_config.enabled,\n    )\n\n    if not enabled:\n        current_config.enabled = False\n        return current_config\n\n    current_config.enabled = True\n\n    bot_prefix = click.prompt(\n        \"Bot prefix (e.g., @bot)\",\n        default=current_config.bot_prefix or \"[BOT]\",\n        type=str,\n    )\n    current_config.bot_prefix = bot_prefix\n\n    bot_token = click.prompt(\n        \"Discord Bot Token\",\n        default=current_config.bot_token or \"\",\n        hide_input=True,\n        type=str,\n    )\n    current_config.bot_token = bot_token\n\n    use_proxy = prompt_confirm(\n        \"Use HTTP proxy?\",\n        default=bool(current_config.http_proxy),\n    )\n\n    if use_proxy:\n        http_proxy = click.prompt(\n            \"HTTP proxy address (e.g., http://127.0.0.1:7890)\",\n            default=current_config.http_proxy or \"\",\n            type=str,\n        )\n        current_config.http_proxy = http_proxy\n\n        use_proxy_auth = prompt_confirm(\n            \"Does proxy require authentication?\",\n            default=bool(current_config.http_proxy_auth),\n        )\n\n        if use_proxy_auth:\n            http_proxy_auth = click.prompt(\n                \"Proxy authentication (format: username:password)\",\n                default=current_config.http_proxy_auth or \"\",\n                hide_input=True,\n                type=str,\n            )\n            current_config.http_proxy_auth = http_proxy_auth\n        else:\n            current_config.http_proxy_auth = \"\"\n    else:\n        current_config.http_proxy = \"\"\n        current_config.http_proxy_auth = \"\"\n\n    return current_config\n\n\ndef configure_dingtalk(current_config: DingTalkConfig) -> DingTalkConfig:\n    \"\"\"Configure DingTalk channel interactively.\"\"\"\n    click.echo(\"\\n=== Configure DingTalk Channel ===\")\n\n    enabled = prompt_confirm(\n        \"Enable DingTalk channel?\",\n        default=current_config.enabled,\n    )\n\n    if not enabled:\n        current_config.enabled = False\n        return current_config\n\n    current_config.enabled = True\n\n    bot_prefix = click.prompt(\n        \"Bot prefix (e.g., @bot)\",\n        default=current_config.bot_prefix or \"[BOT]\",\n        type=str,\n    )\n    current_config.bot_prefix = bot_prefix\n\n    client_id = click.prompt(\n        \"DingTalk Client ID\",\n        default=current_config.client_id or \"\",\n        type=str,\n    )\n    current_config.client_id = client_id\n\n    client_secret = click.prompt(\n        \"DingTalk Client Secret\",\n        default=current_config.client_secret or \"\",\n        hide_input=True,\n        type=str,\n    )\n    current_config.client_secret = client_secret\n\n    return current_config\n\n\ndef configure_feishu(current_config: FeishuConfig) -> FeishuConfig:\n    \"\"\"Configure Feishu channel interactively.\"\"\"\n    click.echo(\"\\n=== Configure Feishu Channel ===\")\n\n    enabled = prompt_confirm(\n        \"Enable Feishu channel?\",\n        default=current_config.enabled,\n    )\n\n    if not enabled:\n        current_config.enabled = False\n        return current_config\n\n    current_config.enabled = True\n\n    bot_prefix = click.prompt(\n        \"Bot prefix (e.g., @bot)\",\n        default=current_config.bot_prefix or \"[BOT]\",\n        type=str,\n    )\n    current_config.bot_prefix = bot_prefix\n\n    app_id = click.prompt(\n        \"Feishu App ID\",\n        default=current_config.app_id or \"\",\n        type=str,\n    )\n    current_config.app_id = app_id\n\n    app_secret = click.prompt(\n        \"Feishu App Secret\",\n        default=current_config.app_secret or \"\",\n        hide_input=True,\n        type=str,\n    )\n    current_config.app_secret = app_secret\n\n    return current_config\n\n\ndef configure_qq(current_config: QQConfig) -> QQConfig:\n    \"\"\"Configure QQ channel interactively.\"\"\"\n    click.echo(\"\\n=== Configure QQ Channel ===\")\n\n    enabled = prompt_confirm(\n        \"Enable QQ channel?\",\n        default=current_config.enabled,\n    )\n\n    if not enabled:\n        current_config.enabled = False\n        return current_config\n\n    current_config.enabled = True\n\n    bot_prefix = click.prompt(\n        \"Bot prefix (e.g., @bot)\",\n        default=current_config.bot_prefix or \"[BOT]\",\n        type=str,\n    )\n    current_config.bot_prefix = bot_prefix\n\n    app_id = click.prompt(\n        \"QQ App ID\",\n        default=current_config.app_id or \"\",\n        type=str,\n    )\n    current_config.app_id = app_id\n\n    client_secret = click.prompt(\n        \"QQ Client Secret\",\n        default=current_config.client_secret or \"\",\n        hide_input=True,\n        type=str,\n    )\n    current_config.client_secret = client_secret\n\n    markdown_enabled = prompt_confirm(\n        \"Enable QQ markdown replies?\",\n        default=current_config.markdown_enabled,\n    )\n    current_config.markdown_enabled = markdown_enabled\n\n    return current_config\n\n\ndef configure_telegram(current_config: TelegramConfig) -> TelegramConfig:\n    \"\"\"Configure Telegram channel interactively.\"\"\"\n    click.echo(\"\\n=== Configure Telegram Channel ===\")\n\n    enabled = prompt_confirm(\n        \"Enable Telegram channel?\",\n        default=current_config.enabled,\n    )\n\n    if not enabled:\n        current_config.enabled = False\n        return current_config\n\n    current_config.enabled = True\n\n    bot_prefix = click.prompt(\n        \"Bot prefix (e.g., @bot)\",\n        default=current_config.bot_prefix or \"[BOT]\",\n        type=str,\n    )\n    current_config.bot_prefix = bot_prefix\n\n    bot_token = click.prompt(\n        \"Telegram Bot Token\",\n        default=current_config.bot_token or \"\",\n        hide_input=True,\n        type=str,\n    )\n    token = bot_token.strip()\n    current_config.bot_token = token\n    if not token:\n        click.echo(\"Warning: Empty bot token provided.\")\n        click.echo(\"Disabling Telegram channel.\")\n        current_config.enabled = False\n        return current_config\n\n    show_typing = prompt_confirm(\n        \"Show typing indicator?\",\n        default=current_config.show_typing is not False,\n    )\n    current_config.show_typing = show_typing\n\n    use_proxy = prompt_confirm(\n        \"Use HTTP proxy?\",\n        default=bool(current_config.http_proxy),\n    )\n\n    if use_proxy:\n        http_proxy = click.prompt(\n            \"HTTP proxy address (e.g., http://127.0.0.1:7890)\",\n            default=current_config.http_proxy or \"\",\n            type=str,\n        )\n        current_config.http_proxy = http_proxy\n\n        use_proxy_auth = prompt_confirm(\n            \"Does proxy require authentication?\",\n            default=bool(current_config.http_proxy_auth),\n        )\n\n        if use_proxy_auth:\n            http_proxy_auth = click.prompt(\n                \"Proxy authentication (format: username:password)\",\n                default=current_config.http_proxy_auth or \"\",\n                hide_input=True,\n                type=str,\n            )\n            current_config.http_proxy_auth = http_proxy_auth\n        else:\n            current_config.http_proxy_auth = \"\"\n    else:\n        current_config.http_proxy = \"\"\n        current_config.http_proxy_auth = \"\"\n\n    return current_config\n\n\ndef configure_voice(\n    current_config: VoiceChannelConfig,\n) -> VoiceChannelConfig:\n    \"\"\"Configure Twilio voice channel interactively.\"\"\"\n    click.echo(\"\\n=== Configure Twilio Channel ===\")\n\n    enabled = prompt_confirm(\n        \"Enable Twilio channel?\",\n        default=current_config.enabled,\n    )\n\n    if not enabled:\n        current_config.enabled = False\n        return current_config\n\n    current_config.enabled = True\n\n    # — Twilio credentials —\n\n    twilio_account_sid = click.prompt(\n        \"Twilio Account SID\",\n        default=current_config.twilio_account_sid or \"\",\n        type=str,\n    )\n    current_config.twilio_account_sid = twilio_account_sid\n\n    twilio_auth_token = click.prompt(\n        \"Twilio Auth Token\",\n        default=current_config.twilio_auth_token or \"\",\n        hide_input=True,\n        type=str,\n    )\n    current_config.twilio_auth_token = twilio_auth_token\n\n    # — Phone number (may be blank if provisioning later via API) —\n\n    phone_number = click.prompt(\n        \"Phone number (e.g., +15551234567, blank to provision later)\",\n        default=current_config.phone_number or \"\",\n        type=str,\n    )\n    current_config.phone_number = phone_number\n\n    phone_number_sid = click.prompt(\n        \"Phone Number SID (e.g., PN..., blank to provision later)\",\n        default=current_config.phone_number_sid or \"\",\n        type=str,\n    )\n    current_config.phone_number_sid = phone_number_sid\n\n    # — TTS / STT settings —\n\n    configure_tts = prompt_confirm(\n        \"Configure TTS/STT settings? (default: Google TTS + Deepgram STT)\",\n        default=False,\n    )\n\n    if configure_tts:\n        tts_provider = click.prompt(\n            \"TTS provider\",\n            default=current_config.tts_provider or \"google\",\n            type=str,\n        )\n        current_config.tts_provider = tts_provider\n\n        tts_voice = click.prompt(\n            \"TTS voice\",\n            default=current_config.tts_voice or \"en-US-Journey-D\",\n            type=str,\n        )\n        current_config.tts_voice = tts_voice\n\n        stt_provider = click.prompt(\n            \"STT provider\",\n            default=current_config.stt_provider or \"deepgram\",\n            type=str,\n        )\n        current_config.stt_provider = stt_provider\n\n        language = click.prompt(\n            \"Language\",\n            default=current_config.language or \"en-US\",\n            type=str,\n        )\n        current_config.language = language\n\n    # — Welcome greeting —\n\n    welcome_greeting = click.prompt(\n        \"Welcome greeting\",\n        default=current_config.welcome_greeting\n        or \"Hi! This is CoPaw. How can I help you?\",\n        type=str,\n    )\n    current_config.welcome_greeting = welcome_greeting\n\n    return current_config\n\n\ndef configure_console(current_config: ConsoleConfig) -> ConsoleConfig:\n    \"\"\"Configure Console channel interactively.\"\"\"\n    click.echo(\"\\n=== Configure Console Channel ===\")\n\n    enabled = prompt_confirm(\n        \"Enable Console channel?\",\n        default=current_config.enabled,\n    )\n\n    if not enabled:\n        current_config.enabled = False\n        return current_config\n\n    current_config.enabled = True\n\n    bot_prefix = click.prompt(\n        \"Bot prefix (e.g., [BOT])\",\n        default=current_config.bot_prefix or \"[BOT] \",\n        type=str,\n    )\n    current_config.bot_prefix = bot_prefix\n\n    return current_config\n\n\n# ── reusable channel configuration flow (used by init_cmd too) ─────\n\n# Full registry — filtered at runtime by get_channel_configurators().\n_ALL_CHANNEL_CONFIGURATORS = {\n    \"imessage\": (\"iMessage\", configure_imessage),\n    \"discord\": (\"Discord\", configure_discord),\n    \"telegram\": (\"Telegram\", configure_telegram),\n    \"dingtalk\": (\"DingTalk\", configure_dingtalk),\n    \"feishu\": (\"Feishu\", configure_feishu),\n    \"qq\": (\"QQ\", configure_qq),\n    \"console\": (\"Console\", configure_console),\n    \"voice\": (\"Twilio\", configure_voice),\n}\n\n\ndef _plugin_configure(\n    _key: str,\n    configurator,\n    current,\n):\n    \"\"\"Run plugin configurator; accept/return dict or object.\"\"\"\n    if isinstance(current, dict):\n        cur_ns = SimpleNamespace(**current)\n    else:\n        cur_ns = current\n    out = configurator(cur_ns)\n    if out is None:\n        return current\n    if hasattr(out, \"__dict__\"):\n        return vars(out)\n    if isinstance(out, dict):\n        return out\n    return current\n\n\ndef get_channel_configurators() -> dict:\n    \"\"\"Return channel configurators (built-in + plugin get_configurator).\"\"\"\n    available = get_available_channels()\n    registry = get_channel_registry()\n    out = {\n        k: v for k, v in _ALL_CHANNEL_CONFIGURATORS.items() if k in available\n    }\n\n    def _default_plugin_configure(current):\n        \"\"\"Minimal configurator: enabled + bot_prefix.\"\"\"\n\n        def _get(obj, k, default=None):\n            return (\n                obj.get(k, default)\n                if isinstance(obj, dict)\n                else getattr(\n                    obj,\n                    k,\n                    default,\n                )\n            )\n\n        def _set(obj, k, v):\n            if isinstance(obj, dict):\n                obj[k] = v\n            else:\n                setattr(obj, k, v)\n\n        enabled = _get(current, \"enabled\", False)\n        _set(\n            current,\n            \"enabled\",\n            prompt_confirm(\"Enable this channel?\", default=enabled),\n        )\n        prefix = _get(current, \"bot_prefix\", \"\") or \"[BOT]\"\n        _set(\n            current,\n            \"bot_prefix\",\n            click.prompt(\"Bot prefix (e.g. [BOT])\", default=prefix, type=str),\n        )\n        return current\n\n    for key in available:\n        if key in out:\n            continue\n        ch_cls = registry.get(key)\n        if ch_cls is None:\n            continue\n        display = (\n            getattr(ch_cls, \"display_name\", None)\n            or key.replace(\n                \"_\",\n                \" \",\n            ).title()\n        )\n        configurator = getattr(ch_cls, \"get_configurator\", None)\n        if callable(configurator):\n            configurator = configurator()\n        if not callable(configurator):\n            configurator = _default_plugin_configure\n\n        def _wrap(cf, k=key):\n            def _run(current):\n                return _plugin_configure(k, cf, current)\n\n            return _run\n\n        out[key] = (display, _wrap(configurator))\n    return out\n\n\ndef _get_channel_config(config: Config, key: str):\n    \"\"\"Get channel config for key (from attr or extra).\"\"\"\n    ch = getattr(config.channels, key, None)\n    if ch is not None:\n        return ch\n    extra = getattr(config.channels, \"__pydantic_extra__\", None) or {}\n    return extra.get(key)\n\n\ndef configure_channels_interactive(config: Config) -> None:\n    \"\"\"Run the interactive channel selection / configuration loop.\n\n    Mutates *config.channels* in-place.\n    \"\"\"\n    configurators = get_channel_configurators()\n    registry = get_channel_registry()\n    click.echo(\"\\n=== Channel Configuration ===\")\n\n    while True:\n        channel_choices: list[tuple[str, str]] = []\n        for channel_key, (channel_name, _) in configurators.items():\n            channel_config = _get_channel_config(config, channel_key)\n            status = \"✓\" if _channel_enabled(channel_config) else \"✗\"\n            channel_choices.append(\n                (f\"{channel_name} [{status}]\", channel_key),\n            )\n        channel_choices.append((\"Save and exit\", \"exit\"))\n\n        click.echo()\n        choice = prompt_select(\n            \"Select a channel to configure:\",\n            options=channel_choices,\n        )\n\n        if choice is None:\n            click.echo(\"\\n\\nOperation cancelled.\")\n            return\n\n        if choice == \"exit\":\n            break\n\n        channel_name, configure_func = configurators[choice]\n        current_config = _get_channel_config(config, choice)\n        if current_config is None:\n            ch_cls = registry.get(choice)\n            default = (\n                getattr(ch_cls, \"get_default_config\", lambda: None)()\n                if ch_cls\n                else None\n            )\n            current_config = default or {\"enabled\": False, \"bot_prefix\": \"\"}\n        updated_config = configure_func(current_config)\n        setattr(config.channels, choice, updated_config)\n\n    # Show enabled channels summary\n    enabled_channels = [\n        name\n        for key, (name, _) in configurators.items()\n        if _channel_enabled(_get_channel_config(config, key))\n    ]\n\n    if enabled_channels:\n        click.echo(\n            f\"\\n✓ Enabled channels: {', '.join(enabled_channels)}\",\n        )\n    else:\n        click.echo(\"\\n⚠ Warning: No channels enabled!\")\n\n\n# ── CLI commands ───────────────────────────────────────────────────\n\n\n@click.group(\"channels\")\ndef channels_group() -> None:\n    \"\"\"Manage channel configuration\n    (iMessage/Discord/DingTalk/Feishu/QQ/Console).\"\"\"\n\n\ndef _channel_config_fields(ch):\n    \"\"\"Yield (field_name, value) for a channel config (model or dict).\"\"\"\n    if hasattr(ch, \"model_fields\"):\n        for fn in ch.model_fields:\n            if fn == \"enabled\":\n                continue\n            yield (fn, getattr(ch, fn))\n    elif isinstance(ch, dict):\n        for k, v in ch.items():\n            if k == \"enabled\":\n                continue\n            yield (k, v)\n    elif hasattr(ch, \"__dict__\"):\n        for k, v in vars(ch).items():\n            if k == \"enabled\":\n                continue\n            yield (k, v)\n\n\ndef _channel_enabled(ch) -> bool:\n    \"\"\"Whether channel config has enabled=True.\"\"\"\n    if ch is None:\n        return False\n    if hasattr(ch, \"enabled\"):\n        return bool(ch.enabled)\n    if isinstance(ch, dict):\n        return bool(ch.get(\"enabled\", False))\n    return False\n\n\n@channels_group.command(\"list\")\n@click.option(\n    \"--agent-id\",\n    default=\"default\",\n    help=\"Agent ID (defaults to 'default')\",\n)\ndef list_cmd(agent_id: str) -> None:\n    \"\"\"Show current channel configuration.\"\"\"\n    try:\n        agent_config = load_agent_config(agent_id)\n        click.echo(f\"Channels for agent: {agent_id}\\n\")\n\n        if not agent_config.channels:\n            click.echo(\"No channels configured for this agent.\")\n            return\n\n        extra = (\n            getattr(agent_config.channels, \"__pydantic_extra__\", None) or {}\n        )\n        for key, name in _get_channel_names().items():\n            ch = getattr(agent_config.channels, key, None)\n            if ch is None:\n                ch = extra.get(key)\n            if ch is None:\n                continue\n            status = (\n                click.style(\"enabled\", fg=\"green\")\n                if _channel_enabled(ch)\n                else click.style(\"disabled\", fg=\"red\")\n            )\n            click.echo(f\"\\n{'─' * 40}\")\n            click.echo(f\"  {name}  [{status}]\")\n            click.echo(f\"{'─' * 40}\")\n\n            for field_name, value in _channel_config_fields(ch):\n                display = (\n                    _mask(str(value))\n                    if field_name in _SECRET_FIELDS\n                    else value\n                )\n                click.echo(f\"  {field_name:20s}: {display}\")\n\n        click.echo()\n    except ValueError as e:\n        click.echo(f\"Error: {e}\", err=True)\n        raise SystemExit(1) from e\n\n\ndef _install_channel_to_dir(\n    key: str,\n    from_path: str | None = None,\n    from_url: str | None = None,\n) -> None:\n    \"\"\"Write channel module to CUSTOM_CHANNELS_DIR (template or copy).\"\"\"\n    CUSTOM_CHANNELS_DIR.mkdir(parents=True, exist_ok=True)\n    if not key.isidentifier():\n        click.echo(\n            f\"Key must be a valid Python identifier (e.g. my_channel), \"\n            f\"got: {key}\",\n            err=True,\n        )\n        raise SystemExit(1)\n\n    dest_file = CUSTOM_CHANNELS_DIR / f\"{key}.py\"\n    dest_dir = CUSTOM_CHANNELS_DIR / key\n\n    if from_path:\n        src = Path(from_path).resolve()\n        if not src.exists():\n            click.echo(f\"Path not found: {src}\", err=True)\n            raise SystemExit(1)\n        if src.is_file():\n            import shutil\n\n            shutil.copy2(src, dest_file)\n            click.echo(f\"✓ Installed {key}.py from {src}\")\n        else:\n            import shutil\n\n            if dest_dir.exists():\n                shutil.rmtree(dest_dir)\n            shutil.copytree(src, dest_dir)\n            click.echo(f\"✓ Installed {key}/ from {src}\")\n        return\n\n    if from_url:\n        import urllib.request\n\n        try:\n            with urllib.request.urlopen(from_url) as resp:\n                body = resp.read().decode(\"utf-8\", errors=\"replace\")\n        except Exception as e:\n            click.echo(f\"Failed to fetch URL: {e}\", err=True)\n            raise SystemExit(1) from e\n        dest_file.write_text(body, encoding=\"utf-8\")\n        click.echo(f\"✓ Installed {key}.py from URL\")\n        return\n\n    if dest_file.exists() or dest_dir.exists():\n        click.echo(\n            f\"Channel '{key}' already exists in {CUSTOM_CHANNELS_DIR}. \"\n            \"Edit the file or use --path/--url to overwrite.\",\n            err=True,\n        )\n        raise SystemExit(1)\n\n    dest_file.write_text(\n        CHANNEL_TEMPLATE.format(key=key),\n        encoding=\"utf-8\",\n    )\n    click.echo(\n        f\"✓ Created {dest_file}. Edit and add config with \"\n        \"`copaw channels config`.\",\n    )\n\n\n@channels_group.command(\"install\")\n@click.argument(\"key\", required=True)\n@click.option(\n    \"--path\",\n    \"from_path\",\n    type=click.Path(exists=True),\n    help=\"Copy channel from local path (file or dir).\",\n)\n@click.option(\n    \"--url\",\n    \"from_url\",\n    type=str,\n    help=\"Download channel module from URL (.py file).\",\n)\ndef install_cmd(key: str, from_path: str | None, from_url: str | None) -> None:\n    \"\"\"Install a channel into the working dir (custom_channels/). Creates a\n    stub module you can edit, or use --path/--url to copy from elsewhere.\n    Manager loads channels from this directory at runtime.\n    \"\"\"\n    _install_channel_to_dir(key, from_path=from_path, from_url=from_url)\n\n\n@channels_group.command(\"add\")\n@click.argument(\"key\", required=True)\n@click.option(\n    \"--path\",\n    \"from_path\",\n    type=click.Path(exists=True),\n    help=\"Copy channel from local path (file or dir).\",\n)\n@click.option(\n    \"--url\",\n    \"from_url\",\n    type=str,\n    help=\"Download channel module from URL (.py file).\",\n)\n@click.option(\n    \"--configure/--no-configure\",\n    default=True,\n    help=\"Run interactive configurator after adding to config.\",\n)\ndef add_cmd(\n    key: str,\n    from_path: str | None,\n    from_url: str | None,\n    configure: bool,\n) -> None:\n    \"\"\"Install channel to custom_channels/ and add to config. For built-in\n    channels only adds to config; for custom, installs (stub or --path/--url)\n    then adds to config.\n    \"\"\"\n    dest_file = CUSTOM_CHANNELS_DIR / f\"{key}.py\"\n    dest_dir = CUSTOM_CHANNELS_DIR / key\n    already_in_dir = dest_file.exists() or dest_dir.exists()\n    is_builtin = key in BUILTIN_CHANNEL_KEYS\n\n    if not is_builtin and (from_path or from_url or not already_in_dir):\n        _install_channel_to_dir(key, from_path=from_path, from_url=from_url)\n\n    config_path = get_config_path()\n    config_path.parent.mkdir(parents=True, exist_ok=True)\n    existing = load_config(config_path) if config_path.is_file() else Config()\n    current = _get_channel_config(existing, key)\n\n    if current is None:\n        default = {\"enabled\": False, \"bot_prefix\": \"\"}\n        setattr(existing.channels, key, default)\n        if configure:\n            configurators = get_channel_configurators()\n            if key in configurators:\n                _, configure_func = configurators[key]\n                updated = configure_func(default)\n                setattr(existing.channels, key, updated)\n        save_config(existing, config_path)\n        click.echo(f\"✓ Added '{key}' to config at {config_path}\")\n\n\n@channels_group.command(\"remove\")\n@click.argument(\"key\", required=True)\n@click.option(\n    \"--keep-config/--no-keep-config\",\n    \"keep_config\",\n    default=False,\n    help=\"Keep the channel entry in config.json (only remove the module).\",\n)\ndef remove_cmd(key: str, keep_config: bool) -> None:\n    \"\"\"Remove a custom channel from custom_channels/. Built-in channels\n    cannot be removed.\n    \"\"\"\n    if key in BUILTIN_CHANNEL_KEYS:\n        click.echo(\n            f\"'{key}' is a built-in channel and cannot be removed. \"\n            \"Disable it in config instead.\",\n            err=True,\n        )\n        raise SystemExit(1)\n\n    dest_file = CUSTOM_CHANNELS_DIR / f\"{key}.py\"\n    dest_dir = CUSTOM_CHANNELS_DIR / key\n    if not dest_file.exists() and not dest_dir.exists():\n        click.echo(\n            f\"Channel '{key}' not found in {CUSTOM_CHANNELS_DIR}.\",\n            err=True,\n        )\n        raise SystemExit(1)\n\n    import shutil\n\n    if dest_file.exists():\n        dest_file.unlink()\n    else:\n        shutil.rmtree(dest_dir)\n    click.echo(f\"✓ Removed channel '{key}' from {CUSTOM_CHANNELS_DIR}.\")\n\n    if not keep_config:\n        config_path = get_config_path()\n        if config_path.is_file():\n            cfg = load_config(config_path)\n            data = cfg.model_dump()\n            ch_data = data.get(\"channels\") or {}\n            if key in ch_data:\n                del ch_data[key]\n                new_cfg = Config.model_validate(data)\n                save_config(new_cfg, config_path)\n                click.echo(f\"✓ Removed '{key}' from config.\")\n\n\n@channels_group.command(\"config\")\n@click.option(\n    \"--agent-id\",\n    default=\"default\",\n    help=\"Agent ID (defaults to 'default')\",\n)\ndef configure_cmd(agent_id: str) -> None:\n    \"\"\"Interactively configure channels.\"\"\"\n    try:\n        agent_config = load_agent_config(agent_id)\n        click.echo(f\"Configuring channels for agent: {agent_id}\\n\")\n\n        # Create a temporary Config object for the interactive configurator\n        temp_config = Config()\n        temp_config.channels = (\n            agent_config.channels\n            if agent_config.channels\n            else temp_config.channels\n        )\n\n        configure_channels_interactive(temp_config)\n\n        # Save back to agent config\n        agent_config.channels = temp_config.channels\n        save_agent_config(agent_id, agent_config)\n        click.echo(f\"\\n✓ Configuration saved for agent {agent_id}\")\n    except ValueError as e:\n        click.echo(f\"Error: {e}\", err=True)\n        raise SystemExit(1) from e\n"
  },
  {
    "path": "src/copaw/cli/chats_cmd.py",
    "content": "# -*- coding: utf-8 -*-\n\"\"\"CLI commands for managing chats via HTTP API (/chats).\"\"\"\nfrom __future__ import annotations\n\nimport json\nfrom pathlib import Path\nfrom typing import Optional\n\nimport click\n\nfrom .http import client, print_json\nfrom ..app.channels.schema import DEFAULT_CHANNEL\n\n\ndef _base_url(ctx: click.Context, base_url: Optional[str]) -> str:\n    \"\"\"Resolve base_url with priority:\n    1) command --base-url\n    2) global --host/--port\n        (already resolved in main.py, may come from config.json)\n    \"\"\"\n    if base_url:\n        return base_url.rstrip(\"/\")\n    host = (ctx.obj or {}).get(\"host\", \"127.0.0.1\")\n    port = (ctx.obj or {}).get(\"port\", 8088)\n    return f\"http://{host}:{port}\"\n\n\n@click.group(\"chats\")\ndef chats_group() -> None:\n    \"\"\"Manage chat sessions via the HTTP API (/chats).\n\n    \\b\n    Common examples:\n      copaw chats list                    # List all chats\n      copaw chats list --user-id alice    # Filter by user\n      copaw chats get            # View details\n      copaw chats create --session-id s1 --user-id u1\n      copaw chats delete         # Delete a chat\n    \"\"\"\n\n\n@chats_group.command(\"list\")\n@click.option(\n    \"--user-id\",\n    default=None,\n    help=\"Filter by user ID, e.g. alice\",\n)\n@click.option(\n    \"--channel\",\n    default=None,\n    help=\"Filter by channel: console/imessage/dingtalk/discord/qq\",\n)\n@click.option(\n    \"--base-url\",\n    default=None,\n    help=\"Override API base URL, e.g. http://127.0.0.1:8088\",\n)\n@click.option(\n    \"--agent-id\",\n    default=\"default\",\n    help=\"Agent ID (defaults to 'default')\",\n)\n@click.pass_context\ndef list_chats(\n    ctx: click.Context,\n    user_id: Optional[str],\n    channel: Optional[str],\n    base_url: Optional[str],\n    agent_id: str,\n) -> None:\n    \"\"\"List all chats, optionally filtered by user_id or channel.\n\n    \\b\n    Examples:\n      copaw chats list\n      copaw chats list --user-id alice\n      copaw chats list --channel discord\n      copaw chats list --user-id alice --channel discord\n    \"\"\"\n    base_url = _base_url(ctx, base_url)\n    params: dict[str, str] = {}\n    if user_id:\n        params[\"user_id\"] = user_id\n    if channel:\n        params[\"channel\"] = channel\n    with client(base_url) as c:\n        headers = {\"X-Agent-Id\": agent_id}\n        r = c.get(\"/chats\", params=params, headers=headers)\n        r.raise_for_status()\n        print_json(r.json())\n\n\n@chats_group.command(\"get\")\n@click.argument(\"chat_id\")\n@click.option(\"--base-url\", default=None, help=\"Override API base URL\")\n@click.option(\n    \"--agent-id\",\n    default=\"default\",\n    help=\"Agent ID (defaults to 'default')\",\n)\n@click.pass_context\ndef get_chat(\n    ctx: click.Context,\n    chat_id: str,\n    base_url: Optional[str],\n    agent_id: str,\n) -> None:\n    \"\"\"View details of a specific chat (including message history).\n\n    \\b\n    CHAT_ID  Chat UUID, obtainable via `copaw chats list`.\n\n    \\b\n    Examples:\n      copaw chats get 823845fe-dd13-43c2-ab8b-d05870602fd8\n    \"\"\"\n    base_url = _base_url(ctx, base_url)\n    with client(base_url) as c:\n        headers = {\"X-Agent-Id\": agent_id}\n        r = c.get(f\"/chats/{chat_id}\", headers=headers)\n        if r.status_code == 404:\n            raise click.ClickException(f\"chat not found: {chat_id}\")\n        r.raise_for_status()\n        print_json(r.json())\n\n\n@chats_group.command(\"create\")\n@click.option(\n    \"-f\",\n    \"--file\",\n    \"file_\",\n    type=click.Path(exists=True, dir_okay=False, path_type=Path),\n    default=None,\n    help=\"Create from JSON file (mutually exclusive with inline args)\",\n)\n@click.option(\n    \"--name\",\n    default=\"New Chat\",\n    help=\"Chat name (default 'New Chat')\",\n)\n@click.option(\n    \"--session-id\",\n    default=None,\n    help=\"Session identifier, format: channel:user_id (required inline)\",\n)\n@click.option(\n    \"--user-id\",\n    default=None,\n    help=\"User ID (required for inline creation)\",\n)\n@click.option(\n    \"--channel\",\n    default=DEFAULT_CHANNEL,\n    help=(\n        f\"Channel name: console/imessage/dingtalk/discord/qq \"\n        f\"(default {DEFAULT_CHANNEL})\"\n    ),\n)\n@click.option(\"--base-url\", default=None, help=\"Override API base URL\")\n@click.option(\n    \"--agent-id\",\n    default=\"default\",\n    help=\"Agent ID (defaults to 'default')\",\n)\n@click.pass_context\ndef create_chat(\n    ctx: click.Context,\n    file_: Optional[Path],\n    name: str,\n    session_id: Optional[str],\n    user_id: Optional[str],\n    channel: str,\n    base_url: Optional[str],\n    agent_id: str,\n) -> None:\n    \"\"\"Create a new chat.\n\n    Use -f to specify a JSON file, or use inline parameters.\n\n    \\b\n    Inline creation examples:\n      copaw chats create --session-id \"discord:alice\" \\\\\n        --user-id alice --name \"My Chat\"\n      copaw chats create --session-id s1 --user-id u1 \\\\\n        --channel imessage\n\n    \\b\n    JSON file creation example:\n      copaw chats create -f chat.json\n    \"\"\"\n    base_url = _base_url(ctx, base_url)\n    if file_ is not None:\n        payload = json.loads(file_.read_text(encoding=\"utf-8\"))\n    else:\n        if not session_id:\n            raise click.UsageError(\n                \"--session-id is required for inline creation\",\n            )\n        if not user_id:\n            raise click.UsageError(\n                \"--user-id is required for inline creation\",\n            )\n        payload = {\n            \"id\": \"\",\n            \"name\": name,\n            \"session_id\": session_id,\n            \"user_id\": user_id,\n            \"channel\": channel,\n            \"meta\": {},\n        }\n    with client(base_url) as c:\n        headers = {\"X-Agent-Id\": agent_id}\n        r = c.post(\"/chats\", json=payload, headers=headers)\n        r.raise_for_status()\n        print_json(r.json())\n\n\n@chats_group.command(\"update\")\n@click.argument(\"chat_id\")\n@click.option(\"--name\", required=True, help=\"New chat name\")\n@click.option(\"--base-url\", default=None, help=\"Override API base URL\")\n@click.option(\n    \"--agent-id\",\n    default=\"default\",\n    help=\"Agent ID (defaults to 'default')\",\n)\n@click.pass_context\ndef update_chat(\n    ctx: click.Context,\n    chat_id: str,\n    name: str,\n    base_url: Optional[str],\n    agent_id: str,\n) -> None:\n    \"\"\"Update chat name.\n\n    \\b\n    CHAT_ID  Chat UUID, obtainable via `copaw chats list`.\n\n    \\b\n    Examples:\n      copaw chats update  --name \"Renamed Chat\"\n    \"\"\"\n    base_url = _base_url(ctx, base_url)\n    headers = {\"X-Agent-Id\": agent_id}\n    # Fetch existing spec, then patch name\n    with client(base_url) as c:\n        r = c.get(\"/chats\", headers=headers)\n        r.raise_for_status()\n        specs = r.json()\n\n    payload = next((s for s in specs if s.get(\"id\") == chat_id), None)\n    if payload is None:\n        raise click.ClickException(f\"chat not found: {chat_id}\")\n\n    payload[\"name\"] = name\n\n    with client(base_url) as c:\n        r = c.put(f\"/chats/{chat_id}\", json=payload, headers=headers)\n        if r.status_code == 404:\n            raise click.ClickException(f\"chat not found: {chat_id}\")\n        r.raise_for_status()\n        print_json(r.json())\n\n\n@chats_group.command(\"delete\")\n@click.argument(\"chat_id\")\n@click.option(\"--base-url\", default=None, help=\"Override API base URL\")\n@click.option(\n    \"--agent-id\",\n    default=\"default\",\n    help=\"Agent ID (defaults to 'default')\",\n)\n@click.pass_context\ndef delete_chat(\n    ctx: click.Context,\n    chat_id: str,\n    base_url: Optional[str],\n    agent_id: str,\n) -> None:\n    \"\"\"Delete a specific chat.\n\n    Only deletes Chat metadata; does not clear Redis session state.\n\n    \\b\n    CHAT_ID  Chat UUID, obtainable via `copaw chats list`.\n\n    \\b\n    Examples:\n      copaw chats delete 823845fe-dd13-43c2-ab8b-d05870602fd8\n    \"\"\"\n    base_url = _base_url(ctx, base_url)\n    with client(base_url) as c:\n        headers = {\"X-Agent-Id\": agent_id}\n        r = c.delete(f\"/chats/{chat_id}\", headers=headers)\n        if r.status_code == 404:\n            raise click.ClickException(f\"chat not found: {chat_id}\")\n        r.raise_for_status()\n        print_json(r.json())\n"
  },
  {
    "path": "src/copaw/cli/clean_cmd.py",
    "content": "# -*- coding: utf-8 -*-\nfrom __future__ import annotations\n\nimport shutil\nfrom pathlib import Path\n\nimport click\n\nfrom ..constant import WORKING_DIR\nfrom ..utils.telemetry import TELEMETRY_MARKER_FILE\n\n\ndef _iter_children(p: Path) -> list[Path]:\n    if not p.exists():\n        return []\n    return sorted(list(p.iterdir()), key=lambda x: x.name)\n\n\n# pylint: disable=too-many-branches\n@click.command(\"clean\")\n@click.option(\"--yes\", is_flag=True, help=\"Do not prompt for confirmation\")\n@click.option(\n    \"--dry-run\",\n    is_flag=True,\n    help=\"List what would be deleted, but do not delete\",\n)\ndef clean_cmd(yes: bool, dry_run: bool) -> None:\n    \"\"\"Clear CoPaw WORKING_DIR (~/.copaw by default).\"\"\"\n    wd = WORKING_DIR\n\n    if not wd.exists():\n        click.echo(f\"WORKING_DIR does not exist: {wd}\")\n        return\n\n    children = _iter_children(wd)\n    # Filter out the telemetry marker file\n    telemetry_marker = wd / TELEMETRY_MARKER_FILE\n    children = [c for c in children if c != telemetry_marker]\n\n    if not children:\n        if telemetry_marker.exists():\n            click.echo(\n                \"WORKING_DIR has no removable files\",\n            )\n        else:\n            click.echo(f\"WORKING_DIR is already empty: {wd}\")\n        return\n\n    click.echo(f\"WORKING_DIR: {wd}\")\n    click.echo(\"Will remove:\")\n    for c in children:\n        click.echo(f\"  - {c}\")\n    if telemetry_marker.exists():\n        click.echo(f\"Will keep: {TELEMETRY_MARKER_FILE}\")\n\n    if dry_run:\n        click.echo(\"dry-run: nothing deleted.\")\n        return\n\n    if not yes:\n        ok = click.confirm(f\"Delete ALL contents under {wd}?\", default=False)\n        if not ok:\n            click.echo(\"Cancelled.\")\n            return\n\n    # delete contents, keep the directory itself\n    for c in children:\n        try:\n            if c.is_dir() and not c.is_symlink():\n                shutil.rmtree(c)\n            else:\n                c.unlink()\n        except FileNotFoundError:\n            pass\n\n    click.echo(\"Done.\")\n"
  },
  {
    "path": "src/copaw/cli/cron_cmd.py",
    "content": "# -*- coding: utf-8 -*-\nfrom __future__ import annotations\n\nimport json\nfrom pathlib import Path\nfrom typing import Optional\n\nimport click\n\nfrom .http import client, print_json\nfrom ..app.channels.schema import DEFAULT_CHANNEL\n\n\ndef _base_url(ctx: click.Context, base_url: Optional[str]) -> str:\n    \"\"\"Resolve base_url with priority:\n    1) command --base-url\n    2) global --host/--port\n        (already resolved in main.py, may come from config.json)\n    \"\"\"\n    if base_url:\n        return base_url.rstrip(\"/\")\n    host = (ctx.obj or {}).get(\"host\", \"127.0.0.1\")\n    port = (ctx.obj or {}).get(\"port\", 8088)\n    return f\"http://{host}:{port}\"\n\n\n@click.group(\"cron\")\ndef cron_group() -> None:\n    \"\"\"Manage scheduled cron jobs via the HTTP API (/cron).\n\n    Use list/get/state to inspect jobs; create/delete to add or remove;\n    pause/resume to toggle execution; run to trigger a one-off run.\n    \"\"\"\n\n\n@cron_group.command(\"list\")\n@click.option(\n    \"--base-url\",\n    default=None,\n    help=(\n        \"Override the API base URL (e.g. http://127.0.0.1:8088). \"\n        \"If omitted, uses global --host and --port from config.\"\n    ),\n)\n@click.option(\n    \"--agent-id\",\n    default=\"default\",\n    help=\"Agent ID (defaults to 'default')\",\n)\n@click.pass_context\ndef list_jobs(\n    ctx: click.Context,\n    base_url: Optional[str],\n    agent_id: str,\n) -> None:\n    \"\"\"List all cron jobs. Output is JSON from GET /cron/jobs.\"\"\"\n    base_url = _base_url(ctx, base_url)\n    with client(base_url) as c:\n        headers = {\"X-Agent-Id\": agent_id}\n        r = c.get(\"/cron/jobs\", headers=headers)\n        r.raise_for_status()\n        print_json(r.json())\n\n\n@cron_group.command(\"get\")\n@click.argument(\"job_id\", metavar=\"JOB_ID\")\n@click.option(\n    \"--base-url\",\n    default=None,\n    help=\"Override the API base URL. Defaults to global --host/--port.\",\n)\n@click.option(\n    \"--agent-id\",\n    default=\"default\",\n    help=\"Agent ID (defaults to 'default')\",\n)\n@click.pass_context\ndef get_job(\n    ctx: click.Context,\n    job_id: str,\n    base_url: Optional[str],\n    agent_id: str,\n) -> None:\n    \"\"\"Fetch a cron job by ID. Returns JSON from GET /cron/jobs/.\"\"\"\n    base_url = _base_url(ctx, base_url)\n    with client(base_url) as c:\n        headers = {\"X-Agent-Id\": agent_id}\n        r = c.get(f\"/cron/jobs/{job_id}\", headers=headers)\n        if r.status_code == 404:\n            raise click.ClickException(\"Job not found.\")\n        r.raise_for_status()\n        print_json(r.json())\n\n\n@cron_group.command(\"state\")\n@click.argument(\"job_id\", metavar=\"JOB_ID\")\n@click.option(\n    \"--base-url\",\n    default=None,\n    help=\"Override the API base URL. Defaults to global --host/--port.\",\n)\n@click.option(\n    \"--agent-id\",\n    default=\"default\",\n    help=\"Agent ID (defaults to 'default')\",\n)\n@click.pass_context\ndef job_state(\n    ctx: click.Context,\n    job_id: str,\n    base_url: Optional[str],\n    agent_id: str,\n) -> None:\n    \"\"\"Get the runtime state of a cron job (e.g. next run time, paused).\"\"\"\n    base_url = _base_url(ctx, base_url)\n    with client(base_url) as c:\n        headers = {\"X-Agent-Id\": agent_id}\n        r = c.get(f\"/cron/jobs/{job_id}/state\", headers=headers)\n        if r.status_code == 404:\n            raise click.ClickException(\"Job not found.\")\n        r.raise_for_status()\n        print_json(r.json())\n\n\ndef _build_spec_from_cli(\n    task_type: str,\n    name: str,\n    cron: str,\n    channel: str,\n    target_user: str,\n    target_session: str,\n    text: Optional[str],\n    timezone: str,\n    enabled: bool,\n    mode: str,\n) -> dict:\n    \"\"\"Build CronJobSpec JSON payload from CLI args (no id).\"\"\"\n    schedule = {\"type\": \"cron\", \"cron\": cron, \"timezone\": timezone}\n    dispatch = {\n        \"type\": \"channel\",\n        \"channel\": channel,\n        \"target\": {\"user_id\": target_user, \"session_id\": target_session},\n        \"mode\": mode,\n        \"meta\": {},\n    }\n    runtime = {\n        \"max_concurrency\": 1,\n        \"timeout_seconds\": 120,\n        \"misfire_grace_seconds\": 60,\n    }\n    if task_type == \"text\":\n        if not (text and text.strip()):\n            raise click.UsageError(\n                \"--text is required when task type is 'text'\",\n            )\n        return {\n            \"id\": \"\",\n            \"name\": name,\n            \"enabled\": enabled,\n            \"schedule\": schedule,\n            \"task_type\": \"text\",\n            \"text\": text.strip(),\n            \"dispatch\": dispatch,\n            \"runtime\": runtime,\n            \"meta\": {},\n        }\n    if task_type == \"agent\":\n        if not (text and text.strip()):\n            raise click.UsageError(\n                \"--text is required when task type is 'agent' \"\n                \"(the question/prompt sent to the agent)\",\n            )\n        return {\n            \"id\": \"\",\n            \"name\": name,\n            \"enabled\": enabled,\n            \"schedule\": schedule,\n            \"task_type\": \"agent\",\n            \"request\": {\n                \"input\": [\n                    {\n                        \"role\": \"user\",\n                        \"type\": \"message\",\n                        \"content\": [{\"type\": \"text\", \"text\": text.strip()}],\n                    },\n                ],\n                \"session_id\": target_session,\n                \"user_id\": \"cron\",\n            },\n            \"dispatch\": dispatch,\n            \"runtime\": runtime,\n            \"meta\": {},\n        }\n    raise click.UsageError(f\"Unsupported task type: {task_type}\")\n\n\n@cron_group.command(\"create\")\n@click.option(\n    \"-f\",\n    \"--file\",\n    \"file_\",\n    type=click.Path(exists=True, dir_okay=False, path_type=Path),\n    default=None,\n    help=(\n        \"Path to a JSON file containing the full cron job spec. \"\n        \"Mutually exclusive with inline options (--type, --name, etc.).\"\n    ),\n)\n@click.option(\n    \"--type\",\n    \"task_type\",\n    type=click.Choice([\"text\", \"agent\"], case_sensitive=False),\n    default=None,\n    help=(\n        \"Task type: 'text' sends fixed content to the channel; \"\n        \"'agent' sends a question to the agent and delivers the reply to the \"\n        \"channel. Required when not using -f/--file.\"\n    ),\n)\n@click.option(\n    \"--name\",\n    default=None,\n    help=\"Display name for the job. Required when not using -f/--file.\",\n)\n@click.option(\n    \"--cron\",\n    default=None,\n    help=(\n        \"Cron expression (5 fields: minute hour day month weekday). \"\n        \"Example: '0 9 * * *' for daily at 09:00. Required without -f/--file.\"\n    ),\n)\n@click.option(\n    \"--channel\",\n    default=None,\n    help=(\n        \"Delivery channel: e.g. imessage, dingtalk, discord, qq, console. \"\n        \"Required when not using -f/--file.\"\n    ),\n)\n@click.option(\n    \"--target-user\",\n    default=None,\n    help=(\n        \"Target user_id for the channel (recipient identifier). \"\n        \"Required when not using -f/--file.\"\n    ),\n)\n@click.option(\n    \"--target-session\",\n    default=None,\n    help=(\n        \"Target session_id for the channel. \"\n        \"Required when not using -f/--file.\"\n    ),\n)\n@click.option(\n    \"--text\",\n    default=None,\n    help=(\n        \"Content: for 'text' tasks this is the message sent to the channel; \"\n        \"for 'agent' tasks this is the prompt/question sent to the agent. \"\n        \"Required for both task types.\"\n    ),\n)\n@click.option(\n    \"--timezone\",\n    default=None,\n    help=(\n        \"Timezone for the cron schedule (e.g. UTC, America/New_York). \"\n        \"Defaults to the user timezone from config.\"\n    ),\n)\n@click.option(\n    \"--enabled/--no-enabled\",\n    default=True,\n    help=\"Create the job as enabled (--enabled) or disabled (--no-enabled).\",\n)\n@click.option(\n    \"--mode\",\n    type=click.Choice([\"stream\", \"final\"], case_sensitive=False),\n    default=\"final\",\n    help=(\n        \"Delivery mode: 'stream' sends incremental updates; \"\n        \"'final' sends only the final result.\"\n    ),\n)\n@click.option(\n    \"--base-url\",\n    default=None,\n    help=\"Override the API base URL. Defaults to global --host/--port.\",\n)\n@click.option(\n    \"--agent-id\",\n    default=\"default\",\n    help=\"Agent ID (defaults to 'default')\",\n)\n@click.pass_context\ndef create_job(\n    ctx: click.Context,\n    file_: Optional[Path],\n    task_type: Optional[str],\n    name: Optional[str],\n    cron: Optional[str],\n    channel: Optional[str],\n    target_user: Optional[str],\n    target_session: Optional[str],\n    text: Optional[str],\n    timezone: Optional[str],\n    enabled: bool,\n    mode: str,\n    base_url: Optional[str],\n    agent_id: str,\n) -> None:\n    \"\"\"Create a cron job.\n\n    Either pass -f/--file with a JSON spec, or use --type, --name, --cron,\n    --channel, --target-user, --target-session and --text to define the job\n    inline.\n    \"\"\"\n    if timezone is None:\n        from ..config import load_config\n\n        timezone = load_config().user_timezone or \"UTC\"\n    base_url = _base_url(ctx, base_url)\n    if file_ is not None:\n        payload = json.loads(file_.read_text(encoding=\"utf-8\"))\n    else:\n        for value, label in [\n            (task_type, \"--type\"),\n            (name, \"--name\"),\n            (cron, \"--cron\"),\n            (channel, \"--channel\"),\n            (target_user, \"--target-user\"),\n            (target_session, \"--target-session\"),\n        ]:\n            if not value or (isinstance(value, str) and not value.strip()):\n                raise click.UsageError(\n                    f\"When creating without -f/--file, {label} is required\",\n                )\n        payload = _build_spec_from_cli(\n            task_type=task_type or \"agent\",\n            name=name or \"\",\n            cron=cron or \"\",\n            channel=channel or DEFAULT_CHANNEL,\n            target_user=target_user or \"\",\n            target_session=target_session or \"\",\n            text=text,\n            timezone=timezone,\n            enabled=enabled,\n            mode=mode,\n        )\n    with client(base_url) as c:\n        headers = {\"X-Agent-Id\": agent_id}\n        r = c.post(\"/cron/jobs\", json=payload, headers=headers)\n        r.raise_for_status()\n        print_json(r.json())\n\n\n@cron_group.command(\"delete\")\n@click.argument(\"job_id\", metavar=\"JOB_ID\")\n@click.option(\n    \"--base-url\",\n    default=None,\n    help=\"Override the API base URL. Defaults to global --host/--port.\",\n)\n@click.option(\n    \"--agent-id\",\n    default=\"default\",\n    help=\"Agent ID (defaults to 'default')\",\n)\n@click.pass_context\ndef delete_job(\n    ctx: click.Context,\n    job_id: str,\n    base_url: Optional[str],\n    agent_id: str,\n) -> None:\n    \"\"\"Permanently delete a cron job. The job is removed from the server.\"\"\"\n    base_url = _base_url(ctx, base_url)\n    with client(base_url) as c:\n        headers = {\"X-Agent-Id\": agent_id}\n        r = c.delete(f\"/cron/jobs/{job_id}\", headers=headers)\n        if r.status_code == 404:\n            raise click.ClickException(\"Job not found.\")\n        r.raise_for_status()\n        print_json(r.json())\n\n\n@cron_group.command(\"pause\")\n@click.argument(\"job_id\", metavar=\"JOB_ID\")\n@click.option(\n    \"--base-url\",\n    default=None,\n    help=\"Override the API base URL. Defaults to global --host/--port.\",\n)\n@click.option(\n    \"--agent-id\",\n    default=\"default\",\n    help=\"Agent ID (defaults to 'default')\",\n)\n@click.pass_context\ndef pause_job(\n    ctx: click.Context,\n    job_id: str,\n    base_url: Optional[str],\n    agent_id: str,\n) -> None:\n    \"\"\"Pause a cron job so it no longer runs on schedule.\n    Use 'resume' to re-enable.\n    \"\"\"\n    base_url = _base_url(ctx, base_url)\n    with client(base_url) as c:\n        headers = {\"X-Agent-Id\": agent_id}\n        r = c.post(f\"/cron/jobs/{job_id}/pause\", headers=headers)\n        if r.status_code == 404:\n            raise click.ClickException(\"Job not found.\")\n        r.raise_for_status()\n        print_json(r.json())\n\n\n@cron_group.command(\"resume\")\n@click.argument(\"job_id\", metavar=\"JOB_ID\")\n@click.option(\n    \"--base-url\",\n    default=None,\n    help=\"Override the API base URL. Defaults to global --host/--port.\",\n)\n@click.option(\n    \"--agent-id\",\n    default=\"default\",\n    help=\"Agent ID (defaults to 'default')\",\n)\n@click.pass_context\ndef resume_job(\n    ctx: click.Context,\n    job_id: str,\n    base_url: Optional[str],\n    agent_id: str,\n) -> None:\n    \"\"\"Resume a paused cron job so it runs again on its schedule.\"\"\"\n    base_url = _base_url(ctx, base_url)\n    with client(base_url) as c:\n        headers = {\"X-Agent-Id\": agent_id}\n        r = c.post(f\"/cron/jobs/{job_id}/resume\", headers=headers)\n        if r.status_code == 404:\n            raise click.ClickException(\"Job not found.\")\n        r.raise_for_status()\n        print_json(r.json())\n\n\n@cron_group.command(\"run\")\n@click.argument(\"job_id\", metavar=\"JOB_ID\")\n@click.option(\n    \"--base-url\",\n    default=None,\n    help=\"Override the API base URL. Defaults to global --host/--port.\",\n)\n@click.option(\n    \"--agent-id\",\n    default=\"default\",\n    help=\"Agent ID (defaults to 'default')\",\n)\n@click.pass_context\ndef run_job(\n    ctx: click.Context,\n    job_id: str,\n    base_url: Optional[str],\n    agent_id: str,\n) -> None:\n    \"\"\"Trigger a one-off run of a cron job immediately (ignores schedule).\"\"\"\n    base_url = _base_url(ctx, base_url)\n    with client(base_url) as c:\n        headers = {\"X-Agent-Id\": agent_id}\n        r = c.post(f\"/cron/jobs/{job_id}/run\", headers=headers)\n        if r.status_code == 404:\n            raise click.ClickException(\"Job not found.\")\n        r.raise_for_status()\n        print_json(r.json())\n"
  },
  {
    "path": "src/copaw/cli/daemon_cmd.py",
    "content": "# -*- coding: utf-8 -*-\n\"\"\"CLI daemon subcommands: status, restart, reload-config, version, logs.\n\nShares execution with in-chat /daemon  via daemon_commands.\n\"\"\"\nfrom __future__ import annotations\n\nimport asyncio\nfrom pathlib import Path\n\nimport click\n\nfrom ..app.runner.daemon_commands import (\n    DaemonContext,\n    run_daemon_logs,\n    run_daemon_reload_config,\n    run_daemon_restart,\n    run_daemon_status,\n    run_daemon_version,\n)\nfrom ..constant import WORKING_DIR\nfrom ..config import load_config\n\n\ndef _get_agent_workspace(agent_id: str) -> Path:\n    \"\"\"Get agent workspace directory.\"\"\"\n    try:\n        config = load_config()\n        if agent_id in config.agents.profiles:\n            ref = config.agents.profiles[agent_id]\n            workspace_dir = Path(ref.workspace_dir).expanduser()\n            return workspace_dir\n    except Exception:\n        pass\n    return WORKING_DIR\n\n\ndef _context(agent_id: str) -> DaemonContext:\n    working_dir = _get_agent_workspace(agent_id)\n    return DaemonContext(\n        working_dir=working_dir,\n        memory_manager=None,\n        manager=None,  # CLI has no access to MultiAgentManager\n        agent_id=agent_id,\n    )\n\n\n@click.group(\"daemon\")\ndef daemon_group() -> None:\n    \"\"\"Daemon commands: status, restart, reload-config, version, logs.\"\"\"\n\n\n@daemon_group.command(\"status\")\n@click.option(\n    \"--agent-id\",\n    default=\"default\",\n    help=\"Agent ID (defaults to 'default')\",\n)\ndef status_cmd(agent_id: str) -> None:\n    \"\"\"Show daemon status (config, working dir, memory manager).\"\"\"\n    ctx = _context(agent_id)\n    click.echo(f\"Agent: {agent_id}\\n\")\n    click.echo(run_daemon_status(ctx))\n\n\n@daemon_group.command(\"restart\")\n@click.option(\n    \"--agent-id\",\n    default=\"default\",\n    help=\"Agent ID (defaults to 'default')\",\n)\ndef restart_cmd(agent_id: str) -> None:\n    \"\"\"Print restart instructions (CLI has no process to restart).\"\"\"\n    ctx = _context(agent_id)\n    click.echo(f\"Agent: {agent_id}\\n\")\n    click.echo(asyncio.run(run_daemon_restart(ctx)))\n\n\n@daemon_group.command(\"reload-config\")\n@click.option(\n    \"--agent-id\",\n    default=\"default\",\n    help=\"Agent ID (defaults to 'default')\",\n)\ndef reload_config_cmd(agent_id: str) -> None:\n    \"\"\"Reload config (re-read from file).\"\"\"\n    ctx = _context(agent_id)\n    click.echo(f\"Agent: {agent_id}\\n\")\n    click.echo(run_daemon_reload_config(ctx))\n\n\n@daemon_group.command(\"version\")\n@click.option(\n    \"--agent-id\",\n    default=\"default\",\n    help=\"Agent ID (defaults to 'default')\",\n)\ndef version_cmd(agent_id: str) -> None:\n    \"\"\"Show version and paths.\"\"\"\n    ctx = _context(agent_id)\n    click.echo(f\"Agent: {agent_id}\\n\")\n    click.echo(run_daemon_version(ctx))\n\n\n@daemon_group.command(\"logs\")\n@click.option(\n    \"-n\",\n    \"--lines\",\n    default=100,\n    type=int,\n    help=\"Number of last lines to show (default 100).\",\n)\n@click.option(\n    \"--agent-id\",\n    default=\"default\",\n    help=\"Agent ID (defaults to 'default')\",\n)\ndef logs_cmd(lines: int, agent_id: str) -> None:\n    \"\"\"Tail last N lines of WORKING_DIR/copaw.log.\"\"\"\n    ctx = _context(agent_id)\n    lines = min(max(1, lines), 2000)\n    click.echo(f\"Agent: {agent_id}\\n\")\n    click.echo(run_daemon_logs(ctx, lines=lines))\n"
  },
  {
    "path": "src/copaw/cli/desktop_cmd.py",
    "content": "# -*- coding: utf-8 -*-\n\"\"\"CLI command: run CoPaw app on a free port in a native webview window.\"\"\"\n# pylint:disable=too-many-branches,too-many-statements,consider-using-with\nfrom __future__ import annotations\n\nimport logging\nimport os\nimport socket\nimport subprocess\nimport sys\nimport threading\nimport time\nimport traceback\nimport webbrowser\n\nimport click\n\nfrom ..constant import LOG_LEVEL_ENV\nfrom ..utils.logging import setup_logger\n\ntry:\n    import webview\nexcept ImportError:\n    webview = None  # type: ignore[assignment]\n\nlogger = logging.getLogger(__name__)\n\n\nclass WebViewAPI:\n    \"\"\"API exposed to the webview for handling external links.\"\"\"\n\n    def open_external_link(self, url: str) -> None:\n        \"\"\"Open URL in system's default browser.\"\"\"\n        if not url.startswith((\"http://\", \"https://\")):\n            return\n        webbrowser.open(url)\n\n\ndef _find_free_port(host: str = \"127.0.0.1\") -> int:\n    \"\"\"Bind to port 0 and return the OS-assigned free port.\"\"\"\n    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as sock:\n        sock.bind((host, 0))\n        sock.listen(1)\n        return sock.getsockname()[1]\n\n\ndef _wait_for_http(host: str, port: int, timeout_sec: float = 300.0) -> bool:\n    \"\"\"Return True when something accepts TCP on host:port.\"\"\"\n    deadline = time.monotonic() + timeout_sec\n    while time.monotonic() < deadline:\n        try:\n            with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:\n                s.settimeout(2.0)\n                s.connect((host, port))\n                return True\n        except (OSError, socket.error):\n            time.sleep(1)\n    return False\n\n\ndef _stream_reader(in_stream, out_stream) -> None:\n    \"\"\"Read from in_stream line by line and write to out_stream.\n\n    Used on Windows to prevent subprocess buffer blocking. Runs in a\n    background thread to continuously drain the subprocess output.\n    \"\"\"\n    try:\n        for line in iter(in_stream.readline, \"\"):\n            if not line:\n                break\n            out_stream.write(line)\n            out_stream.flush()\n    except Exception:\n        pass\n    finally:\n        try:\n            in_stream.close()\n        except Exception:\n            pass\n\n\n@click.command(\"desktop\")\n@click.option(\n    \"--host\",\n    default=\"127.0.0.1\",\n    show_default=True,\n    help=\"Bind host for the app server.\",\n)\n@click.option(\n    \"--log-level\",\n    default=\"info\",\n    type=click.Choice(\n        [\"critical\", \"error\", \"warning\", \"info\", \"debug\", \"trace\"],\n        case_sensitive=False,\n    ),\n    show_default=True,\n    help=\"Log level for the app process.\",\n)\ndef desktop_cmd(\n    host: str,\n    log_level: str,\n) -> None:\n    \"\"\"Run CoPaw app on an auto-selected free port in a webview window.\n\n    Starts the FastAPI app in a subprocess on a free port, then opens a\n    native webview window loading that URL. Use for a dedicated desktop\n    window without conflicting with an existing CoPaw app instance.\n    \"\"\"\n    # Setup logger for desktop command (separate from backend subprocess)\n    setup_logger(log_level)\n\n    port = _find_free_port(host)\n    url = f\"http://{host}:{port}\"\n    click.echo(f\"Starting CoPaw app on {url} (port {port})\")\n    logger.info(\"Server subprocess starting...\")\n\n    env = os.environ.copy()\n    env[LOG_LEVEL_ENV] = log_level\n\n    if \"SSL_CERT_FILE\" in env:\n        cert_file = env[\"SSL_CERT_FILE\"]\n        if os.path.exists(cert_file):\n            logger.info(f\"SSL certificate: {cert_file}\")\n        else:\n            logger.warning(\n                f\"SSL_CERT_FILE set but not found: {cert_file}\",\n            )\n    else:\n        logger.warning(\"SSL_CERT_FILE not set on environment\")\n\n    is_windows = sys.platform == \"win32\"\n    proc = None\n    manually_terminated = (\n        False  # Track if we intentionally terminated the process\n    )\n    try:\n        proc = subprocess.Popen(\n            [\n                sys.executable,\n                \"-m\",\n                \"copaw\",\n                \"app\",\n                \"--host\",\n                host,\n                \"--port\",\n                str(port),\n                \"--log-level\",\n                log_level,\n            ],\n            stdin=subprocess.DEVNULL,\n            stdout=subprocess.PIPE if is_windows else sys.stdout,\n            stderr=subprocess.PIPE if is_windows else sys.stderr,\n            env=env,\n            bufsize=1,\n            universal_newlines=True,\n        )\n        try:\n            if is_windows:\n                stdout_thread = threading.Thread(\n                    target=_stream_reader,\n                    args=(proc.stdout, sys.stdout),\n                    daemon=True,\n                )\n                stderr_thread = threading.Thread(\n                    target=_stream_reader,\n                    args=(proc.stderr, sys.stderr),\n                    daemon=True,\n                )\n                stdout_thread.start()\n                stderr_thread.start()\n            logger.info(\"Waiting for HTTP ready...\")\n            if _wait_for_http(host, port):\n                logger.info(\"HTTP ready, creating webview window...\")\n                api = WebViewAPI()\n                webview.create_window(\n                    \"CoPaw Desktop\",\n                    url,\n                    width=1280,\n                    height=800,\n                    text_select=True,\n                    js_api=api,\n                )\n                logger.info(\n                    \"Calling webview.start() (blocks until closed)...\",\n                )\n                webview.start(\n                    private_mode=False,\n                )  # blocks until user closes the window\n                logger.info(\"webview.start() returned (window closed).\")\n            else:\n                logger.error(\"Server did not become ready in time.\")\n                click.echo(\n                    \"Server did not become ready in time; open manually: \"\n                    + url,\n                    err=True,\n                )\n                try:\n                    proc.wait()\n                except KeyboardInterrupt:\n                    pass  # will be handled in finally\n        finally:\n            # Ensure backend process is always cleaned up\n            # Wrap all cleanup operations to handle race conditions:\n            # - Process may exit between poll() and terminate()\n            # - terminate()/kill() may raise ProcessLookupError/OSError\n            # - We must not let cleanup exceptions mask the original error\n            if proc and proc.poll() is None:  # process still running\n                logger.info(\"Terminating backend server...\")\n                manually_terminated = (\n                    True  # Mark that we're intentionally terminating\n                )\n                try:\n                    proc.terminate()\n                    try:\n                        proc.wait(timeout=5.0)\n                        logger.info(\"Backend server terminated cleanly.\")\n                    except subprocess.TimeoutExpired:\n                        logger.warning(\n                            \"Backend did not exit in 5s, force killing...\",\n                        )\n                        try:\n                            proc.kill()\n                            proc.wait()\n                            logger.info(\"Backend server force killed.\")\n                        except (ProcessLookupError, OSError) as e:\n                            # Process already exited, which is fine\n                            logger.debug(\n                                f\"kill() raised {e.__class__.__name__} \"\n                                f\"(process already exited)\",\n                            )\n                except (ProcessLookupError, OSError) as e:\n                    # Process already exited between poll() and terminate()\n                    logger.debug(\n                        f\"terminate() raised {e.__class__.__name__} \"\n                        f\"(process already exited)\",\n                    )\n            elif proc:\n                logger.info(\n                    f\"Backend already exited with code {proc.returncode}\",\n                )\n\n        # Only report errors if process exited unexpectedly\n        # (not manually terminated)\n        # On Windows, terminate() doesn't use signals so exit codes vary\n        # (1, 259, etc.)\n        # On Unix/Linux/macOS, terminate() sends SIGTERM (exit code -15)\n        # Using a flag is more reliable than checking specific exit codes\n        if proc and proc.returncode != 0 and not manually_terminated:\n            logger.error(\n                f\"Backend process exited unexpectedly with code \"\n                f\"{proc.returncode}\",\n            )\n            # Follow POSIX convention for exit codes:\n            # - Negative (signal): 128 + signal_number\n            # - Positive (normal): use as-is\n            # Example: -15 (SIGTERM) -> 143 (128+15), -11 (SIGSEGV) ->\n            # 139 (128+11)\n            if proc.returncode < 0:\n                sys.exit(128 + abs(proc.returncode))\n            else:\n                sys.exit(proc.returncode or 1)\n    except KeyboardInterrupt:\n        logger.warning(\"KeyboardInterrupt in main, cleaning up...\")\n        raise\n    except Exception as e:\n        logger.error(f\"Exception: {e!r}\")\n        traceback.print_exc(file=sys.stderr)\n        sys.stderr.flush()\n        raise\n"
  },
  {
    "path": "src/copaw/cli/env_cmd.py",
    "content": "# -*- coding: utf-8 -*-\n\"\"\"CLI commands for environment variable management.\"\"\"\nfrom __future__ import annotations\n\nimport click\n\nfrom ..envs import load_envs, set_env_var, delete_env_var\n\n\n@click.group(\"env\")\ndef env_group() -> None:\n    \"\"\"Manage environment variables.\"\"\"\n\n\n# ---------------------------------------------------------------\n# list\n# ---------------------------------------------------------------\n\n\n@env_group.command(\"list\")\ndef list_cmd() -> None:\n    \"\"\"List all environment variables.\"\"\"\n    envs = load_envs()\n    if not envs:\n        click.echo(\"No environment variables configured.\")\n        return\n    click.echo(f\"\\n  {'Key':<30s}  Value\")\n    click.echo(f\"  {'─' * 56}\")\n    for key in sorted(envs):\n        click.echo(f\"  {key:<30s}  {envs[key]}\")\n    click.echo()\n\n\n# ---------------------------------------------------------------\n# set\n# ---------------------------------------------------------------\n\n\n@env_group.command(\"set\")\n@click.argument(\"key\")\n@click.argument(\"value\")\ndef set_cmd(key: str, value: str) -> None:\n    \"\"\"Set an environment variable (KEY VALUE).\"\"\"\n    set_env_var(key, value)\n    click.echo(f\"✓ {key} = {value}\")\n\n\n# ---------------------------------------------------------------\n# delete\n# ---------------------------------------------------------------\n\n\n@env_group.command(\"delete\")\n@click.argument(\"key\")\ndef delete_cmd(key: str) -> None:\n    \"\"\"Delete an environment variable.\"\"\"\n    envs = load_envs()\n    if key not in envs:\n        click.echo(\n            click.style(\n                f\"Env var '{key}' not found.\",\n                fg=\"red\",\n            ),\n        )\n        raise SystemExit(1)\n    delete_env_var(key)\n    click.echo(f\"✓ Deleted: {key}\")\n\n\n# ---------------------------------------------------------------\n# Interactive helper (used by init_cmd)\n# ---------------------------------------------------------------\n\n\ndef configure_env_interactive() -> None:\n    \"\"\"Interactively add/edit environment variables.\"\"\"\n    from .utils import prompt_confirm\n\n    while True:\n        key = click.prompt(\n            \"  Variable name\",\n            default=\"\",\n            show_default=False,\n        ).strip()\n        if not key:\n            break\n        envs = load_envs()\n        current = envs.get(key, \"\")\n        value = click.prompt(\n            f\"  Value for {key}\",\n            default=current or \"\",\n            show_default=bool(current),\n        )\n        set_env_var(key, value)\n        click.echo(f\"  ✓ {key} = {value}\")\n        if not prompt_confirm(\"Add another variable?\", default=False):\n            break\n    click.echo(\"Environment variable configuration complete.\")\n"
  },
  {
    "path": "src/copaw/cli/http.py",
    "content": "# -*- coding: utf-8 -*-\nfrom __future__ import annotations\n\nimport json\nfrom typing import Any\n\nimport click\nimport httpx\n\n\nDEFAULT_BASE_URL = \"http://127.0.0.1:8088\"\n\n\ndef client(base_url: str) -> httpx.Client:\n    \"\"\"Create HTTP client with /api prefix added to all requests.\"\"\"\n    # Ensure base_url ends with /api\n    base = base_url.rstrip(\"/\")\n    if not base.endswith(\"/api\"):\n        base = f\"{base}/api\"\n    return httpx.Client(base_url=base, timeout=30.0)\n\n\ndef print_json(data: Any) -> None:\n    click.echo(json.dumps(data, ensure_ascii=False, indent=2))\n"
  },
  {
    "path": "src/copaw/cli/init_cmd.py",
    "content": "# -*- coding: utf-8 -*-\n# flake8: noqa: E501\n\"\"\"CLI init: interactively create working_dir config.json and HEARTBEAT.md.\"\"\"\nfrom __future__ import annotations\n\nimport click\nfrom rich.console import Console\nfrom rich.panel import Panel\n\nfrom .channels_cmd import configure_channels_interactive\nfrom .env_cmd import configure_env_interactive\nfrom .providers_cmd import configure_providers_interactive\nfrom .skills_cmd import configure_skills_interactive\nfrom .utils import prompt_confirm, prompt_choice\nfrom ..config import (\n    get_config_path,\n    get_heartbeat_query_path,\n    load_config,\n    save_config,\n)\nfrom ..config.config import (\n    ActiveHoursConfig,\n    Config,\n    HeartbeatConfig,\n)\nfrom ..constant import HEARTBEAT_DEFAULT_EVERY\nfrom ..providers import ProviderManager\nfrom ..constant import WORKING_DIR\n\nSECURITY_WARNING = \"\"\"\nSecurity warning — please read.\n\nCoPaw is a personal assistant that runs in your own environment. It can connect to\nchannels (DingTalk, Feishu, QQ, Discord, iMessage, etc.) and run skills that read\nfiles, run commands, and call external APIs. By default it is a single-operator\nboundary: one trusted user. A malicious or confused prompt can lead the agent to\ndo unsafe things if tools are enabled.\n\nIf multiple people can message the same CoPaw instance with tools enabled, they\nshare the same delegated authority (files, commands, secrets the agent can use).\n\nIf you are not comfortable with access control and hardening, do not run CoPaw with\ntools or expose it to untrusted users. Get help from someone experienced before\nenabling powerful skills or exposing the bot to the internet.\n\nRecommended baseline:\n- Restrict which channels and users can trigger the agent; use allowlists where possible.\n- Multi-user or shared inbox: use separate config/credentials and ideally separate\n  OS users or hosts per trust boundary.\n- Run skills with least privilege; sandbox where you can.\n- Keep secrets out of the agent's working directory and skill-accessible paths.\n- Use a capable model when the agent has tools or handles untrusted input.\n\nReview your config and skills regularly; limit tool scope to what you need.\n\"\"\"\n\nTELEMETRY_INFO = \"\"\"\nHelp improve CoPaw by sharing anonymous usage data!\n\nWe collect only:\n• CoPaw version (e.g., 0.0.7)\n• Install method (pip, Docker, or desktop app)\n• OS and version (e.g., macOS 14.0, Ubuntu 22.04)\n• Python version (e.g., 3.11)\n• CPU architecture (e.g., x86_64, arm64)\n• GPU availability (detected, not detailed specs)\n\nNo personal data collected! No files, no credentials, no identifiable information.\nThis helps us understand CoPaw's usage environment and prioritize improvements.\n\"\"\"\n\n\ndef _echo_security_warning_box() -> None:\n    \"\"\"Print SECURITY_WARNING in a rich panel with blue border.\"\"\"\n    console = Console()\n    console.print(\n        Panel(\n            SECURITY_WARNING.strip(),\n            title=\"[bold]🐾 Security warning — please read[/bold]\",\n            border_style=\"blue\",\n        ),\n    )\n\n\ndef _echo_telemetry_info_box() -> None:\n    \"\"\"Print TELEMETRY_INFO in a rich panel with blue border.\"\"\"\n    console = Console()\n    console.print(\n        Panel(\n            TELEMETRY_INFO.strip(),\n            title=\"[bold]📊 Help improve CoPaw[/bold]\",\n            border_style=\"blue\",\n        ),\n    )\n\n\nDEFAULT_HEARTBEAT_MDS = {\n    \"zh\": \"\"\"# Heartbeat checklist\n- 扫描收件箱紧急邮件\n- 查看未来 2h 的日历\n- 检查待办是否卡住\n- 若安静超过 8h，轻量 check-in\n\"\"\",\n    \"en\": \"\"\"# Heartbeat checklist\n- Scan inbox for urgent email\n- Check calendar for next 2h\n- Check tasks for blockers\n- Light check-in if quiet for 8h\n\"\"\",\n    \"ru\": \"\"\"# Heartbeat checklist\n- Проверить входящие на срочные письма\n- Просмотреть календарь на ближайшие 2 часа\n- Проверить задачи на наличие блокировок\n- Лёгкая проверка при отсутствии активности более 8 часов\n\"\"\",\n}\n\n\n@click.command(\"init\")\n@click.option(\n    \"--force\",\n    is_flag=True,\n    help=\"Overwrite existing config.json and HEARTBEAT.md if present.\",\n)\n@click.option(\n    \"--defaults\",\n    \"use_defaults\",\n    is_flag=True,\n    help=\"Use defaults only, no interactive prompts (for scripts).\",\n)\n@click.option(\n    \"--accept-security\",\n    \"accept_security\",\n    is_flag=True,\n    help=\"Skip security confirmation (use with --defaults for scripts/Docker).\",\n)\n# pylint: disable=too-many-branches,too-many-statements\ndef init_cmd(\n    force: bool,\n    use_defaults: bool,\n    accept_security: bool,\n) -> None:\n    \"\"\"Create working dir with config.json and HEARTBEAT.md (interactive).\"\"\"\n    from pathlib import Path\n    from ..app.migration import ensure_default_agent_exists\n\n    config_path = get_config_path()\n    working_dir = config_path.parent\n    heartbeat_path = get_heartbeat_query_path()\n\n    click.echo(f\"Working dir: {working_dir}\")\n\n    # --- Security warning: must accept to continue ---\n    _echo_security_warning_box()\n    if use_defaults and accept_security:\n        click.echo(\n            \"Security acceptance assumed (--accept-security with --defaults).\",\n        )\n    else:\n        accepted = prompt_confirm(\n            \"Have you read and accepted the security notice above? (yes to continue, no to abort)\",\n            default=True,\n        )\n        if not accepted:\n            click.echo(\n                \"Initialization aborted. Read the security notice and run again when ready.\",\n            )\n            raise click.Abort()\n    working_dir.mkdir(parents=True, exist_ok=True)\n\n    # --- Telemetry collection (optional, anonymous) ---\n    from ..utils.telemetry import (\n        collect_and_upload_telemetry,\n        has_telemetry_been_collected,\n        is_telemetry_opted_out,\n        mark_telemetry_collected,\n    )\n\n    if not is_telemetry_opted_out(\n        working_dir,\n    ) and not has_telemetry_been_collected(working_dir):\n        if use_defaults:\n            success = collect_and_upload_telemetry(working_dir)\n\n        else:\n            _echo_telemetry_info_box()\n            if prompt_confirm(\"Share usage data?\", default=True):\n                success = collect_and_upload_telemetry(working_dir)\n                if success:\n                    click.echo(\"✓ Thank you!\")\n            else:\n                mark_telemetry_collected(working_dir, opted_out=True)\n\n    # --- Ensure default agent workspace exists ---\n    click.echo(\"\\n=== Default Workspace Initialization ===\")\n    ensure_default_agent_exists()\n    click.echo(\"✓ Default workspace initialized\")\n\n    # Get default workspace path for subsequent operations\n    default_workspace = Path(f\"{WORKING_DIR}/workspaces/default\").expanduser()\n\n    # --- config.json ---\n    write_config = True\n    if config_path.is_file() and not force and not use_defaults:\n        prompt_text = (\n            f\"{config_path} exists. Do you want to overwrite it? \"\n            '(\"no\" for skipping the configuration process)'\n        )\n        write_config = prompt_confirm(prompt_text, default=False)\n    if not write_config:\n        click.echo(\"Skipping configuration.\")\n    else:\n        if use_defaults:\n            every = HEARTBEAT_DEFAULT_EVERY\n            target = \"main\"\n            active_hours = None\n        else:\n            click.echo(\"\\n=== Heartbeat Configuration ===\")\n            every = click.prompt(\n                \"Heartbeat interval (e.g. 30m, 1h)\",\n                default=HEARTBEAT_DEFAULT_EVERY,\n                type=str,\n            ).strip()\n\n            target = prompt_choice(\n                \"Heartbeat target:\",\n                options=[\"main\", \"last\"],\n                default=\"main\",\n            ).lower()\n\n            use_active = prompt_confirm(\n                \"Set active hours for heartbeat? (skip = run 24h)\",\n                default=False,\n            )\n            active_hours = None\n            if use_active:\n                start = click.prompt(\n                    \"Active start (HH:MM)\",\n                    default=\"08:00\",\n                    type=str,\n                )\n                end = click.prompt(\n                    \"Active end (HH:MM)\",\n                    default=\"22:00\",\n                    type=str,\n                )\n                active_hours = ActiveHoursConfig(\n                    start=start.strip(),\n                    end=end.strip(),\n                )\n\n        hb = HeartbeatConfig(\n            every=every or HEARTBEAT_DEFAULT_EVERY,\n            target=target or \"main\",\n            active_hours=active_hours,\n        )\n        existing = (\n            load_config(config_path) if config_path.is_file() else Config()\n        )\n        # Ensure agents.defaults exists\n        if existing.agents.defaults is None:\n            from ..config.config import AgentsDefaultsConfig\n\n            existing.agents.defaults = AgentsDefaultsConfig()\n        existing.agents.defaults.heartbeat = hb\n\n        # --- show_tool_details ---\n        if use_defaults:\n            existing.show_tool_details = True\n        else:\n            existing.show_tool_details = prompt_confirm(\n                \"Show tool call/result details in channel messages?\",\n                default=True,\n            )\n\n        # --- language selection ---\n        if not use_defaults:\n            language = prompt_choice(\n                \"Select language for MD files:\",\n                options=[\"zh\", \"en\", \"ru\"],\n                default=existing.agents.language,\n            )\n            existing.agents.language = language\n\n        # --- audio mode selection ---\n        if not use_defaults:\n            audio_mode = prompt_choice(\n                \"Select audio mode for voice messages:\\n\"\n                \"  auto   - transcribe if provider available, else file placeholder\\n\"\n                \"  native - send audio directly to model (needs ffmpeg)\\n\"\n                \"Audio mode:\",\n                options=[\"auto\", \"native\"],\n                default=existing.agents.audio_mode,\n            )\n            existing.agents.audio_mode = audio_mode\n\n        # --- transcription provider type selection ---\n        if not use_defaults and audio_mode != \"native\":\n            provider_type = prompt_choice(\n                \"Select transcription provider:\\n\"\n                \"  disabled       - no transcription\\n\"\n                \"  whisper_api    - remote Whisper API endpoint\\n\"\n                \"  local_whisper  - locally installed openai-whisper\\n\"\n                \"                   (requires ffmpeg + openai-whisper)\\n\"\n                \"Provider:\",\n                options=[\"disabled\", \"whisper_api\", \"local_whisper\"],\n                default=existing.agents.transcription_provider_type,\n            )\n            existing.agents.transcription_provider_type = provider_type\n\n        # --- channels (interactive when not --defaults) ---\n        if not use_defaults and prompt_confirm(\n            \"Configure channels? \"\n            \"(iMessage/Discord/DingTalk/Feishu/QQ/Console)\",\n            default=False,\n        ):\n            configure_channels_interactive(existing)\n\n        save_config(existing, config_path)\n        click.echo(f\"\\n✓ Configuration saved to {config_path}\")\n\n    # --- LLM provider and model configuration ---\n    provider_manager = ProviderManager.get_instance()\n    activate_llm = provider_manager.get_active_model()\n\n    if (\n        activate_llm is not None\n        and activate_llm.provider_id\n        and activate_llm.model\n    ):\n        click.echo(\n            f\"\\n✓ LLM already configured: \"\n            f\"{activate_llm.provider_id} / {activate_llm.model}\",\n        )\n        if not use_defaults and prompt_confirm(\n            \"Reconfigure LLM provider?\",\n            default=False,\n        ):\n            click.echo(\"\\n=== LLM Provider Configuration ===\")\n            configure_providers_interactive(use_defaults=False)\n        else:\n            click.echo(\"Skipped LLM configuration.\")\n    else:\n        # No active LLM — must configure, cannot skip\n        click.echo(\"\\n=== LLM Provider Configuration (required) ===\")\n        configure_providers_interactive(use_defaults=use_defaults)\n\n    # --- skills (prompt if needed) ---\n    if use_defaults:\n        # Using --defaults: enable all skills, skip existing\n        from ..agents.skills_manager import sync_skills_to_working_dir\n\n        click.echo(\"Enabling all skills by default (skip existing)...\")\n        synced, skipped = sync_skills_to_working_dir(\n            workspace_dir=default_workspace,\n            skill_names=None,\n            force=False,\n        )\n        if skipped:\n            click.echo(\n                f\"✓ Skills synced: {synced}, skipped (existing): {skipped}\",\n            )\n        else:\n            click.echo(f\"✓ All {synced} skills enabled.\")\n    elif write_config:\n        # Interactive mode and config was written: prompt user\n        skills_choice = prompt_choice(\n            \"Configure skills:\",\n            options=[\"all\", \"none\", \"custom\"],\n            default=\"all\",\n        )\n\n        if skills_choice == \"all\":\n            from ..agents.skills_manager import sync_skills_to_working_dir\n\n            click.echo(\"Enabling all skills...\")\n            synced, skipped = sync_skills_to_working_dir(\n                workspace_dir=default_workspace,\n                skill_names=None,\n                force=False,\n            )\n            click.echo(f\"✓ Skills synced: {synced}, skipped: {skipped}\")\n        elif skills_choice == \"custom\":\n            configure_skills_interactive()\n        else:  # none\n            click.echo(\"Skipped skills configuration.\")\n\n    # --- environment variables ---\n    if not use_defaults:\n        if prompt_confirm(\n            \"Configure environment variables?\",\n            default=False,\n        ):\n            configure_env_interactive()\n        else:\n            click.echo(\"Skipped environment variable configuration.\")\n\n    # --- md files (check language change) ---\n    from ..agents.utils import copy_md_files\n\n    config = load_config(config_path) if config_path.is_file() else Config()\n    current_language = (\n        config.agents.language or \"zh\"\n    )  # Default to \"zh\" if None\n    installed_language = config.agents.installed_md_files_language\n\n    if use_defaults:\n        # --defaults: always attempt copy, skip files that already exist\n        # in default workspace (handles freshly mounted empty volumes).\n        click.echo(f\"\\nChecking MD files [language: {current_language}]...\")\n        copied = copy_md_files(\n            current_language,\n            skip_existing=True,\n            workspace_dir=default_workspace,\n        )\n        if copied:\n            config.agents.installed_md_files_language = current_language\n            save_config(config, config_path)\n            click.echo(\n                f\"✓ Copied {len(copied)} md file(s): \" + \", \".join(copied),\n            )\n        else:\n            click.echo(\"✓ MD files already present, skipped.\")\n    elif installed_language != current_language or force:\n        click.echo(f\"\\nChecking MD files [language: {current_language}]...\")\n        if installed_language and installed_language != current_language:\n            click.echo(\n                f\"Language changed: {installed_language} → {current_language}\",\n            )\n        copied = copy_md_files(\n            current_language,\n            workspace_dir=default_workspace,\n        )\n        if copied:\n            config.agents.installed_md_files_language = current_language\n            save_config(config, config_path)\n            click.echo(\n                f\"✓ Copied {len(copied)} md file(s): \" + \", \".join(copied),\n            )\n        else:\n            click.echo(\"⚠ No md files copied\")\n    else:\n        click.echo(\n            f\"\\n✓ MD files [{current_language}] are already up to date.\",\n        )\n\n    # --- HEARTBEAT.md ---\n    write_heartbeat = True\n    if heartbeat_path.is_file() and not force:\n        if use_defaults:\n            click.echo(\"✓ HEARTBEAT.md already present, skipped.\")\n            write_heartbeat = False\n        else:\n            write_heartbeat = prompt_confirm(\n                f\"{heartbeat_path} exists. Overwrite?\",\n                default=False,\n            )\n    if not write_heartbeat:\n        if not use_defaults:\n            click.echo(\"Skipped HEARTBEAT.md.\")\n    else:\n        DEFAULT_HEARTBEAT_MD = DEFAULT_HEARTBEAT_MDS[current_language]\n        if use_defaults:\n            content = DEFAULT_HEARTBEAT_MD\n        else:\n            click.echo(\"\\n=== Heartbeat Query Configuration ===\")\n            if prompt_confirm(\n                \"Edit heartbeat query in your default editor?\",\n                default=True,\n            ):\n                content = click.edit(\n                    DEFAULT_HEARTBEAT_MD,\n                    extension=\".md\",\n                    require_save=False,\n                )\n                if content is None:\n                    content = DEFAULT_HEARTBEAT_MD\n            else:\n                content = DEFAULT_HEARTBEAT_MD\n        heartbeat_path.write_text(\n            content.strip() or DEFAULT_HEARTBEAT_MD,\n            encoding=\"utf-8\",\n        )\n        click.echo(f\"✓ Heartbeat query saved to {heartbeat_path}\")\n\n    click.echo(\"\\n✓ Initialization complete!\")\n"
  },
  {
    "path": "src/copaw/cli/main.py",
    "content": "# -*- coding: utf-8 -*-\nfrom __future__ import annotations\n\nimport logging\nimport sys\nimport time\n\nimport click\n\n# On Windows, force UTF-8 for stdout/stderr so cron and other commands\n# can handle Chinese and other non-ASCII (Linux is UTF-8 by default).\nif sys.platform == \"win32\":\n    try:\n        sys.stdout.reconfigure(encoding=\"utf-8\")\n        sys.stderr.reconfigure(encoding=\"utf-8\")\n    except (AttributeError, OSError):\n        pass\n\n# pylint: disable=wrong-import-position\n\nlogger = logging.getLogger(__name__)\n# Store init timings so app_cmd can re-log after setting log level to debug.\n_init_timings: list[tuple[str, float]] = []\n_t0_main = time.perf_counter()\n_init_timings.append((\"main.py loaded\", 0.0))\n\n\ndef _record(label: str, elapsed: float) -> None:\n    _init_timings.append((label, elapsed))\n    logger.debug(\"%.3fs %s\", elapsed, label)\n\n\n# Timed imports below: order and placement are intentional (E402/C0413).\n_t = time.perf_counter()\nfrom ..config.utils import read_last_api  # noqa: E402\n\n_record(\"..config.utils\", time.perf_counter() - _t)\n\n_t = time.perf_counter()\nfrom ..__version__ import __version__  # noqa: E402\n\n_record(\"..__version__\", time.perf_counter() - _t)\n\n_t = time.perf_counter()\nfrom .app_cmd import app_cmd  # noqa: E402\n\n_record(\".app_cmd\", time.perf_counter() - _t)\n\n_t = time.perf_counter()\nfrom .channels_cmd import channels_group  # noqa: E402\n\n_record(\".channels_cmd\", time.perf_counter() - _t)\n\n_t = time.perf_counter()\nfrom .chats_cmd import chats_group  # noqa: E402\n\n_record(\".chats_cmd\", time.perf_counter() - _t)\n\n_t = time.perf_counter()\nfrom .daemon_cmd import daemon_group  # noqa: E402\n\n_record(\".daemon_cmd\", time.perf_counter() - _t)\n\n_t = time.perf_counter()\nfrom .clean_cmd import clean_cmd  # noqa: E402\n\n_record(\".clean_cmd\", time.perf_counter() - _t)\n\n_t = time.perf_counter()\nfrom .cron_cmd import cron_group  # noqa: E402\n\n_record(\".cron_cmd\", time.perf_counter() - _t)\n\n_t = time.perf_counter()\nfrom .env_cmd import env_group  # noqa: E402\n\n_record(\".env_cmd\", time.perf_counter() - _t)\n\n_t = time.perf_counter()\nfrom .init_cmd import init_cmd  # noqa: E402\n\n_record(\".init_cmd\", time.perf_counter() - _t)\n\n_t = time.perf_counter()\nfrom .providers_cmd import models_group  # noqa: E402\n\n_record(\".providers_cmd\", time.perf_counter() - _t)\n\n_t = time.perf_counter()\nfrom .skills_cmd import skills_group  # noqa: E402\n\n_record(\".skills_cmd\", time.perf_counter() - _t)\n\n_t = time.perf_counter()\nfrom .uninstall_cmd import uninstall_cmd  # noqa: E402\n\n_record(\".uninstall_cmd\", time.perf_counter() - _t)\n\n_t = time.perf_counter()\nfrom .desktop_cmd import desktop_cmd  # noqa: E402\n\n_record(\".desktop_cmd\", time.perf_counter() - _t)\n\n_t = time.perf_counter()\nfrom .update_cmd import update_cmd  # noqa: E402\n\n_record(\".update_cmd\", time.perf_counter() - _t)\n\n_t = time.perf_counter()\nfrom .shutdown_cmd import shutdown_cmd  # noqa: E402\n\n_record(\".shutdown_cmd\", time.perf_counter() - _t)\n\n_t = time.perf_counter()\nfrom .auth_cmd import auth_group  # noqa: E402\n\n_record(\".auth_cmd\", time.perf_counter() - _t)\n\n_total = time.perf_counter() - _t0_main\n_init_timings.append((\"(total imports)\", _total))\nlogger.debug(\"%.3fs (total imports)\", _total)\n\n\ndef log_init_timings() -> None:\n    \"\"\"Emit init timing debug lines after setup_logger(debug) in app_cmd.\"\"\"\n    for label, elapsed in _init_timings:\n        logger.debug(\"%.3fs %s\", elapsed, label)\n\n\n@click.group(context_settings={\"help_option_names\": [\"-h\", \"--help\"]})\n@click.version_option(version=__version__, prog_name=\"CoPaw\")\n@click.option(\"--host\", default=None, help=\"API Host\")\n@click.option(\n    \"--port\",\n    default=None,\n    type=int,\n    help=\"API Port\",\n)\n@click.pass_context\ndef cli(ctx: click.Context, host: str | None, port: int | None) -> None:\n    \"\"\"CoPaw CLI.\"\"\"\n    # default from last run if not provided\n    last = read_last_api()\n    if host is None or port is None:\n        if last:\n            host = host or last[0]\n            port = port or last[1]\n\n    # final fallback\n    host = host or \"127.0.0.1\"\n    port = port or 8088\n\n    ctx.ensure_object(dict)\n    ctx.obj[\"host\"] = host\n    ctx.obj[\"port\"] = port\n\n\ncli.add_command(app_cmd)\ncli.add_command(channels_group)\ncli.add_command(daemon_group)\ncli.add_command(chats_group)\ncli.add_command(clean_cmd)\ncli.add_command(cron_group)\ncli.add_command(env_group)\ncli.add_command(init_cmd)\ncli.add_command(models_group)\ncli.add_command(skills_group)\ncli.add_command(uninstall_cmd)\ncli.add_command(desktop_cmd)\ncli.add_command(update_cmd)\ncli.add_command(shutdown_cmd)\ncli.add_command(auth_group)\n"
  },
  {
    "path": "src/copaw/cli/process_utils.py",
    "content": "# -*- coding: utf-8 -*-\nfrom __future__ import annotations\n\nimport csv\nimport io\nimport json\nimport re\nimport subprocess\nimport sys\nfrom typing import Optional\n\n\n_PORT_ARG_PATTERN = re.compile(r\"(?:^|\\s)--port(?:=|\\s+)(\\d+)(?=\\s|$)\")\n\n\ndef _coerce_optional_int(value: object) -> Optional[int]:\n    \"\"\"Best-effort conversion of JSON-decoded values to integers.\"\"\"\n    if value is None:\n        return None\n    if isinstance(value, int):\n        return value\n    if isinstance(value, str):\n        try:\n            return int(value)\n        except ValueError:\n            return None\n    return None\n\n\ndef _parse_windows_process_snapshot_json(\n    payload: str,\n) -> dict[int, tuple[Optional[int], str, str]]:\n    \"\"\"Parse PowerShell JSON process snapshot output.\"\"\"\n    if not payload.strip():\n        return {}\n\n    try:\n        data = json.loads(payload)\n    except json.JSONDecodeError:\n        return {}\n\n    rows = data if isinstance(data, list) else [data]\n    snapshot: dict[int, tuple[Optional[int], str, str]] = {}\n    for row in rows:\n        if not isinstance(row, dict):\n            continue\n\n        pid_value = row.get(\"ProcessId\")\n        parent_value = row.get(\"ParentProcessId\")\n        pid = _coerce_optional_int(pid_value)\n        if pid is None:\n            continue\n\n        parent_pid = _coerce_optional_int(parent_value)\n\n        name = str(row.get(\"Name\") or \"\")\n        command = str(row.get(\"CommandLine\") or \"\")\n        snapshot[pid] = (parent_pid, name, command)\n    return snapshot\n\n\ndef _parse_windows_process_snapshot_csv(\n    payload: str,\n) -> dict[int, tuple[Optional[int], str, str]]:\n    \"\"\"Parse WMIC CSV process snapshot output.\"\"\"\n    if not payload.strip():\n        return {}\n\n    snapshot: dict[int, tuple[Optional[int], str, str]] = {}\n    reader = csv.DictReader(io.StringIO(payload))\n    for row in reader:\n        pid_value = (row.get(\"ProcessId\") or \"\").strip()\n        if not pid_value.isdigit():\n            continue\n\n        parent_value = (row.get(\"ParentProcessId\") or \"\").strip()\n        parent_pid = int(parent_value) if parent_value.isdigit() else None\n        pid = int(pid_value)\n        name = (row.get(\"Name\") or \"\").strip()\n        command = (row.get(\"CommandLine\") or \"\").strip()\n        snapshot[pid] = (parent_pid, name, command)\n    return snapshot\n\n\ndef _windows_process_snapshot() -> dict[int, tuple[Optional[int], str, str]]:\n    \"\"\"Return Windows process info as pid -> (parent_pid, name, cmdline).\"\"\"\n    commands = (\n        (\n            [\n                \"powershell\",\n                \"-NoProfile\",\n                \"-Command\",\n                (\n                    \"Get-CimInstance Win32_Process | \"\n                    \"Select-Object ProcessId,ParentProcessId,Name,\"\n                    \"CommandLine | ConvertTo-Json -Compress\"\n                ),\n            ],\n            _parse_windows_process_snapshot_json,\n        ),\n        (\n            [\n                \"wmic\",\n                \"process\",\n                \"get\",\n                \"ProcessId,ParentProcessId,Name,CommandLine\",\n                \"/FORMAT:CSV\",\n            ],\n            _parse_windows_process_snapshot_csv,\n        ),\n    )\n\n    for command, parser in commands:\n        try:\n            result = subprocess.run(\n                command,\n                capture_output=True,\n                text=True,\n                timeout=15,\n                check=False,\n            )\n        except (OSError, subprocess.TimeoutExpired):\n            continue\n\n        snapshot = parser(result.stdout or \"\")\n        if snapshot:\n            return snapshot\n    return {}\n\n\ndef _process_table() -> list[tuple[int, str]]:\n    \"\"\"Return a best-effort process table as (pid, command line).\"\"\"\n    if sys.platform == \"win32\":\n        return [\n            (pid, command or name or \"\")\n            for pid, (\n                _parent_pid,\n                name,\n                command,\n            ) in _windows_process_snapshot().items()\n        ]\n\n    try:\n        result = subprocess.run(\n            [\"ps\", \"-ax\", \"-o\", \"pid=\", \"-o\", \"command=\"],\n            capture_output=True,\n            text=True,\n            timeout=10,\n            check=False,\n        )\n    except (OSError, subprocess.TimeoutExpired):\n        return []\n\n    rows: list[tuple[int, str]] = []\n    for line in (result.stdout or \"\").splitlines():\n        stripped = line.strip()\n        if not stripped:\n            continue\n        parts = stripped.split(None, 1)\n        if not parts or not parts[0].isdigit():\n            continue\n        command = parts[1] if len(parts) > 1 else \"\"\n        rows.append((int(parts[0]), command))\n    return rows\n\n\ndef _matches_copaw_cli_command(command: str, *subcommands: str) -> bool:\n    \"\"\"Return whether command line looks like a CoPaw CLI invocation.\"\"\"\n    lowered = f\" {command.lower()}\"\n    return any(\n        pattern in lowered\n        for subcommand in subcommands\n        for pattern in (\n            f\" -m copaw {subcommand}\",\n            f\" copaw {subcommand}\",\n            f\"__main__.py {subcommand}\",\n            f'copaw.exe\" {subcommand}',\n            f\"copaw.exe {subcommand}\",\n        )\n    )\n\n\ndef _is_copaw_service_command(command: str) -> bool:\n    \"\"\"Return whether the command line looks like a local CoPaw app.\"\"\"\n    return _matches_copaw_cli_command(command, \"app\")\n\n\ndef _is_copaw_wrapper_process(name: str, command: str) -> bool:\n    \"\"\"Return whether the process looks like a CoPaw CLI wrapper.\"\"\"\n    lowered_name = name.lower().removesuffix(\".exe\")\n    return lowered_name == \"copaw\" or _matches_copaw_cli_command(\n        command,\n        \"app\",\n        \"desktop\",\n    )\n\n\ndef _extract_port_from_command(command: str, default: int = 8088) -> int:\n    \"\"\"Extract `--port` from a command line when present.\"\"\"\n    match = _PORT_ARG_PATTERN.search(command)\n    return int(match.group(1)) if match else default\n\n\ndef _base_url(host: str, port: int) -> str:\n    \"\"\"Build a base URL from host and port.\"\"\"\n    normalized_host = host.strip()\n    if \":\" in normalized_host and not normalized_host.startswith(\"[\"):\n        normalized_host = f\"[{normalized_host}]\"\n    return f\"http://{normalized_host}:{port}\"\n\n\ndef _candidate_hosts(host: str | None) -> list[str]:\n    \"\"\"Return host variants that can reach a local CoPaw service.\"\"\"\n    if not host:\n        return []\n\n    normalized = host.strip()\n    lowered = normalized.lower().strip(\"[]\")\n    candidates: list[str] = []\n\n    def _add(value: str) -> None:\n        if value and value not in candidates:\n            candidates.append(value)\n\n    if lowered in {\"0.0.0.0\", \"::\"}:\n        _add(\"127.0.0.1\")\n        _add(\"localhost\")\n        if lowered == \"::\":\n            _add(\"::1\")\n    elif lowered == \"localhost\":\n        _add(\"localhost\")\n        _add(\"127.0.0.1\")\n        _add(\"::1\")\n\n    _add(normalized)\n    return candidates\n"
  },
  {
    "path": "src/copaw/cli/providers_cmd.py",
    "content": "# -*- coding: utf-8 -*-\n\"\"\"CLI commands for managing LLM providers.\"\"\"\nfrom __future__ import annotations\n\nimport asyncio\nfrom typing import Optional\n\nimport click\n\nfrom ..providers.ollama_manager import OllamaModelManager\nfrom ..providers.provider import ModelInfo, Provider, ProviderInfo\nfrom ..providers.provider_manager import ProviderManager\nfrom .utils import prompt_choice\n\n\ndef _manager() -> ProviderManager:\n    return ProviderManager.get_instance()\n\n\ndef _mask_api_key(api_key: str) -> str:\n    if not api_key:\n        return \"\"\n    if len(api_key) <= 8:\n        return \"*\" * len(api_key)\n    return f\"{api_key[:4]}...{api_key[-2:]}\"\n\n\ndef _is_configured(provider: Provider) -> bool:\n    if provider.is_local or provider.id == \"ollama\":\n        return True\n    # for API-based providers, we consider them\n    # configured if they have a base URL and (if required) an API key\n    if not provider.base_url:\n        return False\n    if provider.require_api_key and not provider.api_key:\n        return False\n    return True\n\n\ndef _save_provider(manager: ProviderManager, provider_id: str) -> None:\n    provider = manager.get_provider(provider_id)\n    if provider is None:\n        return\n    manager._save_provider(  # pylint: disable=protected-access\n        provider,\n        is_builtin=provider_id in manager.builtin_providers,\n    )\n\n\ndef _all_provider_objects(manager: ProviderManager) -> list[Provider]:\n    objs: list[Provider] = []\n    for info in asyncio.run(manager.list_provider_info()):\n        provider = manager.get_provider(info.id)\n        if provider is not None:\n            objs.append(provider)\n    return objs\n\n\ndef _get_ollama_host() -> str:\n    manager = _manager()\n    provider = manager.get_provider(\"ollama\")\n    if provider is None or not provider.base_url:\n        return \"http://127.0.0.1:11434\"\n    return provider.base_url\n\n\ndef _select_provider_interactive(\n    prompt_text: str = \"Select provider:\",\n    *,\n    default_pid: str = \"\",\n) -> str:\n    \"\"\"Prompt user to pick a provider. Returns provider_id.\"\"\"\n    manager = _manager()\n    all_providers = _all_provider_objects(manager)\n\n    labels: list[str] = []\n    ids: list[str] = []\n    for provider in all_providers:\n        mark = \"✓\" if _is_configured(provider) else \"✗\"\n        labels.append(f\"{provider.name} ({provider.id}) [{mark}]\")\n        ids.append(provider.id)\n\n    default_label: Optional[str] = None\n    if default_pid in ids:\n        default_label = labels[ids.index(default_pid)]\n\n    chosen_label = prompt_choice(\n        prompt_text,\n        options=labels,\n        default=default_label,\n    )\n    return ids[labels.index(chosen_label)]\n\n\ndef configure_provider_api_key_interactive(\n    provider_id: str | None = None,\n) -> str:\n    \"\"\"Interactively configure a provider's API key. Returns provider_id.\"\"\"\n    manager = _manager()\n\n    if provider_id is None:\n        provider_id = _select_provider_interactive(\n            \"Select provider to configure API key:\",\n        )\n\n    defn = manager.get_provider(provider_id)\n    if defn is None:\n        click.echo(\n            click.style(\n                f\"Error: provider '{provider_id}' not found.\",\n                fg=\"red\",\n            ),\n        )\n        raise SystemExit(1)\n    if not defn.require_api_key:\n        click.echo(\n            f\"{defn.name} does not require API key configuration. Skipping.\",\n        )\n        return provider_id\n\n    current_base, current_key = defn.base_url, defn.api_key\n\n    base_url: Optional[str] = None\n    # Prompt for base_url if the provider is custom or has no default URL\n    # (e.g. Azure OpenAI requires user to provide their endpoint).\n    if defn.is_custom or provider_id == \"azure-openai\" or not current_base:\n        azure_hint = (\n            \"Azure endpoint \"\n            \"(e.g. https://.openai.azure.com/openai/v1)\"\n        )\n        url_hint = (\n            azure_hint\n            if provider_id == \"azure-openai\"\n            else \"Base URL (OpenAI-compatible endpoint)\"\n        )\n        base_url = click.prompt(\n            url_hint,\n            default=current_base or \"\",\n            show_default=bool(current_base),\n        ).strip()\n        if not base_url:\n            click.echo(click.style(\"Error: base_url is required.\", fg=\"red\"))\n            raise SystemExit(1)\n\n    hint = (\n        f\"prefix: {defn.api_key_prefix}\" if defn.api_key_prefix else \"optional\"\n    )\n    api_key = click.prompt(\n        f\"API key ({hint})\",\n        default=current_key or \"\",\n        hide_input=True,\n        show_default=False,\n        prompt_suffix=f\" [{'set' if current_key else 'not set'}]: \",\n    )\n\n    ok = manager.update_provider(\n        provider_id,\n        {\n            \"api_key\": api_key if api_key else None,\n            \"base_url\": base_url,\n        },\n    )\n    if not ok:\n        click.echo(\n            click.style(\n                f\"Error: provider '{provider_id}' not found.\",\n                fg=\"red\",\n            ),\n        )\n        raise SystemExit(1)\n\n    click.echo(\n        f\"✓ {defn.name} — API Key: {_mask_api_key(api_key) or '(not set)'}\"\n        + (f\", Base URL: {base_url}\" if base_url else \"\"),\n    )\n    return provider_id\n\n\ndef _add_models_interactive(provider_id: str) -> None:\n    \"\"\"Interactively add models to a provider after configuration.\"\"\"\n    manager = _manager()\n    defn = manager.get_provider(provider_id)\n    if defn is None:\n        click.echo(\n            click.style(\n                f\"Error: provider '{provider_id}' not found.\",\n                fg=\"red\",\n            ),\n        )\n        raise SystemExit(1)\n\n    # Ollama models cannot be added manually - they come from Ollama daemon\n    if provider_id == \"ollama\":\n        return\n\n    extra = list(defn.extra_models)\n    all_models = list(defn.models) + extra\n\n    if all_models:\n        click.echo(f\"\\nCurrent models for {defn.name}:\")\n        for m in all_models:\n            click.echo(f\"  - {m.name} ({m.id})\")\n    else:\n        click.echo(f\"\\nNo models configured for {defn.name}.\")\n\n    # Default to yes if there are no models at all\n    while click.confirm(\"Add a model?\", default=not all_models):\n        model_id = click.prompt(\"Model identifier\").strip()\n        if not model_id:\n            click.echo(click.style(\"Error: model id is required.\", fg=\"red\"))\n            continue\n        model_name = click.prompt(\n            \"Model display name\",\n            default=model_id,\n        ).strip()\n        try:\n            ok, msg = asyncio.run(\n                defn.add_model(ModelInfo(id=model_id, name=model_name)),\n            )\n            if ok:\n                _save_provider(manager, provider_id)\n                click.echo(f\"✓ Model '{model_name}' ({model_id}) added.\")\n                all_models.append(ModelInfo(id=model_id, name=model_name))\n            else:\n                click.echo(click.style(f\"Error: {msg}\", fg=\"red\"))\n        except ValueError as exc:\n            click.echo(click.style(f\"Error: {exc}\", fg=\"red\"))\n\n\ndef _pick_model_from_list(\n    models: list[ModelInfo],\n    prompt_text: str,\n    current_model: str = \"\",\n) -> str:\n    labels = [m.name for m in models]\n    ids = [m.id for m in models]\n\n    default_label: Optional[str] = None\n    if current_model in ids:\n        default_label = labels[ids.index(current_model)]\n\n    chosen = prompt_choice(prompt_text, options=labels, default=default_label)\n    return ids[labels.index(chosen)]\n\n\ndef _pick_model_free_text(prompt_text: str, current_model: str = \"\") -> str:\n    model = click.prompt(prompt_text, default=current_model or \"\").strip()\n    if not model:\n        click.echo(click.style(\"Error: model name is required.\", fg=\"red\"))\n        raise SystemExit(1)\n    return model\n\n\ndef _filter_eligible(all_providers: list[Provider]) -> list[Provider]:\n    return [d for d in all_providers if _is_configured(d)]\n\n\ndef _select_llm_model(defn, pid, current_slot, *, use_defaults):\n    \"\"\"Pick a model for the given provider. Returns model id.\"\"\"\n    cur = (\n        current_slot.model\n        if current_slot and current_slot.provider_id == pid\n        else \"\"\n    )\n\n    extra = list(defn.extra_models)\n    all_models = list(defn.models) + extra\n\n    if use_defaults:\n        return cur or (all_models[0].id if all_models else \"\")\n\n    if all_models:\n        return _pick_model_from_list(\n            all_models,\n            \"Select LLM model:\",\n            current_model=cur,\n        )\n    return _pick_model_free_text(\n        \"LLM model name (required):\",\n        current_model=cur,\n    )\n\n\ndef configure_llm_slot_interactive(*, use_defaults: bool = False) -> None:\n    \"\"\"Interactively configure the active LLM model slot.\"\"\"\n    manager = _manager()\n    all_providers = _all_provider_objects(manager)\n    current_slot = manager.get_active_model()\n\n    eligible = _filter_eligible(all_providers)\n\n    if not eligible:\n        if use_defaults:\n            click.echo(\n                \"No LLM provider configured. Run 'copaw models config' \"\n                \"to configure later.\",\n            )\n            return\n        click.echo(\n            click.style(\n                \"No providers are configured yet. Let's configure one now.\",\n                fg=\"yellow\",\n            ),\n        )\n        pid = configure_provider_api_key_interactive()\n        _add_models_interactive(pid)\n        manager = _manager()\n        current_slot = manager.get_active_model()\n        eligible = _filter_eligible(_all_provider_objects(manager))\n        if not eligible:\n            click.echo(\n                click.style(\"Error: provider configuration failed.\", fg=\"red\"),\n            )\n            raise SystemExit(1)\n\n    ids = [d.id for d in eligible]\n    if use_defaults:\n        if not ids:\n            click.echo(\"No eligible provider found.\")\n            return\n        pid = (\n            current_slot.provider_id\n            if current_slot and current_slot.provider_id in ids\n            else ids[0]\n        )\n    else:\n        labels = [f\"{d.name} ({d.id})\" for d in eligible]\n        default_label = (\n            labels[ids.index(current_slot.provider_id)]\n            if current_slot and current_slot.provider_id in ids\n            else None\n        )\n        chosen_label = prompt_choice(\n            \"Select provider for LLM:\",\n            options=labels,\n            default=default_label,\n        )\n        pid = ids[labels.index(chosen_label)]\n\n    defn = manager.get_provider(pid)\n    if defn is None:\n        click.echo(\n            click.style(f\"Error: provider '{pid}' not found.\", fg=\"red\"),\n        )\n        raise SystemExit(1)\n    model = _select_llm_model(\n        defn,\n        pid,\n        current_slot,\n        use_defaults=use_defaults,\n    )\n    if not model and use_defaults:\n        click.echo(\n            f\"No default model for {defn.name}. \"\n            \"Run 'copaw models config' to set one.\",\n        )\n        return\n    try:\n        asyncio.run(manager.activate_model(pid, model))\n    except ValueError as exc:\n        if use_defaults:\n            click.echo(\n                f\"Skip default activation for {defn.name}: {exc}\",\n            )\n            return\n        click.echo(click.style(f\"Error: {exc}\", fg=\"red\"))\n        raise SystemExit(1) from exc\n    click.echo(f\"✓ LLM: {defn.name} / {model}\")\n\n\ndef configure_providers_interactive(*, use_defaults: bool = False) -> None:\n    \"\"\"Full interactive setup: configure provider → add models →\n    activate LLM.\"\"\"\n    if use_defaults:\n        configure_llm_slot_interactive(use_defaults=True)\n        return\n\n    click.echo(\"\\n--- Provider Configuration ---\")\n    while True:\n        pid = configure_provider_api_key_interactive()\n\n        # For local providers (llamacpp, mlx, ollama),\n        # skip to model activation directly\n        manager = _manager()\n        defn = manager.get_provider(pid)\n        if defn is None:\n            click.echo(\n                click.style(\n                    f\"Error: provider '{pid}' not found.\",\n                    fg=\"red\",\n                ),\n            )\n            raise SystemExit(1)\n        if defn.is_local or pid == \"ollama\":\n            click.echo(f\"\\n--- Activate {defn.name} Model ---\")\n            configure_llm_slot_interactive()\n            return\n\n        _add_models_interactive(pid)\n        if not click.confirm(\"Configure another provider?\", default=False):\n            break\n\n    click.echo(\"\\n--- Activate LLM Model ---\")\n    configure_llm_slot_interactive()\n\n\n@click.group(\"models\")\ndef models_group() -> None:\n    \"\"\"Manage LLM models and provider configuration.\"\"\"\n\n\n@models_group.command(\"list\")\ndef list_cmd() -> None:\n    \"\"\"Show all providers and their current configuration.\"\"\"\n    manager = _manager()\n\n    click.echo(\"\\n=== Providers ===\")\n    for defn in _all_provider_objects(manager):\n        cur_url, cur_key = defn.base_url, defn.api_key\n\n        tag = (\n            \" [custom]\"\n            if defn.is_custom\n            else \" [local]\"\n            if defn.is_local\n            else \"\"\n        )\n        click.echo(f\"\\n{'─' * 44}\")\n        click.echo(f\"  {defn.name} ({defn.id}){tag}\")\n        click.echo(f\"{'─' * 44}\")\n\n        if defn.is_local:\n            all_models = list(defn.models)\n            if all_models:\n                click.echo(f\"  {'models':16s}:\")\n                for m in all_models:\n                    click.echo(f\"    - {m.name}\")\n            else:\n                click.echo(\"  No models downloaded.\")\n                click.echo(\"  Use 'copaw models download' to add models.\")\n        else:\n            click.echo(f\"  {'base_url':16s}: {cur_url or '(not set)'}\")\n            click.echo(\n                f\"  {'api_key':16s}: \"\n                f\"{_mask_api_key(cur_key) or '(not set)'}\",\n            )\n            if defn.api_key_prefix:\n                click.echo(\n                    f\"  {'api_key_prefix':16s}: {defn.api_key_prefix}\",\n                )\n\n            extra = list(defn.extra_models)\n            all_models = list(defn.models) + extra\n            if all_models:\n                click.echo(f\"  {'models':16s}:\")\n                extra_ids = {m.id for m in extra}\n                for m in all_models:\n                    label = \" [user-added]\" if m.id in extra_ids else \"\"\n                    click.echo(f\"    - {m.name} ({m.id}){label}\")\n\n    click.echo(f\"\\n{'═' * 44}\")\n    click.echo(\"  Active Model Slot\")\n    click.echo(f\"{'═' * 44}\")\n\n    llm = manager.get_active_model()\n    if llm and llm.provider_id and llm.model:\n        click.echo(f\"  {'LLM':16s}: {llm.provider_id} / {llm.model}\")\n    else:\n        click.echo(f\"  {'LLM':16s}: (not configured)\")\n    click.echo()\n\n\n@models_group.command(\"config\")\ndef config_cmd() -> None:\n    \"\"\"Interactively configure providers and active models.\"\"\"\n    configure_providers_interactive()\n\n\n@models_group.command(\"config-key\")\n@click.argument(\"provider_id\", required=False, default=None)\ndef config_key_cmd(provider_id: str | None) -> None:\n    \"\"\"Configure a provider's API key.\"\"\"\n    configure_provider_api_key_interactive(provider_id)\n\n\n@models_group.command(\"set-llm\")\ndef set_llm_cmd() -> None:\n    \"\"\"Interactively set the active LLM model.\"\"\"\n    configure_llm_slot_interactive()\n\n\n@models_group.command(\"add-provider\")\n@click.argument(\"provider_id\")\n@click.option(\"--name\", \"-n\", required=True, help=\"Human-readable name\")\n@click.option(\"--base-url\", \"-u\", default=\"\", help=\"Default API base URL\")\n@click.option(\"--api-key-prefix\", default=\"\", help=\"Expected API key prefix\")\ndef add_provider_cmd(\n    provider_id: str,\n    name: str,\n    base_url: str,\n    api_key_prefix: str,\n) -> None:\n    \"\"\"Add a new custom provider.\"\"\"\n    manager = _manager()\n    try:\n        provider_info = asyncio.run(\n            manager.add_custom_provider(\n                ProviderInfo(\n                    id=provider_id,\n                    name=name,\n                    base_url=base_url,\n                    api_key_prefix=api_key_prefix,\n                    is_custom=True,\n                    chat_model=\"OpenAIChatModel\",\n                ),\n            ),\n        )\n    except ValueError as exc:\n        click.echo(click.style(f\"Error: {exc}\", fg=\"red\"))\n        raise SystemExit(1) from exc\n    click.echo(\n        \"✓ Custom provider \"\n        f\"'{provider_info.name}' ({provider_info.id}) created.\",\n    )\n    if provider_info.id != provider_id:\n        click.echo(f\"  requested id: {provider_id}\")\n    if base_url:\n        click.echo(f\"  base_url: {base_url}\")\n    click.echo(\n        \"  Run 'copaw models add-model' to add models, \"\n        \"then 'copaw models config-key' to set the API key.\",\n    )\n\n\n@models_group.command(\"remove-provider\")\n@click.argument(\"provider_id\")\n@click.option(\"--yes\", \"-y\", is_flag=True, help=\"Skip confirmation\")\ndef remove_provider_cmd(provider_id: str, yes: bool) -> None:\n    \"\"\"Remove a custom provider.\"\"\"\n    manager = _manager()\n    if provider_id in manager.builtin_providers:\n        click.echo(\n            click.style(\n                f\"Error: '{provider_id}' is a built-in provider and \"\n                \"cannot be removed.\",\n                fg=\"red\",\n            ),\n        )\n        raise SystemExit(1)\n    if not yes:\n        if not click.confirm(\n            f\"Delete custom provider '{provider_id}' and all its models?\",\n        ):\n            return\n    try:\n        ok = manager.remove_custom_provider(provider_id)\n        if not ok:\n            raise ValueError(f\"Custom provider '{provider_id}' not found.\")\n    except ValueError as exc:\n        click.echo(click.style(f\"Error: {exc}\", fg=\"red\"))\n        raise SystemExit(1) from exc\n    click.echo(f\"✓ Custom provider '{provider_id}' deleted.\")\n\n\n@models_group.command(\"add-model\")\n@click.argument(\"provider_id\")\n@click.option(\"--model-id\", \"-m\", required=True, help=\"Model identifier\")\n@click.option(\"--model-name\", \"-n\", required=True, help=\"Model display name\")\ndef add_model_cmd(provider_id: str, model_id: str, model_name: str) -> None:\n    \"\"\"Add a model to any provider (built-in or custom).\"\"\"\n    manager = _manager()\n    # Prevent manual model addition for Ollama\n    if provider_id == \"ollama\":\n        click.echo(\n            click.style(\n                \"Error: Ollama models cannot be added manually. \"\n                \"Use 'ollama pull ' to download models.\",\n                fg=\"red\",\n            ),\n        )\n        raise SystemExit(1)\n\n    try:\n        provider = manager.get_provider(provider_id)\n        if provider is None:\n            raise ValueError(f\"Provider '{provider_id}' not found.\")\n        asyncio.run(\n            provider.add_model(ModelInfo(id=model_id, name=model_name)),\n        )\n        _save_provider(manager, provider_id)\n    except ValueError as exc:\n        click.echo(click.style(f\"Error: {exc}\", fg=\"red\"))\n        raise SystemExit(1) from exc\n    click.echo(\n        f\"✓ Model '{model_name}' ({model_id}) added to '{provider_id}'.\",\n    )\n\n\n@models_group.command(\"remove-model\")\n@click.argument(\"provider_id\")\n@click.option(\"--model-id\", \"-m\", required=True, help=\"Model identifier\")\ndef remove_model_cmd(provider_id: str, model_id: str) -> None:\n    \"\"\"Remove a user-added model from any provider.\"\"\"\n    manager = _manager()\n    # Prevent manual model removal for Ollama\n    if provider_id == \"ollama\":\n        click.echo(\n            click.style(\n                \"Error: Ollama models cannot be removed via this command. \"\n                \"Use 'ollama rm ' to delete models.\",\n                fg=\"red\",\n            ),\n        )\n        raise SystemExit(1)\n\n    try:\n        provider = manager.get_provider(provider_id)\n        if provider is None:\n            raise ValueError(f\"Provider '{provider_id}' not found.\")\n        ok, msg = asyncio.run(provider.delete_model(model_id=model_id))\n        if ok:\n            _save_provider(manager, provider_id)\n            click.echo(f\"✓ Model '{model_id}' removed from '{provider_id}'.\")\n        else:\n            click.echo(click.style(f\"Error: {msg}\", fg=\"red\"))\n    except ValueError as exc:\n        click.echo(click.style(f\"Error: {exc}\", fg=\"red\"))\n        raise SystemExit(1) from exc\n\n\n# ---------------------------------------------------------------------------\n# Local model management commands\n# ---------------------------------------------------------------------------\n\n\n@models_group.command(\"download\")\n@click.argument(\"repo_id\")\n@click.option(\n    \"--file\",\n    \"-f\",\n    \"filename\",\n    default=None,\n    help=\"Specific file to download (e.g., 'model.Q4_K_M.gguf')\",\n)\n@click.option(\n    \"--backend\",\n    \"-b\",\n    type=click.Choice([\"llamacpp\", \"mlx\"]),\n    default=\"llamacpp\",\n    help=\"Target backend\",\n)\n@click.option(\n    \"--source\",\n    \"-s\",\n    type=click.Choice([\"huggingface\", \"modelscope\"]),\n    default=\"huggingface\",\n    help=\"Download source\",\n)\ndef download_cmd(\n    repo_id: str,\n    filename: str | None,\n    backend: str,\n    source: str,\n) -> None:\n    \"\"\"Download a model from Hugging Face Hub or ModelScope.\n\n    \\b\n    Examples:\n      copaw models download TheBloke/Mistral-7B-Instruct-v0.2-GGUF\n      copaw models download TheBloke/Mistral-7B-Instruct-v0.2-GGUF \\\\\n          -f mistral-7b-instruct-v0.2.Q4_K_M.gguf\n      copaw models download Qwen/Qwen2-0.5B-Instruct-GGUF --source modelscope\n    \"\"\"\n    try:\n        from ..local_models import (\n            LocalModelManager,\n            BackendType,\n            DownloadSource,\n        )\n    except ImportError as exc:\n        click.echo(\n            click.style(\n                \"Local model dependencies not installed. \"\n                \"Install with: pip install 'copaw[local]'\",\n                fg=\"red\",\n            ),\n        )\n        raise SystemExit(1) from exc\n\n    backend_type = BackendType(backend)\n    source_type = DownloadSource(source)\n\n    suffix = f\" ({filename})\" if filename else \"\"\n    click.echo(f\"Downloading {repo_id}{suffix} from {source}...\")\n\n    try:\n        info = LocalModelManager.download_model_sync(\n            repo_id=repo_id,\n            filename=filename,\n            backend=backend_type,\n            source=source_type,\n        )\n    except ImportError as exc:\n        click.echo(click.style(f\"Error: {exc}\", fg=\"red\"))\n        raise SystemExit(1) from exc\n    except Exception as exc:\n        click.echo(click.style(f\"Download failed: {exc}\", fg=\"red\"))\n        raise SystemExit(1) from exc\n\n    size_mb = info.file_size / (1024 * 1024)\n    click.echo(f\"Done! Model saved to: {info.local_path}\")\n    click.echo(f\"  Size: {size_mb:.1f} MB\")\n    click.echo(f\"  ID: {info.id}\")\n    click.echo(f\"  Backend: {info.backend.value}\")\n    click.echo(\n        f\"\\nTo use this model, run:\\n\"\n        f\"  copaw models set-llm  (select '{backend}' provider)\",\n    )\n\n\n@models_group.command(\"local\")\n@click.option(\n    \"--backend\",\n    \"-b\",\n    type=click.Choice([\"llamacpp\", \"mlx\"]),\n    default=None,\n    help=\"Filter by backend\",\n)\ndef list_local_cmd(backend: str | None) -> None:\n    \"\"\"List all downloaded local models.\"\"\"\n    try:\n        from ..local_models import list_local_models, BackendType\n    except ImportError:\n        click.echo(\n            \"Local model support not installed. \"\n            \"Install with: pip install 'copaw[local]'\",\n        )\n        return\n\n    backend_type = BackendType(backend) if backend else None\n    models = list_local_models(backend=backend_type)\n\n    if not models:\n        click.echo(\"No local models downloaded.\")\n        click.echo(\"Use 'copaw models download ' to download one.\")\n        return\n\n    click.echo(f\"\\n=== Local Models ({len(models)}) ===\")\n    for m in models:\n        size_mb = m.file_size / (1024 * 1024)\n        click.echo(f\"\\n{'─' * 44}\")\n        click.echo(f\"  {m.display_name}\")\n        click.echo(f\"  ID:      {m.id}\")\n        click.echo(f\"  Backend: {m.backend.value}\")\n        click.echo(f\"  Source:  {m.source.value}\")\n        click.echo(f\"  Size:    {size_mb:.1f} MB\")\n        click.echo(f\"  Path:    {m.local_path}\")\n    click.echo()\n\n\n@models_group.command(\"remove-local\")\n@click.argument(\"model_id\")\n@click.option(\"--yes\", \"-y\", is_flag=True, help=\"Skip confirmation\")\ndef remove_local_cmd(model_id: str, yes: bool) -> None:\n    \"\"\"Remove a downloaded local model.\"\"\"\n    try:\n        from ..local_models import delete_local_model\n    except ImportError as exc:\n        click.echo(\n            click.style(\n                \"Local model support not installed. \"\n                \"Install with: pip install 'copaw[local]'\",\n                fg=\"red\",\n            ),\n        )\n        raise SystemExit(1) from exc\n\n    if not yes:\n        if not click.confirm(f\"Delete local model '{model_id}'?\"):\n            return\n    try:\n        delete_local_model(model_id)\n    except ValueError as exc:\n        click.echo(click.style(f\"Error: {exc}\", fg=\"red\"))\n        raise SystemExit(1) from exc\n    click.echo(f\"Done! Model '{model_id}' deleted.\")\n\n\n# ---------------------------------------------------------------------------\n# Ollama model management commands\n# ---------------------------------------------------------------------------\n\n\n@models_group.command(\"ollama-pull\")\n@click.argument(\"model_name\")\ndef ollama_pull_cmd(model_name: str) -> None:\n    \"\"\"Download an Ollama model.\n\n    \\b\n    Examples:\n      copaw models ollama-pull mistral:7b\n      copaw models ollama-pull qwen2.5:3b\n    \"\"\"\n\n    click.echo(f\"Downloading Ollama model: {model_name}...\")\n    try:\n        host = _get_ollama_host()\n        OllamaModelManager.pull_model(model_name, host=host)\n        click.echo(f\"✓ Model '{model_name}' downloaded successfully.\")\n        click.echo(\"\\nTo use this model, run:\\n  copaw models set-llm\")\n    except ImportError as exc:\n        click.echo(\n            click.style(\n                str(exc),\n                fg=\"red\",\n            ),\n        )\n        raise SystemExit(1) from exc\n    except Exception as exc:\n        click.echo(click.style(f\"Download failed: {exc}\", fg=\"red\"))\n        raise SystemExit(1) from exc\n\n\n@models_group.command(\"ollama-list\")\ndef ollama_list_cmd() -> None:\n    \"\"\"List all Ollama models.\"\"\"\n    try:\n        host = _get_ollama_host()\n        models = OllamaModelManager.list_models(host=host)\n    except ImportError as exc:\n        click.echo(\n            click.style(\n                str(exc),\n                fg=\"red\",\n            ),\n        )\n        raise SystemExit(1) from exc\n    except Exception as exc:\n        click.echo(click.style(f\"Error: {exc}\", fg=\"red\"))\n        raise SystemExit(1) from exc\n\n    if not models:\n        click.echo(\"No Ollama models found.\")\n        click.echo(\"Use 'copaw models ollama-pull ' to download one.\")\n        return\n\n    click.echo(f\"\\n=== Ollama Models ({len(models)}) ===\")\n    for m in models:\n        size_gb = m.size / (1024 * 1024 * 1024)\n        click.echo(f\"\\n{'─' * 44}\")\n        click.echo(f\"  {m.name}\")\n        if m.size > 0:\n            click.echo(f\"  Size:    {size_gb:.2f} GB\")\n        if m.digest:\n            click.echo(f\"  Digest:  {m.digest[:16]}...\")\n    click.echo()\n\n\n@models_group.command(\"ollama-remove\")\n@click.argument(\"model_name\")\n@click.option(\"--yes\", \"-y\", is_flag=True, help=\"Skip confirmation\")\ndef ollama_remove_cmd(model_name: str, yes: bool) -> None:\n    \"\"\"Remove an Ollama model.\n\n    \\b\n    Examples:\n      copaw models ollama-remove mistral:7b\n      copaw models ollama-remove qwen2.5:3b -y\n    \"\"\"\n    if not yes:\n        if not click.confirm(f\"Delete Ollama model '{model_name}'?\"):\n            return\n\n    try:\n        host = _get_ollama_host()\n        OllamaModelManager.delete_model(model_name, host=host)\n        click.echo(f\"✓ Model '{model_name}' deleted.\")\n    except ImportError as exc:\n        click.echo(\n            click.style(\n                str(exc),\n                fg=\"red\",\n            ),\n        )\n        raise SystemExit(1) from exc\n    except Exception as exc:\n        click.echo(click.style(f\"Error: {exc}\", fg=\"red\"))\n        raise SystemExit(1) from exc\n"
  },
  {
    "path": "src/copaw/cli/shutdown_cmd.py",
    "content": "# -*- coding: utf-8 -*-\nfrom __future__ import annotations\n\nimport os\nimport signal\nimport subprocess\nimport sys\nimport time\nfrom pathlib import Path\nfrom typing import Optional\n\nimport click\n\nfrom .process_utils import (\n    _is_copaw_wrapper_process,\n    _process_table,\n    _windows_process_snapshot,\n)\n\n\n_PROJECT_ROOT = Path(__file__).resolve().parents[3]\n_CONSOLE_DIR = (_PROJECT_ROOT / \"console\").resolve()\n_SIGTERM = signal.SIGTERM\n_SIGKILL = getattr(signal, \"SIGKILL\", _SIGTERM)\n\n\ndef _backend_port(ctx: click.Context, port: Optional[int]) -> int:\n    \"\"\"Resolve backend port from explicit option or global CLI context.\"\"\"\n    if port is not None:\n        return port\n    return int((ctx.obj or {}).get(\"port\", 8088))\n\n\ndef _listening_pids_for_port(port: int) -> set[int]:\n    \"\"\"Return PIDs currently listening on the given TCP port.\"\"\"\n    if sys.platform == \"win32\":\n        try:\n            result = subprocess.run(\n                [\"netstat\", \"-ano\", \"-p\", \"tcp\"],\n                capture_output=True,\n                text=True,\n                timeout=10,\n                check=False,\n            )\n        except (OSError, subprocess.TimeoutExpired):\n            return set()\n\n        pids: set[int] = set()\n        suffix = f\":{port}\"\n        for line in (result.stdout or \"\").splitlines():\n            parts = line.split()\n            if len(parts) < 5:\n                continue\n            local_addr = parts[1]\n            state = parts[3].upper()\n            if not local_addr.endswith(suffix) or state != \"LISTENING\":\n                continue\n            try:\n                pids.add(int(parts[4]))\n            except ValueError:\n                continue\n        return pids\n\n    commands = (\n        [\"lsof\", \"-nP\", f\"-iTCP:{port}\", \"-sTCP:LISTEN\", \"-t\"],\n        [\"fuser\", f\"{port}/tcp\"],\n    )\n    for command in commands:\n        try:\n            result = subprocess.run(\n                command,\n                capture_output=True,\n                text=True,\n                timeout=10,\n                check=False,\n            )\n        except (OSError, subprocess.TimeoutExpired):\n            continue\n\n        pids = {\n            int(token)\n            for token in (result.stdout or \"\").split()\n            if token.isdigit()\n        }\n        if pids:\n            return pids\n    return set()\n\n\ndef _find_frontend_dev_pids() -> set[int]:\n    \"\"\"Find Vite dev-server processes for this repository's console app.\"\"\"\n    console_dir = str(_CONSOLE_DIR).lower()\n    matches: set[int] = set()\n    for pid, command in _process_table():\n        lowered = command.lower()\n        if \"vite\" in lowered and console_dir in lowered:\n            matches.add(pid)\n            continue\n        if \"copaw-console\" in lowered and (\n            \"npm\" in lowered\n            or \"pnpm\" in lowered\n            or \"yarn\" in lowered\n            or \"node\" in lowered\n        ):\n            matches.add(pid)\n    return matches\n\n\ndef _find_desktop_wrapper_pids() -> set[int]:\n    \"\"\"Find `copaw desktop` wrapper processes for this project.\"\"\"\n    matches: set[int] = set()\n    patterns = (\n        \" -m copaw desktop\",\n        \" copaw desktop\",\n        \"__main__.py desktop\",\n    )\n    for pid, command in _process_table():\n        lowered = f\" {command.lower()}\"\n        if any(pattern in lowered for pattern in patterns):\n            matches.add(pid)\n    return matches\n\n\ndef _find_windows_wrapper_ancestor_pids(pids: set[int]) -> set[int]:\n    \"\"\"Find CoPaw wrapper/supervisor ancestors for Windows backend PIDs.\"\"\"\n    if sys.platform != \"win32\" or not pids:\n        return set()\n\n    snapshot = _windows_process_snapshot()\n    matches: set[int] = set()\n    for pid in pids:\n        visited: set[int] = set()\n        current_pid = pid\n        while True:\n            info = snapshot.get(current_pid)\n            if info is None:\n                break\n\n            parent_pid = info[0]\n            if parent_pid in (None, 0) or parent_pid in visited:\n                break\n            visited.add(parent_pid)\n\n            parent_info = snapshot.get(parent_pid)\n            if parent_info is None:\n                break\n\n            if _is_copaw_wrapper_process(parent_info[1], parent_info[2]):\n                matches.add(parent_pid)\n\n            current_pid = parent_pid\n    return matches\n\n\ndef _child_pids_unix(pid: int) -> set[int]:\n    \"\"\"Recursively collect child PIDs for Unix-like systems.\"\"\"\n    children: set[int] = set()\n    stack = [pid]\n    while stack:\n        current = stack.pop()\n        try:\n            result = subprocess.run(\n                [\"pgrep\", \"-P\", str(current)],\n                capture_output=True,\n                text=True,\n                timeout=5,\n                check=False,\n            )\n        except (OSError, subprocess.TimeoutExpired):\n            continue\n        for token in (result.stdout or \"\").split():\n            if not token.isdigit():\n                continue\n            child = int(token)\n            if child in children:\n                continue\n            children.add(child)\n            stack.append(child)\n    return children\n\n\ndef _pid_exists(pid: int) -> bool:\n    \"\"\"Return whether the PID still exists.\"\"\"\n    if pid <= 0:\n        return False\n    if sys.platform == \"win32\":\n        return pid in _windows_process_snapshot()\n    try:\n        os.kill(pid, 0)\n    except OSError:\n        return False\n    return True\n\n\ndef _wait_for_pid_exit(\n    pid: int,\n    timeout_sec: float,\n    interval_sec: float,\n) -> bool:\n    \"\"\"Wait until a PID exits within the given timeout.\"\"\"\n    deadline = time.monotonic() + timeout_sec\n    while time.monotonic() < deadline:\n        if not _pid_exists(pid):\n            return True\n        time.sleep(interval_sec)\n    return not _pid_exists(pid)\n\n\ndef _signal_process_tree_unix(pid: int, sig: signal.Signals) -> None:\n    \"\"\"Send a signal to a Unix process and its descendants.\"\"\"\n    descendants = sorted(_child_pids_unix(pid), reverse=True)\n    for child_pid in descendants:\n        try:\n            os.kill(child_pid, sig)\n        except OSError:\n            continue\n    try:\n        os.kill(pid, sig)\n    except OSError:\n        pass\n\n\ndef _terminate_process_tree_windows(pid: int, force: bool = False) -> None:\n    \"\"\"Terminate a Windows process tree.\"\"\"\n    command = [\"taskkill\", \"/T\", \"/PID\", str(pid)]\n    if force:\n        command.insert(1, \"/F\")\n    try:\n        subprocess.run(\n            command,\n            capture_output=True,\n            text=True,\n            timeout=10,\n            check=False,\n        )\n    except (OSError, subprocess.TimeoutExpired):\n        pass\n\n\ndef _force_terminate_windows_process(pid: int) -> None:\n    \"\"\"Force terminate a Windows process as a fallback.\"\"\"\n    commands = (\n        [\n            \"powershell\",\n            \"-NoProfile\",\n            \"-Command\",\n            (\n                \"$ErrorActionPreference='SilentlyContinue'; \"\n                f\"Stop-Process -Id {pid} -Force\"\n            ),\n        ],\n        [\"taskkill\", \"/F\", \"/PID\", str(pid)],\n    )\n    for command in commands:\n        try:\n            subprocess.run(\n                command,\n                capture_output=True,\n                text=True,\n                timeout=10,\n                check=False,\n            )\n        except (OSError, subprocess.TimeoutExpired):\n            continue\n\n\ndef _terminate_pid(pid: int, timeout_sec: float = 5.0) -> bool:\n    \"\"\"Terminate a process tree gracefully, then force kill if needed.\"\"\"\n    if not _pid_exists(pid):\n        return True\n\n    if sys.platform == \"win32\":\n        _terminate_process_tree_windows(pid)\n    else:\n        _signal_process_tree_unix(pid, _SIGTERM)\n\n    if _wait_for_pid_exit(pid, timeout_sec, 0.2):\n        return True\n\n    if sys.platform == \"win32\":\n        _terminate_process_tree_windows(pid, force=True)\n        if _wait_for_pid_exit(pid, 2.0, 0.1):\n            return True\n        _force_terminate_windows_process(pid)\n    else:\n        _signal_process_tree_unix(pid, _SIGKILL)\n\n    return _wait_for_pid_exit(pid, 2.0, 0.1)\n\n\ndef _stop_pid_set(pids: set[int]) -> tuple[list[int], list[int]]:\n    \"\"\"Stop a set of PIDs and return (stopped, failed).\"\"\"\n    stopped: list[int] = []\n    failed: list[int] = []\n    for pid in sorted(pids):\n        if _terminate_pid(pid):\n            stopped.append(pid)\n        else:\n            failed.append(pid)\n    return stopped, failed\n\n\n@click.command(\"shutdown\", help=\"Force stop the running CoPaw app processes.\")\n@click.option(\n    \"--port\",\n    default=None,\n    type=int,\n    help=\"Backend port to stop. Defaults to global --port from config.\",\n)\n@click.pass_context\ndef shutdown_cmd(ctx: click.Context, port: Optional[int]) -> None:\n    \"\"\"Stop the running CoPaw app processes.\n\n    `copaw app` only starts the backend process. The web console is normally\n    static files served by that backend. During frontend development, a\n    separate Vite process may also be running from the repository's\n    `console/` directory, and this command will stop that as well.\n    \"\"\"\n    backend_port = _backend_port(ctx, port)\n    backend_pids = _listening_pids_for_port(backend_port)\n    frontend_pids = _find_frontend_dev_pids()\n    desktop_pids = _find_desktop_wrapper_pids()\n    wrapper_pids = _find_windows_wrapper_ancestor_pids(backend_pids)\n\n    # Build a process table for logging.\n    proc_table = dict(_process_table())\n\n    def log_pid_set(title, pids):\n        if not pids:\n            click.echo(f\"{title}: nothing to stop\")\n            return\n        click.echo(f\"{title} ({len(pids)} total):\")\n        for pid in sorted(pids):\n            cmd = proc_table.get(pid, \"\")\n            click.echo(f\"  PID {pid}: {cmd}\")\n\n    log_pid_set(\"Backend listener processes\", backend_pids)\n    log_pid_set(\"Frontend development processes\", frontend_pids)\n    log_pid_set(\"Desktop wrapper processes\", desktop_pids)\n    log_pid_set(\"Related wrapper processes\", wrapper_pids)\n\n    all_targets = backend_pids | frontend_pids | desktop_pids | wrapper_pids\n    if not all_targets:\n        raise click.ClickException(\n            \"No running CoPaw backend/frontend process was found.\",\n        )\n\n    wrapper_stopped, wrapper_failed = _stop_pid_set(wrapper_pids)\n    frontend_stopped, frontend_failed = _stop_pid_set(frontend_pids)\n    desktop_stopped, desktop_failed = _stop_pid_set(\n        desktop_pids - set(wrapper_stopped) - set(frontend_stopped),\n    )\n    backend_stopped, backend_failed = _stop_pid_set(\n        backend_pids\n        - set(wrapper_stopped)\n        - set(frontend_stopped)\n        - set(desktop_stopped),\n    )\n\n    stopped = (\n        wrapper_stopped + frontend_stopped + desktop_stopped + backend_stopped\n    )\n    failed = list(\n        set(\n            wrapper_failed + frontend_failed + desktop_failed + backend_failed,\n        ),\n    )\n\n    if stopped:\n        click.echo(\n            \"Stopped CoPaw processes: \"\n            + \", \".join(str(pid) for pid in sorted(stopped)),\n        )\n    if failed:\n        click.echo(\"Failed to stop the following processes:\")\n        for pid in sorted(failed):\n            cmd = proc_table.get(pid, \"\")\n            click.echo(f\"  PID {pid}: {cmd}\")\n        raise click.ClickException(\n            \"Failed to shutdown process(es): \"\n            + \", \".join(str(pid) for pid in sorted(failed)),\n        )\n"
  },
  {
    "path": "src/copaw/cli/skills_cmd.py",
    "content": "# -*- coding: utf-8 -*-\n\"\"\"CLI skill: list and interactively enable/disable skills.\"\"\"\nfrom __future__ import annotations\n\nfrom pathlib import Path\n\nimport click\n\nfrom ..agents.skills_manager import SkillService, list_available_skills\nfrom ..constant import WORKING_DIR\nfrom ..config import load_config\nfrom .utils import prompt_checkbox, prompt_confirm\n\n\ndef _get_agent_workspace(agent_id: str) -> Path:\n    \"\"\"Get agent workspace directory.\"\"\"\n    try:\n        config = load_config()\n        if agent_id in config.agents.profiles:\n            ref = config.agents.profiles[agent_id]\n            workspace_dir = Path(ref.workspace_dir).expanduser()\n            return workspace_dir\n    except Exception:\n        pass\n    return WORKING_DIR\n\n\n# pylint: disable=too-many-branches\ndef configure_skills_interactive(\n    agent_id: str = \"default\",\n    working_dir: Path | None = None,\n) -> None:\n    \"\"\"Interactively select which skills to enable (multi-select).\"\"\"\n    if working_dir is None:\n        working_dir = _get_agent_workspace(agent_id)\n\n    click.echo(f\"Configuring skills for agent: {agent_id}\\n\")\n\n    skill_service = SkillService(working_dir)\n    all_skills = skill_service.list_all_skills()\n    if not all_skills:\n        click.echo(\"No skills found. Nothing to configure.\")\n        return\n\n    available = set(list_available_skills(working_dir))\n    all_names = {s.name for s in all_skills}\n\n    # Default to all skills if nothing is currently active (first time)\n    default_checked = available if available else all_names\n\n    # Build checkbox options: (label, value)\n    options: list[tuple[str, str]] = []\n    for skill in sorted(all_skills, key=lambda s: s.name):\n        status = \"✓\" if skill.name in available else \"✗\"\n        label = f\"{skill.name}  [{status}] ({skill.source})\"\n        options.append((label, skill.name))\n\n    click.echo(\"\\n=== Skills Configuration ===\")\n    click.echo(\"Use ↑/↓ to move,  to toggle,  to confirm.\\n\")\n\n    selected = prompt_checkbox(\n        \"Select skills to enable:\",\n        options=options,\n        checked=default_checked,\n        select_all_option=False,\n    )\n\n    # Ctrl+C → cancel\n    if selected is None:\n        click.echo(\"\\n\\nOperation cancelled.\")\n        return\n\n    selected_set = set(selected)\n\n    # Show preview of changes\n    to_enable = selected_set - available\n    to_disable = (all_names & available) - selected_set\n\n    if not to_enable and not to_disable:\n        click.echo(\"\\nNo changes needed.\")\n        return\n\n    click.echo()\n    if to_enable:\n        click.echo(\n            click.style(\n                f\"  + Enable:  {', '.join(sorted(to_enable))}\",\n                fg=\"green\",\n            ),\n        )\n    if to_disable:\n        click.echo(\n            click.style(\n                f\"  - Disable: {', '.join(sorted(to_disable))}\",\n                fg=\"red\",\n            ),\n        )\n\n    # Confirm save or skip\n    save = prompt_confirm(\"Apply changes?\", default=True)\n    if not save:\n        click.echo(\"Skipped. No changes applied.\")\n        return\n\n    # Apply changes\n    for name in to_enable:\n        result = skill_service.enable_skill(name)\n        if result:\n            click.echo(f\"  ✓ Enabled: {name}\")\n        else:\n            click.echo(\n                click.style(f\"  ✗ Failed to enable: {name}\", fg=\"red\"),\n            )\n\n    for name in to_disable:\n        result = skill_service.disable_skill(name)\n        if result:\n            click.echo(f\"  ✓ Disabled: {name}\")\n        else:\n            click.echo(\n                click.style(f\"  ✗ Failed to disable: {name}\", fg=\"red\"),\n            )\n\n    click.echo(\"\\n✓ Skills configuration updated!\")\n\n\n@click.group(\"skills\")\ndef skills_group() -> None:\n    \"\"\"Manage skills (list / configure).\"\"\"\n\n\n@skills_group.command(\"list\")\n@click.option(\n    \"--agent-id\",\n    default=\"default\",\n    help=\"Agent ID (defaults to 'default')\",\n)\ndef list_cmd(agent_id: str) -> None:\n    \"\"\"Show all skills and their enabled/disabled status.\"\"\"\n    working_dir = _get_agent_workspace(agent_id)\n\n    click.echo(f\"Skills for agent: {agent_id}\\n\")\n\n    skill_service = SkillService(working_dir)\n    all_skills = skill_service.list_all_skills()\n    available = set(list_available_skills(working_dir))\n\n    if not all_skills:\n        click.echo(\"No skills found.\")\n        return\n\n    click.echo(f\"\\n{'─' * 50}\")\n    click.echo(f\"  {'Skill Name':<30s} {'Source':<12s} Status\")\n    click.echo(f\"{'─' * 50}\")\n\n    for skill in sorted(all_skills, key=lambda s: s.name):\n        status = (\n            click.style(\"✓ enabled\", fg=\"green\")\n            if skill.name in available\n            else click.style(\"✗ disabled\", fg=\"red\")\n        )\n        click.echo(f\"  {skill.name:<30s} {skill.source:<12s} {status}\")\n\n    click.echo(f\"{'─' * 50}\")\n    enabled_count = sum(1 for s in all_skills if s.name in available)\n    click.echo(\n        f\"  Total: {len(all_skills)} skills, \"\n        f\"{enabled_count} enabled, \"\n        f\"{len(all_skills) - enabled_count} disabled\\n\",\n    )\n\n\n@skills_group.command(\"config\")\n@click.option(\n    \"--agent-id\",\n    default=\"default\",\n    help=\"Agent ID (defaults to 'default')\",\n)\ndef configure_cmd(agent_id: str) -> None:\n    \"\"\"Interactively configure skills.\"\"\"\n    configure_skills_interactive(agent_id=agent_id)\n"
  },
  {
    "path": "src/copaw/cli/uninstall_cmd.py",
    "content": "# -*- coding: utf-8 -*-\n\"\"\"copaw uninstall — remove the CoPaw environment and CLI wrapper.\"\"\"\nfrom __future__ import annotations\n\nimport shutil\nimport re\nfrom pathlib import Path\n\nimport click\n\nfrom ..constant import WORKING_DIR\n\n\n# Directories created by the installer (relative to WORKING_DIR).\n_INSTALLER_DIRS = (\"venv\", \"bin\")\n\n# Shell profiles to clean up.\n_SHELL_PROFILES = (\n    Path.home() / \".zshrc\",\n    Path.home() / \".bashrc\",\n    Path.home() / \".bash_profile\",\n)\n\n\ndef _remove_path_entry(profile: Path) -> bool:\n    \"\"\"\n    Remove CoPaw PATH lines from a shell profile. Returns True if changed.\n    \"\"\"\n    if not profile.is_file():\n        return False\n\n    text = profile.read_text()\n    # Remove the \"# CoPaw\" comment line and the export PATH line\n    cleaned = re.sub(\n        r\"\\n?# CoPaw\\nexport PATH=\\\"\\$HOME/\\.copaw/bin:\\$PATH\\\"\\n?\",\n        \"\\n\",\n        text,\n    )\n    if cleaned == text:\n        return False\n\n    profile.write_text(cleaned)\n    return True\n\n\n@click.command(\"uninstall\")\n@click.option(\n    \"--purge\",\n    is_flag=True,\n    help=\"Also remove all data (config, chats, models, etc.)\",\n)\n@click.option(\"--yes\", is_flag=True, help=\"Do not prompt for confirmation\")\ndef uninstall_cmd(purge: bool, yes: bool) -> None:\n    \"\"\"Remove CoPaw environment, CLI wrapper, and shell PATH entries.\"\"\"\n    wd = WORKING_DIR\n\n    if purge:\n        click.echo(f\"This will remove ALL CoPaw data in {wd}\")\n    else:\n        click.echo(\n            \"This will remove the CoPaw Python environment and CLI wrapper.\",\n        )\n        click.echo(f\"Your configuration and data in {wd} will be preserved.\")\n\n    if not yes:\n        ok = click.confirm(\"Continue?\", default=False)\n        if not ok:\n            click.echo(\"Cancelled.\")\n            return\n\n    # Remove installer-managed directories\n    for dirname in _INSTALLER_DIRS:\n        d = wd / dirname\n        if d.exists():\n            shutil.rmtree(d)\n            click.echo(f\"  Removed {d}\")\n\n    # Purge everything if requested\n    if purge and wd.exists():\n        shutil.rmtree(wd)\n        click.echo(f\"  Removed {wd}\")\n\n    # Clean shell profiles\n    for profile in _SHELL_PROFILES:\n        if _remove_path_entry(profile):\n            click.echo(f\"  Cleaned {profile}\")\n\n    click.echo(\"\")\n    click.echo(\"CoPaw uninstalled. Please restart your terminal.\")\n"
  },
  {
    "path": "src/copaw/cli/update_cmd.py",
    "content": "# -*- coding: utf-8 -*-\nfrom __future__ import annotations\n\nimport json\nimport os\nimport signal\nimport shutil\nimport subprocess\nimport sys\nimport time\nfrom dataclasses import asdict, dataclass\nfrom importlib import metadata\nfrom pathlib import Path\nfrom typing import Any\nfrom urllib.parse import urlparse\n\nimport click\nimport httpx\nfrom packaging.version import InvalidVersion, Version\n\nfrom ..__version__ import __version__\nfrom ..constant import WORKING_DIR\nfrom ..config.utils import read_last_api\nfrom .process_utils import (\n    _base_url,\n    _candidate_hosts,\n    _extract_port_from_command,\n    _is_copaw_service_command,\n    _process_table,\n)\n\n_PYPI_JSON_URL = \"https://pypi.org/pypi/copaw/json\"\n\n\ndef _subprocess_text_kwargs() -> dict[str, Any]:\n    \"\"\"Return robust text-decoding settings for subprocess output.\n\n    Package installers may emit UTF-8 regardless of the active Windows code\n    page. Using replacement for undecodable bytes prevents the update worker\n    from crashing while streaming output.\n    \"\"\"\n    return {\n        \"text\": True,\n        \"encoding\": \"utf-8\",\n        \"errors\": \"replace\",\n    }\n\n\n@dataclass(frozen=True)\nclass InstallInfo:\n    \"\"\"Information about the current CoPaw installation.\"\"\"\n\n    package_dir: str\n    python_executable: str\n    environment_root: str\n    environment_kind: str\n    installer: str\n    source_type: str\n    source_url: str | None = None\n\n\n@dataclass(frozen=True)\nclass RunningServiceInfo:\n    \"\"\"Detected CoPaw service endpoint state.\"\"\"\n\n    is_running: bool\n    base_url: str | None = None\n    version: str | None = None\n\n\ndef _version_obj(version: str) -> Any:\n    \"\"\"Parse version when possible; otherwise keep the raw string.\"\"\"\n    try:\n        return Version(version)\n    except InvalidVersion:\n        return version\n\n\ndef _is_newer_version(latest: str, current: str) -> bool | None:\n    \"\"\"Return whether latest is newer than current.\n\n    Returns `None` when either version cannot be compared reliably.\n    \"\"\"\n    parsed_latest = _version_obj(latest)\n    parsed_current = _version_obj(current)\n    if isinstance(parsed_latest, str) or isinstance(parsed_current, str):\n        if latest == current:\n            return False\n        return None\n    return parsed_latest > parsed_current\n\n\ndef _fetch_latest_version() -> str:\n    \"\"\"Fetch the latest published CoPaw version from PyPI.\"\"\"\n    try:\n        resp = httpx.get(\n            _PYPI_JSON_URL,\n            timeout=10.0,\n            headers={\"Accept\": \"application/json\"},\n        )\n        resp.raise_for_status()\n        data = resp.json()\n    except httpx.HTTPError as exc:\n        raise click.ClickException(\n            f\"Failed to fetch the latest CoPaw version from PyPI: {exc}\",\n        ) from exc\n    except json.JSONDecodeError as exc:\n        raise click.ClickException(\n            \"Received an invalid response from PyPI when checking for the \"\n            f\"latest CoPaw version: {exc}\",\n        ) from exc\n    version = str(data.get(\"info\", {}).get(\"version\", \"\")).strip()\n    if not version:\n        raise click.ClickException(\n            \"Unable to determine the latest CoPaw version.\",\n        )\n    return version\n\n\ndef _detect_source_type(\n    direct_url: dict[str, Any] | None,\n) -> tuple[str, str | None]:\n    \"\"\"Classify the current installation origin.\"\"\"\n    if not direct_url:\n        return (\"pypi\", None)\n\n    url = direct_url.get(\"url\")\n    dir_info = direct_url.get(\"dir_info\") or {}\n    if dir_info.get(\"editable\"):\n        return (\"editable\", url)\n    if direct_url.get(\"vcs_info\"):\n        return (\"vcs\", url)\n    if isinstance(url, str) and url.startswith(\"file://\"):\n        return (\"local\", url)\n    return (\"direct-url\", url if isinstance(url, str) else None)\n\n\ndef _detect_installation() -> InstallInfo:\n    \"\"\"Inspect the current Python environment and installation style.\"\"\"\n    dist = metadata.distribution(\"copaw\")\n    # if installed through uv, installer will be `uv`\n    installer = (dist.read_text(\"INSTALLER\") or \"pip\").strip() or \"pip\"\n\n    direct_url: dict[str, Any] | None = None\n    direct_url_text = dist.read_text(\"direct_url.json\")\n    if direct_url_text:\n        try:\n            direct_url = json.loads(direct_url_text)\n        except json.JSONDecodeError:\n            direct_url = None\n\n    source_type, source_url = _detect_source_type(direct_url)\n    package_dir = Path(__file__).resolve().parent.parent\n    python_executable = sys.executable\n    environment_root = Path(sys.prefix).resolve()\n    environment_kind = (\n        \"virtualenv\" if sys.prefix != sys.base_prefix else \"system\"\n    )\n\n    return InstallInfo(\n        package_dir=str(package_dir),\n        python_executable=str(python_executable),\n        environment_root=str(environment_root),\n        environment_kind=environment_kind,\n        installer=installer,\n        source_type=source_type,\n        source_url=source_url,\n    )\n\n\ndef _probe_service(base_url: str) -> RunningServiceInfo:\n    \"\"\"Probe a possible running CoPaw HTTP service.\"\"\"\n    try:\n        resp = httpx.get(\n            f\"{base_url.rstrip('/')}/api/version\",\n            timeout=2.0,\n            headers={\"Accept\": \"application/json\"},\n            trust_env=False,\n        )\n        resp.raise_for_status()\n        payload = resp.json()\n    except (httpx.HTTPError, ValueError):\n        return RunningServiceInfo(is_running=False)\n\n    version = payload.get(\"version\") if isinstance(payload, dict) else None\n    return RunningServiceInfo(\n        is_running=True,\n        base_url=base_url.rstrip(\"/\"),\n        version=str(version) if version else None,\n    )\n\n\ndef _process_candidate_ports() -> list[int]:\n    \"\"\"Infer candidate local CoPaw service ports from running processes.\"\"\"\n    ports: list[int] = []\n    for _pid, command in _process_table():\n        if not _is_copaw_service_command(command):\n            continue\n\n        port = _extract_port_from_command(command)\n        if port not in ports:\n            ports.append(port)\n    return ports\n\n\ndef _detect_running_service_from_processes(\n    preferred_hosts: list[str],\n) -> RunningServiceInfo:\n    \"\"\"Best-effort local process fallback for service detection.\"\"\"\n    for port in _process_candidate_ports():\n        hosts = preferred_hosts or [\"127.0.0.1\", \"localhost\"]\n        for host in hosts:\n            result = _probe_service(_base_url(host, port))\n            if result.is_running:\n                return result\n\n        fallback_host = next(iter(hosts), \"127.0.0.1\")\n        return RunningServiceInfo(\n            is_running=True,\n            base_url=_base_url(fallback_host, port),\n        )\n\n    return RunningServiceInfo(is_running=False)\n\n\ndef _detect_running_service(\n    host: str | None,\n    port: int | None,\n) -> RunningServiceInfo:\n    \"\"\"Detect whether a CoPaw HTTP service is currently running.\"\"\"\n    candidates: list[str] = []\n    seen: set[str] = set()\n    preferred_hosts: list[str] = []\n\n    def _remember_hosts(candidate_host: str | None) -> None:\n        for item in _candidate_hosts(candidate_host):\n            if item not in preferred_hosts:\n                preferred_hosts.append(item)\n\n    def _add_candidate(\n        candidate_host: str | None,\n        candidate_port: int | None,\n    ) -> None:\n        if not candidate_host or candidate_port is None:\n            return\n        _remember_hosts(candidate_host)\n        for resolved_host in _candidate_hosts(candidate_host):\n            base_url = _base_url(resolved_host, candidate_port)\n            if base_url in seen:\n                continue\n            seen.add(base_url)\n            candidates.append(base_url)\n\n    _add_candidate(host, port)\n    last = read_last_api()\n    if last:\n        _add_candidate(last[0], last[1])\n    _add_candidate(\"127.0.0.1\", 8088)\n\n    for base_url in candidates:\n        result = _probe_service(base_url)\n        if result.is_running:\n            return result\n\n    return _detect_running_service_from_processes(preferred_hosts)\n\n\ndef _running_service_display(running: RunningServiceInfo) -> str:\n    \"\"\"Build a concise running-service description for user prompts.\"\"\"\n    if not running.base_url:\n        return \"a running CoPaw service\"\n    version_suffix = f\" (version {running.version})\" if running.version else \"\"\n    return f\"CoPaw service at {running.base_url}{version_suffix}\"\n\n\ndef _confirm_force_shutdown(running: RunningServiceInfo) -> bool:\n    \"\"\"Ask whether `copaw shutdown` should be used before updating.\"\"\"\n    click.echo(\"\")\n    click.secho(\"!\" * 72, fg=\"yellow\", bold=True)\n    click.secho(\n        \"WARNING: RUNNING COPAW SERVICE DETECTED\",\n        fg=\"yellow\",\n        bold=True,\n    )\n    click.secho(\"!\" * 72, fg=\"yellow\", bold=True)\n    click.secho(\n        f\"Detected {_running_service_display(running)}.\",\n        fg=\"yellow\",\n        bold=True,\n    )\n    click.secho(\n        \"Running `copaw shutdown` will forcibly terminate the current \"\n        \"CoPaw backend/frontend processes.\",\n        fg=\"red\",\n        bold=True,\n    )\n    click.secho(\n        \"Active requests, background tasks, or unsaved work may be \"\n        \"interrupted immediately.\",\n        fg=\"red\",\n        bold=True,\n    )\n    click.echo(\"\")\n    return click.confirm(\n        \"Run `copaw shutdown` now and continue with the update?\",\n        default=False,\n    )\n\n\ndef _run_shutdown_for_update(\n    info: InstallInfo,\n    running: RunningServiceInfo,\n) -> None:\n    \"\"\"Run `copaw shutdown` in the current environment before updating.\"\"\"\n    command = [info.python_executable, \"-m\", \"copaw\"]\n    parsed = urlparse(running.base_url or \"\")\n    if parsed.port is not None:\n        command.extend([\"--port\", str(parsed.port)])\n    command.append(\"shutdown\")\n\n    click.echo(\"\")\n    click.echo(\"Running `copaw shutdown` before updating...\")\n\n    try:\n        result = subprocess.run(\n            command,\n            stdout=subprocess.PIPE,\n            stderr=subprocess.STDOUT,\n            **_subprocess_text_kwargs(),\n            check=False,\n        )\n    except OSError as exc:\n        raise click.ClickException(\n            \"Failed to run `copaw shutdown`: \" f\"{exc}\",\n        ) from exc\n\n    output = (result.stdout or \"\").strip()\n    if output:\n        click.echo(output)\n\n    if result.returncode != 0:\n        raise click.ClickException(\n            \"`copaw shutdown` failed. Please stop the running CoPaw \"\n            \"service manually before running `copaw update`.\",\n        )\n\n\ndef _build_upgrade_command(\n    info: InstallInfo,\n    latest_version: str,\n) -> tuple[list[str], str]:\n    \"\"\"Build the installer command used by the detached update worker.\"\"\"\n    package_spec = f\"copaw=={latest_version}\"\n    installer = info.installer.lower()\n    if installer.startswith(\"uv\") and shutil.which(\"uv\"):\n        return (\n            [\n                \"uv\",\n                \"pip\",\n                \"install\",\n                \"--python\",\n                info.python_executable,\n                \"--upgrade\",\n                package_spec,\n                \"--prerelease=allow\",\n            ],\n            \"uv pip\",\n        )\n    return (\n        [\n            info.python_executable,\n            \"-m\",\n            \"pip\",\n            \"install\",\n            \"--upgrade\",\n            package_spec,\n            \"--disable-pip-version-check\",\n        ],\n        \"pip\",\n    )\n\n\ndef _plan_dir() -> Path:\n    \"\"\"Directory used to persist short-lived update worker plans.\"\"\"\n    return WORKING_DIR / \"updates\"\n\n\ndef _write_worker_plan(plan: dict[str, Any]) -> Path:\n    \"\"\"Persist a worker plan for the detached process.\"\"\"\n    plan_dir = _plan_dir()\n    plan_dir.mkdir(parents=True, exist_ok=True)\n    plan_path = plan_dir / f\"update-{int(time.time() * 1000)}.json\"\n    plan_path.write_text(\n        json.dumps(plan, ensure_ascii=False, indent=2),\n        encoding=\"utf-8\",\n    )\n    return plan_path\n\n\ndef _spawn_update_worker(\n    plan_path: Path,\n    *,\n    capture_output: bool = True,\n) -> subprocess.Popen[str]:\n    \"\"\"Spawn the worker that performs the actual package upgrade.\"\"\"\n    worker_code = (\n        \"from copaw.cli.update_cmd import run_update_worker; \"\n        \"import sys; \"\n        \"sys.exit(run_update_worker(sys.argv[1]))\"\n    )\n    kwargs: dict[str, Any] = {\"stdin\": subprocess.DEVNULL}\n    if capture_output:\n        kwargs.update(\n            {\n                \"stdout\": subprocess.PIPE,\n                \"stderr\": subprocess.STDOUT,\n                **_subprocess_text_kwargs(),\n                \"bufsize\": 1,\n            },\n        )\n    if sys.platform == \"win32\":\n        kwargs[\"creationflags\"] = getattr(\n            subprocess,\n            \"CREATE_NEW_PROCESS_GROUP\",\n            0,\n        )\n    else:\n        kwargs[\"start_new_session\"] = True\n\n    return subprocess.Popen(  # pylint: disable=consider-using-with\n        [sys.executable, \"-u\", \"-c\", worker_code, str(plan_path)],\n        **kwargs,\n    )\n\n\ndef _terminate_update_worker(proc: subprocess.Popen[str]) -> None:\n    \"\"\"Best-effort termination for the worker and its installer child.\"\"\"\n    if proc.poll() is not None:\n        return\n\n    try:\n        if sys.platform == \"win32\":\n            ctrl_break = getattr(signal, \"CTRL_BREAK_EVENT\", None)\n            if ctrl_break is not None:\n                proc.send_signal(ctrl_break)\n                try:\n                    proc.wait(timeout=5)\n                    return\n                except subprocess.TimeoutExpired:\n                    pass\n            proc.terminate()\n        else:\n            os.killpg(proc.pid, signal.SIGTERM)\n    except (OSError, ProcessLookupError, ValueError):\n        return\n\n    try:\n        proc.wait(timeout=5)\n    except subprocess.TimeoutExpired:\n        try:\n            proc.kill()\n        except OSError:\n            return\n\n\ndef _wait_for_process_exit(pid: int | None, timeout: float = 15.0) -> None:\n    \"\"\"Wait briefly for another process to exit before updating files.\"\"\"\n    if pid is None or pid <= 0:\n        return\n\n    if sys.platform == \"win32\":\n        try:\n            import ctypes\n\n            kernel32 = ctypes.windll.kernel32\n            synchronize = 0x00100000\n            wait_timeout = 0x00000102\n            handle = kernel32.OpenProcess(synchronize, False, pid)\n            if not handle:\n                return\n            try:\n                result = kernel32.WaitForSingleObject(\n                    handle,\n                    max(0, int(timeout * 1000)),\n                )\n                if result == wait_timeout:\n                    time.sleep(1.0)\n            finally:\n                kernel32.CloseHandle(handle)\n        except (AttributeError, ImportError, OSError):\n            time.sleep(min(timeout, 2.0))\n        return\n\n    deadline = time.monotonic() + timeout\n    while time.monotonic() < deadline:\n        try:\n            os.kill(pid, 0)\n        except OSError:\n            return\n        time.sleep(0.1)\n\n\ndef _run_update_worker_foreground(plan_path: Path) -> int:\n    \"\"\"Run the update worker in a child process and wait for completion.\"\"\"\n    try:\n        proc = _spawn_update_worker(plan_path)\n    except OSError as exc:\n        raise click.ClickException(\n            \"Failed to start update worker: \" f\"{exc}\",\n        ) from exc\n\n    try:\n        with proc:\n            if proc.stdout is not None:\n                for line in proc.stdout:\n                    click.echo(line.rstrip())\n            return proc.wait()\n    except KeyboardInterrupt:\n        click.echo(\"\")\n        click.echo(\"[copaw] Update interrupted. Stopping installer...\")\n        _terminate_update_worker(proc)\n        return 130\n\n\ndef _run_update_worker_detached(plan_path: Path) -> None:\n    \"\"\"Launch the update worker and return immediately.\"\"\"\n    try:\n        _spawn_update_worker(plan_path, capture_output=False)\n    except OSError as exc:\n        raise click.ClickException(\n            \"Failed to start update worker: \" f\"{exc}\",\n        ) from exc\n\n\ndef _load_worker_plan(plan_path: str | Path) -> dict[str, Any]:\n    \"\"\"Load a persisted worker plan.\"\"\"\n    return json.loads(Path(plan_path).read_text(encoding=\"utf-8\"))\n\n\ndef run_update_worker(plan_path: str | Path) -> int:\n    \"\"\"Run the update worker and stream installer output.\"\"\"\n    path = Path(plan_path)\n    plan = _load_worker_plan(path)\n    command = [str(part) for part in plan[\"command\"]]\n\n    _wait_for_process_exit(plan.get(\"launcher_pid\"))\n\n    click.echo(\"\")\n    click.echo(\n        \"[copaw] Updating CoPaw \"\n        f\"{plan['current_version']} -> {plan['latest_version']}...\",\n    )\n    click.echo(f\"[copaw] Using installer: {plan['installer_label']}\")\n\n    try:\n        with subprocess.Popen(\n            command,\n            stdout=subprocess.PIPE,\n            stderr=subprocess.STDOUT,\n            **_subprocess_text_kwargs(),\n            bufsize=1,\n        ) as proc:\n            if proc.stdout is not None:\n                for line in proc.stdout:\n                    click.echo(line.rstrip())\n            return_code = proc.wait()\n    except FileNotFoundError as exc:\n        click.echo(f\"[copaw] Update failed: {exc}\")\n        return_code = 1\n    finally:\n        try:\n            path.unlink(missing_ok=True)\n        except OSError:\n            pass\n\n    if return_code == 0:\n        click.echo(\"[copaw] Update completed successfully.\")\n        click.echo(\n            \"[copaw] Please restart any running CoPaw service \"\n            \"to use the new version.\",\n        )\n    else:\n        click.echo(f\"[copaw] Update failed with exit code {return_code}.\")\n        click.echo(\n            \"[copaw] Please fix the error above and run \"\n            \"`copaw update` again.\",\n        )\n\n    return return_code\n\n\ndef _echo_install_summary(info: InstallInfo, latest_version: str) -> None:\n    \"\"\"Print the update summary shown before launching the worker.\"\"\"\n    click.echo(f\"Current version: {__version__}\")\n    click.echo(f\"Latest version:  {latest_version}\")\n    click.echo(f\"Python:          {info.python_executable}\")\n    click.echo(\n        f\"Environment:     {info.environment_kind} \"\n        f\"({info.environment_root})\",\n    )\n    click.echo(f\"Install path:    {info.package_dir}\")\n    click.echo(f\"Installer:       {info.installer}\")\n\n\ndef _confirm_source_override(info: InstallInfo, yes: bool) -> bool:\n    \"\"\"Confirm whether a non-PyPI installation should be overwritten.\"\"\"\n    if info.source_type == \"pypi\":\n        return True\n\n    detail = f\" ({info.source_url})\" if info.source_url else \"\"\n    message = (\n        \"Detected a non-PyPI installation source: \"\n        f\"{info.source_type}{detail}. Updating will overwrite the current \"\n        \"installation with the PyPI release for this environment.\"\n    )\n\n    if yes:\n        click.echo(\n            f\"Warning: {message} Proceeding because `--yes` was provided.\",\n        )\n        return True\n\n    click.echo(f\"Warning: {message}\")\n    return click.confirm(\n        \"Continue and replace the current installation with the PyPI \"\n        \"version?\",\n        default=False,\n    )\n\n\n@click.command(\"update\")\n@click.option(\n    \"--yes\",\n    is_flag=True,\n    help=\"Do not prompt before starting the update\",\n)\n@click.pass_context\ndef update_cmd(ctx: click.Context, yes: bool) -> None:\n    \"\"\"Upgrade CoPaw in the current Python environment.\"\"\"\n    info = _detect_installation()\n    latest_version = _fetch_latest_version()\n\n    _echo_install_summary(info, latest_version)\n\n    version_check = _is_newer_version(latest_version, __version__)\n    if version_check is False:\n        click.echo(\"CoPaw is already up to date.\")\n        return\n\n    if not _confirm_source_override(info, yes):\n        click.echo(\"Cancelled.\")\n        return\n\n    if version_check is None:\n        if yes:\n            click.echo(\n                \"Warning: unable to compare the current version\"\n                f\"({__version__}) with the latest version ({latest_version})\"\n                \" automatically. Proceeding because `--yes` was provided.\",\n            )\n        elif not click.confirm(\n            f\"Unable to compare the current version ({__version__}) with the \"\n            f\"latest version ({latest_version}) automatically. Continue with \"\n            \"update anyway?\",\n            default=False,\n        ):\n            click.echo(\"Cancelled.\")\n            return\n\n    running = _detect_running_service(\n        ctx.obj.get(\"host\") if ctx.obj else None,\n        ctx.obj.get(\"port\") if ctx.obj else None,\n    )\n    if running.is_running:\n        if yes:\n            raise click.ClickException(\n                \"Detected \"\n                f\"{_running_service_display(running)}. \"\n                \"Please stop it before running `copaw update`, or rerun \"\n                \"without `--yes` to confirm a forced `copaw shutdown`.\",\n            )\n        if not _confirm_force_shutdown(running):\n            click.echo(\"Cancelled.\")\n            return\n        _run_shutdown_for_update(info, running)\n        running = _detect_running_service(\n            ctx.obj.get(\"host\") if ctx.obj else None,\n            ctx.obj.get(\"port\") if ctx.obj else None,\n        )\n        if running.is_running:\n            raise click.ClickException(\n                \"Detected \"\n                f\"{_running_service_display(running)} after `copaw shutdown`. \"\n                \"Please stop it manually before running `copaw update`.\",\n            )\n\n    if not yes and not click.confirm(\n        f\"Update CoPaw to {latest_version} in the current environment?\",\n        default=True,\n    ):\n        click.echo(\"Cancelled.\")\n        return\n\n    command, installer_label = _build_upgrade_command(info, latest_version)\n    plan = {\n        \"current_version\": __version__,\n        \"latest_version\": latest_version,\n        \"installer_label\": installer_label,\n        \"command\": command,\n        \"install\": asdict(info),\n        \"launcher_pid\": os.getpid() if sys.platform == \"win32\" else None,\n    }\n    plan_path = _write_worker_plan(plan)\n    click.echo(\"\")\n    click.echo(\"Starting CoPaw update...\")\n\n    if sys.platform == \"win32\":\n        _run_update_worker_detached(plan_path)\n        click.echo(\n            \"On Windows, the update will continue after this command exits \"\n            \"to avoid locking `copaw.exe`.\",\n        )\n        click.echo(\"Keep this terminal open until the update completes.\")\n        return\n\n    return_code = _run_update_worker_foreground(plan_path)\n\n    if return_code != 0:\n        ctx.exit(return_code)\n"
  },
  {
    "path": "src/copaw/cli/utils.py",
    "content": "# -*- coding: utf-8 -*-\n\"\"\"Shared interactive prompt helpers used by CLI commands.\n\nAll terminal interaction with *questionary* is centralised here so that\nthe rest of the CLI code never imports questionary directly.\n\"\"\"\nfrom __future__ import annotations\nfrom pathlib import Path\nfrom typing import Optional\n\nimport click\nimport questionary\n\n\ndef prompt_confirm(question: str, *, default: bool = False) -> bool:\n    \"\"\"Prompt the user for a yes/no answer.\n    Args:\n        question: The question shown to the user.\n        default:  Pre-selected answer (``False`` → *No*).\n\n    Returns:\n        ``True`` for *Yes*, ``False`` for *No*.\n        Falls back to *default* on Ctrl+C.\n    \"\"\"\n    items = [\n        questionary.Choice(\"Yes\", value=True),\n        questionary.Choice(\"No\", value=False),\n    ]\n    preselect = items[0] if default else items[1]\n\n    result = questionary.select(\n        question,\n        choices=items,\n        default=preselect,\n        use_shortcuts=False,\n        use_arrow_keys=True,\n        use_jk_keys=False,\n    ).ask()\n    if result is None:\n        return default\n    return result\n\n\ndef prompt_path(label: str, *, default: str = \"\") -> str:\n    \"\"\"Ask the user for a filesystem path, warning if it doesn't exist.\n\n    Args:\n        label:   Prompt text (e.g. ``\"iMessage database path\"``).\n        default: Pre-filled path value.\n\n    Returns:\n        The resolved absolute path (if it exists) or the raw input\n        (if the user chose to continue anyway).\n    \"\"\"\n    while True:\n        value = click.prompt(label, default=default, type=str)\n        if not value:\n            return value\n        path = Path(value).expanduser()\n        if path.exists():\n            return str(path.resolve())\n        if prompt_confirm(\n            f\"Path '{value}' does not exist, continue anyway?\",\n            default=True,\n        ):\n            return value\n        # Otherwise loop and re-prompt\n\n\ndef prompt_choice(\n    question: str,\n    options: list[str],\n    *,\n    default: Optional[str] = None,\n) -> str:\n    \"\"\"Let the user pick one item from a plain string list.\n\n    Args:\n        question: Prompt text shown above the list.\n        options:  Selectable string values (label == value).\n        default:  Value to pre-select; ``None`` → first item.\n\n    Returns:\n        The selected string.\n        Falls back to *default* (or the first option) on Ctrl+C.\n    \"\"\"\n    items = [questionary.Choice(opt, value=opt) for opt in options]\n\n    preselect = None\n    if default is not None:\n        try:\n            idx = options.index(default)\n            preselect = items[idx]\n        except (ValueError, IndexError):\n            pass\n\n    result = questionary.select(\n        question,\n        choices=items,\n        default=preselect,\n        use_shortcuts=False,\n        use_arrow_keys=True,\n        use_jk_keys=False,\n    ).ask()\n    if result is None:\n        return default or options[0]\n    return result\n\n\ndef prompt_select(\n    question: str,\n    options: list[tuple[str, str]],\n    *,\n    default: Optional[str] = None,\n) -> Optional[str]:\n    \"\"\"Let the user pick one item from a list of (label, value) pairs.\n\n    Unlike :func:`prompt_choice`, the displayed label here can differ from\n    the returned value — useful for showing status icons, etc.\n\n    Args:\n        question: Prompt text shown above the list.\n        options:  ``(label, value)`` pairs; *label* is displayed,\n                  *value* is returned.\n        default:  The *value* to pre-select; ``None`` → no default.\n\n    Returns:\n        The selected *value*, or ``None`` on Ctrl+C.\n    \"\"\"\n    items = [\n        questionary.Choice(label, value=value) for label, value in options\n    ]\n\n    preselect = None\n    if default is not None:\n        for item in items:\n            if item.value == default:\n                preselect = item\n                break\n\n    return questionary.select(\n        question,\n        choices=items,\n        default=preselect,\n        use_shortcuts=False,\n        use_arrow_keys=True,\n        use_jk_keys=False,\n    ).ask()\n\n\ndef prompt_checkbox(\n    question: str,\n    options: list[tuple[str, str]],\n    *,\n    checked: Optional[set[str]] = None,\n    select_all_option: bool = True,\n) -> Optional[list[str]]:\n    \"\"\"Let the user pick multiple items from a list with checkboxes.\n\n    Supports a \"Select All / Deselect All\" toggle at the top of the list.\n    When the user checks \"Select All\" and presses Enter, the list is\n    re-rendered with **all** items checked (or all unchecked if they\n    were already all checked), so the toggle is visually reflected.\n\n    Args:\n        question:  Prompt text shown above the list.\n        options:   ``(label, value)`` pairs; *label* is displayed,\n                   *value* is returned for each selected item.\n        checked:   Set of *values* that should be pre-checked.\n                   ``None`` → nothing checked.\n        select_all_option: Whether to show a \"Select All\" toggle.\n\n    Returns:\n        List of selected *values*, or ``None`` on Ctrl+C.\n    \"\"\"\n    _SELECT_ALL = \"__select_all__\"\n    all_values = {v for _, v in options}\n    current_checked = set(checked or set()) & all_values\n\n    while True:\n        all_currently_checked = (\n            current_checked == all_values and len(all_values) > 0\n        )\n\n        items: list[questionary.Choice] = []\n        if select_all_option:\n            items.append(\n                questionary.Choice(\n                    \"✦ Select All / Deselect All\",\n                    value=_SELECT_ALL,\n                    checked=all_currently_checked,\n                ),\n            )\n\n        for label, value in options:\n            items.append(\n                questionary.Choice(\n                    label,\n                    value=value,\n                    checked=value in current_checked,\n                ),\n            )\n\n        result = questionary.checkbox(\n            question,\n            choices=items,\n            use_jk_keys=False,\n        ).ask()\n\n        if result is None:\n            return None\n\n        # If \"Select All\" is toggled, refresh the list with all\n        # items checked (or unchecked) and let the user confirm.\n        if _SELECT_ALL in result:\n            if all_currently_checked:\n                # Was all-selected → deselect all\n                current_checked = set()\n            else:\n                # Not all selected → select all\n                current_checked = set(all_values)\n            continue  # re-render the checkbox\n\n        # Normal submit without \"Select All\" → return selection\n        return [r for r in result if r != _SELECT_ALL]\n"
  },
  {
    "path": "src/copaw/config/__init__.py",
    "content": "# -*- coding: utf-8 -*-\nfrom .config import (\n    Config,\n    ChannelConfig,\n    ChannelConfigUnion,\n    AgentsRunningConfig,\n    HeartbeatConfig,\n    SecurityConfig,\n    ToolGuardConfig,\n    ToolGuardRuleConfig,\n)\nfrom .utils import (\n    get_available_channels,\n    get_config_path,\n    get_heartbeat_config,\n    get_heartbeat_query_path,\n    get_playwright_chromium_executable_path,\n    get_system_default_browser,\n    is_running_in_container,\n    load_config,\n    save_config,\n    update_last_dispatch,\n)\n\n__all__ = [\n    \"AgentsRunningConfig\",\n    \"Config\",\n    \"ChannelConfig\",\n    \"ChannelConfigUnion\",\n    \"HeartbeatConfig\",\n    \"SecurityConfig\",\n    \"ToolGuardConfig\",\n    \"ToolGuardRuleConfig\",\n    \"get_available_channels\",\n    \"get_config_path\",\n    \"get_heartbeat_config\",\n    \"get_heartbeat_query_path\",\n    \"get_playwright_chromium_executable_path\",\n    \"get_system_default_browser\",\n    \"is_running_in_container\",\n    \"load_config\",\n    \"save_config\",\n    \"update_last_dispatch\",\n]\n"
  },
  {
    "path": "src/copaw/config/config.py",
    "content": "# -*- coding: utf-8 -*-\nimport os\nimport json\nfrom pathlib import Path\nfrom typing import Optional, Union, Dict, List, Literal\n\nfrom pydantic import BaseModel, Field, ConfigDict, model_validator\nimport shortuuid\n\nfrom .timezone import detect_system_timezone\nfrom ..constant import (\n    HEARTBEAT_DEFAULT_EVERY,\n    HEARTBEAT_DEFAULT_TARGET,\n    WORKING_DIR,\n)\nfrom ..providers.models import ModelSlotConfig\n\n\ndef generate_short_agent_id() -> str:\n    \"\"\"Generate a 6-character short UUID for agent identification.\n\n    Returns:\n        6-character short UUID string\n    \"\"\"\n    return shortuuid.ShortUUID().random(length=6)\n\n\nclass BaseChannelConfig(BaseModel):\n    \"\"\"Base for channel config (read from config.json, no env).\"\"\"\n\n    enabled: bool = False\n    bot_prefix: str = \"\"\n    filter_tool_messages: bool = False\n    filter_thinking: bool = False\n    dm_policy: Literal[\"open\", \"allowlist\"] = \"open\"\n    group_policy: Literal[\"open\", \"allowlist\"] = \"open\"\n    allow_from: List[str] = Field(default_factory=list)\n    deny_message: str = \"\"\n    require_mention: bool = False\n\n\nclass IMessageChannelConfig(BaseChannelConfig):\n    db_path: str = \"~/Library/Messages/chat.db\"\n    poll_sec: float = 1.0\n    media_dir: Optional[str] = None\n    max_decoded_size: int = (\n        10 * 1024 * 1024\n    )  # 10MB default limit for Base64 data\n\n\nclass DiscordConfig(BaseChannelConfig):\n    bot_token: str = \"\"\n    http_proxy: str = \"\"\n    http_proxy_auth: str = \"\"\n\n\nclass DingTalkConfig(BaseChannelConfig):\n    client_id: str = \"\"\n    client_secret: str = \"\"\n    message_type: str = \"markdown\"\n    card_template_id: str = \"\"\n    card_template_key: str = \"content\"\n    robot_code: str = \"\"\n    media_dir: Optional[str] = None\n\n\nclass FeishuConfig(BaseChannelConfig):\n    \"\"\"Feishu/Lark channel: app_id, app_secret; optional encrypt_key,\n    verification_token for event handler. media_dir for received media.\n    \"\"\"\n\n    app_id: str = \"\"\n    app_secret: str = \"\"\n    encrypt_key: str = \"\"\n    verification_token: str = \"\"\n    media_dir: Optional[str] = None\n\n\nclass QQConfig(BaseChannelConfig):\n    app_id: str = \"\"\n    client_secret: str = \"\"\n    markdown_enabled: bool = True\n\n\nclass TelegramConfig(BaseChannelConfig):\n    bot_token: str = \"\"\n    http_proxy: str = \"\"\n    http_proxy_auth: str = \"\"\n    show_typing: Optional[bool] = None\n\n\nclass MQTTConfig(BaseChannelConfig):\n    host: str = \"\"\n    port: Optional[int] = None\n    transport: str = \"\"\n    clean_session: bool = True\n    qos: int = 2\n    username: Optional[str] = None\n    password: Optional[str] = None\n    subscribe_topic: str = \"\"\n    publish_topic: str = \"\"\n    tls_enabled: bool = False\n    tls_ca_certs: Optional[str] = None\n    tls_certfile: Optional[str] = None\n    tls_keyfile: Optional[str] = None\n\n\nclass MattermostConfig(BaseChannelConfig):\n    \"\"\"Mattermost channel: WebSocket polling and REST API.\"\"\"\n\n    url: str = \"\"\n    bot_token: str = \"\"\n    media_dir: Optional[str] = None\n    show_typing: Optional[bool] = None\n    thread_follow_without_mention: bool = False\n\n\nclass ConsoleConfig(BaseChannelConfig):\n    \"\"\"Console channel: prints agent responses to stdout.\"\"\"\n\n    enabled: bool = True\n    media_dir: Optional[str] = None\n\n\nclass WecomConfig(BaseChannelConfig):\n    \"\"\"WeCom (Enterprise WeChat) AI Bot channel config.\"\"\"\n\n    bot_id: str = \"\"\n    secret: str = \"\"\n    media_dir: Optional[str] = None\n    welcome_text: str = \"\"\n    max_reconnect_attempts: int = -1\n\n\nclass MatrixConfig(BaseChannelConfig):\n    \"\"\"Matrix channel configuration.\"\"\"\n\n    homeserver: str = \"\"\n    user_id: str = \"\"\n    access_token: str = \"\"\n\n\nclass VoiceChannelConfig(BaseChannelConfig):\n    \"\"\"Voice channel: Twilio ConversationRelay + Cloudflare Tunnel.\"\"\"\n\n    twilio_account_sid: str = \"\"\n    twilio_auth_token: str = \"\"\n    phone_number: str = \"\"\n    phone_number_sid: str = \"\"\n    tts_provider: str = \"google\"\n    tts_voice: str = \"en-US-Journey-D\"\n    stt_provider: str = \"deepgram\"\n    language: str = \"en-US\"\n    welcome_greeting: str = \"Hi! This is CoPaw. How can I help you?\"\n\n\nclass XiaoYiConfig(BaseChannelConfig):\n    \"\"\"XiaoYi channel: Huawei A2A protocol via WebSocket.\"\"\"\n\n    ak: str = \"\"  # Access Key\n    sk: str = \"\"  # Secret Key\n    agent_id: str = \"\"  # Agent ID from XiaoYi platform\n    ws_url: str = \"wss://hag.cloud.huawei.com/openclaw/v1/ws/link\"\n    task_timeout_ms: int = 3600000  # 1 hour task timeout\n\n\nclass ChannelConfig(BaseModel):\n    \"\"\"Built-in channel configs; extra keys allowed for plugin channels.\"\"\"\n\n    model_config = ConfigDict(extra=\"allow\")\n\n    imessage: IMessageChannelConfig = IMessageChannelConfig()\n    discord: DiscordConfig = DiscordConfig()\n    dingtalk: DingTalkConfig = DingTalkConfig()\n    feishu: FeishuConfig = FeishuConfig()\n    qq: QQConfig = QQConfig()\n    telegram: TelegramConfig = TelegramConfig()\n    mattermost: MattermostConfig = MattermostConfig()\n    mqtt: MQTTConfig = MQTTConfig()\n    console: ConsoleConfig = ConsoleConfig()\n    matrix: MatrixConfig = MatrixConfig()\n    voice: VoiceChannelConfig = VoiceChannelConfig()\n    wecom: WecomConfig = WecomConfig()\n    xiaoyi: XiaoYiConfig = XiaoYiConfig()\n\n\nclass LastApiConfig(BaseModel):\n    host: Optional[str] = None\n    port: Optional[int] = None\n\n\nclass ActiveHoursConfig(BaseModel):\n    \"\"\"Optional active window for heartbeat (e.g. 08:00–22:00).\"\"\"\n\n    start: str = \"08:00\"\n    end: str = \"22:00\"\n\n\nclass HeartbeatConfig(BaseModel):\n    \"\"\"Heartbeat: run agent with HEARTBEAT.md as query at interval.\"\"\"\n\n    model_config = {\"populate_by_name\": True}\n\n    enabled: bool = Field(default=False, description=\"Whether heartbeat is on\")\n    every: str = Field(default=HEARTBEAT_DEFAULT_EVERY)\n    target: str = Field(default=HEARTBEAT_DEFAULT_TARGET)\n    active_hours: Optional[ActiveHoursConfig] = Field(\n        default=None,\n        alias=\"activeHours\",\n    )\n\n\nclass AgentsDefaultsConfig(BaseModel):\n    heartbeat: Optional[HeartbeatConfig] = None\n\n\nclass EmbeddingConfig(BaseModel):\n    \"\"\"Embedding model configuration.\"\"\"\n\n    model_config = ConfigDict(extra=\"allow\")\n\n    backend: str = Field(\n        default=\"openai\",\n        description=\"Embedding backend (openai, etc.)\",\n    )\n    api_key: str = Field(\n        default=\"\",\n        description=\"API key for embedding provider\",\n    )\n    base_url: str = Field(default=\"\", description=\"Base URL for embedding API\")\n    model_name: str = Field(default=\"\", description=\"Embedding model name\")\n    dimensions: int = Field(default=1024, description=\"Embedding dimensions\")\n    enable_cache: bool = Field(\n        default=True,\n        description=\"Whether to enable embedding cache\",\n    )\n    use_dimensions: bool = Field(\n        default=False,\n        description=\"Whether to use custom dimensions\",\n    )\n    max_cache_size: int = Field(default=2000, description=\"Maximum cache size\")\n    max_input_length: int = Field(\n        default=8192,\n        description=\"Maximum input length for embedding\",\n    )\n    max_batch_size: int = Field(\n        default=10,\n        description=\"Maximum batch size for embedding\",\n    )\n\n\nclass AgentsRunningConfig(BaseModel):\n    \"\"\"Agent runtime behavior configuration.\"\"\"\n\n    model_config = ConfigDict(extra=\"allow\")\n\n    max_iters: int = Field(\n        default=50,\n        ge=1,\n        description=(\n            \"Maximum number of reasoning-acting iterations for ReAct agent\"\n        ),\n    )\n\n    token_count_model: str = Field(\n        default=\"default\",\n        description=\"Model to use for token counting\",\n    )\n\n    token_count_estimate_divisor: float = Field(\n        default=3.75,\n        gt=1,\n        description=(\n            \"Divisor for character-based token estimation \" \"(len / divisor)\"\n        ),\n    )\n\n    token_count_use_mirror: bool = Field(\n        default=False,\n        description=\"Whether to use mirror token counting\",\n    )\n\n    max_input_length: int = Field(\n        default=128 * 1024,  # 128K = 131072 tokens\n        ge=1000,\n        description=(\n            \"Maximum input length (tokens) for the model context window\"\n        ),\n    )\n\n    memory_compact_ratio: float = Field(\n        default=0.75,\n        ge=0.3,\n        le=0.9,\n        description=\"Ratio of memory to compact when memory is full\",\n    )\n\n    memory_reserve_ratio: float = Field(\n        default=0.1,\n        ge=0.05,\n        le=0.3,\n        description=\"Ratio of memory to reserve when compact memory\",\n    )\n\n    tool_result_compact_recent_n: int = Field(\n        default=2,\n        ge=1,\n        le=10,\n        description=\"Number of recent messages to use recent_threshold for\",\n    )\n\n    tool_result_compact_old_threshold: int = Field(\n        default=1000,\n        ge=100,\n        description=\"Character threshold for old messages \"\n        \"in tool result compaction\",\n    )\n\n    tool_result_compact_recent_threshold: int = Field(\n        default=30000,\n        ge=1000,\n        description=\"Character threshold for recent messages \"\n        \"in tool result compaction\",\n    )\n\n    tool_result_compact_retention_days: int = Field(\n        default=7,\n        ge=1,\n        le=30,\n        description=\"Number of days to retain tool result files\",\n    )\n\n    history_max_length: int = Field(\n        default=10000,\n        ge=1000,\n        description=\"Maximum length for /history command output\",\n    )\n\n    embedding_config: EmbeddingConfig = Field(\n        default_factory=EmbeddingConfig,\n        description=\"Embedding model configuration\",\n    )\n\n    @property\n    def memory_compact_reserve(self) -> int:\n        \"\"\"Memory compact reserve size (tokens).\"\"\"\n        return int(self.max_input_length * self.memory_reserve_ratio)\n\n    @property\n    def memory_compact_threshold(self) -> int:\n        \"\"\"Memory compact threshold size (tokens).\"\"\"\n        return int(self.max_input_length * self.memory_compact_ratio)\n\n\nclass AgentsLLMRoutingConfig(BaseModel):\n    model_config = ConfigDict(extra=\"ignore\")\n\n    enabled: bool = Field(default=False)\n    mode: Literal[\"local_first\", \"cloud_first\"] = Field(\n        default=\"local_first\",\n        description=(\n            \"local_first routes to the local slot by default; cloud_first \"\n            \"routes to the cloud slot by default. Smarter switching can be \"\n            \"added later without changing the dual-slot config shape.\"\n        ),\n    )\n    local: ModelSlotConfig = Field(\n        default_factory=ModelSlotConfig,\n        description=\"Local model slot (required when routing is enabled).\",\n    )\n    cloud: Optional[ModelSlotConfig] = Field(\n        default=None,\n        description=(\n            \"Optional explicit cloud model slot; when null, uses \"\n            \"providers.json active_llm.\"\n        ),\n    )\n\n\nclass AgentProfileRef(BaseModel):\n    \"\"\"Agent Profile reference (stored in root config.json).\n\n    Only contains ID and workspace directory reference.\n    Full agent configuration is stored in workspace/agent.json.\n    \"\"\"\n\n    id: str = Field(..., description=\"Unique agent ID\")\n    workspace_dir: str = Field(\n        ...,\n        description=\"Path to agent's workspace directory\",\n    )\n\n\nclass AgentProfileConfig(BaseModel):\n    \"\"\"Complete Agent Profile configuration (stored in workspace/agent.json).\n\n    Each agent has its own configuration file with all settings.\n    \"\"\"\n\n    id: str = Field(..., description=\"Unique agent ID\")\n    name: str = Field(..., description=\"Human-readable agent name\")\n    description: str = Field(default=\"\", description=\"Agent description\")\n    workspace_dir: str = Field(\n        default=\"\",\n        description=\"Path to agent's workspace (optional, for reference)\",\n    )\n\n    # Agent-specific configurations\n    channels: Optional[\"ChannelConfig\"] = Field(\n        default=None,\n        description=\"Channel configurations for this agent\",\n    )\n    mcp: Optional[\"MCPConfig\"] = Field(\n        default=None,\n        description=\"MCP clients for this agent\",\n    )\n    heartbeat: Optional[HeartbeatConfig] = Field(\n        default=None,\n        description=\"Heartbeat configuration for this agent\",\n    )\n    last_dispatch: Optional[\"LastDispatchConfig\"] = Field(\n        default=None,\n        description=\"Last dispatch target for this agent\",\n    )\n    running: AgentsRunningConfig = Field(\n        default_factory=AgentsRunningConfig,\n        description=\"Runtime configuration\",\n    )\n    llm_routing: AgentsLLMRoutingConfig = Field(\n        default_factory=AgentsLLMRoutingConfig,\n        description=\"LLM routing settings\",\n    )\n    active_model: Optional[\"ModelSlotConfig\"] = Field(\n        default=None,\n        description=\"Active model for this agent (provider_id + model)\",\n    )\n    language: str = Field(\n        default=\"zh\",\n        description=\"Language setting for this agent\",\n    )\n    system_prompt_files: List[str] = Field(\n        default_factory=lambda: [\"AGENTS.md\", \"SOUL.md\", \"PROFILE.md\"],\n        description=\"System prompt markdown files\",\n    )\n    tools: Optional[\"ToolsConfig\"] = Field(\n        default=None,\n        description=\"Tools configuration for this agent\",\n    )\n    security: Optional[\"SecurityConfig\"] = Field(\n        default=None,\n        description=\"Security configuration for this agent\",\n    )\n\n\nclass AgentsConfig(BaseModel):\n    \"\"\"Agents configuration (root config.json only contains references).\"\"\"\n\n    active_agent: str = Field(\n        default=\"default\",\n        description=\"Currently active agent ID\",\n    )\n    profiles: Dict[str, AgentProfileRef] = Field(\n        default_factory=lambda: {\n            \"default\": AgentProfileRef(\n                id=\"default\",\n                workspace_dir=f\"{WORKING_DIR}/workspaces/default\",\n            ),\n        },\n        description=\"Agent profile references (ID and workspace path only)\",\n    )\n\n    # Legacy fields for backward compatibility (deprecated)\n    # These fields MUST have default values (not None) to support downgrade\n    defaults: Optional[AgentsDefaultsConfig] = None\n    running: AgentsRunningConfig = Field(\n        default_factory=AgentsRunningConfig,\n    )\n    llm_routing: AgentsLLMRoutingConfig = Field(\n        default_factory=AgentsLLMRoutingConfig,\n    )\n    language: str = Field(default=\"zh\")\n    installed_md_files_language: Optional[str] = None\n    system_prompt_files: List[str] = Field(\n        default_factory=lambda: [\"AGENTS.md\", \"SOUL.md\", \"PROFILE.md\"],\n    )\n    audio_mode: Literal[\"auto\", \"native\"] = Field(\n        default=\"auto\",\n        description=(\n            \"How to handle incoming audio/voice messages. \"\n            '\"auto\": transcribe if a provider is available, otherwise show '\n            \"file-uploaded placeholder; \"\n            '\"native\": send audio blocks directly to the model '\n            \"(may need ffmpeg).\"\n        ),\n    )\n\n    transcription_provider_type: Literal[\n        \"disabled\",\n        \"whisper_api\",\n        \"local_whisper\",\n    ] = Field(\n        default=\"disabled\",\n        description=(\n            \"Transcription backend. \"\n            '\"disabled\": no transcription; '\n            '\"whisper_api\": remote OpenAI-compatible endpoint; '\n            '\"local_whisper\": locally installed openai-whisper.'\n        ),\n    )\n    transcription_provider_id: str = Field(\n        default=\"\",\n        description=(\n            \"Provider ID for Whisper API transcription. \"\n            \"Empty = no provider selected. \"\n            'Only used when transcription_provider_type is \"whisper_api\".'\n        ),\n    )\n    transcription_model: str = Field(\n        default=\"whisper-1\",\n        description=(\n            \"Model name for Whisper API transcription. \"\n            'e.g. \"whisper-1\", \"whisper-large-v3\".'\n        ),\n    )\n\n\nclass LastDispatchConfig(BaseModel):\n    \"\"\"Last channel/user/session that received a user-originated reply.\"\"\"\n\n    channel: str = \"\"\n    user_id: str = \"\"\n    session_id: str = \"\"\n\n\nclass MCPClientConfig(BaseModel):\n    \"\"\"Configuration for a single MCP client.\"\"\"\n\n    model_config = ConfigDict(populate_by_name=True)\n\n    name: str\n    description: str = \"\"\n    enabled: bool = True\n    transport: Literal[\"stdio\", \"streamable_http\", \"sse\"] = \"stdio\"\n    url: str = \"\"\n    headers: Dict[str, str] = Field(default_factory=dict)\n    command: str = \"\"\n    args: List[str] = Field(default_factory=list)\n    env: Dict[str, str] = Field(default_factory=dict)\n    cwd: str = \"\"\n\n    @model_validator(mode=\"before\")\n    @classmethod\n    def _normalize_legacy_fields(cls, data):\n        \"\"\"Normalize common MCP field aliases from third-party examples.\"\"\"\n        if not isinstance(data, dict):\n            return data\n\n        payload = dict(data)\n\n        if \"isActive\" in payload and \"enabled\" not in payload:\n            payload[\"enabled\"] = payload[\"isActive\"]\n\n        if \"baseUrl\" in payload and \"url\" not in payload:\n            payload[\"url\"] = payload[\"baseUrl\"]\n\n        if \"type\" in payload and \"transport\" not in payload:\n            payload[\"transport\"] = payload[\"type\"]\n\n        if (\n            \"transport\" not in payload\n            and (payload.get(\"url\") or payload.get(\"baseUrl\"))\n            and not payload.get(\"command\")\n        ):\n            payload[\"transport\"] = \"streamable_http\"\n\n        raw_transport = payload.get(\"transport\")\n        if isinstance(raw_transport, str):\n            normalized = raw_transport.strip().lower()\n            transport_alias_map = {\n                \"streamablehttp\": \"streamable_http\",\n                \"http\": \"streamable_http\",\n                \"stdio\": \"stdio\",\n                \"sse\": \"sse\",\n            }\n            payload[\"transport\"] = transport_alias_map.get(\n                normalized,\n                normalized,\n            )\n\n        return payload\n\n    @model_validator(mode=\"after\")\n    def _validate_transport_config(self):\n        \"\"\"Validate required fields for each MCP transport type.\"\"\"\n        if self.transport == \"stdio\":\n            if not self.command.strip():\n                raise ValueError(\"stdio MCP client requires non-empty command\")\n            return self\n\n        if not self.url.strip():\n            raise ValueError(\n                f\"{self.transport} MCP client requires non-empty url\",\n            )\n        return self\n\n\nclass MCPConfig(BaseModel):\n    \"\"\"MCP clients configuration.\n\n    Uses a dict to allow dynamic client definitions.\n    Default tavily_search client is created and auto-enabled if API key exists.\n    \"\"\"\n\n    clients: Dict[str, MCPClientConfig] = Field(\n        default_factory=lambda: {\n            \"tavily_search\": MCPClientConfig(\n                name=\"tavily_mcp\",\n                # Auto-enable if TAVILY_API_KEY exists in environment\n                enabled=bool(os.getenv(\"TAVILY_API_KEY\")),\n                command=\"npx\",\n                args=[\"-y\", \"tavily-mcp@latest\"],\n                env={\"TAVILY_API_KEY\": os.getenv(\"TAVILY_API_KEY\", \"\")},\n            ),\n        },\n    )\n\n\nclass BuiltinToolConfig(BaseModel):\n    \"\"\"Configuration for a single built-in tool.\"\"\"\n\n    name: str = Field(..., description=\"Tool function name\")\n    enabled: bool = Field(True, description=\"Whether the tool is enabled\")\n    description: str = Field(default=\"\", description=\"Tool description\")\n    display_to_user: bool = Field(\n        True,\n        description=\"Whether tool output is rendered to user channels\",\n    )\n\n\ndef _default_builtin_tools() -> Dict[str, BuiltinToolConfig]:\n    \"\"\"Return a fresh copy of the canonical built-in tool definitions.\"\"\"\n    return {\n        \"execute_shell_command\": BuiltinToolConfig(\n            name=\"execute_shell_command\",\n            enabled=True,\n            description=\"Execute shell commands\",\n        ),\n        \"read_file\": BuiltinToolConfig(\n            name=\"read_file\",\n            enabled=True,\n            description=\"Read file contents\",\n        ),\n        \"write_file\": BuiltinToolConfig(\n            name=\"write_file\",\n            enabled=True,\n            description=\"Write content to file\",\n        ),\n        \"edit_file\": BuiltinToolConfig(\n            name=\"edit_file\",\n            enabled=True,\n            description=\"Edit file using find-and-replace\",\n        ),\n        \"grep_search\": BuiltinToolConfig(\n            name=\"grep_search\",\n            enabled=True,\n            description=\"Search file contents by pattern\",\n        ),\n        \"glob_search\": BuiltinToolConfig(\n            name=\"glob_search\",\n            enabled=True,\n            description=\"Find files matching a glob pattern\",\n        ),\n        \"browser_use\": BuiltinToolConfig(\n            name=\"browser_use\",\n            enabled=True,\n            description=\"Browser automation and web interaction\",\n        ),\n        \"desktop_screenshot\": BuiltinToolConfig(\n            name=\"desktop_screenshot\",\n            enabled=True,\n            description=\"Capture desktop screenshots\",\n        ),\n        \"view_image\": BuiltinToolConfig(\n            name=\"view_image\",\n            enabled=True,\n            description=\"Load an image into LLM context \"\n            \"for visual analysis\",\n            display_to_user=False,\n        ),\n        \"send_file_to_user\": BuiltinToolConfig(\n            name=\"send_file_to_user\",\n            enabled=True,\n            description=\"Send files to user\",\n        ),\n        \"get_current_time\": BuiltinToolConfig(\n            name=\"get_current_time\",\n            enabled=True,\n            description=\"Get current date and time\",\n        ),\n        \"set_user_timezone\": BuiltinToolConfig(\n            name=\"set_user_timezone\",\n            enabled=True,\n            description=\"Set user timezone\",\n        ),\n        \"get_token_usage\": BuiltinToolConfig(\n            name=\"get_token_usage\",\n            enabled=True,\n            description=\"Get llm token usage\",\n        ),\n    }\n\n\nclass ToolsConfig(BaseModel):\n    \"\"\"Built-in tools management configuration.\"\"\"\n\n    builtin_tools: Dict[str, BuiltinToolConfig] = Field(\n        default_factory=_default_builtin_tools,\n    )\n\n    @model_validator(mode=\"after\")\n    def _merge_default_tools(self):\n        \"\"\"Ensure new code-defined tools are present in saved configs.\"\"\"\n        for name, tc in _default_builtin_tools().items():\n            if name not in self.builtin_tools:\n                self.builtin_tools[name] = tc\n        return self\n\n\nclass ToolGuardRuleConfig(BaseModel):\n    \"\"\"A single user-defined guard rule (stored in config.json).\"\"\"\n\n    id: str\n    tools: List[str] = Field(default_factory=list)\n    params: List[str] = Field(default_factory=list)\n    category: str = \"command_injection\"\n    severity: str = \"HIGH\"\n    patterns: List[str] = Field(default_factory=list)\n    exclude_patterns: List[str] = Field(default_factory=list)\n    description: str = \"\"\n    remediation: str = \"\"\n\n\nclass ToolGuardConfig(BaseModel):\n    \"\"\"Tool guard settings under ``security.tool_guard``.\n\n    ``guarded_tools``: ``None`` → use built-in default set; empty list → guard\n    nothing; non-empty list → guard only those tools.\n    \"\"\"\n\n    enabled: bool = True\n    guarded_tools: Optional[List[str]] = None\n    denied_tools: List[str] = Field(default_factory=list)\n    custom_rules: List[ToolGuardRuleConfig] = Field(default_factory=list)\n    disabled_rules: List[str] = Field(default_factory=list)\n\n\nclass SkillScannerWhitelistEntry(BaseModel):\n    \"\"\"A whitelisted skill (identified by name + content hash).\"\"\"\n\n    skill_name: str\n    content_hash: str = Field(\n        default=\"\",\n        description=\"SHA-256 of concatenated file contents at whitelist time. \"\n        \"Empty string means any content is allowed.\",\n    )\n    added_at: str = Field(\n        default=\"\",\n        description=\"ISO 8601 timestamp when the entry was added.\",\n    )\n\n\nclass SkillScannerConfig(BaseModel):\n    \"\"\"Skill scanner settings under ``security.skill_scanner``.\n\n    ``mode`` controls the scanner behavior:\n    * ``\"block\"`` – scan and block unsafe skills.\n    * ``\"warn\"``  – scan but only log warnings, do not block (default).\n    * ``\"off\"``   – disable scanning entirely.\n    \"\"\"\n\n    mode: Literal[\"block\", \"warn\", \"off\"] = Field(\n        default=\"warn\",\n        description=\"Scanner mode: block, warn, or off.\",\n    )\n    timeout: int = Field(\n        default=30,\n        ge=5,\n        le=300,\n        description=\"Max seconds to wait for a scan to complete.\",\n    )\n    whitelist: List[SkillScannerWhitelistEntry] = Field(\n        default_factory=list,\n        description=\"Skills that bypass security scanning.\",\n    )\n\n\nclass SecurityConfig(BaseModel):\n    \"\"\"Top-level ``security`` section in config.json.\"\"\"\n\n    tool_guard: ToolGuardConfig = Field(default_factory=ToolGuardConfig)\n    skill_scanner: SkillScannerConfig = Field(\n        default_factory=SkillScannerConfig,\n    )\n\n\nclass Config(BaseModel):\n    \"\"\"Root config (config.json).\"\"\"\n\n    channels: ChannelConfig = ChannelConfig()\n    mcp: MCPConfig = MCPConfig()\n    tools: ToolsConfig = Field(default_factory=ToolsConfig)\n    last_api: LastApiConfig = LastApiConfig()\n    agents: AgentsConfig = Field(default_factory=AgentsConfig)\n    last_dispatch: Optional[LastDispatchConfig] = None\n    security: SecurityConfig = Field(default_factory=SecurityConfig)\n    show_tool_details: bool = True\n    user_timezone: str = Field(\n        default_factory=detect_system_timezone,\n        description=\"User IANA timezone (e.g. Asia/Shanghai). \"\n        \"Defaults to the system timezone.\",\n    )\n\n\nChannelConfigUnion = Union[\n    IMessageChannelConfig,\n    DiscordConfig,\n    DingTalkConfig,\n    FeishuConfig,\n    QQConfig,\n    TelegramConfig,\n    MattermostConfig,\n    MQTTConfig,\n    ConsoleConfig,\n    MatrixConfig,\n    VoiceChannelConfig,\n    WecomConfig,\n    XiaoYiConfig,\n]\n\n\n# Agent configuration utility functions\n\n\ndef load_agent_config(agent_id: str) -> AgentProfileConfig:\n    \"\"\"Load agent's complete configuration from workspace/agent.json.\n\n    Args:\n        agent_id: Agent ID to load\n\n    Returns:\n        AgentProfileConfig: Complete agent configuration\n\n    Raises:\n        ValueError: If agent ID not found in root config\n    \"\"\"\n    from .utils import load_config\n\n    config = load_config()\n\n    if agent_id not in config.agents.profiles:\n        raise ValueError(f\"Agent '{agent_id}' not found in config\")\n\n    agent_ref = config.agents.profiles[agent_id]\n    workspace_dir = Path(agent_ref.workspace_dir).expanduser()\n    agent_config_path = workspace_dir / \"agent.json\"\n\n    if not agent_config_path.exists():\n        # Fallback: Try to use root config fields for backward compatibility\n        # This allows downgrade scenarios where agent.json doesn't exist yet\n        fallback_config = AgentProfileConfig(\n            id=agent_id,\n            name=agent_id.title(),\n            description=f\"{agent_id} agent\",\n            workspace_dir=str(workspace_dir),\n            # Inherit from root config if available (for backward compat)\n            channels=(\n                config.channels\n                if hasattr(config, \"channels\") and config.channels\n                else None\n            ),\n            mcp=config.mcp if hasattr(config, \"mcp\") and config.mcp else None,\n            tools=(\n                config.tools\n                if hasattr(config, \"tools\") and config.tools\n                else None\n            ),\n            security=(\n                config.security\n                if hasattr(config, \"security\") and config.security\n                else None\n            ),\n            # Use agent-specific configs with proper defaults\n            running=(\n                config.agents.running\n                if hasattr(config.agents, \"running\") and config.agents.running\n                else AgentsRunningConfig()\n            ),\n            llm_routing=(\n                config.agents.llm_routing\n                if hasattr(config.agents, \"llm_routing\")\n                and config.agents.llm_routing\n                else AgentsLLMRoutingConfig()\n            ),\n            system_prompt_files=(\n                config.agents.system_prompt_files\n                if hasattr(config.agents, \"system_prompt_files\")\n                and config.agents.system_prompt_files\n                else [\"AGENTS.md\", \"SOUL.md\", \"PROFILE.md\"]\n            ),\n        )\n        # Save for future use\n        save_agent_config(agent_id, fallback_config)\n        return fallback_config\n\n    with open(agent_config_path, \"r\", encoding=\"utf-8\") as f:\n        data = json.load(f)\n\n    # Normalize legacy ~/.copaw-bound paths to current WORKING_DIR.\n    # This keeps COPAW_WORKING_DIR effective even if existing agent.json\n    # contains older hard-coded paths like \"~/.copaw/media\".\n    try:\n        from .utils import _normalize_working_dir_bound_paths\n\n        data = _normalize_working_dir_bound_paths(data)\n    except Exception:\n        pass\n\n    return AgentProfileConfig(**data)\n\n\ndef save_agent_config(\n    agent_id: str,\n    agent_config: AgentProfileConfig,\n) -> None:\n    \"\"\"Save agent configuration to workspace/agent.json.\n\n    Args:\n        agent_id: Agent ID\n        agent_config: Complete agent configuration to save\n\n    Raises:\n        ValueError: If agent ID not found in root config\n    \"\"\"\n    from .utils import load_config\n\n    config = load_config()\n\n    if agent_id not in config.agents.profiles:\n        raise ValueError(f\"Agent '{agent_id}' not found in config\")\n\n    agent_ref = config.agents.profiles[agent_id]\n    workspace_dir = Path(agent_ref.workspace_dir).expanduser()\n    workspace_dir.mkdir(parents=True, exist_ok=True)\n\n    agent_config_path = workspace_dir / \"agent.json\"\n\n    with open(agent_config_path, \"w\", encoding=\"utf-8\") as f:\n        json.dump(\n            agent_config.model_dump(exclude_none=True),\n            f,\n            ensure_ascii=False,\n            indent=2,\n        )\n\n\ndef migrate_legacy_config_to_multi_agent() -> bool:\n    \"\"\"Migrate legacy single-agent config to new multi-agent structure.\n\n    Returns:\n        bool: True if migration was performed, False if already migrated\n    \"\"\"\n    from .utils import load_config, save_config\n\n    config = load_config()\n\n    # Check if already migrated (new structure has only AgentProfileRef)\n    if \"default\" in config.agents.profiles:\n        agent_ref = config.agents.profiles[\"default\"]\n        # If it's already a AgentProfileRef, migration done\n        if isinstance(agent_ref, AgentProfileRef):\n            # Check if default agent config exists\n            workspace_dir = Path(agent_ref.workspace_dir).expanduser()\n            agent_config_path = workspace_dir / \"agent.json\"\n            if agent_config_path.exists():\n                return False  # Already migrated\n\n    # Perform migration\n    print(\"Migrating legacy config to multi-agent structure...\")\n\n    # Extract legacy agent configuration\n    legacy_agents = config.agents\n\n    # Create default agent workspace\n    default_workspace = Path(f\"{WORKING_DIR}/workspaces/default\").expanduser()\n    default_workspace.mkdir(parents=True, exist_ok=True)\n\n    # Create default agent configuration from legacy settings\n    default_agent_config = AgentProfileConfig(\n        id=\"default\",\n        name=\"Default Agent\",\n        description=\"Default CoPaw agent\",\n        workspace_dir=str(default_workspace),\n        channels=config.channels if config.channels else None,\n        mcp=config.mcp if config.mcp else None,\n        heartbeat=(\n            legacy_agents.defaults.heartbeat\n            if legacy_agents.defaults\n            else None\n        ),\n        running=(\n            legacy_agents.running\n            if legacy_agents.running\n            else AgentsRunningConfig()\n        ),\n        llm_routing=(\n            legacy_agents.llm_routing\n            if legacy_agents.llm_routing\n            else AgentsLLMRoutingConfig()\n        ),\n        system_prompt_files=(\n            legacy_agents.system_prompt_files\n            if legacy_agents.system_prompt_files\n            else [\"AGENTS.md\", \"SOUL.md\", \"PROFILE.md\"]\n        ),\n        tools=config.tools if config.tools else None,\n        security=config.security if config.security else None,\n    )\n\n    # Save default agent configuration to workspace\n    agent_config_path = default_workspace / \"agent.json\"\n    with open(agent_config_path, \"w\", encoding=\"utf-8\") as f:\n        json.dump(\n            default_agent_config.model_dump(exclude_none=True),\n            f,\n            ensure_ascii=False,\n            indent=2,\n        )\n\n    # Migrate existing workspace files from legacy default working dir.\n    # When COPAW_WORKING_DIR is customized, historical data may still exist\n    # under \"~/.copaw\".\n    old_workspace = Path(\"~/.copaw\").expanduser().resolve()\n\n    # Move sessions, memory, and other workspace files\n    for item_name in [\"sessions\", \"memory\", \"jobs.json\"]:\n        old_path = old_workspace / item_name\n        if old_path.exists():\n            new_path = default_workspace / item_name\n            if not new_path.exists():\n                import shutil\n\n                if old_path.is_dir():\n                    shutil.copytree(old_path, new_path)\n                else:\n                    shutil.copy2(old_path, new_path)\n                print(f\"  Migrated {item_name} to default workspace\")\n\n    # Copy markdown files (AGENTS.md, SOUL.md, PROFILE.md)\n    for md_file in [\"AGENTS.md\", \"SOUL.md\", \"PROFILE.md\"]:\n        old_md = old_workspace / md_file\n        if old_md.exists():\n            new_md = default_workspace / md_file\n            if not new_md.exists():\n                import shutil\n\n                shutil.copy2(old_md, new_md)\n                print(f\"  Migrated {md_file} to default workspace\")\n\n    # Update root config.json to new structure\n    # CRITICAL: Preserve legacy agent fields for downgrade compatibility\n    config.agents = AgentsConfig(\n        active_agent=\"default\",\n        profiles={\n            \"default\": AgentProfileRef(\n                id=\"default\",\n                workspace_dir=str(default_workspace),\n            ),\n        },\n        # Preserve legacy fields with values from migrated agent config\n        running=default_agent_config.running,\n        llm_routing=default_agent_config.llm_routing,\n        language=(\n            default_agent_config.language\n            if hasattr(default_agent_config, \"language\")\n            else \"zh\"\n        ),\n        system_prompt_files=default_agent_config.system_prompt_files,\n    )\n\n    # IMPORTANT: Keep channels, mcp, tools, security in root config for\n    # backward compatibility. Do NOT clear these fields.\n    # Old versions expect these fields to exist with valid values.\n\n    save_config(config)\n\n    print(\"Migration completed successfully!\")\n    print(f\"  Default agent workspace: {default_workspace}\")\n    print(f\"  Default agent config: {agent_config_path}\")\n\n    return True\n"
  },
  {
    "path": "src/copaw/config/context.py",
    "content": "# -*- coding: utf-8 -*-\n\"\"\"Context variable for agent workspace directory.\n\nThis module provides a context variable to pass the agent's workspace\ndirectory to tool functions, allowing them to resolve relative paths\ncorrectly in a multi-agent environment.\n\"\"\"\nfrom contextvars import ContextVar\nfrom pathlib import Path\n\n# Context variable to store the current agent's workspace directory\ncurrent_workspace_dir: ContextVar[Path | None] = ContextVar(\n    \"current_workspace_dir\",\n    default=None,\n)\n\n\ndef get_current_workspace_dir() -> Path | None:\n    \"\"\"Get the current agent's workspace directory from context.\n\n    Returns:\n        Path to the current agent's workspace directory, or None if not set.\n    \"\"\"\n    return current_workspace_dir.get()\n\n\ndef set_current_workspace_dir(workspace_dir: Path | None) -> None:\n    \"\"\"Set the current agent's workspace directory in context.\n\n    Args:\n        workspace_dir: Path to the agent's workspace directory.\n    \"\"\"\n    current_workspace_dir.set(workspace_dir)\n"
  },
  {
    "path": "src/copaw/config/timezone.py",
    "content": "# -*- coding: utf-8 -*-\n\"\"\"Detect the system IANA timezone.\n\nKept in its own module to avoid circular imports between config.py and\nutils.py.  Uses only the standard library; always returns a valid string\n(falls back to ``\"UTC\"``).\n\"\"\"\n\nfrom __future__ import annotations\n\nimport os\nfrom datetime import datetime, timezone\nfrom typing import Optional\n\n\ndef _is_iana(name: Optional[str]) -> bool:\n    \"\"\"Return True if *name* looks like an IANA tz id.\"\"\"\n    return bool(name and \"/\" in name)\n\n\ndef detect_system_timezone() -> str:\n    \"\"\"Return the IANA timezone name of the host.\n\n    Falls back to ``\"UTC\"`` when detection fails.  This function\n    must *never* raise — any unexpected error is swallowed.\n    \"\"\"\n    try:\n        return _detect_system_timezone_inner()\n    except Exception:\n        return \"UTC\"\n\n\ndef _detect_system_timezone_inner() -> str:  # noqa: R0911\n    probes = [_probe_python, _probe_env]\n    if os.name == \"nt\":\n        probes.append(_probe_windows_registry)\n    else:\n        probes += [\n            _probe_etc_timezone,\n            _probe_localtime_link,\n            _probe_sysconfig_clock,\n            _probe_timedatectl,\n        ]\n    for probe in probes:\n        result = probe()\n        if result is not None:\n            return result\n    return \"UTC\"\n\n\ndef _probe_python() -> Optional[str]:\n    \"\"\"Ask the Python runtime for the local IANA name.\"\"\"\n    try:\n        name = (\n            datetime.now(timezone.utc)\n            .astimezone()\n            .tzinfo.tzname(None)  # type: ignore[union-attr]\n        )\n        if _is_iana(name):\n            return name\n    except Exception:\n        pass\n    return None\n\n\ndef _probe_env() -> Optional[str]:\n    \"\"\"Check the ``$TZ`` environment variable.\"\"\"\n    tz = os.environ.get(\"TZ\", \"\")\n    return tz if _is_iana(tz) else None\n\n\n_WIN_TO_IANA = {\n    \"China Standard Time\": \"Asia/Shanghai\",\n    \"Taipei Standard Time\": \"Asia/Taipei\",\n    \"Tokyo Standard Time\": \"Asia/Tokyo\",\n    \"Korea Standard Time\": \"Asia/Seoul\",\n    \"Singapore Standard Time\": \"Asia/Singapore\",\n    \"India Standard Time\": \"Asia/Kolkata\",\n    \"Arabian Standard Time\": \"Asia/Dubai\",\n    \"Russian Standard Time\": \"Europe/Moscow\",\n    \"W. Europe Standard Time\": \"Europe/Berlin\",\n    \"Romance Standard Time\": \"Europe/Paris\",\n    \"GMT Standard Time\": \"Europe/London\",\n    \"Eastern Standard Time\": \"America/New_York\",\n    \"Central Standard Time\": \"America/Chicago\",\n    \"Mountain Standard Time\": \"America/Denver\",\n    \"Pacific Standard Time\": \"America/Los_Angeles\",\n    \"US Mountain Standard Time\": \"America/Phoenix\",\n    \"Atlantic Standard Time\": \"America/Halifax\",\n    \"Hawaiian Standard Time\": \"Pacific/Honolulu\",\n    \"AUS Eastern Standard Time\": \"Australia/Sydney\",\n    \"New Zealand Standard Time\": \"Pacific/Auckland\",\n    \"Cen. Australia Standard Time\": \"Australia/Adelaide\",\n    \"E. Africa Standard Time\": \"Africa/Nairobi\",\n    \"SE Asia Standard Time\": \"Asia/Bangkok\",\n    \"West Pacific Standard Time\": \"Pacific/Port_Moresby\",\n    \"SA Eastern Standard Time\": \"America/Sao_Paulo\",\n    \"UTC\": \"UTC\",\n}\n\n\ndef _probe_windows_registry() -> Optional[str]:\n    \"\"\"Read the current timezone from the Windows registry.\"\"\"\n    try:\n        import winreg\n\n        reg_path = r\"SYSTEM\\CurrentControlSet\\Control\\TimeZoneInformation\"\n        key = winreg.OpenKey(winreg.HKEY_LOCAL_MACHINE, reg_path)\n        try:\n            win_tz = winreg.QueryValueEx(key, \"TimeZoneKeyName\")[0]\n        finally:\n            winreg.CloseKey(key)\n        return _WIN_TO_IANA.get(win_tz)\n    except Exception:\n        pass\n    return None\n\n\ndef _probe_etc_timezone() -> Optional[str]:\n    \"\"\"Read ``/etc/timezone`` (Debian / Ubuntu).\"\"\"\n    try:\n        with open(\"/etc/timezone\", encoding=\"utf-8\") as fh:\n            name = fh.read().strip()\n            if _is_iana(name):\n                return name\n    except (OSError, ValueError):\n        pass\n    return None\n\n\ndef _probe_localtime_link() -> Optional[str]:\n    \"\"\"Resolve the ``/etc/localtime`` symlink.\"\"\"\n    try:\n        link = os.readlink(\"/etc/localtime\")\n        if \"zoneinfo/\" in link:\n            return link.split(\"zoneinfo/\", 1)[1]\n    except OSError:\n        pass\n    return None\n\n\ndef _probe_sysconfig_clock() -> Optional[str]:\n    \"\"\"Parse ``/etc/sysconfig/clock`` (CentOS / RHEL ≤ 6).\"\"\"\n    try:\n        with open(\"/etc/sysconfig/clock\", encoding=\"utf-8\") as fh:\n            for raw in fh:\n                if raw.strip().startswith(\"ZONE=\"):\n                    zone = raw.split(\"=\", 1)[1].strip().strip('\"').strip(\"'\")\n                    if _is_iana(zone):\n                        return zone\n    except (OSError, ValueError):\n        pass\n    return None\n\n\ndef _probe_timedatectl() -> Optional[str]:\n    \"\"\"Query ``timedatectl`` (systemd).\"\"\"\n    import subprocess  # delayed: avoid cost on happy path\n\n    # systemd ≥ 239 — machine-readable output\n    try:\n        out = subprocess.check_output(\n            [\n                \"timedatectl\",\n                \"show\",\n                \"-p\",\n                \"Timezone\",\n                \"--value\",\n            ],\n            text=True,\n            timeout=1,\n            stderr=subprocess.DEVNULL,\n        ).strip()\n        if _is_iana(out):\n            return out\n    except Exception:\n        pass\n\n    # systemd < 239 (e.g. CentOS 7) — parse human output\n    try:\n        out = subprocess.check_output(\n            [\"timedatectl\", \"status\"],\n            text=True,\n            timeout=1,\n            stderr=subprocess.DEVNULL,\n        )\n        for line in out.splitlines():\n            if \"time zone\" in line.lower():\n                # \"Time zone: Asia/Shanghai (CST, +0800)\"\n                part = line.split(\":\", 1)[1]\n                part = part.strip().split()[0]\n                if _is_iana(part):\n                    return part\n    except Exception:\n        pass\n    return None\n"
  },
  {
    "path": "src/copaw/config/utils.py",
    "content": "# -*- coding: utf-8 -*-\nfrom __future__ import annotations\n\nimport json\nimport os\nimport plistlib\nimport subprocess\nimport sys\nfrom pathlib import Path\nfrom typing import Optional, Tuple\nfrom pydantic import ValidationError\n\nfrom ..constant import (\n    HEARTBEAT_FILE,\n    JOBS_FILE,\n    CHATS_FILE,\n    PLAYWRIGHT_CHROMIUM_EXECUTABLE_PATH_ENV,\n    RUNNING_IN_CONTAINER,\n    WORKING_DIR,\n)\nfrom .config import (\n    Config,\n    HeartbeatConfig,\n    LastApiConfig,\n    LastDispatchConfig,\n    load_agent_config,\n    save_agent_config,\n)\n\n\ndef _normalize_working_dir_bound_paths(data: object) -> object:\n    \"\"\"Normalize legacy ~/.copaw-bound paths to current WORKING_DIR.\n\n    This keeps COPAW_WORKING_DIR effective even if user config files contain\n    older hard-coded paths like \"~/.copaw/media\" or\n    \"/Users/x/.copaw/workspaces/...\".\n    Only rewrites known working-dir-bound keys.\n    \"\"\"\n    legacy_root_tilde = \"~/.copaw\"\n    legacy_root_abs = str(Path(legacy_root_tilde).expanduser().resolve())\n    new_root_abs = str(WORKING_DIR)\n\n    def _rewrite_path_value(v: object) -> object:\n        if not isinstance(v, str) or not v:\n            return v\n        if v.startswith(legacy_root_tilde):\n            return new_root_abs + v[len(legacy_root_tilde) :]\n        if v.startswith(legacy_root_abs):\n            return new_root_abs + v[len(legacy_root_abs) :]\n        return v\n\n    def _walk(obj: object, key: str | None = None) -> object:\n        if isinstance(obj, dict):\n            out: dict = {}\n            for k, v in obj.items():\n                out[k] = _walk(v, str(k))\n            return out\n        if isinstance(obj, list):\n            return [_walk(x, key) for x in obj]\n        if key in {\"workspace_dir\", \"media_dir\"}:\n            return _rewrite_path_value(obj)\n        return obj\n\n    return _walk(data, None)\n\n\ndef _discover_system_chromium_path() -> Optional[str]:\n    \"\"\"Scan common locations for Chrome/Chromium/Edge so we can use existing\n    browser instead of downloading via Playwright. Returns first found path.\n    \"\"\"\n    candidates: list[Path] = []\n    if sys.platform == \"win32\":\n        pf = os.environ.get(\"ProgramFiles\", \"C:\\\\Program Files\")\n        pf86 = os.environ.get(\"ProgramFiles(x86)\", \"C:\\\\Program Files (x86)\")\n        candidates = [\n            Path(pf) / \"Google\" / \"Chrome\" / \"Application\" / \"chrome.exe\",\n            Path(pf86) / \"Google\" / \"Chrome\" / \"Application\" / \"chrome.exe\",\n            Path(pf) / \"Microsoft\" / \"Edge\" / \"Application\" / \"msedge.exe\",\n            Path(pf86) / \"Microsoft\" / \"Edge\" / \"Application\" / \"msedge.exe\",\n            Path(pf) / \"Chromium\" / \"Application\" / \"chrome.exe\",\n        ]\n    elif sys.platform == \"darwin\":\n        candidates = [\n            Path(\n                \"/Applications/Google Chrome.app/Contents/MacOS/Google Chrome\",\n            ),\n            Path(\"/Applications/Chromium.app/Contents/MacOS/Chromium\"),\n            Path(\n                \"/Applications/Microsoft Edge.app/Contents/MacOS/\"\n                \"Microsoft Edge\",\n            ),\n        ]\n    else:\n        # Linux and other\n        candidates = [\n            Path(\"/usr/bin/google-chrome\"),\n            Path(\"/usr/bin/google-chrome-stable\"),\n            Path(\"/usr/bin/chromium\"),\n            Path(\"/usr/bin/chromium-browser\"),\n            Path(\"/usr/lib/chromium/chromium\"),\n        ]\n    for p in candidates:\n        if p.is_file():\n            return str(p.resolve())\n    return None\n\n\ndef get_playwright_chromium_executable_path() -> Optional[str]:\n    \"\"\"Chromium path from env when set and existing file (e.g. container).\n    In container, if env unset or path missing, try common system paths.\n    When not in container and env unset, scan for installed\n    Chrome/Chromium/Edge so we prefer user's browser instead of\n    triggering a download.\n    \"\"\"\n    path = os.environ.get(PLAYWRIGHT_CHROMIUM_EXECUTABLE_PATH_ENV)\n    if path and os.path.isfile(path):\n        return path\n    if is_running_in_container():\n        for candidate in (\n            \"/usr/bin/chromium\",\n            \"/usr/bin/chromium-browser\",\n            \"/usr/lib/chromium/chromium\",\n        ):\n            if os.path.isfile(candidate):\n                return candidate\n        return None\n    return _discover_system_chromium_path()\n\n\n# Bundle ID / ProgId -> (playwright kind, typical path or None for webkit).\n_BundleItem = Tuple[str, str, Optional[str]]\n_DARWIN_DEFAULT_BROWSER_BUNDLES: Tuple[_BundleItem, ...] = (\n    (\"com.apple.safari\", \"webkit\", None),\n    (\n        \"com.google.chrome\",\n        \"chromium\",\n        \"/Applications/Google Chrome.app/Contents/MacOS/Google Chrome\",\n    ),\n    (\n        \"com.microsoft.edgemac\",\n        \"chromium\",\n        \"/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge\",\n    ),\n    (\n        \"org.mozilla.firefox\",\n        \"firefox\",\n        \"/Applications/Firefox.app/Contents/MacOS/firefox\",\n    ),\n    (\n        \"org.mozilla.firefoxdeveloperedition\",\n        \"firefox\",\n        \"/Applications/Firefox Developer Edition.app/Contents/MacOS/firefox\",\n    ),\n    (\n        \"com.google.chrome.beta\",\n        \"chromium\",\n        \"/Applications/Google Chrome Beta.app/Contents/MacOS/Google Chrome\",\n    ),\n    (\n        \"com.google.chrome.canary\",\n        \"chromium\",\n        \"/Applications/Google Chrome Canary.app/Contents/MacOS/Google Chrome\",\n    ),\n)\n\n\n# pylint: disable=too-many-branches\ndef _get_darwin_default_browser() -> Tuple[Optional[str], Optional[str]]:\n    \"\"\"Return (browser_kind, executable_path) for macOS default HTTP\n    handler.\n    \"\"\"\n    result: Tuple[Optional[str], Optional[str]] = (None, None)\n    pref = \"~/Library/Preferences\"\n    plist_name = (\n        \"com.apple.LaunchServices.com.apple.launchservices.secure.plist\"\n    )\n    plist_path = Path(os.path.expanduser(pref)) / plist_name\n    if not plist_path.is_file():\n        return result\n    try:\n        with open(plist_path, \"rb\") as f:\n            data = plistlib.load(f)\n    except (OSError, plistlib.InvalidFileException):\n        return result\n    handlers = data.get(\"LSHandlers\") or data.get(\"LSHandler\")\n    if not isinstance(handlers, list):\n        return result\n    bundle_id: Optional[str] = None\n    for item in handlers:\n        if not isinstance(item, dict):\n            continue\n        if item.get(\"LSHandlerURLScheme\") in (\"http\", \"https\"):\n            bundle_id = item.get(\"LSHandlerRoleAll\") or item.get(\n                \"LSHandlerRoleViewer\",\n            )\n            if bundle_id:\n                break\n    if not bundle_id:\n        return result\n    for bid, kind, path in _DARWIN_DEFAULT_BROWSER_BUNDLES:\n        if bid != bundle_id:\n            continue\n        if path and Path(path).is_file():\n            result = (kind, path)\n            break\n        if kind == \"webkit\":\n            result = (\"webkit\", None)\n            break\n    else:\n        if bundle_id == \"com.apple.safari\":\n            result = (\"webkit\", None)\n    return result\n\n\ndef _get_win32_default_browser() -> Tuple[Optional[str], Optional[str]]:\n    \"\"\"Return (browser_kind, executable_path) for Windows default HTTP\n    handler.\n    \"\"\"\n    try:\n        import winreg\n    except ImportError:\n        return (None, None)\n    subkey = (\n        r\"Software\\Microsoft\\Windows\\Shell\\Associations\"\n        r\"\\UrlAssociations\\http\\UserChoice\"\n    )\n    try:\n        key = winreg.OpenKey(\n            winreg.HKEY_CURRENT_USER,\n            subkey,\n            0,\n            winreg.KEY_READ,\n        )\n        prog_id, _ = winreg.QueryValueEx(key, \"ProgId\")\n        winreg.CloseKey(key)\n    except OSError:\n        return (None, None)\n    # ProgId -> (kind, path template). %1 is URL.\n    prog_to_cmd: dict[str, Tuple[str, str]] = {\n        \"ChromeHTML\": (\"chromium\", r\"Google\\Chrome\\Application\\chrome.exe\"),\n        \"MSEdgeHTM\": (\"chromium\", r\"Microsoft\\Edge\\Application\\msedge.exe\"),\n        \"FirefoxURL\": (\"firefox\", r\"Mozilla Firefox\\firefox.exe\"),\n    }\n    for pid, (kind, suffix) in prog_to_cmd.items():\n        if not (prog_id == pid or prog_id.startswith(pid)):\n            continue\n        for env_key in (\"ProgramFiles\", \"ProgramFiles(x86)\"):\n            default = (\n                \"C:\\\\Program Files\"\n                if env_key == \"ProgramFiles\"\n                else \"C:\\\\Program Files (x86)\"\n            )\n            base = os.environ.get(env_key, default)\n            path = Path(base) / suffix\n            if path.is_file():\n                return (kind, str(path.resolve()))\n    return (None, None)\n\n\ndef _get_linux_default_browser() -> Tuple[Optional[str], Optional[str]]:\n    \"\"\"Return (browser_kind, executable_path) for Linux default HTTP\n    handler.\n    \"\"\"\n    try:\n        out = subprocess.run(\n            [\"xdg-mime\", \"query\", \"default\", \"x-scheme-handler/http\"],\n            capture_output=True,\n            text=True,\n            timeout=5,\n            check=False,\n        )\n        desktop = (out.stdout or \"\").strip() if out.returncode == 0 else \"\"\n    except (FileNotFoundError, subprocess.TimeoutExpired):\n        return (None, None)\n    if not desktop:\n        return (None, None)\n    xdg_home = os.environ.get(\n        \"XDG_DATA_HOME\",\n        os.path.expanduser(\"~/.local/share\"),\n    )\n    for base in [Path(xdg_home), Path(\"/usr/share\")]:\n        path = base / \"applications\" / desktop\n        if not path.is_file():\n            continue\n        try:\n            with open(path, encoding=\"utf-8\") as f:\n                for line in f:\n                    if line.strip().startswith(\"Exec=\"):\n                        exe = line.split(\"=\", 1)[1].strip().split()[0]\n                        if exe.startswith(\"/\") and Path(exe).is_file():\n                            return _linux_desktop_to_kind_and_path(exe)\n                        for p in [\"/usr/bin\", \"/usr/local/bin\"]:\n                            candidate = Path(p) / exe\n                            if candidate.is_file():\n                                return _linux_desktop_to_kind_and_path(\n                                    str(candidate),\n                                )\n                        break\n        except OSError:\n            continue\n    return (None, None)\n\n\ndef _linux_desktop_to_kind_and_path(exe_path: str) -> Tuple[str, str]:\n    \"\"\"Map Linux browser executable name to (kind, path).\"\"\"\n    name = Path(exe_path).name.lower()\n    if \"chrome\" in name or \"chromium\" in name:\n        return (\"chromium\", exe_path)\n    if \"firefox\" in name:\n        return (\"firefox\", exe_path)\n    if \"edge\" in name:\n        return (\"chromium\", exe_path)\n    return (\"chromium\", exe_path)\n\n\ndef get_system_default_browser() -> Tuple[Optional[str], Optional[str]]:\n    \"\"\"Return (browser_kind, executable_path) for the OS default HTTP browser.\n\n    browser_kind is 'chromium', 'firefox', or 'webkit'. path is None for\n    webkit. Returns (None, None) if detection fails or unsupported.\n    \"\"\"\n    if is_running_in_container():\n        return (None, None)\n    if sys.platform == \"darwin\":\n        return _get_darwin_default_browser()\n    if sys.platform == \"win32\":\n        return _get_win32_default_browser()\n    if sys.platform.startswith(\"linux\"):\n        return _get_linux_default_browser()\n    return (None, None)\n\n\ndef get_available_channels() -> Tuple[str, ...]:\n    \"\"\"Return channel keys enabled for this run (built-in + entry point\n    copaw.channels), filtered by COPAW_ENABLED_CHANNELS or\n    COPAW_DISABLED_CHANNELS when set.\n\n    * COPAW_ENABLED_CHANNELS — whitelist (only these channels are active).\n    * COPAW_DISABLED_CHANNELS — blacklist (all channels *except* these).\n    * If both are set, COPAW_ENABLED_CHANNELS takes precedence.\n    * If neither is set, all discovered channels are returned.\n    \"\"\"\n    from ..app.channels.registry import get_channel_registry\n\n    registry = get_channel_registry()\n    all_keys = tuple(registry.keys())\n\n    raw_enabled = os.environ.get(\"COPAW_ENABLED_CHANNELS\", \"\").strip()\n    if raw_enabled:\n        enabled = {ch.strip() for ch in raw_enabled.split(\",\") if ch.strip()}\n        return tuple(k for k in all_keys if k in enabled) or all_keys\n\n    raw_disabled = os.environ.get(\"COPAW_DISABLED_CHANNELS\", \"\").strip()\n    if raw_disabled:\n        disabled = {ch.strip() for ch in raw_disabled.split(\",\") if ch.strip()}\n        return tuple(k for k in all_keys if k not in disabled) or all_keys\n\n    return all_keys\n\n\ndef is_running_in_container() -> bool:\n    \"\"\"Return True if running inside a container (Docker/Kubernetes).\n    Prefer env COPAW_RUNNING_IN_CONTAINER (1/true/yes) at call time so\n    supervisord child gets correct value; else check /.dockerenv and cgroup.\n    \"\"\"\n    if RUNNING_IN_CONTAINER:\n        return True\n    if os.path.exists(\"/.dockerenv\"):\n        return True\n    try:\n        with open(\"/proc/1/cgroup\", encoding=\"utf-8\") as f:\n            content = f.read()\n            return \"docker\" in content or \"kubepods\" in content\n    except (OSError, FileNotFoundError):\n        return False\n\n\ndef get_config_path() -> Path:\n    \"\"\"Get the path to the config file.\"\"\"\n    return WORKING_DIR.joinpath(\"config.json\")\n\n\ndef get_heartbeat_query_path() -> Path:\n    \"\"\"Get path to heartbeat query file (HEARTBEAT.md in working dir).\"\"\"\n    return get_config_path().parent.joinpath(HEARTBEAT_FILE)\n\n\ndef _remove_nested_key(data: dict, path: list) -> bool:\n    \"\"\"Remove a nested key from *data* given a path list.\n\n    Returns True if the key was found and removed.\n    \"\"\"\n    obj = data\n    for segment in path[:-1]:\n        if isinstance(segment, str) and isinstance(obj, dict):\n            obj = obj.get(segment)\n        elif isinstance(segment, int) and isinstance(obj, list):\n            try:\n                obj = obj[segment]\n            except IndexError:\n                return False\n        else:\n            return False\n        if obj is None:\n            return False\n    last = path[-1]\n    if isinstance(last, str) and isinstance(obj, dict) and last in obj:\n        del obj[last]\n        return True\n    return False\n\n\ndef _remove_bad_field(data: dict, loc: list) -> bool:\n    \"\"\"Try to remove the field at *loc*; fall back to ancestor keys.\"\"\"\n    if _remove_nested_key(data, loc):\n        return True\n    for end in range(len(loc) - 1, 0, -1):\n        if _remove_nested_key(data, loc[:end]):\n            return True\n    return False\n\n\ndef load_config(config_path: Optional[Path] = None) -> Config:\n    \"\"\"Load config from file. Returns default Config if file is missing.\"\"\"\n    if config_path is None:\n        config_path = get_config_path()\n    if not config_path.is_file():\n        return Config()\n\n    try:\n        with open(config_path, \"r\", encoding=\"utf-8\") as file:\n            data = json.load(file)\n    except (json.JSONDecodeError, UnicodeDecodeError):\n        return Config()\n\n    data = _normalize_working_dir_bound_paths(data)\n    # Backward compat: top-level last_api_host / last_api_port -> last_api\n    if \"last_api_host\" in data or \"last_api_port\" in data:\n        la = data.setdefault(\"last_api\", {})\n        if \"host\" not in la and \"last_api_host\" in data:\n            la[\"host\"] = data.get(\"last_api_host\")\n        if \"port\" not in la and \"last_api_port\" in data:\n            la[\"port\"] = data.get(\"last_api_port\")\n\n    try:\n        return Config.model_validate(data)\n    except ValidationError as exc:\n        fixed_any = False\n        for err in exc.errors():\n            loc = list(err.get(\"loc\", []))\n            if loc and _remove_bad_field(data, loc):\n                fixed_any = True\n        if not fixed_any:\n            raise\n\n    try:\n        return Config.model_validate(data)\n    except ValidationError:\n        return Config()\n\n\ndef save_config(config: Config, config_path: Optional[Path] = None) -> None:\n    \"\"\"Save the config to the file.\"\"\"\n    if config_path is None:\n        config_path = get_config_path()\n    config_path.parent.mkdir(parents=True, exist_ok=True)\n    with open(config_path, \"w\", encoding=\"utf-8\") as file:\n        json.dump(\n            config.model_dump(mode=\"json\", by_alias=True),\n            file,\n            indent=2,\n            ensure_ascii=False,\n        )\n\n\ndef get_heartbeat_config(agent_id: Optional[str] = None) -> HeartbeatConfig:\n    \"\"\"Return effective heartbeat config (from agent config or default).\n\n    Args:\n        agent_id: Agent ID to load config from. If None, tries to load from\n                  root config.agents.defaults (legacy behavior).\n\n    Returns:\n        HeartbeatConfig: Heartbeat configuration or default.\n    \"\"\"\n    if agent_id is not None:\n        try:\n            agent_config = load_agent_config(agent_id)\n            hb = agent_config.heartbeat\n            return hb if hb is not None else HeartbeatConfig()\n        except Exception:\n            return HeartbeatConfig()\n\n    # Legacy: try to load from root config\n    config = load_config()\n    if config.agents.defaults is None:\n        return HeartbeatConfig()\n    hb = config.agents.defaults.heartbeat\n    return hb if hb is not None else HeartbeatConfig()\n\n\ndef update_last_dispatch(\n    channel: str,\n    user_id: str,\n    session_id: str,\n    agent_id: Optional[str] = None,\n) -> None:\n    \"\"\"Persist last user-reply dispatch target (user send+reply only).\n\n    Args:\n        channel: Channel name\n        user_id: User ID\n        session_id: Session ID\n        agent_id: Agent ID to update. If None, updates root config (legacy).\n    \"\"\"\n    if agent_id is not None:\n        try:\n            agent_config = load_agent_config(agent_id)\n            agent_config.last_dispatch = LastDispatchConfig(\n                channel=channel,\n                user_id=user_id,\n                session_id=session_id,\n            )\n            save_agent_config(agent_id, agent_config)\n            return\n        except Exception:\n            pass\n\n    # Legacy: update root config\n    config = load_config()\n    config.last_dispatch = LastDispatchConfig(\n        channel=channel,\n        user_id=user_id,\n        session_id=session_id,\n    )\n    save_config(config)\n\n\ndef read_last_api() -> Optional[Tuple[str, int]]:\n    \"\"\"Read last API host/port from config (via config load/save).\"\"\"\n    config = load_config()\n    host = config.last_api.host\n    port = config.last_api.port\n    if not host or port is None:\n        return None\n    return host, port\n\n\ndef write_last_api(host: str, port: int) -> None:\n    \"\"\"Write last API host/port to config (via config load/save).\"\"\"\n    config = load_config()\n    config.last_api = LastApiConfig(host=host, port=port)\n    save_config(config)\n\n\ndef get_jobs_path() -> Path:\n    \"\"\"Return cron jobs.json path.\"\"\"\n\n    return (WORKING_DIR / JOBS_FILE).expanduser()\n\n\ndef get_chats_path() -> Path:\n    \"\"\"Return chats.json path.\"\"\"\n    return (WORKING_DIR / CHATS_FILE).expanduser()\n"
  },
  {
    "path": "src/copaw/constant.py",
    "content": "# -*- coding: utf-8 -*-\nimport os\nfrom pathlib import Path\nfrom dotenv import load_dotenv\n\n# Load .env file from project root before reading any env vars\n_env_path = Path(__file__).resolve().parent.parent.parent / \".env\"\nif _env_path.exists():\n    load_dotenv(_env_path)\n\n\nclass EnvVarLoader:\n    \"\"\"Utility to load and parse environment variables with type safety\n    and defaults.\n    \"\"\"\n\n    @staticmethod\n    def get_bool(env_var: str, default: bool = False) -> bool:\n        \"\"\"Get a boolean environment variable,\n        interpreting common truthy values.\"\"\"\n        val = os.environ.get(env_var, str(default)).lower()\n        return val in (\"true\", \"1\", \"yes\")\n\n    @staticmethod\n    def get_float(\n        env_var: str,\n        default: float = 0.0,\n        min_value: float | None = None,\n        max_value: float | None = None,\n        allow_inf: bool = False,\n    ) -> float:\n        \"\"\"Get a float environment variable with optional bounds\n        and infinity handling.\"\"\"\n        try:\n            value = float(os.environ.get(env_var, str(default)))\n            if min_value is not None and value < min_value:\n                return min_value\n            if max_value is not None and value > max_value:\n                return max_value\n            if not allow_inf and (\n                value == float(\"inf\") or value == float(\"-inf\")\n            ):\n                return default\n            return value\n        except (TypeError, ValueError):\n            return default\n\n    @staticmethod\n    def get_int(\n        env_var: str,\n        default: int = 0,\n        min_value: int | None = None,\n        max_value: int | None = None,\n    ) -> int:\n        \"\"\"Get an integer environment variable with optional bounds.\"\"\"\n        try:\n            value = int(os.environ.get(env_var, str(default)))\n            if min_value is not None and value < min_value:\n                return min_value\n            if max_value is not None and value > max_value:\n                return max_value\n            return value\n        except (TypeError, ValueError):\n            return default\n\n    @staticmethod\n    def get_str(env_var: str, default: str = \"\") -> str:\n        \"\"\"Get a string environment variable with a default fallback.\"\"\"\n        return os.environ.get(env_var, default)\n\n\nWORKING_DIR = (\n    Path(EnvVarLoader.get_str(\"COPAW_WORKING_DIR\", \"~/.copaw\"))\n    .expanduser()\n    .resolve()\n)\nSECRET_DIR = (\n    Path(\n        EnvVarLoader.get_str(\n            \"COPAW_SECRET_DIR\",\n            f\"{WORKING_DIR}.secret\",\n        ),\n    )\n    .expanduser()\n    .resolve()\n)\n\n# Default media directory for channels (cross-platform)\nDEFAULT_MEDIA_DIR = WORKING_DIR / \"media\"\n\nJOBS_FILE = EnvVarLoader.get_str(\"COPAW_JOBS_FILE\", \"jobs.json\")\n\nCHATS_FILE = EnvVarLoader.get_str(\"COPAW_CHATS_FILE\", \"chats.json\")\n\nTOKEN_USAGE_FILE = EnvVarLoader.get_str(\n    \"COPAW_TOKEN_USAGE_FILE\",\n    \"token_usage.json\",\n)\n\nCONFIG_FILE = EnvVarLoader.get_str(\"COPAW_CONFIG_FILE\", \"config.json\")\n\nHEARTBEAT_FILE = EnvVarLoader.get_str(\"COPAW_HEARTBEAT_FILE\", \"HEARTBEAT.md\")\nHEARTBEAT_DEFAULT_EVERY = \"6h\"\nHEARTBEAT_DEFAULT_TARGET = \"main\"\nHEARTBEAT_TARGET_LAST = \"last\"\n\n# Debug history file for /dump_history and /load_history commands\nDEBUG_HISTORY_FILE = EnvVarLoader.get_str(\n    \"COPAW_DEBUG_HISTORY_FILE\",\n    \"debug_history.jsonl\",\n)\nMAX_LOAD_HISTORY_COUNT = 10000\n\n# Env key for app log level (used by CLI and app load for reload child).\nLOG_LEVEL_ENV = \"COPAW_LOG_LEVEL\"\n\n# Env to indicate running inside a container (e.g. Docker). Set to 1/true/yes.\nRUNNING_IN_CONTAINER = EnvVarLoader.get_bool(\n    \"COPAW_RUNNING_IN_CONTAINER\",\n    False,\n)\n\n# Timeout in seconds for checking if a provider is reachable.\nMODEL_PROVIDER_CHECK_TIMEOUT = EnvVarLoader.get_float(\n    \"COPAW_MODEL_PROVIDER_CHECK_TIMEOUT\",\n    5.0,\n    min_value=0,\n    allow_inf=False,\n)\n\n# Playwright: use system Chromium when set (e.g. in Docker).\nPLAYWRIGHT_CHROMIUM_EXECUTABLE_PATH_ENV = \"PLAYWRIGHT_CHROMIUM_EXECUTABLE_PATH\"\n\n# When True, expose /docs, /redoc, /openapi.json\n# (dev only; keep False in prod).\nDOCS_ENABLED = EnvVarLoader.get_bool(\"COPAW_OPENAPI_DOCS\", False)\n\n# Memory directory\nMEMORY_DIR = WORKING_DIR / \"memory\"\n\n# Custom channel modules (installed via `copaw channels install`); manager\n# loads BaseChannel subclasses from here.\nCUSTOM_CHANNELS_DIR = WORKING_DIR / \"custom_channels\"\n\n# Local models directory\nMODELS_DIR = WORKING_DIR / \"models\"\n\nMEMORY_COMPACT_KEEP_RECENT = EnvVarLoader.get_int(\n    \"COPAW_MEMORY_COMPACT_KEEP_RECENT\",\n    3,\n    min_value=0,\n)\n\n# Memory compaction configuration\nMEMORY_COMPACT_RATIO = EnvVarLoader.get_float(\n    \"COPAW_MEMORY_COMPACT_RATIO\",\n    0.7,\n    min_value=0,\n    allow_inf=False,\n)\n\nDASHSCOPE_BASE_URL = EnvVarLoader.get_str(\n    \"DASHSCOPE_BASE_URL\",\n    \"https://dashscope.aliyuncs.com/compatible-mode/v1\",\n)\n\n# CORS configuration — comma-separated list of allowed origins for dev mode.\n# Example: COPAW_CORS_ORIGINS=\"http://localhost:5173,http://127.0.0.1:5173\"\n# When unset, CORS middleware is not applied.\nCORS_ORIGINS = EnvVarLoader.get_str(\"COPAW_CORS_ORIGINS\", \"\").strip()\n\n# LLM API retry configuration\nLLM_MAX_RETRIES = EnvVarLoader.get_int(\n    \"COPAW_LLM_MAX_RETRIES\",\n    3,\n    min_value=0,\n)\n\nLLM_BACKOFF_BASE = EnvVarLoader.get_float(\n    \"COPAW_LLM_BACKOFF_BASE\",\n    1.0,\n    min_value=0.1,\n)\n\nLLM_BACKOFF_CAP = EnvVarLoader.get_float(\n    \"COPAW_LLM_BACKOFF_CAP\",\n    10.0,\n    min_value=0.5,\n)\n\n# Tool guard approval timeout (seconds).\ntry:\n    TOOL_GUARD_APPROVAL_TIMEOUT_SECONDS = max(\n        float(\n            os.environ.get(\"COPAW_TOOL_GUARD_APPROVAL_TIMEOUT_SECONDS\", \"600\"),\n        ),\n        1.0,\n    )\nexcept (TypeError, ValueError):\n    TOOL_GUARD_APPROVAL_TIMEOUT_SECONDS = 600.0\n"
  },
  {
    "path": "src/copaw/envs/__init__.py",
    "content": "# -*- coding: utf-8 -*-\n\"\"\"Environment variable management.\"\"\"\nfrom .store import (\n    delete_env_var,\n    load_envs,\n    load_envs_into_environ,\n    save_envs,\n    set_env_var,\n)\n\n__all__ = [\n    \"delete_env_var\",\n    \"load_envs\",\n    \"load_envs_into_environ\",\n    \"save_envs\",\n    \"set_env_var\",\n]\n"
  },
  {
    "path": "src/copaw/envs/store.py",
    "content": "# -*- coding: utf-8 -*-\n\"\"\"Reading and writing environment variables.\n\nPersistence strategy (two layers):\n\n1. **envs.json** – canonical store, survives process restarts.\n2. **os.environ** – injected into the current Python process so that\n   ``os.getenv()`` and child subprocesses (``subprocess.run``, etc.)\n   can read them immediately.\n\"\"\"\nfrom __future__ import annotations\n\nimport json\nimport logging\nimport os\nimport shutil\nfrom pathlib import Path\nfrom typing import Optional\n\nlogger = logging.getLogger(__name__)\n\n_BOOTSTRAP_WORKING_DIR = (\n    Path(os.environ.get(\"COPAW_WORKING_DIR\", \"~/.copaw\"))\n    .expanduser()\n    .resolve()\n)\n_BOOTSTRAP_SECRET_DIR = (\n    Path(\n        os.environ.get(\n            \"COPAW_SECRET_DIR\",\n            f\"{_BOOTSTRAP_WORKING_DIR}.secret\",\n        ),\n    )\n    .expanduser()\n    .resolve()\n)\n\n_ENVS_JSON = _BOOTSTRAP_SECRET_DIR / \"envs.json\"\n_LEGACY_ENVS_JSON_CANDIDATES = (\n    Path(__file__).resolve().parent / \"envs.json\",\n    _BOOTSTRAP_WORKING_DIR / \"envs.json\",\n)\n\n\ndef _same_path(a: Path, b: Path) -> bool:\n    try:\n        return a.resolve() == b.resolve()\n    except OSError:\n        return False\n\n\ndef _chmod_best_effort(path: Path, mode: int) -> None:\n    try:\n        os.chmod(path, mode)\n    except OSError:\n        # Some systems/filesystems may not support chmod semantics.\n        pass\n\n\ndef _prepare_secret_parent(path: Path) -> None:\n    path.parent.mkdir(parents=True, exist_ok=True)\n    _chmod_best_effort(path.parent, 0o700)\n\n\ndef _migrate_legacy_envs_json(path: Path) -> None:\n    \"\"\"Copy old envs.json into secret dir once (best effort).\"\"\"\n    if path.is_file():\n        return\n    if path.exists() and not path.is_file():\n        logger.error(\n            \"envs.json path exists but is not a regular file: %s\",\n            path,\n        )\n        return\n\n    for legacy in _LEGACY_ENVS_JSON_CANDIDATES:\n        if not legacy.is_file() or _same_path(legacy, path):\n            continue\n        try:\n            _prepare_secret_parent(path)\n            shutil.copy2(legacy, path)\n            _chmod_best_effort(path, 0o600)\n            return\n        except OSError as exc:\n            logger.warning(\n                \"Failed to migrate legacy envs.json from %s: %s\",\n                legacy,\n                exc,\n            )\n            continue\n\n\n# Security-sensitive envs should come from process/system environment,\n# not persisted envs.json.\n_PROTECTED_BOOTSTRAP_KEYS = frozenset(\n    {\n        \"COPAW_WORKING_DIR\",\n        \"COPAW_SECRET_DIR\",\n    },\n)\n\n\ndef get_envs_json_path() -> Path:\n    \"\"\"Return envs.json path under SECRET_DIR.\"\"\"\n    return _ENVS_JSON\n\n\n# ------------------------------------------------------------------\n# os.environ helpers\n# ------------------------------------------------------------------\n\n\ndef _apply_to_environ(\n    envs: dict[str, str],\n    *,\n    overwrite: bool = True,\n) -> None:\n    \"\"\"Set key/value pairs into ``os.environ``.\n\n    Args:\n        envs: Key-value mapping to inject.\n        overwrite: When False, existing process env values take precedence.\n    \"\"\"\n    for key, value in envs.items():\n        if not overwrite and key in os.environ:\n            continue\n        os.environ[key] = value\n\n\ndef _remove_from_environ(key: str) -> None:\n    \"\"\"Remove *key* from ``os.environ`` if present.\"\"\"\n    os.environ.pop(key, None)\n\n\ndef _sync_environ(\n    old: dict[str, str],\n    new: dict[str, str],\n) -> None:\n    \"\"\"Synchronise ``os.environ``: set *new*, remove stale *old*.\"\"\"\n    for key, old_value in old.items():\n        if key not in new and os.environ.get(key) == old_value:\n            _remove_from_environ(key)\n    _apply_to_environ(new, overwrite=True)\n\n\n# ------------------------------------------------------------------\n# JSON persistence\n# ------------------------------------------------------------------\n\n\ndef load_envs(\n    path: Optional[Path] = None,\n) -> dict[str, str]:\n    \"\"\"Load env vars from envs.json.\"\"\"\n    if path is None:\n        path = get_envs_json_path()\n        _migrate_legacy_envs_json(path)\n    if path.exists() and not path.is_file():\n        logger.error(\n            \"envs.json path exists but is not a regular file: %s\",\n            path,\n        )\n        return {}\n    if not path.is_file():\n        return {}\n    try:\n        with open(path, \"r\", encoding=\"utf-8\") as fh:\n            data = json.load(fh)\n        if isinstance(data, dict):\n            return {k: str(v) for k, v in data.items()}\n    except (json.JSONDecodeError, ValueError):\n        pass\n    except OSError as exc:\n        logger.warning(\n            \"Failed to read envs.json from %s due to OS error: %s\",\n            path,\n            exc,\n        )\n    return {}\n\n\ndef save_envs(\n    envs: dict[str, str],\n    path: Optional[Path] = None,\n) -> None:\n    \"\"\"Write env vars to envs.json and sync to ``os.environ``.\"\"\"\n    if path is None:\n        path = get_envs_json_path()\n        _migrate_legacy_envs_json(path)\n    old = load_envs(path)\n    if path.exists() and not path.is_file():\n        raise IsADirectoryError(\n            f\"envs.json path exists but is not a regular file: {path}\",\n        )\n    _prepare_secret_parent(path)\n    with open(path, \"w\", encoding=\"utf-8\") as fh:\n        json.dump(envs, fh, indent=2, ensure_ascii=False)\n    _chmod_best_effort(path, 0o600)\n\n    _sync_environ(old, envs)\n\n\ndef set_env_var(\n    key: str,\n    value: str,\n) -> dict[str, str]:\n    \"\"\"Set a single env var. Returns updated dict.\"\"\"\n    envs = load_envs()\n    envs[key] = value\n    save_envs(envs)\n    return envs\n\n\ndef delete_env_var(key: str) -> dict[str, str]:\n    \"\"\"Delete a single env var. Returns updated dict.\"\"\"\n    envs = load_envs()\n    envs.pop(key, None)\n    save_envs(envs)\n    return envs\n\n\ndef load_envs_into_environ() -> dict[str, str]:\n    \"\"\"Load envs.json and apply bootstrap-safe entries to ``os.environ``.\n\n    Call this once at application startup so that environment\n    variables persisted from a previous session are available\n    immediately. Protected keys are excluded from injection, and\n    existing process/system env vars are preserved.\n\n    Returns:\n        Full persisted mapping from envs.json, including protected keys\n        that are intentionally not injected into ``os.environ``.\n    \"\"\"\n    envs = load_envs()\n    bootstrap_envs = {\n        key: value\n        for key, value in envs.items()\n        if key not in _PROTECTED_BOOTSTRAP_KEYS\n    }\n    # Do not override explicit runtime/system env vars.\n    _apply_to_environ(bootstrap_envs, overwrite=False)\n    return envs\n"
  },
  {
    "path": "src/copaw/local_models/__init__.py",
    "content": "# -*- coding: utf-8 -*-\n\"\"\"Local model management and inference.\"\"\"\n\nfrom .schema import (\n    BackendType,\n    DownloadSource,\n    LocalModelInfo,\n    DownloadProgress,\n)\nfrom .manager import (\n    LocalModelManager,\n    list_local_models,\n    get_local_model,\n    delete_local_model,\n)\nfrom .factory import (\n    create_local_chat_model,\n    unload_active_model,\n    get_active_local_model,\n)\n\n__all__ = [\n    \"BackendType\",\n    \"DownloadSource\",\n    \"LocalModelInfo\",\n    \"DownloadProgress\",\n    \"LocalModelManager\",\n    \"list_local_models\",\n    \"get_local_model\",\n    \"delete_local_model\",\n    \"create_local_chat_model\",\n    \"unload_active_model\",\n    \"get_active_local_model\",\n]\n"
  },
  {
    "path": "src/copaw/local_models/backends/__init__.py",
    "content": "# -*- coding: utf-8 -*-\n\"\"\"Local model inference backends.\"\"\"\n\nfrom .base import LocalBackend\n\n__all__ = [\"LocalBackend\"]\n"
  },
  {
    "path": "src/copaw/local_models/backends/base.py",
    "content": "# -*- coding: utf-8 -*-\n\"\"\"Abstract base class for local model inference backends.\"\"\"\n\nfrom __future__ import annotations\n\nfrom abc import ABC, abstractmethod\nfrom typing import Any, Iterator, Optional, Type\n\nfrom pydantic import BaseModel\n\n\nclass LocalBackend(ABC):\n    \"\"\"Abstract interface for a local model inference backend.\n\n    Each backend wraps a specific library (llama-cpp-python, mlx-lm, etc.)\n    and exposes a unified chat-completion interface that returns\n    OpenAI-compatible dicts.\n    \"\"\"\n\n    @abstractmethod\n    def __init__(self, model_path: str, **kwargs: Any) -> None:\n        \"\"\"Load the model from disk into memory.\n\n        Args:\n            model_path: Absolute path to the model file.\n            **kwargs: Backend-specific parameters (n_ctx, n_gpu_layers, etc.)\n        \"\"\"\n\n    @abstractmethod\n    def chat_completion(\n        self,\n        messages: list[dict],\n        tools: Optional[list[dict]] = None,\n        tool_choice: Optional[str] = None,\n        structured_model: Optional[Type[BaseModel]] = None,\n        **kwargs: Any,\n    ) -> dict:\n        \"\"\"Non-streaming chat completion.\n\n        Returns an OpenAI-compatible dict with ``choices`` and ``usage``.\n        \"\"\"\n\n    @abstractmethod\n    def chat_completion_stream(\n        self,\n        messages: list[dict],\n        tools: Optional[list[dict]] = None,\n        tool_choice: Optional[str] = None,\n        **kwargs: Any,\n    ) -> Iterator[dict]:\n        \"\"\"Streaming chat completion.\n\n        Yields OpenAI-compatible chunk dicts.\n        \"\"\"\n\n    @abstractmethod\n    def unload(self) -> None:\n        \"\"\"Release all resources (VRAM, RAM) held by the model.\"\"\"\n\n    @property\n    @abstractmethod\n    def is_loaded(self) -> bool:\n        \"\"\"Whether a model is currently loaded and ready for inference.\"\"\"\n"
  },
  {
    "path": "src/copaw/local_models/backends/llamacpp_backend.py",
    "content": "# -*- coding: utf-8 -*-\n\"\"\"llama.cpp backend using llama-cpp-python.\"\"\"\n\nfrom __future__ import annotations\n\nimport logging\nfrom typing import Any, Iterator, Optional, Type\n\nfrom pydantic import BaseModel\n\nfrom .base import LocalBackend\n\nlogger = logging.getLogger(__name__)\n\n\ndef _normalize_messages(messages: list[dict]) -> list[dict]:\n    \"\"\"Normalise messages for llama-cpp-python's Jinja chat templates.\n\n    * Content must be a plain string (never ``None`` or a list of blocks).\n    * ``tool_calls`` must be a proper list or absent (never ``None``).\n    \"\"\"\n    out: list[dict] = []\n    for msg in messages:\n        content = msg.get(\"content\")\n        if isinstance(content, list):\n            parts: list[str] = []\n            for block in content:\n                if isinstance(block, dict):\n                    parts.append(block.get(\"text\", \"\"))\n                elif isinstance(block, str):\n                    parts.append(block)\n            msg = {**msg, \"content\": \"\\n\".join(parts)}\n        elif content is None:\n            msg = {**msg, \"content\": \"\"}\n\n        # Ensure tool_calls is a proper list or absent — Jinja templates\n        # crash when iterating or checking containment on None.\n        if \"tool_calls\" in msg and not msg[\"tool_calls\"]:\n            msg = {k: v for k, v in msg.items() if k != \"tool_calls\"}\n\n        out.append(msg)\n    return out\n\n\nclass LlamaCppBackend(LocalBackend):\n    \"\"\"Backend implementation using llama-cpp-python.\"\"\"\n\n    def __init__(\n        self,\n        model_path: str,\n        n_ctx: int = 32768,\n        n_gpu_layers: int = -1,\n        verbose: bool = False,\n        chat_format: Optional[str] = None,\n        **kwargs: Any,\n    ) -> None:\n        try:\n            from llama_cpp import Llama\n        except ImportError as e:\n            raise ImportError(\n                \"llama-cpp-python is required for the llamacpp backend. \"\n                \"Install it with: pip install 'copaw[llamacpp]'\",\n            ) from e\n\n        logger.info(\n            \"Loading model from %s (n_ctx=%d, n_gpu_layers=%d)\",\n            model_path,\n            n_ctx,\n            n_gpu_layers,\n        )\n\n        init_kwargs: dict[str, Any] = {\n            \"model_path\": model_path,\n            \"n_ctx\": n_ctx,\n            \"n_gpu_layers\": n_gpu_layers,\n            \"verbose\": verbose,\n            **kwargs,\n        }\n        if chat_format is not None:\n            init_kwargs[\"chat_format\"] = chat_format\n\n        self._llm = Llama(**init_kwargs)\n        self._model_path = model_path\n        logger.info(\"Model loaded successfully: %s\", model_path)\n\n    def chat_completion(\n        self,\n        messages: list[dict],\n        tools: Optional[list[dict]] = None,\n        tool_choice: Optional[str] = None,\n        structured_model: Optional[Type[BaseModel]] = None,\n        **kwargs: Any,\n    ) -> dict:\n        call_kwargs: dict[str, Any] = {\n            \"messages\": _normalize_messages(messages),\n            \"stream\": False,\n            **kwargs,\n        }\n\n        if tools:\n            call_kwargs[\"tools\"] = tools\n            call_kwargs[\"tool_choice\"] = tool_choice or \"auto\"\n\n        if structured_model:\n            schema = structured_model.model_json_schema()\n            call_kwargs[\"response_format\"] = {\n                \"type\": \"json_object\",\n                \"schema\": schema,\n            }\n\n        return self._llm.create_chat_completion(**call_kwargs)\n\n    def chat_completion_stream(\n        self,\n        messages: list[dict],\n        tools: Optional[list[dict]] = None,\n        tool_choice: Optional[str] = None,\n        **kwargs: Any,\n    ) -> Iterator[dict]:\n        call_kwargs: dict[str, Any] = {\n            \"messages\": _normalize_messages(messages),\n            \"stream\": True,\n            **kwargs,\n        }\n        if tools:\n            call_kwargs[\"tools\"] = tools\n            call_kwargs[\"tool_choice\"] = tool_choice or \"auto\"\n\n        yield from self._llm.create_chat_completion(**call_kwargs)\n\n    def unload(self) -> None:\n        if self._llm is not None:\n            del self._llm\n            self._llm = None\n            logger.info(\"Model unloaded: %s\", self._model_path)\n\n    @property\n    def is_loaded(self) -> bool:\n        return self._llm is not None\n"
  },
  {
    "path": "src/copaw/local_models/backends/mlx_backend.py",
    "content": "# -*- coding: utf-8 -*-\n\"\"\"MLX backend using mlx-lm for Apple Silicon.\"\"\"\n\nfrom __future__ import annotations\n\nimport logging\nfrom pathlib import Path\nfrom typing import Any, Iterator, Optional, Type\n\nfrom pydantic import BaseModel\n\nfrom .base import LocalBackend\n\nlogger = logging.getLogger(__name__)\n\n\ndef _normalize_messages(messages: list[dict]) -> list[dict]:\n    \"\"\"Normalise messages for MLX tokenizer chat templates.\n\n    * Content must be a plain string (never ``None`` or a list of blocks).\n    * ``tool_calls`` must be a proper list or absent (never ``None``).\n    \"\"\"\n    out: list[dict] = []\n    for msg in messages:\n        content = msg.get(\"content\")\n        if isinstance(content, list):\n            parts: list[str] = []\n            for block in content:\n                if isinstance(block, dict):\n                    parts.append(block.get(\"text\", \"\"))\n                elif isinstance(block, str):\n                    parts.append(block)\n            msg = {**msg, \"content\": \"\\n\".join(parts)}\n        elif content is None:\n            msg = {**msg, \"content\": \"\"}\n\n        if \"tool_calls\" in msg and not msg[\"tool_calls\"]:\n            msg = {k: v for k, v in msg.items() if k != \"tool_calls\"}\n\n        out.append(msg)\n    return out\n\n\ndef _resolve_model_dir(model_path: str) -> str:\n    \"\"\"Return the model directory from a file or directory path.\n\n    MLX models are directory-based (safetensors + config files), but\n    ``LocalModelInfo.local_path`` may point to a specific file within that\n    directory.\n    \"\"\"\n    p = Path(model_path)\n    if p.is_file():\n        return str(p.parent)\n    return str(p)\n\n\nclass MlxBackend(LocalBackend):\n    \"\"\"Backend implementation using mlx-lm for Apple Silicon.\"\"\"\n\n    def __init__(\n        self,\n        model_path: str,\n        max_tokens: int = 2048,\n        **kwargs: Any,\n    ) -> None:\n        try:\n            import mlx_lm\n        except ImportError as e:\n            raise ImportError(\n                \"mlx-lm is required for the MLX backend. \"\n                \"Install it with: pip install 'copaw[mlx]'\",\n            ) from e\n\n        model_dir = _resolve_model_dir(model_path)\n        logger.info(\"Loading MLX model from %s\", model_dir)\n\n        self._model, self._tokenizer = mlx_lm.load(model_dir)\n        self._model_path = model_path\n        self._model_dir = model_dir\n        self._max_tokens = max_tokens\n        self._kwargs = kwargs\n        logger.info(\"MLX model loaded successfully: %s\", model_dir)\n\n    def _build_prompt(\n        self,\n        messages: list[dict],\n        tools: Optional[list[dict]] = None,\n    ) -> str:\n        \"\"\"Apply the tokenizer chat template to produce a prompt string.\"\"\"\n        kwargs: dict[str, Any] = {\n            \"tokenize\": False,\n            \"add_generation_prompt\": True,\n        }\n        if tools and getattr(self._tokenizer, \"has_tool_calling\", False):\n            kwargs[\"tools\"] = tools\n        return self._tokenizer.apply_chat_template(messages, **kwargs)\n\n    def chat_completion(\n        self,\n        messages: list[dict],\n        tools: Optional[list[dict]] = None,\n        tool_choice: Optional[str] = None,\n        structured_model: Optional[Type[BaseModel]] = None,\n        **kwargs: Any,\n    ) -> dict:\n        import mlx_lm\n\n        prompt = self._build_prompt(_normalize_messages(messages), tools=tools)\n\n        max_tokens = kwargs.pop(\"max_tokens\", self._max_tokens)\n        merged = {**self._kwargs, **kwargs}\n\n        # Build sampler kwargs from merged params\n        sampler_kwargs = {}\n        for key in (\"temp\", \"temperature\", \"top_p\", \"min_p\", \"top_k\"):\n            if key in merged:\n                val = merged.pop(key)\n                # mlx-lm uses \"temp\" not \"temperature\"\n                sampler_key = \"temp\" if key == \"temperature\" else key\n                sampler_kwargs[sampler_key] = val\n\n        generate_kwargs: dict[str, Any] = {}\n        if sampler_kwargs:\n            from mlx_lm.sample_utils import make_sampler\n\n            generate_kwargs[\"sampler\"] = make_sampler(**sampler_kwargs)\n\n        if structured_model:\n            schema = structured_model.model_json_schema()\n            # Append JSON instruction to prompt — MLX doesn't have native\n            # structured output, so we rely on the model\n            # following instructions.\n            prompt += (\n                f\"\\nRespond with a JSON object matching this schema: \"\n                f\"{schema}\\n\"\n            )\n\n        # Accumulate all tokens via stream_generate\n        text_parts: list[str] = []\n        prompt_tokens = 0\n        generation_tokens = 0\n        finish_reason: Optional[str] = None\n\n        for response in mlx_lm.stream_generate(\n            self._model,\n            self._tokenizer,\n            prompt=prompt,\n            max_tokens=max_tokens if max_tokens is not None else 2048,\n            **generate_kwargs,\n        ):\n            text_parts.append(response.text)\n            prompt_tokens = response.prompt_tokens\n            generation_tokens = response.generation_tokens\n            if response.finish_reason is not None:\n                finish_reason = response.finish_reason\n\n        full_text = \"\".join(text_parts)\n\n        return {\n            \"choices\": [\n                {\n                    \"message\": {\n                        \"role\": \"assistant\",\n                        \"content\": full_text,\n                    },\n                    \"finish_reason\": finish_reason or \"stop\",\n                },\n            ],\n            \"usage\": {\n                \"prompt_tokens\": prompt_tokens,\n                \"completion_tokens\": generation_tokens,\n            },\n        }\n\n    def chat_completion_stream(\n        self,\n        messages: list[dict],\n        tools: Optional[list[dict]] = None,\n        tool_choice: Optional[str] = None,\n        **kwargs: Any,\n    ) -> Iterator[dict]:\n        import mlx_lm\n\n        prompt = self._build_prompt(_normalize_messages(messages), tools=tools)\n\n        max_tokens = kwargs.pop(\"max_tokens\", self._max_tokens)\n        merged = {**self._kwargs, **kwargs}\n\n        sampler_kwargs = {}\n        for key in (\"temp\", \"temperature\", \"top_p\", \"min_p\", \"top_k\"):\n            if key in merged:\n                val = merged.pop(key)\n                sampler_key = \"temp\" if key == \"temperature\" else key\n                sampler_kwargs[sampler_key] = val\n\n        generate_kwargs: dict[str, Any] = {}\n        if sampler_kwargs:\n            from mlx_lm.sample_utils import make_sampler\n\n            generate_kwargs[\"sampler\"] = make_sampler(**sampler_kwargs)\n\n        for response in mlx_lm.stream_generate(\n            self._model,\n            self._tokenizer,\n            prompt=prompt,\n            max_tokens=max_tokens if max_tokens is not None else 2048,\n            **generate_kwargs,\n        ):\n            is_final = response.finish_reason is not None\n            chunk: dict[str, Any] = {\n                \"choices\": [\n                    {\n                        \"delta\": {\"content\": response.text},\n                        \"finish_reason\": response.finish_reason,\n                    },\n                ],\n            }\n            if is_final:\n                chunk[\"usage\"] = {\n                    \"prompt_tokens\": response.prompt_tokens,\n                    \"completion_tokens\": response.generation_tokens,\n                }\n            yield chunk\n\n    def unload(self) -> None:\n        if self._model is not None:\n            del self._model\n            del self._tokenizer\n            self._model = None\n            self._tokenizer = None\n            logger.info(\"MLX model unloaded: %s\", self._model_dir)\n\n    @property\n    def is_loaded(self) -> bool:\n        return self._model is not None\n"
  },
  {
    "path": "src/copaw/local_models/chat_model.py",
    "content": "# -*- coding: utf-8 -*-\n# pylint:disable=too-many-branches,too-many-statements\n\"\"\"LocalChatModel — ChatModelBase implementation for local backends.\"\"\"\n\nfrom __future__ import annotations\n\nimport asyncio\nimport json\nimport logging\nfrom datetime import datetime\nfrom typing import Any, AsyncGenerator, Literal, Optional, Type\n\nfrom pydantic import BaseModel\n\nfrom agentscope.model._model_base import ChatModelBase\nfrom agentscope.model._model_response import ChatResponse\nfrom agentscope.model._model_usage import ChatUsage\nfrom agentscope.message import TextBlock, ToolUseBlock, ThinkingBlock\n\nfrom .backends.base import LocalBackend\nfrom .tag_parser import (\n    extract_thinking_from_text,\n    parse_tool_calls_from_text,\n    text_contains_think_tag,\n    text_contains_tool_call_tag,\n)\n\nlogger = logging.getLogger(__name__)\n\n\ndef _json_loads_safe(s: str) -> dict:\n    \"\"\"Safely parse JSON string, returning empty dict on failure.\"\"\"\n    try:\n        return json.loads(s)\n    except (json.JSONDecodeError, TypeError):\n        return {}\n\n\nclass LocalChatModel(ChatModelBase):\n    \"\"\"ChatModelBase implementation for local model backends.\n\n    Wraps any ``LocalBackend`` (llama.cpp, future MLX) and presents it\n    through the agentscope ``ChatModelBase`` interface.  Since backends are\n    synchronous, inference runs in a thread executor for async compatibility.\n    \"\"\"\n\n    def __init__(\n        self,\n        model_name: str,\n        backend: LocalBackend,\n        stream: bool = True,\n        generate_kwargs: Optional[dict[str, Any]] = None,\n    ) -> None:\n        super().__init__(model_name, stream)\n        self._backend = backend\n        self._generate_kwargs = generate_kwargs or {}\n\n    async def __call__(\n        self,\n        messages: list[dict],\n        tools: list[dict] | None = None,\n        tool_choice: Literal[\"auto\", \"none\", \"required\"] | str | None = None,\n        structured_model: Type[BaseModel] | None = None,\n        **kwargs: Any,\n    ) -> ChatResponse | AsyncGenerator[ChatResponse, None]:\n        merged_kwargs = {**self._generate_kwargs, **kwargs}\n        start_datetime = datetime.now()\n\n        if self.stream and not structured_model:\n            return self._stream_response(\n                messages,\n                tools,\n                tool_choice,\n                start_datetime,\n                **merged_kwargs,\n            )\n\n        # Non-streaming or structured output: run in thread\n        loop = asyncio.get_running_loop()\n        response = await loop.run_in_executor(\n            None,\n            lambda: self._backend.chat_completion(\n                messages=messages,\n                tools=tools,\n                tool_choice=tool_choice,\n                structured_model=structured_model,\n                **merged_kwargs,\n            ),\n        )\n        return self._parse_completion_response(\n            response,\n            start_datetime,\n            structured_model,\n        )\n\n    async def _stream_response(\n        self,\n        messages: list[dict],\n        tools: list[dict] | None,\n        tool_choice: str | None,\n        start_datetime: datetime,\n        **kwargs: Any,\n    ) -> AsyncGenerator[ChatResponse, None]:\n        \"\"\"Wrap synchronous streaming iterator as async generator.\n\n        Uses a background thread to drive the synchronous iterator and\n        feeds chunks through an ``asyncio.Queue``.\n        \"\"\"\n        loop = asyncio.get_running_loop()\n        queue: asyncio.Queue = asyncio.Queue()\n        _SENTINEL = object()\n\n        def _produce() -> None:\n            try:\n                for chunk in self._backend.chat_completion_stream(\n                    messages=messages,\n                    tools=tools,\n                    tool_choice=tool_choice,\n                    **kwargs,\n                ):\n                    loop.call_soon_threadsafe(queue.put_nowait, chunk)\n            except Exception as exc:\n                loop.call_soon_threadsafe(queue.put_nowait, exc)\n            finally:\n                loop.call_soon_threadsafe(queue.put_nowait, _SENTINEL)\n\n        loop.run_in_executor(None, _produce)\n\n        accumulated_text = \"\"\n        accumulated_thinking = \"\"\n        tool_calls: dict[int, dict] = {}\n\n        while True:\n            item = await queue.get()\n            if item is _SENTINEL:\n                break\n            if isinstance(item, Exception):\n                raise item\n\n            chunk = item\n            choices = chunk.get(\"choices\", [])\n            if not choices:\n                continue\n\n            delta = choices[0].get(\"delta\", {})\n\n            # Accumulate text\n            content_piece = delta.get(\"content\") or \"\"\n            accumulated_text += content_piece\n\n            # Accumulate reasoning/thinking content\n            thinking_piece = delta.get(\"reasoning_content\") or \"\"\n            accumulated_thinking += thinking_piece\n\n            # Handle tool calls in delta\n            for tc in delta.get(\"tool_calls\") or []:\n                idx = tc.get(\"index\", 0)\n                if idx not in tool_calls:\n                    tool_calls[idx] = {\n                        \"id\": tc.get(\"id\", f\"call_{idx}\"),\n                        \"name\": (tc.get(\"function\") or {}).get(\"name\", \"\"),\n                        \"arguments\": \"\",\n                    }\n                tool_calls[idx][\"arguments\"] += (tc.get(\"function\") or {}).get(\n                    \"arguments\",\n                ) or \"\"\n\n            # Build content blocks\n            contents: list = []\n\n            # Determine effective thinking and display text.\n            # If the backend provides structured reasoning_content we use\n            # that; otherwise fall back to extracting  tags from\n            # the accumulated text.\n            effective_thinking = accumulated_thinking\n            effective_text = accumulated_text\n\n            if (\n                not effective_thinking\n                and effective_text\n                and text_contains_think_tag(effective_text)\n            ):\n                parsed_thinking = extract_thinking_from_text(effective_text)\n                effective_thinking = parsed_thinking.thinking\n                effective_text = parsed_thinking.remaining_text\n                # If  is still open, suppress all text output\n                # (thinking is still streaming).\n                if parsed_thinking.has_open_tag:\n                    effective_text = \"\"\n\n            if effective_thinking:\n                contents.append(\n                    ThinkingBlock(\n                        type=\"thinking\",\n                        thinking=effective_thinking,\n                    ),\n                )\n\n            # Fallback: parse  tags from effective text when\n            # the backend doesn't provide structured tool_calls.\n            if (\n                not tool_calls\n                and effective_text\n                and text_contains_tool_call_tag(effective_text)\n            ):\n                parsed = parse_tool_calls_from_text(effective_text)\n                display_text = parsed.text_before\n                if parsed.text_after:\n                    display_text = (\n                        f\"{display_text}\\n{parsed.text_after}\".strip()\n                        if display_text\n                        else parsed.text_after\n                    )\n                if display_text:\n                    contents.append(\n                        TextBlock(type=\"text\", text=display_text),\n                    )\n                for ptc in parsed.tool_calls:\n                    contents.append(\n                        ToolUseBlock(\n                            type=\"tool_use\",\n                            id=ptc.id,\n                            name=ptc.name,\n                            input=ptc.arguments,\n                            raw_input=ptc.raw_arguments,\n                        ),\n                    )\n            elif effective_text:\n                contents.append(\n                    TextBlock(type=\"text\", text=effective_text),\n                )\n\n            for tc_data in tool_calls.values():\n                contents.append(\n                    ToolUseBlock(\n                        type=\"tool_use\",\n                        id=tc_data[\"id\"],\n                        name=tc_data[\"name\"],\n                        input=_json_loads_safe(tc_data[\"arguments\"]),\n                        raw_input=tc_data[\"arguments\"],\n                    ),\n                )\n\n            usage_raw = chunk.get(\"usage\")\n            elapsed = (datetime.now() - start_datetime).total_seconds()\n            usage = (\n                ChatUsage(\n                    input_tokens=usage_raw.get(\"prompt_tokens\", 0),\n                    output_tokens=usage_raw.get(\"completion_tokens\", 0),\n                    time=elapsed,\n                )\n                if usage_raw\n                else None\n            )\n\n            if contents:\n                yield ChatResponse(content=contents, usage=usage)\n\n    def _parse_completion_response(\n        self,\n        response: dict,\n        start_datetime: datetime,\n        structured_model: Type[BaseModel] | None = None,\n    ) -> ChatResponse:\n        \"\"\"Parse a non-streaming response dict into ChatResponse.\"\"\"\n        content_blocks: list = []\n        metadata = None\n\n        choices = response.get(\"choices\", [])\n        if choices:\n            message = choices[0].get(\"message\", {})\n\n            # Reasoning/thinking content\n            thinking = message.get(\"reasoning_content\") or \"\"\n            text = message.get(\"content\") or \"\"\n\n            # Fallback: if backend didn't return structured\n            # reasoning_content but the text contains  tags,\n            # extract them.\n            if not thinking and text and text_contains_think_tag(text):\n                parsed_thinking = extract_thinking_from_text(text)\n                thinking = parsed_thinking.thinking\n                text = parsed_thinking.remaining_text\n\n            if thinking:\n                content_blocks.append(\n                    ThinkingBlock(type=\"thinking\", thinking=thinking),\n                )\n\n            # Tool calls\n            backend_tool_calls = message.get(\"tool_calls\") or []\n\n            # Fallback: if backend didn't return structured tool_calls but\n            # the text contains  tags, parse them from text.\n            if (\n                not backend_tool_calls\n                and text\n                and text_contains_tool_call_tag(text)\n            ):\n                parsed = parse_tool_calls_from_text(text)\n                clean_text = parsed.text_before\n                if parsed.text_after:\n                    clean_text = (\n                        f\"{clean_text}\\n{parsed.text_after}\".strip()\n                        if clean_text\n                        else parsed.text_after\n                    )\n                if clean_text:\n                    content_blocks.append(\n                        TextBlock(type=\"text\", text=clean_text),\n                    )\n                    if structured_model:\n                        metadata = _json_loads_safe(clean_text)\n                for tc in parsed.tool_calls:\n                    content_blocks.append(\n                        ToolUseBlock(\n                            type=\"tool_use\",\n                            id=tc.id,\n                            name=tc.name,\n                            input=tc.arguments,\n                            raw_input=tc.raw_arguments,\n                        ),\n                    )\n            else:\n                if text:\n                    content_blocks.append(\n                        TextBlock(type=\"text\", text=text),\n                    )\n                    if structured_model:\n                        metadata = _json_loads_safe(text)\n                for tc in backend_tool_calls:\n                    func = tc.get(\"function\", {})\n                    content_blocks.append(\n                        ToolUseBlock(\n                            type=\"tool_use\",\n                            id=tc.get(\"id\", \"\"),\n                            name=func.get(\"name\", \"\"),\n                            input=_json_loads_safe(\n                                func.get(\"arguments\", \"{}\"),\n                            ),\n                            raw_input=func.get(\"arguments\", \"\"),\n                        ),\n                    )\n\n        usage_raw = response.get(\"usage\")\n        elapsed = (datetime.now() - start_datetime).total_seconds()\n        usage = (\n            ChatUsage(\n                input_tokens=usage_raw.get(\"prompt_tokens\", 0),\n                output_tokens=usage_raw.get(\"completion_tokens\", 0),\n                time=elapsed,\n            )\n            if usage_raw\n            else None\n        )\n\n        return ChatResponse(\n            content=content_blocks,\n            usage=usage,\n            metadata=metadata,\n        )\n"
  },
  {
    "path": "src/copaw/local_models/factory.py",
    "content": "# -*- coding: utf-8 -*-\n\"\"\"Singleton factory for local model instances.\"\"\"\n\nfrom __future__ import annotations\n\nimport logging\nimport threading\nfrom typing import Any, Optional\n\nfrom .schema import BackendType, LocalModelInfo\nfrom .manager import get_local_model\nfrom .backends.base import LocalBackend\nfrom .chat_model import LocalChatModel\n\nlogger = logging.getLogger(__name__)\n\n_lock = threading.Lock()\n_active_backend: Optional[LocalBackend] = None\n_active_model_id: Optional[str] = None\n\n\ndef get_active_local_model() -> (\n    Optional[tuple[Optional[str], LocalBackend]] | None\n):\n    \"\"\"Return (model_id, backend) if a local model is currently loaded.\"\"\"\n    with _lock:\n        if _active_backend is not None and _active_backend.is_loaded:\n            return _active_model_id, _active_backend\n        return None\n\n\ndef unload_active_model() -> None:\n    \"\"\"Unload the currently loaded local model, freeing resources.\"\"\"\n    global _active_backend, _active_model_id\n    with _lock:\n        if _active_backend is not None:\n            _active_backend.unload()\n            _active_backend = None\n            _active_model_id = None\n\n\ndef create_local_chat_model(\n    model_id: str,\n    stream: bool = True,\n    backend_kwargs: Optional[dict[str, Any]] = None,\n    generate_kwargs: Optional[dict[str, Any]] = None,\n) -> LocalChatModel:\n    \"\"\"Create a LocalChatModel for the given model_id.\n\n    Uses singleton pattern: if the same model is already loaded, reuses it.\n    If a different model is loaded, unloads it first.\n\n    Args:\n        model_id: ID of a downloaded local model (from manifest).\n        stream: Whether to use streaming output.\n        backend_kwargs: Extra kwargs passed to the backend constructor\n                       (e.g., n_ctx, n_gpu_layers for llama.cpp).\n        generate_kwargs: Extra kwargs passed to every generate call\n                        (e.g., temperature, top_p).\n\n    Returns:\n        A LocalChatModel instance ready for use.\n\n    Raises:\n        ValueError: If model_id is not found in the manifest.\n        ImportError: If the required backend library is not installed.\n    \"\"\"\n    global _active_backend, _active_model_id\n\n    info = get_local_model(model_id)\n    if info is None:\n        raise ValueError(\n            f\"Local model '{model_id}' not found. \"\n            \"Download it first with 'copaw models download'.\",\n        )\n\n    with _lock:\n        # Reuse if same model already loaded\n        if (\n            _active_model_id == model_id\n            and _active_backend is not None\n            and _active_backend.is_loaded\n        ):\n            logger.debug(\"Reusing already-loaded model: %s\", model_id)\n            return LocalChatModel(\n                model_name=model_id,\n                backend=_active_backend,\n                stream=stream,\n                generate_kwargs=generate_kwargs,\n            )\n\n        # Unload previous model\n        if _active_backend is not None:\n            logger.info(\"Unloading previous model: %s\", _active_model_id)\n            _active_backend.unload()\n\n        # Load new model\n        backend = _create_backend(info, backend_kwargs or {})\n        _active_backend = backend\n        _active_model_id = model_id\n\n        return LocalChatModel(\n            model_name=model_id,\n            backend=_active_backend,\n            stream=stream,\n            generate_kwargs=generate_kwargs,\n        )\n\n\ndef _create_backend(\n    info: LocalModelInfo,\n    kwargs: dict[str, Any],\n) -> LocalBackend:\n    \"\"\"Instantiate the appropriate backend for a model.\"\"\"\n    if info.backend == BackendType.LLAMACPP:\n        from .backends.llamacpp_backend import LlamaCppBackend\n\n        return LlamaCppBackend(model_path=info.local_path, **kwargs)\n    elif info.backend == BackendType.MLX:\n        from .backends.mlx_backend import MlxBackend\n\n        return MlxBackend(model_path=info.local_path, **kwargs)\n    else:\n        raise ValueError(f\"Unknown backend: {info.backend}\")\n"
  },
  {
    "path": "src/copaw/local_models/manager.py",
    "content": "# -*- coding: utf-8 -*-\n\"\"\"Local model download, listing, and deletion.\"\"\"\n\nfrom __future__ import annotations\n\nimport json\nimport logging\nimport shutil\nfrom pathlib import Path\nfrom typing import Optional\n\nfrom ..constant import MODELS_DIR\nfrom .schema import (\n    BackendType,\n    DownloadSource,\n    LocalModelInfo,\n    LocalModelsManifest,\n)\n\nlogger = logging.getLogger(__name__)\n\nMANIFEST_PATH = MODELS_DIR / \"manifest.json\"\n\n\ndef _ensure_models_dir() -> Path:\n    MODELS_DIR.mkdir(parents=True, exist_ok=True)\n    return MODELS_DIR\n\n\ndef _load_manifest() -> LocalModelsManifest:\n    if MANIFEST_PATH.is_file():\n        try:\n            raw = json.loads(MANIFEST_PATH.read_text(encoding=\"utf-8\"))\n            return LocalModelsManifest.model_validate(raw)\n        except (json.JSONDecodeError, ValueError):\n            logger.warning(\"Corrupted manifest.json, starting fresh\")\n    return LocalModelsManifest()\n\n\ndef _save_manifest(manifest: LocalModelsManifest) -> None:\n    _ensure_models_dir()\n    MANIFEST_PATH.write_text(\n        json.dumps(\n            manifest.model_dump(mode=\"json\"),\n            indent=2,\n            ensure_ascii=False,\n        ),\n        encoding=\"utf-8\",\n    )\n\n\ndef list_local_models(\n    backend: Optional[BackendType] = None,\n) -> list[LocalModelInfo]:\n    \"\"\"Return all downloaded local models, optionally filtered by backend.\"\"\"\n    manifest = _load_manifest()\n    models = list(manifest.models.values())\n    if backend is not None:\n        models = [m for m in models if m.backend == backend]\n    return models\n\n\ndef get_local_model(model_id: str) -> Optional[LocalModelInfo]:\n    \"\"\"Look up a local model by ID.\"\"\"\n    manifest = _load_manifest()\n    return manifest.models.get(model_id)\n\n\ndef delete_local_model(model_id: str) -> None:\n    \"\"\"Delete a downloaded model file/directory and remove from manifest.\"\"\"\n    manifest = _load_manifest()\n    info = manifest.models.pop(model_id, None)\n    if info is None:\n        raise ValueError(f\"Local model '{model_id}' not found.\")\n    path = Path(info.local_path)\n    if path.is_dir():\n        shutil.rmtree(path, ignore_errors=True)\n        logger.info(\"Deleted model directory: %s\", path)\n    elif path.is_file():\n        path.unlink()\n        logger.info(\"Deleted model file: %s\", path)\n        # Clean up empty parent directories\n        parent = path.parent\n        if parent.is_dir() and not any(parent.iterdir()):\n            shutil.rmtree(parent, ignore_errors=True)\n    _save_manifest(manifest)\n\n\ndef _sanitize_repo_id(repo_id: str) -> str:\n    \"\"\"Convert repo_id to a safe directory name.\"\"\"\n    return repo_id.replace(\"/\", \"--\")\n\n\nclass LocalModelManager:\n    \"\"\"Handles downloading models from Hugging Face Hub or ModelScope.\"\"\"\n\n    @staticmethod\n    def download_model_sync(\n        repo_id: str,\n        filename: Optional[str] = None,\n        backend: BackendType = BackendType.LLAMACPP,\n        source: DownloadSource = DownloadSource.HUGGINGFACE,\n    ) -> LocalModelInfo:\n        \"\"\"Synchronous download (for CLI usage).\n\n        If filename is None, auto-selects the first GGUF file for llamacpp\n        backend (preferring Q4_K_M quantization).\n        \"\"\"\n        if source == DownloadSource.HUGGINGFACE:\n            return LocalModelManager._download_from_huggingface(\n                repo_id,\n                filename,\n                backend,\n            )\n        elif source == DownloadSource.MODELSCOPE:\n            return LocalModelManager._download_from_modelscope(\n                repo_id,\n                filename,\n                backend,\n            )\n        else:\n            raise ValueError(f\"Unknown download source: {source}\")\n\n    @staticmethod\n    def _download_from_huggingface(\n        repo_id: str,\n        filename: Optional[str],\n        backend: BackendType,\n    ) -> LocalModelInfo:\n        try:\n            from huggingface_hub import hf_hub_download, list_repo_files\n        except ImportError as e:\n            raise ImportError(\n                \"huggingface_hub is required for model downloads. \"\n                \"Install it with: pip install 'copaw[local]'\",\n            ) from e\n\n        _ensure_models_dir()\n        local_dir = MODELS_DIR / _sanitize_repo_id(repo_id)\n\n        # MLX models are directory-based — download entire repo\n        if backend == BackendType.MLX:\n            from huggingface_hub import snapshot_download\n\n            logger.info(\n                \"Downloading full repo %s from Hugging Face (MLX)...\",\n                repo_id,\n            )\n            snapshot_dir = snapshot_download(\n                repo_id=repo_id,\n                local_dir=str(local_dir),\n            )\n            LocalModelManager._validate_mlx_directory(Path(snapshot_dir))\n            return LocalModelManager._register_model(\n                repo_id,\n                filename or \"(full repo)\",\n                backend,\n                DownloadSource.HUGGINGFACE,\n                snapshot_dir,\n            )\n\n        if filename is None:\n            filename = LocalModelManager._auto_select_file(\n                list(list_repo_files(repo_id)),\n                backend,\n            )\n\n        logger.info(\n            \"Downloading %s/%s from Hugging Face...\",\n            repo_id,\n            filename,\n        )\n        downloaded_path = hf_hub_download(\n            repo_id=repo_id,\n            filename=filename,\n            local_dir=str(local_dir),\n        )\n\n        return LocalModelManager._register_model(\n            repo_id,\n            filename,\n            backend,\n            DownloadSource.HUGGINGFACE,\n            downloaded_path,\n        )\n\n    @staticmethod\n    def _download_from_modelscope(\n        repo_id: str,\n        filename: Optional[str],\n        backend: BackendType,\n    ) -> LocalModelInfo:\n        _ensure_models_dir()\n        local_dir = MODELS_DIR / _sanitize_repo_id(repo_id)\n\n        # MLX models require config/tokenizer files in addition to weights.\n        # ModelScope file download pulls only one file, so use full snapshot.\n        if backend == BackendType.MLX:\n            snapshot_download_fn = None\n            try:\n                from modelscope.hub.snapshot_download import (\n                    snapshot_download as _hub_snapshot_download,\n                )\n\n                snapshot_download_fn = _hub_snapshot_download\n            except ImportError:\n                try:\n                    # Compatibility fallback for old ModelScope versions.\n                    from modelscope import (\n                        snapshot_download as _legacy_snapshot_download,\n                    )\n\n                    snapshot_download_fn = _legacy_snapshot_download\n                except ImportError:\n                    snapshot_download_fn = None\n\n            if snapshot_download_fn is None:\n                raise ImportError(\n                    \"ModelScope snapshot download is required for MLX models. \"\n                    \"Install it with: pip install modelscope, \"\n                    \"or upgrade modelscope \"\n                    \"to a newer version if it is already installed.\",\n                )\n\n            logger.info(\n                \"Downloading full repo %s from ModelScope (MLX)...\",\n                repo_id,\n            )\n            local_dir_existed = local_dir.exists()\n            local_dir.mkdir(parents=True, exist_ok=True)\n            try:\n                snapshot_dir = snapshot_download_fn(\n                    model_id=repo_id,\n                    local_dir=str(local_dir),\n                )\n                LocalModelManager._validate_mlx_directory(Path(snapshot_dir))\n            except Exception:\n                if not local_dir_existed:\n                    shutil.rmtree(local_dir, ignore_errors=True)\n                raise\n            return LocalModelManager._register_model(\n                repo_id,\n                filename or \"(full repo)\",\n                backend,\n                DownloadSource.MODELSCOPE,\n                snapshot_dir,\n            )\n\n        try:\n            from modelscope.hub.file_download import model_file_download\n        except ImportError as e:\n            raise ImportError(\n                \"modelscope is required for ModelScope downloads. \"\n                \"Install it with: pip install modelscope\",\n            ) from e\n\n        if filename is None:\n            try:\n                from modelscope.hub.api import HubApi\n\n                api = HubApi()\n                files = [\n                    f[\"Path\"]\n                    for f in api.get_model_files(repo_id)\n                    if isinstance(f, dict) and \"Path\" in f\n                ]\n            except Exception as e:\n                raise ValueError(\n                    f\"Cannot list files for {repo_id} on ModelScope. \"\n                    \"Please specify the filename explicitly.\",\n                ) from e\n            filename = LocalModelManager._auto_select_file(files, backend)\n\n        local_dir.mkdir(parents=True, exist_ok=True)\n        logger.info(\n            \"Downloading %s/%s from ModelScope...\",\n            repo_id,\n            filename,\n        )\n        downloaded_path = model_file_download(\n            model_id=repo_id,\n            file_path=filename,\n            local_dir=str(local_dir),\n        )\n\n        return LocalModelManager._register_model(\n            repo_id,\n            filename,\n            backend,\n            DownloadSource.MODELSCOPE,\n            downloaded_path,\n        )\n\n    @staticmethod\n    def _auto_select_file(\n        files: list[str],\n        backend: BackendType,\n    ) -> str:\n        \"\"\"Auto-select a model file from the repo file list.\"\"\"\n        if backend == BackendType.LLAMACPP:\n            gguf_files = [f for f in files if f.endswith(\".gguf\")]\n            if not gguf_files:\n                raise ValueError(\n                    \"No .gguf files found in this repository. \"\n                    \"This repo may not provide GGUF-format models. \"\n                    \"Please specify the filename explicitly or choose \"\n                    \"a GGUF-compatible repository.\",\n                )\n            # Prefer Q4_K_M quantization as a sensible default\n            return next(\n                (f for f in gguf_files if \"Q4_K_M\" in f),\n                gguf_files[0],\n            )\n        elif backend == BackendType.MLX:\n            # MLX models are directory-based (safetensors + config).\n            # Auto-select a safetensors file so the whole repo gets pulled.\n            st_files = [f for f in files if f.endswith(\".safetensors\")]\n            if not st_files:\n                raise ValueError(\n                    \"No .safetensors files found in this repository. \"\n                    \"This repo may not be an MLX-compatible model. \"\n                    \"Please specify the filename explicitly or choose \"\n                    \"an MLX-compatible repository.\",\n                )\n            # Return the first safetensors file; the download function\n            # will pull it and register the model.\n            return st_files[0]\n        else:\n            raise ValueError(f\"Unknown backend: {backend}\")\n\n    @staticmethod\n    def _validate_mlx_directory(model_dir: Path) -> None:\n        \"\"\"Verify an MLX model directory has the minimum required files.\"\"\"\n        required = [\"config.json\"]\n        missing = [f for f in required if not (model_dir / f).is_file()]\n        if missing:\n            raise RuntimeError(\n                f\"MLX model download appears incomplete — missing files \"\n                f\"in {model_dir}: {', '.join(missing)}. \"\n                f\"The download may have been interrupted. \"\n                f\"Delete the directory and try again.\",\n            )\n        # Check for at least one safetensors file (not inside temp dirs)\n        st_files = [\n            f\n            for f in model_dir.rglob(\"*.safetensors\")\n            if f.is_file()\n            and not f.name.startswith(\".\")\n            and not any(\n                p.name.startswith(\".\")\n                for p in f.relative_to(model_dir).parents\n                if p != Path(\".\")\n            )\n        ]\n        if not st_files:\n            raise RuntimeError(\n                f\"MLX model download appears incomplete — no .safetensors \"\n                f\"files found in {model_dir}. \"\n                f\"The download may have been interrupted. \"\n                f\"Delete the directory and try again.\",\n            )\n\n    @staticmethod\n    def _register_model(\n        repo_id: str,\n        filename: str,\n        backend: BackendType,\n        source: DownloadSource,\n        downloaded_path: str,\n    ) -> LocalModelInfo:\n        \"\"\"Register a downloaded model in the manifest.\"\"\"\n        resolved_path = Path(downloaded_path).resolve()\n\n        # Directory-based models (MLX): compute total size of all files\n        # Exclude hidden/temp directories (e.g. ._____temp, .cache)\n        if resolved_path.is_dir():\n            file_size = sum(\n                f.stat().st_size\n                for f in resolved_path.rglob(\"*\")\n                if f.is_file()\n                and not any(\n                    p.name.startswith(\".\")\n                    for p in f.relative_to(resolved_path).parents\n                    if p != Path(\".\")\n                )\n            )\n            model_id = repo_id\n            repo_short = repo_id.split(\"/\")[-1] if \"/\" in repo_id else repo_id\n            display_name = repo_short\n        else:\n            file_size = resolved_path.stat().st_size\n            model_id = f\"{repo_id}/{filename}\"\n            repo_short = repo_id.split(\"/\")[-1] if \"/\" in repo_id else repo_id\n            display_name = f\"{repo_short} ({filename})\"\n\n        info = LocalModelInfo(\n            id=model_id,\n            repo_id=repo_id,\n            filename=filename,\n            backend=backend,\n            source=source,\n            file_size=file_size,\n            local_path=str(resolved_path),\n            display_name=display_name,\n        )\n\n        manifest = _load_manifest()\n        manifest.models[model_id] = info\n        _save_manifest(manifest)\n\n        logger.info(\"Registered local model: %s (%s)\", model_id, display_name)\n        return info\n"
  },
  {
    "path": "src/copaw/local_models/schema.py",
    "content": "# -*- coding: utf-8 -*-\n\"\"\"Data models for local model management.\"\"\"\n\nfrom __future__ import annotations\n\nfrom enum import Enum\nfrom typing import Optional\n\nfrom pydantic import BaseModel, Field\n\n\nclass BackendType(str, Enum):\n    LLAMACPP = \"llamacpp\"\n    MLX = \"mlx\"\n\n\nclass DownloadSource(str, Enum):\n    HUGGINGFACE = \"huggingface\"\n    MODELSCOPE = \"modelscope\"\n\n\nclass LocalModelInfo(BaseModel):\n    \"\"\"Metadata for a single downloaded local model.\"\"\"\n\n    id: str = Field(..., description=\"Unique ID: /\")\n    repo_id: str = Field(\n        ...,\n        description=\"Source repo, e.g. 'Qwen/Qwen3-8B-GGUF'\",\n    )\n    filename: str = Field(\n        ...,\n        description=\"Model file, e.g. 'mistral-7b-instruct-v0.2.Q4_K_M.gguf'\",\n    )\n    backend: BackendType\n    source: DownloadSource = DownloadSource.HUGGINGFACE\n    file_size: int = Field(default=0, description=\"File size in bytes\")\n    local_path: str = Field(\n        default=\"\",\n        description=\"Absolute path to model file on disk\",\n    )\n    display_name: str = Field(default=\"\", description=\"Human-friendly name\")\n\n\nclass DownloadProgress(BaseModel):\n    \"\"\"Progress event emitted during model download.\"\"\"\n\n    repo_id: str\n    filename: str\n    total_bytes: int = 0\n    downloaded_bytes: int = 0\n    status: str = \"downloading\"  # \"downloading\" | \"complete\" | \"error\"\n    error: Optional[str] = None\n\n\nclass LocalModelsManifest(BaseModel):\n    \"\"\"Persisted to ~/.copaw/models/manifest.json.\"\"\"\n\n    models: dict[str, LocalModelInfo] = Field(default_factory=dict)\n"
  },
  {
    "path": "src/copaw/local_models/tag_parser.py",
    "content": "# -*- coding: utf-8 -*-\n\"\"\"Parse special tags from model-generated text.\n\nHandles ``...`` (reasoning) and\n``...`` (function calling) tags that local models\nlike Qwen3-Instruct embed in their raw text output.\n\"\"\"\n\nfrom __future__ import annotations\n\nimport json\nimport logging\nimport re\nimport uuid\nfrom dataclasses import dataclass, field\n\nlogger = logging.getLogger(__name__)\n\n# ---------------------------------------------------------------------------\n# Constants\n# ---------------------------------------------------------------------------\n\nTHINK_START = \"\"\nTHINK_END = \"\"\n\nTOOL_CALL_START = \"\"\nTOOL_CALL_END = \"\"\n\n# Regex to find a complete ... block (non-greedy).\n_THINK_RE = re.compile(\n    r\"(.*?)\",\n    re.DOTALL,\n)\n\n# Regex to find complete ... blocks (non-greedy).\n_TOOL_CALL_RE = re.compile(\n    r\"\\s*(.*?)\\s*\",\n    re.DOTALL,\n)\n\n# ---------------------------------------------------------------------------\n# Data classes\n# ---------------------------------------------------------------------------\n\n\n@dataclass\nclass TextWithThinking:\n    \"\"\"Result of extracting ```` tags from text.\"\"\"\n\n    # The thinking/reasoning content (between the tags).\n    thinking: str = \"\"\n    # The remaining text after removing the ``...`` block.\n    remaining_text: str = \"\"\n    # True when ```` has been opened but ```` not yet seen\n    # (streaming scenario).\n    has_open_tag: bool = False\n\n\n@dataclass\nclass ParsedToolCall:\n    \"\"\"A single parsed tool call extracted from text.\"\"\"\n\n    id: str\n    name: str\n    arguments: dict\n    raw_arguments: str\n\n\n@dataclass\nclass TextWithToolCalls:\n    \"\"\"Result of parsing text that may contain tool-call tags.\"\"\"\n\n    # Text content before the first  tag.\n    text_before: str = \"\"\n    # Text content after the last  tag.\n    text_after: str = \"\"\n    # Successfully parsed tool calls.\n    tool_calls: list[ParsedToolCall] = field(default_factory=list)\n    # True when an opening  has no matching  yet\n    # (streaming scenario).\n    has_open_tag: bool = False\n    # Raw text accumulated after the unclosed  tag.\n    partial_tool_text: str = \"\"\n\n\n# ---------------------------------------------------------------------------\n# Helpers\n# ---------------------------------------------------------------------------\n\n\ndef _generate_call_id() -> str:\n    return f\"call_{uuid.uuid4().hex[:12]}\"\n\n\ndef _parse_single_tool_call(raw_text: str) -> ParsedToolCall | None:\n    \"\"\"\n    Parse the JSON content between a ```` / ```` pair.\n\n    Expected format::\n\n        {\"name\": \"func_name\", \"arguments\": {\"key\": \"value\"}}\n    \"\"\"\n    try:\n        data = json.loads(raw_text.strip())\n    except (json.JSONDecodeError, TypeError):\n        logger.warning(\"Failed to parse tool call JSON: %s\", raw_text[:200])\n        return None\n\n    name = data.get(\"name\", \"\")\n    if not name:\n        logger.warning(\"Tool call missing 'name' field: %s\", raw_text[:200])\n        return None\n\n    arguments = data.get(\"arguments\", {})\n    if isinstance(arguments, str):\n        try:\n            arguments = json.loads(arguments)\n        except (json.JSONDecodeError, TypeError):\n            arguments = {}\n\n    return ParsedToolCall(\n        id=_generate_call_id(),\n        name=name,\n        arguments=arguments,\n        raw_arguments=json.dumps(arguments, ensure_ascii=False),\n    )\n\n\n# ---------------------------------------------------------------------------\n# Public API\n# ---------------------------------------------------------------------------\n\n\ndef text_contains_think_tag(text: str) -> bool:\n    \"\"\"Fast substring check for a ```` tag.\"\"\"\n    return THINK_START in text\n\n\ndef extract_thinking_from_text(text: str) -> TextWithThinking:\n    \"\"\"Extract ``...`` content from *text*.\n\n    Returns a :class:`TextWithThinking` with:\n\n    * ``thinking``       – the reasoning content (empty if none found)\n    * ``remaining_text`` – everything outside the think tags\n    * ``has_open_tag``   – ``True`` if ```` opened but not closed yet\n    \"\"\"\n    match = _THINK_RE.search(text)\n    if match:\n        thinking = match.group(1).strip()\n        remaining = (text[: match.start()] + text[match.end() :]).strip()\n        return TextWithThinking(\n            thinking=thinking,\n            remaining_text=remaining,\n        )\n\n    # No complete block — check for an unclosed .\n    open_idx = text.find(THINK_START)\n    if open_idx != -1:\n        remaining = text[:open_idx].strip()\n        partial = text[open_idx + len(THINK_START) :]\n        return TextWithThinking(\n            thinking=partial.strip(),\n            remaining_text=remaining,\n            has_open_tag=True,\n        )\n\n    return TextWithThinking(remaining_text=text)\n\n\ndef text_contains_tool_call_tag(text: str) -> bool:\n    \"\"\"Fast substring check for a ```` tag.\"\"\"\n    return TOOL_CALL_START in text\n\n\ndef parse_tool_calls_from_text(text: str) -> TextWithToolCalls:\n    \"\"\"Extract all ``...`` blocks from *text*.\n\n    Returns a :class:`TextWithToolCalls` with:\n\n    * ``text_before`` – all text before the first ```` tag\n    * ``text_after``  – all text after the last ```` tag\n    * ``tool_calls``  – successfully parsed tool calls\n    * ``has_open_tag`` – whether there is an unclosed ````\n        (streaming)\n    * ``partial_tool_text`` – content after the unclosed tag\n    \"\"\"\n    matches = list(_TOOL_CALL_RE.finditer(text))\n\n    if not matches:\n        # No complete blocks.  Check for an unclosed opening tag.\n        open_idx = text.rfind(TOOL_CALL_START)\n        if open_idx != -1:\n            return TextWithToolCalls(\n                text_before=text[:open_idx].rstrip(),\n                has_open_tag=True,\n                partial_tool_text=text[open_idx + len(TOOL_CALL_START) :],\n            )\n        return TextWithToolCalls(text_before=text)\n\n    # --- Text before the first match ---\n    text_before = text[: matches[0].start()].rstrip()\n\n    # --- Text after the last match ---\n    remaining = text[matches[-1].end() :]\n    open_idx = remaining.find(TOOL_CALL_START)\n    if open_idx != -1:\n        text_after = remaining[:open_idx].strip()\n        has_open_tag = True\n        partial_tool_text = remaining[open_idx + len(TOOL_CALL_START) :]\n    else:\n        text_after = remaining.strip()\n        has_open_tag = False\n        partial_tool_text = \"\"\n\n    # --- Parse each complete block ---\n    tool_calls: list[ParsedToolCall] = []\n    for match in matches:\n        parsed = _parse_single_tool_call(match.group(1))\n        if parsed is not None:\n            tool_calls.append(parsed)\n\n    return TextWithToolCalls(\n        text_before=text_before,\n        text_after=text_after,\n        tool_calls=tool_calls,\n        has_open_tag=has_open_tag,\n        partial_tool_text=partial_tool_text,\n    )\n"
  },
  {
    "path": "src/copaw/providers/__init__.py",
    "content": "# -*- coding: utf-8 -*-\n\"\"\"Provider management — models, registry + persistent store.\"\"\"\n\nfrom .models import (\n    CustomProviderData,\n    ProviderDefinition,\n    ProviderSettings,\n)\nfrom .provider import Provider, ProviderInfo, ModelInfo\nfrom .provider_manager import ProviderManager, ActiveModelsInfo\n\n__all__ = [\n    \"ActiveModelsInfo\",\n    \"CustomProviderData\",\n    \"ModelInfo\",\n    \"ProviderDefinition\",\n    \"ProviderInfo\",\n    \"ProviderSettings\",\n    \"Provider\",\n    \"ProviderManager\",\n    \"ModelInfo\",\n    \"ProviderInfo\",\n]\n"
  },
  {
    "path": "src/copaw/providers/anthropic_provider.py",
    "content": "# -*- coding: utf-8 -*-\n\"\"\"An Anthropic provider implementation.\"\"\"\n\nfrom __future__ import annotations\n\nimport json\nfrom typing import Any, List\n\nfrom agentscope.model import ChatModelBase\nimport anthropic\n\nfrom copaw.providers.provider import ModelInfo, Provider\n\nDASHSCOPE_BASE_URL = \"https://dashscope.aliyuncs.com/compatible-mode/v1\"\nCODING_DASHSCOPE_BASE_URL = \"https://coding.dashscope.aliyuncs.com/v1\"\n\n\nclass AnthropicProvider(Provider):\n    \"\"\"Provider implementation for Anthropic API.\"\"\"\n\n    def _client(self, timeout: float = 5) -> anthropic.AsyncAnthropic:\n        return anthropic.AsyncAnthropic(\n            api_key=self.api_key,\n            base_url=self.base_url,\n            timeout=timeout,\n        )\n\n    @staticmethod\n    def _normalize_models_payload(payload: Any) -> List[ModelInfo]:\n        if isinstance(payload, dict):\n            rows = payload.get(\"data\", [])\n        else:\n            rows = getattr(payload, \"data\", payload)\n\n        models: List[ModelInfo] = []\n        for row in rows or []:\n            model_id = str(\n                getattr(row, \"id\", \"\") or \"\",\n            ).strip()\n            model_name = str(\n                getattr(row, \"display_name\", \"\") or model_id,\n            ).strip()\n\n            if not model_id:\n                continue\n            models.append(ModelInfo(id=model_id, name=model_name))\n\n        deduped: List[ModelInfo] = []\n        seen: set[str] = set()\n        for model in models:\n            if model.id in seen:\n                continue\n            seen.add(model.id)\n            deduped.append(model)\n        return deduped\n\n    async def check_connection(self, timeout: float = 5) -> tuple[bool, str]:\n        \"\"\"Check if Anthropic provider is reachable.\"\"\"\n        try:\n            client = self._client(timeout=timeout)\n            await client.models.list()\n            return True, \"\"\n        except anthropic.APIError:\n            return False, \"Anthropic API error\"\n        except Exception:\n            return (\n                False,\n                f\"Unknown exception when connecting to `{self.base_url}`\",\n            )\n\n    async def fetch_models(self, timeout: float = 5) -> List[ModelInfo]:\n        \"\"\"Fetch available models.\"\"\"\n        client = self._client(timeout=timeout)\n        payload = await client.models.list()\n        models = self._normalize_models_payload(payload)\n        return models\n\n    async def check_model_connection(\n        self,\n        model_id: str,\n        timeout: float = 5,\n    ) -> tuple[bool, str]:\n        \"\"\"Check if a specific model is reachable/usable.\"\"\"\n        target = (model_id or \"\").strip()\n        if not target:\n            return False, \"Empty model ID\"\n\n        body = {\n            \"model\": target,\n            \"max_tokens\": 1,\n            \"messages\": [\n                {\n                    \"role\": \"user\",\n                    \"content\": [\n                        {\n                            \"type\": \"text\",\n                            \"text\": \"ping\",\n                        },\n                    ],\n                },\n            ],\n            \"stream\": True,\n        }\n        try:\n            client = self._client(timeout=timeout)\n            resp = await client.messages.create(**body)\n            # consume the stream to ensure the model is actually responsive\n            async for _ in resp:\n                break\n            return True, \"\"\n        except anthropic.APIError:\n            return False, f\"Model '{model_id}' is not reachable or usable\"\n        except Exception:\n            return (\n                False,\n                f\"Unknown exception when connecting to model '{model_id}'\",\n            )\n\n    def get_chat_model_instance(self, model_id: str) -> ChatModelBase:\n        from agentscope.model import AnthropicChatModel\n\n        client_kwargs = {\"base_url\": self.base_url}\n        if self.base_url == DASHSCOPE_BASE_URL:\n            client_kwargs[\"default_headers\"] = {\n                \"x-dashscope-agentapp\": json.dumps(\n                    {\n                        \"agentType\": \"CoPaw\",\n                        \"deployType\": \"UnKnown\",\n                        \"moduleCode\": \"model\",\n                        \"agentCode\": \"UnKnown\",\n                    },\n                    ensure_ascii=False,\n                ),\n            }\n        elif self.base_url == CODING_DASHSCOPE_BASE_URL:\n            client_kwargs[\"default_headers\"] = {\n                \"X-DashScope-Cdpl\": json.dumps(\n                    {\n                        \"agentType\": \"CoPaw\",\n                        \"deployType\": \"UnKnown\",\n                        \"moduleCode\": \"model\",\n                        \"agentCode\": \"UnKnown\",\n                    },\n                    ensure_ascii=False,\n                ),\n            }\n\n        return AnthropicChatModel(\n            model_name=model_id,\n            stream=True,\n            api_key=self.api_key,\n            stream_tool_parsing=False,\n            client_kwargs=client_kwargs,\n            generate_kwargs=self.generate_kwargs,\n        )\n"
  },
  {
    "path": "src/copaw/providers/gemini_provider.py",
    "content": "# -*- coding: utf-8 -*-\n\"\"\"A Google Gemini provider implementation using AgentScope's native\nGeminiChatModel.\"\"\"\n\nfrom __future__ import annotations\n\nfrom typing import Any, List\n\nfrom agentscope.model import ChatModelBase\nfrom google import genai\nfrom google.genai import errors as genai_errors\nfrom google.genai import types as genai_types\n\nfrom copaw.providers.provider import ModelInfo, Provider\n\n\nclass GeminiProvider(Provider):\n    \"\"\"Provider implementation for Google Gemini API.\"\"\"\n\n    def _client(self, timeout: float = 10) -> Any:\n        return genai.Client(\n            api_key=self.api_key,\n            http_options=genai_types.HttpOptions(timeout=int(timeout * 1000)),\n        )\n\n    @staticmethod\n    def _normalize_models_payload(payload: Any) -> List[ModelInfo]:\n        models: List[ModelInfo] = []\n        for row in payload or []:\n            model_id = str(getattr(row, \"name\", \"\") or \"\").strip()\n\n            if not model_id:\n                continue\n\n            # Gemini API returns model names like \"models/gemini-2.5-flash\"\n            # Strip the \"models/\" prefix for cleaner IDs\n            if model_id.startswith(\"models/\"):\n                model_id = model_id[len(\"models/\") :]\n\n            display_name = str(\n                getattr(row, \"display_name\", \"\") or model_id,\n            ).strip()\n\n            if not display_name or display_name.startswith(\"models/\"):\n                display_name = model_id\n\n            models.append(ModelInfo(id=model_id, name=display_name))\n\n        deduped: List[ModelInfo] = []\n        seen: set[str] = set()\n        for model in models:\n            if model.id in seen:\n                continue\n            seen.add(model.id)\n            deduped.append(model)\n        return deduped\n\n    async def check_connection(self, timeout: float = 10) -> tuple[bool, str]:\n        \"\"\"Check if Google Gemini provider is reachable.\"\"\"\n        try:\n            client = self._client(timeout=timeout)\n            # Use the async list models endpoint to verify connectivity\n            async for _ in await client.aio.models.list():\n                break\n            return True, \"\"\n        except genai_errors.APIError:\n            return (\n                False,\n                \"Failed to connect to Google Gemini API. \"\n                \"Check your API key.\",\n            )\n        except Exception:\n            return (\n                False,\n                \"Unknown exception when connecting to Google Gemini API.\",\n            )\n\n    async def fetch_models(self, timeout: float = 10) -> List[ModelInfo]:\n        \"\"\"Fetch available models from Gemini API.\"\"\"\n        try:\n            client = self._client(timeout=timeout)\n            payload = []\n            async for model in await client.aio.models.list():\n                payload.append(model)\n            models = self._normalize_models_payload(payload)\n            return models\n        except genai_errors.APIError:\n            return []\n        except Exception:\n            return []\n\n    async def check_model_connection(\n        self,\n        model_id: str,\n        timeout: float = 10,\n    ) -> tuple[bool, str]:\n        \"\"\"Check if a specific Gemini model is reachable/usable.\"\"\"\n        target = (model_id or \"\").strip()\n        if not target:\n            return False, \"Empty model ID\"\n\n        try:\n            client = self._client(timeout=timeout)\n            response = await client.aio.models.generate_content_stream(\n                model=target,\n                contents=\"ping\",\n            )\n            async for _ in response:\n                break\n            return True, \"\"\n        except genai_errors.APIError:\n            return (\n                False,\n                f\"Model '{model_id}' is not reachable or usable\",\n            )\n        except Exception:\n            return (\n                False,\n                f\"Unknown exception when connecting to model '{model_id}'\",\n            )\n\n    def get_chat_model_instance(self, model_id: str) -> ChatModelBase:\n        from agentscope.model import GeminiChatModel\n\n        return GeminiChatModel(\n            model_name=model_id,\n            stream=True,\n            api_key=self.api_key,\n            generate_kwargs=self.generate_kwargs,\n        )\n"
  },
  {
    "path": "src/copaw/providers/models.py",
    "content": "# -*- coding: utf-8 -*-\n\"\"\"Pydantic data models for providers and models.\"\"\"\n\nfrom __future__ import annotations\n\nfrom typing import List\n\nfrom pydantic import BaseModel, Field\n\n\nclass ModelInfo(BaseModel):\n    id: str = Field(..., description=\"Model identifier used in API calls\")\n    name: str = Field(..., description=\"Human-readable model name\")\n\n\nclass ProviderDefinition(BaseModel):\n    \"\"\"Static definition of a provider (built-in or custom).\"\"\"\n\n    id: str = Field(..., description=\"Provider identifier\")\n    name: str = Field(..., description=\"Human-readable provider name\")\n    default_base_url: str = Field(\n        default=\"\",\n        description=\"Default API base URL\",\n    )\n    api_key_prefix: str = Field(\n        default=\"\",\n        description=\"Expected prefix for the API key\",\n    )\n    models: List[ModelInfo] = Field(\n        default_factory=list,\n        description=\"Built-in LLM model list\",\n    )\n    is_custom: bool = Field(default=False)\n    is_local: bool = Field(default=False)\n    chat_model: str = Field(\n        default=\"OpenAIChatModel\",\n        description=\"Chat model class name (e.g., 'OpenAIChatModel')\",\n    )\n\n\nclass ProviderSettings(BaseModel):\n    \"\"\"Per-provider settings stored in providers.json (built-in only).\"\"\"\n\n    base_url: str = Field(default=\"\")\n    api_key: str = Field(default=\"\")\n    extra_models: List[ModelInfo] = Field(default_factory=list)\n    chat_model: str = Field(\n        default=\"\",\n        description=\"Chat model class name (e.g., 'OpenAIChatModel'). \"\n        \"If empty, uses ProviderDefinition default.\",\n    )\n\n\nclass CustomProviderData(BaseModel):\n    \"\"\"Persisted definition + runtime config of a user-created custom provider.\n\n    All configuration lives here; custom providers do NOT have a\n    corresponding entry in the ``providers`` dict.\n    \"\"\"\n\n    id: str = Field(..., description=\"Provider identifier (unique)\")\n    name: str = Field(..., description=\"Human-readable provider name\")\n    default_base_url: str = Field(default=\"\")\n    api_key_prefix: str = Field(default=\"\")\n    models: List[ModelInfo] = Field(default_factory=list)\n    base_url: str = Field(default=\"\")\n    api_key: str = Field(default=\"\")\n    chat_model: str = Field(\n        default=\"OpenAIChatModel\",\n        description=\"Chat model class name (e.g., 'OpenAIChatModel')\",\n    )\n\n\nclass ModelSlotConfig(BaseModel):\n    provider_id: str = Field(default=\"\")\n    model: str = Field(default=\"\")\n\n\nclass ActiveModelsInfo(BaseModel):\n    active_llm: ModelSlotConfig | None\n"
  },
  {
    "path": "src/copaw/providers/ollama_manager.py",
    "content": "# -*- coding: utf-8 -*-\n\"\"\"Ollama model management using the Ollama Python SDK.\n\nThis module mirrors the structure of local_models.manager, but delegates all\nlifecycle operations to the running Ollama daemon instead of managing files\nor a manifest.json. Ollama remains the single source of truth for its models.\n\"\"\"\n\nfrom __future__ import annotations\n\nimport logging\nfrom datetime import datetime\nfrom typing import List, Optional, Union\n\nfrom pydantic import BaseModel, Field, field_validator\nfrom ..constant import MODEL_PROVIDER_CHECK_TIMEOUT\n\nlogger = logging.getLogger(__name__)\n\n\nclass OllamaModelInfo(BaseModel):\n    \"\"\"Metadata for a single Ollama model returned by ``ollama.list()``.\"\"\"\n\n    name: str = Field(..., description=\"Model name, e.g. 'llama3:8b'\")\n    size: int = Field(0, description=\"Approximate size in bytes (if provided)\")\n    digest: Optional[str] = Field(default=None, description=\"Model digest/id\")\n    modified_at: Optional[str] = Field(\n        default=None,\n        description=\"Last modified time string (from Ollama, if present)\",\n    )\n\n    @field_validator(\"modified_at\", mode=\"before\")\n    @classmethod\n    def convert_datetime_to_str(\n        cls,\n        v: Union[str, datetime, None],\n    ) -> Optional[str]:\n        \"\"\"Convert datetime objects to ISO format strings.\"\"\"\n        if v is None:\n            return None\n        if isinstance(v, datetime):\n            return v.isoformat()\n        return str(v)\n\n\ndef _ensure_ollama():\n    \"\"\"Import the ollama SDK with a helpful error message on failure.\"\"\"\n\n    try:\n        import ollama  # type: ignore[import]\n    except ImportError as e:  # pragma: no cover - import guard\n        raise ImportError(\n            \"The 'ollama' Python package is required. You may have \"\n            \"installed Ollama via their CLI or desktop app, but you \"\n            \"also need the Python SDK to manage models from CoPaw. \"\n            \"Please install it with: pip install 'copaw[ollama]'\",\n        ) from e\n    return ollama\n\n\ndef _base_url_to_host(base_url: str) -> Optional[str]:\n    \"\"\"Convert an OpenAI-compat ``base_url`` (with ``/v1``) to an Ollama host.\n\n    The providers.json stores ``http://host:port/v1`` for OpenAI compatibility,\n    but the native Ollama SDK expects ``http://host:port``.\n    \"\"\"\n    if not base_url:\n        return None\n    url = base_url.rstrip(\"/\")\n    if url.endswith(\"/v1\"):\n        url = url[:-3]\n    return url or None\n\n\nclass OllamaModelManager:\n    \"\"\"High-level wrapper around the Ollama SDK for model lifecycle.\n\n    All operations delegate to the Ollama daemon; this module does not manage\n    files or persist a manifest. It is safe to call these methods from\n    background tasks and CLIs.\n\n    Every method accepts an optional *host* parameter (e.g.\n    ``http://remote:11434``) that overrides the SDK default.\n    \"\"\"\n\n    @staticmethod\n    def _make_client(host: Optional[str] = None):\n        \"\"\"Create an Ollama SDK client, optionally targeting a custom host.\"\"\"\n        ollama = _ensure_ollama()\n        kwargs: dict = {\"timeout\": MODEL_PROVIDER_CHECK_TIMEOUT}\n        if host:\n            kwargs[\"host\"] = host\n        return ollama.Client(**kwargs)\n\n    @staticmethod\n    def list_models(host: Optional[str] = None) -> List[OllamaModelInfo]:\n        \"\"\"Return the current model list from ``ollama.list()``.\"\"\"\n\n        raw = OllamaModelManager._make_client(host).list()\n        models: List[OllamaModelInfo] = []\n        for m in raw.get(\"models\", []):\n            models.append(\n                OllamaModelInfo(\n                    name=m.get(\"model\", \"\"),\n                    size=m.get(\"size\", 0) or 0,\n                    digest=m.get(\"digest\"),\n                    modified_at=m.get(\"modified_at\"),\n                ),\n            )\n        return models\n\n    @staticmethod\n    def pull_model(\n        name: str,\n        host: Optional[str] = None,\n    ) -> OllamaModelInfo:\n        \"\"\"Pull/download a model via ``ollama.pull``.\n\n        This call is blocking and intended to be run in a thread executor when\n        used from async FastAPI endpoints.\n        \"\"\"\n\n        logger.info(\"Pulling Ollama model: %s\", name)\n        OllamaModelManager._make_client(host).pull(name)\n        logger.info(\"Pull completed: %s\", name)\n\n        for model in OllamaModelManager.list_models(host=host):\n            if model.name == name:\n                return model\n\n        raise ValueError(f\"Ollama model '{name}' not found after pull.\")\n\n    @staticmethod\n    def delete_model(name: str, host: Optional[str] = None) -> None:\n        \"\"\"Delete a model from the local Ollama instance.\"\"\"\n\n        logger.info(\"Deleting Ollama model: %s\", name)\n        OllamaModelManager._make_client(host).delete(name)\n        logger.info(\"Ollama model deleted: %s\", name)\n"
  },
  {
    "path": "src/copaw/providers/ollama_provider.py",
    "content": "# -*- coding: utf-8 -*-\n\"\"\"An OpenAI provider implementation.\"\"\"\n\nfrom __future__ import annotations\n\nimport os\nfrom typing import Any, List\n\ntry:\n    import ollama\nexcept ImportError:\n    ollama = None  # type: ignore\n\nfrom agentscope.model import ChatModelBase\n\nfrom copaw.providers.provider import ModelInfo, Provider\n\n\nclass OllamaProvider(Provider):\n    \"\"\"Provider implementation for Ollama local LLM hosting platform.\"\"\"\n\n    def model_post_init(self, __context: Any) -> None:\n        if not self.base_url:  # type: ignore\n            self.base_url = (\n                os.environ.get(\"OLLAMA_HOST\") or \"http://127.0.0.1:11434\"\n            )\n        if self.base_url.endswith(\"/v1\"):\n            # For backwards compatibility, if the URL ends with /v1,\n            # we strip it to get the base URL\n            self.base_url = self.base_url[:-3]\n\n    def _client(self, timeout: float = 5):\n        if ollama is None:\n            raise ImportError(\n                \"The 'ollama' Python package is required. You may have \"\n                \"installed Ollama via their CLI or desktop app, but you \"\n                \"also need the Python SDK to manage models from CoPaw. \"\n                \"Please install it with: pip install 'copaw[ollama]'\",\n            )\n        return ollama.AsyncClient(host=self.base_url, timeout=timeout)\n\n    @staticmethod\n    def _normalize_models_payload(payload: Any) -> List[ModelInfo]:\n        rows = payload.get(\"models\", [])\n        models: List[ModelInfo] = []\n        for row in rows or []:\n            model_id = str(\n                getattr(row, \"model\", \"\"),\n            ).strip()\n            model_name = model_id\n            if not model_id:\n                continue\n            models.append(\n                ModelInfo(\n                    id=model_id,\n                    name=model_name,\n                ),\n            )\n\n        deduped: List[ModelInfo] = []\n        seen: set[str] = set()\n        for model in models:\n            if model.id in seen:\n                continue\n            seen.add(model.id)\n            deduped.append(model)\n        return deduped\n\n    async def check_connection(self, timeout: float = 5) -> tuple[bool, str]:\n        \"\"\"Check if Ollama provider is reachable with current configuration.\"\"\"\n        try:\n            client = self._client(timeout=timeout)\n            await client.list()\n            return True, \"\"\n        except ImportError:\n            return False, \"Ollama Python SDK is not installed\"\n        except ConnectionError:\n            return False, f\"Failed to connect to Ollama at `{self.base_url}`\"\n        except Exception as exc:\n            return (\n                False,\n                f\"Failed to connect to Ollama at `{self.base_url}`: {exc}\",\n            )\n\n    async def fetch_models(self, timeout: float = 5) -> List[ModelInfo]:\n        \"\"\"Fetch available models and cache them on this provider instance.\"\"\"\n        try:\n            client = self._client(timeout=timeout)\n            payload = await client.list()\n            models = self._normalize_models_payload(payload)\n            return models\n        except (ImportError, ConnectionError, OSError, RuntimeError):\n            return []\n\n    async def check_model_connection(\n        self,\n        model_id: str,\n        timeout: float = 10,\n    ) -> tuple[bool, str]:\n        \"\"\"Check if a specific model is reachable/usable.\"\"\"\n        target = (model_id or \"\").strip()\n        if not target:\n            return False, \"Empty model ID\"\n        try:\n            client = self._client(timeout=timeout)\n            await client.chat(\n                model=target,\n                messages=[{\"role\": \"user\", \"content\": \"ping\"}],\n                options={\"num_predict\": 1},\n            )\n            return True, \"\"\n        except ImportError:\n            return False, \"Ollama Python SDK is not installed\"\n        except ConnectionError:\n            return False, f\"Failed to connect to Ollama at `{self.base_url}`\"\n        except Exception as exc:\n            return False, f\"Model connection failed for `{target}`: {exc}\"\n\n    async def add_model(\n        self,\n        model_info: ModelInfo,\n        target: str = \"models\",\n        timeout: float = 36000,\n    ) -> tuple[bool, str]:\n        \"\"\"Ollama models are added by pulling from a registry, so here we\n        interpret \"adding\" a model as pulling it from the registry.\n        The model_info.id is expected to be in the format of\n        \"registry/model:tag\" or \"registry/model\".\n        \"\"\"\n        if model_info.id in {\n            model.id for model in self.extra_models  # type: ignore [has-type]\n        }:\n            return False, f\"Model '{model_info.id}' already exists\"\n        client = self._client(timeout=timeout)\n        try:\n            await client.pull(model=model_info.id)\n        except ImportError:\n            return False, \"Ollama Python SDK is not installed\"\n        except ConnectionError:\n            return False, f\"Failed to connect to Ollama at `{self.base_url}`\"\n        except Exception:\n            return False, f\"Failed to pull model '{model_info.id}'\"\n        self.extra_models = await self.fetch_models()\n        return True, \"\"\n\n    async def delete_model(\n        self,\n        model_id: str,\n        timeout: float = 60,\n    ) -> tuple[bool, str]:\n        client = self._client(timeout=timeout)\n        try:\n            await client.delete(model=model_id)\n        except ImportError:\n            return False, \"Ollama Python SDK is not installed\"\n        except ConnectionError:\n            return False, f\"Failed to connect to Ollama at `{self.base_url}`\"\n        except Exception:\n            return False, f\"Failed to delete model '{model_id}'\"\n        self.extra_models = await self.fetch_models()\n        return True, \"\"\n\n    def get_chat_model_instance(self, model_id: str) -> ChatModelBase:\n        from .openai_chat_model_compat import OpenAIChatModelCompat\n\n        if self.base_url.endswith(\"/\"):\n            openai_compatible_url = self.base_url[:-1] + \"/v1\"\n        else:\n            openai_compatible_url = self.base_url + \"/v1\"\n\n        return OpenAIChatModelCompat(\n            model_name=model_id,\n            stream=True,\n            api_key=self.api_key,\n            stream_tool_parsing=False,\n            client_kwargs={\"base_url\": openai_compatible_url},\n            generate_kwargs=self.generate_kwargs,\n        )\n"
  },
  {
    "path": "src/copaw/providers/openai_chat_model_compat.py",
    "content": "# -*- coding: utf-8 -*-\n\"\"\"OpenAI chat model compatibility wrappers.\"\"\"\n\nfrom __future__ import annotations\n\nimport json\nfrom datetime import datetime\nfrom types import SimpleNamespace\nfrom typing import Any, AsyncGenerator, Type\n\nfrom agentscope.model import OpenAIChatModel\nfrom agentscope.model._model_response import ChatResponse\nfrom pydantic import BaseModel\n\n\ndef _clone_with_overrides(obj: Any, **overrides: Any) -> Any:\n    \"\"\"Clone a stream object into a mutable namespace with overrides.\"\"\"\n    data = dict(getattr(obj, \"__dict__\", {}))\n    data.update(overrides)\n    return SimpleNamespace(**data)\n\n\ndef _sanitize_tool_call(tool_call: Any) -> Any | None:\n    \"\"\"Normalize a tool call for parser safety, or drop it if unusable.\"\"\"\n    if not hasattr(tool_call, \"index\"):\n        return None\n\n    function = getattr(tool_call, \"function\", None)\n    if function is None:\n        return None\n\n    has_name = hasattr(function, \"name\")\n    has_arguments = hasattr(function, \"arguments\")\n\n    raw_name = getattr(function, \"name\", \"\")\n    if isinstance(raw_name, str):\n        safe_name = raw_name\n    elif raw_name is None:\n        safe_name = \"\"\n    else:\n        safe_name = str(raw_name)\n\n    raw_arguments = getattr(function, \"arguments\", \"\")\n    if isinstance(raw_arguments, str):\n        safe_arguments = raw_arguments\n    elif raw_arguments is None:\n        safe_arguments = \"\"\n    else:\n        try:\n            safe_arguments = json.dumps(raw_arguments, ensure_ascii=False)\n        except (TypeError, ValueError):\n            safe_arguments = str(raw_arguments)\n\n    if (\n        has_name\n        and has_arguments\n        and isinstance(raw_name, str)\n        and isinstance(\n            raw_arguments,\n            str,\n        )\n    ):\n        return tool_call\n\n    safe_function = SimpleNamespace(\n        name=safe_name,\n        arguments=safe_arguments,\n    )\n    return _clone_with_overrides(tool_call, function=safe_function)\n\n\ndef _sanitize_chunk(chunk: Any) -> Any:\n    \"\"\"Drop/normalize malformed tool-calls in a streaming chunk.\"\"\"\n    choices = getattr(chunk, \"choices\", None)\n    if not choices:\n        return chunk\n\n    sanitized_choices: list[Any] = []\n    changed = False\n\n    for choice in choices:\n        delta = getattr(choice, \"delta\", None)\n        if delta is None:\n            sanitized_choices.append(choice)\n            continue\n\n        raw_tool_calls = getattr(delta, \"tool_calls\", None)\n        if not raw_tool_calls:\n            sanitized_choices.append(choice)\n            continue\n\n        choice_changed = False\n        sanitized_tool_calls: list[Any] = []\n        for tool_call in raw_tool_calls:\n            sanitized = _sanitize_tool_call(tool_call)\n            if sanitized is not tool_call:\n                choice_changed = True\n            if sanitized is not None:\n                sanitized_tool_calls.append(sanitized)\n\n        if choice_changed:\n            changed = True\n            sanitized_delta = _clone_with_overrides(\n                delta,\n                tool_calls=sanitized_tool_calls,\n            )\n            sanitized_choice = _clone_with_overrides(\n                choice,\n                delta=sanitized_delta,\n            )\n            sanitized_choices.append(sanitized_choice)\n            continue\n\n        sanitized_choices.append(choice)\n\n    if not changed:\n        return chunk\n    return _clone_with_overrides(chunk, choices=sanitized_choices)\n\n\ndef _sanitize_stream_item(item: Any) -> Any:\n    \"\"\"Sanitize either plain stream chunks or structured stream items.\"\"\"\n    if hasattr(item, \"chunk\"):\n        chunk = item.chunk\n        sanitized_chunk = _sanitize_chunk(chunk)\n        if sanitized_chunk is chunk:\n            return item\n        return _clone_with_overrides(item, chunk=sanitized_chunk)\n\n    return _sanitize_chunk(item)\n\n\nclass _SanitizedStream:\n    \"\"\"Proxy OpenAI async stream that sanitizes each emitted item and\n    captures ``extra_content`` from tool-call chunks (used by Gemini\n    thinking models to carry ``thought_signature``).\"\"\"\n\n    def __init__(self, stream: Any):\n        self._stream = stream\n        self._ctx_stream: Any | None = None\n        self.extra_contents: dict[str, Any] = {}\n\n    async def __aenter__(self) -> \"_SanitizedStream\":\n        self._ctx_stream = await self._stream.__aenter__()\n        return self\n\n    async def __aexit__(\n        self,\n        exc_type: Any,\n        exc: Any,\n        tb: Any,\n    ) -> bool | None:\n        return await self._stream.__aexit__(exc_type, exc, tb)\n\n    def __aiter__(self) -> \"_SanitizedStream\":\n        return self\n\n    async def __anext__(self) -> Any:\n        if self._ctx_stream is None:\n            raise StopAsyncIteration\n        item = await self._ctx_stream.__anext__()\n        self._capture_extra_content(item)\n        return _sanitize_stream_item(item)\n\n    def _capture_extra_content(self, item: Any) -> None:\n        \"\"\"Store ``extra_content`` keyed by tool-call id.\"\"\"\n        chunk = getattr(item, \"chunk\", item)\n        choices = getattr(chunk, \"choices\", None) or []\n        for choice in choices:\n            delta = getattr(choice, \"delta\", None)\n            if not delta:\n                continue\n            for tc in getattr(delta, \"tool_calls\", None) or []:\n                tc_id = getattr(tc, \"id\", None)\n                if not tc_id:\n                    continue\n                extra = getattr(tc, \"extra_content\", None)\n                if extra is None:\n                    model_extra = getattr(tc, \"model_extra\", None)\n                    if isinstance(model_extra, dict):\n                        extra = model_extra.get(\"extra_content\")\n                if extra:\n                    self.extra_contents[tc_id] = extra\n\n\nclass OpenAIChatModelCompat(OpenAIChatModel):\n    \"\"\"OpenAIChatModel with robust parsing for malformed tool-call chunks\n    and transparent ``extra_content`` (Gemini thought_signature) relay.\"\"\"\n\n    async def _parse_openai_stream_response(\n        self,\n        start_datetime: datetime,\n        response: Any,\n        structured_model: Type[BaseModel] | None = None,\n    ) -> AsyncGenerator[ChatResponse, None]:\n        sanitized_response = _SanitizedStream(response)\n        async for parsed in super()._parse_openai_stream_response(\n            start_datetime=start_datetime,\n            response=sanitized_response,\n            structured_model=structured_model,\n        ):\n            if sanitized_response.extra_contents:\n                for block in parsed.content:\n                    if block.get(\"type\") != \"tool_use\":\n                        continue\n                    tool_id = block.get(\"id\")\n                    if not isinstance(tool_id, str):\n                        continue\n                    ec = sanitized_response.extra_contents.get(tool_id)\n                    if ec:\n                        block[\"extra_content\"] = ec\n            yield parsed\n"
  },
  {
    "path": "src/copaw/providers/openai_provider.py",
    "content": "# -*- coding: utf-8 -*-\n\"\"\"An OpenAI provider implementation.\"\"\"\n\nfrom __future__ import annotations\n\nimport json\nfrom typing import Any, List\n\nfrom agentscope.model import ChatModelBase\nfrom openai import APIError, AsyncOpenAI\n\nfrom copaw.providers.provider import ModelInfo, Provider\n\nDASHSCOPE_BASE_URL = \"https://dashscope.aliyuncs.com/compatible-mode/v1\"\nCODING_DASHSCOPE_BASE_URL = \"https://coding.dashscope.aliyuncs.com/v1\"\n\n\nclass OpenAIProvider(Provider):\n    \"\"\"Provider implementation for OpenAI API and compatible endpoints.\"\"\"\n\n    def _client(self, timeout: float = 5) -> AsyncOpenAI:\n        return AsyncOpenAI(\n            base_url=self.base_url,\n            api_key=self.api_key,\n            timeout=timeout,\n        )\n\n    @staticmethod\n    def _normalize_models_payload(payload: Any) -> List[ModelInfo]:\n        models: List[ModelInfo] = []\n        rows = getattr(payload, \"data\", [])\n        for row in rows or []:\n            model_id = str(getattr(row, \"id\", \"\") or \"\").strip()\n            if not model_id:\n                continue\n            model_name = (\n                str(getattr(row, \"name\", \"\") or model_id).strip() or model_id\n            )\n            models.append(ModelInfo(id=model_id, name=model_name))\n\n        deduped: List[ModelInfo] = []\n        seen: set[str] = set()\n        for model in models:\n            if model.id in seen:\n                continue\n            seen.add(model.id)\n            deduped.append(model)\n        return deduped\n\n    async def check_connection(self, timeout: float = 5) -> tuple[bool, str]:\n        \"\"\"Check if OpenAI provider is reachable with current configuration.\"\"\"\n        if self.base_url == CODING_DASHSCOPE_BASE_URL:\n            return True, \"\"\n        client = self._client()\n        try:\n            await client.models.list(timeout=timeout)\n            return True, \"\"\n        except APIError:\n            return False, f\"API error when connecting to `{self.base_url}`\"\n        except Exception:\n            return (\n                False,\n                f\"Unknown exception when connecting to `{self.base_url}`\",\n            )\n\n    async def fetch_models(self, timeout: float = 5) -> List[ModelInfo]:\n        \"\"\"Fetch available models.\"\"\"\n        try:\n            client = self._client(timeout=timeout)\n            payload = await client.models.list(timeout=timeout)\n            models = self._normalize_models_payload(payload)\n            return models\n        except APIError:\n            return []\n        except Exception:\n            return []\n\n    async def check_model_connection(\n        self,\n        model_id: str,\n        timeout: float = 5,\n    ) -> tuple[bool, str]:\n        \"\"\"Check if a specific model is reachable/usable\"\"\"\n        model_id = (model_id or \"\").strip()\n        if not model_id:\n            return False, \"Empty model ID\"\n\n        try:\n            client = self._client(timeout=timeout)\n            res = await client.chat.completions.create(\n                model=model_id,\n                messages=[\n                    {\n                        \"role\": \"user\",\n                        \"content\": [\n                            {\n                                \"type\": \"text\",\n                                \"text\": \"ping\",\n                            },\n                        ],\n                    },\n                ],\n                timeout=timeout,\n                max_tokens=1,\n                stream=True,\n            )\n            # consume the stream to ensure the model is actually responsive\n            async for _ in res:\n                break\n            return True, \"\"\n        except APIError:\n            return False, f\"API error when connecting to model '{model_id}'\"\n        except Exception:\n            return (\n                False,\n                f\"Unknown exception when connecting to model '{model_id}'\",\n            )\n\n    def get_chat_model_instance(self, model_id: str) -> ChatModelBase:\n        from .openai_chat_model_compat import OpenAIChatModelCompat\n\n        client_kwargs = {\"base_url\": self.base_url}\n\n        if self.base_url == DASHSCOPE_BASE_URL:\n            client_kwargs[\"default_headers\"] = {\n                \"x-dashscope-agentapp\": json.dumps(\n                    {\n                        \"agentType\": \"CoPaw\",\n                        \"deployType\": \"UnKnown\",\n                        \"moduleCode\": \"model\",\n                        \"agentCode\": \"UnKnown\",\n                    },\n                    ensure_ascii=False,\n                ),\n            }\n        elif self.base_url == CODING_DASHSCOPE_BASE_URL:\n            client_kwargs[\"default_headers\"] = {\n                \"X-DashScope-Cdpl\": json.dumps(\n                    {\n                        \"agentType\": \"CoPaw\",\n                        \"deployType\": \"UnKnown\",\n                        \"moduleCode\": \"model\",\n                        \"agentCode\": \"UnKnown\",\n                    },\n                    ensure_ascii=False,\n                ),\n            }\n\n        return OpenAIChatModelCompat(\n            model_name=model_id,\n            stream=True,\n            api_key=self.api_key,\n            stream_tool_parsing=False,\n            client_kwargs=client_kwargs,\n            generate_kwargs=self.generate_kwargs,\n        )\n"
  },
  {
    "path": "src/copaw/providers/provider.py",
    "content": "# -*- coding: utf-8 -*-\n\"\"\"Definition of Provider.\"\"\"\n\nfrom abc import ABC, abstractmethod\nfrom typing import Dict, List, Type, Any\nfrom pydantic import BaseModel, Field\n\nfrom agentscope.model import ChatModelBase\n\n\nclass ModelInfo(BaseModel):\n    id: str = Field(..., description=\"Model identifier used in API calls\")\n    name: str = Field(..., description=\"Human-readable model name\")\n\n\nclass ProviderInfo(BaseModel):\n    id: str = Field(..., description=\"Provider identifier\")\n    name: str = Field(..., description=\"Human-readable provider name\")\n    base_url: str = Field(default=\"\", description=\"API base URL\")\n    api_key: str = Field(default=\"\", description=\"API key for authentication\")\n    chat_model: str = Field(\n        default=\"OpenAIChatModel\",\n        description=\"AgentScope ChatModel name (e.g., 'OpenAIChatModel')\",\n    )\n    models: List[ModelInfo] = Field(\n        default_factory=list,\n        description=\"List of pre-defined models\",\n    )\n    extra_models: List[ModelInfo] = Field(\n        default_factory=list,\n        description=\"List of user-added models (not fetched from provider)\",\n    )\n    api_key_prefix: str = Field(\n        default=\"\",\n        description=\"Expected prefix for the API key (e.g., 'sk-')\",\n    )\n    is_local: bool = Field(\n        default=False,\n        description=\"Whether this provider is for a local hosting platform\",\n    )\n    freeze_url: bool = Field(\n        default=False,\n        description=\"Whether the base_url should be frozen (not editable)\",\n    )\n    require_api_key: bool = Field(\n        default=True,\n        description=\"Whether this provider requires an API key\",\n    )\n    is_custom: bool = Field(\n        default=False,\n        description=(\"Whether this provider is user-created (not built-in).\"),\n    )\n    support_model_discovery: bool = Field(\n        default=False,\n        description=(\n            \"Whether this provider supports fetching available models\"\n            \" from the provider's API\"\n        ),\n    )\n    support_connection_check: bool = Field(\n        default=True,\n        description=(\n            \"Whether this provider supports checking connection to the API \"\n            \"without model configuration\"\n        ),\n    )\n    generate_kwargs: Dict[str, Any] = Field(\n        default_factory=dict,\n        description=\"Generation parameters for agentscope chat models.\",\n    )\n\n\nclass Provider(ProviderInfo, ABC):\n    \"\"\"Represents a provider instance with its configuration.\"\"\"\n\n    @abstractmethod\n    async def check_connection(self, timeout: float = 5) -> tuple[bool, str]:\n        \"\"\"Check if the provider is reachable with the current config.\"\"\"\n\n    @abstractmethod\n    async def fetch_models(self, timeout: float = 5) -> List[ModelInfo]:\n        \"\"\"Fetch the list of available models from the provider.\"\"\"\n\n    @abstractmethod\n    async def check_model_connection(\n        self,\n        model_id: str,\n        timeout: float = 5,  # pylint: disable=unused-argument\n    ) -> tuple[bool, str]:\n        \"\"\"Check if a specific model is reachable/usable.\"\"\"\n\n    async def add_model(\n        self,\n        model_info: ModelInfo,\n        target: str = \"extra_models\",\n        timeout: float = 10,  # pylint: disable=unused-argument\n    ) -> tuple[bool, str]:\n        \"\"\"Add a model to the provider's model list.\"\"\"\n        if model_info.id in {\n            model.id for model in self.models + self.extra_models\n        }:\n            return False, f\"Model '{model_info.id}' already exists\"\n        if target == \"extra_models\":\n            self.extra_models.append(model_info)\n        elif target == \"models\":\n            self.models.append(model_info)\n        else:\n            return False, f\"Invalid target '{target}' for adding model\"\n        return True, \"\"\n\n    async def delete_model(\n        self,\n        model_id: str,\n        timeout: float = 10,  # pylint: disable=unused-argument\n    ) -> tuple[bool, str]:\n        \"\"\"Delete a model from the provider's model list.\"\"\"\n        self.extra_models = [\n            model for model in self.extra_models if model.id != model_id\n        ]\n        return True, \"\"\n\n    def update_config(self, config: Dict) -> None:\n        \"\"\"Update provider configuration with the given dictionary.\"\"\"\n        if \"name\" in config and config[\"name\"] is not None:\n            self.name = str(config[\"name\"])\n        if (\n            not self.freeze_url\n            and \"base_url\" in config\n            and config[\"base_url\"] is not None\n        ):\n            self.base_url = str(config[\"base_url\"])\n        if \"api_key\" in config and config[\"api_key\"] is not None:\n            self.api_key = str(config[\"api_key\"])\n        if (\n            self.is_custom\n            and \"chat_model\" in config\n            and config[\"chat_model\"] is not None\n        ):\n            self.chat_model = str(config[\"chat_model\"])\n        if \"api_key_prefix\" in config and config[\"api_key_prefix\"] is not None:\n            self.api_key_prefix = str(config[\"api_key_prefix\"])\n        if (\n            \"generate_kwargs\" in config\n            and config[\"generate_kwargs\"] is not None\n            and isinstance(config[\"generate_kwargs\"], dict)\n        ):\n            self.generate_kwargs = config[\"generate_kwargs\"]\n\n    def get_chat_model_cls(self) -> Type[ChatModelBase]:\n        \"\"\"Return the chat model class associated with this provider.\"\"\"\n        import agentscope.model\n\n        chat_model_cls = getattr(\n            agentscope.model,\n            self.chat_model,\n            None,\n        )\n        if chat_model_cls is None:\n            raise ValueError(\n                f\"Chat model class '{self.chat_model}' not found\"\n                f\" for provider '{self.name}'.\",\n            )\n        return chat_model_cls\n\n    def has_model(self, model_id: str) -> bool:\n        \"\"\"Check if the provider has a model with the given ID.\"\"\"\n        return any(\n            model.id == model_id for model in self.models + self.extra_models\n        )\n\n    @abstractmethod\n    def get_chat_model_instance(self, model_id: str) -> ChatModelBase:\n        \"\"\"Return an instance of the chat model associated with this\n        provider and model_id.\"\"\"\n\n    async def get_info(self, mock_secret: bool = True) -> ProviderInfo:\n        \"\"\"Return a ProviderInfo instance with the provider's details.\"\"\"\n        api_key = (\n            self.api_key_prefix + \"*\" * 6\n            if mock_secret and self.api_key\n            else self.api_key\n        )\n        return ProviderInfo(\n            id=self.id,\n            name=self.name,\n            base_url=self.base_url,\n            api_key=api_key,\n            chat_model=self.chat_model,\n            models=self.models,\n            extra_models=self.extra_models,\n            api_key_prefix=self.api_key_prefix,\n            is_local=self.is_local,\n            is_custom=self.is_custom,\n            support_model_discovery=self.support_model_discovery,\n            # custom providers are assumed to not support connection check\n            support_connection_check=self.support_connection_check\n            and not self.is_custom,\n            freeze_url=self.freeze_url,\n            require_api_key=self.require_api_key,\n            generate_kwargs=self.generate_kwargs,\n        )\n\n\nclass DefaultProvider(Provider):\n    \"\"\"Default provider implementation with no-op methods.\"\"\"\n\n    async def check_connection(self, timeout: float = 5) -> tuple[bool, str]:\n        if len(self.models) > 0:\n            return True, \"\"\n        return False, \"No models available in the default provider\"\n\n    async def fetch_models(self, timeout: float = 5) -> List[ModelInfo]:\n        return self.models\n\n    async def check_model_connection(\n        self,\n        model_id: str,\n        timeout: float = 5,\n    ) -> tuple[bool, str]:\n        if model_id in {model.id for model in self.models}:\n            return True, \"\"\n        return False, f\"Model '{model_id}' not found\"\n\n    def update_config(self, config: Dict) -> None:\n        pass\n\n    def get_chat_model_instance(self, model_id: str) -> ChatModelBase:\n        raise NotImplementedError(\n            \"DefaultProvider does not implement chat model\",\n        )\n"
  },
  {
    "path": "src/copaw/providers/provider_manager.py",
    "content": "# -*- coding: utf-8 -*-\n\"\"\"A Manager class to handle all providers, including built-in and custom ones.\nIt provides a unified interface to manage providers, such as listing available\nproviders, adding/removing custom providers, and fetching provider details.\"\"\"\n\nimport asyncio\nimport os\nfrom typing import Dict, List\nimport logging\nimport json\n\nfrom pydantic import BaseModel\n\nfrom agentscope.model import ChatModelBase\n\nfrom copaw.providers.provider import (\n    ModelInfo,\n    DefaultProvider,\n    Provider,\n    ProviderInfo,\n)\nfrom copaw.providers.models import ModelSlotConfig\nfrom copaw.providers.openai_provider import OpenAIProvider\nfrom copaw.providers.anthropic_provider import AnthropicProvider\nfrom copaw.providers.gemini_provider import GeminiProvider\nfrom copaw.providers.ollama_provider import OllamaProvider\nfrom copaw.constant import SECRET_DIR\nfrom copaw.local_models import create_local_chat_model\n\nlogger = logging.getLogger(__name__)\n\n\n# -------------------------------------------------------\n# Built-in provider definitions and their default models.\n# -------------------------------------------------------\n\nMODELSCOPE_MODELS: List[ModelInfo] = [\n    ModelInfo(\n        id=\"Qwen/Qwen3.5-122B-A10B\",\n        name=\"Qwen3.5-122B-A10B\",\n    ),\n    ModelInfo(id=\"ZhipuAI/GLM-5\", name=\"GLM-5\"),\n]\n\nDASHSCOPE_MODELS: List[ModelInfo] = [\n    ModelInfo(id=\"qwen3-max\", name=\"Qwen3 Max\"),\n    ModelInfo(\n        id=\"qwen3-235b-a22b-thinking-2507\",\n        name=\"Qwen3 235B A22B Thinking\",\n    ),\n    ModelInfo(id=\"deepseek-v3.2\", name=\"DeepSeek-V3.2\"),\n]\n\nALIYUN_CODINGPLAN_MODELS: List[ModelInfo] = [\n    ModelInfo(id=\"qwen3.5-plus\", name=\"Qwen3.5 Plus\"),\n    ModelInfo(id=\"glm-5\", name=\"GLM-5\"),\n    ModelInfo(id=\"glm-4.7\", name=\"GLM-4.7\"),\n    ModelInfo(id=\"MiniMax-M2.5\", name=\"MiniMax M2.5\"),\n    ModelInfo(id=\"kimi-k2.5\", name=\"Kimi K2.5\"),\n    ModelInfo(id=\"qwen3-max-2026-01-23\", name=\"Qwen3 Max 2026-01-23\"),\n    ModelInfo(id=\"qwen3-coder-next\", name=\"Qwen3 Coder Next\"),\n    ModelInfo(id=\"qwen3-coder-plus\", name=\"Qwen3 Coder Plus\"),\n]\n\nOPENAI_MODELS: List[ModelInfo] = [\n    ModelInfo(id=\"gpt-5.2\", name=\"GPT-5.2\"),\n    ModelInfo(id=\"gpt-5\", name=\"GPT-5\"),\n    ModelInfo(id=\"gpt-5-mini\", name=\"GPT-5 Mini\"),\n    ModelInfo(id=\"gpt-5-nano\", name=\"GPT-5 Nano\"),\n    ModelInfo(id=\"gpt-4.1\", name=\"GPT-4.1\"),\n    ModelInfo(id=\"gpt-4.1-mini\", name=\"GPT-4.1 Mini\"),\n    ModelInfo(id=\"gpt-4.1-nano\", name=\"GPT-4.1 Nano\"),\n    ModelInfo(id=\"o3\", name=\"o3\"),\n    ModelInfo(id=\"o4-mini\", name=\"o4-mini\"),\n    ModelInfo(id=\"gpt-4o\", name=\"GPT-4o\"),\n    ModelInfo(id=\"gpt-4o-mini\", name=\"GPT-4o Mini\"),\n]\n\nAZURE_OPENAI_MODELS: List[ModelInfo] = [\n    ModelInfo(id=\"gpt-5-chat\", name=\"GPT-5 Chat\"),\n    ModelInfo(id=\"gpt-5-mini\", name=\"GPT-5 Mini\"),\n    ModelInfo(id=\"gpt-5-nano\", name=\"GPT-5 Nano\"),\n    ModelInfo(id=\"gpt-4.1\", name=\"GPT-4.1\"),\n    ModelInfo(id=\"gpt-4.1-mini\", name=\"GPT-4.1 Mini\"),\n    ModelInfo(id=\"gpt-4.1-nano\", name=\"GPT-4.1 Nano\"),\n    ModelInfo(id=\"gpt-4o\", name=\"GPT-4o\"),\n    ModelInfo(id=\"gpt-4o-mini\", name=\"GPT-4o Mini\"),\n]\n\nMINIMAX_MODELS: List[ModelInfo] = [\n    ModelInfo(id=\"MiniMax-M2.5\", name=\"MiniMax M2.5\"),\n    ModelInfo(id=\"MiniMax-M2.5-highspeed\", name=\"MiniMax M2.5 Highspeed\"),\n    ModelInfo(id=\"MiniMax-M2.7\", name=\"MiniMax M2.7\"),\n    ModelInfo(id=\"MiniMax-M2.7-highspeed\", name=\"MiniMax M2.7 Highspeed\"),\n]\n\nKIMI_MODELS: List[ModelInfo] = [\n    ModelInfo(id=\"kimi-k2.5\", name=\"Kimi K2.5\"),\n    ModelInfo(\n        id=\"kimi-k2-0905-preview\",\n        name=\"Kimi K2 0905 Preview\",\n    ),\n    ModelInfo(\n        id=\"kimi-k2-0711-preview\",\n        name=\"Kimi K2 0711 Preview\",\n    ),\n    ModelInfo(\n        id=\"kimi-k2-turbo-preview\",\n        name=\"Kimi K2 Turbo Preview\",\n    ),\n    ModelInfo(id=\"kimi-k2-thinking\", name=\"Kimi K2 Thinking\"),\n    ModelInfo(\n        id=\"kimi-k2-thinking-turbo\",\n        name=\"Kimi K2 Thinking Turbo\",\n    ),\n]\n\nDEEPSEEK_MODELS: List[ModelInfo] = [\n    ModelInfo(id=\"deepseek-chat\", name=\"DeepSeek Chat\"),\n    ModelInfo(id=\"deepseek-reasoner\", name=\"DeepSeek Reasoner\"),\n]\n\nANTHROPIC_MODELS: List[ModelInfo] = []\n\nGEMINI_MODELS: List[ModelInfo] = [\n    ModelInfo(id=\"gemini-3.1-pro-preview\", name=\"Gemini 3.1 Pro Preview\"),\n    ModelInfo(id=\"gemini-3-flash-preview\", name=\"Gemini 3 Flash Preview\"),\n    ModelInfo(\n        id=\"gemini-3.1-flash-lite-preview\",\n        name=\"Gemini 3.1 Flash Lite Preview\",\n    ),\n    ModelInfo(id=\"gemini-2.5-pro\", name=\"Gemini 2.5 Pro\"),\n    ModelInfo(id=\"gemini-2.5-flash\", name=\"Gemini 2.5 Flash\"),\n    ModelInfo(id=\"gemini-2.5-flash-lite\", name=\"Gemini 2.5 Flash Lite\"),\n    ModelInfo(id=\"gemini-2.0-flash\", name=\"Gemini 2.0 Flash\"),\n]\n\nPROVIDER_MODELSCOPE = OpenAIProvider(\n    id=\"modelscope\",\n    name=\"ModelScope\",\n    base_url=\"https://api-inference.modelscope.cn/v1\",\n    api_key_prefix=\"ms\",\n    models=MODELSCOPE_MODELS,\n    freeze_url=True,\n)\n\nPROVIDER_DASHSCOPE = OpenAIProvider(\n    id=\"dashscope\",\n    name=\"DashScope\",\n    base_url=\"https://dashscope.aliyuncs.com/compatible-mode/v1\",\n    api_key_prefix=\"sk\",\n    models=DASHSCOPE_MODELS,\n    freeze_url=True,\n)\n\nPROVIDER_ALIYUN_CODINGPLAN = OpenAIProvider(\n    id=\"aliyun-codingplan\",\n    name=\"Aliyun Coding Plan\",\n    base_url=\"https://coding.dashscope.aliyuncs.com/v1\",\n    api_key_prefix=\"sk-sp\",\n    models=ALIYUN_CODINGPLAN_MODELS,\n    # This provider doesn't support connection check without model config\n    support_connection_check=False,\n    freeze_url=True,\n)\n\nPROVIDER_LLAMACPP = DefaultProvider(\n    id=\"llamacpp\",\n    name=\"llama.cpp (Local)\",\n    is_local=True,\n    require_api_key=False,\n)\n\nPROVIDER_MLX = DefaultProvider(\n    id=\"mlx\",\n    name=\"MLX (Local, Apple Silicon)\",\n    is_local=True,\n    require_api_key=False,\n)\n\nPROVIDER_OPENAI = OpenAIProvider(\n    id=\"openai\",\n    name=\"OpenAI\",\n    base_url=\"https://api.openai.com/v1\",\n    api_key_prefix=\"sk-\",\n    models=OPENAI_MODELS,\n    freeze_url=True,\n)\n\nPROVIDER_AZURE_OPENAI = OpenAIProvider(\n    id=\"azure-openai\",\n    name=\"Azure OpenAI\",\n    api_key_prefix=\"\",\n    models=AZURE_OPENAI_MODELS,\n)\n\nPROVIDER_MINIMAX = AnthropicProvider(\n    id=\"minimax\",\n    name=\"MiniMax (International)\",\n    base_url=\"https://api.minimax.io/anthropic\",\n    models=MINIMAX_MODELS,\n    chat_model=\"AnthropicChatModel\",\n    freeze_url=True,\n)\n\nPROVIDER_MINIMAX_CN = AnthropicProvider(\n    id=\"minimax-cn\",\n    name=\"MiniMax (China)\",\n    base_url=\"https://api.minimaxi.com/anthropic\",\n    models=MINIMAX_MODELS,\n    chat_model=\"AnthropicChatModel\",\n    freeze_url=True,\n    # This provider doesn't support connection check without model config\n    support_connection_check=False,\n)\n\nPROVIDER_KIMI_CN = OpenAIProvider(\n    id=\"kimi-cn\",\n    name=\"Kimi (China)\",\n    base_url=\"https://api.moonshot.cn/v1\",\n    api_key_prefix=\"\",\n    models=KIMI_MODELS,\n    freeze_url=True,\n)\n\nPROVIDER_KIMI_INTL = OpenAIProvider(\n    id=\"kimi-intl\",\n    name=\"Kimi (International)\",\n    base_url=\"https://api.moonshot.ai/v1\",\n    api_key_prefix=\"\",\n    models=KIMI_MODELS,\n    freeze_url=True,\n)\n\nPROVIDER_DEEPSEEK = OpenAIProvider(\n    id=\"deepseek\",\n    name=\"DeepSeek\",\n    base_url=\"https://api.deepseek.com\",\n    api_key_prefix=\"sk-\",\n    models=DEEPSEEK_MODELS,\n    freeze_url=True,\n)\n\nPROVIDER_ANTHROPIC = AnthropicProvider(\n    id=\"anthropic\",\n    name=\"Anthropic\",\n    base_url=\"https://api.anthropic.com\",\n    api_key_prefix=\"sk-ant-\",\n    models=ANTHROPIC_MODELS,\n    chat_model=\"AnthropicChatModel\",\n    freeze_url=True,\n)\n\nPROVIDER_GEMINI = GeminiProvider(\n    id=\"gemini\",\n    name=\"Google Gemini\",\n    base_url=\"https://generativelanguage.googleapis.com\",\n    api_key_prefix=\"\",\n    models=GEMINI_MODELS,\n    chat_model=\"GeminiChatModel\",\n    freeze_url=True,\n    support_model_discovery=True,\n)\n\nPROVIDER_OLLAMA = OllamaProvider(\n    id=\"ollama\",\n    name=\"Ollama\",\n    require_api_key=False,\n    support_model_discovery=True,\n    generate_kwargs={\"max_tokens\": None},\n)\n\nPROVIDER_LMSTUDIO = OpenAIProvider(\n    id=\"lmstudio\",\n    name=\"LM Studio\",\n    base_url=\"http://localhost:1234/v1\",\n    require_api_key=False,\n    api_key_prefix=\"\",\n    support_model_discovery=True,\n    generate_kwargs={\"max_tokens\": None},\n)\n\n\nclass ActiveModelsInfo(BaseModel):\n    active_llm: ModelSlotConfig | None\n\n\nclass ProviderManager:\n    \"\"\"A manager class to handle all providers,\n    including built-in and custom ones.\"\"\"\n\n    _instance = None\n\n    def __init__(self) -> None:\n        # Initialize provider manager, load providers from registry and store\n        # any necessary state (e.g., cached models).\n        self.builtin_providers: Dict[str, Provider] = {}\n        self.custom_providers: Dict[str, Provider] = {}\n        self.active_model: ModelSlotConfig | None = None\n        self.root_path = SECRET_DIR / \"providers\"\n        self.builtin_path = self.root_path / \"builtin\"\n        self.custom_path = self.root_path / \"custom\"\n        self._prepare_disk_storage()\n        self._init_builtins()\n        try:\n            self._migrate_legacy_providers()\n        except Exception as e:\n            logger.warning(\"Failed to migrate legacy providers: %s\", e)\n        self._init_from_storage()\n        self.update_local_models()\n\n    def _prepare_disk_storage(self):\n        \"\"\"Prepare directory structure\"\"\"\n        for path in [self.root_path, self.builtin_path, self.custom_path]:\n            path.mkdir(parents=True, exist_ok=True)\n            try:\n                os.chmod(path, 0o700)  # Restrict permissions for security\n            except Exception:\n                pass\n\n    def _init_builtins(self):\n        self._add_builtin(PROVIDER_MODELSCOPE)\n        self._add_builtin(PROVIDER_DASHSCOPE)\n        self._add_builtin(PROVIDER_ALIYUN_CODINGPLAN)\n        self._add_builtin(PROVIDER_OPENAI)\n        self._add_builtin(PROVIDER_AZURE_OPENAI)\n        self._add_builtin(PROVIDER_KIMI_CN)\n        self._add_builtin(PROVIDER_KIMI_INTL)\n        self._add_builtin(PROVIDER_DEEPSEEK)\n        self._add_builtin(PROVIDER_ANTHROPIC)\n        self._add_builtin(PROVIDER_GEMINI)\n        self._add_builtin(PROVIDER_MINIMAX_CN)\n        self._add_builtin(PROVIDER_MINIMAX)\n        self._add_builtin(PROVIDER_OLLAMA)\n        self._add_builtin(PROVIDER_LMSTUDIO)\n        self._add_builtin(PROVIDER_LLAMACPP)\n        self._add_builtin(PROVIDER_MLX)\n\n    def _add_builtin(self, provider: Provider):\n        self.builtin_providers[provider.id] = provider\n\n    async def list_provider_info(self) -> List[ProviderInfo]:\n        tasks = [\n            provider.get_info() for provider in self.builtin_providers.values()\n        ]\n        tasks += [\n            provider.get_info() for provider in self.custom_providers.values()\n        ]\n        provider_infos = await asyncio.gather(*tasks)\n        return list(provider_infos)\n\n    def get_provider(self, provider_id: str) -> Provider | None:\n        # Return a provider instance by its ID. This will be used to create\n        # chat model instances for the agent.\n        if provider_id in self.builtin_providers:\n            return self.builtin_providers[provider_id]\n        if provider_id in self.custom_providers:\n            return self.custom_providers[provider_id]\n        return None\n\n    async def get_provider_info(self, provider_id: str) -> ProviderInfo | None:\n        provider = self.get_provider(provider_id)\n        return await provider.get_info() if provider else None\n\n    def get_active_model(self) -> ModelSlotConfig | None:\n        # Return the currently active provider/model configuration.\n        return self.active_model\n\n    def update_provider(self, provider_id: str, config: Dict) -> bool:\n        # Update the configuration of a provider (e.g., base URL, API key).\n        # This will be called when the user edits a provider's settings in the\n        # UI. It should update the in-memory provider instance and persist the\n        # changes to providers.json.\n        provider = self.get_provider(provider_id)\n        if not provider:\n            return False\n        provider.update_config(config)\n        self._save_provider(\n            provider,\n            is_builtin=provider_id in self.builtin_providers,\n        )\n        return True\n\n    async def fetch_provider_models(\n        self,\n        provider_id: str,\n    ) -> List[ModelInfo]:\n        \"\"\"Fetch the list of available models from a provider and update.\"\"\"\n        provider = self.get_provider(provider_id)\n        if not provider:\n            return []\n        try:\n            models = await provider.fetch_models()\n            provider.extra_models = models\n            self._save_provider(\n                provider,\n                is_builtin=provider_id in self.builtin_providers,\n            )\n            return models\n        except Exception as e:\n            logger.warning(\n                \"Failed to fetch models for provider '%s': %s\",\n                provider_id,\n                e,\n            )\n            return []\n\n    def _resolve_custom_provider_id(self, provider_id: str) -> str:\n        \"\"\"Resolve provider ID conflicts for a custom provider.\"\"\"\n        base_id = provider_id\n        if base_id in self.builtin_providers:\n            base_id = f\"{base_id}-custom\"\n\n        resolved_id = base_id\n        while (\n            resolved_id in self.builtin_providers\n            or resolved_id in self.custom_providers\n        ):\n            resolved_id = f\"{resolved_id}-new\"\n\n        return resolved_id\n\n    async def add_custom_provider(self, provider_data: ProviderInfo):\n        # Add a new custom provider with the given data. This will update the\n        # providers.json file and make the new provider available in the UI.\n        provider_payload = provider_data.model_dump()\n        provider_payload[\"id\"] = self._resolve_custom_provider_id(\n            provider_data.id,\n        )\n        provider_payload[\"is_custom\"] = True\n        provider = self._provider_from_data(\n            provider_payload,\n        )  # Validate provider data\n        # For custom providers, we assume they don't support connection check\n        # without model config, to avoid false negatives in the UI.\n        provider.support_connection_check = False\n        self.custom_providers[provider.id] = provider\n        self._save_provider(provider, is_builtin=False)\n        return await provider.get_info()\n\n    def remove_custom_provider(self, provider_id: str) -> bool:\n        # Remove a custom provider by its ID. This will update the\n        # providers.json file and remove the provider from the UI.\n        if provider_id in self.custom_providers:\n            del self.custom_providers[provider_id]\n            provider_path = self.custom_path / f\"{provider_id}.json\"\n            if provider_path.exists():\n                os.remove(provider_path)\n            return True\n        return False\n\n    async def activate_model(self, provider_id: str, model_id: str):\n        # Set the active provider and model for the agent. This will update\n        # providers.json and determine which provider/model is used when the\n        # agent creates chat model instances.\n        provider = self.get_provider(provider_id)\n        if not provider:\n            raise ValueError(f\"Provider '{provider_id}' not found.\")\n        if not provider.has_model(model_id):\n            raise ValueError(\n                f\"Model '{model_id}' not found in provider '{provider_id}'.\",\n            )\n        self.active_model = ModelSlotConfig(\n            provider_id=provider_id,\n            model=model_id,\n        )\n        self.save_active_model(self.active_model)\n\n    async def add_model_to_provider(\n        self,\n        provider_id: str,\n        model_info: ModelInfo,\n    ) -> ProviderInfo:\n        provider = self.get_provider(provider_id)\n        if not provider:\n            raise ValueError(f\"Provider '{provider_id}' not found.\")\n        await provider.add_model(model_info)\n        self._save_provider(\n            provider,\n            is_builtin=provider_id in self.builtin_providers,\n        )\n        return await provider.get_info()\n\n    async def delete_model_from_provider(\n        self,\n        provider_id: str,\n        model_id: str,\n    ) -> ProviderInfo:\n        provider = self.get_provider(provider_id)\n        if not provider:\n            raise ValueError(f\"Provider '{provider_id}' not found.\")\n        await provider.delete_model(model_id=model_id)\n        self._save_provider(\n            provider,\n            is_builtin=provider_id in self.builtin_providers,\n        )\n        return await provider.get_info()\n\n    def _save_provider(\n        self,\n        provider: Provider,\n        is_builtin: bool = False,\n        skip_if_exists: bool = False,\n    ):\n        \"\"\"Save a provider configuration to disk.\"\"\"\n        provider_dir = self.builtin_path if is_builtin else self.custom_path\n        provider_path = provider_dir / f\"{provider.id}.json\"\n        if skip_if_exists and provider_path.exists():\n            return\n        with open(provider_path, \"w\", encoding=\"utf-8\") as f:\n            json.dump(provider.model_dump(), f, ensure_ascii=False, indent=2)\n        try:\n            os.chmod(provider_path, 0o600)\n        except OSError:\n            pass\n\n    def load_provider(\n        self,\n        provider_id: str,\n        is_builtin: bool = False,\n    ) -> Provider | None:\n        \"\"\"Load a provider configuration from disk.\"\"\"\n        provider_dir = self.builtin_path if is_builtin else self.custom_path\n        provider_path = provider_dir / f\"{provider_id}.json\"\n        if not provider_path.exists():\n            return None\n        try:\n            with open(provider_path, \"r\", encoding=\"utf-8\") as f:\n                data = json.load(f)\n            return self._provider_from_data(data)\n        except Exception as e:\n            logger.warning(\n                \"Failed to load provider '%s' from %s: %s\",\n                provider_id,\n                provider_path,\n                e,\n            )\n            return None\n\n    def _provider_from_data(self, data: Dict) -> Provider:\n        \"\"\"Deserialize provider data to a concrete provider type.\"\"\"\n        provider_id = str(data.get(\"id\", \"\"))\n        chat_model = str(data.get(\"chat_model\", \"\"))\n\n        if provider_id == \"anthropic\" or chat_model == \"AnthropicChatModel\":\n            return AnthropicProvider.model_validate(data)\n        if provider_id == \"gemini\" or chat_model == \"GeminiChatModel\":\n            return GeminiProvider.model_validate(data)\n        if provider_id == \"ollama\":\n            return OllamaProvider.model_validate(data)\n        if data.get(\"is_local\", False):\n            return DefaultProvider.model_validate(data)\n        return OpenAIProvider.model_validate(data)\n\n    def save_active_model(self, active_model: ModelSlotConfig):\n        \"\"\"Save the active provider/model configuration to disk.\"\"\"\n        active_path = self.root_path / \"active_model.json\"\n        with open(active_path, \"w\", encoding=\"utf-8\") as f:\n            json.dump(\n                active_model.model_dump(),\n                f,\n                ensure_ascii=False,\n                indent=2,\n            )\n        try:\n            os.chmod(active_path, 0o600)\n        except OSError:\n            pass\n\n    def load_active_model(self) -> ModelSlotConfig | None:\n        \"\"\"Load the active provider/model configuration from disk.\"\"\"\n        active_path = self.root_path / \"active_model.json\"\n        if not active_path.exists():\n            return None\n        try:\n            with open(active_path, \"r\", encoding=\"utf-8\") as f:\n                data = json.load(f)\n                return ModelSlotConfig.model_validate(data)\n        except Exception:\n            return None\n\n    def _migrate_legacy_providers(self):\n        \"\"\"Migrate from legacy providers.json format to the new structure.\"\"\"\n        legacy_path = SECRET_DIR / \"providers.json\"\n        if legacy_path.exists() and legacy_path.is_file():\n            with open(legacy_path, \"r\", encoding=\"utf-8\") as f:\n                legacy_data = json.load(f)\n            builtin_providers = legacy_data.get(\"providers\", {})\n            custom_providers = legacy_data.get(\"custom_providers\", {})\n            active_model = legacy_data.get(\"active_llm\", {})\n            # Migrate built-in providers\n            for provider_id, config in builtin_providers.items():\n                provider = self.get_provider(provider_id)\n                if not provider:\n                    logger.warning(\n                        \"Legacy provider '%s' not found in\"\n                        \" registry, skipping migration for this provider.\",\n                        provider_id,\n                    )\n                    continue\n                if \"api_key\" in config:\n                    provider.api_key = config[\"api_key\"]\n                if \"extra_models\" in config:\n                    provider.extra_models = [\n                        ModelInfo.model_validate(model)\n                        for model in config[\"extra_models\"]\n                    ]\n                if not provider.freeze_url and \"base_url\" in config:\n                    provider.base_url = config[\"base_url\"]\n                self._save_provider(provider, is_builtin=True)\n            # Migrate custom providers\n            for provider_id, data in custom_providers.items():\n                custom_provider = OpenAIProvider(\n                    id=provider_id,\n                    name=data.get(\"name\", provider_id),\n                    base_url=data.get(\"base_url\", \"\"),\n                    api_key=data.get(\"api_key\", \"\"),\n                    is_custom=True,\n                )\n                if \"models\" in data:\n                    # migrate models to extra_models field\n                    custom_provider.extra_models = [\n                        ModelInfo.model_validate(model)\n                        for model in data[\"models\"]\n                    ]\n                if \"chat_model\" in data:\n                    custom_provider.chat_model = data[\"chat_model\"]\n                self._save_provider(custom_provider, is_builtin=False)\n            # Migrate active model\n            if active_model:\n                try:\n                    self.active_model = ModelSlotConfig.model_validate(\n                        active_model,\n                    )\n                    self.save_active_model(self.active_model)\n                except Exception:\n                    logger.warning(\n                        \"Failed to migrate active model, using default.\",\n                    )\n            # Remove legacy file after migration\n            try:\n                os.remove(legacy_path)\n            except Exception:\n                logger.warning(\n                    \"Failed to remove legacy providers.json after migration.\",\n                )\n\n    def _init_from_storage(self):\n        \"\"\"Initialize all providers and active model from disk storage.\"\"\"\n        # Load built-in providers\n        for builtin in self.builtin_providers.values():\n            provider = self.load_provider(builtin.id, is_builtin=True)\n            if provider:\n                # inherit user-configured base_url only when freeze_url=False\n                if not builtin.freeze_url:\n                    builtin.base_url = provider.base_url\n                builtin.api_key = provider.api_key\n                builtin.extra_models = provider.extra_models\n                builtin.generate_kwargs.update(provider.generate_kwargs)\n        # Load custom providers\n        for provider_file in self.custom_path.glob(\"*.json\"):\n            provider = self.load_provider(provider_file.stem, is_builtin=False)\n            if provider:\n                self.custom_providers[provider.id] = provider\n        # Load active model config\n        active_model = self.load_active_model()\n        if active_model:\n            self.active_model = active_model\n\n    def update_local_models(self):\n        \"\"\"Update the model list of a local provider.\"\"\"\n        try:\n            from ..local_models.manager import list_local_models\n            from ..local_models.schema import BackendType\n\n            llamacpp_models: list[ModelInfo] = []\n            mlx_models: list[ModelInfo] = []\n\n            for model in list_local_models():\n                info = ModelInfo(id=model.id, name=model.display_name)\n                if model.backend == BackendType.LLAMACPP:\n                    llamacpp_models.append(info)\n                elif model.backend == BackendType.MLX:\n                    mlx_models.append(info)\n            PROVIDER_LLAMACPP.models = llamacpp_models\n            PROVIDER_MLX.models = mlx_models\n        except ImportError:\n            # local_models dependencies not installed; leave model lists empty\n            pass\n\n    @staticmethod\n    def get_instance() -> \"ProviderManager\":\n        \"\"\"Get the singleton instance of ProviderManager.\"\"\"\n        if ProviderManager._instance is None:\n            ProviderManager._instance = ProviderManager()\n        return ProviderManager._instance\n\n    @staticmethod\n    def get_active_chat_model() -> ChatModelBase:\n        \"\"\"Get the currently active provider/model configuration.\"\"\"\n        manager = ProviderManager.get_instance()\n        model = manager.get_active_model()\n        if model is None or model.provider_id == \"\" or model.model == \"\":\n            raise ValueError(\"No active model configured.\")\n        provider = manager.get_provider(model.provider_id)\n        if provider is None:\n            raise ValueError(\n                f\"Active provider '{model.provider_id}' not found.\",\n            )\n        if provider.is_local:\n            return create_local_chat_model(\n                model_id=model.model,\n                stream=True,\n                generate_kwargs={\"max_tokens\": None},\n            )\n        return provider.get_chat_model_instance(model.model)\n"
  },
  {
    "path": "src/copaw/providers/retry_chat_model.py",
    "content": "# -*- coding: utf-8 -*-\n\"\"\"Retry wrapper for ChatModelBase instances.\n\nTransparently retries LLM API calls on transient errors (rate-limit,\ntimeout, connection) with configurable exponential back-off.\n\nConfiguration via environment variables (or use defaults from constant.py):\n    COPAW_LLM_MAX_RETRIES   – max retry attempts (default 3)\n    COPAW_LLM_BACKOFF_BASE  – base delay in seconds (default 1.0)\n    COPAW_LLM_BACKOFF_CAP   – max delay cap in seconds (default 10.0)\n\"\"\"\n\nfrom __future__ import annotations\n\nimport asyncio\nimport logging\nfrom typing import Any, AsyncGenerator\n\nfrom agentscope.model import ChatModelBase\nfrom agentscope.model._model_response import ChatResponse\n\nfrom ..constant import LLM_BACKOFF_BASE, LLM_BACKOFF_CAP, LLM_MAX_RETRIES\n\nlogger = logging.getLogger(__name__)\n\nRETRYABLE_STATUS_CODES = {429, 500, 502, 503, 504, 529}\n\n_openai_retryable: tuple[type[Exception], ...] | None = None\n_anthropic_retryable: tuple[type[Exception], ...] | None = None\n\n\ndef _get_openai_retryable() -> tuple[type[Exception], ...]:\n    global _openai_retryable  # noqa: PLW0603\n    if _openai_retryable is None:\n        try:\n            import openai  # noqa: PLC0415\n\n            _openai_retryable = (\n                openai.RateLimitError,\n                openai.APITimeoutError,\n                openai.APIConnectionError,\n            )\n        except ImportError:\n            _openai_retryable = ()\n    return _openai_retryable\n\n\ndef _get_anthropic_retryable() -> tuple[type[Exception], ...]:\n    global _anthropic_retryable  # noqa: PLW0603\n    if _anthropic_retryable is None:\n        try:\n            import anthropic  # noqa: PLC0415\n\n            _anthropic_retryable = (\n                anthropic.RateLimitError,\n                anthropic.APITimeoutError,\n                anthropic.APIConnectionError,\n            )\n        except ImportError:\n            _anthropic_retryable = ()\n    return _anthropic_retryable\n\n\ndef _is_retryable(exc: Exception) -> bool:\n    \"\"\"Return *True* if *exc* should trigger a retry.\"\"\"\n    retryable = _get_openai_retryable() + _get_anthropic_retryable()\n    if retryable and isinstance(exc, retryable):\n        return True\n\n    status = getattr(exc, \"status_code\", None)\n    if status is not None and status in RETRYABLE_STATUS_CODES:\n        return True\n\n    return False\n\n\ndef _compute_backoff(attempt: int) -> float:\n    \"\"\"Exponential back-off: base * 2^(attempt-1), capped.\"\"\"\n    return min(LLM_BACKOFF_CAP, LLM_BACKOFF_BASE * (2 ** max(0, attempt - 1)))\n\n\nclass RetryChatModel(ChatModelBase):\n    \"\"\"Transparent retry wrapper around any :class:`ChatModelBase`.\n\n    The wrapper delegates every call to the underlying *inner* model and\n    retries on transient errors with exponential back-off.  Streaming\n    responses are also covered: if the stream fails mid-consumption the\n    entire request is retried from scratch.\n    \"\"\"\n\n    def __init__(self, inner: ChatModelBase) -> None:\n        super().__init__(model_name=inner.model_name, stream=inner.stream)\n        self._inner = inner\n\n    # Expose the real model's class so that formatter mapping keeps working\n    # when code inspects ``model.__class__`` after wrapping.\n    @property\n    def inner_class(self) -> type:\n        return self._inner.__class__\n\n    async def __call__(\n        self,\n        *args: Any,\n        **kwargs: Any,\n    ) -> ChatResponse | AsyncGenerator[ChatResponse, None]:\n        retries = LLM_MAX_RETRIES\n        attempts = retries + 1\n        last_exc: Exception | None = None\n\n        for attempt in range(1, attempts + 1):\n            try:\n                result = await self._inner(*args, **kwargs)\n\n                if isinstance(result, AsyncGenerator):\n                    return self._wrap_stream(\n                        result,\n                        args,\n                        kwargs,\n                        attempt,\n                        attempts,\n                    )\n                return result\n\n            except Exception as exc:\n                last_exc = exc\n                if not _is_retryable(exc) or attempt >= attempts:\n                    raise\n                delay = _compute_backoff(attempt)\n                logger.warning(\n                    \"LLM call failed (attempt %d/%d): %s. \"\n                    \"Retrying in %.1fs …\",\n                    attempt,\n                    attempts,\n                    exc,\n                    delay,\n                )\n                await asyncio.sleep(delay)\n\n        # Should be unreachable, but satisfies the type-checker.\n        raise last_exc  # type: ignore[misc]\n\n    async def _wrap_stream(\n        self,\n        stream: AsyncGenerator[ChatResponse, None],\n        call_args: tuple,\n        call_kwargs: dict,\n        current_attempt: int,\n        max_attempts: int,\n    ) -> AsyncGenerator[ChatResponse, None]:\n        \"\"\"Yield chunks from *stream*; on transient failure, retry the\n        full request and yield from the new stream instead.\"\"\"\n        failed_exc: Exception | None = None\n        try:\n            async for chunk in stream:\n                yield chunk\n        except Exception as exc:\n            failed_exc = exc\n        finally:\n            await stream.aclose()\n\n        if failed_exc is None:\n            return\n\n        if not _is_retryable(failed_exc) or current_attempt >= max_attempts:\n            raise failed_exc\n        delay = _compute_backoff(current_attempt)\n        logger.warning(\n            \"LLM stream failed (attempt %d/%d): %s. Retrying in %.1fs …\",\n            current_attempt,\n            max_attempts,\n            failed_exc,\n            delay,\n        )\n        await asyncio.sleep(delay)\n\n        new_stream: AsyncGenerator | None = None\n        for attempt in range(current_attempt + 1, max_attempts + 1):\n            try:\n                result = await self._inner(*call_args, **call_kwargs)\n                if isinstance(result, AsyncGenerator):\n                    new_stream = result\n                    async for chunk in new_stream:\n                        yield chunk\n                    new_stream = None\n                else:\n                    yield result\n                return\n            except Exception as retry_exc:\n                if new_stream is not None:\n                    await new_stream.aclose()\n                    new_stream = None\n                if not _is_retryable(retry_exc) or attempt >= max_attempts:\n                    raise\n                retry_delay = _compute_backoff(attempt)\n                logger.warning(\n                    \"LLM stream retry failed (attempt %d/%d): %s. \"\n                    \"Retrying in %.1fs …\",\n                    attempt,\n                    max_attempts,\n                    retry_exc,\n                    retry_delay,\n                )\n                await asyncio.sleep(retry_delay)\n"
  },
  {
    "path": "src/copaw/security/__init__.py",
    "content": "# -*- coding: utf-8 -*-\n\"\"\"\nSecurity framework for CoPaw.\n\nThis package centralises all security-related mechanisms:\n\n* **Tool-call guarding** (``copaw.security.tool_guard``)\n  Pre-execution parameter scanning to detect dangerous tool usage\n  patterns (command injection, data exfiltration, etc.).\n* **Skill scanning** (``copaw.security.skill_scanner``)\n  Static analysis of skill directories before install / activation.\n\nSub-modules are kept independent so each concern can evolve (or be\ndisabled) without affecting the others.  Import-time cost is near-zero\nbecause heavy dependencies are lazily loaded inside each sub-module.\n\"\"\"\n"
  },
  {
    "path": "src/copaw/security/skill_scanner/__init__.py",
    "content": "# -*- coding: utf-8 -*-\n\"\"\"\nSkill security scanner for CoPaw.\n\nScans skills for security threats before they are activated or installed.\n\nArchitecture\n~~~~~~~~~~~~\n\nThe scanner follows a lightweight, extensible design:\n\n* **BaseAnalyzer** - abstract interface every analyzer must implement.\n* **PatternAnalyzer** - YAML regex-signature matching (fast, line-based).\n* **SkillScanner** - orchestrator that runs registered analyzers and\n  aggregates findings into a :class:`ScanResult`.\n\nThis branch intentionally ships the baseline pattern analyzer only.\nAdditional analyzers can be plugged in later without changing the\norchestrator.\n\nQuick start::\n\n    from copaw.security.skill_scanner import SkillScanner\n\n    scanner = SkillScanner()\n    result = scanner.scan_skill(\"/path/to/skill_directory\")\n    if not result.is_safe:\n        print(f\"Blocked: {result.max_severity.value} findings detected\")\n\"\"\"\nfrom __future__ import annotations\n\nfrom concurrent import futures\nimport hashlib\nimport json\nimport logging\nimport os\nimport threading\nfrom dataclasses import dataclass, field\nfrom datetime import datetime, timezone\nfrom pathlib import Path\nfrom typing import Any\n\nfrom .models import (\n    Finding,\n    ScanResult,\n    Severity,\n    SkillFile,\n    ThreatCategory,\n)\nfrom .scan_policy import ScanPolicy\nfrom .analyzers import BaseAnalyzer\nfrom .analyzers.pattern_analyzer import PatternAnalyzer\nfrom .scanner import SkillScanner\n\nlogger = logging.getLogger(__name__)\n\n__all__ = [\n    \"BaseAnalyzer\",\n    \"BlockedSkillRecord\",\n    \"Finding\",\n    \"PatternAnalyzer\",\n    \"ScanPolicy\",\n    \"ScanResult\",\n    \"Severity\",\n    \"SkillFile\",\n    \"SkillScanner\",\n    \"SkillScanError\",\n    \"ThreatCategory\",\n    \"compute_skill_content_hash\",\n    \"get_blocked_history\",\n    \"clear_blocked_history\",\n    \"remove_blocked_entry\",\n    \"is_skill_whitelisted\",\n    \"scan_skill_directory\",\n]\n\n# ---------------------------------------------------------------------------\n# Config helpers\n# ---------------------------------------------------------------------------\n\n\n_VALID_MODES = {\"block\", \"warn\", \"off\"}\n\n\ndef _load_scanner_config() -> Any:\n    \"\"\"Load SkillScannerConfig from the app config (lazy import).\"\"\"\n    try:\n        from ...config import load_config\n\n        return load_config().security.skill_scanner\n    except Exception:\n        return None\n\n\ndef _get_scan_mode(cfg: Any = None) -> str:\n    \"\"\"Return the effective scan mode: ``block``, ``warn``, or ``off``.\n\n    Priority: env ``COPAW_SKILL_SCAN_MODE`` > config > default ``warn``.\n    \"\"\"\n    env = os.environ.get(\"COPAW_SKILL_SCAN_MODE\")\n    if env is not None:\n        val = env.lower().strip()\n        if val in _VALID_MODES:\n            return val\n    if cfg is None:\n        cfg = _load_scanner_config()\n    return cfg.mode if cfg is not None else \"block\"\n\n\ndef _scan_timeout(cfg: Any = None) -> float:\n    if cfg is None:\n        cfg = _load_scanner_config()\n    return float(cfg.timeout) if cfg is not None else 30.0\n\n\n# ---------------------------------------------------------------------------\n# Content hash\n# ---------------------------------------------------------------------------\n\n\ndef compute_skill_content_hash(skill_dir: Path) -> str:\n    \"\"\"SHA-256 hash of all regular file contents in *skill_dir* (sorted).\"\"\"\n    h = hashlib.sha256()\n    try:\n        for p in sorted(skill_dir.rglob(\"*\")):\n            if p.is_file() and not p.is_symlink():\n                try:\n                    h.update(p.read_bytes())\n                except OSError:\n                    pass\n    except OSError:\n        pass\n    return h.hexdigest()\n\n\n# ---------------------------------------------------------------------------\n# Whitelist helpers\n# ---------------------------------------------------------------------------\n\n\ndef is_skill_whitelisted(\n    skill_name: str,\n    skill_dir: Path | None = None,\n    *,\n    cfg: Any = None,\n) -> bool:\n    \"\"\"Return True if *skill_name* is on the whitelist.\n\n    When a whitelist entry has a non-empty ``content_hash``, the hash must\n    match the current directory contents for the entry to apply.\n    \"\"\"\n    if cfg is None:\n        cfg = _load_scanner_config()\n    if cfg is None:\n        return False\n    for entry in cfg.whitelist:\n        if entry.skill_name != skill_name:\n            continue\n        if not entry.content_hash:\n            return True\n        if skill_dir is not None:\n            current_hash = compute_skill_content_hash(skill_dir)\n            if current_hash == entry.content_hash:\n                return True\n        else:\n            return True\n    return False\n\n\n# ---------------------------------------------------------------------------\n# Blocked history persistence\n# ---------------------------------------------------------------------------\n\n_BLOCKED_HISTORY_FILE = \"skill_scanner_blocked.json\"\n_history_lock = threading.Lock()\n\n\ndef _get_blocked_history_path() -> Path:\n    try:\n        from ...constant import WORKING_DIR\n\n        return WORKING_DIR / _BLOCKED_HISTORY_FILE\n    except Exception:\n        return Path.home() / \".copaw\" / _BLOCKED_HISTORY_FILE\n\n\n@dataclass\nclass BlockedSkillRecord:\n    \"\"\"A record of a scan alert (blocked or warned).\"\"\"\n\n    skill_name: str\n    blocked_at: str\n    max_severity: str\n    findings: list[dict[str, Any]] = field(default_factory=list)\n    content_hash: str = \"\"\n    action: str = \"blocked\"\n\n    def to_dict(self) -> dict[str, Any]:\n        return {\n            \"skill_name\": self.skill_name,\n            \"blocked_at\": self.blocked_at,\n            \"max_severity\": self.max_severity,\n            \"findings\": self.findings,\n            \"content_hash\": self.content_hash,\n            \"action\": self.action,\n        }\n\n    @classmethod\n    def from_dict(cls, data: dict[str, Any]) -> BlockedSkillRecord:\n        return cls(\n            skill_name=data.get(\"skill_name\", \"\"),\n            blocked_at=data.get(\"blocked_at\", \"\"),\n            max_severity=data.get(\"max_severity\", \"\"),\n            findings=data.get(\"findings\", []),\n            content_hash=data.get(\"content_hash\", \"\"),\n            action=data.get(\"action\", \"blocked\"),\n        )\n\n\ndef _finding_to_dict(f: Finding) -> dict[str, Any]:\n    return {\n        \"severity\": f.severity.value,\n        \"title\": f.title,\n        \"description\": f.description,\n        \"file_path\": f.file_path,\n        \"line_number\": f.line_number,\n        \"rule_id\": f.rule_id,\n    }\n\n\ndef _record_blocked_skill(\n    result: ScanResult,\n    skill_dir: Path,\n    *,\n    action: str = \"blocked\",\n) -> None:\n    \"\"\"Append a scan alert to the history file.\"\"\"\n    record = BlockedSkillRecord(\n        skill_name=result.skill_name,\n        blocked_at=datetime.now(timezone.utc).isoformat(),\n        max_severity=result.max_severity.value,\n        findings=[_finding_to_dict(f) for f in result.findings],\n        content_hash=compute_skill_content_hash(skill_dir),\n        action=action,\n    )\n    path = _get_blocked_history_path()\n    with _history_lock:\n        try:\n            existing: list[dict[str, Any]] = []\n            if path.is_file():\n                existing = json.loads(path.read_text(encoding=\"utf-8\"))\n            existing.append(record.to_dict())\n            path.parent.mkdir(parents=True, exist_ok=True)\n            path.write_text(\n                json.dumps(existing, indent=2, ensure_ascii=False),\n                encoding=\"utf-8\",\n            )\n        except Exception as exc:\n            logger.warning(\"Failed to record blocked skill: %s\", exc)\n\n\ndef get_blocked_history() -> list[BlockedSkillRecord]:\n    \"\"\"Load all blocked skill records from disk.\"\"\"\n    path = _get_blocked_history_path()\n    if not path.is_file():\n        return []\n    try:\n        data = json.loads(path.read_text(encoding=\"utf-8\"))\n        return [BlockedSkillRecord.from_dict(d) for d in data]\n    except Exception as exc:\n        logger.warning(\"Failed to load blocked history: %s\", exc)\n        return []\n\n\ndef clear_blocked_history() -> None:\n    \"\"\"Delete all blocked skill records.\"\"\"\n    path = _get_blocked_history_path()\n    try:\n        if path.is_file():\n            path.unlink()\n    except OSError as exc:\n        logger.warning(\"Failed to clear blocked history: %s\", exc)\n\n\ndef remove_blocked_entry(index: int) -> bool:\n    \"\"\"Remove a single blocked record by index. Returns True on success.\"\"\"\n    path = _get_blocked_history_path()\n    if not path.is_file():\n        return False\n    try:\n        data = json.loads(path.read_text(encoding=\"utf-8\"))\n        if 0 <= index < len(data):\n            data.pop(index)\n            path.write_text(\n                json.dumps(data, indent=2, ensure_ascii=False),\n                encoding=\"utf-8\",\n            )\n            return True\n        return False\n    except Exception as exc:\n        logger.warning(\"Failed to remove blocked entry: %s\", exc)\n        return False\n\n\n# ---------------------------------------------------------------------------\n# Lazy singleton (thread-safe)\n# ---------------------------------------------------------------------------\n\n_scanner_instance: SkillScanner | None = None\n_scanner_lock = threading.Lock()\n\n\ndef _get_scanner() -> SkillScanner:\n    \"\"\"Return a lazily-initialised :class:`SkillScanner` singleton.\"\"\"\n    global _scanner_instance\n    if _scanner_instance is None:\n        with _scanner_lock:\n            if _scanner_instance is None:\n                _scanner_instance = SkillScanner()\n    return _scanner_instance\n\n\n# ---------------------------------------------------------------------------\n# Scan result cache (mtime-based)\n# ---------------------------------------------------------------------------\n\n_MAX_CACHE_ENTRIES = 64\n_scan_cache: dict[str, tuple[float, ScanResult]] = {}\n_cache_lock = threading.Lock()\n\n\ndef _get_dir_mtime(skill_dir: Path) -> float:\n    \"\"\"Return the latest mtime among the directory and its immediate files.\"\"\"\n    try:\n        latest = skill_dir.stat().st_mtime\n    except OSError:\n        return 0.0\n    try:\n        for p in skill_dir.iterdir():\n            if p.is_file() and not p.is_symlink():\n                latest = max(latest, p.stat().st_mtime)\n    except OSError:\n        pass\n    return latest\n\n\ndef _get_cached_result(\n    skill_dir: Path,\n) -> ScanResult | None:\n    \"\"\"Return a cached ScanResult if the directory hasn't changed.\"\"\"\n    key = str(skill_dir)\n    with _cache_lock:\n        entry = _scan_cache.get(key)\n    if entry is None:\n        return None\n    cached_mtime, cached_result = entry\n    current_mtime = _get_dir_mtime(skill_dir)\n    if current_mtime == cached_mtime:\n        logger.debug(\n            \"Returning cached scan result for '%s'\",\n            cached_result.skill_name,\n        )\n        return cached_result\n    return None\n\n\ndef _store_cached_result(\n    skill_dir: Path,\n    result: ScanResult,\n) -> None:\n    \"\"\"Store a scan result in the cache (LRU eviction).\"\"\"\n    key = str(skill_dir)\n    mtime = _get_dir_mtime(skill_dir)\n    with _cache_lock:\n        _scan_cache.pop(key, None)\n        _scan_cache[key] = (mtime, result)\n        while len(_scan_cache) > _MAX_CACHE_ENTRIES:\n            oldest = next(iter(_scan_cache))\n            del _scan_cache[oldest]\n\n\n# ---------------------------------------------------------------------------\n# Public API\n# ---------------------------------------------------------------------------\n\n\ndef _format_finding_location(f: Finding) -> str:\n    if f.line_number is not None:\n        return f\"({f.file_path}:{f.line_number})\"\n    return f\"({f.file_path})\"\n\n\nclass SkillScanError(Exception):\n    \"\"\"Raised when a skill fails a security scan and blocking is enabled.\"\"\"\n\n    def __init__(self, result: ScanResult) -> None:\n        self.result = result\n        findings_summary = \"; \".join(\n            f\"[{f.severity.value}] {f.title} \" f\"{_format_finding_location(f)}\"\n            for f in result.findings[:5]\n        )\n        truncated = (\n            f\" (and {len(result.findings) - 5} more)\"\n            if len(result.findings) > 5\n            else \"\"\n        )\n        super().__init__(\n            f\"Security scan of skill '{result.skill_name}' found \"\n            f\"{len(result.findings)} issue(s) \"\n            f\"(max severity: {result.max_severity.value}): \"\n            f\"{findings_summary}{truncated}\",\n        )\n\n\ndef scan_skill_directory(\n    skill_dir: str | Path,\n    *,\n    skill_name: str | None = None,\n    block: bool | None = None,\n    timeout: float | None = None,\n) -> ScanResult | None:\n    \"\"\"Scan a skill directory and optionally block on unsafe results.\n\n    Parameters\n    ----------\n    skill_dir:\n        Path to the skill directory to scan.\n    skill_name:\n        Human-readable name (falls back to directory name).\n    block:\n        Whether to raise :class:`SkillScanError` when the scan finds\n        CRITICAL/HIGH issues.  *None* means use the configured mode\n        (``block`` mode → True, ``warn`` mode → False).\n    timeout:\n        Maximum seconds to wait for the scan to complete before\n        giving up and returning ``None``.  *None* reads from config.\n\n    Returns\n    -------\n    ScanResult or None\n        ``None`` when scanning is disabled, whitelisted, or timed out.\n\n    Raises\n    ------\n    SkillScanError\n        When blocking is enabled and the skill is deemed unsafe.\n    \"\"\"\n    cfg = _load_scanner_config()\n    mode = _get_scan_mode(cfg)\n    if mode == \"off\":\n        return None\n\n    resolved = Path(skill_dir).resolve()\n    effective_name = skill_name or resolved.name\n\n    if is_skill_whitelisted(effective_name, resolved, cfg=cfg):\n        logger.debug(\n            \"Skill '%s' is whitelisted, skipping scan\",\n            effective_name,\n        )\n        return None\n\n    effective_timeout = timeout if timeout is not None else _scan_timeout(cfg)\n\n    cached = _get_cached_result(resolved)\n    if cached is not None:\n        result = cached\n    else:\n        scanner = _get_scanner()\n\n        with futures.ThreadPoolExecutor(max_workers=1) as executor:\n            future = executor.submit(\n                scanner.scan_skill,\n                resolved,\n                skill_name=skill_name,\n            )\n            try:\n                result = future.result(timeout=effective_timeout)\n            except futures.TimeoutError:\n                logger.warning(\n                    \"Security scan of skill '%s' timed out after %.0fs\",\n                    effective_name,\n                    effective_timeout,\n                )\n                future.cancel()\n                return None\n\n        _store_cached_result(resolved, result)\n\n    if not result.is_safe:\n        should_block = block if block is not None else (mode == \"block\")\n        if should_block:\n            _record_blocked_skill(result, resolved, action=\"blocked\")\n            raise SkillScanError(result)\n        _record_blocked_skill(result, resolved, action=\"warned\")\n        logger.warning(\n            \"Skill '%s' has %d security finding(s) (max severity: %s) \"\n            \"but blocking is disabled – proceeding anyway.\",\n            result.skill_name,\n            len(result.findings),\n            result.max_severity.value,\n        )\n\n    return result\n"
  },
  {
    "path": "src/copaw/security/skill_scanner/analyzers/__init__.py",
    "content": "# -*- coding: utf-8 -*-\n\"\"\"Abstract base class for all security analyzers.\n\nEvery analyzer must subclass :class:`BaseAnalyzer` and implement\n:meth:`analyze`.  The interface is intentionally minimal so that\nnew detection engines (e.g. LLM-based, behavioural dataflow) can be\nadded as drop-in plugins without touching the scanner orchestrator.\n\"\"\"\nfrom __future__ import annotations\n\nfrom abc import ABC, abstractmethod\nfrom pathlib import Path\nfrom typing import TYPE_CHECKING\n\nfrom ..models import Finding, SkillFile\n\nif TYPE_CHECKING:\n    from ..scan_policy import ScanPolicy\n\n\nclass BaseAnalyzer(ABC):\n    \"\"\"Abstract base class for all security analyzers.\n\n    Parameters\n    ----------\n    name:\n        Human-readable analyzer name (used in :attr:`Finding.analyzer`).\n    policy:\n        Optional :class:`ScanPolicy` for org-specific rule scoping,\n        severity overrides, and allowlists.  When *None*, analysers\n        use their own built-in defaults.\n    \"\"\"\n\n    def __init__(\n        self,\n        name: str,\n        *,\n        policy: \"ScanPolicy | None\" = None,\n    ) -> None:\n        self.name = name\n        # Lazily import to avoid circular dependencies\n        if policy is None:\n            from ..scan_policy import ScanPolicy\n\n            policy = ScanPolicy.default()\n        self._policy = policy\n\n    @property\n    def policy(self) -> \"ScanPolicy\":\n        \"\"\"The active scan policy.\"\"\"\n        return self._policy\n\n    # ------------------------------------------------------------------\n    # Abstract interface\n    # ------------------------------------------------------------------\n\n    @abstractmethod\n    def analyze(\n        self,\n        skill_dir: Path,\n        files: list[SkillFile],\n        *,\n        skill_name: str | None = None,\n    ) -> list[Finding]:\n        \"\"\"Analyze a skill package for security issues.\n\n        Parameters\n        ----------\n        skill_dir:\n            Root directory of the skill.\n        files:\n            Pre-discovered list of :class:`SkillFile` objects belonging\n            to the skill.\n        skill_name:\n            Optional skill name for richer finding messages.\n\n        Returns\n        -------\n        list[Finding]\n            Findings discovered by this analyzer.\n        \"\"\"\n\n    # ------------------------------------------------------------------\n    # Helpers\n    # ------------------------------------------------------------------\n\n    def get_name(self) -> str:  # noqa: D401\n        \"\"\"Analyzer name.\"\"\"\n        return self.name\n"
  },
  {
    "path": "src/copaw/security/skill_scanner/analyzers/pattern_analyzer.py",
    "content": "# -*- coding: utf-8 -*-\n\"\"\"YAML-signature pattern matching analyzer.\n\nLoads security rules from YAML files (see ``rules/signatures/``) and\nperforms fast, line-based regex matching with a multiline fallback for\npatterns that intentionally span newlines.\n\"\"\"\nfrom __future__ import annotations\n\nimport logging\nimport re\nfrom pathlib import Path\nfrom typing import Any\n\nimport yaml\n\nfrom ..models import Finding, Severity, SkillFile, ThreatCategory\nfrom ..scan_policy import ScanPolicy\nfrom . import BaseAnalyzer\n\nlogger = logging.getLogger(__name__)\n\n# Matches character-class contents so we can tell whether ``\\n`` in a\n# pattern is genuinely multiline vs. ``[^\\n]``.\n_CHAR_CLASS_RE = re.compile(r\"\\[[^\\]]*\\]\")\n\n# Default signatures directory (shipped with the package).\n_DEFAULT_SIGNATURES_DIR = (\n    Path(__file__).resolve().parent.parent / \"rules\" / \"signatures\"\n)\n\n\n# ---------------------------------------------------------------------------\n# SecurityRule – one YAML rule entry\n# ---------------------------------------------------------------------------\n\n\nclass SecurityRule:\n    \"\"\"A single regex-based security detection rule.\"\"\"\n\n    __slots__ = (\n        \"id\",\n        \"category\",\n        \"severity\",\n        \"patterns\",\n        \"exclude_patterns\",\n        \"file_types\",\n        \"description\",\n        \"remediation\",\n        \"compiled_patterns\",\n        \"compiled_exclude_patterns\",\n    )\n\n    def __init__(self, rule_data: dict[str, Any]) -> None:\n        self.id: str = rule_data[\"id\"]\n        self.category = ThreatCategory(rule_data[\"category\"])\n        self.severity = Severity(rule_data[\"severity\"])\n        self.patterns: list[str] = rule_data[\"patterns\"]\n        self.exclude_patterns: list[str] = rule_data.get(\n            \"exclude_patterns\",\n            [],\n        )\n        self.file_types: list[str] = rule_data.get(\"file_types\", [])\n        self.description: str = rule_data[\"description\"]\n        self.remediation: str = rule_data.get(\"remediation\", \"\")\n\n        self.compiled_patterns: list[re.Pattern[str]] = []\n        for pat in self.patterns:\n            try:\n                self.compiled_patterns.append(re.compile(pat))\n            except re.error as exc:\n                logger.warning(\"Bad regex in rule %s: %s\", self.id, exc)\n\n        self.compiled_exclude_patterns: list[re.Pattern[str]] = []\n        for pat in self.exclude_patterns:\n            try:\n                self.compiled_exclude_patterns.append(re.compile(pat))\n            except re.error as exc:\n                logger.warning(\n                    \"Bad exclude regex in rule %s: %s\",\n                    self.id,\n                    exc,\n                )\n\n    # ------------------------------------------------------------------\n\n    def matches_file_type(self, file_type: str) -> bool:\n        \"\"\"Return *True* if this rule applies to *file_type*.\"\"\"\n        if not self.file_types:\n            return True\n        return file_type in self.file_types\n\n    def scan_content(\n        self,\n        content: str,\n        file_path: str | None = None,\n    ) -> list[dict[str, Any]]:\n        \"\"\"Scan *content* for rule violations.\n\n        Returns a list of match dicts with ``line_number``, ``line_content``,\n        ``matched_pattern``, ``matched_text``, and ``file_path``.\n        \"\"\"\n        matches: list[dict[str, Any]] = []\n        lines = content.split(\"\\n\")\n\n        # --- Pass 1: line-based matching (fast) --------------------------\n        for line_num, line in enumerate(lines, start=1):\n            excluded = any(\n                ep.search(line) for ep in self.compiled_exclude_patterns\n            )\n            if excluded:\n                continue\n            for pattern in self.compiled_patterns:\n                m = pattern.search(line)\n                if m:\n                    matches.append(\n                        {\n                            \"line_number\": line_num,\n                            \"line_content\": line.strip(),\n                            \"matched_pattern\": pattern.pattern,\n                            \"matched_text\": m.group(0),\n                            \"file_path\": file_path,\n                        },\n                    )\n\n        # --- Pass 2: multiline patterns ----------------------------------\n        for pattern in self.compiled_patterns:\n            stripped = _CHAR_CLASS_RE.sub(\"\", pattern.pattern)\n            if \"\\\\n\" not in stripped:\n                continue\n            for m in pattern.finditer(content):\n                matched_text = m.group(0)\n                excluded = any(\n                    ep.search(matched_text)\n                    for ep in self.compiled_exclude_patterns\n                )\n                if excluded:\n                    continue\n                start_line = content.count(\"\\n\", 0, m.start()) + 1\n                snippet = (\n                    lines[start_line - 1].strip()\n                    if 0 <= start_line - 1 < len(lines)\n                    else \"\"\n                )\n                matches.append(\n                    {\n                        \"line_number\": start_line,\n                        \"line_content\": snippet,\n                        \"matched_pattern\": pattern.pattern,\n                        \"matched_text\": matched_text[:200],\n                        \"file_path\": file_path,\n                    },\n                )\n\n        return matches\n\n\n# ---------------------------------------------------------------------------\n# RuleLoader\n# ---------------------------------------------------------------------------\n\n\nclass RuleLoader:\n    \"\"\"Loads :class:`SecurityRule` objects from YAML files.\"\"\"\n\n    def __init__(self, rules_path: Path | None = None) -> None:\n        self.rules_path = rules_path or _DEFAULT_SIGNATURES_DIR\n        self.rules: list[SecurityRule] = []\n        self.rules_by_id: dict[str, SecurityRule] = {}\n        self.rules_by_category: dict[ThreatCategory, list[SecurityRule]] = {}\n\n    def load_rules(self) -> list[SecurityRule]:\n        \"\"\"Load and index all rules from the configured path.\"\"\"\n        path = Path(self.rules_path)\n        if path.is_dir():\n            raw: list[dict[str, Any]] = []\n            for yaml_file in sorted(path.glob(\"*.yaml\")):\n                try:\n                    with open(yaml_file, encoding=\"utf-8\") as fh:\n                        data = yaml.safe_load(fh)\n                except Exception as exc:\n                    raise RuntimeError(\n                        f\"Failed to load {yaml_file}: {exc}\",\n                    ) from exc\n                if not isinstance(data, list):\n                    raise RuntimeError(f\"Expected list in {yaml_file}\")\n                raw.extend(data)\n        else:\n            try:\n                with open(path, encoding=\"utf-8\") as fh:\n                    raw = yaml.safe_load(fh)\n            except Exception as exc:\n                raise RuntimeError(f\"Failed to load {path}: {exc}\") from exc\n            if not isinstance(raw, list):\n                raise RuntimeError(f\"Expected list in {path}\")\n\n        self.rules = []\n        self.rules_by_id = {}\n        self.rules_by_category = {}\n\n        for entry in raw:\n            try:\n                rule = SecurityRule(entry)\n                self.rules.append(rule)\n                self.rules_by_id[rule.id] = rule\n                self.rules_by_category.setdefault(rule.category, []).append(\n                    rule,\n                )\n            except Exception as exc:\n                logger.warning(\n                    \"Skipping rule %s: %s\",\n                    entry.get(\"id\", \"?\"),\n                    exc,\n                )\n\n        return self.rules\n\n    def get_rule(self, rule_id: str) -> SecurityRule | None:\n        return self.rules_by_id.get(rule_id)\n\n    def get_rules_for_file_type(self, file_type: str) -> list[SecurityRule]:\n        return [r for r in self.rules if r.matches_file_type(file_type)]\n\n    def get_rules_for_category(\n        self,\n        category: ThreatCategory,\n    ) -> list[SecurityRule]:\n        return self.rules_by_category.get(category, [])\n\n\n# ---------------------------------------------------------------------------\n# PatternAnalyzer\n# ---------------------------------------------------------------------------\n\n\nclass PatternAnalyzer(BaseAnalyzer):\n    \"\"\"Analyzer that matches YAML regex signatures against skill files.\n\n    Parameters\n    ----------\n    rules_path:\n        Path to a YAML file or a directory of YAML files.  Defaults to\n        the ``rules/signatures/`` directory shipped with the package.\n    policy:\n        Optional :class:`ScanPolicy` for rule disabling, severity\n        overrides, and doc-path skipping.\n    \"\"\"\n\n    def __init__(\n        self,\n        rules_path: Path | None = None,\n        *,\n        policy: ScanPolicy | None = None,\n    ) -> None:\n        super().__init__(name=\"pattern\", policy=policy)\n        loader = RuleLoader(rules_path)\n        self._rules = loader.load_rules()\n        self._rules_by_file_type: dict[str, list[SecurityRule]] = {}\n        logger.debug(\"PatternAnalyzer loaded %d rules\", len(self._rules))\n\n    # ------------------------------------------------------------------\n    # BaseAnalyzer interface\n    # ------------------------------------------------------------------\n\n    def analyze(\n        self,\n        skill_dir: Path,\n        files: list[SkillFile],\n        *,\n        skill_name: str | None = None,\n    ) -> list[Finding]:\n        findings: list[Finding] = []\n        skip_in_docs = self.policy.rule_scoping.skip_in_docs\n\n        for sf in files:\n            content = sf.read_content()\n            if not content:\n                continue\n\n            is_doc = self.policy.is_doc_path(sf.relative_path)\n\n            applicable = self._get_rules(sf.file_type)\n            for rule in applicable:\n                # --- Policy-based rule filtering ---\n                # Skip disabled rules early\n                if self.policy.is_rule_disabled(rule.id):\n                    continue\n                # Skip doc-only exclusions\n                if is_doc and rule.id in skip_in_docs:\n                    continue\n                # Code-only rules should not fire on non-code files\n                if rule.id in self.policy.rule_scoping.code_only:\n                    if sf.file_type not in (\n                        \"python\",\n                        \"bash\",\n                        \"javascript\",\n                        \"typescript\",\n                    ):\n                        continue\n\n                matches = rule.scan_content(\n                    content,\n                    file_path=sf.relative_path,\n                )\n                for match in matches:\n                    # Apply severity override if configured\n                    severity = rule.severity\n                    override = self.policy.get_severity_override(rule.id)\n                    if override:\n                        try:\n                            severity = Severity(override)\n                        except ValueError:\n                            pass\n\n                    findings.append(\n                        Finding(\n                            id=(\n                                f\"{rule.id}:{sf.relative_path}\"\n                                f\":{match['line_number']}\"\n                            ),\n                            rule_id=rule.id,\n                            category=rule.category,\n                            severity=severity,\n                            title=rule.description,\n                            description=rule.description,\n                            file_path=sf.relative_path,\n                            line_number=match[\"line_number\"],\n                            snippet=match[\"line_content\"],\n                            remediation=rule.remediation,\n                            analyzer=self.name,\n                            metadata={\n                                \"matched_pattern\": match[\"matched_pattern\"],\n                                \"matched_text\": match[\"matched_text\"],\n                            },\n                        ),\n                    )\n\n        # Filter well-known test credentials\n        findings = [\n            f for f in findings if not self._is_known_test_credential(f)\n        ]\n\n        # De-duplicate if enabled in policy\n        if self.policy.rule_scoping.dedupe_duplicate_findings:\n            findings = self._dedupe_findings(findings)\n\n        return findings\n\n    # ------------------------------------------------------------------\n    # Credential filtering\n    # ------------------------------------------------------------------\n\n    def _is_known_test_credential(self, finding: Finding) -> bool:\n        \"\"\"Suppress findings that match known test/placeholder credentials.\"\"\"\n        if finding.category != ThreatCategory.HARDCODED_SECRETS:\n            return False\n        snippet = (finding.snippet or \"\").lower()\n        for cred in self.policy.credentials.known_test_values:\n            if cred.lower() in snippet:\n                return True\n        for marker in self.policy.credentials.placeholder_markers:\n            if marker.lower() in snippet:\n                return True\n        return False\n\n    # ------------------------------------------------------------------\n    # De-duplication\n    # ------------------------------------------------------------------\n\n    @staticmethod\n    def _dedupe_findings(findings: list[Finding]) -> list[Finding]:\n        \"\"\"Remove exact duplicate findings (same rule + file + line).\"\"\"\n        seen: set[str] = set()\n        unique: list[Finding] = []\n        for f in findings:\n            key = f\"{f.rule_id}:{f.file_path}:{f.line_number}\"\n            if key not in seen:\n                seen.add(key)\n                unique.append(f)\n        return unique\n\n    # ------------------------------------------------------------------\n    # Internals\n    # ------------------------------------------------------------------\n\n    def _get_rules(self, file_type: str) -> list[SecurityRule]:\n        \"\"\"Return rules applicable to *file_type* (cached).\"\"\"\n        if file_type not in self._rules_by_file_type:\n            self._rules_by_file_type[file_type] = [\n                r for r in self._rules if r.matches_file_type(file_type)\n            ]\n        return self._rules_by_file_type[file_type]\n"
  },
  {
    "path": "src/copaw/security/skill_scanner/data/default_policy.yaml",
    "content": "# CoPaw Skill Scanner – Default Scan Policy\n# ============================================\n# This file defines the built-in security policy.  Every setting here can be\n# overridden in an organisation-specific policy file passed via --policy.\n#\n# To use a custom policy:\n#   scanner = SkillScanner(policy=ScanPolicy.from_yaml(\"my_org_policy.yaml\"))\n\npolicy_name: default\npolicy_version: \"1.0\"\npreset_base: balanced\n\n# ---------------------------------------------------------------------------\n# Hidden files – which dotfiles and dotdirs are considered benign\n# ---------------------------------------------------------------------------\nhidden_files:\n  benign_dotfiles:\n    - \".gitignore\"\n    - \".gitattributes\"\n    - \".gitmodules\"\n    - \".gitkeep\"\n    - \".editorconfig\"\n    - \".prettierrc\"\n    - \".prettierignore\"\n    - \".eslintrc\"\n    - \".eslintignore\"\n    - \".eslintrc.json\"\n    - \".eslintrc.js\"\n    - \".eslintrc.yml\"\n    - \".npmrc\"\n    - \".npmignore\"\n    - \".nvmrc\"\n    - \".node-version\"\n    - \".python-version\"\n    - \".ruby-version\"\n    - \".tool-versions\"\n    - \".flake8\"\n    - \".pylintrc\"\n    - \".isort.cfg\"\n    - \".mypy.ini\"\n    - \".babelrc\"\n    - \".browserslistrc\"\n    - \".dockerignore\"\n    - \".env.example\"\n    - \".env.sample\"\n    - \".env.template\"\n    - \".markdownlint.json\"\n    - \".markdownlintignore\"\n    - \".yamllint\"\n    - \".yamllint.yml\"\n    - \".cursorrules\"\n    - \".cursorignore\"\n    - \".clang-format\"\n    - \".clang-tidy\"\n    - \".mcp.json\"\n    - \".envrc\"\n    - \".version\"\n\n  benign_dotdirs:\n    - \".github\"\n    - \".vscode\"\n    - \".idea\"\n    - \".cursor\"\n    - \".husky\"\n    - \".circleci\"\n    - \".gitlab\"\n    - \".cache\"\n    - \".tmp\"\n    - \".data\"\n    - \".next\"\n    - \".nuxt\"\n    - \".claude\"\n    - \".devcontainer\"\n    - \".vitepress\"\n    - \".docusaurus\"\n    - \".storybook\"\n\n# ---------------------------------------------------------------------------\n# Rule scoping – which rules fire where\n# ---------------------------------------------------------------------------\nrule_scoping:\n  skip_in_docs:\n    - \"COMMAND_INJECTION_EVAL\"\n    - \"COMMAND_INJECTION_OS_SYSTEM\"\n    - \"COMMAND_INJECTION_SHELL_TRUE\"\n    - \"RESOURCE_ABUSE_INFINITE_LOOP\"\n\n  code_only:\n    - \"COMMAND_INJECTION_EVAL\"\n    - \"COMMAND_INJECTION_OS_SYSTEM\"\n    - \"COMMAND_INJECTION_SHELL_TRUE\"\n    - \"RESOURCE_ABUSE_INFINITE_LOOP\"\n\n  doc_path_indicators:\n    - \"docs\"\n    - \"doc\"\n    - \"examples\"\n    - \"example\"\n    - \"tutorials\"\n    - \"tutorial\"\n    - \"guides\"\n    - \"guide\"\n    - \"samples\"\n    - \"sample\"\n    - \"demo\"\n    - \"demos\"\n    - \"tests\"\n    - \"test\"\n\n  doc_filename_patterns:\n    - \"readme\"\n    - \"example\"\n    - \"tutorial\"\n    - \"sample\"\n    - \"demo\"\n    - \"howto\"\n    - \"guide\"\n\n  dedupe_duplicate_findings: true\n\n# ---------------------------------------------------------------------------\n# Credentials – known test/placeholder values to auto-suppress\n# ---------------------------------------------------------------------------\ncredentials:\n  known_test_values:\n    - \"test\"\n    - \"test123\"\n    - \"password\"\n    - \"changeme\"\n    - \"example\"\n    - \"dummy\"\n    - \"placeholder\"\n    - \"your-api-key\"\n    - \"your_api_key\"\n    - \"sk-test\"\n    - \"pk-test\"\n    - \"xxx\"\n    - \"abc123\"\n    - \"secret\"\n    - \"foobar\"\n\n  placeholder_markers:\n    - \"your-\"\n    - \"your_\"\n    - \"your \"\n    - \"example\"\n    - \"sample\"\n    - \"dummy\"\n    - \"placeholder\"\n    - \"replace\"\n    - \"changeme\"\n    - \"change_me\"\n    - \" str:\n        \"\"\"Read file content if not already loaded.\"\"\"\n        if self.content is None and self.path.exists():\n            try:\n                with open(self.path, encoding=\"utf-8\") as f:\n                    self.content = f.read()\n            except (OSError, UnicodeDecodeError):\n                self.content = \"\"\n        return self.content or \"\"\n\n    @property\n    def is_hidden(self) -> bool:\n        \"\"\"Check if file is a dotfile or inside a hidden dir.\"\"\"\n        parts = Path(self.relative_path).parts\n        return any(part.startswith(\".\") and part != \".\" for part in parts)\n\n    # ------------------------------------------------------------------\n    # Factory helpers\n    # ------------------------------------------------------------------\n\n    @classmethod\n    def from_path(cls, path: Path, base_dir: Path) -> \"SkillFile\":\n        \"\"\"Create a SkillFile from an on-disk path relative to *base_dir*.\"\"\"\n        rel = str(path.relative_to(base_dir))\n        suffix = path.suffix.lower()\n        file_type = _FILE_TYPE_MAP.get(suffix, \"other\")\n        try:\n            size = path.stat().st_size\n        except OSError:\n            size = 0\n        return cls(\n            path=path,\n            relative_path=rel,\n            file_type=file_type,\n            size_bytes=size,\n        )\n\n\n# ---------------------------------------------------------------------------\n# Finding\n# ---------------------------------------------------------------------------\n\n\n@dataclass\nclass Finding:\n    \"\"\"A security issue discovered during a skill scan.\"\"\"\n\n    id: str\n    rule_id: str\n    category: ThreatCategory\n    severity: Severity\n    title: str\n    description: str\n    file_path: str | None = None\n    line_number: int | None = None\n    snippet: str | None = None\n    remediation: str | None = None\n    analyzer: str | None = None\n    metadata: dict[str, Any] = field(default_factory=dict)\n\n    def to_dict(self) -> dict[str, Any]:\n        return {\n            \"id\": self.id,\n            \"rule_id\": self.rule_id,\n            \"category\": self.category.value,\n            \"severity\": self.severity.value,\n            \"title\": self.title,\n            \"description\": self.description,\n            \"file_path\": self.file_path,\n            \"line_number\": self.line_number,\n            \"snippet\": self.snippet,\n            \"remediation\": self.remediation,\n            \"analyzer\": self.analyzer,\n            \"metadata\": self.metadata,\n        }\n\n\n# ---------------------------------------------------------------------------\n# Scan result\n# ---------------------------------------------------------------------------\n\n\n@dataclass\nclass ScanResult:\n    \"\"\"Aggregated results from scanning a single skill.\"\"\"\n\n    skill_name: str\n    skill_directory: str\n    findings: list[Finding] = field(default_factory=list)\n    scan_duration_seconds: float = 0.0\n    analyzers_used: list[str] = field(default_factory=list)\n    analyzers_failed: list[dict[str, str]] = field(default_factory=list)\n    timestamp: datetime = field(\n        default_factory=lambda: datetime.now(timezone.utc),\n    )\n\n    # ------------------------------------------------------------------\n    # Convenience properties\n    # ------------------------------------------------------------------\n\n    @property\n    def is_safe(self) -> bool:\n        \"\"\"``True`` when there are no CRITICAL or HIGH findings.\"\"\"\n        return not any(\n            f.severity in (Severity.CRITICAL, Severity.HIGH)\n            for f in self.findings\n        )\n\n    @property\n    def max_severity(self) -> Severity:\n        \"\"\"Return the highest severity found, or ``SAFE``.\"\"\"\n        if not self.findings:\n            return Severity.SAFE\n        order = [\n            Severity.CRITICAL,\n            Severity.HIGH,\n            Severity.MEDIUM,\n            Severity.LOW,\n            Severity.INFO,\n        ]\n        for sev in order:\n            if any(f.severity == sev for f in self.findings):\n                return sev\n        return Severity.SAFE\n\n    def get_findings_by_severity(self, severity: Severity) -> list[Finding]:\n        return [f for f in self.findings if f.severity == severity]\n\n    def get_findings_by_category(\n        self,\n        category: ThreatCategory,\n    ) -> list[Finding]:\n        return [f for f in self.findings if f.category == category]\n\n    def to_dict(self) -> dict[str, Any]:\n        result: dict[str, Any] = {\n            \"skill_name\": self.skill_name,\n            \"skill_path\": self.skill_directory,\n            \"is_safe\": self.is_safe,\n            \"max_severity\": self.max_severity.value,\n            \"findings_count\": len(self.findings),\n            \"findings\": [f.to_dict() for f in self.findings],\n            \"scan_duration_seconds\": self.scan_duration_seconds,\n            \"analyzers_used\": self.analyzers_used,\n            \"timestamp\": self.timestamp.isoformat(),\n        }\n        if self.analyzers_failed:\n            result[\"analyzers_failed\"] = self.analyzers_failed\n        return result\n"
  },
  {
    "path": "src/copaw/security/skill_scanner/rules/signatures/command_injection.yaml",
    "content": "# Command & Code Injection Signatures\n# Detects dangerous code execution, shell injection, path traversal, and SQL injection\n\n- id: COMMAND_INJECTION_EVAL\n  category: command_injection\n  severity: CRITICAL\n  patterns:\n    - \"(?]*>[^<]*\"\n    - \"\\\\bon\\\\w+\\\\s*=\\\\s*[\\\"'][^\\\"']*[\\\"']\"\n    - \"javascript\\\\s*:\"\n  file_types: [other]\n  description: \"SVG file contains embedded script tags or event handlers that can execute JavaScript\"\n  remediation: \"Remove all