harnessx 0.3.0__py3-none-any.whl

harnessx/__init__.py

@@ -0,0 +1,151 @@
+"""HarnessX — composable Python agents, tools, and durable execution."""
+
+import importlib.util as _importlib_util
+from importlib.metadata import PackageNotFoundError as _PackageNotFoundError, version as _dist_version
+
+try:
+    __version__ = _dist_version("harnessx")
+except _PackageNotFoundError:  # bare checkout without an installed distribution
+    __version__ = "0.0.0"
+
+from .core import Agent
+from .subagents import SubAgent
+from .extensions import Extension, ExtensionContext, LangSmithExtension, ResultSpillExtension
+from .mcp import MCPManager, MCPServerConfig, MCPToolInfo
+from .hooks import HookContext, HookEvent, HookManager, Middleware, MiddlewarePipeline
+from .memory import (
+    AgentMemory,
+    ConversationMemory,
+    InMemoryVectorStore,
+    LongTermMemory,
+    PersistentMemory,
+    VectorMemoryStore,
+)
+from .messages import Message, ContentBlock
+from .permissions import CliPermissionManager, CostLimitError, GuardrailsEngine, MaxIterationsError, PermissionManager
+from .providers import AnthropicProvider, LLMProvider, make_provider
+from .runtime import AgentRuntime, RunHandle
+from .recorder import IncidentRecorder, ExportPolicy, BundleLimits, IncidentError, VerificationReport, Playback, export_incident
+from ._journal import RecordingError
+from .backends.temporal import TemporalBackend, RedisEvents
+from .artifacts import S3ArtifactStore
+from .backends import SQLiteBackend, PostgresBackend, SchemaError, StorageError, SessionBusyError, LeaseLostError
+from .sandbox import Sandbox
+from .skills import Skill, SkillManager
+from .execution import RunEvent, RunEventType, RunResult, RunStatus, RunStream, RunFailure, PendingTool, ReplayPolicy, current_tool_context
+from .registry import AgentRef, AgentRegistry, agents
+from .tools import ToolNotFoundError, ToolRegistry, normalize_tool_registry
+from .types import (
+    AgentConfig,
+    CheckpointData,
+    PermissionLevel,
+    PromptCacheHint,
+    PromptCachePolicy,
+    ProviderResponse,
+    Role,
+    RuntimeConfig,
+    RuntimeState,
+    RuntimeStatus,
+    SandboxConfig,
+    SandboxResult,
+    SessionState,
+    StopReason,
+    StreamChunk,
+    TokenUsage,
+    ToolCall,
+    ToolDefinition,
+    ToolResult,
+)
+
+__all__ = [
+    "__version__",
+    # Core
+    "Agent",
+    "SubAgent",
+    "AgentConfig",
+    "PromptCachePolicy",
+    "PromptCacheHint",
+    "Role",
+    "StopReason",
+    "ProviderResponse",
+    "StreamChunk",
+    # Tools
+    "ToolRegistry",
+    "ToolDefinition",
+    "ToolCall",
+    "ToolResult",
+    "ToolNotFoundError",
+    "PermissionLevel",
+    "normalize_tool_registry",
+    # Memory
+    "ConversationMemory",
+    "Message", "ContentBlock",
+    "PersistentMemory",
+    "LongTermMemory",
+    "AgentMemory",
+    "VectorMemoryStore",
+    "InMemoryVectorStore",
+    "SessionState",
+    "TokenUsage",
+    # Permissions
+    "PermissionManager",
+    "CliPermissionManager",
+    "GuardrailsEngine",
+    "MaxIterationsError",
+    "CostLimitError",
+    # Hooks
+    "HookManager",
+    "HookEvent",
+    "HookContext",
+    "Middleware",
+    "MiddlewarePipeline",
+    # Streaming
+    "RunEvent", "RunEventType", "RunResult", "RunStatus", "RunStream",
+    "RunFailure", "PendingTool",
+    "ReplayPolicy", "current_tool_context", "AgentRef", "AgentRegistry", "agents",
+    # Sandbox
+    "Sandbox",
+    "SandboxConfig",
+    "SandboxResult",
+    # Runtime
+    "AgentRuntime", "RunHandle", "TemporalBackend", "RedisEvents", "S3ArtifactStore", "SQLiteBackend", "PostgresBackend",
+    "SchemaError", "StorageError", "SessionBusyError", "LeaseLostError",
+    "IncidentRecorder", "ExportPolicy", "BundleLimits", "IncidentError",
+    "VerificationReport", "Playback", "RecordingError",
+    "export_incident",
+    "RuntimeConfig",
+    "RuntimeState",
+    "RuntimeStatus",
+    "CheckpointData",
+    # MCP
+    "MCPManager",
+    "MCPServerConfig",
+    "MCPToolInfo",
+    # Skills
+    "Skill",
+    "SkillManager",
+    # Providers
+    "LLMProvider",
+    "AnthropicProvider",
+    "make_provider",
+    # Extensions
+    "Extension",
+    "ExtensionContext",
+    "LangSmithExtension",
+    "ResultSpillExtension",
+    # Evals
+    "evaluate_agent",
+]
+
+# Keep optional evaluation imports (and their environment setup) out of core startup.
+
+if _importlib_util.find_spec("langsmith") is None:
+    __all__.remove("evaluate_agent")
+
+
+def __getattr__(name):
+    if name == "evaluate_agent":
+        from .evals import evaluate_agent
+        globals()[name] = evaluate_agent
+        return evaluate_agent
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

harnessx/_journal.py

@@ -0,0 +1,46 @@
+"""Internal flight-recorder records. Payloads never enter the public event stream."""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+import uuid
+
+from .execution import wire
+
+
+class RecordingError(RuntimeError):
+    """A required recording boundary could not be committed."""
+
+
+def record(kind, payload, state, entry=None):
+    return {
+        "version": 1,
+        "id": str(uuid.uuid4()),
+        "kind": kind,
+        "recorded_at": datetime.now(timezone.utc).isoformat(),
+        "session_id": state["session_id"],
+        "run_id": state["run_id"],
+        "step_id": str(state.get("iterations", 0)),
+        "attempt_id": str((entry or state).get("attempt", 0)),
+        "execution_key": (entry or {}).get("execution_key"),
+        "payload": wire(payload),
+    }
+
+
+def checkpoint(state):
+    return {
+        "phase": state["phase"],
+        "status": state["status"],
+        "error": state.get("error"),
+        # Spill envelopes contain result IDs; the extension snapshot binds those
+        # IDs to portable artifact URIs without introducing a public reference API.
+        "extensions": state.get("extensions", {}),
+        "tools": [
+            {
+                key: tool[key]
+                for key in ("execution_key", "status", "attempt", "approved")
+                if key in tool
+            }
+            for tool in state.get("tools", [])
+        ],
+    }

harnessx/artifacts.py

@@ -0,0 +1,150 @@
+"""Portable, content-addressed artifacts; persisted state contains no host paths."""
+
+from __future__ import annotations
+import asyncio
+import hashlib
+from pathlib import Path
+import tempfile
+import os
+
+
+class DirectoryArtifactStore:
+    """Snapshot-owned artifacts, retained until PersistentMemory.delete_session()."""
+
+    def __init__(self, root):
+        self.root = Path(root)
+
+    async def put_artifact(self, content: bytes) -> str:
+        key = hashlib.sha256(content).hexdigest()
+
+        def write():
+            self.root.mkdir(parents=True, exist_ok=True)
+            with tempfile.NamedTemporaryFile(dir=self.root, delete=False) as output:
+                temporary = output.name
+                try:
+                    output.write(content)
+                    output.flush()
+                    os.fsync(output.fileno())
+                    os.replace(temporary, self.root / key)
+                finally:
+                    if os.path.exists(temporary):
+                        os.unlink(temporary)
+        await asyncio.to_thread(write)
+        return key
+
+    async def get_artifact(self, key: str) -> bytes:
+        if len(key) != 64 or any(c not in "0123456789abcdef" for c in key):
+            raise ValueError("Invalid artifact key")
+        content = await asyncio.to_thread((self.root / key).read_bytes)
+        if hashlib.sha256(content).hexdigest() != key:
+            raise ValueError("Artifact checksum mismatch")
+        return content
+
+
+def replace_paths(value, replacements):
+    if isinstance(value, str):
+        for old, new in sorted(
+            replacements.items(), key=lambda x: len(x[0]), reverse=True
+        ):
+            value = value.replace(old, new)
+        return value
+    if isinstance(value, dict):
+        return {k: replace_paths(v, replacements) for k, v in value.items()}
+    if isinstance(value, list):
+        return [replace_paths(v, replacements) for v in value]
+    return value
+
+
+async def capture(agent, state):
+    store = getattr(agent, "_artifact_store", None)
+    if store is None:
+        return state
+    paths = set(getattr(agent.memory, "_artifact_paths", set()))
+    for ext in state.get("extensions", {}).values():
+        if isinstance(ext, dict):
+            for result in ext.get("results", {}).values():
+                if isinstance(result, dict) and "path" in result:
+                    paths.add(result["path"])
+    replacements = dict(getattr(agent, "_artifact_uris", {}))
+    for path in paths:
+        if path.startswith("artifact://"):
+            continue
+        content = await asyncio.to_thread(Path(path).read_bytes)
+        key = await store.put_artifact(content)
+        replacements[path] = "artifact://" + key
+    agent._artifact_uris = replacements
+    return replace_paths(state, replacements)
+
+
+async def materialize(agent, state):
+    store = getattr(agent, "_artifact_store", None)
+    if store is None:
+        return state
+    import json
+    import re
+
+    keys = set(re.findall(r"artifact://([a-f0-9]{64})", json.dumps(state)))
+    replacements = {}
+    if not keys:
+        return state
+    if getattr(agent, "_materialized_artifacts", None) is None:
+        agent._materialized_artifacts = tempfile.TemporaryDirectory(prefix="harnessx-artifacts-")
+    root = Path(agent._materialized_artifacts.name)
+    for key in keys:
+        path = root / key
+        content = await store.get_artifact(key)
+        if hashlib.sha256(content).hexdigest() != key:
+            raise ValueError("Artifact checksum mismatch")
+        await asyncio.to_thread(path.write_bytes, content)
+        replacements["artifact://" + key] = str(path)
+    agent._artifact_uris = {path: uri for uri, path in replacements.items()}
+    agent.memory._artifact_paths.update(replacements.values())
+    return replace_paths(state, replacements)
+
+
+class S3ArtifactStore:
+    def __init__(self, bucket, *, prefix="harness-x/", endpoint_url=None, client=None):
+        self._owns_client = client is None
+        self.bucket, self.prefix, self.endpoint_url, self._client = (
+            bucket,
+            prefix,
+            endpoint_url,
+            client,
+        )
+
+    def _get_client(self):
+        if self._client is None:
+            import boto3
+
+            self._client = boto3.client("s3", endpoint_url=self.endpoint_url)
+        return self._client
+
+    async def put_artifact(self, content):
+        key = hashlib.sha256(content).hexdigest()
+        await asyncio.to_thread(
+            self._get_client().put_object,
+            Bucket=self.bucket,
+            Key=self.prefix + key,
+            Body=content,
+        )
+        return key
+
+    async def get_artifact(self, key):
+        if len(key) != 64 or any(c not in "0123456789abcdef" for c in key):
+            raise ValueError("Invalid artifact key")
+
+        def read():
+            body = self._get_client().get_object(
+                Bucket=self.bucket, Key=self.prefix + key
+            )["Body"]
+            try:
+                return body.read()
+            finally:
+                body.close()
+
+        return await asyncio.to_thread(read)
+
+    async def aclose(self):
+        if self._owns_client and self._client is not None:
+            await asyncio.to_thread(self._client.close)
+            self._client = None

harnessx/backends/__init__.py

@@ -0,0 +1,12 @@
+from .sqlite import SQLiteBackend
+from .postgres import PostgresBackend
+from .store import SchemaError, StorageError, SessionBusyError, LeaseLostError
+
+__all__ = [
+    "SQLiteBackend",
+    "PostgresBackend",
+    "SchemaError",
+    "StorageError",
+    "SessionBusyError",
+    "LeaseLostError",
+]

harnessx/backends/postgres.py

@@ -0,0 +1,238 @@
+"""PostgreSQL runtime storage; bootstraps an isolated, versioned schema."""
+
+from __future__ import annotations
+from contextlib import asynccontextmanager
+import hashlib
+import asyncio
+import uuid
+
+from .store import (
+    SQLStore,
+    TABLES,
+    MIGRATION_CHECKSUM,
+    SchemaError,
+    StorageError,
+    SessionBusyError,
+    LeaseLostError,
+    retry_transaction,
+)
+
+
+class PostgresTransaction:
+    def __init__(self, conn):
+        self.conn = conn
+
+    async def execute(self, sql, args=()):
+        return await self.conn.execute(postgres_bindings(sql), args)
+
+    async def one(self, sql, args=()):
+        return await (await self.execute(sql, args)).fetchone()
+
+    async def all(self, sql, args=()):
+        return await (await self.execute(sql, args)).fetchall()
+
+
+class PostgresBackend(SQLStore):
+    postgres = True
+
+    def __init__(
+        self,
+        connection_string: str,
+        *,
+        schema="harness_x",  # Preserve existing databases across the package rename.
+        auto_migrate=True,
+        lease_seconds=30,
+        pool_size=10,
+        artifact_store=None,
+    ):
+        if not schema or "\x00" in schema or len(schema.encode()) > 63:
+            raise ValueError(
+                "Schema must be a nonempty PostgreSQL identifier of at most 63 bytes"
+            )
+        if lease_seconds <= 0:
+            raise ValueError("lease_seconds must be positive")
+        self._dsn = connection_string
+        self.schema = schema
+        self.prefix = '"' + schema.replace('"', '""') + '".'
+        self.auto_migrate = auto_migrate
+        self.lease_seconds = lease_seconds
+        self.pool_size = pool_size
+        self.pool = None
+        self._initialized = False
+        self._init_lock = asyncio.Lock()
+        self._artifact_store = artifact_store
+
+    def __repr__(self):
+        return f"PostgresBackend(schema={self.schema!r}, connection_string=<redacted>)"
+
+    async def initialize(self):
+        async with self._init_lock:
+            if self._initialized:
+                return
+            await self._initialize()
+            self._initialized = True
+
+    async def _initialize(self):
+        try:
+            from psycopg_pool import AsyncConnectionPool
+        except ImportError:
+            raise ImportError("Install harnessx[postgres] to use PostgreSQL") from None
+        # Connection failures can include DSN credentials: expose only sanitized diagnostics.
+        try:
+            self.pool = AsyncConnectionPool(
+                self._dsn, min_size=0, max_size=self.pool_size, open=False, timeout=10
+            )
+            await self.pool.open()
+            await self.migrate(validate_only=not self.auto_migrate)
+        except SchemaError:
+            await self.aclose()
+            raise
+        except Exception:
+            await self.aclose()
+            raise StorageError(
+                "PostgreSQL initialization failed; check connectivity, TLS, and schema privileges"
+            ) from None
+
+    async def migrate(self, *, validate_only=False):
+        if self.pool is None:
+            # Explicit provisioning entry point for deployments using auto_migrate=False.
+            saved = self.auto_migrate
+            self.auto_migrate = not validate_only
+            try:
+                await self.initialize()
+            finally:
+                self.auto_migrate = saved
+            return
+        key = int.from_bytes(
+            hashlib.sha256(("harness_x:migrations:" + self.schema).encode()).digest()[
+                :8
+            ],
+            "big",
+            signed=True,
+        )
+        try:
+            async with self.transaction() as tx:
+                await tx.execute("SELECT pg_advisory_xact_lock(?)", (key,))
+                row = await tx.one(
+                    "SELECT EXISTS(SELECT 1 FROM information_schema.tables WHERE table_schema=? AND table_name=?)",
+                    (self.schema, "schema_versions"),
+                )
+                if not row[0]:
+                    if validate_only:
+                        raise SchemaError(
+                            "Schema missing; run backend.migrate() or enable auto_migrate"
+                        )
+                    await tx.execute(f"CREATE SCHEMA IF NOT EXISTS {self.prefix[:-1]}")
+                    for name, definition in TABLES.items():
+                        await tx.execute(
+                            f"CREATE TABLE {self.table(name)} ({definition.format(json='JSONB', blob='BYTEA', schema=self.prefix)})"
+                        )
+                    await tx.execute(
+                        f"CREATE INDEX runs_session ON {self.table('runs')}(session_id)"
+                    )
+                    await tx.execute(
+                        f"INSERT INTO {self.table('schema_versions')} VALUES (?,?)",
+                        (1, MIGRATION_CHECKSUM),
+                    )
+                await self._migrate_journal(tx, validate_only=validate_only)
+        except SchemaError:
+            raise
+        except Exception as exc:
+            code = getattr(exc, "sqlstate", "")
+            if code == "42501":
+                raise SchemaError(
+                    "Insufficient PostgreSQL privileges: schema provisioning needs database CREATE; migrations need ownership of Harness objects"
+                ) from None
+            raise SchemaError(
+                "Schema provisioning failed; conflicting objects or unavailable database (SQLSTATE "
+                + str(code)
+                + ")"
+            ) from None
+
+    @asynccontextmanager
+    async def transaction(self):
+        async with self.pool.connection() as conn:
+            async with conn.transaction():
+                yield PostgresTransaction(conn)
+
+    @retry_transaction
+    async def claim(self, session_id):
+        owner = str(uuid.uuid4())
+        async with self.transaction() as tx:
+            row = await tx.one(
+                f"UPDATE {self.table('sessions')} SET owner=?,generation=generation+1,lease_until=EXTRACT(EPOCH FROM clock_timestamp())+? WHERE id=? AND (owner IS NULL OR lease_until<EXTRACT(EPOCH FROM clock_timestamp())) RETURNING generation",
+                (owner, self.lease_seconds, session_id),
+            )
+            if row is None:
+                raise SessionBusyError(
+                    "Session is owned by another worker or does not exist"
+                )
+            return (owner, row[0])
+
+    async def _fence(self, tx, session_id, lease):
+        owner, generation = lease
+        row = await tx.one(
+            f"SELECT id FROM {self.table('sessions')} WHERE id=? AND owner=? AND generation=? AND lease_until>EXTRACT(EPOCH FROM clock_timestamp()) FOR UPDATE",
+            (session_id, owner, generation),
+        )
+        if row is None:
+            raise LeaseLostError("Session lease expired or was superseded")
+
+    @retry_transaction
+    async def renew(self, session_id, lease):
+        async with self.transaction() as tx:
+            await self._fence(tx, session_id, lease)
+            await tx.execute(
+                f"UPDATE {self.table('sessions')} SET lease_until=EXTRACT(EPOCH FROM clock_timestamp())+? WHERE id=?",
+                (self.lease_seconds, session_id),
+            )
+
+    @retry_transaction
+    async def release(self, session_id, lease):
+        async with self.transaction() as tx:
+            await tx.execute(
+                f"UPDATE {self.table('sessions')} SET owner=NULL,lease_until=0 WHERE id=? AND owner=? AND generation=?",
+                (session_id, *lease),
+            )
+
+    async def put_artifact(self, content):
+        if self._artifact_store is not None:
+            return await self._artifact_store.put_artifact(content)
+        return await super().put_artifact(content)
+
+    async def get_artifact(self, key):
+        if self._artifact_store is not None:
+            return await self._artifact_store.get_artifact(key)
+        return await super().get_artifact(key)
+
+    async def aclose(self):
+        self._initialized = False
+        if self.pool:
+            await self.pool.close()
+            self.pool = None
+
+
+def postgres_bindings(sql: str) -> str:
+    """Translate our qmark parameters without rewriting quoted identifiers/literals."""
+    result = []
+    quote = None
+    index = 0
+    while index < len(sql):
+        char = sql[index]
+        if quote:
+            result.append("%%" if char == "%" else char)
+            if char == quote:
+                if index + 1 < len(sql) and sql[index + 1] == quote:
+                    result.append(quote)
+                    index += 1
+                else:
+                    quote = None
+        elif char in ('"', "'"):
+            quote = char
+            result.append(char)
+        elif char == "?":
+            result.append("%s")
+        else:
+            result.append("%%" if char == "%" else char)
+        index += 1
+    return "".join(result)