aria-code 0.167.0__py3-none-win_amd64.whl

aria_bots/__init__.py

@@ -0,0 +1,7 @@
+"""Aria's chat bots: Feishu and Telegram adapters, the relay client, and the
+logistics tools they answer shipper questions with.
+
+This package runs as its own service (services/aria-bots). It does not import
+aria_code; aria_code keeps shims at the old module paths until the Python core
+is removed.
+"""

aria_bots/channels/README.md

@@ -0,0 +1,97 @@
+# Channel Apps
+
+Target role: adapters for non-terminal entrypoints.
+
+Examples:
+
+- relay server/client;
+- Feishu bot;
+- Telegram bot;
+- webhooks;
+- future desktop or browser UI.
+
+Each channel should translate inbound messages into gateway requests and render
+gateway responses back to the channel. It should not bypass safety, runtime, or
+artifact policies.
+
+## The conversation layer (`conversation.py`)
+
+Everything a chat bot decides that does not depend on the platform lives in
+one module, so every channel — Feishu today, Arthera's own bot later — gets
+the same rules from the same code:
+
+| Rule | Where |
+|------|-------|
+| In a group, answer only when addressed; in a direct chat, always | `should_respond` |
+| One group = one shipper (货主), bound by an admin with `/owner <id>` | `handle_owner_command`, `ConversationStore` |
+| Admins are per channel: `ARIA_CHANNEL_ADMINS=feishu:ou_x,telegram:42` | `is_admin` |
+| Context is the conversation's own recent messages, never another's; capped at 20 messages and 7 days | `ConversationStore.history` |
+| A bound conversation runs every turn with `ARIA_OWNER_SCOPE`, enforced by the logistics tools themselves | `ChannelTurn.env`, `aria_bots/logistics/tenancy.py` |
+
+A new channel is an adapter: turn the platform's event into an
+`InboundMessage`, then
+
+```python
+if not should_respond(msg):
+    return
+reply = handle_owner_command(msg, store)          # /owner commands
+if reply is None:
+    turn = prepare_turn(msg, store)               # context + shipper scope
+    reply = await run_model(turn.prompt, history=turn.history, env=turn.env)
+    store.record(msg.key, "assistant", reply)
+send(reply)
+```
+
+`aria_feishu_bot.feishu_inbound` is the Feishu version of that first step.
+Conversation keys are `<channel>:<conversation id>`, so the same chat id on
+two platforms is two conversations.
+
+## The shipper digest (`digest.py`)
+
+The first thing the conversation layer enables that a reply-only bot cannot:
+each group bound to a shipper is sent, unprompted, what needs attention —
+reorders, SKUs with too little history to plan, dead stock, waybills to query,
+and safe carrier switches. `run_digests(store, senders)` walks the bindings and
+hands each digest to that channel's sender, so a new channel registers a
+`(conversation_id, title, body) -> bool` function and gets the digest too.
+
+Data comes from the operator's `ARIA_SHIPPER_FEEDS` file, never from chat, and
+is read through the logistics tools under `ARIA_OWNER_SCOPE`, so a shared
+multi-shipper export yields only that shipper's lines. Configuration problems
+go to the log, not the client's group; a day with nothing to report sends
+nothing.
+
+## Approvals (`approvals.py`)
+
+Bot runs cannot use confirmation-required tools, so a bot that may only
+suggest still leaves someone retyping its suggestion. Approvals are the
+sanctioned way through: the bot stores exactly what it proposes, an
+authorised person presses approve or reject in the chat, and only then does
+the action run — once, under the shipper's scope, with who and when recorded.
+
+| Rule | Why |
+|------|-----|
+| Approvers per channel (`ARIA_CHANNEL_APPROVERS`, plus admins); none by default | fail closed |
+| Only in the conversation that raised it | a forwarded card cannot be approved elsewhere |
+| A single conditional UPDATE claims the request | two presses cannot both execute |
+| Expires after 24 h | stale numbers should be recomputed, not approved |
+| The conversation must still be bound to the same shipper | a rebound group cannot run the old client's action |
+| The payload is frozen at request time | what was approved is what runs |
+| Failures are recorded, not shown in the chat | exceptions can name host paths |
+
+A channel renders the request with two buttons and calls
+`ApprovalStore.decide`; actions are registered in `EXECUTORS`. The first,
+`purchase_order_draft`, writes a CSV to `ARIA_APPROVAL_OUTBOX/<shipper>/` for
+the 3PL's purchasing system: Aria has no integration that places orders, and
+does not pretend to.
+
+## Relay mode
+
+In relay mode the user's machine has no Feishu app credentials — the app
+secret stays on the relay — so `aria_feishu_bot._send_message` hands every
+message back over the relay WebSocket and the relay sends it. The relay
+accepts a send only where the client has standing: a reply to a message it
+forwarded to that client (within an hour), or a post to a chat that client's
+bound user has spoken to the bot in; text or cards, rate-limited. A press on a
+card is routed to the client that posted the card, which holds the approval.
+Attachments still need the app's credentials and are declined with a message.

aria_bots/channels/__init__.py

@@ -0,0 +1 @@
+"""Conversations, approval cards and shipper digests shared by the chat bots."""

aria_bots/channels/approvals.py

@@ -0,0 +1,263 @@
+"""Approvals: a bot may propose an action with consequences, a person decides.
+
+Bot runs cannot use confirmation-required tools, because nobody in a chat can
+answer a terminal prompt. That stops harm and also stops the useful half of
+the job — a reorder list someone still has to retype. This is the other way
+through: the bot writes down exactly what it proposes, an authorised person
+approves or rejects it in the chat, and only then does it happen, with a
+record of who decided what and when.
+
+Platform-neutral like the rest of apps/channels. A channel renders a request
+with approve/reject buttons and calls `decide` when one is pressed; the rules
+below hold whichever platform the button was on:
+
+  - Who may decide: ARIA_CHANNEL_APPROVERS, plus ARIA_CHANNEL_ADMINS, per
+    channel ("feishu:ou_x"). Nobody, when neither is set.
+  - Where: only in the conversation the request was raised in. A card
+    forwarded to another chat cannot be approved there.
+  - Once: the transition out of "pending" is a single conditional UPDATE, so
+    two clicks, or two approvers at the same moment, cannot both execute.
+  - Not late: a request expires after `ttl_seconds` (24 h).
+  - Not for someone else: the conversation must still be bound to the shipper
+    the request was made for, and the action runs under ARIA_OWNER_SCOPE.
+  - What was approved is what runs: the payload is frozen at request time and
+    executed as stored, never recomputed — the approver saw these lines.
+
+Actions are registered in EXECUTORS. The first, "purchase_order_draft", writes
+a CSV draft to an outbox directory (ARIA_APPROVAL_OUTBOX) for the 3PL's own
+purchasing system to pick up. Aria does not place orders: it has no
+integration that could, and pretending otherwise would be the wrong default.
+"""
+
+from __future__ import annotations
+
+import csv
+import json
+import os
+import secrets
+import sqlite3
+import time
+from contextlib import contextmanager
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Callable, Dict, Iterator, List, Optional, Tuple
+
+from aria_bots.channels.conversation import ADMINS_ENV, default_db_path
+from aria_bots.logistics.tenancy import OWNER_SCOPE_ENV
+
+APPROVERS_ENV = "ARIA_CHANNEL_APPROVERS"
+OUTBOX_ENV = "ARIA_APPROVAL_OUTBOX"
+
+PENDING, APPROVED, REJECTED, EXPIRED, FAILED = "pending", "approved", "rejected", "expired", "failed"
+
+
+def can_decide(channel: str, sender_ids: Tuple[str, ...], env: Optional[Dict[str, str]] = None) -> bool:
+    env = env if env is not None else os.environ
+    allowed = set()
+    for key in (APPROVERS_ENV, ADMINS_ENV):
+        allowed |= {item.strip() for item in env.get(key, "").split(",") if item.strip()}
+    return any(f"{channel}:{sid}" in allowed for sid in sender_ids if sid)
+
+
+@dataclass(frozen=True)
+class Approval:
+    id: str
+    conversation: str
+    owner_id: str
+    kind: str
+    payload: Dict[str, Any]
+    summary: str
+    requested_by: str
+    requested_at: float
+    status: str
+    decided_by: str = ""
+    decided_at: float = 0.0
+    result: str = ""
+
+
+@dataclass(frozen=True)
+class Decision:
+    ok: bool
+    message: str
+    approval: Optional[Approval] = None
+
+
+@contextmanager
+def _confined_to(owner_id: str) -> Iterator[None]:
+    previous = os.environ.get(OWNER_SCOPE_ENV)
+    os.environ[OWNER_SCOPE_ENV] = owner_id
+    try:
+        yield
+    finally:
+        if previous is None:
+            os.environ.pop(OWNER_SCOPE_ENV, None)
+        else:
+            os.environ[OWNER_SCOPE_ENV] = previous
+
+
+# ── Executors ────────────────────────────────────────────────────────────────
+
+def outbox_dir() -> Path:
+    configured = os.environ.get(OUTBOX_ENV, "").strip()
+    return Path(configured).expanduser() if configured else Path.home() / ".aria" / "outbox"
+
+
+def execute_purchase_order_draft(approval: Approval) -> str:
+    """Write the approved lines, exactly as approved, as a CSV draft."""
+    lines = approval.payload.get("lines") or []
+    if not lines:
+        raise ValueError("nothing to order")
+    folder = outbox_dir() / approval.owner_id
+    folder.mkdir(parents=True, exist_ok=True)
+    os.chmod(folder, 0o700)
+    stamp = time.strftime("%Y%m%d", time.localtime(approval.decided_at or time.time()))
+    path = folder / f"PO-{approval.owner_id}-{stamp}-{approval.id[:8]}.csv"
+    with path.open("x", newline="", encoding="utf-8") as handle:  # never overwrite a draft
+        writer = csv.writer(handle)
+        writer.writerow(["owner_id", "sku", "order_qty", "approval_id", "approved_by", "approved_at"])
+        decided = time.strftime("%Y-%m-%dT%H:%M:%S", time.localtime(approval.decided_at))
+        for line in lines:
+            writer.writerow([approval.owner_id, line["sku"], line["qty"], approval.id,
+                             approval.decided_by, decided])
+    return str(path)
+
+
+EXECUTORS: Dict[str, Callable[[Approval], str]] = {
+    "purchase_order_draft": execute_purchase_order_draft,
+}
+
+
+def propose_reorder(owner_id: str, inventory_path: str) -> Optional[Tuple[str, Dict[str, Any]]]:
+    """A purchase-order draft from the shipper's reorder list, or None if nothing to order."""
+    from aria_bots.logistics.inventory import tool_plan_inventory_policy
+
+    with _confined_to(owner_id):
+        result = tool_plan_inventory_policy({"file_path": inventory_path})
+    if not result.get("success"):
+        raise ValueError(result.get("error") or "inventory analysis failed")
+    lines = [{"sku": i["sku"], "qty": int(i["suggested_order_qty"])}
+             for i in result["data"]["items"]
+             if i.get("action") == "reorder" and i.get("suggested_order_qty")]
+    if not lines:
+        return None
+    summary = "\n".join(f"- {line['sku']}：{line['qty']}" for line in lines)
+    return summary, {"lines": lines}
+
+
+# ── Store ────────────────────────────────────────────────────────────────────
+
+class ApprovalStore:
+    """Requests and decisions, in the same SQLite file as the conversations."""
+
+    def __init__(self, path: Optional[Path | str] = None, *, ttl_seconds: float = 24 * 3600,
+                 clock: Callable[[], float] = time.time) -> None:
+        self.path = Path(path) if path else default_db_path()
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        self.ttl_seconds = float(ttl_seconds)
+        self._clock = clock
+        with self._db() as db:
+            db.execute(
+                """CREATE TABLE IF NOT EXISTS approvals (
+                    id TEXT PRIMARY KEY, conversation TEXT NOT NULL, owner_id TEXT NOT NULL,
+                    kind TEXT NOT NULL, payload TEXT NOT NULL, summary TEXT NOT NULL,
+                    requested_by TEXT NOT NULL, requested_at REAL NOT NULL,
+                    status TEXT NOT NULL, decided_by TEXT NOT NULL DEFAULT '',
+                    decided_at REAL NOT NULL DEFAULT 0, result TEXT NOT NULL DEFAULT '')"""
+            )
+        try:
+            os.chmod(self.path, 0o600)
+        except OSError:
+            pass
+
+    def _db(self) -> sqlite3.Connection:
+        return sqlite3.connect(str(self.path))
+
+    def request(self, *, conversation: str, owner_id: str, kind: str, payload: Dict[str, Any],
+                summary: str, requested_by: str) -> Approval:
+        if kind not in EXECUTORS:
+            raise ValueError(f"unknown action {kind!r}")
+        approval_id = secrets.token_urlsafe(12)  # unguessable: it travels in a card button
+        with self._db() as db:
+            db.execute(
+                "INSERT INTO approvals (id, conversation, owner_id, kind, payload, summary, "
+                "requested_by, requested_at, status) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)",
+                (approval_id, conversation, owner_id, kind, json.dumps(payload, ensure_ascii=False),
+                 summary, requested_by, self._clock(), PENDING),
+            )
+        return self.get(approval_id)  # type: ignore[return-value]
+
+    def get(self, approval_id: str) -> Optional[Approval]:
+        with self._db() as db:
+            row = db.execute(
+                "SELECT id, conversation, owner_id, kind, payload, summary, requested_by, requested_at, "
+                "status, decided_by, decided_at, result FROM approvals WHERE id = ?", (approval_id,)
+            ).fetchone()
+        if not row:
+            return None
+        values = list(row)
+        values[4] = json.loads(values[4])
+        return Approval(*values)
+
+    def recent(self, conversation: str, limit: int = 5) -> List[Approval]:
+        with self._db() as db:
+            ids = [r[0] for r in db.execute(
+                "SELECT id FROM approvals WHERE conversation = ? ORDER BY requested_at DESC LIMIT ?",
+                (conversation, limit))]
+        return [a for a in (self.get(i) for i in ids) if a]
+
+    def _transition(self, approval_id: str, status: str, by: str, result: str = "",
+                    expect: str = PENDING) -> bool:
+        with self._db() as db:
+            cursor = db.execute(
+                "UPDATE approvals SET status = ?, decided_by = ?, decided_at = ?, result = ? "
+                "WHERE id = ? AND status = ?",
+                (status, by, self._clock(), result, approval_id, expect),
+            )
+            return cursor.rowcount == 1
+
+    def decide(self, approval_id: str, *, conversation: str, current_owner: Optional[str],
+               decided_by: str, approve: bool, authorised: bool) -> Decision:
+        """Apply one approve/reject press. Every refusal says why, and changes nothing."""
+        approval = self.get(approval_id)
+        if approval is None or approval.conversation != conversation:
+            # The same answer for "no such request" and "not this chat's": a
+            # forwarded card learns nothing about where it came from.
+            return Decision(False, "找不到这条审批，或它不属于本会话。")
+        if not authorised:
+            return Decision(False, "你没有审批权限。", approval)
+        if approval.status != PENDING:
+            who = f"（{approval.decided_by}）" if approval.decided_by else ""
+            return Decision(False, f"这条审批已经是「{_STATUS_LABEL.get(approval.status, approval.status)}」{who}。", approval)
+        if self._clock() - approval.requested_at > self.ttl_seconds:
+            self._transition(approval_id, EXPIRED, "system")
+            return Decision(False, "这条审批已过期，请重新发起。", self.get(approval_id))
+        if current_owner != approval.owner_id:
+            return Decision(False, "本会话绑定的货主已变更，这条审批不能再执行。", approval)
+
+        if not approve:
+            if not self._transition(approval_id, REJECTED, decided_by):
+                return Decision(False, "这条审批刚刚已被处理。", self.get(approval_id))
+            return Decision(True, "已驳回。", self.get(approval_id))
+
+        # Claim it first; only the press that wins the claim executes.
+        if not self._transition(approval_id, APPROVED, decided_by, result="executing"):
+            return Decision(False, "这条审批刚刚已被处理。", self.get(approval_id))
+        claimed = self.get(approval_id)
+        try:
+            with _confined_to(approval.owner_id):
+                outcome = EXECUTORS[approval.kind](claimed)  # type: ignore[arg-type]
+        except Exception as exc:
+            # The reason is kept in the record for the operator; the chat only
+            # learns that it failed, since an exception can name host paths.
+            self._transition(approval_id, FAILED, decided_by, result=str(exc)[:500], expect=APPROVED)
+            return Decision(False, "已批准，但执行失败，原因已记录。", self.get(approval_id))
+        with self._db() as db:
+            db.execute("UPDATE approvals SET result = ? WHERE id = ?", (outcome, approval_id))
+        return Decision(True, "已批准并执行。", self.get(approval_id))
+
+
+_STATUS_LABEL = {PENDING: "待审批", APPROVED: "已批准", REJECTED: "已驳回", EXPIRED: "已过期", FAILED: "执行失败"}
+
+
+def status_label(status: str) -> str:
+    return _STATUS_LABEL.get(status, status)

aria_bots/channels/conversation.py

@@ -0,0 +1,280 @@
+"""The platform-neutral half of every chat channel.
+
+A chat bot does the same five things on any platform: decide whether a
+message is for it, know which client a conversation belongs to, remember what
+was just said there, keep each conversation's memory to itself, and hand the
+model a turn. Only parsing the platform's event and sending its reply differ.
+This module is the part that does not differ, so Feishu, Telegram, and a bot
+on Arthera's own app or website share one implementation of the rules that
+matter — and a new channel is an adapter of a few dozen lines:
+
+    msg = InboundMessage(channel="myapp", conversation_id=room_id, kind="group",
+                         sender_id=user_id, text=text, mentions_bot=True)
+    if not should_respond(msg):
+        return
+    turn = prepare_turn(msg, store)
+    reply = await run_my_model(turn.prompt, history=turn.history, env=turn.env)
+    store.record(msg.key, "assistant", reply)
+
+The guarantees, each tested in tests/test_conversation_core.py:
+
+  - In a group the bot answers only when addressed; in a direct chat, always.
+  - A conversation bound to a shipper (货主) runs every turn with
+    ARIA_OWNER_SCOPE set, which the logistics tools enforce themselves
+    (tools/logistics_tenancy.py) — the binding does not rely on the prompt.
+  - Only channel admins (ARIA_CHANNEL_ADMINS) can bind or unbind.
+  - History is per conversation and never crosses: the context for a turn is
+    built from that conversation's own messages and nothing else.
+  - History is bounded twice: the last `max_turns` messages, none older than
+    `ttl_seconds`. A chat bot that keeps every client message forever is a
+    liability, not a feature.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+import sqlite3
+import time
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Callable, Dict, List, Optional, Tuple
+
+from aria_bots.channels.registry import CHANNEL_TASK_SCHEMA
+from aria_bots.logistics.tenancy import OWNER_SCOPE_ENV
+
+ADMINS_ENV = "ARIA_CHANNEL_ADMINS"
+DB_ENV = "ARIA_CONVERSATIONS_DB"
+_OWNER_ID = re.compile(r"^[A-Za-z0-9][A-Za-z0-9_.\-]{0,63}$")
+
+
+@dataclass(frozen=True)
+class InboundMessage:
+    """One message, as any channel adapter normalises it."""
+
+    channel: str                 # "feishu", "telegram", "web", ...
+    conversation_id: str         # the chat / group / room on that channel
+    kind: str                    # "direct" or "group"
+    sender_id: str
+    text: str
+    message_id: str = ""
+    mentions_bot: bool = False
+    reply_to: str = ""           # the message this one answers, if any
+    sender_aliases: Tuple[str, ...] = ()   # other ids for the same person
+
+    @property
+    def key(self) -> str:
+        """Unique across channels: two platforms may reuse the same chat id."""
+        return f"{self.channel}:{self.conversation_id}"
+
+    @property
+    def sender_ids(self) -> Tuple[str, ...]:
+        return tuple(i for i in (self.sender_id, *self.sender_aliases) if i)
+
+
+def should_respond(msg: InboundMessage) -> bool:
+    """Direct chats always; groups only when the bot is addressed."""
+    if msg.kind == "direct":
+        return True
+    return bool(msg.mentions_bot)
+
+
+def is_admin(msg: InboundMessage, env: Optional[Dict[str, str]] = None) -> bool:
+    """ARIA_CHANNEL_ADMINS="feishu:ou_abc,telegram:12345" — per channel, fail closed."""
+    raw = (env if env is not None else os.environ).get(ADMINS_ENV, "")
+    admins = {item.strip() for item in raw.split(",") if item.strip()}
+    return any(f"{msg.channel}:{sid}" in admins for sid in msg.sender_ids)
+
+
+# ── Admin commands ───────────────────────────────────────────────────────────
+
+_OWNER_COMMAND = re.compile(r"^/(?:owner|货主)(?:\s+(\S+))?\s*$", re.IGNORECASE)
+_UNBIND_WORDS = {"off", "clear", "none", "解除", "取消"}
+
+
+def parse_owner_command(text: str) -> Optional[Tuple[str, str]]:
+    """'/owner' → show; '/owner ACME' → bind; '/owner off' → unbind. None otherwise."""
+    match = _OWNER_COMMAND.match((text or "").strip())
+    if not match:
+        return None
+    arg = (match.group(1) or "").strip()
+    if not arg:
+        return ("show", "")
+    if arg.lower() in _UNBIND_WORDS:
+        return ("unbind", "")
+    return ("bind", arg)
+
+
+def handle_owner_command(msg: InboundMessage, store: "ConversationStore",
+                         env: Optional[Dict[str, str]] = None) -> Optional[str]:
+    """Run an /owner command and return the reply text, or None if it is not one."""
+    command = parse_owner_command(msg.text)
+    if command is None:
+        return None
+    action, owner = command
+    current = store.owner_for(msg.key)
+    if action == "show":
+        return (f"本会话绑定的货主：{current}" if current
+                else "本会话未绑定货主。管理员可发送 /owner <货主ID> 绑定。")
+    if not is_admin(msg, env):
+        return "只有管理员可以修改本会话绑定的货主。"
+    if msg.kind != "group":
+        # A direct chat is one person, not a client; binding it would confine
+        # an operator's own chat to one shipper and surprise them later.
+        return "货主只能绑定到群聊：一个群对应一个货主。"
+    if action == "unbind":
+        store.unbind_owner(msg.key)
+        return "已解除本会话的货主绑定。"
+    if not _OWNER_ID.match(owner):
+        return "货主 ID 只能包含字母、数字、下划线、点和短横线，最长 64 个字符。"
+    store.bind_owner(msg.key, owner, bound_by=f"{msg.channel}:{msg.sender_id}")
+    return f"已绑定：本会话之后的分析只会使用货主 {owner} 的数据。"
+
+
+# ── Storage ──────────────────────────────────────────────────────────────────
+
+def default_db_path() -> Path:
+    configured = os.environ.get(DB_ENV, "").strip()
+    if configured:
+        return Path(configured).expanduser()
+    return Path.home() / ".aria" / "conversations.db"
+
+
+class ConversationStore:
+    """Owner bindings and bounded per-conversation history, in one SQLite file."""
+
+    def __init__(self, path: Optional[Path | str] = None, *, max_turns: int = 20,
+                 ttl_seconds: float = 7 * 86400, clock: Callable[[], float] = time.time) -> None:
+        self.path = Path(path) if path else default_db_path()
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        self.max_turns = max(1, int(max_turns))
+        self.ttl_seconds = float(ttl_seconds)
+        self._clock = clock
+        with self._db() as db:
+            db.executescript(
+                """
+                CREATE TABLE IF NOT EXISTS bindings (
+                    conversation TEXT PRIMARY KEY,
+                    owner_id     TEXT NOT NULL,
+                    bound_by     TEXT NOT NULL,
+                    bound_at     REAL NOT NULL
+                );
+                CREATE TABLE IF NOT EXISTS history (
+                    id           INTEGER PRIMARY KEY AUTOINCREMENT,
+                    conversation TEXT NOT NULL,
+                    role         TEXT NOT NULL,
+                    sender       TEXT NOT NULL DEFAULT '',
+                    content      TEXT NOT NULL,
+                    at           REAL NOT NULL
+                );
+                CREATE INDEX IF NOT EXISTS history_by_conversation ON history (conversation, id);
+                """
+            )
+        try:
+            os.chmod(self.path, 0o600)  # client messages: owner-readable only
+        except OSError:
+            pass
+
+    def _db(self) -> sqlite3.Connection:
+        return sqlite3.connect(str(self.path))
+
+    # bindings
+    def bind_owner(self, key: str, owner_id: str, *, bound_by: str) -> None:
+        with self._db() as db:
+            db.execute(
+                "INSERT INTO bindings (conversation, owner_id, bound_by, bound_at) VALUES (?, ?, ?, ?) "
+                "ON CONFLICT(conversation) DO UPDATE SET owner_id=excluded.owner_id, "
+                "bound_by=excluded.bound_by, bound_at=excluded.bound_at",
+                (key, owner_id, bound_by, self._clock()),
+            )
+
+    def unbind_owner(self, key: str) -> None:
+        with self._db() as db:
+            db.execute("DELETE FROM bindings WHERE conversation = ?", (key,))
+
+    def bindings(self) -> List[Tuple[str, str]]:
+        """Every (conversation key, shipper) binding, for jobs that push to them."""
+        with self._db() as db:
+            return [tuple(row) for row in db.execute(
+                "SELECT conversation, owner_id FROM bindings ORDER BY conversation")]
+
+    def owner_for(self, key: str) -> Optional[str]:
+        with self._db() as db:
+            row = db.execute("SELECT owner_id FROM bindings WHERE conversation = ?", (key,)).fetchone()
+        return row[0] if row else None
+
+    # history
+    def record(self, key: str, role: str, content: str, *, sender: str = "") -> None:
+        if role not in ("user", "assistant") or not (content or "").strip():
+            return
+        now = self._clock()
+        with self._db() as db:
+            db.execute("INSERT INTO history (conversation, role, sender, content, at) VALUES (?, ?, ?, ?, ?)",
+                       (key, role, sender, content, now))
+            self._prune(db, key, now)
+
+    def history(self, key: str) -> List[Dict[str, str]]:
+        """Oldest first, in the {role, content} shape model providers take."""
+        now = self._clock()
+        with self._db() as db:
+            self._prune(db, key, now)
+            rows = db.execute(
+                "SELECT role, content FROM history WHERE conversation = ? ORDER BY id", (key,)
+            ).fetchall()
+        return [{"role": role, "content": content} for role, content in rows]
+
+    def forget(self, key: str) -> None:
+        with self._db() as db:
+            db.execute("DELETE FROM history WHERE conversation = ?", (key,))
+
+    def _prune(self, db: sqlite3.Connection, key: str, now: float) -> None:
+        db.execute("DELETE FROM history WHERE conversation = ? AND at < ?", (key, now - self.ttl_seconds))
+        db.execute(
+            "DELETE FROM history WHERE conversation = ? AND id NOT IN "
+            "(SELECT id FROM history WHERE conversation = ? ORDER BY id DESC LIMIT ?)",
+            (key, key, self.max_turns),
+        )
+
+
+# ── Turns ────────────────────────────────────────────────────────────────────
+
+@dataclass(frozen=True)
+class ChannelTurn:
+    """Everything a model call needs for one message, platform-free."""
+
+    prompt: str
+    history: List[Dict[str, str]] = field(default_factory=list)
+    owner_scope: Optional[str] = None
+
+    @property
+    def env(self) -> Dict[str, str]:
+        """Environment for a subprocess running this turn's tools."""
+        return {OWNER_SCOPE_ENV: self.owner_scope} if self.owner_scope else {}
+
+    def as_task(self, msg: InboundMessage) -> Dict[str, object]:
+        """The same turn as a structured channel task (aria.channel_task.v1)."""
+        return {
+            "schema": CHANNEL_TASK_SCHEMA,
+            "channel": msg.channel,
+            "conversation": msg.key,
+            "message_id": msg.message_id,
+            "prompt": self.prompt,
+            "history": list(self.history),
+            "owner_scope": self.owner_scope,
+        }
+
+
+def prepare_turn(msg: InboundMessage, store: ConversationStore) -> ChannelTurn:
+    """Record the incoming message and build the turn that answers it.
+
+    History is read before this message is recorded, so the turn carries the
+    conversation so far plus the new prompt — not the prompt twice.
+    """
+    history = store.history(msg.key)
+    owner = store.owner_for(msg.key)
+    store.record(msg.key, "user", msg.text, sender=msg.sender_id)
+    prompt = msg.text
+    if owner:
+        prompt = (f"[本会话属于货主 {owner}。只分析该货主的数据，回答中不要提及其他货主。]\n"
+                  f"{msg.text}")
+    return ChannelTurn(prompt=prompt, history=history, owner_scope=owner)