runlayer-hooks-sdk 0.1.0__tar.gz

runlayer_hooks_sdk-0.1.0/.gitignore

@@ -0,0 +1,94 @@
+.vscode
+.idea
+.mcp.json
+.worktrees
+node_modules/
+.pnpm-store
+/test-results/
+/playwright-report/
+/blob-report/
+/playwright/.cache/
+
+# Environment variables
+.env
+.env.local
+
+# Local development instance tracking (for multi-instance support)
+.local-instance
+.env.staging
+.env.production
+.env.*
+!.env.example
+!.env.local.example
+
+# Terraform
+terraform.tfstate
+terraform.tfstate.*
+*.tfstate
+*.tfstate.*
+.terraform/
+.terraform.lock.hcl
+terraform.tfvars
+terraform.*.tfvars
+tfplan
+
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.pyc
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+dist-test/
+downloads/
+eggs/
+.eggs/
+.libs/
+*.libs/
+*.libs/
+*.dist-info/
+psycopg*/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+.DS_Store
+.worktrees/
+.history/
+playwright/.auth
+backend/scripts/catalog_validation_results.json
+
+# We don't want to commit cursor plans
+.cursor/plans/
+# More agent stuff we don't want to commit
+.claude/worktrees/
+
+# Local stuff (kept as references for agents)
+mcp-manager.sh/
+typescript-sdk/
+vitor-plans/
+.superset/attachments
+
+# Local development tracking files (for multi-instance support)
+.local-pids
+
+# SBOM local generation output + tool cache
+sbom/
+.cache/sbom-tools/
+
+# Vulnerability scan output
+vuln/
+
+# Test artifacts
+backend/test_output.txt
+
+# Local ops-console rollout notes
+ops-console-deploy-checklist.local.md

runlayer_hooks_sdk-0.1.0/Makefile

@@ -0,0 +1,26 @@
+.PHONY: check check-fix format format-check lint lint-fix type-check test build
+
+check: format-check lint type-check
+
+check-fix: format lint-fix type-check
+
+format:
+	uv run ruff format .
+
+format-check:
+	uv run ruff format --check .
+
+lint:
+	uv run ruff check .
+
+lint-fix:
+	uv run ruff check --fix .
+
+type-check:
+	uv run ty check .
+
+test:
+	uv run pytest
+
+build:
+	uv build

runlayer_hooks_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,128 @@
+Metadata-Version: 2.4
+Name: runlayer-hooks-sdk
+Version: 0.1.0
+Summary: Runlayer Hooks SDK for Python agent runtimes
+Project-URL: Homepage, https://runlayer.com
+Project-URL: Documentation, https://docs.runlayer.com/
+Author-email: Runlayer <engineering@runlayer.com>
+License: Apache-2.0
+Keywords: agent,llm,mcp,runlayer,security
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+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: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Requires-Dist: httpx==0.28.1
+Description-Content-Type: text/markdown
+
+# Runlayer Hooks Python SDK
+
+Python SDK companion to `@runlayer/hooks-sdk`.
+
+## Configure
+
+```sh
+export RUNLAYER_BASE_URL="https://your-runlayer-instance.com"
+export RUNLAYER_API_KEY="rl_..."
+```
+
+Agent account auth is also supported:
+
+```sh
+export RUNLAYER_BASE_URL="https://your-runlayer-instance.com"
+export RUNLAYER_AGENT_CLIENT_ID="client_..."
+export RUNLAYER_AGENT_CLIENT_SECRET="..."
+```
+
+Optional OBO subject fields:
+
+```sh
+export RUNLAYER_AGENT_SUBJECT_TOKEN="user@example.com"
+export RUNLAYER_AGENT_SUBJECT_TOKEN_TYPE="urn:runlayer:token-type:user-email"
+```
+
+Optional runtime controls:
+
+| Variable | Purpose |
+| --- | --- |
+| `RUNLAYER_HOOK_TIMEOUT_MS` | Hook request timeout. Defaults to `10000`. |
+| `RUNLAYER_HOOK_MAX_TOOL_OUTPUT_BYTES` | Maximum serialized tool output sent to Runlayer. Defaults to `65536`. |
+| `RUNLAYER_HOOK_ENFORCEMENT_FAILURE_MODE` | Defaults to `closed`; set to `open` only if tool calls should continue when Runlayer is unreachable. |
+| `RUNLAYER_ALLOW_INSECURE_TRANSPORT=1` | Allow non-HTTPS `RUNLAYER_BASE_URL` for local development. |
+
+## Usage
+
+```python
+from runlayer_sdk import RunlayerClient
+
+runlayer = RunlayerClient.from_env(client_version="my-agent/1.0.0")
+
+
+def run_local_tool(tool_input: dict[str, object]) -> str:
+    return "tool output"
+
+
+output = runlayer.run_tool(
+    execute=run_local_tool,
+    session_id="session-id",
+    tool_input={"command": "cat README.md"},
+    tool_name="Bash",
+    tool_type="shell",
+)
+```
+
+Use `tool_enforcement` to skip Runlayer-owned MCP tools or proxy URLs:
+
+```python
+runlayer = RunlayerClient.from_env(
+    tool_enforcement={
+        "ignored_mcp_server_names": ["github-preview"],
+        "skip_runlayer_mcp_proxy_urls": True,
+    }
+)
+```
+
+`RunlayerClient` exposes:
+
+- `emit_event`
+- `before_tool`
+- `after_tool`
+- `run_tool`
+- `should_enforce_tool`
+
+The package also exports `send_runlayer_preflight`.
+
+## Framework tool adapters
+
+Dependency-free adapters wrap common tool dictionary shapes:
+
+- `with_runlayer_vercel_ai_tool`
+- `with_runlayer_vercel_ai_tools`
+- `with_runlayer_openai_agents_tool`
+- `with_runlayer_google_adk_tool`
+- `run_runlayer_adapter_tool`
+
+## Claude Agent SDK hooks
+
+Use the adapter helpers when a Python agent runtime wants the same Claude Agent
+SDK hook output shapes as the Hooks TypeScript SDK:
+
+```python
+from runlayer_sdk import RunlayerClient, create_claude_agent_sdk_hooks
+
+runlayer = RunlayerClient.from_env()
+hooks = create_claude_agent_sdk_hooks(runlayer, include_stop=False)
+```
+
+The adapter exports:
+
+- `create_claude_agent_sdk_hooks`
+- `emit_claude_agent_sdk_transcript_stop`
+- `claude_agent_sdk_assistant_message_to_transcript_line`
+- `tool_type_from_name`
+
+TypeScript-style camelCase aliases are also available for SDK parity.

runlayer_hooks_sdk-0.1.0/README.md

@@ -0,0 +1,107 @@
+# Runlayer Hooks Python SDK
+
+Python SDK companion to `@runlayer/hooks-sdk`.
+
+## Configure
+
+```sh
+export RUNLAYER_BASE_URL="https://your-runlayer-instance.com"
+export RUNLAYER_API_KEY="rl_..."
+```
+
+Agent account auth is also supported:
+
+```sh
+export RUNLAYER_BASE_URL="https://your-runlayer-instance.com"
+export RUNLAYER_AGENT_CLIENT_ID="client_..."
+export RUNLAYER_AGENT_CLIENT_SECRET="..."
+```
+
+Optional OBO subject fields:
+
+```sh
+export RUNLAYER_AGENT_SUBJECT_TOKEN="user@example.com"
+export RUNLAYER_AGENT_SUBJECT_TOKEN_TYPE="urn:runlayer:token-type:user-email"
+```
+
+Optional runtime controls:
+
+| Variable | Purpose |
+| --- | --- |
+| `RUNLAYER_HOOK_TIMEOUT_MS` | Hook request timeout. Defaults to `10000`. |
+| `RUNLAYER_HOOK_MAX_TOOL_OUTPUT_BYTES` | Maximum serialized tool output sent to Runlayer. Defaults to `65536`. |
+| `RUNLAYER_HOOK_ENFORCEMENT_FAILURE_MODE` | Defaults to `closed`; set to `open` only if tool calls should continue when Runlayer is unreachable. |
+| `RUNLAYER_ALLOW_INSECURE_TRANSPORT=1` | Allow non-HTTPS `RUNLAYER_BASE_URL` for local development. |
+
+## Usage
+
+```python
+from runlayer_sdk import RunlayerClient
+
+runlayer = RunlayerClient.from_env(client_version="my-agent/1.0.0")
+
+
+def run_local_tool(tool_input: dict[str, object]) -> str:
+    return "tool output"
+
+
+output = runlayer.run_tool(
+    execute=run_local_tool,
+    session_id="session-id",
+    tool_input={"command": "cat README.md"},
+    tool_name="Bash",
+    tool_type="shell",
+)
+```
+
+Use `tool_enforcement` to skip Runlayer-owned MCP tools or proxy URLs:
+
+```python
+runlayer = RunlayerClient.from_env(
+    tool_enforcement={
+        "ignored_mcp_server_names": ["github-preview"],
+        "skip_runlayer_mcp_proxy_urls": True,
+    }
+)
+```
+
+`RunlayerClient` exposes:
+
+- `emit_event`
+- `before_tool`
+- `after_tool`
+- `run_tool`
+- `should_enforce_tool`
+
+The package also exports `send_runlayer_preflight`.
+
+## Framework tool adapters
+
+Dependency-free adapters wrap common tool dictionary shapes:
+
+- `with_runlayer_vercel_ai_tool`
+- `with_runlayer_vercel_ai_tools`
+- `with_runlayer_openai_agents_tool`
+- `with_runlayer_google_adk_tool`
+- `run_runlayer_adapter_tool`
+
+## Claude Agent SDK hooks
+
+Use the adapter helpers when a Python agent runtime wants the same Claude Agent
+SDK hook output shapes as the Hooks TypeScript SDK:
+
+```python
+from runlayer_sdk import RunlayerClient, create_claude_agent_sdk_hooks
+
+runlayer = RunlayerClient.from_env()
+hooks = create_claude_agent_sdk_hooks(runlayer, include_stop=False)
+```
+
+The adapter exports:
+
+- `create_claude_agent_sdk_hooks`
+- `emit_claude_agent_sdk_transcript_stop`
+- `claude_agent_sdk_assistant_message_to_transcript_line`
+- `tool_type_from_name`
+
+TypeScript-style camelCase aliases are also available for SDK parity.

runlayer_hooks_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,44 @@
+[project]
+name = "runlayer-hooks-sdk"
+version = "0.1.0"
+description = "Runlayer Hooks SDK for Python agent runtimes"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "Apache-2.0" }
+authors = [{ name = "Runlayer", email = "engineering@runlayer.com" }]
+keywords = ["mcp", "runlayer", "agent", "llm", "security"]
+classifiers = [
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: Apache Software License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = [
+  "httpx==0.28.1",
+]
+
+[dependency-groups]
+dev = [
+  "anyio==4.13.0",
+  "pytest==9.0.3",
+  "ruff==0.15.10",
+  "ty==0.0.31",
+]
+
+[project.urls]
+Homepage = "https://runlayer.com"
+Documentation = "https://docs.runlayer.com/"
+
+[tool.uv]
+exclude-newer = "7 days"
+
+[build-system]
+build-backend = "hatchling.build"
+requires = ["hatchling==1.27.0"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["runlayer_sdk"]

runlayer_hooks_sdk-0.1.0/runlayer_sdk/__init__.py

@@ -0,0 +1,158 @@
+"""Runlayer Hooks Python SDK."""
+
+from runlayer_sdk.client import RunlayerClient, RunlayerHookClient
+from runlayer_sdk.claude_agent_sdk import (
+    ClaudeAgentSdkHooksOptions,
+    ClaudeAgentSdkTranscriptStopOptions,
+    claudeAgentSdkAssistantMessageToTranscriptLine,
+    claude_agent_sdk_assistant_message_to_transcript_line,
+    createClaudeAgentSdkHooks,
+    create_claude_agent_sdk_hooks,
+    emitClaudeAgentSdkTranscriptStop,
+    emit_claude_agent_sdk_transcript_stop,
+    toolTypeFromName,
+    tool_type_from_name,
+)
+from runlayer_sdk.types import (
+    AgentAccountOptions,
+    AfterToolOptions,
+    AfterToolResult,
+    AgentSubjectTokenType,
+    BeforeToolOptions,
+    BeforeToolResult,
+    EnforceMcpSourceOptions,
+    FetchLike,
+    FetchResponse,
+    HookEventName,
+    JsonObject,
+    RunlayerAgentAccountOptions,
+    RunlayerBlockedError,
+    RunlayerClientEnvOptions,
+    RunlayerClientOptions,
+    RunlayerEnforcementFailureMode,
+    RunlayerEnforcementUnavailableError,
+    RunlayerToolContext,
+    RunlayerToolEnforcementOptions,
+    RunlayerToolEnforcementPredicate,
+    RunToolOptions,
+)
+from runlayer_sdk.preflight import (
+    PreflightOptions,
+    PreflightResult,
+    sendRunlayerPreflight,
+    send_runlayer_preflight,
+)
+from runlayer_sdk.google_adk import (
+    GoogleAdkFunctionToolOptions,
+    GoogleAdkToolContext,
+    RunlayerGoogleAdkToolAdapterOptions,
+    withRunlayerGoogleAdkTool,
+    with_runlayer_google_adk_tool,
+)
+from runlayer_sdk.openai_agents_sdk import (
+    OpenAIAgentsFunctionToolOptions,
+    OpenAIAgentsToolCallDetails,
+    RunlayerOpenAIAgentsToolAdapterOptions,
+    withRunlayerOpenAIAgentsTool,
+    with_runlayer_openai_agents_tool,
+)
+from runlayer_sdk.tool_adapter import (
+    RunlayerAdapterMetadataResolver,
+    RunlayerAdapterRunOptions,
+    RunlayerAdapterToolExecute,
+    RunlayerAdapterToolExecution,
+    RunlayerToolAdapterOptions,
+    runRunlayerAdapterToolAsync,
+    runRunlayerAdapterTool,
+    run_runlayer_adapter_tool_async,
+    run_runlayer_adapter_tool,
+)
+from runlayer_sdk.tool_enforcement import (
+    isRunlayerMcpProxyUrl,
+    is_runlayer_mcp_proxy_url,
+    mcpServerNameFromToolName,
+    mcp_server_name_from_tool_name,
+    shouldEnforceTool,
+    should_enforce_tool,
+)
+from runlayer_sdk.vercel_ai_sdk import (
+    VercelAiTool,
+    VercelAiToolExecutionOptions,
+    VercelAiToolSet,
+    withRunlayerVercelAiTool,
+    withRunlayerVercelAiTools,
+    with_runlayer_vercel_ai_tool,
+    with_runlayer_vercel_ai_tools,
+)
+
+__all__ = [
+    "AgentAccountOptions",
+    "AfterToolOptions",
+    "AfterToolResult",
+    "AgentSubjectTokenType",
+    "BeforeToolOptions",
+    "BeforeToolResult",
+    "ClaudeAgentSdkHooksOptions",
+    "ClaudeAgentSdkTranscriptStopOptions",
+    "EnforceMcpSourceOptions",
+    "FetchLike",
+    "FetchResponse",
+    "GoogleAdkFunctionToolOptions",
+    "GoogleAdkToolContext",
+    "HookEventName",
+    "JsonObject",
+    "OpenAIAgentsFunctionToolOptions",
+    "OpenAIAgentsToolCallDetails",
+    "PreflightOptions",
+    "PreflightResult",
+    "RunlayerAdapterMetadataResolver",
+    "RunlayerAdapterRunOptions",
+    "RunlayerAdapterToolExecute",
+    "RunlayerAdapterToolExecution",
+    "RunToolOptions",
+    "RunlayerAgentAccountOptions",
+    "RunlayerBlockedError",
+    "RunlayerClient",
+    "RunlayerClientEnvOptions",
+    "RunlayerClientOptions",
+    "RunlayerEnforcementFailureMode",
+    "RunlayerEnforcementUnavailableError",
+    "RunlayerGoogleAdkToolAdapterOptions",
+    "RunlayerHookClient",
+    "RunlayerOpenAIAgentsToolAdapterOptions",
+    "RunlayerToolAdapterOptions",
+    "RunlayerToolContext",
+    "RunlayerToolEnforcementOptions",
+    "RunlayerToolEnforcementPredicate",
+    "VercelAiTool",
+    "VercelAiToolExecutionOptions",
+    "VercelAiToolSet",
+    "claudeAgentSdkAssistantMessageToTranscriptLine",
+    "claude_agent_sdk_assistant_message_to_transcript_line",
+    "createClaudeAgentSdkHooks",
+    "create_claude_agent_sdk_hooks",
+    "emitClaudeAgentSdkTranscriptStop",
+    "emit_claude_agent_sdk_transcript_stop",
+    "isRunlayerMcpProxyUrl",
+    "is_runlayer_mcp_proxy_url",
+    "mcpServerNameFromToolName",
+    "mcp_server_name_from_tool_name",
+    "runRunlayerAdapterToolAsync",
+    "runRunlayerAdapterTool",
+    "run_runlayer_adapter_tool_async",
+    "run_runlayer_adapter_tool",
+    "sendRunlayerPreflight",
+    "send_runlayer_preflight",
+    "shouldEnforceTool",
+    "should_enforce_tool",
+    "toolTypeFromName",
+    "tool_type_from_name",
+    "withRunlayerGoogleAdkTool",
+    "withRunlayerOpenAIAgentsTool",
+    "withRunlayerVercelAiTool",
+    "withRunlayerVercelAiTools",
+    "with_runlayer_google_adk_tool",
+    "with_runlayer_openai_agents_tool",
+    "with_runlayer_vercel_ai_tool",
+    "with_runlayer_vercel_ai_tools",
+]