autoclaw 0.1.0__tar.gz

autoclaw-0.1.0/PKG-INFO

@@ -0,0 +1,64 @@
+Metadata-Version: 2.4
+Name: autoclaw
+Version: 0.1.0
+Summary: AutoClaw local-first workflow control plane
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+Requires-Dist: fastapi<1.0.0,>=0.115.12
+Requires-Dist: uvicorn[standard]<1.0.0,>=0.34.0
+Requires-Dist: sqlalchemy<3.0.0,>=2.0.40
+Requires-Dist: pydantic<3.0.0,>=2.11.3
+Requires-Dist: pydantic-settings<3.0.0,>=2.8.1
+Requires-Dist: mcp<2.0.0,>=1.27.1
+Requires-Dist: python-dotenv<2.0.0,>=1.1.0
+Requires-Dist: httpx<1.0.0,>=0.28.1
+Requires-Dist: platformdirs<5.0.0,>=4.3.7
+Requires-Dist: aiosqlite<1.0.0,>=0.21.0
+Provides-Extra: postgres
+Requires-Dist: asyncpg<1.0.0,>=0.30.0; extra == "postgres"
+Provides-Extra: dev
+Requires-Dist: pytest<9.0.0,>=8.3.5; extra == "dev"
+Requires-Dist: pytest-asyncio<1.0.0,>=0.26.0; extra == "dev"
+Requires-Dist: pytest-cov<7.0.0,>=6.1.1; extra == "dev"
+Requires-Dist: ruff<1.0.0,>=0.11.5; extra == "dev"
+Requires-Dist: mypy<2.0.0,>=1.15.0; extra == "dev"
+Requires-Dist: PyYAML<7.0.0,>=6.0.2; extra == "dev"
+Requires-Dist: types-PyYAML<7.0.0,>=6.0.12.20250326; extra == "dev"
+Requires-Dist: asyncpg<1.0.0,>=0.30.0; extra == "dev"
+
+# AutoClaw
+
+Last verified: 2026-05-07
+
+AutoClaw is a controlled agent runtime for multi-step work that must stay auditable, replayable, and operationally recoverable.
+
+This root README is a front-door router only. Canonical implementation, redesign, and execution truth lives under `docs/`.
+
+## Start here
+
+- Current shipped behavior: [docs/current/README.md](docs/current/README.md)
+- Target redesign contract: [docs/redesign/README.md](docs/redesign/README.md)
+- Redesign landing and phase execution: [docs/execution/README.md](docs/execution/README.md)
+- Docs map and reading guide: [docs/README.md](docs/README.md)
+- Coding-agent policy: [AGENTS.md](AGENTS.md)
+- Coding standards: [STYLE.md](STYLE.md)
+
+## Repo shape
+
+- `apps/api/` - backend API, runtime, DB, CLI, and tests
+- `definitions/` - workflow and definition content used by owning phases
+- `docs/` - current behavior, redesign contract, and execution canon
+- `scripts/` - repo tooling, including docs validation under `scripts/docs/`
+- `examples/` - example workflows and supporting artifacts
+
+## Common verification lanes
+
+- Local backend suite: `./.venv/bin/pytest -q apps/api/tests`
+- Docker/Postgres verification: `make test-api-db`
+- Docs freeze validation: `./.venv/bin/python scripts/docs/docs_freeze_validate.py`
+
+## Surface rule
+
+Use this page for fast routing only.
+
+Do not treat it as the authoritative source for detailed runtime behavior, redesign contracts, or phase-closeout status.

autoclaw-0.1.0/README.md

@@ -0,0 +1,36 @@
+# AutoClaw
+
+Last verified: 2026-05-07
+
+AutoClaw is a controlled agent runtime for multi-step work that must stay auditable, replayable, and operationally recoverable.
+
+This root README is a front-door router only. Canonical implementation, redesign, and execution truth lives under `docs/`.
+
+## Start here
+
+- Current shipped behavior: [docs/current/README.md](docs/current/README.md)
+- Target redesign contract: [docs/redesign/README.md](docs/redesign/README.md)
+- Redesign landing and phase execution: [docs/execution/README.md](docs/execution/README.md)
+- Docs map and reading guide: [docs/README.md](docs/README.md)
+- Coding-agent policy: [AGENTS.md](AGENTS.md)
+- Coding standards: [STYLE.md](STYLE.md)
+
+## Repo shape
+
+- `apps/api/` - backend API, runtime, DB, CLI, and tests
+- `definitions/` - workflow and definition content used by owning phases
+- `docs/` - current behavior, redesign contract, and execution canon
+- `scripts/` - repo tooling, including docs validation under `scripts/docs/`
+- `examples/` - example workflows and supporting artifacts
+
+## Common verification lanes
+
+- Local backend suite: `./.venv/bin/pytest -q apps/api/tests`
+- Docker/Postgres verification: `make test-api-db`
+- Docs freeze validation: `./.venv/bin/python scripts/docs/docs_freeze_validate.py`
+
+## Surface rule
+
+Use this page for fast routing only.
+
+Do not treat it as the authoritative source for detailed runtime behavior, redesign contracts, or phase-closeout status.

autoclaw-0.1.0/apps/api/app/api/deps.py

@@ -0,0 +1,36 @@
+from __future__ import annotations
+
+from typing import Annotated
+
+from fastapi import Header, status
+
+from app.api.errors import raise_operation_failure
+from app.config import get_settings
+from app.schemas.operation_failure import OperationFailureCode
+
+
+def _require_exact_api_key(
+    *,
+    provided_key: str | None,
+    expected_key: str,
+) -> None:
+    if provided_key != expected_key:
+        raise_operation_failure(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            code=OperationFailureCode.ILLEGAL_CALLER,
+            summary="missing or invalid API key",
+            retryable=False,
+            suggested_next_step="Provide the configured X-AutoClaw-API-Key header.",
+        )
+
+
+def require_api_key(
+    api_key: Annotated[str | None, Header(alias="X-AutoClaw-API-Key")] = None,
+) -> None:
+    _require_exact_api_key(provided_key=api_key, expected_key=get_settings().api_key)
+
+
+def require_internal_api_key(
+    api_key: Annotated[str | None, Header(alias="X-AutoClaw-API-Key")] = None,
+) -> None:
+    _require_exact_api_key(provided_key=api_key, expected_key=get_settings().internal_api_key)

autoclaw-0.1.0/apps/api/app/api/errors.py

@@ -0,0 +1,71 @@
+from __future__ import annotations
+
+from typing import NoReturn
+
+from fastapi import HTTPException
+from fastapi.exceptions import RequestValidationError
+
+import app.api.runtime_exception_mapping as runtime_exception_mapping
+from app.schemas.operation_failure import OperationFailure, OperationFailureCode
+
+
+def operation_failure(
+    *,
+    code: OperationFailureCode,
+    summary: str,
+    retryable: bool,
+    field_path: str | None = None,
+    suggested_next_step: str | None = None,
+) -> OperationFailure:
+    return OperationFailure(
+        code=code,
+        summary=summary,
+        retryable=retryable,
+        field_path=field_path,
+        suggested_next_step=suggested_next_step,
+    )
+
+
+def raise_operation_failure(
+    *,
+    status_code: int,
+    code: OperationFailureCode,
+    summary: str,
+    retryable: bool,
+    field_path: str | None = None,
+    suggested_next_step: str | None = None,
+) -> NoReturn:
+    raise HTTPException(
+        status_code=status_code,
+        detail=operation_failure(
+            code=code,
+            summary=summary,
+            retryable=retryable,
+            field_path=field_path,
+            suggested_next_step=suggested_next_step,
+        ).model_dump(mode="json"),
+    )
+
+
+def request_validation_failure(exc: RequestValidationError) -> OperationFailure:
+    first_error = exc.errors()[0] if exc.errors() else {}
+    loc = first_error.get("loc", ())
+    field_path = ".".join(str(part) for part in loc if part != "body") or None
+    return operation_failure(
+        code=OperationFailureCode.INVALID_REQUEST_SHAPE,
+        summary="request shape does not match the canonical runtime surface",
+        retryable=False,
+        field_path=field_path,
+        suggested_next_step=(
+            "Reread the canonical request shape and resend the request with only the live "
+            "required fields."
+        ),
+    )
+
+
+def runtime_exception_failure(exc: Exception) -> tuple[int, OperationFailure]:
+    return runtime_exception_mapping.runtime_exception_failure(exc)
+
+
+def raise_runtime_exception(exc: Exception) -> NoReturn:
+    runtime_exception_mapping.raise_runtime_exception(exc)

autoclaw-0.1.0/apps/api/app/api/router.py

@@ -0,0 +1,18 @@
+from fastapi import APIRouter
+
+from app.api.routes.callback import router as callback_router
+from app.api.routes.definitions import router as definitions_router
+from app.api.routes.health import router as health_router
+from app.api.routes.observability import router as observability_router
+from app.api.routes.operator import router as operator_router
+from app.api.routes.runtime import router as runtime_router
+from app.api.routes.tasks import router as tasks_router
+
+api_router = APIRouter()
+api_router.include_router(health_router)
+api_router.include_router(definitions_router)
+api_router.include_router(tasks_router)
+api_router.include_router(runtime_router)
+api_router.include_router(operator_router)
+api_router.include_router(callback_router)
+api_router.include_router(observability_router)

autoclaw-0.1.0/apps/api/app/api/routes/callback.py

@@ -0,0 +1,98 @@
+from __future__ import annotations
+
+from typing import Annotated
+
+from fastapi import APIRouter, Depends, Query
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.api.errors import raise_runtime_exception
+from app.db.session import get_db_session
+from app.runtime.contracts import ParentRootToolName
+from app.runtime.control.failures import invalid_request_shape_error
+from app.runtime.control.node_operations import (
+    BoundaryNodeOperation,
+    CheckpointNodeOperation,
+    ParentToolNodeOperation,
+    execute_node_operation,
+)
+from app.schemas.runtime import (
+    BoundaryRead,
+    BoundaryWrite,
+    CheckpointRead,
+    CheckpointWrite,
+    ParentToolCall,
+    ParentToolSuccess,
+)
+
+router = APIRouter(prefix="/callback", tags=["callback"])
+DBSession = Annotated[AsyncSession, Depends(get_db_session)]
+
+
+def _require_callback_session_key(session_key: str | None) -> str:
+    if session_key is None:
+        raise invalid_request_shape_error("callback session_key is required")
+    return session_key
+
+
+@router.post("/tasks/{task_id}/checkpoint", response_model=CheckpointRead)
+async def post_checkpoint(
+    task_id: str,
+    payload: CheckpointWrite,
+    session: DBSession,
+    session_key: str | None = Query(default=None),
+) -> CheckpointRead:
+    try:
+        return await execute_node_operation(
+            session,
+            task_id=task_id,
+            session_key=_require_callback_session_key(session_key),
+            operation=CheckpointNodeOperation(payload=payload),
+            invalid_summary="invalid callback session key",
+            stale_summary="stale callback session key",
+            inactive_summary="inactive callback session key",
+        )
+    except Exception as exc:  # pragma: no cover - thin HTTP wrapper
+        raise_runtime_exception(exc)
+
+
+@router.post("/tasks/{task_id}/boundary", response_model=BoundaryRead)
+async def post_boundary(
+    task_id: str,
+    payload: BoundaryWrite,
+    session: DBSession,
+    session_key: str | None = Query(default=None),
+) -> BoundaryRead:
+    try:
+        return await execute_node_operation(
+            session,
+            task_id=task_id,
+            session_key=_require_callback_session_key(session_key),
+            operation=BoundaryNodeOperation(payload=payload),
+            invalid_summary="invalid callback session key",
+            stale_summary="stale callback session key",
+            inactive_summary="inactive callback session key",
+        )
+    except Exception as exc:  # pragma: no cover - thin HTTP wrapper
+        raise_runtime_exception(exc)
+
+
+@router.post("/tasks/{task_id}/tools/{tool_name}", response_model=ParentToolSuccess)
+async def post_tool(
+    task_id: str,
+    tool_name: ParentRootToolName,
+    payload: ParentToolCall,
+    session: DBSession,
+    session_key: str | None = Query(default=None),
+) -> ParentToolSuccess:
+    try:
+        return await execute_node_operation(
+            session,
+            task_id=task_id,
+            session_key=_require_callback_session_key(session_key),
+            operation=ParentToolNodeOperation(tool_name=tool_name, payload=payload),
+            invalid_summary="invalid callback session key",
+            stale_summary="stale callback session key",
+            inactive_summary="inactive callback session key",
+        )
+    except Exception as exc:  # pragma: no cover - thin HTTP wrapper
+        raise_runtime_exception(exc)

autoclaw-0.1.0/apps/api/app/api/routes/definitions.py

@@ -0,0 +1,110 @@
+from __future__ import annotations
+
+from typing import Annotated
+
+from fastapi import APIRouter, Depends, Query, Response, status
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.api.deps import require_api_key
+from app.api.errors import raise_runtime_exception
+from app.db.session import get_db_session
+from app.registry.definition_catalog import (
+    get_definition_detail,
+    list_policy_definitions,
+    list_role_definitions,
+    list_workflow_definitions,
+    upload_definition,
+)
+from app.registry.definition_history import get_definition_history
+from app.schemas.definitions import (
+    DefinitionKind,
+    DefinitionListQuery,
+    DefinitionRevisionDetailResponse,
+    DefinitionRevisionHistoryQuery,
+    DefinitionRevisionHistoryResponse,
+    DefinitionSummaryListResponse,
+    DefinitionUploadRequest,
+)
+
+router = APIRouter(
+    prefix="/definitions",
+    tags=["definitions"],
+    dependencies=[Depends(require_api_key)],
+)
+type DBSession = Annotated[AsyncSession, Depends(get_db_session)]
+type DefinitionListParams = Annotated[DefinitionListQuery, Query()]
+type DefinitionHistoryParams = Annotated[DefinitionRevisionHistoryQuery, Query()]
+
+
+@router.get("/roles", response_model=DefinitionSummaryListResponse)
+async def get_role_definitions(
+    session: DBSession,
+    query: DefinitionListParams,
+) -> DefinitionSummaryListResponse:
+    try:
+        return await list_role_definitions(session, query)
+    except Exception as exc:  # pragma: no cover - thin HTTP wrapper
+        raise_runtime_exception(exc)
+
+
+@router.get("/policies", response_model=DefinitionSummaryListResponse)
+async def get_policy_definitions(
+    session: DBSession,
+    query: DefinitionListParams,
+) -> DefinitionSummaryListResponse:
+    try:
+        return await list_policy_definitions(session, query)
+    except Exception as exc:  # pragma: no cover - thin HTTP wrapper
+        raise_runtime_exception(exc)
+
+
+@router.get("/workflows", response_model=DefinitionSummaryListResponse)
+async def get_workflow_definitions(
+    session: DBSession,
+    query: DefinitionListParams,
+) -> DefinitionSummaryListResponse:
+    try:
+        return await list_workflow_definitions(session, query)
+    except Exception as exc:  # pragma: no cover - thin HTTP wrapper
+        raise_runtime_exception(exc)
+
+
+@router.get("/{kind}/{key}", response_model=DefinitionRevisionDetailResponse)
+async def get_definition(
+    kind: DefinitionKind,
+    key: str,
+    session: DBSession,
+) -> DefinitionRevisionDetailResponse:
+    try:
+        return await get_definition_detail(session, kind, key)
+    except Exception as exc:  # pragma: no cover - thin HTTP wrapper
+        raise_runtime_exception(exc)
+
+
+@router.get("/{kind}/{key}/versions", response_model=DefinitionRevisionHistoryResponse)
+async def get_definition_versions(
+    kind: DefinitionKind,
+    key: str,
+    session: DBSession,
+    query: DefinitionHistoryParams,
+) -> DefinitionRevisionHistoryResponse:
+    try:
+        return await get_definition_history(session, kind, key, query)
+    except Exception as exc:  # pragma: no cover - thin HTTP wrapper
+        raise_runtime_exception(exc)
+
+
+@router.post("", response_model=DefinitionRevisionDetailResponse)
+async def post_definition(
+    request: DefinitionUploadRequest,
+    response: Response,
+    session: DBSession,
+) -> DefinitionRevisionDetailResponse:
+    try:
+        result = await upload_definition(session, request)
+        await session.commit()
+        response.status_code = status.HTTP_201_CREATED if result.created else status.HTTP_200_OK
+        return result.detail
+    except Exception as exc:  # pragma: no cover - thin HTTP wrapper
+        await session.rollback()
+        raise_runtime_exception(exc)

autoclaw-0.1.0/apps/api/app/api/routes/health.py

@@ -0,0 +1,24 @@
+from fastapi import APIRouter, HTTPException, status
+
+from app.db.session import ping_database
+from app.schemas.health import HealthResponse
+
+router = APIRouter(tags=["health"])
+
+
+@router.get("/healthz", response_model=HealthResponse, status_code=status.HTTP_200_OK)
+async def healthz() -> HealthResponse:
+    return HealthResponse(status="ok", service="autoclaw-api")
+
+
+@router.get("/readyz", response_model=HealthResponse, status_code=status.HTTP_200_OK)
+async def readyz() -> HealthResponse:
+    try:
+        await ping_database()
+    except Exception as exc:  # pragma: no cover - readiness degrades without DB
+        raise HTTPException(
+            status_code=status.HTTP_503_SERVICE_UNAVAILABLE,
+            detail="database_unavailable",
+        ) from exc
+
+    return HealthResponse(status="ready", service="autoclaw-api")

autoclaw-0.1.0/apps/api/app/api/routes/observability.py

@@ -0,0 +1,83 @@
+from __future__ import annotations
+
+from typing import Annotated
+
+from fastapi import APIRouter, Depends
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.api.deps import require_api_key
+from app.api.errors import raise_runtime_exception
+from app.db.session import get_db_session
+from app.runtime.control.observability import observability_ref
+from app.schemas.runtime import ObservabilityFileRef
+
+router = APIRouter(
+    prefix="/observability",
+    tags=["observability"],
+    dependencies=[Depends(require_api_key)],
+)
+DBSession = Annotated[AsyncSession, Depends(get_db_session)]
+
+
+@router.get("/tasks/{task_id}/delivery-state", response_model=ObservabilityFileRef)
+async def get_delivery_state(
+    task_id: str,
+    session: DBSession,
+) -> ObservabilityFileRef:
+    try:
+        return await observability_ref(
+            session,
+            task_id,
+            "delivery-state.json",
+            "Latest task-scoped delivery-state projection.",
+        )
+    except Exception as exc:  # pragma: no cover - thin HTTP wrapper
+        raise_runtime_exception(exc)
+
+
+@router.get("/tasks/{task_id}/continuity-state", response_model=ObservabilityFileRef)
+async def get_continuity_state(
+    task_id: str,
+    session: DBSession,
+) -> ObservabilityFileRef:
+    try:
+        return await observability_ref(
+            session,
+            task_id,
+            "continuity-state.json",
+            "Latest task-scoped continuity-state projection.",
+        )
+    except Exception as exc:  # pragma: no cover - thin HTTP wrapper
+        raise_runtime_exception(exc)
+
+
+@router.get("/tasks/{task_id}/watchdog-state", response_model=ObservabilityFileRef)
+async def get_watchdog_state(
+    task_id: str,
+    session: DBSession,
+) -> ObservabilityFileRef:
+    try:
+        return await observability_ref(
+            session,
+            task_id,
+            "watchdog-state.json",
+            "Latest task-scoped watchdog-state projection.",
+        )
+    except Exception as exc:  # pragma: no cover - thin HTTP wrapper
+        raise_runtime_exception(exc)
+
+
+@router.get("/tasks/{task_id}/provider-events", response_model=ObservabilityFileRef)
+async def get_provider_events(
+    task_id: str,
+    session: DBSession,
+) -> ObservabilityFileRef:
+    try:
+        return await observability_ref(
+            session,
+            task_id,
+            "provider-events.ndjson",
+            "Normalized provider-event history for the selected task.",
+        )
+    except Exception as exc:  # pragma: no cover - thin HTTP wrapper
+        raise_runtime_exception(exc)

autoclaw-0.1.0/apps/api/app/api/routes/operator.py

@@ -0,0 +1,51 @@
+from __future__ import annotations
+
+from typing import Annotated
+
+from fastapi import APIRouter, Depends, Query
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.api.deps import require_api_key
+from app.api.errors import raise_runtime_exception
+from app.db.session import get_db_session
+from app.runtime.control.observability import operator_snapshot, operator_trace
+from app.schemas.runtime import (
+    OperatorFlowSnapshotResponse,
+    OperatorFlowTraceQuery,
+    OperatorFlowTraceResponse,
+)
+
+router = APIRouter(prefix="/operator", tags=["operator"], dependencies=[Depends(require_api_key)])
+type DBSession = Annotated[AsyncSession, Depends(get_db_session)]
+type OperatorTraceParams = Annotated[OperatorFlowTraceQuery, Query()]
+
+
+@router.get("/tasks/{task_id}/snapshot", response_model=OperatorFlowSnapshotResponse)
+async def get_operator_snapshot(
+    task_id: str,
+    session: DBSession,
+) -> OperatorFlowSnapshotResponse:
+    try:
+        return await operator_snapshot(session, task_id)
+    except Exception as exc:  # pragma: no cover - thin HTTP wrapper
+        raise_runtime_exception(exc)
+
+
+@router.get("/tasks/{task_id}/trace", response_model=OperatorFlowTraceResponse)
+async def get_operator_trace(
+    task_id: str,
+    session: DBSession,
+    query: OperatorTraceParams,
+) -> OperatorFlowTraceResponse:
+    try:
+        return await operator_trace(
+            session,
+            task_id,
+            scope=query.scope,
+            q=query.q,
+            cursor=query.cursor,
+            limit=query.limit,
+            sort=query.sort,
+        )
+    except Exception as exc:  # pragma: no cover - thin HTTP wrapper
+        raise_runtime_exception(exc)