1claw-crewai-tools 0.1.0__tar.gz

1claw_crewai_tools-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 1Claw
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

1claw_crewai_tools-0.1.0/PKG-INFO

@@ -0,0 +1,171 @@
+Metadata-Version: 2.4
+Name: 1claw-crewai-tools
+Version: 0.1.0
+Summary: Secure secret fetching for CrewAI agents via 1claw HSM-backed vaults
+Author: 1Claw
+License-Expression: MIT
+Project-URL: Documentation, https://docs.1claw.xyz
+Project-URL: Homepage, https://github.com/1ClawAI/1claw-crewai-tools
+Project-URL: Repository, https://github.com/1ClawAI/1claw-crewai-tools
+Keywords: 1claw,crewai,secrets,vault,agents
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: <3.14,>=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: crewai>=0.100.0
+Requires-Dist: httpx>=0.27
+Requires-Dist: pydantic>=2.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: respx>=0.21; extra == "dev"
+Requires-Dist: ruff>=0.4; extra == "dev"
+Requires-Dist: mypy>=1.8; extra == "dev"
+Requires-Dist: freezegun>=1.5; extra == "dev"
+Requires-Dist: build>=1.0; extra == "dev"
+Requires-Dist: twine>=5.0; extra == "dev"
+Dynamic: license-file
+
+# 1claw-crewai-tools
+
+[![PyPI version](https://img.shields.io/pypi/v/1claw-crewai-tools.svg)](https://pypi.org/project/1claw-crewai-tools/)
+[![Python versions](https://img.shields.io/pypi/pyversions/1claw-crewai-tools.svg)](https://pypi.org/project/1claw-crewai-tools/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![CI](https://github.com/1ClawAI/1claw-crewai-tools/actions/workflows/ci.yml/badge.svg)](https://github.com/1ClawAI/1claw-crewai-tools/actions/workflows/ci.yml)
+
+**Secure secret fetching for CrewAI agents via [1Claw](https://1claw.xyz) HSM-backed vaults.**
+
+Credentials are retrieved at **runtime** from your vault using a **scoped agent identity** — not copied into prompts, repos, or long-lived agent memory. Do not log tool return values.
+
+## Install
+
+PyPI distribution name: **`1claw-crewai-tools`**. Python import package: **`oneclaw_crewai`**.
+
+```bash
+pip install 1claw-crewai-tools
+```
+
+## Usage
+
+```python
+import os
+from crewai import Agent, Crew, Process, Task
+from oneclaw_crewai import OneclawVaultTool
+
+vault_tool = OneclawVaultTool(
+    agent_id=os.environ["ONECLAW_AGENT_ID"],
+    api_key=os.environ["ONECLAW_AGENT_API_KEY"],
+    vault_id=os.environ["ONECLAW_VAULT_ID"],
+)
+
+agent = Agent(
+    role="Engineer",
+    goal="Build features using vault-stored API keys",
+    backstory="You use tools instead of pasted secrets.",
+    tools=[vault_tool],
+    verbose=True,
+)
+
+task = Task(
+    description="Read path api-keys/example using the vault tool; do not echo raw values in logs.",
+    expected_output="Confirmation that the path was read.",
+    agent=agent,
+)
+
+crew = Crew(agents=[agent], tasks=[task], process=Process.sequential)
+crew.kickoff()
+```
+
+## Testing
+
+### Unit tests (offline, no credentials needed)
+
+```bash
+# From the package root:
+python -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+pytest -v                    # 10 tests — client + tool
+ruff check src tests examples
+mypy
+```
+
+All network calls are mocked with `respx`; no 1Claw account is required.
+
+### Live integration test (requires 1Claw + LLM key)
+
+`examples/test_live.py` runs three progressive phases against the real API:
+
+| Phase | What it validates |
+|-------|-------------------|
+| 1 | Raw `OneclawClient` — agent token exchange + `get_secret` (no CrewAI) |
+| 2 | Single-agent crew — CrewAI invokes `oneclaw_vault` tool, LLM reports result |
+| 3 | Two-agent crew — fetcher reads secret, writer produces unrelated output |
+
+**Prerequisites:**
+
+1. A [1Claw](https://1claw.xyz) account with a vault containing at least one secret.
+2. An agent registered in that org, bound to the vault (`vault_ids`), with a read policy on the secret path (e.g. `demo/**` or `**`).
+3. An LLM API key — **OpenAI** (`OPENAI_API_KEY`) or **Google Gemini** (`GOOGLE_API_KEY`).
+
+For Gemini, install the provider extra: `pip install "crewai[google-genai]"`.
+
+**Run:**
+
+```bash
+export ONECLAW_AGENT_ID="<agent-uuid>"
+export ONECLAW_AGENT_API_KEY="ocv_..."
+export ONECLAW_VAULT_ID="<vault-uuid>"
+export GOOGLE_API_KEY="..."   # or OPENAI_API_KEY
+
+python examples/test_live.py demo/api-key
+```
+
+The script accepts an optional secret path argument (defaults to `test/crewai-live`).
+
+**Example output (Phase 2):**
+
+```
+╭─── 🔧 Tool Execution Started (#1) ───╮
+│  Tool: oneclaw_vault                  │
+│  Args: {'path': 'demo/api-key'}      │
+╰───────────────────────────────────────╯
+
+╭─── ✅ Agent Final Answer ────╮
+│  Fetch succeeded,            │
+│  character length: 32.       │
+╰──────────────────────────────╯
+```
+
+### Known issues and gotchas
+
+| Issue | Details |
+|-------|---------|
+| **Tool name must be a valid identifier** | OpenAI (and other providers) require function names to start with a letter or underscore. The tool is named `oneclaw_vault` — not `1claw Vault` — for this reason. If you subclass and change `name`, keep it alphanumeric + underscores, starting with a letter. |
+| **CrewAI verbose logging prints secret values** | When `verbose=True`, CrewAI's internal executor logs the raw return value of every tool call. This is a CrewAI framework behaviour, not this package. In production, set `verbose=False` or redirect stdout. |
+| **Google Gemini requires an extra** | `pip install "crewai[google-genai]"` — without it, `LLM(model="gemini/...")` raises `ImportError`. |
+| **`cache_function` must be a callable** | CrewAI's `BaseTool.cache_function` field is typed as `Callable[..., bool]`, not `bool`. This package sets it to a function that always returns `False`. If you override it, pass a callable, not a bare `False`. |
+
+## Documentation
+
+- **[Quickstart](docs/quickstart.md)** — prerequisites, env vars, paths, security, troubleshooting
+- **[1Claw docs](https://docs.1claw.xyz)** — vaults, agents, policies
+
+## Security
+
+- Tool output can contain **plaintext credentials**. Never `print()` or log the return value of `_run` / tool execution.
+- `OneclawVaultTool` sets CrewAI's **`cache_function`** to a callable that **always returns `False`** so credential reads are **not** cached by the framework.
+- CrewAI's `verbose=True` prints tool output including secrets to stdout — use `verbose=False` in production.
+
+## Repository
+
+Source: [github.com/1ClawAI/1claw-crewai-tools](https://github.com/1ClawAI/1claw-crewai-tools)
+
+## License
+
+MIT — see [LICENSE](LICENSE).

1claw_crewai_tools-0.1.0/README.md

@@ -0,0 +1,137 @@
+# 1claw-crewai-tools
+
+[![PyPI version](https://img.shields.io/pypi/v/1claw-crewai-tools.svg)](https://pypi.org/project/1claw-crewai-tools/)
+[![Python versions](https://img.shields.io/pypi/pyversions/1claw-crewai-tools.svg)](https://pypi.org/project/1claw-crewai-tools/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![CI](https://github.com/1ClawAI/1claw-crewai-tools/actions/workflows/ci.yml/badge.svg)](https://github.com/1ClawAI/1claw-crewai-tools/actions/workflows/ci.yml)
+
+**Secure secret fetching for CrewAI agents via [1Claw](https://1claw.xyz) HSM-backed vaults.**
+
+Credentials are retrieved at **runtime** from your vault using a **scoped agent identity** — not copied into prompts, repos, or long-lived agent memory. Do not log tool return values.
+
+## Install
+
+PyPI distribution name: **`1claw-crewai-tools`**. Python import package: **`oneclaw_crewai`**.
+
+```bash
+pip install 1claw-crewai-tools
+```
+
+## Usage
+
+```python
+import os
+from crewai import Agent, Crew, Process, Task
+from oneclaw_crewai import OneclawVaultTool
+
+vault_tool = OneclawVaultTool(
+    agent_id=os.environ["ONECLAW_AGENT_ID"],
+    api_key=os.environ["ONECLAW_AGENT_API_KEY"],
+    vault_id=os.environ["ONECLAW_VAULT_ID"],
+)
+
+agent = Agent(
+    role="Engineer",
+    goal="Build features using vault-stored API keys",
+    backstory="You use tools instead of pasted secrets.",
+    tools=[vault_tool],
+    verbose=True,
+)
+
+task = Task(
+    description="Read path api-keys/example using the vault tool; do not echo raw values in logs.",
+    expected_output="Confirmation that the path was read.",
+    agent=agent,
+)
+
+crew = Crew(agents=[agent], tasks=[task], process=Process.sequential)
+crew.kickoff()
+```
+
+## Testing
+
+### Unit tests (offline, no credentials needed)
+
+```bash
+# From the package root:
+python -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+pytest -v                    # 10 tests — client + tool
+ruff check src tests examples
+mypy
+```
+
+All network calls are mocked with `respx`; no 1Claw account is required.
+
+### Live integration test (requires 1Claw + LLM key)
+
+`examples/test_live.py` runs three progressive phases against the real API:
+
+| Phase | What it validates |
+|-------|-------------------|
+| 1 | Raw `OneclawClient` — agent token exchange + `get_secret` (no CrewAI) |
+| 2 | Single-agent crew — CrewAI invokes `oneclaw_vault` tool, LLM reports result |
+| 3 | Two-agent crew — fetcher reads secret, writer produces unrelated output |
+
+**Prerequisites:**
+
+1. A [1Claw](https://1claw.xyz) account with a vault containing at least one secret.
+2. An agent registered in that org, bound to the vault (`vault_ids`), with a read policy on the secret path (e.g. `demo/**` or `**`).
+3. An LLM API key — **OpenAI** (`OPENAI_API_KEY`) or **Google Gemini** (`GOOGLE_API_KEY`).
+
+For Gemini, install the provider extra: `pip install "crewai[google-genai]"`.
+
+**Run:**
+
+```bash
+export ONECLAW_AGENT_ID="<agent-uuid>"
+export ONECLAW_AGENT_API_KEY="ocv_..."
+export ONECLAW_VAULT_ID="<vault-uuid>"
+export GOOGLE_API_KEY="..."   # or OPENAI_API_KEY
+
+python examples/test_live.py demo/api-key
+```
+
+The script accepts an optional secret path argument (defaults to `test/crewai-live`).
+
+**Example output (Phase 2):**
+
+```
+╭─── 🔧 Tool Execution Started (#1) ───╮
+│  Tool: oneclaw_vault                  │
+│  Args: {'path': 'demo/api-key'}      │
+╰───────────────────────────────────────╯
+
+╭─── ✅ Agent Final Answer ────╮
+│  Fetch succeeded,            │
+│  character length: 32.       │
+╰──────────────────────────────╯
+```
+
+### Known issues and gotchas
+
+| Issue | Details |
+|-------|---------|
+| **Tool name must be a valid identifier** | OpenAI (and other providers) require function names to start with a letter or underscore. The tool is named `oneclaw_vault` — not `1claw Vault` — for this reason. If you subclass and change `name`, keep it alphanumeric + underscores, starting with a letter. |
+| **CrewAI verbose logging prints secret values** | When `verbose=True`, CrewAI's internal executor logs the raw return value of every tool call. This is a CrewAI framework behaviour, not this package. In production, set `verbose=False` or redirect stdout. |
+| **Google Gemini requires an extra** | `pip install "crewai[google-genai]"` — without it, `LLM(model="gemini/...")` raises `ImportError`. |
+| **`cache_function` must be a callable** | CrewAI's `BaseTool.cache_function` field is typed as `Callable[..., bool]`, not `bool`. This package sets it to a function that always returns `False`. If you override it, pass a callable, not a bare `False`. |
+
+## Documentation
+
+- **[Quickstart](docs/quickstart.md)** — prerequisites, env vars, paths, security, troubleshooting
+- **[1Claw docs](https://docs.1claw.xyz)** — vaults, agents, policies
+
+## Security
+
+- Tool output can contain **plaintext credentials**. Never `print()` or log the return value of `_run` / tool execution.
+- `OneclawVaultTool` sets CrewAI's **`cache_function`** to a callable that **always returns `False`** so credential reads are **not** cached by the framework.
+- CrewAI's `verbose=True` prints tool output including secrets to stdout — use `verbose=False` in production.
+
+## Repository
+
+Source: [github.com/1ClawAI/1claw-crewai-tools](https://github.com/1ClawAI/1claw-crewai-tools)
+
+## License
+
+MIT — see [LICENSE](LICENSE).

1claw_crewai_tools-0.1.0/pyproject.toml

@@ -0,0 +1,74 @@
+[build-system]
+requires = ["setuptools>=61", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "1claw-crewai-tools"
+version = "0.1.0"
+description = "Secure secret fetching for CrewAI agents via 1claw HSM-backed vaults"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.10,<3.14"
+authors = [{ name = "1Claw" }]
+keywords = ["1claw", "crewai", "secrets", "vault", "agents"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Typing :: Typed",
+]
+dependencies = [
+  "crewai>=0.100.0",
+  "httpx>=0.27",
+  "pydantic>=2.0",
+]
+
+[project.optional-dependencies]
+dev = [
+  "pytest>=8.0",
+  "respx>=0.21",
+  "ruff>=0.4",
+  "mypy>=1.8",
+  "freezegun>=1.5",
+  "build>=1.0",
+  "twine>=5.0",
+]
+
+[project.urls]
+Documentation = "https://docs.1claw.xyz"
+Homepage = "https://github.com/1ClawAI/1claw-crewai-tools"
+Repository = "https://github.com/1ClawAI/1claw-crewai-tools"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+oneclaw_crewai = ["py.typed"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+src = ["src", "tests", "examples"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "W"]
+
+[tool.mypy]
+python_version = "3.10"
+strict = true
+warn_return_any = true
+warn_unused_configs = true
+mypy_path = "src"
+packages = ["oneclaw_crewai"]
+
+[[tool.mypy.overrides]]
+module = ["crewai.*", "crewai_tools.*"]
+ignore_missing_imports = true
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

1claw_crewai_tools-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

1claw_crewai_tools-0.1.0/src/1claw_crewai_tools.egg-info/PKG-INFO

@@ -0,0 +1,171 @@
+Metadata-Version: 2.4
+Name: 1claw-crewai-tools
+Version: 0.1.0
+Summary: Secure secret fetching for CrewAI agents via 1claw HSM-backed vaults
+Author: 1Claw
+License-Expression: MIT
+Project-URL: Documentation, https://docs.1claw.xyz
+Project-URL: Homepage, https://github.com/1ClawAI/1claw-crewai-tools
+Project-URL: Repository, https://github.com/1ClawAI/1claw-crewai-tools
+Keywords: 1claw,crewai,secrets,vault,agents
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: <3.14,>=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: crewai>=0.100.0
+Requires-Dist: httpx>=0.27
+Requires-Dist: pydantic>=2.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: respx>=0.21; extra == "dev"
+Requires-Dist: ruff>=0.4; extra == "dev"
+Requires-Dist: mypy>=1.8; extra == "dev"
+Requires-Dist: freezegun>=1.5; extra == "dev"
+Requires-Dist: build>=1.0; extra == "dev"
+Requires-Dist: twine>=5.0; extra == "dev"
+Dynamic: license-file
+
+# 1claw-crewai-tools
+
+[![PyPI version](https://img.shields.io/pypi/v/1claw-crewai-tools.svg)](https://pypi.org/project/1claw-crewai-tools/)
+[![Python versions](https://img.shields.io/pypi/pyversions/1claw-crewai-tools.svg)](https://pypi.org/project/1claw-crewai-tools/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![CI](https://github.com/1ClawAI/1claw-crewai-tools/actions/workflows/ci.yml/badge.svg)](https://github.com/1ClawAI/1claw-crewai-tools/actions/workflows/ci.yml)
+
+**Secure secret fetching for CrewAI agents via [1Claw](https://1claw.xyz) HSM-backed vaults.**
+
+Credentials are retrieved at **runtime** from your vault using a **scoped agent identity** — not copied into prompts, repos, or long-lived agent memory. Do not log tool return values.
+
+## Install
+
+PyPI distribution name: **`1claw-crewai-tools`**. Python import package: **`oneclaw_crewai`**.
+
+```bash
+pip install 1claw-crewai-tools
+```
+
+## Usage
+
+```python
+import os
+from crewai import Agent, Crew, Process, Task
+from oneclaw_crewai import OneclawVaultTool
+
+vault_tool = OneclawVaultTool(
+    agent_id=os.environ["ONECLAW_AGENT_ID"],
+    api_key=os.environ["ONECLAW_AGENT_API_KEY"],
+    vault_id=os.environ["ONECLAW_VAULT_ID"],
+)
+
+agent = Agent(
+    role="Engineer",
+    goal="Build features using vault-stored API keys",
+    backstory="You use tools instead of pasted secrets.",
+    tools=[vault_tool],
+    verbose=True,
+)
+
+task = Task(
+    description="Read path api-keys/example using the vault tool; do not echo raw values in logs.",
+    expected_output="Confirmation that the path was read.",
+    agent=agent,
+)
+
+crew = Crew(agents=[agent], tasks=[task], process=Process.sequential)
+crew.kickoff()
+```
+
+## Testing
+
+### Unit tests (offline, no credentials needed)
+
+```bash
+# From the package root:
+python -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+pytest -v                    # 10 tests — client + tool
+ruff check src tests examples
+mypy
+```
+
+All network calls are mocked with `respx`; no 1Claw account is required.
+
+### Live integration test (requires 1Claw + LLM key)
+
+`examples/test_live.py` runs three progressive phases against the real API:
+
+| Phase | What it validates |
+|-------|-------------------|
+| 1 | Raw `OneclawClient` — agent token exchange + `get_secret` (no CrewAI) |
+| 2 | Single-agent crew — CrewAI invokes `oneclaw_vault` tool, LLM reports result |
+| 3 | Two-agent crew — fetcher reads secret, writer produces unrelated output |
+
+**Prerequisites:**
+
+1. A [1Claw](https://1claw.xyz) account with a vault containing at least one secret.
+2. An agent registered in that org, bound to the vault (`vault_ids`), with a read policy on the secret path (e.g. `demo/**` or `**`).
+3. An LLM API key — **OpenAI** (`OPENAI_API_KEY`) or **Google Gemini** (`GOOGLE_API_KEY`).
+
+For Gemini, install the provider extra: `pip install "crewai[google-genai]"`.
+
+**Run:**
+
+```bash
+export ONECLAW_AGENT_ID="<agent-uuid>"
+export ONECLAW_AGENT_API_KEY="ocv_..."
+export ONECLAW_VAULT_ID="<vault-uuid>"
+export GOOGLE_API_KEY="..."   # or OPENAI_API_KEY
+
+python examples/test_live.py demo/api-key
+```
+
+The script accepts an optional secret path argument (defaults to `test/crewai-live`).
+
+**Example output (Phase 2):**
+
+```
+╭─── 🔧 Tool Execution Started (#1) ───╮
+│  Tool: oneclaw_vault                  │
+│  Args: {'path': 'demo/api-key'}      │
+╰───────────────────────────────────────╯
+
+╭─── ✅ Agent Final Answer ────╮
+│  Fetch succeeded,            │
+│  character length: 32.       │
+╰──────────────────────────────╯
+```
+
+### Known issues and gotchas
+
+| Issue | Details |
+|-------|---------|
+| **Tool name must be a valid identifier** | OpenAI (and other providers) require function names to start with a letter or underscore. The tool is named `oneclaw_vault` — not `1claw Vault` — for this reason. If you subclass and change `name`, keep it alphanumeric + underscores, starting with a letter. |
+| **CrewAI verbose logging prints secret values** | When `verbose=True`, CrewAI's internal executor logs the raw return value of every tool call. This is a CrewAI framework behaviour, not this package. In production, set `verbose=False` or redirect stdout. |
+| **Google Gemini requires an extra** | `pip install "crewai[google-genai]"` — without it, `LLM(model="gemini/...")` raises `ImportError`. |
+| **`cache_function` must be a callable** | CrewAI's `BaseTool.cache_function` field is typed as `Callable[..., bool]`, not `bool`. This package sets it to a function that always returns `False`. If you override it, pass a callable, not a bare `False`. |
+
+## Documentation
+
+- **[Quickstart](docs/quickstart.md)** — prerequisites, env vars, paths, security, troubleshooting
+- **[1Claw docs](https://docs.1claw.xyz)** — vaults, agents, policies
+
+## Security
+
+- Tool output can contain **plaintext credentials**. Never `print()` or log the return value of `_run` / tool execution.
+- `OneclawVaultTool` sets CrewAI's **`cache_function`** to a callable that **always returns `False`** so credential reads are **not** cached by the framework.
+- CrewAI's `verbose=True` prints tool output including secrets to stdout — use `verbose=False` in production.
+
+## Repository
+
+Source: [github.com/1ClawAI/1claw-crewai-tools](https://github.com/1ClawAI/1claw-crewai-tools)
+
+## License
+
+MIT — see [LICENSE](LICENSE).

1claw_crewai_tools-0.1.0/src/1claw_crewai_tools.egg-info/SOURCES.txt

@@ -0,0 +1,14 @@
+LICENSE
+README.md
+pyproject.toml
+src/1claw_crewai_tools.egg-info/PKG-INFO
+src/1claw_crewai_tools.egg-info/SOURCES.txt
+src/1claw_crewai_tools.egg-info/dependency_links.txt
+src/1claw_crewai_tools.egg-info/requires.txt
+src/1claw_crewai_tools.egg-info/top_level.txt
+src/oneclaw_crewai/__init__.py
+src/oneclaw_crewai/_client.py
+src/oneclaw_crewai/_tool.py
+src/oneclaw_crewai/py.typed
+tests/test_client.py
+tests/test_tool.py

1claw_crewai_tools-0.1.0/src/1claw_crewai_tools.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

1claw_crewai_tools-0.1.0/src/1claw_crewai_tools.egg-info/requires.txt

@@ -0,0 +1,12 @@
+crewai>=0.100.0
+httpx>=0.27
+pydantic>=2.0
+
+[dev]
+pytest>=8.0
+respx>=0.21
+ruff>=0.4
+mypy>=1.8
+freezegun>=1.5
+build>=1.0
+twine>=5.0

1claw_crewai_tools-0.1.0/src/1claw_crewai_tools.egg-info/top_level.txt

@@ -0,0 +1 @@
+oneclaw_crewai

1claw_crewai_tools-0.1.0/src/oneclaw_crewai/__init__.py

@@ -0,0 +1,6 @@
+"""1Claw CrewAI tools — secure vault access for agents."""
+
+from ._tool import OneclawVaultTool
+
+__version__ = "0.1.0"
+__all__ = ["OneclawVaultTool"]

1claw_crewai_tools-0.1.0/src/oneclaw_crewai/_client.py

@@ -0,0 +1,134 @@
+"""HTTP client for the 1Claw Vault REST API (agent authentication)."""
+
+from __future__ import annotations
+
+import time
+from typing import Any
+from urllib.parse import quote
+
+import httpx
+
+
+class OneclawError(Exception):
+    """Base error for 1Claw API failures."""
+
+    pass
+
+
+class OneclawAuthError(OneclawError):
+    """Raised when authentication or authorization fails (401/403)."""
+
+    pass
+
+
+class OneclawSecretNotFoundError(OneclawError):
+    """Raised when the requested secret path does not exist (404)."""
+
+    pass
+
+
+class OneclawClient:
+    """Synchronous httpx client with JWT caching for agent API access."""
+
+    def __init__(
+        self,
+        agent_id: str,
+        api_key: str,
+        vault_id: str,
+        base_url: str = "https://api.1claw.xyz",
+    ) -> None:
+        """Create a client for the given agent credentials and vault.
+
+        Args:
+            agent_id: 1Claw agent UUID string.
+            api_key: Agent API key (``ocv_`` prefix).
+            vault_id: Target vault UUID string.
+            base_url: Vault API base URL (no trailing slash).
+        """
+        self._agent_id = agent_id
+        self._api_key = api_key
+        self._vault_id = vault_id
+        self._base_url = base_url.rstrip("/")
+        self._http = httpx.Client(timeout=30.0)
+        self._access_token: str | None = None
+        self._token_expires_at: float | None = None
+
+    def close(self) -> None:
+        """Close the underlying HTTP client."""
+        self._http.close()
+
+    def __enter__(self) -> OneclawClient:
+        return self
+
+    def __exit__(self, *args: object) -> None:
+        self.close()
+
+    def _ensure_token(self) -> None:
+        """Obtain or refresh the bearer token if missing or near expiry."""
+        now = time.time()
+        if (
+            self._access_token is not None
+            and self._token_expires_at is not None
+            and now < self._token_expires_at - 30
+        ):
+            return
+
+        url = f"{self._base_url}/v1/auth/agent-token"
+        resp = self._http.post(
+            url,
+            json={"agent_id": self._agent_id, "api_key": self._api_key},
+            headers={"Content-Type": "application/json"},
+        )
+        if resp.status_code in (401, 403):
+            raise OneclawAuthError(f"Authentication failed: HTTP {resp.status_code}")
+        if not resp.is_success:
+            raise OneclawError(f"Token request failed: HTTP {resp.status_code}")
+
+        data: dict[str, Any] = resp.json()
+        token = data.get("access_token")
+        if not isinstance(token, str) or not token:
+            raise OneclawError("Token response missing access_token")
+        expires_in = data.get("expires_in", 300)
+        if not isinstance(expires_in, (int, float)):
+            expires_in = 300
+
+        self._access_token = token
+        self._token_expires_at = now + float(expires_in)
+
+    def get_secret(self, path: str) -> str:
+        """GET a decrypted secret value by vault path.
+
+        Args:
+            path: Secret path (e.g. ``api-keys/stripe``).
+
+        Returns:
+            The decrypted secret value string.
+
+        Raises:
+            OneclawAuthError: On 401 or 403.
+            OneclawSecretNotFoundError: On 404.
+            OneclawError: On other non-success responses or malformed JSON.
+        """
+        self._ensure_token()
+        assert self._access_token is not None
+
+        encoded = quote(path.lstrip("/"), safe="")
+        url = f"{self._base_url}/v1/vaults/{self._vault_id}/secrets/{encoded}"
+        resp = self._http.get(
+            url,
+            headers={"Authorization": f"Bearer {self._access_token}"},
+        )
+
+        if resp.status_code in (401, 403):
+            raise OneclawAuthError(f"Secret request unauthorized: HTTP {resp.status_code}")
+        if resp.status_code == 404:
+            raise OneclawSecretNotFoundError(f"Secret not found at path: {path}")
+        if not resp.is_success:
+            raise OneclawError(f"Secret request failed: HTTP {resp.status_code}")
+
+        body: dict[str, Any] = resp.json()
+        value = body.get("value")
+        if not isinstance(value, str):
+            raise OneclawError("Secret response missing string value")
+        # SECRET: do not log — value is sensitive; never print or log this string.
+        return value

1claw_crewai_tools-0.1.0/src/oneclaw_crewai/_tool.py

@@ -0,0 +1,83 @@
+"""CrewAI BaseTool that reads secrets from a 1Claw vault."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from crewai.tools import BaseTool
+from pydantic import BaseModel, Field
+
+from ._client import OneclawClient, OneclawError
+
+
+def _never_cache_vault_tool(_args: Any = None, _result: Any = None) -> bool:
+    """Return False so CrewAI does not cache tool output (credentials may rotate)."""
+    return False
+
+
+class OneclawVaultInput(BaseModel):
+    """Input schema for :class:`OneclawVaultTool`."""
+
+    path: str = Field(
+        ...,
+        description=(
+            "The secret path in the 1claw vault, e.g. 'api-keys/stripe' or "
+            "'db/postgres-url'. Use the exact path the vault owner configured."
+        ),
+    )
+
+
+class OneclawVaultTool(BaseTool):
+    """Tool that fetches a secret value from a 1Claw vault by path."""
+
+    name: str = "oneclaw_vault"
+    description: str = (
+        "Fetch a secret from the 1Claw HSM-backed vault by its path. "
+        "Use this tool whenever you need an API key, token, connection string, "
+        "or other credential. Never ask the user to paste credentials — "
+        "fetch them from the vault instead. "
+        "Input: the secret path (e.g. 'api-keys/openai')."
+    )
+    args_schema: type[BaseModel] = OneclawVaultInput
+    # CrewAI uses a callable here (not a bool); must always return False.
+    cache_function: Any = _never_cache_vault_tool
+
+    _client: OneclawClient | None = None
+
+    def __init__(
+        self,
+        *,
+        agent_id: str,
+        api_key: str,
+        vault_id: str,
+        base_url: str = "https://api.1claw.xyz",
+        **kwargs: Any,
+    ) -> None:
+        """Build a vault tool for the given agent and vault.
+
+        Args:
+            agent_id: 1Claw agent id (UUID).
+            api_key: Agent API key (``ocv_`` prefix).
+            vault_id: Vault id (UUID) the agent may access per policy.
+            base_url: Vault API base URL.
+            **kwargs: Forwarded to :class:`crewai.tools.BaseTool`.
+        """
+        super().__init__(**kwargs)
+        object.__setattr__(
+            self,
+            "_client",
+            OneclawClient(
+                agent_id=agent_id,
+                api_key=api_key,
+                vault_id=vault_id,
+                base_url=base_url,
+            ),
+        )
+
+    def _run(self, path: str) -> str:
+        """Fetch the secret at ``path``; returns error string on failure (does not raise)."""
+        assert self._client is not None
+        try:
+            return self._client.get_secret(path)
+        except OneclawError as exc:
+            return f"[1claw error] {exc}"

1claw_crewai_tools-0.1.0/tests/test_client.py

@@ -0,0 +1,187 @@
+"""Tests for :mod:`oneclaw_crewai._client`."""
+
+from __future__ import annotations
+
+import uuid
+from datetime import timedelta
+
+import httpx
+import pytest
+import respx
+from freezegun import freeze_time
+
+from oneclaw_crewai._client import (
+    OneclawAuthError,
+    OneclawClient,
+    OneclawError,
+    OneclawSecretNotFoundError,
+)
+
+
+def _vault_id() -> str:
+    return str(uuid.uuid4())
+
+
+def _agent_id() -> str:
+    return str(uuid.uuid4())
+
+
+@respx.mock
+def test_successful_auth_and_secret_fetch(api_base: str) -> None:
+    vid = _vault_id()
+    aid = _agent_id()
+    respx.post(f"{api_base}/v1/auth/agent-token").mock(
+        return_value=httpx.Response(
+            200,
+            json={"access_token": "jwt-one", "expires_in": 3600},
+        )
+    )
+    respx.get(f"{api_base}/v1/vaults/{vid}/secrets/api-keys%2Fstripe").mock(
+        return_value=httpx.Response(
+            200,
+            json={"value": "sk_test_abc", "path": "api-keys/stripe", "version": 1},
+        )
+    )
+
+    client = OneclawClient(
+        agent_id=aid,
+        api_key="ocv_testkey",
+        vault_id=vid,
+        base_url=api_base,
+    )
+    try:
+        assert client.get_secret("api-keys/stripe") == "sk_test_abc"
+    finally:
+        client.close()
+
+
+@respx.mock
+def test_jwt_caching_single_auth_for_two_fetches(api_base: str) -> None:
+    vid = _vault_id()
+    aid = _agent_id()
+    auth_route = respx.post(f"{api_base}/v1/auth/agent-token").mock(
+        return_value=httpx.Response(
+            200,
+            json={"access_token": "jwt-one", "expires_in": 3600},
+        )
+    )
+    respx.get(f"{api_base}/v1/vaults/{vid}/secrets/a").mock(
+        return_value=httpx.Response(200, json={"value": "v1"}),
+    )
+    respx.get(f"{api_base}/v1/vaults/{vid}/secrets/b").mock(
+        return_value=httpx.Response(200, json={"value": "v2"}),
+    )
+
+    client = OneclawClient(
+        agent_id=aid,
+        api_key="ocv_testkey",
+        vault_id=vid,
+        base_url=api_base,
+    )
+    try:
+        assert client.get_secret("a") == "v1"
+        assert client.get_secret("b") == "v2"
+        assert auth_route.call_count == 1
+    finally:
+        client.close()
+
+
+@respx.mock
+@pytest.mark.parametrize("status", [401, 403])
+def test_auth_error_on_token_failure(api_base: str, status: int) -> None:
+    vid = _vault_id()
+    aid = _agent_id()
+    respx.post(f"{api_base}/v1/auth/agent-token").mock(
+        return_value=httpx.Response(status, json={"detail": "nope"}),
+    )
+
+    client = OneclawClient(
+        agent_id=aid,
+        api_key="ocv_testkey",
+        vault_id=vid,
+        base_url=api_base,
+    )
+    try:
+        with pytest.raises(OneclawAuthError):
+            client.get_secret("x")
+    finally:
+        client.close()
+
+
+@respx.mock
+def test_secret_not_found(api_base: str) -> None:
+    vid = _vault_id()
+    aid = _agent_id()
+    respx.post(f"{api_base}/v1/auth/agent-token").mock(
+        return_value=httpx.Response(200, json={"access_token": "jwt", "expires_in": 3600}),
+    )
+    respx.get(f"{api_base}/v1/vaults/{vid}/secrets/missing").mock(
+        return_value=httpx.Response(404, json={"detail": "not found"}),
+    )
+
+    client = OneclawClient(
+        agent_id=aid,
+        api_key="ocv_testkey",
+        vault_id=vid,
+        base_url=api_base,
+    )
+    try:
+        with pytest.raises(OneclawSecretNotFoundError):
+            client.get_secret("missing")
+    finally:
+        client.close()
+
+
+@respx.mock
+def test_other_http_error(api_base: str) -> None:
+    vid = _vault_id()
+    aid = _agent_id()
+    respx.post(f"{api_base}/v1/auth/agent-token").mock(
+        return_value=httpx.Response(200, json={"access_token": "jwt", "expires_in": 3600}),
+    )
+    respx.get(f"{api_base}/v1/vaults/{vid}/secrets/boom").mock(
+        return_value=httpx.Response(500, json={"detail": "server"}),
+    )
+
+    client = OneclawClient(
+        agent_id=aid,
+        api_key="ocv_testkey",
+        vault_id=vid,
+        base_url=api_base,
+    )
+    try:
+        with pytest.raises(OneclawError):
+            client.get_secret("boom")
+    finally:
+        client.close()
+
+
+@respx.mock
+def test_token_refresh_when_near_expiry(api_base: str) -> None:
+    vid = _vault_id()
+    aid = _agent_id()
+    auth = respx.post(f"{api_base}/v1/auth/agent-token").mock(
+        side_effect=[
+            httpx.Response(200, json={"access_token": "jwt-first", "expires_in": 100}),
+            httpx.Response(200, json={"access_token": "jwt-second", "expires_in": 3600}),
+        ]
+    )
+    get_route = respx.get(f"{api_base}/v1/vaults/{vid}/secrets/x").mock(
+        return_value=httpx.Response(200, json={"value": "ok"}),
+    )
+
+    client = OneclawClient(
+        agent_id=aid,
+        api_key="ocv_testkey",
+        vault_id=vid,
+        base_url=api_base,
+    )
+    try:
+        with freeze_time("2024-06-01T12:00:00Z") as frozen:
+            assert client.get_secret("x") == "ok"
+            frozen.tick(delta=timedelta(seconds=71))
+            assert client.get_secret("x") == "ok"
+        assert auth.call_count == 2
+        assert get_route.call_count == 2
+    finally:
+        client.close()

1claw_crewai_tools-0.1.0/tests/test_tool.py

@@ -0,0 +1,79 @@
+"""Tests for :mod:`oneclaw_crewai._tool`."""
+
+from __future__ import annotations
+
+import uuid
+from unittest.mock import patch
+
+import httpx
+import respx
+
+from oneclaw_crewai._client import OneclawAuthError
+from oneclaw_crewai._tool import OneclawVaultTool
+
+
+def _ids() -> tuple[str, str, str]:
+    return str(uuid.uuid4()), str(uuid.uuid4()), "ocv_testkey1234567890"
+
+
+@respx.mock
+def test_run_returns_secret_on_success() -> None:
+    agent_id, vault_id, api_key = _ids()
+    base = "https://api.1claw.example"
+    respx.post(f"{base}/v1/auth/agent-token").mock(
+        return_value=httpx.Response(200, json={"access_token": "jwt", "expires_in": 3600}),
+    )
+    respx.get(f"{base}/v1/vaults/{vault_id}/secrets/api-keys%2Fopenai").mock(
+        return_value=httpx.Response(200, json={"value": "the-key-material"}),
+    )
+
+    tool = OneclawVaultTool(
+        agent_id=agent_id,
+        api_key=api_key,
+        vault_id=vault_id,
+        base_url=base,
+    )
+    try:
+        assert tool._run("api-keys/openai") == "the-key-material"
+    finally:
+        if tool._client is not None:
+            tool._client.close()
+
+
+def test_run_returns_error_string_on_oneclaw_error() -> None:
+    agent_id, vault_id, api_key = _ids()
+    tool = OneclawVaultTool(
+        agent_id=agent_id,
+        api_key=api_key,
+        vault_id=vault_id,
+        base_url="https://api.1claw.example",
+    )
+    try:
+        assert tool._client is not None
+        with patch.object(
+            tool._client,
+            "get_secret",
+            side_effect=OneclawAuthError("denied"),
+        ):
+            out = tool._run("any/path")
+        assert out.startswith("[1claw error]")
+        assert "denied" in out
+    finally:
+        if tool._client is not None:
+            tool._client.close()
+
+
+def test_cache_function_disabled() -> None:
+    agent_id, vault_id, api_key = _ids()
+    tool = OneclawVaultTool(
+        agent_id=agent_id,
+        api_key=api_key,
+        vault_id=vault_id,
+        base_url="https://api.1claw.example",
+    )
+    try:
+        assert callable(tool.cache_function)
+        assert tool.cache_function({"path": "x"}, "out") is False
+    finally:
+        if tool._client is not None:
+            tool._client.close()