tg-agent 0.1.12__tar.gz

tg_agent-0.1.12/.codex-staging/feature-dev/README.md

@@ -0,0 +1,15 @@
+# feature-dev
+
+Codex skill adapted from the Claude `feature-dev` plugin.
+
+It provides a structured workflow for feature delivery:
+
+1. Discovery
+2. Codebase exploration
+3. Clarifying questions
+4. Architecture design
+5. Implementation
+6. Quality review
+7. Summary
+
+Primary entrypoint: [`SKILL.md`](./SKILL.md)

tg_agent-0.1.12/.codex-staging/feature-dev/SKILL.md

@@ -0,0 +1,120 @@
+---
+name: feature-dev
+description: Structured feature development workflow with codebase exploration, architecture tradeoffs, implementation gating, and review
+version: 1.0.0
+metadata:
+  source: claude-plugins-official/feature-dev
+---
+
+# Feature Dev Skill
+
+Use this skill when the user wants to build a new feature and would benefit from a deliberate workflow instead of immediate implementation.
+
+## Goal
+
+Drive feature work through seven phases:
+
+1. Discovery
+2. Codebase exploration
+3. Clarifying questions
+4. Architecture design
+5. Implementation
+6. Quality review
+7. Summary
+
+## Operating Rules
+
+- Do not jump straight into code for ambiguous feature work.
+- Read the codebase before proposing implementation details.
+- Ask clarifying questions after exploration and before architecture selection.
+- Present concrete tradeoffs, not abstract options.
+- Do not start implementation until the user approves an approach.
+- After implementation, run a review pass focused on bugs, regressions, and convention mismatches.
+
+## Workflow
+
+### 1. Discovery
+
+- Restate the feature request in concrete terms.
+- If the request is underspecified, ask what problem is being solved, required behavior, constraints, and non-goals.
+- Create a task plan that tracks all seven phases.
+
+### 2. Codebase Exploration
+
+Investigate the codebase from multiple angles. Parallelize local reads and searches when possible.
+
+Cover at least these perspectives:
+- Similar or adjacent features
+- Relevant architecture layers and extension points
+- Existing tests, conventions, and user flows
+
+For each perspective, produce:
+- Key files with path references
+- Relevant control flow and abstractions
+- Constraints that affect implementation
+
+After exploration, read the most important files and summarize patterns that the new feature should follow.
+
+### 3. Clarifying Questions
+
+Before designing the solution, identify ambiguities such as:
+- Edge cases
+- Error handling
+- Scope boundaries
+- Integration points
+- Backward compatibility
+- Performance or security requirements
+
+Ask the user a concise grouped list of questions and wait for answers. If the user delegates the choice, give a recommendation and get explicit confirmation.
+
+### 4. Architecture Design
+
+Develop 2-3 implementation approaches with distinct tradeoffs:
+- Minimal changes
+- Clean architecture
+- Pragmatic balance
+
+For each approach, include:
+- Files to change or create
+- Main abstractions
+- Benefits
+- Costs and risks
+
+Recommend one approach and explain why it fits this codebase and request. Ask the user which approach to use.
+
+### 5. Implementation
+
+Do not begin until the user explicitly approves an approach.
+
+When implementing:
+- Follow existing project patterns
+- Keep changes scoped to the agreed design
+- Update the task plan as work progresses
+- Add tests when the codebase supports them
+
+### 6. Quality Review
+
+Review the resulting changes from three lenses:
+- Simplicity, DRY, and maintainability
+- Bugs, correctness, and regressions
+- Project conventions and abstraction fit
+
+Report the highest-signal findings first. If issues exist, ask whether to fix now, defer, or proceed as-is.
+
+### 7. Summary
+
+Close with:
+- What was built
+- Key decisions
+- Main files changed
+- Remaining risks or next steps
+
+## Specialist Lenses
+
+Use these role prompts internally when useful:
+
+- [code-explorer](references/code-explorer.md): trace feature flows and architecture
+- [code-architect](references/code-architect.md): produce decisive implementation blueprints
+- [code-reviewer](references/code-reviewer.md): review for real bugs and convention drift
+
+You do not need separate agents to use this skill. Reuse the lenses as structured thinking modes during exploration, design, and review.

tg_agent-0.1.12/.codex-staging/feature-dev/references/code-architect.md

@@ -0,0 +1,17 @@
+# Code Architect Lens
+
+Use this lens to design a concrete implementation that fits the codebase.
+
+## Focus
+
+- Reuse established patterns
+- Pick a clear architecture rather than staying vague
+- Map files to create or modify
+- Call out interfaces, data flow, and sequencing
+
+## Output
+
+- Recommended approach
+- Tradeoffs
+- File-by-file implementation map
+- Build sequence and critical details

tg_agent-0.1.12/.codex-staging/feature-dev/references/code-explorer.md

@@ -0,0 +1,17 @@
+# Code Explorer Lens
+
+Use this lens to understand how an existing feature works before changing it.
+
+## Focus
+
+- Find entry points
+- Trace execution flow end to end
+- Identify important abstractions and dependencies
+- Surface existing patterns worth reusing
+
+## Output
+
+- Key files to read
+- Step-by-step flow
+- Data transformations
+- Notable constraints, risks, or technical debt

tg_agent-0.1.12/.codex-staging/feature-dev/references/code-reviewer.md

@@ -0,0 +1,17 @@
+# Code Reviewer Lens
+
+Use this lens after implementation to review only meaningful issues.
+
+## Focus
+
+- Functional correctness
+- Regression risk
+- Convention mismatches
+- Simplicity and maintainability
+
+## Output
+
+- High-signal findings only
+- Concrete file references
+- Specific fix guidance
+- Residual risks if no issues are found

tg_agent-0.1.12/.devcontainer/devcontainer.json

@@ -0,0 +1,6 @@
+{
+	"image": "mcr.microsoft.com/devcontainers/universal:2",
+	"features": {
+		"ghcr.io/devcontainers/features/copilot-cli:1": {}
+	}
+}

tg_agent-0.1.12/.dockerignore

@@ -0,0 +1,13 @@
+__pycache__
+*.py[cod]
+*.egg-info
+.git
+.env
+.venv
+venv
+.pytest_cache
+.ruff_cache
+.mypy_cache
+data/*.db
+tests/
+*.md

tg_agent-0.1.12/.env.example

@@ -0,0 +1,23 @@
+# Telegram API credentials (https://my.telegram.org/apps)
+TG_API_ID=
+TG_API_HASH=
+
+# Web panel password (required)
+WEB_PASS=
+
+# Key for encrypting Telegram session strings in DB (enc:v2)
+SESSION_ENCRYPTION_KEY=
+
+# LLM for AI search (optional)
+LLM_API_KEY=
+
+# AI Agent — Claude API key and OAuth token
+ANTHROPIC_API_KEY=
+CLAUDE_CODE_OAUTH_TOKEN=
+# AI Agent model override (optional, default: anthropic:claude-sonnet-4-6)
+AGENT_MODEL=
+
+# PyPI publishing (used by scripts/release_pypi.sh)
+TWINE_USERNAME=__token__
+TEST_PYPI_TOKEN=pypi-...
+PYPI_TOKEN=pypi-...

tg_agent-0.1.12/.github/copilot-instructions.md

@@ -0,0 +1,41 @@
+# Copilot instructions
+
+## Build, test, and lint commands
+
+- Install dev dependencies: `pip install -e ".[dev]"`
+- Lint: `ruff check src/ tests/ conftest.py`
+- Run parallel-safe tests: `pytest tests/ -v -m "not aiosqlite_serial" -n auto`
+- Run `aiosqlite`-backed tests serially: `pytest tests/ -v -m aiosqlite_serial`
+- Run a single test: `pytest tests/test_web.py::test_health_endpoint -v`
+- Benchmark serial vs safe mixed-mode suite execution: `python -m src.main test benchmark`
+- Run the web app locally: `python -m src.main serve [--web-pass PASS]`
+
+## High-level architecture
+
+This project has three main layers: CLI/Web entry points, Telegram/search/scheduler services, and a single SQLite database.
+
+- `src/main.py` is the main CLI entry point. CLI commands live under `src/cli/commands/`.
+- `src/web/` is a FastAPI web UI over the same underlying logic. Keep CLI and web behavior aligned when changing features.
+- The Telegram layer centers on `ClientPool` for multi-account rotation, `Collector` for message collection, and `Notifier` for Telegram alerts.
+- Collection is orchestrated through `src/services/collection_service.py` and `src/collection_queue.py`: requests are queued, persisted as collection tasks, and processed by a single async worker.
+- Search has multiple backends: local SQLite/FTS search, direct Telegram search, and AI-backed search/agent flows.
+- Storage is a single SQLite database managed asynchronously with `aiosqlite`; schema creation and additive migrations happen in code.
+
+## Key conventions
+
+- Preserve CLI/web parity: features exposed in the web UI should have corresponding CLI behavior and reuse shared logic.
+- This codebase is async-first. Prefer `asyncio` patterns and existing async helpers over introducing sync shortcuts.
+- Use Pydantic v2 APIs such as `model_validate`, not deprecated v1 patterns.
+- Config values support `${ENV_VAR}` substitution, and keys whose value is only `${ENV_VAR}` are dropped entirely if the env var is empty or missing.
+- Incremental collection matters: collection resumes from `last_collected_id` instead of reloading full history unless a full run is explicitly requested.
+- `ClientPool` rotates around flood waits. Reuse its account-selection logic instead of bypassing it.
+- Collection tasks are persisted and processed sequentially through `CollectionQueue`; keep task status transitions and cancellation behavior intact.
+- Filtered channels are normally skipped during collection unless the flow explicitly uses `force=True`.
+- The collector depends on Telegram entity cache warmup before some channel operations. Do not remove cache-priming behavior such as dialog loading without verifying PeerChannel resolution still works.
+- Duplicate messages are tolerated through `INSERT OR IGNORE` with unique constraints; avoid replacing that behavior with manual dedup flows.
+- Web auth is password-based and session tokens are custom HMAC-signed cookies backed by a secret stored in the database.
+- When `SESSION_ENCRYPTION_KEY` is configured, session strings are stored encrypted (`enc:v2:*`); startup should fail fast if encrypted rows exist but the key is missing.
+- Web routes use HTMX progressive enhancement patterns. When a route already branches on `HX-Request`, preserve fragment-vs-redirect behavior.
+- Identifier import flows accept `t.me` links, `@usernames`, negative IDs, and text/file parsing through existing parser helpers; reuse those helpers instead of duplicating parsing logic.
+- Real Telegram tests are opt-in only. Default tests should stay fake/harness-based. Any live pytest must use `real_telegram_sandbox` plus `@pytest.mark.real_tg_safe` or `@pytest.mark.real_tg_manual`.
+- Parallel pytest runs use `pytest-xdist`, and the repository-level worker hook uses `joblib.cpu_count()` to pick `max(1, cpu_count - 1)`. Tests marked `aiosqlite_serial` must stay out of xdist and run in a separate serial pass; live Telegram runs are also forced back to a single worker.

tg_agent-0.1.12/.github/release-metadata/README.md

@@ -0,0 +1,22 @@
+# Release Metadata
+
+Create one JSON file per release tag in this directory before pushing the tag.
+
+Example:
+
+```json
+{
+  "tag": "v0.1.11",
+  "title": "Short Release Title",
+  "highlights": [
+    {
+      "title": "Highlight One",
+      "description": "One-sentence summary for the release notes."
+    }
+  ]
+}
+```
+
+The release workflow reads `.github/release-metadata/<tag>.json`, generates the
+`## What's Changed` section from GitHub, inserts `### Highlights` from this file,
+and publishes the release title as `<tag> — <title>`.

tg_agent-0.1.12/.github/release-metadata/v0.1.10.json

@@ -0,0 +1,14 @@
+{
+  "tag": "v0.1.10",
+  "title": "Deepagents Fallback",
+  "highlights": [
+    {
+      "title": "Explicit Photo Targets",
+      "description": "Require an explicit Telegram target for Photo Loader actions, restore the last selected target per account, and surface clear validation errors for missing or invalid destinations."
+    },
+    {
+      "title": "Agent Fallback Availability",
+      "description": "Keep the /agent flow available when DeepAgents runs through the legacy fallback path and optional provider libraries are not installed."
+    }
+  ]
+}

tg_agent-0.1.12/.github/release-metadata/v0.1.12.json

@@ -0,0 +1,18 @@
+{
+  "tag": "v0.1.12",
+  "title": "PyPI Packaging",
+  "highlights": [
+    {
+      "title": "PyPI-Ready Project Metadata",
+      "description": "Round out the package metadata with project URLs, classifiers, keywords, author information, and an explicit MIT license so the distribution is ready for a proper PyPI release."
+    },
+    {
+      "title": "Installable CLI and Web Assets",
+      "description": "Expose the `tg-agent` console entry point and include the bundled web templates and static assets in package data so installed builds behave like the source checkout."
+    },
+    {
+      "title": "Release Publishing Workflow",
+      "description": "Add the repository release script, token placeholders in `.env.example`, and the missing license file so the staged TestPyPI-to-PyPI publication flow is reproducible."
+    }
+  ]
+}

tg_agent-0.1.12/.github/release.yml

@@ -0,0 +1,12 @@
+changelog:
+  categories:
+    - title: "🚀 Features"
+      labels: ["feat", "feature", "enhancement"]
+    - title: "🐛 Fixes"
+      labels: ["fix", "bug", "bugfix"]
+    - title: "⚠️ Breaking Changes"
+      labels: ["breaking"]
+    - title: "🔧 Maintenance"
+      labels: ["refactor", "chore", "docs", "test", "ci"]
+    - title: "Other Changes"
+      labels: ["*"]

tg_agent-0.1.12/.github/scripts/render_release.py

@@ -0,0 +1,131 @@
+#!/usr/bin/env python3
+from __future__ import annotations
+
+import argparse
+import json
+import subprocess
+import sys
+from pathlib import Path
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(description="Render templated GitHub release notes.")
+    parser.add_argument("--repo", required=True, help="GitHub repository in OWNER/REPO format.")
+    parser.add_argument("--tag", required=True, help="Release tag, for example v0.1.10.")
+    parser.add_argument("--title-file", required=True, help="Path to write the rendered release title.")
+    parser.add_argument("--notes-file", required=True, help="Path to write the rendered release notes.")
+    parser.add_argument(
+        "--metadata-dir",
+        default=".github/release-metadata",
+        help="Directory containing per-tag release metadata JSON files.",
+    )
+    return parser.parse_args()
+
+
+def load_metadata(tag: str, metadata_dir: Path) -> dict:
+    metadata_path = metadata_dir / f"{tag}.json"
+    if not metadata_path.exists():
+        raise SystemExit(
+            f"Missing release metadata: {metadata_path}. "
+            "Add a JSON file for this tag before pushing the release tag."
+        )
+
+    metadata = json.loads(metadata_path.read_text())
+    metadata_tag = metadata.get("tag")
+    if metadata_tag != tag:
+        raise SystemExit(
+            f"Release metadata tag mismatch in {metadata_path}: expected {tag}, got {metadata_tag!r}."
+        )
+
+    if not metadata.get("title"):
+        raise SystemExit(f"Release metadata {metadata_path} must define a non-empty 'title'.")
+
+    highlights = metadata.get("highlights")
+    if not isinstance(highlights, list) or not highlights:
+        raise SystemExit(f"Release metadata {metadata_path} must define a non-empty 'highlights' list.")
+
+    return metadata
+
+
+def generate_notes(repo: str, tag: str) -> dict:
+    result = subprocess.run(
+        [
+            "gh",
+            "api",
+            f"repos/{repo}/releases/generate-notes",
+            "--method",
+            "POST",
+            "-f",
+            f"tag_name={tag}",
+        ],
+        check=True,
+        capture_output=True,
+        text=True,
+    )
+    return json.loads(result.stdout)
+
+
+def strip_generator_comment(body: str) -> str:
+    stripped = body.lstrip()
+    if stripped.startswith("<!--"):
+        end = stripped.find("-->")
+        if end != -1:
+            stripped = stripped[end + 3 :]
+    return stripped.lstrip()
+
+
+def normalize_single_category(body: str) -> str:
+    marker = "\n**Full Changelog**:"
+    head, sep, tail = body.partition(marker)
+    headings = head.count("\n### ")
+    prefix = "## What's Changed\n### "
+    if headings == 1 and head.startswith(prefix):
+        _, remainder = head.split("\n", 1)
+        head = "## What's Changed\n" + remainder.split("\n", 1)[1]
+    if not sep:
+        return head
+    return head + sep + tail
+
+
+def render_highlights(highlights: list[dict]) -> str:
+    lines = ["### Highlights", ""]
+    for item in highlights:
+        title = str(item.get("title", "")).strip()
+        description = str(item.get("description", "")).strip()
+        if not title or not description:
+            raise SystemExit("Each highlight item must include non-empty 'title' and 'description'.")
+        lines.append(f"- **{title}** — {description}")
+    return "\n".join(lines)
+
+
+def inject_highlights(body: str, highlights_block: str) -> str:
+    marker = "\n**Full Changelog**:"
+    if marker in body:
+        head, tail = body.split(marker, 1)
+        head = head.rstrip()
+        return f"{head}\n\n{highlights_block}\n\n**Full Changelog**:{tail}"
+    return f"{body.rstrip()}\n\n{highlights_block}\n"
+
+
+def write_text(path: str, content: str) -> None:
+    output_path = Path(path)
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+    output_path.write_text(content.rstrip() + "\n")
+
+
+def main() -> int:
+    args = parse_args()
+    metadata = load_metadata(args.tag, Path(args.metadata_dir))
+    generated = generate_notes(args.repo, args.tag)
+    generated_body = normalize_single_category(strip_generator_comment(str(generated.get("body", ""))))
+    highlights_block = render_highlights(metadata["highlights"])
+    rendered_body = inject_highlights(generated_body, highlights_block)
+    rendered_title = f"{args.tag} — {metadata['title']}"
+
+    write_text(args.title_file, rendered_title)
+    write_text(args.notes_file, rendered_body)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

tg_agent-0.1.12/.github/workflows/ci.yml

@@ -0,0 +1,31 @@
+name: CI
+
+on:
+  push:
+    branches:
+      - main
+      - fix/**
+      - codex/**
+  pull_request:
+
+jobs:
+  lint-and-test:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install dependencies
+        run: pip install -e ".[dev]"
+
+      - name: Ruff
+        run: ruff check src tests conftest.py
+
+      - name: Pytest
+        run: pytest tests -q -m "not aiosqlite_serial" -n auto && pytest tests -q -m aiosqlite_serial

tg_agent-0.1.12/.github/workflows/claude-code-review.yml

@@ -0,0 +1,44 @@
+name: Claude Code Review
+
+on:
+  pull_request:
+    types: [opened, synchronize, ready_for_review, reopened]
+    # Optional: Only run on specific file changes
+    # paths:
+    #   - "src/**/*.ts"
+    #   - "src/**/*.tsx"
+    #   - "src/**/*.js"
+    #   - "src/**/*.jsx"
+
+jobs:
+  claude-review:
+    # Optional: Filter by PR author
+    # if: |
+    #   github.event.pull_request.user.login == 'external-contributor' ||
+    #   github.event.pull_request.user.login == 'new-developer' ||
+    #   github.event.pull_request.author_association == 'FIRST_TIME_CONTRIBUTOR'
+
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: read
+      issues: read
+      id-token: write
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 1
+
+      - name: Run Claude Code Review
+        id: claude-review
+        uses: anthropics/claude-code-action@v1
+        with:
+          claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
+          plugin_marketplaces: 'https://github.com/anthropics/claude-code.git'
+          plugins: 'code-review@claude-code-plugins'
+          prompt: '/code-review:code-review ${{ github.repository }}/pull/${{ github.event.pull_request.number }}'
+          # See https://github.com/anthropics/claude-code-action/blob/main/docs/usage.md
+          # or https://code.claude.com/docs/en/cli-reference for available options
+

tg_agent-0.1.12/.github/workflows/claude.yml

@@ -0,0 +1,50 @@
+name: Claude Code
+
+on:
+  issue_comment:
+    types: [created]
+  pull_request_review_comment:
+    types: [created]
+  issues:
+    types: [opened, assigned]
+  pull_request_review:
+    types: [submitted]
+
+jobs:
+  claude:
+    if: |
+      (github.event_name == 'issue_comment' && contains(github.event.comment.body, '@claude')) ||
+      (github.event_name == 'pull_request_review_comment' && contains(github.event.comment.body, '@claude')) ||
+      (github.event_name == 'pull_request_review' && contains(github.event.review.body, '@claude')) ||
+      (github.event_name == 'issues' && (contains(github.event.issue.body, '@claude') || contains(github.event.issue.title, '@claude')))
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: read
+      issues: read
+      id-token: write
+      actions: read # Required for Claude to read CI results on PRs
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 1
+
+      - name: Run Claude Code
+        id: claude
+        uses: anthropics/claude-code-action@v1
+        with:
+          claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
+
+          # This is an optional setting that allows Claude to read CI results on PRs
+          additional_permissions: |
+            actions: read
+
+          # Optional: Give a custom prompt to Claude. If this is not specified, Claude will perform the instructions specified in the comment that tagged it.
+          # prompt: 'Update the pull request description to include a summary of changes.'
+
+          # Optional: Add claude_args to customize behavior and configuration
+          # See https://github.com/anthropics/claude-code-action/blob/main/docs/usage.md
+          # or https://code.claude.com/docs/en/cli-reference for available options
+          # claude_args: '--allowed-tools Bash(gh pr:*)'
+

tg_agent-0.1.12/.github/workflows/release.yml

@@ -0,0 +1,48 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: write
+
+jobs:
+  publish-release:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Create GitHub release if missing
+        env:
+          GH_REPO: ${{ github.repository }}
+          GH_TOKEN: ${{ github.token }}
+          GITHUB_TOKEN: ${{ github.token }}
+          TAG: ${{ github.ref_name }}
+        run: |
+          set -euo pipefail
+
+          if gh release view "$TAG" --repo "$GH_REPO" >/dev/null 2>&1; then
+            echo "Release $TAG already exists; nothing to do."
+            exit 0
+          fi
+
+          TITLE_FILE="$RUNNER_TEMP/release-title.txt"
+          NOTES_FILE="$RUNNER_TEMP/release-notes.md"
+
+          python3 .github/scripts/render_release.py \
+            --repo "$GH_REPO" \
+            --tag "$TAG" \
+            --title-file "$TITLE_FILE" \
+            --notes-file "$NOTES_FILE"
+
+          gh release create "$TAG" \
+            --repo "$GH_REPO" \
+            --title "$(cat "$TITLE_FILE")" \
+            --notes-file "$NOTES_FILE" \
+            --verify-tag