Merge branch 'main' into stas/trace-agentex-source

Author: smoreinis

.claude/settings.json

@@ -0,0 +1,15 @@
+{
+  "permissions": {
+    "allow": [
+      "WebSearch",
+      "WebFetch(domain:docs.temporal.io)",
+      "Bash(rye run pytest:*)",      
+      "Bash(rye run lint:*)",
+      "Bash(rye run typecheck:*)",
+      "Bash(rye run sync:*)",
+      "Bash(rye run build:*)"
+    ],
+    "deny": [],
+    "ask": []
+  }
+}

.cursor/rules/00_repo_tooling.mdc

@@ -0,0 +1,24 @@
+---
+description: Project-wide tooling, env, and command conventions
+globs: "**/*"
+alwaysApply: true
+---
+
+Use Rye for Python dependency management and workflows. Prefer these commands:
+
+- Setup env: `./scripts/bootstrap` or `rye sync --all-features` [[Use Rye in this repo]]
+- Run tests: `rye run pytest` or `./scripts/test`
+- Run a specific test: `rye run pytest path/to/test_file.py::TestClass::test_method -v`
+- Format: `rye run format` or `./scripts/format`
+- Lint: `rye run lint` or `./scripts/lint`
+- Type check: `rye run typecheck` (runs pyright and mypy)
+- Build: `rye build`
+
+Environment requirements:
+
+- Python 3.12+ is required
+- A mock server auto-starts for tests on port 4010
+
+Notes:
+
+- Only use `uv` inside of tutorial folders which have their own virtualenv (managed by a tutorial specific pyproject.toml inside the relevant tutorial folder). Otherwise use rye at the top level.

.cursor/rules/05_permissions_and_tools.mdc

@@ -0,0 +1,18 @@
+---
+description: Cursor agent permissions and allowed tools aligned with Claude settings
+globs: "**/*"
+alwaysApply: true
+---
+
+When invoking external tools or the terminal, follow these constraints:
+
+- Web search is allowed when needed for docs and references
+- Prefer fetching docs from `docs.temporal.io` when researching Temporal topics
+- Allowed bash commands should go through Rye workflows:
+  - `rye run pytest:*`
+  - `rye run lint:*`
+  - `rye run typecheck:*`
+  - `rye run sync:*`
+  - `rye run build:*`
+
+Default to Rye; only use other tools when explicitly required by the codebase.

.cursor/rules/10_architecture.mdc

@@ -0,0 +1,30 @@
+---
+description: Repository architecture overview and code navigation hints
+globs: "src/agentex/**, examples/**, tests/**, README.md"
+alwaysApply: false
+---
+
+Code structure expectations:
+
+- `src/agentex/` contains the core SDK and generated API client code
+- `src/agentex/lib/` contains manually maintained code that should not be overwritten by the code generator
+  - `cli/` Typer-based CLI implementation
+  - `core/` Core services, adapters, and Temporal workflows
+  - `sdk/` SDK utilities and FastACP implementation
+  - `types/` Custom type definitions
+  - `utils/` Utility functions
+- `examples/` provides example implementations and tutorials
+- `tests/` contains the test suites
+
+Key components quick reference:
+
+- Client Layer: HTTP client for AgentEx API in `_client.py` and `resources/`
+- CLI Layer: Typer-based commands under `lib/cli/`
+- Core Services: Temporal workflows and services under `lib/core/`
+- FastACP: Protocol implementation in `lib/sdk/fastacp/`
+- State Machine: Workflow state management in `lib/sdk/state_machine/`
+
+Generated vs manual code:
+
+- Treat `src/agentex/lib/**` as manual code; avoid edits in generated areas unless regenerating consistently
+- Expect merge conflicts between generator outputs and manual patches; keep custom logic in `lib/`

.cursor/rules/20_codegen_boundaries.mdc

@@ -0,0 +1,11 @@
+---
+description: Keep manual code separate from generated SDK code
+globs: "src/agentex/**"
+alwaysApply: true
+---
+
+Guideline:
+
+- Avoid modifying auto-generated files in `src/agentex/` except where explicitly intended. Place custom logic, extensions, and higher-level abstractions in `src/agentex/lib/`.
+- When adding features, prefer adding new modules under `src/agentex/lib/**` rather than changing generated files directly.
+- If a change to generated code is required, document the reason and ensure the generator configuration or upstream schema is updated to make the change reproducible.

.cursor/rules/30_cli_and_commands.mdc

@@ -0,0 +1,18 @@
+---
+description: Guidance for working with the agentex CLI and commands
+globs: "src/agentex/lib/cli/**, src/agentex/lib/core/**"
+alwaysApply: false
+---
+
+The `agentex` CLI exposes:
+
+- `agentex agents` for get/list/run/build/deploy agents
+- `agentex tasks` for get/list/delete tasks
+- `agentex secrets` for sync/get/list/delete secrets
+- `agentex uv` as a UV wrapper with AgentEx-specific enhancements
+- `agentex init` to initialize new agent projects
+
+Development tips:
+
+- For agent development, use `agentex agents run --manifest manifest.yaml`
+- For debugging, append `--debug-worker` and optionally `--debug-port 5679`

.cursor/rules/40_temporal_and_agents.mdc

@@ -0,0 +1,17 @@
+---
+description: Temporal workflows, activities, and agent development guidance
+globs: "src/agentex/lib/core/temporal/**, examples/**/10_temporal/**"
+alwaysApply: false
+---
+
+Temporal integration:
+
+- Workflow definitions live in `lib/core/temporal/`
+- Include activity definitions for different providers and worker implementations
+- Keep workflow logic deterministic and side-effect free; move I/O into activities
+
+Agent framework:
+
+- Agents are manifest-driven and support multiple agent types (sync and Temporal-based)
+- Use the examples under `examples/10_agentic/` and `examples/10_temporal/` for patterns
+- For debugging agents, use the CLI flags `--debug-worker` and `--debug-port`

.cursor/rules/50_tests_and_mocking.mdc

@@ -0,0 +1,16 @@
+---
+description: Testing workflow and mock server details
+globs: "tests/**, scripts/test, scripts/mock"
+alwaysApply: true
+---
+
+Testing:
+
+- Run tests with `rye run pytest` or `./scripts/test`
+- To run a specific test: `rye run pytest path/to/test_file.py::TestClass::test_method -v`
+- A mock server is automatically started for tests on port 4010
+
+When writing tests:
+
+- Prefer deterministic unit tests that do not depend on external services
+- Use the mock server and fixtures provided in the repository

.cursor/rules/60_style_lint_typecheck.mdc

@@ -0,0 +1,16 @@
+---
+description: Formatting, linting, and type checking standards
+globs: "src/**, tests/**"
+alwaysApply: true
+---
+
+Standards:
+
+- Format code via `rye run format` or `./scripts/format`
+- Lint via `rye run lint` or `./scripts/lint`
+- Type check via `rye run typecheck` (pyright + mypy)
+
+Guidance:
+
+- Keep code readable and consistent; prefer small, focused functions
+- Avoid introducing style or type violations; fix before committing

.cursor/rules/70_examples_and_docs.mdc

@@ -0,0 +1,11 @@
+---
+description: How to use examples and documentation for development
+globs: "examples/**, README.md"
+alwaysApply: false
+---
+
+Use the `examples/` directory as reference implementations and tutorials. When creating new features:
+
+- Mirror patterns from the closest matching example
+- Keep examples runnable with the documented commands
+- Prefer adding or updating examples alongside significant feature changes