Add attachment support to chat and send_message APIs

Author: bojieli

.github/workflows/ci.yml

@@ -0,0 +1,39 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  workflow_call:
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install build tools
+        run: pip install build twine
+
+      - name: Install package
+        run: pip install .
+
+      - name: Verify import
+        run: python -c "from pine_ai import PineAI, AsyncPineAI, __version__; print(f'pine-ai {__version__} OK')"
+
+      - name: Build distribution
+        run: python -m build
+
+      - name: Check distribution
+        run: twine check dist/*

.github/workflows/publish.yml

@@ -0,0 +1,31 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  ci:
+    uses: ./.github/workflows/ci.yml
+
+  publish:
+    needs: ci
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build tools
+        run: pip install build
+
+      - name: Build distribution
+        run: python -m build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

README.md

@@ -36,6 +36,33 @@ pine sessions list                       # List sessions
 pine task start <session-id>             # Start task (Pro)
 ```
 
+## Handling Events
+
+Pine AI behaves like a human assistant. After you send a message, it sends
+acknowledgments, then work logs, then the real response (form, text, or task_ready).
+**Don't respond to acknowledgments** — only respond to forms, specific questions,
+and task lifecycle events, or you'll create an infinite loop.
+
+## Continuing Existing Sessions
+
+```python
+# List all sessions
+result = await client.sessions.list(limit=20)
+
+# Continue an existing session
+await client.join_session(existing_session_id)
+history = await client.get_history(existing_session_id)
+async for event in client.chat(existing_session_id, "What is the status?"):
+    ...
+```
+
+## Attachments
+
+```python
+# Upload a document for dispute tasks
+attachments = await client.sessions.upload_attachment("bill.pdf")
+```
+
 ## Stream Buffering
 
 Text streaming is buffered internally. You receive one merged text event,

RELEASING.md

@@ -0,0 +1,32 @@
+# Releasing pine-ai (Python)
+
+This package uses **PyPI trusted publishing** (OIDC) — no PyPI tokens are stored in GitHub.
+
+## One-time setup
+
+### Register the trusted publisher on PyPI
+
+1. Go to <https://pypi.org/manage/project/pine-ai/settings/publishing/> (or add a **pending publisher** at <https://pypi.org/manage/account/publishing/> if the project doesn't exist on PyPI yet).
+2. Under **Add a new publisher**, fill in:
+   - **Owner:** `RunVid`
+   - **Repository:** `pine-python`
+   - **Workflow name:** `publish.yml`
+3. Save.
+
+## CI
+
+CI runs automatically on every push to `main` and on pull requests.
+It installs, imports, builds, and verifies the package across Python 3.10 – 3.13.
+
+## Publishing a new version
+
+1. Bump the version in **both** places:
+   - `pyproject.toml` → `version = "X.Y.Z"`
+   - `src/pine_ai/__init__.py` → `__version__ = "X.Y.Z"`
+2. Commit, tag, and push:
+   ```bash
+   git add -A && git commit -m "release: vX.Y.Z"
+   git tag vX.Y.Z
+   git push && git push --tags
+   ```
+3. The `publish.yml` workflow triggers on the `v*` tag, runs CI first, then publishes to PyPI.

src/pine_ai/chat.py

@@ -8,24 +8,24 @@
 """
 
 import asyncio
-from typing import Any, AsyncGenerator, Optional
+import time
+from typing import Any, AsyncGenerator, Callable, Coroutine, Optional
 
 from pine_ai.models.events import C2SEvent, S2CEvent
 from pine_ai.transport.socketio import SocketIOManager
 
-# Immediate-dispatch event types (Tier 2)
-IMMEDIATE_EVENTS = {
-    S2CEvent.SESSION_STATE, S2CEvent.SESSION_INPUT_STATE, S2CEvent.SESSION_RICH_CONTENT,
-    S2CEvent.SESSION_FORM_TO_USER,
-    S2CEvent.SESSION_ASK_FOR_LOCATION, S2CEvent.SESSION_LOCATION_SELECTION,
-    S2CEvent.SESSION_REWARD, S2CEvent.SESSION_PAYMENT, S2CEvent.SESSION_TASK_READY,
+TERMINAL_STATES = {"task_finished", "task_cancelled", "task_stale"}
+DEFAULT_IDLE_TIMEOUT_S = 120.0
+
+# Events that are buffered/debounced — NOT dispatched immediately
+BUFFERED_EVENTS = {S2CEvent.SESSION_TEXT_PART, S2CEvent.SESSION_WORK_LOG_PART}
+
+# Substantive response events — track for waiting_input termination gating
+SUBSTANTIVE_EVENTS = {
+    S2CEvent.SESSION_TEXT, S2CEvent.SESSION_FORM_TO_USER,
+    S2CEvent.SESSION_ASK_FOR_LOCATION, S2CEvent.SESSION_TASK_READY,
     S2CEvent.SESSION_TASK_FINISHED, S2CEvent.SESSION_INTERACTIVE_AUTH_CONFIRMATION,
-    S2CEvent.SESSION_THREE_WAY_CALL, S2CEvent.SESSION_ERROR, S2CEvent.SESSION_THINKING,
-    S2CEvent.SESSION_WORK_LOG, S2CEvent.SESSION_UPDATE_TITLE, S2CEvent.SESSION_TEXT,
-    S2CEvent.SESSION_MESSAGE_STATUS, S2CEvent.SESSION_CARD, S2CEvent.SESSION_NEXT_TASKS,
-    S2CEvent.SESSION_CONTINUE_IN_NEW_TASK, S2CEvent.SESSION_SOCIAL_SHARING,
-    S2CEvent.SESSION_RETRY, S2CEvent.SESSION_DEBUG, S2CEvent.SESSION_ACTION_STATUS,
-    S2CEvent.SESSION_COMPUTER_USE_INTERVENTION,
+    S2CEvent.SESSION_THREE_WAY_CALL, S2CEvent.SESSION_REWARD,
 }
 
 
@@ -62,8 +62,15 @@ def collect(self, message_id: str, content: str, final: bool) -> Optional[str]:
 
 
 class ChatEngine:
-    def __init__(self, sio: SocketIOManager):
+    def __init__(
+        self,
+        sio: SocketIOManager,
+        check_session_state: Optional[Callable[[str], Coroutine[Any, Any, dict[str, Any]]]] = None,
+        idle_timeout_s: float = DEFAULT_IDLE_TIMEOUT_S,
+    ):
         self._sio = sio
+        self._check_session_state = check_session_state
+        self._idle_timeout_s = idle_timeout_s
 
     async def join_session(self, session_id: str) -> dict[str, Any]:
         """Join a session room — spec 5.1.1.
@@ -80,7 +87,12 @@ def leave_session(self, session_id: str) -> None:
         self._sio.emit(C2SEvent.SESSION_LEAVE, None, session_id)
 
     async def chat(
-        self, session_id: str, content: str,
+        self,
+        session_id: str,
+        content: str,
+        *,
+        attachments: Optional[list[dict[str, Any]]] = None,
+        referenced_sessions: Optional[list[dict[str, str]]] = None,
     ) -> AsyncGenerator[ChatEvent, None]:
         """Send a message and yield events with stream buffering.
         Production handler reads payload.data as {content, attachments, ...}.
@@ -90,22 +102,51 @@ async def chat(
             C2SEvent.SESSION_MESSAGE,
             {
                 "content": content,
-                "attachments": [],
-                "referenced_sessions": [],
+                "attachments": attachments or [],
+                "referenced_sessions": referenced_sessions or [],
                 "client_now_date": datetime.now().isoformat(),
             },
             session_id,
         )
         async for event in self._listen(session_id):
             yield event
 
+    def send_message(
+        self,
+        session_id: str,
+        content: str,
+        *,
+        attachments: Optional[list[dict[str, Any]]] = None,
+        referenced_sessions: Optional[list[dict[str, str]]] = None,
+    ) -> None:
+        """Fire-and-forget message send (no event listening)."""
+        from datetime import datetime
+        self._sio.emit(
+            C2SEvent.SESSION_MESSAGE,
+            {
+                "content": content,
+                "attachments": attachments or [],
+                "referenced_sessions": referenced_sessions or [],
+                "client_now_date": datetime.now().isoformat(),
+            },
+            session_id,
+        )
+
     async def _listen(self, session_id: str) -> AsyncGenerator[ChatEvent, None]:
         """Listen for events with stream buffering."""
+        # Check session state before entering loop — don't hang on completed sessions
+        if self._check_session_state:
+            try:
+                session = await self._check_session_state(session_id)
+                if session.get("state") in TERMINAL_STATES:
+                    yield ChatEvent(type=S2CEvent.SESSION_STATE, session_id=session_id, data={"content": session["state"]})
+                    return
+            except Exception:
+                pass  # best effort
+
         text_buffer = TextPartBuffer()
         queue: asyncio.Queue[Optional[ChatEvent]] = asyncio.Queue()
         done = False
-        # Only terminate on waiting_input AFTER agent has sent substantive content.
-        # The initial waiting_input (default state) arrives before agent starts.
         received_agent_response = False
 
         # Work log debounce state
@@ -162,37 +203,41 @@ def handler(event: str, raw: dict[str, Any]) -> None:
                     wl_timers[step_id] = loop.call_later(3.0, flush_wl, step_id)
                 return
 
-            # Tier 2: immediate events
-            if event in IMMEDIATE_EVENTS:
-                nonlocal received_agent_response
-                queue.put_nowait(ChatEvent(
-                    type=event, session_id=session_id,
-                    message_id=message_id, data=data, metadata=metadata,
-                ))
-                # Track substantive agent responses
-                if event in (
-                    S2CEvent.SESSION_TEXT, S2CEvent.SESSION_FORM_TO_USER,
-                    S2CEvent.SESSION_ASK_FOR_LOCATION, S2CEvent.SESSION_TASK_READY,
-                    S2CEvent.SESSION_TASK_FINISHED, S2CEvent.SESSION_INTERACTIVE_AUTH_CONFIRMATION,
-                    S2CEvent.SESSION_THREE_WAY_CALL, S2CEvent.SESSION_REWARD,
-                ):
-                    received_agent_response = True
-                # Terminal conditions — only after agent has spoken
-                if event == S2CEvent.SESSION_INPUT_STATE and isinstance(data, dict):
-                    if data.get("content") == "waiting_input" and received_agent_response:
-                        done = True
-                        queue.put_nowait(None)
-                if event == S2CEvent.SESSION_STATE and isinstance(data, dict):
-                    state = data.get("content", "")
-                    if state in ("task_finished", "task_cancelled", "task_stale"):
-                        done = True
-                        queue.put_nowait(None)
+            # All other events: dispatch immediately (pass-through for agent)
+            nonlocal received_agent_response
+            queue.put_nowait(ChatEvent(
+                type=event, session_id=session_id,
+                message_id=message_id, data=data, metadata=metadata,
+            ))
+            if event in SUBSTANTIVE_EVENTS:
+                received_agent_response = True
+            if event == S2CEvent.SESSION_INPUT_STATE and isinstance(data, dict):
+                if data.get("content") == "waiting_input" and received_agent_response:
+                    done = True
+                    queue.put_nowait(None)
+            if event == S2CEvent.SESSION_STATE and isinstance(data, dict):
+                state = data.get("content", "")
+                if state in TERMINAL_STATES:
+                    done = True
+                    queue.put_nowait(None)
 
         remove_handler = self._sio.add_event_handler(handler)
 
         try:
             while not done:
-                evt = await queue.get()
+                try:
+                    evt = await asyncio.wait_for(queue.get(), timeout=self._idle_timeout_s)
+                except asyncio.TimeoutError:
+                    # Idle timeout — check session state via REST
+                    if self._check_session_state:
+                        try:
+                            session = await self._check_session_state(session_id)
+                            if session.get("state") in TERMINAL_STATES:
+                                yield ChatEvent(type=S2CEvent.SESSION_STATE, session_id=session_id, data={"content": session["state"]})
+                                break
+                        except Exception:
+                            pass
+                    continue
                 if evt is None:
                     break
                 yield evt