pulse-coding-agent 0.1.0__py3-none-any.whl

pulse/runtime.py

@@ -0,0 +1,217 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+from pulse.agent import ProjectAgent
+from pulse.agent_manager import (
+    AgentManager,
+    DocumentationAgent,
+    GitAgent,
+    PlannerAgent,
+    ReviewerAgent,
+    SoftwareEngineerAgent,
+    TesterAgent,
+)
+from pulse.audit import AuditLog
+from pulse.auth import AuthenticationManager
+from pulse.config import AgentConfig, load_agent_config
+from pulse.context import ContextManager
+from pulse.core.planner import RequestPlanner
+from pulse.edits import EditWorkflow
+from pulse.git import GitIntelligence
+from pulse.memory import LongTermMemory
+from pulse.mutations import MutationTracker
+from pulse.provider import ModelProvider
+from pulse.providers.manager import ProviderManager
+from pulse.reasoning import ReasoningEngine
+from pulse.repository import RepositoryIndex
+from pulse.sandbox import ProjectSandbox
+from pulse.session_manager import SessionManager
+from pulse.software_engineer import AutonomousSoftwareEngineer
+from pulse.streaming import StreamingExecutionEngine
+from pulse.task_manager import TaskManager
+from pulse.telemetry import TelemetryLogger
+from pulse.tool_policy import ToolPolicyEngine
+from pulse.tool_registry import ToolInvocation, ToolRegistry
+from pulse.tools import (
+    DoctorTool,
+    EditTool,
+    GitTool,
+    IndexTool,
+    MemoryTool,
+    MutationsTool,
+    RollbackTool,
+    SearchTool,
+    SessionTool,
+    StatusTool,
+    SymbolsTool,
+    TaskTool,
+    VerifyTool,
+)
+from pulse.verification import VerificationEngine
+
+
+@dataclass(slots=True)
+class AgentRuntime:
+    workspace: Path
+    config: AgentConfig
+    audit: AuditLog
+    mutations: MutationTracker
+    sandbox: ProjectSandbox
+    provider: ModelProvider
+    agent: ProjectAgent
+    edits: EditWorkflow
+    tools: ToolRegistry
+    repository: RepositoryIndex
+    verification: VerificationEngine
+    git: GitIntelligence
+    memory: LongTermMemory
+    manager: AgentManager
+    task_manager: TaskManager
+    session_manager: SessionManager
+    context_manager: ContextManager
+    reasoning_engine: ReasoningEngine
+    planner: RequestPlanner
+    streaming_engine: StreamingExecutionEngine
+    software_engineer: AutonomousSoftwareEngineer
+    auth: AuthenticationManager
+    telemetry: TelemetryLogger
+
+
+def build_runtime(workspace: Path, config: AgentConfig | None = None) -> AgentRuntime:
+    resolved_workspace = workspace.resolve()
+    resolved_config = config or load_agent_config(resolved_workspace)
+    audit = AuditLog(resolved_config.logging.action_log)
+    telemetry = TelemetryLogger(resolved_config.logging.telemetry_log)
+    mutations = MutationTracker(resolved_workspace)
+    sandbox = ProjectSandbox(resolved_config.sandbox, audit, mutations)
+
+    provider_manager = ProviderManager(resolved_workspace)
+    provider = provider_manager.create_provider(
+        resolved_config.model, resolved_workspace / ".env"
+    )
+    audit.add_secret(getattr(provider, "api_key", None))
+    telemetry.add_secret(getattr(provider, "api_key", None))
+
+    edits = EditWorkflow(sandbox)
+    repository = RepositoryIndex(resolved_workspace)
+    verification = VerificationEngine(resolved_workspace)
+    git = GitIntelligence(resolved_workspace)
+    memory = LongTermMemory(
+        resolved_workspace,
+        secrets=[provider.api_key] if getattr(provider, "api_key", None) else None,
+    )
+    task_manager = TaskManager(resolved_workspace, memory=memory, telemetry=telemetry)
+    session_manager = SessionManager(
+        resolved_workspace, task_manager=task_manager, telemetry=telemetry
+    )
+
+    async def check_permission(invocation: ToolInvocation, tool: object) -> bool:
+        return sandbox.request_project_action(
+            "run tool", getattr(tool, "name", "tool"), "This action changes the project."
+        )
+
+    tool_capabilities = frozenset(
+        {
+            "status", "doctor", "mutations", "edit", "rollback", "git", "memory",
+            "index", "search", "symbols", "verify", "task", "tasks", "resume", "cancel",
+            "session", "sessions", "resume-session",
+        }
+    )
+    tools = ToolRegistry(
+        [
+            StatusTool(resolved_config, provider), DoctorTool(resolved_workspace, resolved_config, provider),
+            MutationsTool(mutations), EditTool(edits, git), RollbackTool(edits), GitTool(git), MemoryTool(memory),
+        ],
+        permission_checker=check_permission,
+        telemetry=telemetry,
+        policy_engine=ToolPolicyEngine(
+            workspace=resolved_workspace,
+            allowed_capabilities=tool_capabilities,
+            audit_log=audit,
+        ),
+    )
+    tools.register(IndexTool(repository))
+    tools.register(SearchTool(repository))
+    tools.register(SymbolsTool(repository))
+    tools.register(VerifyTool(verification))
+    tools.register(TaskTool(task_manager))
+    tools.register(SessionTool(session_manager))
+
+    manager = AgentManager(
+        task_manager=task_manager,
+        agents=[
+            PlannerAgent(provider, tools),
+            SoftwareEngineerAgent(provider, tools),
+            ReviewerAgent(provider, tools),
+            TesterAgent(provider, tools),
+            DocumentationAgent(provider, tools),
+            GitAgent(provider, tools),
+        ],
+    )
+    agent = ProjectAgent(
+        resolved_config.agent_name,
+        sandbox,
+        provider,
+        audit,
+        tools,
+        repository,
+        memory,
+        manager,
+    )
+
+    context_manager = ContextManager(
+        repository=repository, memory=memory, git=git, workspace=resolved_workspace
+    )
+    reasoning_engine = ReasoningEngine(
+        provider=provider, context_manager=context_manager, tool_registry=tools
+    )
+    planner = RequestPlanner()
+    streaming_engine = StreamingExecutionEngine(
+        provider=provider,
+        tool_registry=tools,
+        reasoning_engine=reasoning_engine,
+        task_manager=task_manager,
+        telemetry=telemetry,
+        verification_engine=verification,
+    )
+    software_engineer = AutonomousSoftwareEngineer(
+        reasoning_engine=reasoning_engine,
+        planner=planner,
+        task_manager=task_manager,
+        session_manager=session_manager,
+        streaming_engine=streaming_engine,
+        verification_engine=verification,
+        context_manager=context_manager,
+        memory=memory,
+        repository=repository,
+        tool_registry=tools,
+    )
+    auth = AuthenticationManager(resolved_workspace)
+
+    return AgentRuntime(
+        workspace=resolved_workspace,
+        config=resolved_config,
+        audit=audit,
+        mutations=mutations,
+        sandbox=sandbox,
+        provider=provider,
+        agent=agent,
+        edits=edits,
+        tools=tools,
+        repository=repository,
+        verification=verification,
+        git=git,
+        memory=memory,
+        manager=manager,
+        task_manager=task_manager,
+        session_manager=session_manager,
+        context_manager=context_manager,
+        reasoning_engine=reasoning_engine,
+        planner=planner,
+        streaming_engine=streaming_engine,
+        software_engineer=software_engineer,
+        auth=auth,
+        telemetry=telemetry,
+    )

pulse/safety/__init__.py

@@ -0,0 +1,3 @@
+from pulse.safety.safety_manager import RiskLevel, SafetyManager
+
+__all__ = ["RiskLevel", "SafetyManager"]

pulse/safety/safety_manager.py

@@ -0,0 +1,97 @@
+from __future__ import annotations
+
+import asyncio
+from collections.abc import Awaitable, Callable
+from enum import Enum
+
+from pulse.audit import AuditLog
+
+
+class RiskLevel(Enum):
+    LOW = "LOW"        # Read-only operations
+    MEDIUM = "MEDIUM"  # File edits and test executions
+    HIGH = "HIGH"      # System execution, shell commands, or file deletion
+
+
+class SafetyManager:
+    """Assesses action risk levels, enforces user confirmation for HIGH risk actions, and records audit logs."""
+
+    def __init__(
+        self,
+        audit_log: AuditLog | None = None,
+        confirmation_callback: Callable[[str, RiskLevel], bool | Awaitable[bool]] | None = None,
+    ) -> None:
+        self.audit_log = audit_log
+        self.confirmation_callback = confirmation_callback
+
+    def assess_risk(self, action: str, target: str = "") -> RiskLevel:
+        action_lower = action.lower()
+        target_lower = target.lower()
+
+        # HIGH risk: system command execution, shell access, deletion
+        high_keywords = {
+            "execute",
+            "system",
+            "shell",
+            "delete",
+            "remove",
+            "destroy",
+            "drop",
+            "unlink",
+            "bash",
+            "cmd",
+            "terminal",
+            "eval",
+        }
+        if any(kw in action_lower for kw in high_keywords) or "delete" in target_lower or "remove" in target_lower:
+            return RiskLevel.HIGH
+
+        # MEDIUM risk: edits, code modifications, writing files, running test suites
+        medium_keywords = {
+            "edit",
+            "modify",
+            "write",
+            "update",
+            "patch",
+            "test",
+            "pytest",
+            "mutate",
+            "create",
+        }
+        if any(kw in action_lower for kw in medium_keywords):
+            return RiskLevel.MEDIUM
+
+        return RiskLevel.LOW
+
+    async def authorize(self, action: str, target: str = "", detail: str = "") -> bool:
+        risk = self.assess_risk(action, target)
+        authorized = True
+
+        if risk is RiskLevel.HIGH:
+            if self.confirmation_callback is not None:
+                res = self.confirmation_callback(action, risk)
+                if asyncio.iscoroutine(res) or hasattr(res, "__await__"):
+                    authorized = bool(await res)
+                else:
+                    authorized = bool(res)
+            else:
+                authorized = False
+
+        if self.audit_log:
+            status = "APPROVED" if authorized else "REJECTED"
+            self.audit_log.record(
+                action=f"safety-{risk.value.lower()}-{status.lower()}",
+                file=target or ".",
+                detail=f"Action: {action} | Risk: {risk.value} | Authorized: {authorized} | {detail}".strip(" |"),
+            )
+
+        return authorized
+
+    def log_audit(self, action: str, target: str, detail: str, risk: RiskLevel | None = None) -> None:
+        if self.audit_log:
+            risk_label = risk.value if risk else "UNKNOWN"
+            self.audit_log.record(
+                action=action,
+                file=target or ".",
+                detail=f"[{risk_label}] {detail}",
+            )

pulse/sandbox/SECURITY.md

@@ -0,0 +1,57 @@
+# Pulse Secure Sandbox — Security Architecture
+
+## Isolation Models
+
+The Pulse Sandbox provides multiple layers of defense to execute untrusted code safely. 
+We categorize security controls into Prevention, Detection, and Redaction.
+
+### Prevention (Isolation)
+- **Tool Authorization**: Model-produced tool arguments are validated against
+  typed schemas before execution. `ToolPolicyEngine` evaluates a per-runtime
+  capability allowlist, workspace scope, risk level, and approval requirement.
+  Unknown capabilities, malformed arguments, and paths outside the configured
+  workspace are rejected before a tool receives them.
+- **Containerization**: `DockerBackend` enforces process isolation, filesystem isolation, and network isolation using namespaces and cgroups. 
+- **Remote Execution**: `RemoteSandboxBackend` enables untrusted code to run on a dedicated remote host via the `pulse-remote` worker daemon. This physical/network separation prevents any host escape from affecting the local development machine, with communication secured via authenticated WSS.
+- **Secret Injection**: Secrets are explicitly injected into the container environment via temporary `--env-file` structures stored outside the workspace. This prevents argv leakage (e.g. `ps aux`) and ensures robust lifecycle cleanup.
+- **Copy-on-Write Filesystem (CoW)**: Changes are strictly staged via CoW transactions. If explicitly authorized secrets are detected in staged files, the commit is outright rejected by the security engine to prevent secret persistence in snapshots.
+- **Path Validation**: TOCTOU-safe path verification prevents directory traversal and symlink escapes.
+
+### Detection (Auditing)
+- **Structured Audit Logging**: All security boundary interactions (reads, writes, network connections, execution) are logged securely in `audit.jsonl` with their resolved `isolation_level`.
+- **Policy Decision Logging**: Every central tool-policy decision records the
+  subject, capability, risk, and reason. Raw tool argument values are excluded
+  so audit records cannot become a second secret store.
+
+### Redaction (Scrubber)
+- **SecretScrubber**: In-memory regex and exact-value matching redaction engine scrub sensitive keys from standard output, errors, and audit logs. All regex patterns are optimized to prevent ReDoS.
+
+## Known Limitations & Unsupported Scopes
+
+- **Host Execution Fallback**: Running `HostBackend` is intrinsically unsafe for untrusted code execution. By default, the sandbox requires an explicit opt-in (`unsafe_host_execution=True`) which is audited and warned against.
+- **Process Group Termination Escapes**: On POSIX, a child process running directly on the host can escape `killpg()` termination by calling `setsid()`. This underscores the mandatory requirement for container-level isolation boundaries.
+- **Scoped Secret Access**: Providing per-network-request secret injection (Scoped Secrets) is **currently unsupported**. Given that network isolation and environment variable capabilities are decoupled, attempting to implement scoped secrets without strong OS/ebpf-level enforcement can lead to a false sense of security. Secrets injected into a container are accessible to any process within that container. 
+
+## Threat Model and Incident Response
+
+Pulse treats provider output, tool arguments, downloaded artifacts, and remote
+worker messages as untrusted. The intended deployment boundary is a dedicated
+container or remote worker; host execution is development-only and explicitly
+unsafe. The system is designed to contain path traversal, shell injection,
+archive attacks, unrestricted network egress, credential leakage, stale remote
+results, and cross-tenant remote execution access.
+
+If a remote token, client certificate, or provider credential may be exposed:
+
+1. Revoke the affected credential at its issuer and replace the configured
+   `PULSE_REMOTE_TOKEN` or TLS material on both worker and clients.
+2. Restart remote workers to terminate active sessions; inspect the durable
+   execution store and `audit.jsonl` for the affected tenant and execution IDs.
+3. Quarantine ambiguous tasks through recovery rather than retrying them with a
+   new external ID, then rotate any secrets mounted into the affected worker.
+4. Preserve redacted audit logs and the worker version/configuration for
+   incident review. Do not copy raw execution output into tickets.
+
+Remote workers must use `wss://` with mTLS outside loopback, have a dedicated
+tenant-isolated workspace volume, enforce a finite execution retention period,
+and expose health checks only on an authenticated operations network.

pulse/sandbox/__init__.py

@@ -0,0 +1,57 @@
+"""Secure sandbox subsystem public exports.
+
+The package keeps these exports lazy so importing a narrow helper such as
+``pulse.sandbox.secrets`` does not initialize the full sandbox stack.
+"""
+
+from __future__ import annotations
+
+from importlib import import_module
+from typing import Any
+
+_EXPORTS = {
+    "ActionType": "pulse.sandbox.policy",
+    "CoWFilesystem": "pulse.sandbox.filesystem",
+    "CoWTransaction": "pulse.sandbox.filesystem",
+    "ContainerBackend": "pulse.sandbox.backend",
+    "DockerBackend": "pulse.sandbox.backend",
+    "ExecutionMetrics": "pulse.sandbox.resources",
+    "HostBackend": "pulse.sandbox.backend",
+    "PathValidationError": "pulse.sandbox.path_validator",
+    "PathValidator": "pulse.sandbox.path_validator",
+    "PolicyDecision": "pulse.sandbox.policy",
+    "PolicyRule": "pulse.sandbox.policy",
+    "ProcessManager": "pulse.sandbox.process",
+    "ProcessResult": "pulse.sandbox.process",
+    "ProjectSandbox": "pulse.sandbox.project",
+    "ResourceController": "pulse.sandbox.resources",
+    "ResourceLimitExceeded": "pulse.sandbox.resources",
+    "ResourceLimiter": "pulse.sandbox.resources",
+    "ResourceLimits": "pulse.sandbox.resources",
+    "ResourceMonitor": "pulse.sandbox.resources",
+    "ResourcePolicy": "pulse.sandbox.resources",
+    "SafeGit": "pulse.sandbox.git_safe",
+    "SafePython": "pulse.sandbox.python_safe",
+    "Sandbox": "pulse.sandbox.api",
+    "SandboxConcurrentModificationError": "pulse.sandbox.errors",
+    "SandboxPolicy": "pulse.sandbox.policy",
+    "SandboxResourceError": "pulse.sandbox.errors",
+    "SandboxSecurityError": "pulse.sandbox.errors",
+    "SandboxSession": "pulse.sandbox.api",
+    "SandboxUnavailableError": "pulse.sandbox.errors",
+    "SecretScrubber": "pulse.sandbox.secrets",
+    "StructuredAuditEntry": "pulse.sandbox.audit",
+    "StructuredAuditLogger": "pulse.sandbox.audit",
+    "TimeoutExceeded": "pulse.sandbox.resources",
+}
+
+__all__ = tuple(sorted(_EXPORTS))
+
+
+def __getattr__(name: str) -> Any:
+    if name not in _EXPORTS:
+        raise AttributeError(name)
+    module = import_module(_EXPORTS[name])
+    value = getattr(module, name)
+    globals()[name] = value
+    return value