pal-code 0.1.0__py3-none-any.whl

pal/sdk/pipeline.py

@@ -0,0 +1,240 @@
+"""
+AIOS SDK (AIOS section 3.9): what an agent developer actually imports
+and uses. Wraps every kernel manager behind one small, agent-facing
+interface -- chat(), remember()/recall(), read()/write()/delete(),
+call_tool(), search_knowledge(), request_access() -- so building an
+agent means calling straightforward methods, not assembling
+LLMSyscalls, StorageSyscalls, and ToolCallRequests by hand. Every
+method here is a thin pass-through to the corresponding manager; the
+abstraction IS not having to know those managers exist, matching "this
+SDK... abstracts complex system calls, allowing developers to focus on
+the agent's internal workflows."
+
+One AgentSDK instance is scoped to exactly one agent_id -- every
+storage/memory/tool call it makes is attributed to that agent, and
+every access-manager check runs as that agent. OrchestratorPipeline.
+sdk_for() is the usual way to get one, wired to the orchestrator's
+shared managers.
+"""
+import time
+from pathlib import Path
+from types import SimpleNamespace
+from typing import Any, Optional
+
+from pal.access_manager.components.base import AccessDecision, OperationType
+from pal.access_manager.pipeline import AccessManagerPipeline
+from pal.errors import PalError, UserInputError
+from pal.llm_wrapper.components.base import LLMResponse, LLMSyscall, LLMWrapper
+from pal.llm_wrapper.pipeline import LLMWrapperPipeline
+from pal.memory.pipeline import MemoryPipeline
+from pal.os_kernel import OSKernel
+from pal.sdk.os_api import OSAPI
+from pal.sdk.queries import (
+    OS_KERNEL,
+    PAL_KERNEL,
+    LLMQuery,
+    MemoryQuery,
+    OSQuery,
+    Query,
+    Response,
+    StorageQuery,
+    ToolQuery,
+)
+from pal.sdk.savers import CallSavers
+from pal.storage_manager.pipeline import StorageManagerPipeline
+from pal.storage_manager.utils.sdk import StorageSDK
+from pal.tool_manager.pipeline import ToolManagerPipeline
+
+
+class AgentSDK:
+    def __init__(
+        self,
+        agent_id: str,
+        llm_wrapper: Optional[LLMWrapperPipeline],
+        storage_manager: StorageManagerPipeline,
+        tool_manager: ToolManagerPipeline,
+        access_manager: AccessManagerPipeline,
+        memory: Optional[MemoryPipeline] = None,
+        syscall_scheduler=None,
+        savers: Optional[CallSavers] = None,
+        os_kernel: Optional[OSKernel] = None,
+    ):
+        self.agent_id = agent_id
+        self.savers = savers
+        self._os_kernel = os_kernel
+        self.os = OSAPI(self)
+        self._llm_wrapper = llm_wrapper
+        self._syscall_scheduler = syscall_scheduler
+        self._storage = StorageSDK(agent_id, storage_manager)
+        self._tool_manager = tool_manager
+        self._access_manager = access_manager
+        self.memory = memory or MemoryPipeline(agent_id=agent_id, storage_manager=storage_manager)
+
+    @classmethod
+    def standalone(cls, core, agent_id: str = "agent", root: Optional[str] = None,
+                   savers: Optional[CallSavers] = None, os_kernel: Optional[OSKernel] = None) -> "AgentSDK":
+        """A ready-to-use SDK with no orchestrator: one call to start using Pal from your own agent code.
+        `core` is an LLMWrapper or a WrapperConfig. Storage lives under `root` (default ~/.pal/sdk). Built-in tools
+        (calculator, time, word count) are registered. Light savers (tidy) are on; the exact-repeat cache is off."""
+        from pal.llm_wrapper.components.base import WrapperConfig
+        from pal.llm_wrapper.utils.registry import build_wrapper
+        from pal.paths import data_dir
+        from pal.sdk.components.tool_catalog import register_builtin_tools
+
+        active = build_wrapper(core) if isinstance(core, WrapperConfig) else core
+        base = root or data_dir("sdk")
+        storage = StorageManagerPipeline(root=str(base))
+        tools = ToolManagerPipeline()
+        register_builtin_tools(tools)
+        access = AccessManagerPipeline()
+        kernel = os_kernel or OSKernel(access=access, root=Path(base) / "workspaces")
+        return cls(agent_id, SimpleNamespace(core=active), storage, tools, access,  # type: ignore[arg-type]
+                   savers=savers if savers is not None else CallSavers(), os_kernel=kernel)
+
+    @property
+    def stats(self) -> dict:
+        """Calls, cache hits, tidied characters, provider-reported tokens and time spent in model calls."""
+        s = self.savers.stats if self.savers else None
+        return {k: getattr(s, k) for k in ("calls", "cache_hits", "chars_tidied", "prompt_tokens",
+                                           "completion_tokens", "seconds")} if s else {}
+
+    # -- chat / inference -------------------------------------------------------
+
+    def chat_response(self, messages: list[dict], core: Optional[LLMWrapper] = None, **kwargs) -> LLMResponse:
+        """Runs one LLM inference call and returns the full response (text plus token counts).
+        Under the hood this is an LLM syscall -- through the shared centralized SyscallScheduler when
+        one was supplied (AIOS 3.3), or directly against the core otherwise. `core` overrides the
+        SDK's own core for this call (e.g. a per-request API model chosen in the UI)."""
+        active = core or (self._llm_wrapper.core if self._llm_wrapper is not None else None)
+        if active is None:
+            raise RuntimeError("no LLM core: pass core= or construct the SDK with llm_wrapper")
+        sv = self.savers
+        key = None
+        if sv is not None:
+            messages = sv.prepare(messages)
+            key = sv.key(getattr(getattr(active, "config", None), "model", ""), messages, kwargs)
+            cached = sv.get(key)
+            if cached is not None:
+                sv.stats.calls += 1
+                return cached
+        started = time.perf_counter()
+        resp = self._infer(active, messages, kwargs)
+        if sv is not None:
+            sv.stats.calls += 1
+            sv.stats.prompt_tokens += resp.prompt_tokens or 0
+            sv.stats.completion_tokens += resp.completion_tokens or 0
+            sv.stats.seconds += time.perf_counter() - started
+            sv.put(key or "", resp)
+        return resp
+
+    def _infer(self, active: LLMWrapper, messages: list[dict], kwargs: dict) -> LLMResponse:
+        syscall = LLMSyscall(messages=messages, **kwargs)
+        if self._syscall_scheduler is not None:
+            request_id = self._syscall_scheduler.submit(self.agent_id, active, syscall)
+            req = self._syscall_scheduler.get_result(request_id)
+            while req.status.value in ("queued", "running"):
+                self._syscall_scheduler.tick()
+                req = self._syscall_scheduler.get_result(request_id)
+            if req.status.value == "error":
+                raise RuntimeError(f"chat failed: {req.error}")
+            return req.result
+        return active.chat(syscall)
+
+    def chat(self, messages: list[dict], core: Optional[LLMWrapper] = None, **kwargs) -> str:
+        """Like chat_response(), returning only the reply text."""
+        return self.chat_response(messages, core=core, **kwargs).text
+
+    # -- query routing: LLM queries to the Pal kernel, non-LLM queries to the OS kernel ----------------------
+    def send_request(self, query: Query) -> Response:
+        """The one place that decides where a query goes, by its class alone:
+        LLMQuery to the Pal kernel (model), Memory/Storage/Tool queries to the Pal kernel's managers, OSQuery to the
+        OS kernel (Ubuntu: files, network, system facts). A refusal or failure comes back as Response(ok=False)."""
+        cls = getattr(query, "query_class", "")
+        dest = OS_KERNEL if cls == "os" else PAL_KERNEL
+        try:
+            if isinstance(query, LLMQuery):
+                kw = {k: v for k, v in (("max_tokens", query.max_tokens), ("temperature", query.temperature)) if v is not None}
+                return Response(True, self.chat_response(query.messages, **kw), handled_by=dest)
+            if isinstance(query, MemoryQuery):
+                data = self.remember(**query.params) if query.op == "remember" else self.recall(**query.params)
+                return Response(True, data, handled_by=dest)
+            if isinstance(query, StorageQuery):
+                return Response(True, self._storage_op(query), handled_by=dest)
+            if isinstance(query, ToolQuery):
+                return Response(True, self.call_tool(query.tool, **query.args), handled_by=dest)
+            if isinstance(query, OSQuery):
+                if self._os_kernel is None:
+                    raise UserInputError("this SDK has no OS kernel interface")
+                return Response(True, self._os_kernel.handle(self.agent_id, query.op, query.params), handled_by=dest)
+        except (PalError, RuntimeError, ValueError, TypeError, KeyError) as e:
+            return Response(False, error=str(e), handled_by=dest)
+        raise UserInputError(f"unknown query class {cls!r}")
+
+    def _storage_op(self, q: StorageQuery) -> Any:
+        ops = {"read": self.read, "write": self.write, "delete": self.delete, "list": self.list_keys,
+               "add_knowledge": self.add_knowledge, "search_knowledge": self.search_knowledge}
+        if q.op not in ops:
+            raise UserInputError(f"unknown storage operation {q.op!r}")
+        return ops[q.op](**q.params)
+
+    # -- memory (AIOS 3.5) --------------------------------------------------------
+
+    def remember(self, content: str, tags: Optional[list[str]] = None, session_id: Optional[str] = None):
+        return self.memory.add(content, session_id=session_id or self.agent_id, tags=tags)
+
+    def recall(self, query: str, top_k: int = 3):
+        return self.memory.retrieve(query, top_k=top_k)
+
+    # -- storage: own data (AIOS 3.6) ---------------------------------------------
+
+    def read(self, key: str) -> Optional[Any]:
+        return self._storage.read(key)
+
+    def write(self, key: str, data: Any) -> None:
+        self._storage.write(key, data)
+
+    def delete(self, key: str) -> None:
+        self._storage.delete(key)
+
+    def list_keys(self, prefix: str = "") -> list[str]:
+        return self._storage.list_keys(prefix=prefix)
+
+    def add_knowledge(self, doc_id: str, text: str, metadata: Optional[dict] = None) -> None:
+        self._storage.vector_upsert(doc_id, text, metadata=metadata)
+
+    def search_knowledge(self, query: str, top_k: int = 3) -> list[dict]:
+        return self._storage.vector_query(query, top_k=top_k)
+
+    # -- storage: another agent's data, subject to the Access Manager (3.8) ------
+
+    def read_from(self, target_agent_id: str, key: str) -> Optional[Any]:
+        return self._storage.read_from(target_agent_id, key)
+
+    def write_to(self, target_agent_id: str, key: str, data: Any) -> None:
+        self._storage.write_to(target_agent_id, key, data)
+
+    def delete_from(self, target_agent_id: str, key: str) -> None:
+        self._storage.delete_from(target_agent_id, key)
+
+    def request_access(self, target_agent_id: str, operation: OperationType, resource: str = "") -> AccessDecision:
+        """Checks (without performing) whether this agent would be
+        allowed to touch target_agent_id's resource -- useful for an
+        agent to decide whether to even attempt a cross-agent call
+        before issuing it."""
+        return self._access_manager.check_access(self.agent_id, target_agent_id, operation, resource=resource)
+
+    # -- tools (AIOS 3.7) -----------------------------------------------------------
+
+    def call_tool(self, tool_name: str, **kwargs) -> Any:
+        result = self._tool_manager.invoke(self.agent_id, tool_name, kwargs)
+        if not result.ok:
+            raise RuntimeError(f"tool '{tool_name}' failed: {result.error}")
+        return result.result
+
+    def list_tools(self) -> list[str]:
+        return self._tool_manager.list_tools()
+
+    def close(self) -> None:
+        """Delete this agent's stored files and vectors (a chat session ended). Memory notes are
+        kept: they are the cross-session part."""
+        self._storage.storage_manager.purge_agent(self.agent_id)

pal/sdk/queries.py

@@ -0,0 +1,68 @@
+"""Typed queries an agent sends through the SDK, and where each kind goes.
+
+    LLMQuery                            -> Pal kernel   (model work: reasoning, planning, tool parsing, code)
+    MemoryQuery, StorageQuery, ToolQuery -> Pal kernel   (its memory, storage and tool managers)
+    OSQuery                             -> OS kernel       (file operations, network requests, system facts)
+
+An OSQuery never reaches a model and an LLMQuery never touches the filesystem or the network: the router in
+`AgentSDK.send_request` is the only place that decides, and it decides by query class alone.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, ClassVar
+
+PAL_KERNEL = "pal_kernel"
+OS_KERNEL = "os_kernel"
+
+
+@dataclass
+class Query:
+    query_class: ClassVar[str] = ""
+
+
+@dataclass
+class LLMQuery(Query):
+    query_class: ClassVar[str] = "llm"
+    messages: list[dict] = field(default_factory=list)
+    max_tokens: int | None = None
+    temperature: float | None = None
+
+
+@dataclass
+class MemoryQuery(Query):
+    """op: remember | recall"""
+    query_class: ClassVar[str] = "memory"
+    op: str = "recall"
+    params: dict = field(default_factory=dict)
+
+
+@dataclass
+class StorageQuery(Query):
+    """op: read | write | delete | list | add_knowledge | search_knowledge"""
+    query_class: ClassVar[str] = "storage"
+    op: str = "read"
+    params: dict = field(default_factory=dict)
+
+
+@dataclass
+class ToolQuery(Query):
+    query_class: ClassVar[str] = "tool"
+    tool: str = ""
+    args: dict = field(default_factory=dict)
+
+
+@dataclass
+class OSQuery(Query):
+    """op: file_read | file_write | file_list | file_delete | net_get | net_post | sys_info | keyboard | mouse"""
+    query_class: ClassVar[str] = "os"
+    op: str = "sys_info"
+    params: dict = field(default_factory=dict)
+
+
+@dataclass
+class Response:
+    ok: bool
+    data: Any = None
+    error: str = ""
+    handled_by: str = ""      # PAL_KERNEL or OS_KERNEL

pal/sdk/savers.py

@@ -0,0 +1,88 @@
+"""Light token savers for calls that come from agents Pal does not control (adapted frameworks).
+
+The full token-saving pipeline (input trimming by a local model, document and code-graph retrieval, paged history,
+output rules) belongs to the chat turn, where Pal owns the prompt. A framework such as AutoGen owns its own
+prompts, so here only safe, deterministic steps run:
+  * tidy: trailing spaces and runs of blank lines are removed outside code blocks (code is never touched);
+  * optional exact-repeat cache: an identical request inside the TTL is answered with no model call. Off by default,
+    because agent loops sometimes retry on purpose and expect a different answer.
+"""
+from __future__ import annotations
+
+import hashlib
+import json
+import re
+import threading
+import time
+from collections import OrderedDict
+from dataclasses import dataclass, replace
+
+from pal.llm_wrapper.components.base import LLMResponse
+
+_TRAILING = re.compile(r"[ \t]+(?=\n)")
+_BLANKS = re.compile(r"\n{3,}")
+
+
+def tidy(text: str) -> str:
+    parts = text.split("```")
+    for i in range(0, len(parts), 2):            # even parts are outside fenced code
+        parts[i] = _BLANKS.sub("\n\n", _TRAILING.sub("", parts[i]))
+    return "```".join(parts)
+
+
+@dataclass
+class CallStats:
+    calls: int = 0
+    cache_hits: int = 0
+    chars_tidied: int = 0
+    prompt_tokens: int = 0
+    completion_tokens: int = 0
+    seconds: float = 0.0
+
+
+class CallSavers:
+    def __init__(self, tidy_messages: bool = True, cache: bool = False, cache_size: int = 64, cache_ttl: float = 300.0):
+        self.tidy_messages = tidy_messages
+        self.cache = cache
+        self.cache_size = cache_size
+        self.cache_ttl = cache_ttl
+        self.stats = CallStats()
+        self._lock = threading.Lock()
+        self._store: OrderedDict[str, tuple[float, LLMResponse]] = OrderedDict()
+
+    def prepare(self, messages: list[dict]) -> list[dict]:
+        if not self.tidy_messages:
+            return messages
+        out = []
+        for m in messages:
+            c = m.get("content")
+            if isinstance(c, str):
+                t = tidy(c)
+                self.stats.chars_tidied += len(c) - len(t)
+                m = {**m, "content": t}
+            out.append(m)
+        return out
+
+    def key(self, model: str, messages: list[dict], kwargs: dict) -> str:
+        blob = json.dumps([model, messages, sorted(kwargs.items())], sort_keys=True, default=str)
+        return hashlib.sha256(blob.encode("utf-8")).hexdigest()
+
+    def get(self, key: str) -> LLMResponse | None:
+        if not self.cache:
+            return None
+        with self._lock:
+            hit = self._store.get(key)
+            if hit is None or time.monotonic() - hit[0] > self.cache_ttl:
+                self._store.pop(key, None)
+                return None
+            self._store.move_to_end(key)
+            self.stats.cache_hits += 1
+            return replace(hit[1], prompt_tokens=0, completion_tokens=0, meta={**hit[1].meta, "cache": True})
+
+    def put(self, key: str, resp: LLMResponse) -> None:
+        if not self.cache:
+            return
+        with self._lock:
+            self._store[key] = (time.monotonic(), resp)
+            while len(self._store) > self.cache_size:
+                self._store.popitem(last=False)

pal/sdk/utils/__init__.py

@@ -0,0 +1,2 @@
+"""No shared utilities yet for sdk -- reserved for future helpers (e.g.
+config-file-driven agent bootstrapping)."""

pal/storage_manager/__init__.py

@@ -0,0 +1,17 @@
+from pal.storage_manager.components.base import StorageOp, StorageResponse, StorageSyscall
+from pal.storage_manager.components.local_file_backend import LocalFileBackend
+from pal.storage_manager.components.vector_store_backend import VectorStoreBackend
+from pal.storage_manager.pipeline import StorageManagerPipeline
+from pal.storage_manager.utils.memory_adapter import AgentScopedMemoryStorage
+from pal.storage_manager.utils.sdk import StorageSDK
+
+__all__ = [
+    "StorageManagerPipeline",
+    "StorageOp",
+    "StorageResponse",
+    "StorageSyscall",
+    "LocalFileBackend",
+    "VectorStoreBackend",
+    "StorageSDK",
+    "AgentScopedMemoryStorage",
+]

pal/storage_manager/components/__init__.py

@@ -0,0 +1,19 @@
+from pal.storage_manager.components.base import StorageOp, StorageResponse, StorageSyscall
+from pal.storage_manager.components.local_file_backend import LocalFileBackend
+from pal.storage_manager.components.storage_queue import (
+    StorageRequest,
+    StorageSyscallQueue,
+    StorageSyscallStatus,
+)
+from pal.storage_manager.components.vector_store_backend import VectorStoreBackend
+
+__all__ = [
+    "StorageOp",
+    "StorageResponse",
+    "StorageSyscall",
+    "LocalFileBackend",
+    "StorageRequest",
+    "StorageSyscallQueue",
+    "StorageSyscallStatus",
+    "VectorStoreBackend",
+]

pal/storage_manager/components/base.py

@@ -0,0 +1,50 @@
+"""
+Unified system-call layer for storage. Agents (via the SDK,
+utils/sdk.py) and other modules (the memory manager, when it swaps
+data to disk) never talk to a backend directly -- they issue a
+StorageSyscall and get a StorageResponse back, same "syscall, not a
+direct backend call" shape as llm_wrapper' LLMSyscall/LLMResponse.
+"""
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any, Optional
+
+
+class StorageOp(str, Enum):
+    READ = "read"
+    WRITE = "write"
+    DELETE = "delete"
+    LIST = "list"
+    VECTOR_UPSERT = "vector_upsert"
+    VECTOR_QUERY = "vector_query"
+
+
+@dataclass
+class StorageSyscall:
+    """One storage request, always scoped to the agent that owns the
+    data -- "the storage manager reads and writes data based on the
+    agent ID passed from the memory manager" applies just as much to an
+    agent's own direct SDK calls, so agent_id is required on every op,
+    not just memory-manager swaps."""
+
+    agent_id: str               # whose resource this operates on (the "owner"/target)
+    op: StorageOp
+    key: Optional[str] = None          # file ops: the key/filename; LIST: prefix filter
+    data: Any = None                   # WRITE: value to store; VECTOR_UPSERT: document text
+    query_text: Optional[str] = None   # VECTOR_QUERY
+    top_k: int = 3                     # VECTOR_QUERY
+    metadata: dict = field(default_factory=dict)  # VECTOR_UPSERT
+    # Who is actually making this call -- distinct from agent_id when an
+    # agent reads/writes ANOTHER agent's resource. None means "the owner
+    # is calling on its own behalf", the common case, which needs no
+    # access-manager cross-agent check (AIOS 3.8). Only meaningful when
+    # a StorageManagerPipeline has an access_manager wired in; ignored
+    # otherwise.
+    requesting_agent_id: Optional[str] = None
+
+
+@dataclass
+class StorageResponse:
+    ok: bool
+    data: Any = None
+    error: Optional[str] = None

pal/storage_manager/components/local_file_backend.py

@@ -0,0 +1,84 @@
+"""
+Local-file storage backend, with one root subdirectory PER AGENT so different agents' files never
+collide. Values are stored as JSON when JSON-serializable and as raw bytes otherwise.
+
+Portable and safe on Linux, macOS and Windows:
+- agent ids and keys are validated (no `..`, absolute paths, drive letters, backslashes, characters
+  or device names Windows forbids), and the resolved path must stay inside the agent's folder;
+- writes are atomic (temp file + rename), so a crash never leaves a half-written value;
+- keys are always reported with forward slashes.
+"""
+from __future__ import annotations
+
+import json
+import shutil
+from pathlib import Path
+from typing import Any, Optional
+
+from pal.errors import UserInputError
+from pal.paths import atomic_write_bytes, is_safe_relative_key, safe_id
+
+
+class InvalidStorageKey(UserInputError):
+    pass
+
+
+class LocalFileBackend:
+    def __init__(self, root: Path):
+        self.root = Path(root)
+        self.root.mkdir(parents=True, exist_ok=True)
+
+    def _agent_dir(self, agent_id: str) -> Path:
+        if not agent_id or safe_id(agent_id) != agent_id:
+            raise InvalidStorageKey(f"invalid agent id: {agent_id!r}")
+        d = self.root / agent_id
+        d.mkdir(parents=True, exist_ok=True)
+        return d
+
+    def _path(self, agent_id: str, key: str) -> Path:
+        base = self._agent_dir(agent_id)
+        if not is_safe_relative_key(key):
+            raise InvalidStorageKey(f"invalid storage key: {key!r}")
+        path = (base / key).resolve()
+        if base.resolve() not in path.parents:
+            raise InvalidStorageKey(f"storage key escapes its folder: {key!r}")
+        return path
+
+    def write(self, agent_id: str, key: str, data: Any) -> None:
+        path = self._path(agent_id, key)
+        raw = bytes(data) if isinstance(data, (bytes, bytearray)) else json.dumps(data).encode("utf-8")
+        atomic_write_bytes(path, raw)
+
+    def read(self, agent_id: str, key: str) -> Optional[Any]:
+        path = self._path(agent_id, key)
+        if not path.is_file():
+            return None
+        try:
+            return json.loads(path.read_text(encoding="utf-8"))
+        except (UnicodeDecodeError, json.JSONDecodeError):
+            return path.read_bytes()
+
+    def delete(self, agent_id: str, key: str) -> None:
+        path = self._path(agent_id, key)
+        if path.is_file():
+            path.unlink()
+
+    def exists(self, agent_id: str, key: str) -> bool:
+        return self._path(agent_id, key).is_file()
+
+    def list_keys(self, agent_id: str, prefix: str = "") -> list[str]:
+        agent_dir = self._agent_dir(agent_id)
+        keys = []
+        for p in agent_dir.rglob("*"):
+            if not p.is_file() or p.name.endswith(".tmp"):
+                continue
+            rel = p.relative_to(agent_dir).as_posix()
+            if rel.startswith(prefix):
+                keys.append(rel)
+        return sorted(keys)
+
+    def purge(self, agent_id: str) -> None:
+        """Delete everything stored for one agent."""
+        d = self.root / agent_id
+        if d.is_dir() and safe_id(agent_id) == agent_id:
+            shutil.rmtree(d, ignore_errors=True)

pal/storage_manager/components/storage_queue.py

@@ -0,0 +1,91 @@
+"""
+Centralized storage system-call queue (AIOS section 3.6): "the agent
+calls the storage API in the SDK, which is further converted into
+storage-related system calls and put into the storage queue by the
+scheduler. The storage manager then processes the requests in the
+queue."
+
+Mirrors how llm_wrapper' inference requests are centralized in
+orchestrator/components/syscall_scheduler.py (section 3.3) -- one
+queue, submit() to add work, something drives it forward. Storage ops
+are effectively instantaneous local file/DB operations (no
+multi-second generation to time-slice), so this queue only needs FIFO
+processing; there's no equivalent need for Round Robin / context-
+interrupt machinery here.
+"""
+from __future__ import annotations
+
+import threading
+import time
+import uuid
+from collections import deque
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Optional
+
+from pal.storage_manager.components.base import StorageResponse, StorageSyscall
+
+
+class StorageSyscallStatus(str, Enum):
+    QUEUED = "queued"
+    DONE = "done"
+    ERROR = "error"
+
+
+@dataclass
+class StorageRequest:
+    syscall: StorageSyscall
+    id: str = field(default_factory=lambda: str(uuid.uuid4()))
+    submitted_at: float = field(default_factory=time.time)
+    status: StorageSyscallStatus = StorageSyscallStatus.QUEUED
+    response: Optional[StorageResponse] = None
+
+
+class StorageSyscallQueue:
+    def __init__(self, pipeline):
+        # `pipeline` is a StorageManagerPipeline, kept untyped here to
+        # avoid a circular import between this module and pipeline.py
+        # (which owns the queue and passes itself in).
+        self.pipeline = pipeline
+        self.queue: deque[StorageRequest] = deque()
+        self.requests: dict[str, StorageRequest] = {}
+        self._lock = threading.Lock()
+
+    def submit(self, syscall: StorageSyscall) -> str:
+        req = StorageRequest(syscall=syscall)
+        with self._lock:
+            self.requests[req.id] = req
+            self.queue.append(req)
+        return req.id
+
+    def process_next(self) -> Optional[StorageRequest]:
+        with self._lock:
+            if not self.queue:
+                return None
+            req = self.queue.popleft()
+        try:
+            req.response = self.pipeline.execute(req.syscall)
+            req.status = StorageSyscallStatus.DONE if req.response.ok else StorageSyscallStatus.ERROR
+        except Exception as e:
+            req.response = StorageResponse(ok=False, error=str(e))
+            req.status = StorageSyscallStatus.ERROR
+        return req
+
+    def drain(self, max_iterations: int = 10_000) -> list[StorageRequest]:
+        finished = []
+        i = 0
+        while self.queue and i < max_iterations:
+            finished.append(self.process_next())
+            i += 1
+        return finished
+
+    def get_result(self, request_id: str) -> StorageRequest:
+        return self.requests[request_id]
+
+    def forget(self, request_id: str) -> None:
+        """Drop a finished request. Callers that wait synchronously (the SDK) call this so the
+        request table does not grow for the life of the process."""
+        self.requests.pop(request_id, None)
+
+    def pending_count(self) -> int:
+        return len(self.queue)