From e3997dcedeaa08fcf4017e0786d119080049bf0d Mon Sep 17 00:00:00 2001 From: Arvin Hsu Date: Fri, 6 Nov 2026 16:50:37 +0000 Subject: [PATCH 1/4] docs: clarify task startup and account-specific guidance --- skills/pine/SKILL.md | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/skills/pine/SKILL.md b/skills/pine/SKILL.md index 471a892..9856048 100644 --- a/skills/pine/SKILL.md +++ b/skills/pine/SKILL.md @@ -11,7 +11,7 @@ For a new or continuing phone task, read [Phone tasks](references/phone-tasks.md A clear task request is authorization: do not ask a separate “start?” question. Gather only information that is necessary to act. -Use the [client AsyncAPI](https://www.19pine.ai/api/docs/client.asyncapi.json) for Socket.IO connection details and event payloads, and the [client OpenAPI](https://www.19pine.ai/api/docs/client.openapi.json) for HTTP request and response schemas. Use `https://www.19pine.ai/api` as the HTTP API base; routes below are relative to it. The API provides capabilities to create, list, and get sessions; send a message; read history and outcomes; and stop an agent. It does not require a separate task-start call for a new task. +Use the [client AsyncAPI](https://www.19pine.ai/api/docs/client.asyncapi.json) for Socket.IO connection details and event payloads, and the [client OpenAPI](https://www.19pine.ai/api/docs/client.openapi.json) for HTTP request and response schemas. Use `https://www.19pine.ai/api` as the HTTP API base; routes below are relative to it. The API provides capabilities to create, list, and get sessions; send a message; read history and outcomes; and start or stop execution. It does not require a separate task-start call for a new task. Authentication, HTTP requests, Socket.IO, and task pages use production at `https://www.19pine.ai`. With the SDK, use `base_url="https://www.19pine.ai"`. @@ -44,6 +44,8 @@ Do not claim an external action happened or the task is complete from a session After sending an instruction or answer, follow live events when Socket.IO is available and read the same session's history for questions, forms, state, task-finished content, connection or payment requests, and Pine's replies. Read outcomes as well when they are relevant. Present Pine's actual reply and result facts faithfully; explain them if useful, but do not manufacture a summary, outcome, or terminal status. +Explain progress, failures, blockers, and next steps in plain language rather than exposing internal state names or raw fields. Use Pine's current response for account-specific facts; do not substitute general credit rules or unverified prices. When credits are insufficient, state the returned balance and minimum needed to start, if provided, and link to the Pine task page to add credits. + Fetch bounded history pages with `GET /v2/sessions/{session_id}/messages`. Messages are newest-first; parse each message's `data` JSON string. Follow `next_message_id` as `before_message_id` only while an older page is needed; an empty cursor ends pagination. Refresh messages with the same ID from the latest history response; `version` describes the encoding, not the edit revision. Use live-event revisions only as defined by the protocol. Replies appear only after persistence, so missing text after a state change calls for a later read, not resending the instruction. With Socket.IO, consume live replies, forms, and task events; assemble text parts by message ID. Rebuild history after joining, reconnecting, or unexplained silence, since missed live events are not replayed. A chat turn ending is not task completion; keep following the session while work runs. @@ -68,13 +70,15 @@ Actual OAuth/account connection, payment, phone verification, and other actions If your safety checks require user confirmation before sending information to Pine, briefly state what would be sent and ask the user to confirm. Avoid security jargon unless asked, and proceed after confirmation where permitted. -## Stop a task +## Start or stop execution + +When the user asks to begin or resume an existing task that is waiting to start or paused, call `POST /v2/sessions/{session_id}/start`. Pine checks whether the task can start, including available credits. Query the same session afterward to confirm progress; an accepted start does not mean the task is complete. When the user asks to stop a Pine task, identify the matching session and call `POST /v2/sessions/{session_id}/stop`. A clear request is sufficient; clarify only when the target is ambiguous. Pine decides whether that task can be stopped. If it rejects the request, explain the returned reason rather than creating a replacement task or trying another execution path. -Stop pauses a processing task; in chat, it prevents new actions while an in-flight action may finish. It does not end the session or prove the objective succeeded. Query the same session and history to report the resulting state rather than claiming an external action has already stopped. Do not stop other tasks merely to free a task slot unless the user has authorized stopping those tasks. Resume a stopped task in the Pine task page; sending a message alone does not resume it. +Stop pauses a processing task; in chat, it prevents new actions while an in-flight action may finish. It does not end the session or prove the objective succeeded. Query the same session and history to report the resulting state rather than claiming an external action has already stopped. Do not stop other tasks merely to free a task slot unless the user has authorized stopping those tasks. Sending a message alone does not resume a stopped task. -If stopping the task times out or returns an unknown result, query the same session and its history before deciding what to do next. The state may have changed before notification to the agent failed; do not blindly repeat the write or claim that downstream execution has stopped. +If starting or stopping the task times out or returns an unknown result, query the same session and its history before deciding what to do next. The state may have changed before notification to the agent failed; do not blindly repeat the write or claim that downstream execution has started or stopped. ## Uncertain writes From ce3231cde7738ea759474384cd931cab71538099 Mon Sep 17 00:00:00 2001 From: Arvin Hsu Date: Fri, 6 Nov 2026 17:01:08 +0000 Subject: [PATCH 2/4] fix: preserve insufficient-credit explanations from HTTP responses --- skills/pine/SKILL.md | 2 +- src/pine_assistant/transport/http.py | 17 +++++++- tests/test_m1_resources.py | 58 +++++++++++++++++++++++++++- 3 files changed, 74 insertions(+), 3 deletions(-) diff --git a/skills/pine/SKILL.md b/skills/pine/SKILL.md index 9856048..0a15a31 100644 --- a/skills/pine/SKILL.md +++ b/skills/pine/SKILL.md @@ -44,7 +44,7 @@ Do not claim an external action happened or the task is complete from a session After sending an instruction or answer, follow live events when Socket.IO is available and read the same session's history for questions, forms, state, task-finished content, connection or payment requests, and Pine's replies. Read outcomes as well when they are relevant. Present Pine's actual reply and result facts faithfully; explain them if useful, but do not manufacture a summary, outcome, or terminal status. -Explain progress, failures, blockers, and next steps in plain language rather than exposing internal state names or raw fields. Use Pine's current response for account-specific facts; do not substitute general credit rules or unverified prices. When credits are insufficient, state the returned balance and minimum needed to start, if provided, and link to the Pine task page to add credits. +Explain progress, failures, blockers, and next steps in plain language rather than exposing internal state names or raw fields. Use Pine's current response for account-specific facts; do not substitute general credit rules or unverified prices. When credits are insufficient, state the returned balance and minimum needed to start, if provided, and link to the Pine task page to add credits. After a top-up, use `GET /v2/sessions/{session_id}` to check current requirements; an older history message may still describe the previous balance. Fetch bounded history pages with `GET /v2/sessions/{session_id}/messages`. Messages are newest-first; parse each message's `data` JSON string. Follow `next_message_id` as `before_message_id` only while an older page is needed; an empty cursor ends pagination. Refresh messages with the same ID from the latest history response; `version` describes the encoding, not the edit revision. Use live-event revisions only as defined by the protocol. Replies appear only after persistence, so missing text after a state change calls for a later read, not resending the instruction. diff --git a/src/pine_assistant/transport/http.py b/src/pine_assistant/transport/http.py index dfda978..ab202d8 100644 --- a/src/pine_assistant/transport/http.py +++ b/src/pine_assistant/transport/http.py @@ -77,11 +77,26 @@ def _input_state_details(response: httpx.Response) -> dict[str, Any] | None: return {"input_state": input_state} +def _error_message(response: httpx.Response) -> str: + """Preserve the public credit explanation without exposing other error bodies.""" + if response.status_code == 402: + try: + payload = response.json() + except (ValueError, TypeError): + payload = None + error = payload.get("error") if isinstance(payload, dict) else None + if isinstance(error, dict) and error.get("code") == "credits_insufficient": + message = error.get("message") + if isinstance(message, str) and message.strip(): + return message + return f"Pine API request failed with HTTP {response.status_code}" + + def _json_data(response: httpx.Response) -> Any: if not 200 <= response.status_code < 300: raise PineAIError( _error_code(response), - f"Pine API request failed with HTTP {response.status_code}", + _error_message(response), _input_state_details(response), status_code=response.status_code, ) diff --git a/tests/test_m1_resources.py b/tests/test_m1_resources.py index 75180e4..a49cfd6 100644 --- a/tests/test_m1_resources.py +++ b/tests/test_m1_resources.py @@ -4,7 +4,7 @@ import httpx import pytest -from pine_assistant import AsyncPineAI, AuthError, PineAI, SessionError +from pine_assistant import AsyncPineAI, AuthError, PineAI, PineAIError, SessionError def success(data): @@ -541,3 +541,59 @@ async def handler(request): access_token="user", base_url="https://pine.test", http_transport=httpx.MockTransport(handler), ) as client: assert await client.sessions.upload_attachment(str(attachment)) == [] + + +@pytest.mark.parametrize("message", [ + "Insufficient credits. Please top up your account or subscribe to continue.", + None, + {"private": "unrelated data"}, + "", + " ", +]) +def test_start_preserves_only_string_credit_explanations(message): + def handler(request): + assert request.method == "POST" + assert request.url.path == "/api/v2/sessions/7/start" + return httpx.Response(402, json={"status": "error", "error": { + "code": "credits_insufficient", "message": message, "details": {"private": "hidden"}, + }}) + + with ( + PineAI(base_url="https://pine.test", http_transport=httpx.MockTransport(handler)) as client, + pytest.raises(PineAIError) as error, + ): + client.sessions.start_task("7") + assert error.value.code == "credits_insufficient" + assert error.value.status_code == 402 + assert str(error.value) == (message if isinstance(message, str) and message.strip() else "Pine API request failed with HTTP 402") + assert error.value.details is None + + +@pytest.mark.asyncio +async def test_async_start_preserves_credit_explanation(): + message = "Insufficient credits. Please top up your account or subscribe to continue." + + def handler(request): + assert request.url.path == "/api/v2/sessions/7/start" + return httpx.Response(402, json={"status": "error", "error": { + "code": "credits_insufficient", "message": message, + }}) + + async with AsyncPineAI(base_url="https://pine.test", http_transport=httpx.MockTransport(handler)) as client: + with pytest.raises(PineAIError, match="Insufficient credits") as error: + await client.sessions.start_task("7") + assert str(error.value) == message + assert error.value.status_code == 402 + + +@pytest.mark.parametrize("status,code", [(402, "other_error"), (500, "credits_insufficient")]) +def test_start_does_not_expose_other_http_error_messages(status, code): + def handler(_request): + return httpx.Response(status, json={"error": {"code": code, "message": "private upstream content"}}) + + with ( + PineAI(base_url="https://pine.test", http_transport=httpx.MockTransport(handler)) as client, + pytest.raises(PineAIError) as error, + ): + client.sessions.start_task("7") + assert str(error.value) == f"Pine API request failed with HTTP {status}" From d54af8fdba85b09b712ad2ee61f3a24f90653ed9 Mon Sep 17 00:00:00 2001 From: Arvin Hsu Date: Sat, 7 Nov 2026 04:07:28 +0000 Subject: [PATCH 3/4] docs: use current session requirements for waiting tasks --- skills/pine/SKILL.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/skills/pine/SKILL.md b/skills/pine/SKILL.md index 0a15a31..12684b8 100644 --- a/skills/pine/SKILL.md +++ b/skills/pine/SKILL.md @@ -44,7 +44,7 @@ Do not claim an external action happened or the task is complete from a session After sending an instruction or answer, follow live events when Socket.IO is available and read the same session's history for questions, forms, state, task-finished content, connection or payment requests, and Pine's replies. Read outcomes as well when they are relevant. Present Pine's actual reply and result facts faithfully; explain them if useful, but do not manufacture a summary, outcome, or terminal status. -Explain progress, failures, blockers, and next steps in plain language rather than exposing internal state names or raw fields. Use Pine's current response for account-specific facts; do not substitute general credit rules or unverified prices. When credits are insufficient, state the returned balance and minimum needed to start, if provided, and link to the Pine task page to add credits. After a top-up, use `GET /v2/sessions/{session_id}` to check current requirements; an older history message may still describe the previous balance. +Explain progress, failures, blockers, and next steps in plain language rather than exposing internal state names or raw fields. Use Pine's current response for account-specific facts; do not substitute general credit rules or unverified prices. When credits are insufficient, state the returned balance and minimum needed to start, if provided, and link to the Pine task page to add credits. When a task is waiting to start or after a top-up, use `GET /v2/sessions/{session_id}` to check current requirements; history does not establish the current balance. Fetch bounded history pages with `GET /v2/sessions/{session_id}/messages`. Messages are newest-first; parse each message's `data` JSON string. Follow `next_message_id` as `before_message_id` only while an older page is needed; an empty cursor ends pagination. Refresh messages with the same ID from the latest history response; `version` describes the encoding, not the edit revision. Use live-event revisions only as defined by the protocol. Replies appear only after persistence, so missing text after a state change calls for a later read, not resending the instruction. From 54b7a6e4b7fb93d9f05f5bf9b18c4ca16c623531 Mon Sep 17 00:00:00 2001 From: Arvin Hsu Date: Sat, 7 Nov 2026 07:51:36 +0000 Subject: [PATCH 4/4] docs: simplify user communication guidance --- skills/pine/SKILL.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/skills/pine/SKILL.md b/skills/pine/SKILL.md index 12684b8..3b929c1 100644 --- a/skills/pine/SKILL.md +++ b/skills/pine/SKILL.md @@ -44,7 +44,7 @@ Do not claim an external action happened or the task is complete from a session After sending an instruction or answer, follow live events when Socket.IO is available and read the same session's history for questions, forms, state, task-finished content, connection or payment requests, and Pine's replies. Read outcomes as well when they are relevant. Present Pine's actual reply and result facts faithfully; explain them if useful, but do not manufacture a summary, outcome, or terminal status. -Explain progress, failures, blockers, and next steps in plain language rather than exposing internal state names or raw fields. Use Pine's current response for account-specific facts; do not substitute general credit rules or unverified prices. When credits are insufficient, state the returned balance and minimum needed to start, if provided, and link to the Pine task page to add credits. When a task is waiting to start or after a top-up, use `GET /v2/sessions/{session_id}` to check current requirements; history does not establish the current balance. +Explain Pine's progress, problems, and next steps in plain language rather than listing internal state names or raw fields. When the user needs to act on a Pine page, provide the task link. Fetch bounded history pages with `GET /v2/sessions/{session_id}/messages`. Messages are newest-first; parse each message's `data` JSON string. Follow `next_message_id` as `before_message_id` only while an older page is needed; an empty cursor ends pagination. Refresh messages with the same ID from the latest history response; `version` describes the encoding, not the edit revision. Use live-event revisions only as defined by the protocol. Replies appear only after persistence, so missing text after a state change calls for a later read, not resending the instruction.