aipelago-sdk 0.6.1__tar.gz

aipelago_sdk-0.6.1/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

aipelago_sdk-0.6.1/PKG-INFO

@@ -0,0 +1,30 @@
+Metadata-Version: 2.4
+Name: aipelago-sdk
+Version: 0.6.1
+Summary: The SDK agents are written against: @tool, @hook and the ToolContext a handler receives.
+Author-email: Jiaan Liu <jiaanliux@gmail.com>
+License-Expression: Apache-2.0
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: pydantic==2.12.0
+Description-Content-Type: text/markdown
+
+# aipelago-sdk
+
+The author-facing API for Aipelago agents: `@tool`, `@hook`, and the `ToolContext`
+the kernel injects into every handler.
+
+The same API on every distribution of the kernel, so an agent written for one
+runs on all of them. A distribution's developer CLI (for Ailands, `pip install
+ailands`) depends on this package, so installing the CLI brings it in.
+
+```python
+from aipelago.sdk import tool, ToolContext
+
+@tool("weather.today")
+async def today(ctx: ToolContext, args: dict) -> dict:
+    return {"forecast": "sun"}
+```
+
+Installing this package needs no kernel: it exists so you can type-check and
+unit-test an agent on your own machine.

aipelago_sdk-0.6.1/README.md

@@ -0,0 +1,19 @@
+# aipelago-sdk
+
+The author-facing API for Aipelago agents: `@tool`, `@hook`, and the `ToolContext`
+the kernel injects into every handler.
+
+The same API on every distribution of the kernel, so an agent written for one
+runs on all of them. A distribution's developer CLI (for Ailands, `pip install
+ailands`) depends on this package, so installing the CLI brings it in.
+
+```python
+from aipelago.sdk import tool, ToolContext
+
+@tool("weather.today")
+async def today(ctx: ToolContext, args: dict) -> dict:
+    return {"forecast": "sun"}
+```
+
+Installing this package needs no kernel: it exists so you can type-check and
+unit-test an agent on your own machine.

aipelago_sdk-0.6.1/aipelago/sdk/__init__.py

@@ -0,0 +1,36 @@
+"""Aipelago SDK — author-facing API.
+
+What you import as an agent author. The kernel injects a `ToolContext`
+into every tool handler; the SDK is the only surface authors should depend on.
+
+It needs nothing else of the kernel, so it installs on its own as the
+`aipelago-sdk` package: the one import every distribution's agents are written in.
+"""
+
+from aipelago.sdk.context import (
+    AgentBuilderHandle,
+    AskReply,
+    EmbeddingHandle,
+    InboundAttachment,
+    SessionHandle,
+    SharesHandle,
+    ToolContext,
+)
+from aipelago.sdk.decorator import tool
+from aipelago.sdk.hook import HookDecision, hook
+from aipelago.sdk.principal import Principal, PrincipalStatus
+
+__all__ = [
+    "AgentBuilderHandle",
+    "AskReply",
+    "EmbeddingHandle",
+    "HookDecision",
+    "InboundAttachment",
+    "Principal",
+    "PrincipalStatus",
+    "SessionHandle",
+    "SharesHandle",
+    "ToolContext",
+    "hook",
+    "tool",
+]

aipelago_sdk-0.6.1/aipelago/sdk/context.py

@@ -0,0 +1,800 @@
+"""`ToolContext` — the only object a tool handler may rely on.
+
+The kernel constructs this per tool call and passes it as the first argument to
+the handler. Crucially, it carries no raw DB connection, no provider client, no
+`os` handle — every effect goes through a mediated method.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass, field
+from datetime import datetime
+from pathlib import Path
+from typing import Any, Protocol
+from uuid import UUID
+
+from aipelago.sdk.principal import Principal
+
+
+@dataclass(frozen=True, slots=True)
+class AskReply:
+    """What came back from the person `ctx.ask` asked.
+
+    `text` is always the whole answer in prose. It is what a chat channel
+    produced, what the trajectory records, and what a yes/no decision is judged
+    on — every path can fill it, so every caller can read it.
+
+    `values` is the same answer keyed by field, and only a form filled in on a
+    surface that could draw one produces it. It is the half worth having when
+    there were several questions: without it the caller gets four answers glued
+    into one string and has to take them apart again, which is the parsing step
+    the form existed to remove. Empty when the answer arrived as plain text.
+    """
+
+    text: str
+    values: dict[str, list[str]] = field(default_factory=dict)
+
+
+class SessionHandle(Protocol):
+    """Ephemeral per-session scratch, exposed as `ctx.session`."""
+
+    def get(self, key: str, default: Any = None) -> Any: ...
+    def set(self, key: str, value: Any) -> None: ...
+
+
+class InboundAttachment(Protocol):
+    """One of the caller's attachments as `ctx.attachment()` returns it — bytes
+    plus enough to interpret them."""
+
+    @property
+    def media_type(self) -> str: ...
+    @property
+    def data(self) -> bytes: ...
+    @property
+    def filename(self) -> str: ...
+    @property
+    def id(self) -> UUID | None: ...
+
+
+#: Ask the user a free-form question (optionally with suggested choices) and wait
+#: for their reply over the active channel. Returns the reply text, or None if no
+#: interactive channel is attached or the wait times out.
+AskFn = Callable[[str, "list[str] | None"], Awaitable["str | None"]]
+
+#: Fetch one of the caller's own attachments by id. Returns the attachment
+#: (bytes + media_type + filename), or None when no attachment of this caller
+#: has that id — "not yours" and "does not exist" look the same.
+AttachmentFn = Callable[[str], Awaitable["InboundAttachment | None"]]
+
+#: Answers `ctx.is_admin()`. Three-valued on purpose — see the method.
+AdminFn = Callable[[], Awaitable["bool | None"]]
+#: Behind `ctx.notify`: the notice body in, the receipt out.
+NotifyFn = Callable[[dict[str, Any]], Awaitable[dict[str, Any]]]
+
+
+class _StateHandle(Protocol):
+    async def execute(self, query: str, *args: Any) -> str: ...
+    async def fetch(self, query: str, *args: Any) -> list[Any]: ...
+    async def fetchrow(self, query: str, *args: Any) -> Any: ...
+    async def fetchval(self, query: str, *args: Any) -> Any: ...
+
+
+class CapabilityHandle:
+    """Capability invocation handle exposed via `ctx.capability`."""
+
+    def __init__(
+        self,
+        check: Callable[[str], Awaitable[bool]],
+        invoke: Callable[[str, dict[str, Any]], Awaitable[Any]],
+    ) -> None:
+        self._check = check
+        self._invoke = invoke
+
+    async def check(self, capability_id: str) -> bool:
+        return await self._check(capability_id)
+
+    async def invoke(self, capability_id: str, args: dict[str, Any]) -> Any:
+        return await self._invoke(capability_id, args)
+
+
+class ChannelHandle:
+    """Channel send handle exposed via `ctx.channel`."""
+
+    def __init__(
+        self,
+        send: Callable[..., Awaitable[Any]],
+    ) -> None:
+        self._send = send
+
+    async def send(self, *, to: Any, message: str, via: str | None = None) -> Any:
+        return await self._send(to=to, message=message, via=via)
+
+
+class BudgetHandle:
+    """Per-invocation budget control."""
+
+    def __init__(self, charge: Callable[[dict[str, Any]], Awaitable[None]]) -> None:
+        self._charge = charge
+
+    async def charge(self, cost: dict[str, Any]) -> None:
+        await self._charge(cost)
+
+
+class EmbeddingHandle:
+    """Provider-neutral embedding seam exposed to agent tools."""
+
+    def __init__(self, registry: Any) -> None:
+        self._registry = registry
+
+    def describe(self) -> dict[str, Any]:
+        if self._registry is None:
+            return {"available": False}
+        name = self._registry.select()
+        if name is None:
+            return {"available": False}
+        provider = self._registry.get(name)
+        metadata = dict(provider.meta)
+        describe = metadata.pop("describe", None)
+        if callable(describe):
+            metadata.update(describe())
+        return {
+            "available": True,
+            "provider": name,
+            "dimensions": metadata.pop("dimensions", metadata.pop("dim", None)),
+            "semantic": name != "hashing",
+            **metadata,
+        }
+
+    async def embed(self, texts: list[str], dimensions: int | None = None) -> list[list[float]]:
+        if self._registry is None:
+            raise RuntimeError("embedding backend unavailable")
+        name = self._registry.select()
+        if name is None:
+            raise RuntimeError("embedding backend unavailable")
+        return await self._registry.get(name).run(texts, dimensions)
+
+
+class ScheduleHandle:
+    """Deferred/recurring self-scheduling exposed via `ctx.schedule`.
+
+    Lets a tool register a future persona invocation (a reminder, a recurring
+    job) that the kernel fires and delivers later — the real primitive behind
+    "remind me in 15 minutes". Absent (None) inside an autonomous scheduled run,
+    so a fired task cannot schedule more (no recursion)."""
+
+    def __init__(
+        self,
+        set_fn: Callable[..., Awaitable[Any]],
+        list_fn: Callable[[], Awaitable[Any]],
+        cancel_fn: Callable[[str], Awaitable[bool]],
+    ) -> None:
+        self._set = set_fn
+        self._list = list_fn
+        self._cancel = cancel_fn
+
+    async def set(
+        self, *, when: str, kind: str = "notify", message: str = "", label: str = ""
+    ) -> Any:
+        return await self._set(when=when, kind=kind, message=message, label=label)
+
+    async def list(self) -> Any:
+        return await self._list()
+
+    async def cancel(self, task_id: str) -> bool:
+        return await self._cancel(task_id)
+
+
+class DispatchHandle:
+    """Handing work to a PEER agent, exposed via `ctx.dispatch`.
+
+    Not a call into the peer's code — the kernel starts the peer's OWN persona
+    on the brief, with its own prompt, model and tools. Handed over, the work is
+    the peer's: the person hears from it directly, and its answer — what it
+    said when it finished — comes back to the sender through `status`. Asked
+    (`hand_off(wait=True)`), the sender waits for that answer inside its own
+    turn, which pays for it.
+
+    Absent (None) when this run may not hand work to a peer — for example when
+    it acts for no person.
+
+    Also how a run that IS a handed-over task sends it back — see `decline`.
+    """
+
+    def __init__(
+        self,
+        hand_off_fn: Callable[..., Awaitable[Any]],
+        status_fn: Callable[[], Awaitable[Any]],
+        decline_fn: Callable[[str], Awaitable[None]] | None = None,
+        find_fn: Callable[[str], Awaitable[Any]] | None = None,
+    ) -> None:
+        self._hand_off = hand_off_fn
+        self._status = status_fn
+        self._decline = decline_fn
+        self._find = find_fn
+
+    async def hand_off(
+        self,
+        *,
+        to_agent: str,
+        brief: str,
+        label: str = "",
+        forward_user_turn: bool = True,
+        wait: bool = False,
+    ) -> Any:
+        """Returns a RECEIPT (which peer, which handoff id, its status).
+
+        `wait=True` asks rather than hands over: the receipt comes back once the
+        peer has answered, with its `answer`, and the peer's run spends against
+        this run's own turn. A peer that cannot start now, or is still working
+        when this turn's own limits run out, carries on as an ordinary handoff;
+        its answer is then read later through `status`.
+
+        `forward_user_turn` sends the person's own message and its attachments
+        along with the brief. On by default, and the caller can only turn it OFF
+        — it cannot choose which turn, edit the words, or substitute the files.
+        The runtime reads them off the message this run was actually given, so
+        the receiver's "what the person sent" really is that.
+        """
+        return await self._hand_off(
+            to_agent=to_agent,
+            brief=brief,
+            label=label,
+            forward_user_turn=forward_user_turn,
+            wait=wait,
+        )
+
+    async def status(self) -> Any:
+        """What this agent has handed off for this person lately, how it went,
+        and each peer's answer: what it said when it finished, or why not."""
+        return await self._status()
+
+    async def find(self, need: str) -> Any:
+        """Peers whose own words look like `need`, best first.
+
+        The prompt names only some of the person's other agents; this searches
+        all of them, and finds none the person could not use.
+        """
+        if self._find is None:
+            return []
+        return await self._find(need)
+
+    @property
+    def can_decline(self) -> bool:
+        """True only inside a run that IS a handed-over piece of work.
+
+        There is nothing to decline anywhere else, and a tool that accepted the
+        word regardless would let a model believe it had refused something.
+        """
+        return self._decline is not None
+
+    async def decline(self, reason: str) -> None:
+        """Send this brief back: not work this agent does, and here is why.
+
+        Ends the handoff as `declined` — a terminal state that is neither
+        success nor failure. The kernel records the reason, tells the person, and
+        makes it visible to the sender through `status`. Declining in prose alone
+        would settle the handoff as `done`, which is the sender being told the
+        work happened.
+        """
+        if self._decline is None:
+            raise ValueError("nothing to decline: this run is not a handed-over task")
+        await self._decline(reason)
+
+
+_Call = Callable[[str, dict[str, Any]], Awaitable[dict[str, Any]]]
+
+
+class MemoryHandle:
+    """What this agent remembers about the person it acts for, via `ctx.memory`:
+    facts and standing rules that change how it helps, one sentence under a key.
+    Kept by the kernel per (agent, person), shown to the person in their settings.
+
+    Every method acts for the principal this context was built for; there is no
+    argument that names another, and no agent can read another agent's memory.
+    Returns plain dicts; a mistake the caller can fix raises `ValueError`. None
+    for system principals."""
+
+    def __init__(self, call: _Call) -> None:
+        self._call = call
+
+    async def list(self) -> dict[str, Any]:
+        return await self._call("list", {})
+
+    async def recall(self, query: str) -> dict[str, Any]:
+        return await self._call("recall", {"query": query})
+
+    async def save(self, key: str, content: str) -> dict[str, Any]:
+        """Save or overwrite the memory under `key`."""
+        return await self._call("save", {"key": key, "content": content})
+
+    async def forget(self, key: str) -> dict[str, Any]:
+        return await self._call("forget", {"key": key})
+
+    async def history(self, id: str | None = None, *, limit: int = 30) -> dict[str, Any]:
+        return await self._call("history", {"id": id, "limit": limit})
+
+    async def undo(self, change_id: str) -> dict[str, Any]:
+        return await self._call("undo", {"change_id": change_id})
+
+
+class TodoHandle:
+    """The person's to-dos with this agent, via `ctx.todos`: a title, a note, an
+    optional `due` date (2026-09-25) with `due_time` (18:30), `remind` and
+    `repeat` (daily/weekly/monthly/yearly), done or not, and optionally the
+    `item_id` it is about with `on_done={label, value}` written to that item when
+    it is finished. The person sees and edits them. Same rules as `MemoryHandle`."""
+
+    def __init__(self, call: _Call) -> None:
+        self._call = call
+
+    async def list(self, status: str = "open", query: str = "") -> dict[str, Any]:
+        """`status`: open, done or all."""
+        return await self._call("list", {"status": status, "query": query})
+
+    async def add(self, title: str, **fields: Any) -> dict[str, Any]:
+        return await self._call("add", {"title": title, **fields})
+
+    async def update(self, id: str, **changes: Any) -> dict[str, Any]:
+        return await self._call("update", {"id": id, **changes})
+
+    async def done(self, id: str, done: bool = True) -> dict[str, Any]:
+        return await self._call("done", {"id": id, "done": done})
+
+    async def delete(self, id: str) -> dict[str, Any]:
+        return await self._call("delete", {"id": id})
+
+    async def history(self, id: str | None = None, *, limit: int = 30) -> dict[str, Any]:
+        return await self._call("history", {"id": id, "limit": limit})
+
+    async def undo(self, change_id: str) -> dict[str, Any]:
+        return await self._call("undo", {"change_id": change_id})
+
+
+class ItemHandle:
+    """What the person keeps with this agent to look up, via `ctx.items`: each item
+    a title, a free-text `category`, and ordered `fields` —
+    `[{label, value, kind}]` with kind text, longtext, date, secret, url, phone or
+    number (`remind: true` on a date reminds the person). No schema to declare.
+    `update` merges fields by label, `remove` drops labels, and `note` adds a line
+    of what was done to the item's history. Same rules as `MemoryHandle`."""
+
+    def __init__(self, call: _Call) -> None:
+        self._call = call
+
+    async def list(self, category: str = "", query: str = "") -> dict[str, Any]:
+        return await self._call("list", {"category": category, "query": query})
+
+    async def counts(self, category: str = "", query: str = "") -> dict[str, Any]:
+        """How many items match, in all and per category — exact, unlike a list,
+        which stops at 500."""
+        return await self._call("counts", {"category": category, "query": query})
+
+    async def get(self, id: str) -> dict[str, Any]:
+        return await self._call("get", {"id": id})
+
+    async def save(
+        self, title: str, category: str = "", fields: Any = None, note: str = ""
+    ) -> dict[str, Any]:
+        return await self._call(
+            "save", {"title": title, "category": category, "fields": fields or [], "note": note}
+        )
+
+    async def update(self, id: str, **changes: Any) -> dict[str, Any]:
+        return await self._call("update", {"id": id, **changes})
+
+    async def delete(self, id: str) -> dict[str, Any]:
+        return await self._call("delete", {"id": id})
+
+    async def history(self, id: str | None = None, *, limit: int = 30) -> dict[str, Any]:
+        return await self._call("history", {"id": id, "limit": limit})
+
+    async def undo(self, change_id: str) -> dict[str, Any]:
+        return await self._call("undo", {"change_id": change_id})
+
+
+class SharesHandle:
+    """The shares of this agent that the person it acts for takes part in, via
+    `ctx.shares`. None outside a person's principal.
+
+    - `list()` — each share: `{id, kind, title, ref, role, principal_ref,
+      unread, you, members: [{ref, name, role}]}`. Members are pseudonyms (`ref`)
+      stable for this agent; never kernel ids or addresses.
+    - `principal(share_id)` — the share's `principal_ref`: what your SQL writes
+      into `principal_id` to put a row in the share. Row-level security decides
+      whether the write is allowed (a viewer's is not); knowing it grants nothing.
+    - `activity(share_id, kind, ref="", summary=None)` — record what happened,
+      as the person this run acts for; every member sees it.
+    - `propose(kind=, title=, ref=, invite_emails=, announce=True)` — ask the
+      person's app to open its share panel with this filled in. Nothing is
+      shared until they confirm there. `announce=False` only checks it and
+      returns the proposal, for a caller that shows it itself."""
+
+    def __init__(
+        self,
+        list_fn: Callable[[], Awaitable[list[dict[str, Any]]]],
+        principal_fn: Callable[[str], Awaitable[str]],
+        activity_fn: Callable[[str, str, str, dict[str, Any]], Awaitable[int]],
+        propose_fn: Callable[[dict[str, Any], bool], Awaitable[dict[str, Any]]],
+    ) -> None:
+        self._list = list_fn
+        self._principal = principal_fn
+        self._activity = activity_fn
+        self._propose = propose_fn
+
+    async def list(self) -> list[dict[str, Any]]:
+        return await self._list()
+
+    async def principal(self, share_id: str) -> str:
+        return await self._principal(share_id)
+
+    async def activity(
+        self, share_id: str, kind: str, ref: str = "", summary: dict[str, Any] | None = None
+    ) -> int:
+        return await self._activity(share_id, kind, ref, summary or {})
+
+    async def propose(
+        self,
+        *,
+        kind: str = "thing",
+        title: str,
+        ref: str = "",
+        invite_emails: list[str] | None = None,
+        announce: bool = True,
+    ) -> dict[str, Any]:
+        return await self._propose(
+            {"kind": kind, "title": title, "ref": ref, "invite_emails": invite_emails or []},
+            announce,
+        )
+
+
+class AgentBuilderHandle:
+    """Narrow personal-Agent composition seam exposed via `ctx.agent_builder`.
+
+    It never accepts a raw manifest or source code: it takes a constrained spec,
+    checks it against the tools and capabilities that exist, and makes an
+    ordinary prompt-only agent from it.
+
+    The person has at most one **draft**: a spec not yet published, which they
+    can try as an agent and which their own builder edits too. `draft` reads it,
+    `save_draft` replaces it, `draft_presentation` reads or replaces how it
+    looks to them.
+    """
+
+    def __init__(
+        self,
+        catalog_fn: Callable[[], Awaitable[dict[str, Any]]],
+        preview_fn: Callable[[dict[str, Any]], Awaitable[dict[str, Any]]],
+        publish_fn: Callable[[dict[str, Any]], Awaitable[dict[str, Any]]],
+        list_fn: Callable[[], Awaitable[list[dict[str, Any]]]],
+        archive_fn: Callable[[str], Awaitable[None]],
+        draft_fn: Callable[[], Awaitable[dict[str, Any] | None]],
+        save_draft_fn: Callable[[dict[str, Any]], Awaitable[dict[str, Any]]],
+        draft_presentation_fn: Callable[[dict[str, Any] | None], Awaitable[dict[str, Any] | None]],
+    ) -> None:
+        self._catalog = catalog_fn
+        self._preview = preview_fn
+        self._publish = publish_fn
+        self._list = list_fn
+        self._archive = archive_fn
+        self._draft = draft_fn
+        self._save_draft = save_draft_fn
+        self._draft_presentation = draft_presentation_fn
+
+    async def catalog(self) -> dict[str, Any]:
+        return await self._catalog()
+
+    async def preview(self, spec: dict[str, Any]) -> dict[str, Any]:
+        return await self._preview(spec)
+
+    async def publish(self, spec: dict[str, Any]) -> dict[str, Any]:
+        return await self._publish(spec)
+
+    async def list(self) -> list[dict[str, Any]]:
+        return await self._list()
+
+    async def archive(self, agent_id: str) -> None:
+        await self._archive(agent_id)
+
+    async def draft(self) -> dict[str, Any] | None:
+        """The person's draft: `{spec, edits, presentation}`, or None when they
+        have none. `spec` is as it was last saved, its page markup included;
+        `edits` is the id of the published agent it is an edit of, or None for a
+        new one."""
+        return await self._draft()
+
+    async def save_draft(self, spec: dict[str, Any]) -> dict[str, Any]:
+        """Make `spec` the person's draft, replacing the one they had. Validated
+        and composed as `preview` does — and refused the same way — and returns
+        the same summary. Nothing is published."""
+        return await self._save_draft(spec)
+
+    async def draft_presentation(
+        self, value: dict[str, Any] | None = None
+    ) -> dict[str, Any] | None:
+        """How the draft looks to the person, in the distribution's own terms.
+        With `value`, replace it whole (there has to be a draft); either way
+        returns what is stored now, None for none."""
+        return await self._draft_presentation(value)
+
+
+class StandingHandle:
+    """What this agent has arranged for the person, via `ctx.device.standing`,
+    keyed by the agent's own `item_key` — putting the same item again changes
+    nothing.
+
+    An `alert` (a reminder at a time) is kept by the kernel: every phone of the
+    person installs it and rings on its own, and the kernel pushes it when no
+    phone did. It needs no device and can be put from anywhere.
+
+    A `location`, `alarm`, `live_activity` or `glance` item is set ON THE DEVICE
+    THE PERSON IS USING and confirmed by it before `put` returns. Called from
+    anything that is not such a device — a schedule, an event, a browser — it
+    raises `ValueError` with `code` `device.no_device` or `device.unsupported`.
+
+    A mistake the caller can fix raises `ValueError`; a permission the person
+    has not given raises one too, whose `code` is `capability_needs_approval`
+    (nobody has decided) or `capability_denied`, and whose `capability` is the
+    permission to ask them for."""
+
+    def __init__(
+        self,
+        put: Callable[[dict[str, Any]], Awaitable[dict[str, Any]]],
+        delete: Callable[[str, str | None, str | None], Awaitable[dict[str, Any]]],
+        list_: Callable[[], Awaitable[dict[str, Any]]],
+    ) -> None:
+        self._put = put
+        self._delete = delete
+        self._list = list_
+
+    async def put(
+        self,
+        item_key: str,
+        kind: str,
+        spec: dict[str, Any],
+        *,
+        level: str | None = None,
+        actions: list[dict[str, Any]] | None = None,
+        to: str | None = None,
+        share: str | None = None,
+    ) -> dict[str, Any]:
+        """`kind`: alert, location, alarm, live_activity or glance. Returns
+        `{ok, item_key, level, downgraded, changed}`, and for every kind but
+        `alert` also `installed` (whether the device confirmed it) with
+        `reason` when it did not. `to` (a participant ref) with `share` puts an
+        ALERT on that participant's phones instead, on their own permissions."""
+        body: dict[str, Any] = {"item_key": item_key, "kind": kind, "spec": spec}
+        if to is not None or share is not None:
+            body["to"], body["share"] = to, share
+        if level is not None:
+            body["level"] = level
+        if actions is not None:
+            body["actions"] = actions
+        return await self._put(body)
+
+    async def delete(
+        self, item_key: str, *, to: str | None = None, share: str | None = None
+    ) -> dict[str, Any]:
+        """Take the item back from every device it is on. Works from anywhere."""
+        return await self._delete(item_key, to, share)
+
+    async def list(self) -> dict[str, Any]:
+        """`{items: [{item_key, kind, spec, level, actions, updated_at, here,
+        devices: [{device_id, state, reason?, at}]}]}`. `here` says whether the
+        item is on the device the person is using now."""
+        return await self._list()
+
+
+class DeviceHandle:
+    """The device the person is on, via `ctx.device`. None for a system
+    principal.
+
+    `call(op, args)` runs one operation on that device — read their calendar,
+    ask them to pick a photo, get where they are — through the kernel, which
+    checks the permission and waits up to 15 seconds. The device is the one
+    this request came from: the one the person's message was sent on, or the
+    one this agent's page is open on. The kernel reaches no other device of
+    theirs, and a request that came from none (a schedule, an event, a chat
+    channel, work handed over by another agent) reaches none.
+    It returns `{"ok": True, "result": …}` or `{"ok": False, "code", "message"}`
+    with `code` one of `device.no_device`, `device.unsupported` (this device
+    cannot), `device.unreachable`, `device.os_denied`, `device.declined`,
+    `device.not_own`, or `capability_needs_approval` / `capability_denied`. The
+    ops and their arguments are listed in the SDK reference."""
+
+    def __init__(
+        self,
+        call: Callable[[str, dict[str, Any]], Awaitable[dict[str, Any]]],
+        standing: StandingHandle,
+    ) -> None:
+        self._call = call
+        self.standing = standing
+
+    async def call(self, op: str, args: dict[str, Any] | None = None) -> dict[str, Any]:
+        return await self._call(op, args or {})
+
+
+class ToolContext:
+    """Injected by the kernel; the only surface a tool author should touch."""
+
+    def __init__(
+        self,
+        principal: Principal,
+        state_factory: Callable[[str], Awaitable[_StateHandle]],
+        capability: CapabilityHandle,
+        channel: ChannelHandle,
+        budget: BudgetHandle,
+        now_fn: Callable[[], datetime],
+        config: dict[str, Any],
+        principal_config: dict[str, Any],
+        ask: AskFn | None = None,
+        session: SessionHandle | None = None,
+        schedule: ScheduleHandle | None = None,
+        dispatch: DispatchHandle | None = None,
+        attachment: AttachmentFn | None = None,
+        embedding: EmbeddingHandle | None = None,
+        agent_builder: AgentBuilderHandle | None = None,
+        memory: MemoryHandle | None = None,
+        todos: TodoHandle | None = None,
+        items: ItemHandle | None = None,
+        is_admin: AdminFn | None = None,
+        workspace: Path | None = None,
+        shares: SharesHandle | None = None,
+        notify: NotifyFn | None = None,
+        device: DeviceHandle | None = None,
+    ) -> None:
+        self.principal = principal
+        self._state_factory = state_factory
+        self.capability = capability
+        self.channel = channel
+        self.budget = budget
+        #: Deferred/recurring self-scheduling; None inside an autonomous fire.
+        self.schedule = schedule
+        #: None when this run may not hand work to a peer. See `DispatchHandle`.
+        self.dispatch = dispatch
+        self._now = now_fn
+        self._config = config
+        self._principal_config = principal_config
+        self._ask = ask
+        #: Ephemeral per-session scratch state (todo/goal); None outside a run.
+        self.session = session
+        #: Where this run may put files (None outside a run). The built-in file
+        #: tools (`system.fs.read`, `system.doc.inspect`) read the same
+        #: directory, so a file left here can be handed to them. Give the model
+        #: the path RELATIVE to this directory, never the absolute one. Scratch,
+        #: not storage: files untouched for a day are deleted, and anything that
+        #: must last belongs in the agent's own state.
+        self.workspace = workspace
+        self._attachment = attachment
+        self.embedding = embedding or EmbeddingHandle(None)
+        #: Conversational prompt-only agent composition. None for system
+        #: principals; tool inventory/capabilities decide who can call it.
+        self.agent_builder = agent_builder
+        #: What is kept for the person with this agent (memory, to-dos, items).
+        #: None for system principals.
+        self.memory = memory
+        self.todos = todos
+        self.items = items
+        #: The shares of this agent its person takes part in (`SharesHandle`).
+        #: None outside a person's principal (a share's, the system's).
+        self.shares = shares
+        #: The device the person is on. None for system principals.
+        self.device = device
+        self._is_admin = is_admin
+        self._notify = notify
+
+    async def notify(
+        self,
+        text: str,
+        *,
+        title: str | None = None,
+        key: str | None = None,
+        level: str | None = None,
+        actions: list[dict[str, Any]] | None = None,
+        share: str | None = None,
+        to: str | None = None,
+        category: str | None = None,
+    ) -> dict[str, Any]:
+        """Tell a person something, now, with no model turn — what a federated
+        backend does with `POST /api/agent/notify`.
+
+        To this principal's person by default; with `to` (a participant `ref`)
+        and `share` (a share this principal belongs to), to that participant,
+        through their own principal and under their own permission. `level`:
+        `passive` | `active` (default) | `time_sensitive` (lowered to `active`
+        unless the person allowed `device.notify.urgent`; the receipt then says
+        `level_requested`). `actions` `[{id, label, destructive?, foreground?,
+        input?}]` come back as `notice.action` events, so they need a
+        `provides.events` handler that hears that kind; phones, browsers and
+        the web conversation show them, chat apps get the text only. `key` makes a retry
+        within a day a no-op; `category` is what a share participant can turn
+        off.
+
+        Returns the receipt `{ok: true, status, level, …}`, or `{ok: false,
+        code, message}` when refused (for example `notify.not_allowed`: the
+        person has not allowed this agent `person.notify`). Never raises for a
+        refusal."""
+        if self._notify is None:
+            return {
+                "ok": False,
+                "code": "notify.unavailable",
+                "message": "nobody to notify from here",
+            }
+        body: dict[str, Any] = {"text": text}
+        for name, value in (
+            ("title", title),
+            ("key", key),
+            ("level", level),
+            ("actions", actions),
+            ("share", share),
+            ("to", to),
+            ("category", category),
+        ):
+            if value is not None:
+                body[name] = value
+        return await self._notify(body)
+
+    async def state(self, namespace_id: str) -> _StateHandle:
+        return await self._state_factory(namespace_id)
+
+    async def attachment(self, attachment_id: str) -> InboundAttachment | None:
+        """Fetch one of the caller's own attachments by id (bytes + media_type +
+        filename), or None when none of the caller's attachments has that id."""
+        if self._attachment is None:
+            return None
+        return await self._attachment(attachment_id)
+
+    async def ask(
+        self,
+        question: str,
+        choices: list[str] | None = None,
+        fields: list[dict[str, Any]] | None = None,
+    ) -> AskReply | None:
+        """Ask the user something and wait for the reply over the run's
+        interactive channel.
+
+        `question` + `choices` is the universal form: one sentence and a flat list
+        of suggested answers. Every surface can render it — a chat channel, a log
+        line, a client written before any of this was structured.
+
+        `fields` is the SAME question drawn as a form, for a surface that can draw
+        one. Each entry is ``{key, label, options, multiple, placeholder}`` (the
+        same field shape as a `form` block). It must always be a faithful elaboration of
+        `question`, never extra content — a surface that cannot draw a form
+        ignores it, and the user still has to be asked the whole thing.
+
+        Returns an `AskReply`, or None when the run has no back-channel to reach
+        the user (e.g. a cron/batch fire) or the wait times out — callers must
+        handle None."""
+        if self._ask is None:
+            return None
+        return await self._ask(question, choices, fields)
+
+    async def is_admin(self) -> bool | None:
+        """Whether the person behind this call is one of the deployment's
+        administrators.
+
+        ``True``   a person, an administrator.
+        ``False``  a person, not an administrator.
+        ``None``   no person behind this call (a scheduled job, a system
+                   principal), or the deployment cannot say.
+
+        A fact about a person, not a permission: it authorizes nothing and
+        unlocks no tool. Use it to show someone the page that matches their
+        role; every write behind that page still needs its ordinary capability.
+
+        Each call is recorded on the run, so the person can see that an agent
+        asked.
+        """
+        if self._is_admin is None:
+            return None
+        return await self._is_admin()
+
+    def now(self) -> datetime:
+        return self._now()
+
+    def config(self, key: str, default: Any = None) -> Any:
+        return self._config.get(key, default)
+
+    def principal_config(self, key: str, default: Any = None) -> Any:
+        return self._principal_config.get(key, default)

aipelago_sdk-0.6.1/aipelago/sdk/decorator.py

@@ -0,0 +1,60 @@
+"""`@tool` decorator — attaches metadata so the kernel can find the handler.
+
+The manifest names the handler by Python ref; this decorator only adds a marker
+attribute. The actual schema is declared in `manifest.yaml`. We deliberately
+don't infer the schema from Python signatures — schema is a manifest concern.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Awaitable, Callable
+from functools import wraps
+from typing import Any
+
+from aipelago.sdk.context import ToolContext
+
+ToolHandler = Callable[[ToolContext, dict[str, Any]], Awaitable[dict[str, Any] | Any]]
+
+
+def tool(
+    tool_id: str,
+    *,
+    side_effects: str = "read-only",
+    idempotency: str = "unsafe",
+    input_schema: dict[str, Any] | None = None,
+    reaches: str | None = None,
+    parallelizable: bool = False,
+    capability: str | None = None,
+) -> Callable[[ToolHandler], ToolHandler]:
+    """Mark a coroutine as the handler for a tool.
+
+    In an agent, `manifest.yaml` is the source of truth for everything about a
+    tool, so only `tool_id` matters here and the other arguments are ignored.
+    They describe the kernel's own built-in tools, which have no manifest:
+
+    * `side_effects` — `read-only` or not; it decides the sandbox a call runs in.
+    * `input_schema` — JSON Schema for the arguments, shown to the model and
+      checked before the call.
+    * `reaches` — the argument holding the host the tool talks to, when it is
+      not `url`, so the person can be asked about that host.
+    * `parallelizable` — two calls in one turn may run together (read-only
+      tools only).
+    * `capability` — the permission every call needs, decided (asking the
+      person when it is theirs to give) before the handler runs.
+    """
+
+    def deco(fn: ToolHandler) -> ToolHandler:
+        @wraps(fn)
+        async def wrapped(ctx: ToolContext, args: dict[str, Any]) -> Any:
+            return await fn(ctx, args)
+
+        wrapped.__aipelago_tool_id__ = tool_id  # type: ignore[attr-defined]
+        wrapped.__aipelago_side_effects__ = side_effects  # type: ignore[attr-defined]
+        wrapped.__aipelago_idempotency__ = idempotency  # type: ignore[attr-defined]
+        wrapped.__aipelago_input_schema__ = input_schema  # type: ignore[attr-defined]
+        wrapped.__aipelago_reaches__ = reaches  # type: ignore[attr-defined]
+        wrapped.__aipelago_parallelizable__ = parallelizable  # type: ignore[attr-defined]
+        wrapped.__aipelago_capability__ = capability  # type: ignore[attr-defined]
+        return wrapped
+
+    return deco

aipelago_sdk-0.6.1/aipelago/sdk/hook.py

@@ -0,0 +1,81 @@
+"""Lifecycle hooks: the `@hook` decorator and the `HookDecision` a handler returns.
+
+`@hook` mirrors `@tool`: the manifest declares the hook (event + handler ref +
+matcher); this decorator only marks the handler. A handler receives the event
+payload dict and returns a `HookDecision` (or None = allow).
+
+    from aipelago.sdk import hook, HookDecision
+
+    @hook("pre_tool_use")
+    async def block_secrets(payload: dict) -> HookDecision | None:
+        if "secret" in str(payload.get("args", {})):
+            return HookDecision(decision="deny", reason="no secrets in args")
+        return None
+"""
+
+from __future__ import annotations
+
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass
+from functools import wraps
+from typing import Any
+
+
+@dataclass(frozen=True)
+class HookDecision:
+    """A hook's verdict. A handler returns this (or None = allow); an external
+    command prints it as JSON on stdout. Which fields count depends on the event:
+    ``args`` on pre_tool_use, ``text`` on user_prompt_submit, ``output`` on
+    post_tool_use; ``steer`` is guidance the model sees, on deny too, on the
+    events that accept it. Events that only observe ignore every field."""
+
+    decision: str = "allow"  # "allow" | "deny"
+    reason: str | None = None
+    args: dict[str, Any] | None = None
+    text: str | None = None
+    output: Any | None = None
+    steer: str | None = None
+
+    @property
+    def is_deny(self) -> bool:
+        return self.decision == "deny"
+
+    @classmethod
+    def allow(cls) -> HookDecision:
+        return cls()
+
+    @classmethod
+    def from_payload(cls, raw: Any) -> HookDecision:
+        """Parse a hook's raw output (e.g. JSON from an external command) into a
+        decision. Anything that is not a dict reads as allow."""
+        if not isinstance(raw, dict):
+            return cls.allow()
+        decision = "deny" if str(raw.get("decision", "allow")).lower() == "deny" else "allow"
+        args = raw.get("args")
+        text = raw.get("text")
+        steer = raw.get("steer")
+        return cls(
+            decision=decision,
+            reason=raw.get("reason"),
+            args=args if isinstance(args, dict) else None,
+            text=str(text) if text is not None else None,
+            output=raw.get("output"),
+            steer=str(steer) if steer is not None else None,
+        )
+
+
+HookHandler = Callable[[dict[str, Any]], Awaitable["HookDecision | None"]]
+
+
+def hook(event: str) -> Callable[[HookHandler], HookHandler]:
+    """Mark a coroutine as the handler for a manifest-declared lifecycle hook."""
+
+    def deco(fn: HookHandler) -> HookHandler:
+        @wraps(fn)
+        async def wrapped(payload: dict[str, Any]) -> Any:
+            return await fn(payload)
+
+        wrapped.__aipelago_hook_event__ = event  # type: ignore[attr-defined]
+        return wrapped
+
+    return deco

aipelago_sdk-0.6.1/aipelago/sdk/principal.py

@@ -0,0 +1,66 @@
+"""`Principal`: whom a call is made for — `(owner, agent)`, the owner a person or
+a share. A tool handler reads it as `ctx.principal`.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+from enum import StrEnum
+from fnmatch import fnmatchcase
+from uuid import UUID
+
+from pydantic import BaseModel, ConfigDict
+
+
+class PrincipalStatus(StrEnum):
+    active = "active"
+    suspended = "suspended"
+    removed = "removed"
+
+
+class Principal(BaseModel):
+    """An `(owner, agent)` row. The unit of state/capability/budget partitioning.
+
+    Exactly one of three shapes: a person's (`user_id`), a share's (`share_id` —
+    a thing or a conversation several people use together, which owns its own
+    rows), or the deployment's own identity for the agent (neither)."""
+
+    model_config = ConfigDict(frozen=True)
+
+    principal_id: UUID
+    user_id: UUID | None
+    agent_id: str
+    activated_at: datetime
+    status: PrincipalStatus
+    #: When the call came with a token limited to some of the agent's
+    #: capabilities, the patterns it is limited to; None = no such limit. It
+    #: only ever narrows what the agent was granted.
+    capability_scope: frozenset[str] | None = None
+    #: When the person arrived from your own product, signed in there, their id
+    #: in your product; tokens minted for your backend carry it as `sub`. None
+    #: otherwise.
+    native_sub: str | None = None
+    #: The share this principal is the owner-of-rows for; None for a person's
+    #: or the system's.
+    share_id: UUID | None = None
+    #: The person's device this request came from — the one their message was
+    #: sent on, or the one the agent's page is open on. The only device
+    #: `ctx.device` reaches for this request; None for anything that did not
+    #: come from one (a schedule, an event, a chat channel, handed-over work).
+    device_id: UUID | None = None
+
+    @property
+    def is_system(self) -> bool:
+        """System principals have no owner — driven only by cron/event triggers."""
+        return self.user_id is None and self.share_id is None
+
+    @property
+    def is_share(self) -> bool:
+        """A share's principal: its rows are the shared thing's, and whoever
+        acts on it is a participant, not its owner."""
+        return self.share_id is not None
+
+    def scope_permits(self, capability_id: str) -> bool:
+        if self.capability_scope is None:
+            return True
+        return any(fnmatchcase(capability_id, g) for g in self.capability_scope)

aipelago_sdk-0.6.1/pyproject.toml

@@ -0,0 +1,22 @@
+# Ships `aipelago/sdk/` and NOT `aipelago/__init__.py`, so `aipelago` is a
+# namespace package here and never shadows the kernel's own package.
+[project]
+name = "aipelago-sdk"
+version = "0.6.1"
+description = "The SDK agents are written against: @tool, @hook and the ToolContext a handler receives."
+readme = "README.md"
+requires-python = ">=3.11"
+license = "Apache-2.0"
+license-files = ["LICENSE"]
+authors = [{ name = "Jiaan Liu", email = "jiaanliux@gmail.com" }]
+dependencies = ["pydantic==2.12.0"]
+
+[build-system]
+requires = ["hatchling==1.27.0"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.sdist]
+only-include = ["aipelago", "README.md", "LICENSE"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["aipelago"]