pal-code 0.1.0__py3-none-any.whl

pal/os_kernel/pipeline.py

@@ -0,0 +1,175 @@
+"""The OS kernel interface: where non-LLM queries go.
+
+An agent's non-LLM requests (file operations, network requests, system facts) are not model work and never touch the
+LLM. They are system calls into the operating system, here Ubuntu's Linux kernel: files through its filesystem, requests
+through its network stack, facts through /proc. This class is the guarded doorway: a per-agent workspace, size and
+network limits, the access manager's confirmation gate for destructive operations, and an audit trail (operation and
+target only, never file contents).
+"""
+from __future__ import annotations
+
+import base64
+import logging
+from collections import deque
+from pathlib import Path
+from typing import Any
+
+from pal.access_manager.components.base import OperationType
+from pal.access_manager.pipeline import AccessManagerPipeline
+from pal.config import OsKernelConfig
+from pal.os_kernel import network
+from pal.os_kernel.filesystem import OSKernelError, Workspace
+from pal.os_kernel.sysinfo import system_info
+from pal.paths import data_dir, safe_id
+
+log = logging.getLogger(__name__)
+
+OS_OPS = ("file_read", "file_write", "file_list", "file_delete", "file_read_b64", "net_get", "net_post", "net_request", "sys_info",
+          "keyboard", "mouse")
+
+# the file extension for a downloaded media type, used when a caller saves a response as "name.{ext}"
+_EXT = {"image/png": "png", "image/jpeg": "jpg", "image/webp": "webp", "image/gif": "gif", "audio/flac": "flac",
+        "audio/x-flac": "flac", "audio/wav": "wav", "audio/x-wav": "wav", "audio/wave": "wav", "audio/mpeg": "mp3",
+        "audio/ogg": "ogg", "audio/mp4": "m4a"}
+
+
+class OSKernel:
+    def __init__(self, cfg: OsKernelConfig | dict | None = None, access: AccessManagerPipeline | None = None,
+                 root: Path | None = None):
+        self.cfg = OsKernelConfig.coerce(cfg)
+        self.access = access or AccessManagerPipeline()
+        self.root = Path(root) if root else (Path(self.cfg.workspace_dir).expanduser() if self.cfg.workspace_dir
+                                             else data_dir("workspaces"))
+        self._workspaces: dict[str, Workspace] = {}
+        self.audit: deque[dict] = deque(maxlen=500)
+
+    def workspace(self, agent_id: str) -> Workspace:
+        key = safe_id(agent_id)
+        if key not in self._workspaces:
+            self._workspaces[key] = Workspace(self.root / key, self.cfg.max_read_bytes, self.cfg.max_write_bytes,
+                                              self.cfg.max_binary_bytes)
+        return self._workspaces[key]
+
+    def drop_workspace(self, agent_id: str) -> bool:
+        """Delete an agent's whole workspace: used when a chat session ends, so uploaded and generated files do not outlive it."""
+        import shutil
+        key = safe_id(agent_id)
+        self._workspaces.pop(key, None)
+        path = self.root / key
+        existed = path.is_dir()
+        shutil.rmtree(path, ignore_errors=True)
+        return existed
+
+    def prune_stale(self, prefix: str, max_age_seconds: float) -> int:
+        """Delete workspaces whose folder name starts with `prefix` and that nothing has touched for `max_age_seconds` (left behind
+        by a crash or an upload whose chat never started). Other workspaces, such as an SDK agent's own, are not touched."""
+        import shutil
+        import time
+        removed = 0
+        if not self.root.is_dir():
+            return 0
+        for d in self.root.iterdir():
+            try:
+                if d.is_dir() and d.name.startswith(prefix) and time.time() - self._last_touched(d) > max_age_seconds:
+                    self._workspaces.pop(d.name, None)
+                    shutil.rmtree(d, ignore_errors=True)
+                    removed += 1
+            except OSError:
+                continue
+        return removed
+
+    @staticmethod
+    def _last_touched(d: Path) -> float:
+        times = [d.stat().st_mtime] + [p.stat().st_mtime for p in d.rglob("*") if p.is_file()]
+        return max(times)
+
+    def _authorize(self, agent_id: str, op: OperationType, resource: str) -> None:
+        decision = self.access.authorize(agent_id, agent_id, op, resource=resource)
+        if not decision.allowed:
+            raise OSKernelError(f"{op.value} of {resource!r} was not permitted: {decision.reason or 'denied'}")
+
+    def handle(self, agent_id: str, op: str, params: dict | None = None) -> Any:
+        params = params or {}
+        # a URL is logged without its query string: that is where a service key may be
+        target = network.safe_target(str(params["url"])) if params.get("url") else str(params.get("path") or params.get("prefix") or "")
+        ok = False
+        try:
+            if not self.cfg.enabled:
+                raise OSKernelError("OS access is turned off in the settings")
+            if op not in OS_OPS:
+                raise OSKernelError(f"unknown OS operation {op!r}; available: {', '.join(OS_OPS)}")
+            result = self._dispatch(agent_id, op, params)
+            ok = True
+            return result
+        finally:
+            self.audit.append({"agent": agent_id, "op": op, "target": target[:200], "ok": ok})
+            log.info("os call agent=%s op=%s target=%s ok=%s", agent_id, op, target[:120], ok)
+
+    def _dispatch(self, agent_id: str, op: str, p: dict) -> Any:
+        if op in ("keyboard", "mouse"):
+            raise OSKernelError("keyboard and mouse control need a desktop session and are not supported here")
+        if op == "sys_info":
+            return system_info()
+        if op in ("net_get", "net_post"):
+            return network.request(
+                "GET" if op == "net_get" else "POST", str(p.get("url", "")), allow_private=self.cfg.allow_private_network,
+                allowed_hosts=list(self.cfg.allowed_hosts), timeout=self.cfg.net_timeout_seconds,
+                max_bytes=self.cfg.net_max_bytes, json=p.get("json"))
+        if op == "net_request":
+            return self._net_request(agent_id, p)
+        ws = self.workspace(agent_id)
+        if op == "file_list":
+            return ws.list(str(p.get("prefix", "")))
+        path = str(p.get("path", ""))
+        ws.resolve(path)                      # validate first: nobody is ever asked to confirm an invalid path
+        if op == "file_read":
+            return ws.read(path)
+        if op == "file_read_b64":
+            data = ws.read_bytes(path)
+            return {"path": path, "bytes": len(data), "b64": base64.b64encode(data).decode("ascii")}
+        if op == "file_write":
+            self._authorize(agent_id, OperationType.OVERWRITE if ws.exists(path) else OperationType.WRITE, path)
+            return {"path": path, "bytes": ws.write(path, p.get("content", ""))}
+        if not ws.exists(path):               # file_delete: nothing to confirm if there is nothing to delete
+            raise OSKernelError(f"no such file: {path}")
+        self._authorize(agent_id, OperationType.DELETE, path)
+        ws.delete(path)
+        return {"path": path, "deleted": True}
+
+    def _net_request(self, agent_id: str, p: dict) -> dict:
+        """A network request with auth headers (from an allow-list), and binary data in either direction through the workspace:
+        `body_path` sends a workspace file as the request body, `save_as` stores a non-text answer in the workspace (a literal
+        "{ext}" in the name becomes the right extension). Text answers come back as `text`."""
+        method = str(p.get("method", "GET")).upper()
+        if method not in ("GET", "POST"):
+            raise OSKernelError("only GET and POST requests are supported")
+        ws = self.workspace(agent_id)
+        headers = network.clean_headers(p.get("headers"))
+        data = None
+        if p.get("body_path"):
+            if p.get("json") is not None:
+                raise OSKernelError("send either a JSON body or a file, not both")
+            data = ws.read_bytes(str(p["body_path"]))
+            headers["Content-Type"] = str(p.get("content_type") or "application/octet-stream")
+            headers = network.clean_headers(headers)
+        save_as = str(p["save_as"]) if p.get("save_as") else ""
+        if save_as:
+            ws.resolve(save_as.replace("{ext}", "bin"))           # validate the name before spending a request
+        res = network.request(method, str(p.get("url", "")), allow_private=self.cfg.allow_private_network,
+                              allowed_hosts=list(self.cfg.allowed_hosts), timeout=self.cfg.net_timeout_seconds,
+                              max_bytes=self.cfg.net_max_bytes, json=p.get("json"), headers=headers, data=data,
+                              max_binary_bytes=self.cfg.max_binary_bytes, keep_binary=True)
+        body = res.pop("body", None)
+        if body is None:
+            return res
+        res["binary"] = True
+        if res["truncated"]:
+            raise OSKernelError(f"the answer is larger than the {self.cfg.max_binary_bytes:,}-byte limit")
+        if not save_as or res["status"] >= 400:
+            return {**res, "saved": ""}
+        ext = _EXT.get(res["content_type"].split(";")[0].strip().lower(), "bin")
+        path = save_as.replace("{ext}", ext)
+        ws.resolve(path)
+        self._authorize(agent_id, OperationType.OVERWRITE if ws.exists(path) else OperationType.WRITE, path)
+        ws.write_bytes(path, body)
+        return {**res, "saved": path}

pal/os_kernel/sysinfo.py

@@ -0,0 +1,36 @@
+"""Read-only facts from the OS kernel. On Linux (Ubuntu) they come from /proc and /etc/os-release."""
+from __future__ import annotations
+
+import os
+import platform
+from pathlib import Path
+
+
+def _distro() -> str:
+    try:
+        for line in Path("/etc/os-release").read_text(encoding="utf-8").splitlines():
+            if line.startswith("PRETTY_NAME="):
+                return line.split("=", 1)[1].strip().strip('"')
+    except OSError:
+        pass
+    return platform.system()
+
+
+def _meminfo() -> dict:
+    out = {}
+    try:
+        for line in Path("/proc/meminfo").read_text(encoding="utf-8").splitlines():
+            key, _, rest = line.partition(":")
+            if key in ("MemTotal", "MemAvailable"):
+                out[key] = int(rest.split()[0]) // 1024
+    except (OSError, ValueError, IndexError):
+        pass
+    return {"total_mb": out.get("MemTotal"), "available_mb": out.get("MemAvailable")} if out else {}
+
+
+def system_info() -> dict:
+    info: dict = {"system": platform.system(), "distro": _distro(), "kernel": platform.release(), "machine": platform.machine(),
+            "cpu_count": os.cpu_count(), "memory": _meminfo()}
+    if hasattr(os, "getloadavg"):
+        info["load_average"] = [round(x, 2) for x in os.getloadavg()]
+    return info

pal/paths.py

@@ -0,0 +1,59 @@
+"""Where Pal keeps its data, the same way on Linux, macOS and Windows.
+
+Default is `~/.pal` (Path.home() resolves correctly on every OS). Set PAL_HOME to move it.
+"""
+from __future__ import annotations
+
+import os
+import re
+from pathlib import Path
+
+_WINDOWS_RESERVED = {"con", "prn", "aux", "nul", *(f"com{i}" for i in range(1, 10)), *(f"lpt{i}" for i in range(1, 10))}
+_SAFE_ID = re.compile(r"[^A-Za-z0-9_-]")
+
+
+def pal_home() -> Path:
+    env = os.environ.get("PAL_HOME")
+    return Path(env).expanduser() if env else Path.home() / ".pal"
+
+
+def data_dir(*parts: str) -> Path:
+    return pal_home().joinpath(*parts)
+
+
+def safe_id(value: str, default: str = "default", max_len: int = 64) -> str:
+    """Turn any string into something safe as one path component on every OS."""
+    out = _SAFE_ID.sub("", value or "")[:max_len]
+    if not out or out.lower() in _WINDOWS_RESERVED:
+        return default if not out else f"_{out}"
+    return out
+
+
+def is_safe_relative_key(key: str) -> bool:
+    """True when `key` is a relative path that stays inside its folder on every OS: no `..`, no drive
+    letters or absolute paths, no backslashes, no characters Windows forbids, no reserved device names."""
+    if not key or key != key.strip() or "\\" in key or key.startswith("/") or "\x00" in key:
+        return False
+    for part in key.split("/"):
+        if part in ("", ".", "..") or re.search(r'[<>:"|?*\x00-\x1f]', part) or part.endswith((".", " ")):
+            return False
+        if part.split(".")[0].lower() in _WINDOWS_RESERVED:
+            return False
+    return True
+
+
+def atomic_write_bytes(path: Path, data: bytes) -> None:
+    """Write via a temp file and rename, so a crash never leaves a half-written file (os.replace is
+    atomic on POSIX and replaces an existing file on Windows)."""
+    path.parent.mkdir(parents=True, exist_ok=True)
+    tmp = path.with_name(f".{path.name}.{os.getpid()}.tmp")
+    try:
+        tmp.write_bytes(data)
+        os.replace(tmp, path)
+    finally:
+        if tmp.exists():
+            tmp.unlink(missing_ok=True)
+
+
+def atomic_write_text(path: Path, text: str) -> None:
+    atomic_write_bytes(path, text.encode("utf-8"))

pal/pipeline.py

@@ -0,0 +1,177 @@
+import time
+import uuid
+
+from pal.agent_constraints.pipeline import AgentConstraintsPipeline
+from pal.compression.pipeline import CompressionPipeline
+from pal.context_manager.components.pager import Segment
+from pal.context_manager.pipeline import ContextManagerPipeline
+from pal.llm_wrapper.components.base import LLMSyscall, WrapperConfig
+from pal.llm_wrapper.pipeline import LLMWrapperPipeline
+from pal.memory.pipeline import MemoryPipeline
+from pal.metrics.pipeline import MetricsPipeline
+
+
+class Pipeline:
+    """
+    One full chat turn, top to bottom:
+    user message -> compression + memory recall -> cache + paging ->
+    an LLM core (any deployment option) -> compressed reply, with
+    metrics recorded and history/memory updated.
+
+    This is the class every other entry point (webapp, orchestrator
+    agents, experiments) drives -- it's the composition root for every
+    pal/<component>/pipeline.py above.
+    """
+
+    def __init__(
+        self,
+        core_config: WrapperConfig,
+        session_id: str = None,
+        memory_store_path: str = None,
+        syscall_scheduler=None,
+        agent_name: str = None,
+        storage_manager=None,
+    ):
+        self.llm_wrapper = LLMWrapperPipeline(core_config)
+        self.context_manager = ContextManagerPipeline(self.llm_wrapper.core)
+        self.compression = CompressionPipeline()
+        self.agent_constraints = AgentConstraintsPipeline()
+        self.metrics = MetricsPipeline()
+        self.history: list[Segment] = []
+        self.session_id = session_id or str(uuid.uuid4())
+        self.agent_name = agent_name or self.session_id
+
+        # Persistent, cross-session memory (survives restarts) -- distinct
+        # from context_manager's pager, which only pages within THIS open
+        # conversation and forgets everything once the process exits.
+        # When a shared StorageManagerPipeline is supplied (AIOS 3.6 --
+        # see pal/storage_manager/), the memory manager's disk
+        # swaps route through it, scoped by this Pipeline's agent_name;
+        # otherwise MemoryPipeline falls back to its own private,
+        # unscoped local store.
+        self.storage_manager = storage_manager
+        self.memory = MemoryPipeline(
+            store_path=memory_store_path,
+            agent_id=self.agent_name,
+            storage_manager=storage_manager,
+        )
+
+        # Optional centralized syscall scheduler (AIOS 3.3 -- see
+        # orchestrator/components/syscall_scheduler.py). When one is
+        # supplied (typically the same SyscallScheduler an
+        # OrchestratorPipeline owns, shared across every agent/pipeline
+        # in the system), this Pipeline submits its LLM requests there
+        # instead of calling the core directly -- so ordering and
+        # time-slicing across MULTIPLE pipelines/agents actually goes
+        # through one queue, not a private one per Pipeline instance.
+        # Left as None by default (e.g. the standalone webapp use case),
+        # in which case run() falls back to calling llm_wrapper directly.
+        self.syscall_scheduler = syscall_scheduler
+
+    # kept for callers that reached into the old Router/adapter directly
+    # (e.g. the webapp's naive-vs-optimized benchmark path)
+    @property
+    def core(self):
+        return self.llm_wrapper.core
+
+    def run(self, system_prompt: str, user_message: str, **kwargs) -> str:
+        # Permanent output-behavior constraints, merged into every system
+        # prompt so the model generates tersely up front rather than
+        # being trimmed after the fact.
+        system_prompt = self.agent_constraints.with_constraints(system_prompt)
+
+        compressed_msg = self.compression.compress_input(user_message)
+
+        # Persistent memory recall: pull relevant notes from PAST
+        # sessions (not this conversation's own history). Injected into
+        # the system prompt so it doesn't distort the naive-vs-optimized
+        # token comparison for history paging below.
+        recalled_memories = self.memory.retrieve(compressed_msg, top_k=3)
+        if recalled_memories:
+            memory_block = "\n".join(f"- {n.content}" for n in recalled_memories)
+            system_prompt = f"{system_prompt}\n\nRelevant memory from past sessions:\n{memory_block}"
+
+        cache_hit, _ = self.context_manager.cache_system_prompt(system_prompt)
+        paged = self.context_manager.page_history(self.history, compressed_msg)
+
+        messages = [{"role": "system", "content": system_prompt}]
+        for seg in paged:
+            messages.append({"role": seg.role, "content": seg.content})
+        messages.append({"role": "user", "content": compressed_msg})
+
+        # Naive baseline: what a naive/unbounded implementation would
+        # send this turn -- the FULL history (not paged/trimmed) plus
+        # system prompt and new message. Comparing it against what was
+        # actually sent (optimized_tokens below) reflects real paging
+        # savings, not a same-payload measured-two-ways artifact.
+        naive_messages = [system_prompt] + [seg.content for seg in self.history] + [compressed_msg]
+        naive_tokens = sum(self.llm_wrapper.syscall_token_count(t) for t in naive_messages)
+
+        t0 = time.time()
+        response = self._dispatch_chat(messages, **kwargs)
+        latency = time.time() - t0
+
+        output_text = self.compression.compress_output(response.text)
+
+        # Optimized figure: the server's own reported prompt-eval count,
+        # when available. For local server cores this reflects tokens
+        # actually reprocessed -- if the backend's KV cache reused a
+        # matching prefix, this number comes back lower than the naive
+        # estimate on its own. Falls back to the estimate otherwise
+        # (meaning: no measurable saving, not a caching failure).
+        optimized_tokens = response.prompt_tokens if response.prompt_tokens else naive_tokens
+
+        self.metrics.record(
+            tokens_naive=naive_tokens,
+            tokens_optimized=optimized_tokens,
+            latency=latency,
+            cache_hit=cache_hit,
+        )
+
+        self.history.append(Segment(id=str(len(self.history)), content=compressed_msg, role="user"))
+        self.history.append(Segment(id=str(len(self.history)), content=output_text, role="assistant"))
+
+        # Persist this turn to long-term memory so it can be recalled in
+        # a FUTURE session (a future Pipeline instance, possibly after a
+        # restart) -- not just later in this same conversation.
+        self.memory.add(compressed_msg, session_id=self.session_id, tags=["user_turn"])
+
+        return output_text
+
+    def _dispatch_chat(self, messages: list[dict], **kwargs):
+        """Routes the actual inference call either through the shared
+        centralized SyscallScheduler (when one was supplied -- request
+        ordering/time-slicing then happens there, alongside every other
+        pipeline/agent sharing that scheduler) or directly through
+        llm_wrapper when running standalone."""
+        if self.syscall_scheduler is None:
+            return self.llm_wrapper.syscall_chat(messages, **kwargs)
+
+        syscall = LLMSyscall(
+            messages=messages,
+            model=kwargs.pop("model", None),
+            temperature=kwargs.pop("temperature", None),
+            max_tokens=kwargs.pop("max_tokens", None),
+            stream=kwargs.pop("stream", False),
+            params=kwargs,
+        )
+        request_id = self.syscall_scheduler.submit(self.agent_name, self.llm_wrapper.core, syscall)
+
+        # Drive the shared scheduler until THIS request reaches a
+        # terminal state. Other pipelines/agents sharing the same
+        # scheduler may have requests interleaved into these ticks too
+        # (that's the point of centralizing) -- this loop just doesn't
+        # return control to this Pipeline until its own turn is done.
+        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"syscall failed: {req.error}")
+        return req.result
+
+    def summary(self) -> dict:
+        """Metrics summary including cache memory overhead, so savings
+        can be checked against the cost of the caching layer itself."""
+        return self.metrics.summary(cache_overhead_bytes=self.context_manager.size_bytes())

pal/redact.py

@@ -0,0 +1,19 @@
+"""Hide API keys in any text that may be shown or logged. Known keys are replaced exactly; strings shaped like common provider
+keys are replaced too, because a provider's error message can echo a key we were never told about."""
+from __future__ import annotations
+
+import re
+
+_SECRET = re.compile(r"(sk-[A-Za-z0-9_\-]{8,}|AIza[0-9A-Za-z_\-]{10,}|AQ\.[A-Za-z0-9_\-]{20,}|AKIA[0-9A-Z]{12,}"
+                     r"|Bearer\s+[A-Za-z0-9._\-]{12,})")
+
+
+# a key=value pair whose name says it is a secret, as in a query string: ?api_key=abc&q=cats
+_PAIR = re.compile(r"(?i)\b(api[_-]?key|apikey|appid|app_id|access[_-]?token|auth[_-]?token|token|secret|password|key)=([^&\s\"']+)")
+
+
+def redact(text: str, *keys: str | None) -> str:
+    for k in keys:
+        if k:
+            text = text.replace(k, "***")
+    return _PAIR.sub(r"\1=***", _SECRET.sub("***", text))

pal/sdk/__init__.py

@@ -0,0 +1,33 @@
+"""The Pal SDK: build native agents on pre-defined APIs, or adapt agents written with other frameworks.
+
+    from pal.sdk import AgentSDK, adapt, NativeAgent, ReActAgent, ReflexionAgent
+"""
+from pal.sdk.adapters import adapt, supported_frameworks
+from pal.sdk.agent import AgentResult, AgentSpec, NativeAgent, agent_key, list_agents
+from pal.sdk.components.autogen_adapter import AutoGenAdapter
+from pal.sdk.components.autogen_client import autogen_model_client
+from pal.sdk.components.framework_adapter_base import FrameworkAdapter, FrameworkAdapterError
+from pal.sdk.components.metagpt_adapter import MetaGPTAdapter
+from pal.sdk.components.open_interpreter_adapter import OpenInterpreterAdapter
+from pal.sdk.components.tool_catalog import register_builtin_tools
+from pal.sdk.os_api import OSAPI, register_os_tools
+from pal.sdk.patterns import ReActAgent, ReflexionAgent
+from pal.sdk.pipeline import AgentSDK
+from pal.sdk.queries import (
+    OS_KERNEL,
+    PAL_KERNEL,
+    LLMQuery,
+    MemoryQuery,
+    OSQuery,
+    Query,
+    Response,
+    StorageQuery,
+    ToolQuery,
+)
+from pal.sdk.savers import CallSavers
+
+__all__ = [
+    "AgentResult", "AgentSDK", "LLMQuery", "PAL_KERNEL", "MemoryQuery", "OSAPI", "OSQuery", "OS_KERNEL", "Query", "Response", "StorageQuery", "ToolQuery", "register_os_tools", "AgentSpec", "AutoGenAdapter", "CallSavers", "FrameworkAdapter",
+    "FrameworkAdapterError", "MetaGPTAdapter", "NativeAgent", "OpenInterpreterAdapter", "ReActAgent",
+    "ReflexionAgent", "adapt", "agent_key", "autogen_model_client", "list_agents", "register_builtin_tools", "supported_frameworks",
+]

pal/sdk/adapters.py

@@ -0,0 +1,43 @@
+"""One entry point for non-native agents: `adapt("autogen", sdk)`.
+
+Third-party frameworks are adapted by replacing the framework's own core model-call function so the call goes to
+the SDK instead; the agent's code is not changed. ReAct and Reflexion are reasoning patterns, not libraries, so
+they ship as native agents (`ReActAgent`, `ReflexionAgent`).
+
+    sdk = AgentSDK.standalone(WrapperConfig(backend="gemini", model="...", api_key="..."))
+    with adapt("autogen", sdk):
+        ...  # your existing AutoGen code, unchanged
+"""
+from __future__ import annotations
+
+from pal.sdk.components.autogen_adapter import AutoGenAdapter
+from pal.sdk.components.framework_adapter_base import FrameworkAdapter, FrameworkAdapterError
+from pal.sdk.components.metagpt_adapter import MetaGPTAdapter
+from pal.sdk.components.open_interpreter_adapter import OpenInterpreterAdapter
+from pal.sdk.pipeline import AgentSDK
+
+_ADAPTERS: dict[str, type[FrameworkAdapter]] = {
+    "autogen": AutoGenAdapter, "open-interpreter": OpenInterpreterAdapter, "metagpt": MetaGPTAdapter}
+_ALIASES = {"open_interpreter": "open-interpreter", "interpreter": "open-interpreter", "pyautogen": "autogen"}
+_PATTERNS = {"react": "ReActAgent", "reflexion": "ReflexionAgent"}
+
+
+def _norm(name: str) -> str:
+    n = name.strip().lower()
+    return _ALIASES.get(n, n)
+
+
+def adapt(framework: str, sdk: AgentSDK) -> FrameworkAdapter:
+    """An adapter for `framework`. Use it as a context manager, or call install() and uninstall() yourself."""
+    n = _norm(framework)
+    if n in _PATTERNS:
+        raise FrameworkAdapterError(f"{framework} is a reasoning pattern, not a library: use {_PATTERNS[n]}(sdk) "
+                                    "from pal.sdk")
+    cls = _ADAPTERS.get(n)
+    if cls is None:
+        raise FrameworkAdapterError(f"no adapter for {framework!r}; supported: {', '.join(supported_frameworks())}")
+    return cls(sdk)
+
+
+def supported_frameworks() -> list[str]:
+    return [*_ADAPTERS, *_PATTERNS]

pal/sdk/agent.py

@@ -0,0 +1,99 @@
+"""Native agent development: what a developer subclasses to build an agent for Pal.
+
+A *native* agent is written for Pal: it talks to the system only through the SDK's pre-defined APIs
+(`self.sdk.chat`, `.remember`, `.recall`, `.write`, `.read`, `.search_knowledge`, `.call_tool`, `.request_access`).
+It never holds a model client, a file handle or a tool directly, so Pal can route, trim, cache, limit and
+measure every call. A *non-native* agent is written with another framework and is adapted instead
+(see `pal.sdk.adapt`).
+"""
+from __future__ import annotations
+
+import os
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from typing import Any, ClassVar, Protocol
+
+from pal.errors import UserInputError
+
+_READ_TOOLS = frozenset({"read_source", "search_documents", "read_document"})
+
+
+@dataclass(frozen=True)
+class AgentSpec:
+    """The small, declarative part of an agent."""
+
+    id: str
+    name: str
+    description: str
+    role: str                     # kept short: it is sent with every request
+    key_env: str = ""             # environment variable holding this agent's API key ("" = none needed)
+    tools: frozenset[str] = _READ_TOOLS
+    max_tokens: int = 1024        # output cap per call (free tiers are small)
+
+
+@dataclass
+class AgentResult:
+    answer: str
+    ok: bool = True
+    steps: list[Any] = field(default_factory=list)   # ReAct steps, Reflexion trials, ...
+    error: str = ""
+    meta: dict = field(default_factory=dict)
+
+
+class Kernel(Protocol):
+    """Anything that runs a full token-saving turn: ChatService does."""
+
+    def send(self, session_id: str, provider: str, model: str, api_key: str | None, message: str,
+             attachments: list[dict], *args: Any, **kw: Any) -> Any: ...
+
+
+class NativeAgent:
+    """Base class for native agents.
+
+    `sdk` gives the pre-defined APIs. `kernel` (optional) is the token-saving turn pipeline; when present, the
+    default `run()` uses it, so the agent gets input trimming, document and code-graph retrieval, paged history
+    and output rules for free. Without a kernel, `run()` makes one plain SDK call with the agent's role.
+    Override `run()` to write your own logic with the SDK calls (see ReActAgent and ReflexionAgent).
+    """
+
+    spec: ClassVar[AgentSpec | None] = None
+
+    def __init__(self, sdk: Any = None, kernel: Kernel | None = None):
+        self.sdk = sdk
+        self.kernel = kernel
+
+    def run(self, task: str, attachments: list[dict] | None = None, session: str = "agent") -> AgentResult:
+        spec = self.spec
+        if spec is None:
+            raise NotImplementedError("a native agent needs a `spec` or its own run()")
+        if self.kernel is not None:
+            res = self.kernel.send(session, "", "", None, task, list(attachments or []), agent=spec.id)
+            return AgentResult(res.reply, meta={"input_tokens": res.input_tokens, "output_tokens": res.output_tokens})
+        if self.sdk is None:
+            raise RuntimeError("no SDK or kernel: create the agent with sdk= or kernel=")
+        text = self.sdk.chat([{"role": "system", "content": spec.role}, {"role": "user", "content": task}],
+                             max_tokens=spec.max_tokens)
+        return AgentResult(text)
+
+
+def agent_key(spec: AgentSpec, env: Mapping[str, str] | None = None) -> str | None:
+    """The agent's own key, else the shared GEMINI_API_KEY."""
+    env = os.environ if env is None else env
+    return (env.get(spec.key_env) if spec.key_env else None) or env.get("GEMINI_API_KEY") or None
+
+
+def get_spec(agents: Mapping[str, type[NativeAgent]], agent_id: str) -> AgentSpec:
+    cls = agents.get(agent_id)
+    if cls is None or cls.spec is None:
+        raise UserInputError(f"unknown agent {agent_id!r}; choose one of: {', '.join(agents)}")
+    return cls.spec
+
+
+def list_agents(agents: Mapping[str, type[NativeAgent]], env: Mapping[str, str] | None = None) -> list[dict]:
+    out = []
+    for cls in agents.values():
+        s = cls.spec
+        if s is not None:
+            out.append({"id": s.id, "name": s.name, "description": s.description,
+                        "ready": bool(agent_key(s, env)), "key_env": s.key_env})
+    return out

pal/sdk/components/__init__.py

@@ -0,0 +1,14 @@
+from pal.sdk.components.autogen_adapter import AutoGenAdapter
+from pal.sdk.components.framework_adapter_base import FrameworkAdapter, FrameworkAdapterError
+from pal.sdk.components.metagpt_adapter import MetaGPTAdapter
+from pal.sdk.components.open_interpreter_adapter import OpenInterpreterAdapter
+from pal.sdk.components.tool_catalog import register_builtin_tools
+
+__all__ = [
+    "AutoGenAdapter",
+    "FrameworkAdapter",
+    "FrameworkAdapterError",
+    "MetaGPTAdapter",
+    "OpenInterpreterAdapter",
+    "register_builtin_tools",
+]