Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 8 additions & 4 deletions skills/pine/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -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"`.

Expand Down Expand Up @@ -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 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.

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.
Expand All @@ -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

Expand Down
17 changes: 16 additions & 1 deletion src/pine_assistant/transport/http.py
Original file line number Diff line number Diff line change
Expand Up @@ -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,
)
Expand Down
58 changes: 57 additions & 1 deletion tests/test_m1_resources.py
Original file line number Diff line number Diff line change
Expand Up @@ -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):
Expand Down Expand Up @@ -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}"
Loading