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
3 changes: 1 addition & 2 deletions docs/socketio.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,8 +4,7 @@

This page covers only part of the Socket.IO protocol. While you use Socket.IO,
the server can also send events that this page does not describe. For the public connection and event contract, see the
[client AsyncAPI](https://5t4g1ng.19pine.ai/api/docs/client.asyncapi.json).
Only this documentation link temporarily uses staging; connections use production.
[client AsyncAPI](https://www.19pine.ai/api/docs/client.asyncapi.json).
The managed-user authentication guidance below still applies to partners.

## Connect
Expand Down
2 changes: 1 addition & 1 deletion install/instinct.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Set up Pine in Instinct

Connect to Pine production at `https://www.19pine.ai`. Only the linked API documentation temporarily uses staging; its links will move to production.
Connect to Pine production at `https://www.19pine.ai`.

Read the [Pine skill](https://github.com/19PINE-AI/pine-assistant-python/blob/main/skills/pine/SKILL.md)
and its references; retain that complete link for future conversations if you
Expand Down
10 changes: 7 additions & 3 deletions skills/pine/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,9 +11,9 @@ 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://5t4g1ng.19pine.ai/api/docs/client.asyncapi.json) for Socket.IO connection details and event payloads, and the [client OpenAPI](https://5t4g1ng.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 stop an agent. It does not require a separate task-start call for a new task.

Only the API documentation is temporarily hosted on staging; these links will move to production. Use the staging documentation URLs above when following contract cross-references. Authentication, HTTP requests, Socket.IO, and task pages use production at `https://www.19pine.ai`. Resolve the OpenAPI server `/api` against this production origin, not the documentation host. With the SDK, use `base_url="https://www.19pine.ai"`.
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"`.

## Choose a transport

Expand Down Expand Up @@ -48,7 +48,11 @@ Fetch bounded history pages with `GET /v2/sessions/{session_id}/messages`. Messa

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.

With REST, Pine does not send you updates automatically, so you must actively read history to follow progress. After sending a message and after each history read, decide when to check again based on Pine’s latest reply and the task’s expected progress. If timing is uncertain, prefer checking sooner rather than stopping follow-up; avoid tight polling loops. An acknowledgement is not completion. Defer checks for scheduled work, pause for required user input, and stop when the task finishes.
With REST, retrieve subsequent progress through history reads and schedule checks proactively. An acknowledgement such as “I'll take care of it” is not completion; while the task is still running, arrange the next check.

Use Pine's latest reply and current progress to estimate when the next update is likely. Without a clear timing signal, check again in about 30 seconds; extend the interval when there is reason to expect progress to take longer. Reassess after every read rather than keeping one interval for the whole task or waiting progressively longer just because no new message has appeared.

If Pine gives a specific future time to continue, schedule the next check around that time instead of polling throughout the wait. If timed wake-ups are available, set a one-time check; otherwise, explain that you cannot follow up automatically at that time. When Pine needs user input or action, relay the request and pause routine checks. Resume follow-up after sending the user's answer to Pine or when the user reports completing the action. If completion is uncertain, check the same session to confirm its status. Stop checking when the task finishes.

If you have a wait tool, use it before another bounded query; do not promise updates after you stop checking. A later conversation can recover by listing sessions and reading the chosen session's history/outcomes.

Expand Down
Loading