loki-mode 7.78.0 → 7.80.0

package/docs/INSTALLATION.md

@@ -2,7 +2,7 @@
 
 The flagship product of [Autonomi](https://www.autonomi.dev/). Loki Mode is a spec-driven autonomous builder with a built-in trust layer that takes any spec to a deployed product and verifies completion with evidence (quality gates plus a completion council), not just a "done" claim. Complete installation instructions for all platforms and use cases.
 
-**Version:** v7.78.0
+**Version:** v7.80.0
 
 ---
 
@@ -395,7 +395,7 @@ provider works inside the container. Provide auth with your Anthropic API key:
 # Run Loki Mode in Docker (Claude provider, API-key auth)
 docker run --rm -e ANTHROPIC_API_KEY="$ANTHROPIC_API_KEY" \
   -v $(pwd):/workspace -w /workspace \
-  asklokesh/loki-mode:7.78.0 start ./my-spec.md
+  asklokesh/loki-mode:7.80.0 start ./my-spec.md
 ```
 
 ##### docker compose + .env (no host install)

package/loki-ts/dist/loki.js

@@ -1,5 +1,5 @@
 // @bun
-var QQ=Object.defineProperty;var ZQ=($)=>$;function zQ($,Q){this[$]=ZQ.bind(null,Q)}var b=($,Q)=>{for(var Z in Q)QQ($,Z,{get:Q[Z],enumerable:!0,configurable:!0,set:zQ.bind(Q,Z)})};var L=($,Q)=>()=>($&&(Q=$($=0)),Q);var q$=import.meta.require;var h1={};b(h1,{lokiDir:()=>P,homeLokiDir:()=>i$,findRepoRootForVersion:()=>t$,REPO_ROOT:()=>g});import{resolve as a,dirname as r$}from"path";import{fileURLToPath as XQ}from"url";import{existsSync as R$}from"fs";import{homedir as KQ}from"os";function qQ(){let $=b1;for(let Q=0;Q<6;Q++){if(R$(a($,"VERSION"))&&R$(a($,"autonomy/run.sh")))return $;let Z=r$($);if(Z===$)break;$=Z}return a(b1,"..","..","..")}function t$($){let Q=$;for(let Z=0;Z<6;Z++){if(R$(a(Q,"VERSION"))&&R$(a(Q,"autonomy/run.sh")))return Q;let z=r$(Q);if(z===Q)break;Q=z}return a($,"..","..","..")}function P(){return process.env.LOKI_DIR??a(process.cwd(),".loki")}function i$(){return a(KQ(),".loki")}var b1,g;var C=L(()=>{b1=r$(XQ(import.meta.url));g=qQ()});import{readFileSync as VQ}from"fs";import{resolve as JQ,dirname as UQ}from"path";import{fileURLToPath as WQ}from"url";function E$(){if(Q$!==null)return Q$;let $="7.78.0";if(typeof $==="string"&&$.length>0)return Q$=$,Q$;try{let Q=UQ(WQ(import.meta.url)),Z=t$(Q);Q$=VQ(JQ(Z,"VERSION"),"utf-8").trim()}catch{Q$="unknown"}return Q$}var Q$=null;var e$=L(()=>{C()});var g1={};b(g1,{runOrThrow:()=>HQ,run:()=>F,readStreamCapped:()=>m1,commandVersion:()=>BQ,commandExists:()=>f,ShellError:()=>$1,MAX_STDOUT_BYTES:()=>v1});async function m1($,Q=v1){let Z=$.getReader(),z=new TextDecoder,X="",q=0;try{while(q<Q){let{done:K,value:U}=await Z.read();if(K)break;if(!U)continue;if(q+=U.byteLength,q>Q){let J=U.byteLength-(q-Q);X+=z.decode(U.subarray(0,J),{stream:!0});break}X+=z.decode(U,{stream:!0})}X+=z.decode()}finally{try{await Z.cancel()}catch{}Z.releaseLock()}return X}async function F($,Q={}){let Z=Bun.spawn({cmd:[...$],stdout:"pipe",stderr:"pipe",env:Q.env?{...process.env,...Q.env}:process.env,cwd:Q.cwd}),z,X;if(Q.timeoutMs&&Q.timeoutMs>0)z=setTimeout(()=>{try{Z.kill("SIGTERM")}catch{}X=setTimeout(()=>{try{Z.kill("SIGKILL")}catch{}},2000)},Q.timeoutMs);try{let[q,K,U]=await Promise.all([m1(Z.stdout),new Response(Z.stderr).text(),Z.exited]);return{stdout:q,stderr:K,exitCode:U}}finally{if(z)clearTimeout(z);if(X)clearTimeout(X)}}async function HQ($,Q={}){let Z=await F($,Q);if(Z.exitCode!==0)throw new $1(`command failed (${Z.exitCode}): ${$.join(" ")}`,Z.exitCode,Z.stdout,Z.stderr);return Z}async function f($){let Q=GQ($),Z=await F(["sh","-c",`command -v ${Q}`],{timeoutMs:5000});if(Z.exitCode===0)return Z.stdout.trim()||null;return null}function GQ($){if(!/^[A-Za-z0-9._/-]+$/.test($))throw Error(`refused to shell-escape suspect token: ${$}`);return $}async function BQ($,Q="--version"){if(!await f($))return null;let z=await F([$,Q],{timeoutMs:5000});if(z.exitCode!==0)return null;return((z.stdout||z.stderr).split(/\r?\n/)[0]?.trim()??"")||null}var v1=16777216,$1;var d=L(()=>{$1=class $1 extends Error{message;exitCode;stdout;stderr;constructor($,Q,Z,z){super($);this.message=$;this.exitCode=Q;this.stdout=Z;this.stderr=z;this.name="ShellError"}}});function s($){return YQ?"":$}var YQ,O,S,_,_Z,I,k,h,V;var c=L(()=>{YQ=(process.env.NO_COLOR??"").length>0;O=s("\x1B[0;31m"),S=s("\x1B[0;32m"),_=s("\x1B[1;33m"),_Z=s("\x1B[0;34m"),I=s("\x1B[0;36m"),k=s("\x1B[1m"),h=s("\x1B[2m"),V=s("\x1B[0m")});import{existsSync as jQ}from"fs";async function Z$(){if(Y$!==void 0)return Y$;let $="/opt/homebrew/bin/python3.12";if(jQ($))return Y$=$,$;let Q=await f("python3.12");if(Q)return Y$=Q,Q;let Z=await f("python3");return Y$=Z,Z}async function z$($,Q={}){let Z=await Z$();if(!Z)return{stdout:"",stderr:"python3 not found",exitCode:127};return F([Z,"-c",$],Q)}var Y$;var V$=L(()=>{d()});var X0={};b(X0,{runStatus:()=>oQ});import{existsSync as y,readFileSync as U$,readdirSync as r1,statSync as t1}from"fs";import{resolve as D,basename as vQ}from"path";import{homedir as mQ}from"os";function i1($){let Q=Math.trunc($);if(Q>=1e6)return`${(Math.trunc(Q/1e6*10)/10).toFixed(1)}M`;if(Q>=1000)return`${(Math.trunc(Q/1000*10)/10).toFixed(1)}K`;return String(Q)}function e1($,Q,Z){if(Q===0)return null;let z=Math.trunc($*100/Q),X=Math.trunc($*N$/Q);if(X>N$)X=N$;let q=N$-X,K=S;if(z>=80)K=O;else if(z>=50)K=_;let U="=".repeat(Math.max(0,X))+" ".repeat(Math.max(0,q)),J=i1($),W=i1(Q);return`  ${k}${Z}${V} ${K}[${U}]${V} ${z}% (${J} / ${W})`}async function fQ(){if(await f("jq"))return!0;return process.stdout.write(`${O}Error: jq is required but not installed.${V}
+var QQ=Object.defineProperty;var ZQ=($)=>$;function zQ($,Q){this[$]=ZQ.bind(null,Q)}var b=($,Q)=>{for(var Z in Q)QQ($,Z,{get:Q[Z],enumerable:!0,configurable:!0,set:zQ.bind(Q,Z)})};var L=($,Q)=>()=>($&&(Q=$($=0)),Q);var q$=import.meta.require;var h1={};b(h1,{lokiDir:()=>P,homeLokiDir:()=>i$,findRepoRootForVersion:()=>t$,REPO_ROOT:()=>g});import{resolve as a,dirname as r$}from"path";import{fileURLToPath as XQ}from"url";import{existsSync as R$}from"fs";import{homedir as KQ}from"os";function qQ(){let $=b1;for(let Q=0;Q<6;Q++){if(R$(a($,"VERSION"))&&R$(a($,"autonomy/run.sh")))return $;let Z=r$($);if(Z===$)break;$=Z}return a(b1,"..","..","..")}function t$($){let Q=$;for(let Z=0;Z<6;Z++){if(R$(a(Q,"VERSION"))&&R$(a(Q,"autonomy/run.sh")))return Q;let z=r$(Q);if(z===Q)break;Q=z}return a($,"..","..","..")}function P(){return process.env.LOKI_DIR??a(process.cwd(),".loki")}function i$(){return a(KQ(),".loki")}var b1,g;var C=L(()=>{b1=r$(XQ(import.meta.url));g=qQ()});import{readFileSync as VQ}from"fs";import{resolve as JQ,dirname as UQ}from"path";import{fileURLToPath as WQ}from"url";function E$(){if(Q$!==null)return Q$;let $="7.80.0";if(typeof $==="string"&&$.length>0)return Q$=$,Q$;try{let Q=UQ(WQ(import.meta.url)),Z=t$(Q);Q$=VQ(JQ(Z,"VERSION"),"utf-8").trim()}catch{Q$="unknown"}return Q$}var Q$=null;var e$=L(()=>{C()});var g1={};b(g1,{runOrThrow:()=>HQ,run:()=>F,readStreamCapped:()=>m1,commandVersion:()=>BQ,commandExists:()=>f,ShellError:()=>$1,MAX_STDOUT_BYTES:()=>v1});async function m1($,Q=v1){let Z=$.getReader(),z=new TextDecoder,X="",q=0;try{while(q<Q){let{done:K,value:U}=await Z.read();if(K)break;if(!U)continue;if(q+=U.byteLength,q>Q){let J=U.byteLength-(q-Q);X+=z.decode(U.subarray(0,J),{stream:!0});break}X+=z.decode(U,{stream:!0})}X+=z.decode()}finally{try{await Z.cancel()}catch{}Z.releaseLock()}return X}async function F($,Q={}){let Z=Bun.spawn({cmd:[...$],stdout:"pipe",stderr:"pipe",env:Q.env?{...process.env,...Q.env}:process.env,cwd:Q.cwd}),z,X;if(Q.timeoutMs&&Q.timeoutMs>0)z=setTimeout(()=>{try{Z.kill("SIGTERM")}catch{}X=setTimeout(()=>{try{Z.kill("SIGKILL")}catch{}},2000)},Q.timeoutMs);try{let[q,K,U]=await Promise.all([m1(Z.stdout),new Response(Z.stderr).text(),Z.exited]);return{stdout:q,stderr:K,exitCode:U}}finally{if(z)clearTimeout(z);if(X)clearTimeout(X)}}async function HQ($,Q={}){let Z=await F($,Q);if(Z.exitCode!==0)throw new $1(`command failed (${Z.exitCode}): ${$.join(" ")}`,Z.exitCode,Z.stdout,Z.stderr);return Z}async function f($){let Q=GQ($),Z=await F(["sh","-c",`command -v ${Q}`],{timeoutMs:5000});if(Z.exitCode===0)return Z.stdout.trim()||null;return null}function GQ($){if(!/^[A-Za-z0-9._/-]+$/.test($))throw Error(`refused to shell-escape suspect token: ${$}`);return $}async function BQ($,Q="--version"){if(!await f($))return null;let z=await F([$,Q],{timeoutMs:5000});if(z.exitCode!==0)return null;return((z.stdout||z.stderr).split(/\r?\n/)[0]?.trim()??"")||null}var v1=16777216,$1;var d=L(()=>{$1=class $1 extends Error{message;exitCode;stdout;stderr;constructor($,Q,Z,z){super($);this.message=$;this.exitCode=Q;this.stdout=Z;this.stderr=z;this.name="ShellError"}}});function s($){return YQ?"":$}var YQ,O,S,_,_Z,I,k,h,V;var c=L(()=>{YQ=(process.env.NO_COLOR??"").length>0;O=s("\x1B[0;31m"),S=s("\x1B[0;32m"),_=s("\x1B[1;33m"),_Z=s("\x1B[0;34m"),I=s("\x1B[0;36m"),k=s("\x1B[1m"),h=s("\x1B[2m"),V=s("\x1B[0m")});import{existsSync as jQ}from"fs";async function Z$(){if(Y$!==void 0)return Y$;let $="/opt/homebrew/bin/python3.12";if(jQ($))return Y$=$,$;let Q=await f("python3.12");if(Q)return Y$=Q,Q;let Z=await f("python3");return Y$=Z,Z}async function z$($,Q={}){let Z=await Z$();if(!Z)return{stdout:"",stderr:"python3 not found",exitCode:127};return F([Z,"-c",$],Q)}var Y$;var V$=L(()=>{d()});var X0={};b(X0,{runStatus:()=>oQ});import{existsSync as y,readFileSync as U$,readdirSync as r1,statSync as t1}from"fs";import{resolve as D,basename as vQ}from"path";import{homedir as mQ}from"os";function i1($){let Q=Math.trunc($);if(Q>=1e6)return`${(Math.trunc(Q/1e6*10)/10).toFixed(1)}M`;if(Q>=1000)return`${(Math.trunc(Q/1000*10)/10).toFixed(1)}K`;return String(Q)}function e1($,Q,Z){if(Q===0)return null;let z=Math.trunc($*100/Q),X=Math.trunc($*N$/Q);if(X>N$)X=N$;let q=N$-X,K=S;if(z>=80)K=O;else if(z>=50)K=_;let U="=".repeat(Math.max(0,X))+" ".repeat(Math.max(0,q)),J=i1($),W=i1(Q);return`  ${k}${Z}${V} ${K}[${U}]${V} ${z}% (${J} / ${W})`}async function fQ(){if(await f("jq"))return!0;return process.stdout.write(`${O}Error: jq is required but not installed.${V}
 `),process.stdout.write(`Install with:
 `),process.stdout.write(`  brew install jq    (macOS)
 `),process.stdout.write(`  apt install jq     (Debian/Ubuntu)
@@ -793,4 +793,4 @@ Set LOKI_LEGACY_BASH=1 to force the bash CLI for every command.
 `),2}default:return process.stderr.write(`Unknown command: ${Q}
 `),process.stderr.write($Q),2}}s1();process.on("SIGINT",()=>process.exit(130));process.on("SIGTERM",()=>process.exit(143));var qZ=await KZ(Bun.argv.slice(2));process.exit(qZ);
 
-//# debugId=753B9888BD0ED74B64756E2164756E21
+//# debugId=5DBFF3AC2E319A5664756E2164756E21

package/lokistore/__init__.py

@@ -0,0 +1,65 @@
+"""
+LokiStore: pluggable, local-first storage abstraction for Loki Mode.
+
+This package is the consolidation spine for durable artifacts (state,
+checkpoints, memory blobs, healing artifacts, etc.). Features should bind to
+this abstraction instead of hardcoding `.loki/` paths or embedding their own
+cloud SDK clients.
+
+Design goals
+------------
+- Local-first by default. With nothing configured, LocalStore writes to the
+  project `.loki/` directory with byte-identical behavior to today's direct
+  file writes (atomic temp+rename, fcntl advisory locking, path-traversal
+  guard). Zero new dependencies, zero behavior change for local users.
+- Optional cloud backends (S3, GCS, Azure Blob) behind lazy imports. The
+  cloud SDK is imported ONLY inside the backend's __init__, so a missing
+  dependency raises a clear, actionable error ONLY when that backend is
+  explicitly selected -- never at import time, never for local users.
+- One interface (put/get/get_to/exists/list/delete) so callers are backend
+  agnostic.
+
+Quick start
+-----------
+    from lokistore import get_store
+
+    store = get_store()  # local by default, honors LOKI_DIR/TARGET_DIR
+    store.put("state/checkpoints/cp-1/metadata.json", b"{...}")
+    data = store.get("state/checkpoints/cp-1/metadata.json")
+    for key in store.list("state/checkpoints/"):
+        ...
+
+Configuration (env or config dict)
+----------------------------------
+- LOKI_STORAGE_BACKEND : local | s3 | gcs | azure-blob   (default: local)
+- LOKI_STORAGE_BUCKET  : bucket / container name          (cloud backends)
+- LOKI_STORAGE_PREFIX  : key prefix within the bucket      (optional)
+- LOKI_STORAGE_REGION  : region                            (s3, optional)
+
+The metadata backend (sqlite default, postgres later) is selected separately;
+see get_metadata_backend() / METADATA notes below. For this release the blob
+backends are the core deliverable and the metadata selector is a thin,
+documented stub that defaults to the existing sqlite path.
+"""
+
+from .base import LokiStore, StoreError, BackendNotAvailableError
+from .local import LocalStore
+from .factory import (
+    get_store,
+    build_store,
+    get_metadata_backend,
+    resolve_local_base,
+)
+
+__all__ = [
+    "LokiStore",
+    "StoreError",
+    "BackendNotAvailableError",
+    "LocalStore",
+    "get_store",
+    "build_store",
+    "get_metadata_backend",
+    "resolve_local_base",
+]
+
+__version__ = "1.0.0"

package/lokistore/base.py

@@ -0,0 +1,172 @@
+"""
+LokiStore interface and shared helpers.
+
+Defines the abstract blob-store contract that every backend implements, plus
+errors and a key-normalization helper shared across backends.
+"""
+
+from __future__ import annotations
+
+import os
+from abc import ABC, abstractmethod
+from typing import List, Union
+
+
+class StoreError(Exception):
+    """Base class for LokiStore errors."""
+
+
+class BackendNotAvailableError(StoreError):
+    """
+    Raised when a cloud backend is explicitly selected but its SDK (or
+    required configuration) is not available. The message names the missing
+    package and how to install it so the failure is actionable.
+    """
+
+
+def normalize_key(key: str) -> str:
+    """
+    Normalize a store key to a clean POSIX-style relative path.
+
+    Keys are relative paths like "state/checkpoints/cp-1/metadata.json".
+    This rejects absolute paths and any key that would traverse outside the
+    store root (a leading or embedded ".." segment). The same guard is used
+    by every backend so traversal is rejected uniformly, whether the bytes
+    land on a local filesystem or in an object-store key namespace.
+
+    Args:
+        key: A POSIX-style relative path.
+
+    Returns:
+        The normalized key (forward slashes, no leading slash, no "."/".."
+        segments collapsed away).
+
+    Raises:
+        ValueError: If the key is empty, absolute, or escapes the root.
+    """
+    if not isinstance(key, str) or not key:
+        raise ValueError("store key must be a non-empty string")
+
+    # Treat backslashes as separators too, so a Windows-style key cannot
+    # smuggle a traversal past the split() check below.
+    candidate = key.replace("\\", "/")
+
+    if candidate.startswith("/"):
+        raise ValueError(f"absolute keys are not allowed: {key!r}")
+
+    parts: List[str] = []
+    for segment in candidate.split("/"):
+        if segment == "" or segment == ".":
+            # Collapse empty (e.g. "a//b") and current-dir segments.
+            continue
+        if segment == "..":
+            raise ValueError(f"path traversal is not allowed in key: {key!r}")
+        parts.append(segment)
+
+    if not parts:
+        raise ValueError(f"key resolves to an empty path: {key!r}")
+
+    return "/".join(parts)
+
+
+def read_source_bytes(data: Union[bytes, bytearray, str, os.PathLike]) -> bytes:
+    """
+    Coerce a put() source argument into bytes.
+
+    Accepts raw bytes (returned as-is) or a path-like pointing at a file whose
+    contents are read in binary. A plain str is treated as a FILESYSTEM PATH,
+    not as text, to match the put(key, bytes_or_path) contract; callers that
+    want to store a string must encode it themselves.
+
+    Args:
+        data: bytes/bytearray, or a path-like to an existing file.
+
+    Returns:
+        The bytes to store.
+
+    Raises:
+        FileNotFoundError: If a path is given and the file does not exist.
+        TypeError: If the argument is neither bytes nor a path-like.
+    """
+    if isinstance(data, (bytes, bytearray)):
+        return bytes(data)
+    if isinstance(data, (str, os.PathLike)):
+        with open(data, "rb") as f:
+            return f.read()
+    raise TypeError(
+        "put() source must be bytes or a path-like to a file, "
+        f"got {type(data).__name__}"
+    )
+
+
+class LokiStore(ABC):
+    """
+    Abstract pluggable blob store.
+
+    All keys are POSIX-style relative paths (see normalize_key). Implementations
+    must apply normalize_key to every incoming key so traversal is rejected and
+    behavior is uniform across backends.
+
+    The contract is intentionally small (no streaming, no multipart, no
+    credential framework) so backends stay thin. Larger payload handling can be
+    layered on later without changing this interface.
+    """
+
+    @abstractmethod
+    def put(self, key: str, data: Union[bytes, bytearray, str, os.PathLike]) -> None:
+        """
+        Store bytes under key. The source is either raw bytes or a path-like
+        to a file whose contents are stored. Overwrites any existing value
+        atomically where the backend supports it.
+        """
+
+    @abstractmethod
+    def get(self, key: str) -> bytes:
+        """
+        Return the bytes stored under key.
+
+        Raises:
+            FileNotFoundError: If the key does not exist.
+        """
+
+    @abstractmethod
+    def get_to(self, key: str, dest_path: Union[str, os.PathLike]) -> None:
+        """
+        Write the bytes stored under key to dest_path (a local filesystem
+        path). Parent directories are created as needed.
+
+        Raises:
+            FileNotFoundError: If the key does not exist.
+        """
+
+    @abstractmethod
+    def exists(self, key: str) -> bool:
+        """Return True if key exists in the store."""
+
+    @abstractmethod
+    def list(self, prefix: str = "") -> List[str]:
+        """
+        List keys under prefix (a POSIX-style relative PATH prefix). An empty
+        prefix lists every key. Returns normalized keys, sorted, relative to
+        the store root.
+
+        Prefix semantics (portable contract):
+        - prefix is a PATH prefix matched at slash boundaries, NOT a raw
+          substring. A slash-terminated prefix like "state/" selects every key
+          beneath the "state" directory and is the portable form that behaves
+          IDENTICALLY across all backends (local and cloud).
+        - An empty prefix lists everything.
+
+        A non-slash-terminated prefix (e.g. "state") is normalized to its
+        directory form before matching, so it selects keys under "state/" and
+        does NOT match siblings that merely share the leading characters (e.g.
+        "stateful/x.json"). Callers wanting portable results should pass a
+        slash-terminated prefix.
+        """
+
+    @abstractmethod
+    def delete(self, key: str) -> bool:
+        """
+        Delete key. Returns True if a value was removed, False if the key did
+        not exist (delete is idempotent and never raises on a missing key).
+        """

package/lokistore/cloud.py

@@ -0,0 +1,305 @@
+"""
+Optional cloud LokiStore backends: S3, GCS, Azure Blob.
+
+Each backend's SDK is imported ONLY inside its __init__, so:
+- The SDK is never imported at module import time.
+- Local-only users never touch these classes and never pay an import cost.
+- Selecting a cloud backend without its SDK installed raises a clear,
+  actionable BackendNotAvailableError naming the missing package.
+
+Backends are intentionally thin. They do not add retry/credential frameworks;
+they rely on each SDK's default credential chain (env vars, instance metadata,
+etc.). Keys are normalized identically to LocalStore (traversal rejected) and
+an optional store-level prefix is prepended to every object key.
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import List, Optional, Union
+
+from .base import (
+    BackendNotAvailableError,
+    LokiStore,
+    normalize_key,
+    read_source_bytes,
+)
+
+
+def _join_prefix(prefix: str, key: str) -> str:
+    """Join a normalized store prefix and a normalized key into an object key."""
+    key = normalize_key(key)
+    if not prefix:
+        return key
+    return f"{prefix.rstrip('/')}/{key}"
+
+
+def _normalize_prefix(prefix: Optional[str]) -> str:
+    """Normalize an optional store prefix to a clean POSIX-style path (or '')."""
+    if not prefix:
+        return ""
+    # Reuse the key guard so a prefix cannot smuggle traversal either.
+    return normalize_key(prefix)
+
+
+def _dir_prefix(obj_prefix: str) -> str:
+    """
+    Coerce a non-empty object-key prefix to its directory form (slash
+    terminated) so cloud list() matches at slash boundaries like LocalStore's
+    directory walk, per the LokiStore.list contract. An empty prefix (list
+    everything) is returned unchanged.
+    """
+    if obj_prefix and not obj_prefix.endswith("/"):
+        return obj_prefix + "/"
+    return obj_prefix
+
+
+class S3Store(LokiStore):
+    """Amazon S3 (or S3-compatible) backend (requires boto3)."""
+
+    def __init__(
+        self,
+        bucket: str,
+        prefix: Optional[str] = None,
+        region: Optional[str] = None,
+    ):
+        if not bucket:
+            raise ValueError("S3Store requires a bucket name")
+        try:
+            import boto3  # noqa: F401  (imported here so missing dep is lazy)
+        except ImportError as exc:
+            raise BackendNotAvailableError(
+                "The s3 storage backend requires the 'boto3' package. "
+                "Install it with: pip install boto3"
+            ) from exc
+
+        self._bucket = bucket
+        self._prefix = _normalize_prefix(prefix)
+        # boto3 picks up credentials from its default chain (env, shared
+        # config, instance/role metadata). region_name is optional.
+        kwargs = {"region_name": region} if region else {}
+        self._client = boto3.client("s3", **kwargs)
+
+    def _object_key(self, key: str) -> str:
+        return _join_prefix(self._prefix, key)
+
+    def put(self, key: str, data: Union[bytes, bytearray, str, os.PathLike]) -> None:
+        payload = read_source_bytes(data)
+        self._client.put_object(
+            Bucket=self._bucket, Key=self._object_key(key), Body=payload
+        )
+
+    def get(self, key: str) -> bytes:
+        try:
+            resp = self._client.get_object(
+                Bucket=self._bucket, Key=self._object_key(key)
+            )
+        except self._client.exceptions.NoSuchKey as exc:
+            raise FileNotFoundError(f"no such key: {key!r}") from exc
+        return resp["Body"].read()
+
+    def get_to(self, key: str, dest_path: Union[str, os.PathLike]) -> None:
+        dest = Path(dest_path).expanduser()
+        dest.parent.mkdir(parents=True, exist_ok=True)
+        self._client.download_file(self._bucket, self._object_key(key), str(dest))
+
+    def exists(self, key: str) -> bool:
+        try:
+            self._client.head_object(Bucket=self._bucket, Key=self._object_key(key))
+            return True
+        except Exception:
+            # head_object raises ClientError (404) when absent; treat any
+            # lookup failure as "not present" for the boolean contract.
+            return False
+
+    def list(self, prefix: str = "") -> List[str]:
+        # A caller prefix is matched at slash boundaries (directory form); the
+        # store-level prefix, when listing everything, is left as-is.
+        obj_prefix = _dir_prefix(self._object_key(prefix)) if prefix else self._prefix
+        paginator = self._client.get_paginator("list_objects_v2")
+        strip = (self._prefix + "/") if self._prefix else ""
+        keys: List[str] = []
+        for page in paginator.paginate(Bucket=self._bucket, Prefix=obj_prefix):
+            for item in page.get("Contents", []):
+                full = item["Key"]
+                rel = full[len(strip):] if strip and full.startswith(strip) else full
+                keys.append(rel)
+        keys.sort()
+        return keys
+
+    def delete(self, key: str) -> bool:
+        # S3 delete is idempotent and does not signal whether an object
+        # existed. Probe first so the boolean contract is honest.
+        existed = self.exists(key)
+        self._client.delete_object(Bucket=self._bucket, Key=self._object_key(key))
+        return existed
+
+
+class GCSStore(LokiStore):
+    """Google Cloud Storage backend (requires google-cloud-storage)."""
+
+    def __init__(
+        self,
+        bucket: str,
+        prefix: Optional[str] = None,
+        region: Optional[str] = None,  # accepted for signature parity, unused
+    ):
+        if not bucket:
+            raise ValueError("GCSStore requires a bucket name")
+        try:
+            from google.cloud import storage  # type: ignore
+        except ImportError as exc:
+            raise BackendNotAvailableError(
+                "The gcs storage backend requires the 'google-cloud-storage' "
+                "package. Install it with: pip install google-cloud-storage"
+            ) from exc
+
+        self._prefix = _normalize_prefix(prefix)
+        # The client uses Application Default Credentials (env, gcloud, or
+        # workload identity).
+        self._client = storage.Client()
+        self._bucket = self._client.bucket(bucket)
+
+    def _object_key(self, key: str) -> str:
+        return _join_prefix(self._prefix, key)
+
+    def put(self, key: str, data: Union[bytes, bytearray, str, os.PathLike]) -> None:
+        payload = read_source_bytes(data)
+        blob = self._bucket.blob(self._object_key(key))
+        blob.upload_from_string(payload)
+
+    def get(self, key: str) -> bytes:
+        blob = self._bucket.blob(self._object_key(key))
+        if not blob.exists():
+            raise FileNotFoundError(f"no such key: {key!r}")
+        return blob.download_as_bytes()
+
+    def get_to(self, key: str, dest_path: Union[str, os.PathLike]) -> None:
+        dest = Path(dest_path).expanduser()
+        dest.parent.mkdir(parents=True, exist_ok=True)
+        blob = self._bucket.blob(self._object_key(key))
+        if not blob.exists():
+            raise FileNotFoundError(f"no such key: {key!r}")
+        blob.download_to_filename(str(dest))
+
+    def exists(self, key: str) -> bool:
+        return self._bucket.blob(self._object_key(key)).exists()
+
+    def list(self, prefix: str = "") -> List[str]:
+        obj_prefix = _dir_prefix(self._object_key(prefix)) if prefix else self._prefix
+        strip = (self._prefix + "/") if self._prefix else ""
+        keys: List[str] = []
+        for blob in self._client.list_blobs(self._bucket, prefix=obj_prefix):
+            full = blob.name
+            rel = full[len(strip):] if strip and full.startswith(strip) else full
+            keys.append(rel)
+        keys.sort()
+        return keys
+
+    def delete(self, key: str) -> bool:
+        blob = self._bucket.blob(self._object_key(key))
+        if not blob.exists():
+            return False
+        blob.delete()
+        return True
+
+
+class AzureBlobStore(LokiStore):
+    """Azure Blob Storage backend (requires azure-storage-blob)."""
+
+    def __init__(
+        self,
+        bucket: str,
+        prefix: Optional[str] = None,
+        region: Optional[str] = None,  # accepted for signature parity, unused
+    ):
+        # In Azure terms `bucket` is the container name.
+        if not bucket:
+            raise ValueError("AzureBlobStore requires a container name (bucket)")
+        try:
+            from azure.storage.blob import ContainerClient  # type: ignore
+        except ImportError as exc:
+            raise BackendNotAvailableError(
+                "The azure-blob storage backend requires the "
+                "'azure-storage-blob' package. "
+                "Install it with: pip install azure-storage-blob"
+            ) from exc
+
+        self._prefix = _normalize_prefix(prefix)
+
+        # Credentials come from the SDK's default chain. We accept either a
+        # full connection string (AZURE_STORAGE_CONNECTION_STRING) or an
+        # account URL (AZURE_STORAGE_ACCOUNT_URL) + DefaultAzureCredential.
+        conn = os.environ.get("AZURE_STORAGE_CONNECTION_STRING")
+        account_url = os.environ.get("AZURE_STORAGE_ACCOUNT_URL")
+        if conn:
+            self._container = ContainerClient.from_connection_string(
+                conn, container_name=bucket
+            )
+        elif account_url:
+            try:
+                from azure.identity import DefaultAzureCredential  # type: ignore
+            except ImportError as exc:
+                raise BackendNotAvailableError(
+                    "Azure account-URL auth requires the 'azure-identity' "
+                    "package. Install it with: pip install azure-identity"
+                ) from exc
+            self._container = ContainerClient(
+                account_url=account_url,
+                container_name=bucket,
+                credential=DefaultAzureCredential(),
+            )
+        else:
+            raise BackendNotAvailableError(
+                "The azure-blob backend needs AZURE_STORAGE_CONNECTION_STRING "
+                "or AZURE_STORAGE_ACCOUNT_URL to be set."
+            )
+
+    def _object_key(self, key: str) -> str:
+        return _join_prefix(self._prefix, key)
+
+    def put(self, key: str, data: Union[bytes, bytearray, str, os.PathLike]) -> None:
+        payload = read_source_bytes(data)
+        self._container.upload_blob(
+            name=self._object_key(key), data=payload, overwrite=True
+        )
+
+    def get(self, key: str) -> bytes:
+        from azure.core.exceptions import ResourceNotFoundError  # type: ignore
+
+        try:
+            downloader = self._container.download_blob(self._object_key(key))
+        except ResourceNotFoundError as exc:
+            raise FileNotFoundError(f"no such key: {key!r}") from exc
+        return downloader.readall()
+
+    def get_to(self, key: str, dest_path: Union[str, os.PathLike]) -> None:
+        payload = self.get(key)
+        dest = Path(dest_path).expanduser()
+        dest.parent.mkdir(parents=True, exist_ok=True)
+        with open(dest, "wb") as f:
+            f.write(payload)
+
+    def exists(self, key: str) -> bool:
+        return self._container.get_blob_client(self._object_key(key)).exists()
+
+    def list(self, prefix: str = "") -> List[str]:
+        obj_prefix = _dir_prefix(self._object_key(prefix)) if prefix else self._prefix
+        strip = (self._prefix + "/") if self._prefix else ""
+        keys: List[str] = []
+        for blob in self._container.list_blobs(name_starts_with=obj_prefix or None):
+            full = blob.name
+            rel = full[len(strip):] if strip and full.startswith(strip) else full
+            keys.append(rel)
+        keys.sort()
+        return keys
+
+    def delete(self, key: str) -> bool:
+        from azure.core.exceptions import ResourceNotFoundError  # type: ignore
+
+        try:
+            self._container.delete_blob(self._object_key(key))
+            return True
+        except ResourceNotFoundError:
+            return False