From a623e2fb5f8f980143a4dbfc94f3e8c9c473a726 Mon Sep 17 00:00:00 2001 From: Arvin Hsu Date: Thu, 5 Nov 2026 12:53:51 +0000 Subject: [PATCH 1/8] docs: add Instinct REST setup and Pine skill --- README.md | 5 ++ install/instinct.md | 29 ++++++++++++ skills/pine-rest/SKILL.md | 54 ++++++++++++++++++++++ skills/pine-rest/references/phone-tasks.md | 27 +++++++++++ 4 files changed, 115 insertions(+) create mode 100644 install/instinct.md create mode 100644 skills/pine-rest/SKILL.md create mode 100644 skills/pine-rest/references/phone-tasks.md diff --git a/README.md b/README.md index 3da3179..a565506 100644 --- a/README.md +++ b/README.md @@ -13,6 +13,11 @@ pip install pine-assistant # SDK only pip install pine-assistant[cli] # SDK + CLI ``` +## Instinct and REST agents + +Follow [Set up Pine in Instinct](install/instinct.md) to connect with a user token +and the [Pine REST skill](skills/pine-rest/SKILL.md), without installing Python. + ## Quick Start (Async) ```python diff --git a/install/instinct.md b/install/instinct.md new file mode 100644 index 0000000..55eb3f5 --- /dev/null +++ b/install/instinct.md @@ -0,0 +1,29 @@ +# Set up Pine in Instinct + +Use REST with Instinct's API Key credential storage. Python, MCP, and native +Skill installation are not required. Read the [Pine REST skill](../skills/pine-rest/SKILL.md) +and its references; retain that complete link for future conversations if you +cannot save the files. + +Use the [agent REST OpenAPI](https://www.19pine.ai/api/docs/agent-rest.openapi.json) +with API base `https://www.19pine.ai/api`. If it is unavailable, report that setup +is incomplete rather than inventing an API definition. + +1. Ask for the user's Pine account email. Explain that verifying an email without + an existing account creates one; use their existing account when intended. +2. Send `POST /v2/auth/email/request` with `{"email":"..."}` and retain + `data.request_token`. Ask the user for the emailed code, then send + `POST /v2/auth/email/verify` with `email`, `code`, and `request_token`. +3. Save `data.access_token` in API Key storage and use + `Authorization: Bearer ` for authenticated Pine requests. This + is a normal user token, not a partner API key or MCP OAuth token. Do not print + it or save it in the Skill. If secure storage is unavailable, ask the user to + configure the credential securely instead. +4. Verify with `GET /v2/auth/me` and retain `data.user_id`. Setup does not create + sessions, send task instructions, or make calls. + +Successful authentication renews the token's idle expiry (30 days in the +production configuration). +If it expires or is revoked, repeat email login and check that `/v2/auth/me` +returns the same user ID before continuing existing tasks. Do not automatically +replay a failed write after signing in; follow the Skill's recovery rules. diff --git a/skills/pine-rest/SKILL.md b/skills/pine-rest/SKILL.md new file mode 100644 index 0000000..25a9fdb --- /dev/null +++ b/skills/pine-rest/SKILL.md @@ -0,0 +1,54 @@ +--- +name: pine-rest +description: Connect to Pine AI over REST to delegate supported real-world tasks and check, continue, or stop existing Pine tasks. See the skill instructions for the integration's currently supported scope. +--- + +# Pine Assistant + +Pine AI is an assistant that carries out real-world tasks. This REST integration currently supports starting phone tasks only. Pine can search for public business phone numbers and do the preparation needed to complete those phone tasks. This is the integration's current release scope, not a limit on Pine's overall capabilities. When a user's goal can be handled by phone, treat it as a phone task without requiring them to explicitly say “call.” If they explicitly request a new task through email, browser operation, fax, or another non-phone method, explain that this integration does not yet support starting that kind of task; do not silently change it to a phone call. + +For a new or continuing phone task, read [Phone tasks](references/phone-tasks.md) before composing the task instruction or interpreting call results. Existing Pine tasks can still be queried, answered, or stopped using the available REST operations; do not reject an existing task merely because it used another execution method. Ordinary informational questions can be answered in this conversation without delegating to Pine. + +A clear task request is authorization: do not ask a separate “start?” question. Gather only information that is necessary to act. + +Use the [agent REST OpenAPI](https://www.19pine.ai/api/docs/agent-rest.openapi.json) for request and response schemas. Its server `/api` resolves on `https://www.19pine.ai`; routes below are relative to that server. 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. + +Authenticate with the normal user's bearer from [Instinct setup](../../install/instinct.md), stored in the client's credential store. Send it only to Pine, not in prompts or logs. On authentication failure, repeat setup with the same account and verify its user ID before continuing; do not automatically replay writes. + +## Start or continue work + +1. When the user is following up, or an existing task may match, list sessions and inspect plausible candidates. Reuse the matching session. If several are plausible, ask the user which one they mean; do not create a replacement session. +2. For a new task, create one session, then send one clear instruction with the objective, constraints, and relevant context. Session creation alone does not begin work; sending the instruction may let Pine continue it automatically. +3. Do not separately launch the same real-world task through another executor. Keep execution of the delegated task with Pine; include any useful research you have already gathered. + +Do not claim an external action happened or the task is complete from a session state, timestamp, or a `received`/`delivered` message receipt. A delivered message only confirms dispatch. A `delivery_failed` receipt does not establish that nothing was saved; inspect history before sending again. A session can remain processing after Pine has replied. + +## Read updates and respond + +After sending an instruction or answer, 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. + +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. Retain the latest `version` of duplicate messages. Replies appear only after persistence, so missing text after a state change calls for a later read, not resending the instruction. + +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. + +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. + +For an ordinary Pine question, collect the user's answer in this conversation and send it to the same session. Keep sensitive form values, especially L2/L3 values, out of unnecessary narration. + +## Forms and web actions + +Typed form, authorization, and location responses are not available through this REST integration. When Pine requests one, payment, account connection, phone verification, or another web intervention, direct the user to `https://www.19pine.ai/app/chat/{session_id}` with the actual session ID. An ordinary text message is not equivalent to completing a typed response. After the user finishes, query the original session again; do not resend the task instruction or create a new session. + +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 + +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 an active task; 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. + +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. + +## Uncertain writes + +Creating sessions and sending messages are non-idempotent. Do not blindly retry when a write times out, has an unknown result, or reports a transport/server failure. For an uncertain creation, first list recent sessions; for an uncertain message, first read that session's history and reconcile the result. Ask for direction when recovery still cannot establish what happened. diff --git a/skills/pine-rest/references/phone-tasks.md b/skills/pine-rest/references/phone-tasks.md new file mode 100644 index 0000000..5b11f20 --- /dev/null +++ b/skills/pine-rest/references/phone-tasks.md @@ -0,0 +1,27 @@ +# Phone tasks + +Use this reference when preparing, continuing, or interpreting a Pine phone task. Follow the shared session, authorization, form, and recovery rules in [Pine Assistant](../SKILL.md). + +## Prepare the instruction + +Organize the task message using this short template. It guides the client's handoff to Pine; the user does not need to fill it out, and no new request parameters are required. + +```text +Goal: +Contact / phone number / search criteria: +Relevant background and requirements: (if available) +``` + +The goal and enough information to identify or find the contact are required. Use the current conversation first. For public businesses or organizations, pass a known number or enough information for Pine to find a public number. For private contacts, use a number provided by the user or retrieved from an authorized source the client can actually access. If neither is available, ask for the number; do not search publicly or guess it. The current Pine REST integration do not provide contact lookup, so do not promise to retrieve a number from a Pine address book. Include the country code when known, and clarify ambiguous dialing information when needed. + +Always carry over the user's known constraints and any relevant background. Omit an optional heading when it has no content. Ask about missing information only when it blocks progress; otherwise Pine can ask follow-up questions during the task. Do not invent personal facts, preferences, or authorization to fill the template. + +## Continue the task + +When Pine asks a question or presents a form, use the shared reply/form workflow in the original session. If Pine requires a verified phone number, direct the user to the Pine task page described in the shared workflow. Only treat a `phone_number` connector as requiring verification when its latest event requires action and is not connected. Typing a number in chat or submitting a form does not bind the account. After verification, query the same session again. + +## Interpret call results + +Use Pine's actual replies, history, and outcomes to report who was contacted and what happened. Message delivery, a session status, or a timestamp alone does not prove a call was placed, a person answered, or the objective succeeded. If the result is unclear, say what is known and retrieve the relevant history instead of inventing a successful outcome. + +A request to stop the task uses the shared REST stop workflow. Its response alone does not prove an ongoing call has disconnected. From 58c3ca9b553fd0137c7ecc2d57f28d27ff0c7cfd Mon Sep 17 00:00:00 2001 From: Arvin Hsu Date: Thu, 5 Nov 2026 12:54:34 +0000 Subject: [PATCH 2/8] docs: clarify durable skill link and token recovery --- install/instinct.md | 2 +- skills/pine-rest/SKILL.md | 2 +- skills/pine-rest/references/phone-tasks.md | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/install/instinct.md b/install/instinct.md index 55eb3f5..da433d7 100644 --- a/install/instinct.md +++ b/install/instinct.md @@ -1,7 +1,7 @@ # Set up Pine in Instinct Use REST with Instinct's API Key credential storage. Python, MCP, and native -Skill installation are not required. Read the [Pine REST skill](../skills/pine-rest/SKILL.md) +Skill installation are not required. Read the [Pine REST skill](https://github.com/19PINE-AI/pine-assistant-python/blob/main/skills/pine-rest/SKILL.md) and its references; retain that complete link for future conversations if you cannot save the files. diff --git a/skills/pine-rest/SKILL.md b/skills/pine-rest/SKILL.md index 25a9fdb..5384ca5 100644 --- a/skills/pine-rest/SKILL.md +++ b/skills/pine-rest/SKILL.md @@ -13,7 +13,7 @@ A clear task request is authorization: do not ask a separate “start?” questi Use the [agent REST OpenAPI](https://www.19pine.ai/api/docs/agent-rest.openapi.json) for request and response schemas. Its server `/api` resolves on `https://www.19pine.ai`; routes below are relative to that server. 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. -Authenticate with the normal user's bearer from [Instinct setup](../../install/instinct.md), stored in the client's credential store. Send it only to Pine, not in prompts or logs. On authentication failure, repeat setup with the same account and verify its user ID before continuing; do not automatically replay writes. +Authenticate with the normal user's bearer from [Instinct setup](../../install/instinct.md), stored in the client's credential store. Send it only to Pine, not in prompts or logs. On a 401 for an expired or invalid token, repeat setup with the same account and verify its user ID before continuing; do not automatically replay writes. ## Start or continue work diff --git a/skills/pine-rest/references/phone-tasks.md b/skills/pine-rest/references/phone-tasks.md index 5b11f20..f19a9c0 100644 --- a/skills/pine-rest/references/phone-tasks.md +++ b/skills/pine-rest/references/phone-tasks.md @@ -12,7 +12,7 @@ Contact / phone number / search criteria: Relevant background and requirements: (if available) ``` -The goal and enough information to identify or find the contact are required. Use the current conversation first. For public businesses or organizations, pass a known number or enough information for Pine to find a public number. For private contacts, use a number provided by the user or retrieved from an authorized source the client can actually access. If neither is available, ask for the number; do not search publicly or guess it. The current Pine REST integration do not provide contact lookup, so do not promise to retrieve a number from a Pine address book. Include the country code when known, and clarify ambiguous dialing information when needed. +The goal and enough information to identify or find the contact are required. Use the current conversation first. For public businesses or organizations, pass a known number or enough information for Pine to find a public number. For private contacts, use a number provided by the user or retrieved from an authorized source the client can actually access. If neither is available, ask for the number; do not search publicly or guess it. The current Pine REST integration does not provide contact lookup, so do not promise to retrieve a number from a Pine address book. Include the country code when known, and clarify ambiguous dialing information when needed. Always carry over the user's known constraints and any relevant background. Omit an optional heading when it has no content. Ask about missing information only when it blocks progress; otherwise Pine can ask follow-up questions during the task. Do not invent personal facts, preferences, or authorization to fill the template. From 9de089a535df18fbdb2f1b9b90e7fe85271e5e10 Mon Sep 17 00:00:00 2001 From: Arvin Hsu Date: Thu, 5 Nov 2026 12:56:17 +0000 Subject: [PATCH 3/8] docs: preserve read-only session lookup and stop semantics --- skills/pine-rest/SKILL.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/skills/pine-rest/SKILL.md b/skills/pine-rest/SKILL.md index 5384ca5..c6739f4 100644 --- a/skills/pine-rest/SKILL.md +++ b/skills/pine-rest/SKILL.md @@ -17,7 +17,7 @@ Authenticate with the normal user's bearer from [Instinct setup](../../install/i ## Start or continue work -1. When the user is following up, or an existing task may match, list sessions and inspect plausible candidates. Reuse the matching session. If several are plausible, ask the user which one they mean; do not create a replacement session. +1. When the user is following up, or an existing task may match, list sessions with `ensure_copilot=false` and inspect plausible candidates. Reuse the matching session. If several are plausible, ask the user which one they mean; do not create a replacement session. 2. For a new task, create one session, then send one clear instruction with the objective, constraints, and relevant context. Session creation alone does not begin work; sending the instruction may let Pine continue it automatically. 3. Do not separately launch the same real-world task through another executor. Keep execution of the delegated task with Pine; include any useful research you have already gathered. @@ -45,7 +45,7 @@ If your safety checks require user confirmation before sending information to Pi 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 an active task; 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. Resume a stopped task in the Pine task page; sending a message alone does not resume it. 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. From f884af8945cd85f598465b62560a4ea59d4bad15 Mon Sep 17 00:00:00 2001 From: Arvin Hsu Date: Thu, 5 Nov 2026 14:13:08 +0000 Subject: [PATCH 4/8] docs: move REST authentication into shared skill --- install/instinct.md | 25 +++---------------------- skills/pine-rest/SKILL.md | 11 ++++++++++- 2 files changed, 13 insertions(+), 23 deletions(-) diff --git a/install/instinct.md b/install/instinct.md index da433d7..1248182 100644 --- a/install/instinct.md +++ b/install/instinct.md @@ -5,25 +5,6 @@ Skill installation are not required. Read the [Pine REST skill](https://github.c and its references; retain that complete link for future conversations if you cannot save the files. -Use the [agent REST OpenAPI](https://www.19pine.ai/api/docs/agent-rest.openapi.json) -with API base `https://www.19pine.ai/api`. If it is unavailable, report that setup -is incomplete rather than inventing an API definition. - -1. Ask for the user's Pine account email. Explain that verifying an email without - an existing account creates one; use their existing account when intended. -2. Send `POST /v2/auth/email/request` with `{"email":"..."}` and retain - `data.request_token`. Ask the user for the emailed code, then send - `POST /v2/auth/email/verify` with `email`, `code`, and `request_token`. -3. Save `data.access_token` in API Key storage and use - `Authorization: Bearer ` for authenticated Pine requests. This - is a normal user token, not a partner API key or MCP OAuth token. Do not print - it or save it in the Skill. If secure storage is unavailable, ask the user to - configure the credential securely instead. -4. Verify with `GET /v2/auth/me` and retain `data.user_id`. Setup does not create - sessions, send task instructions, or make calls. - -Successful authentication renews the token's idle expiry (30 days in the -production configuration). -If it expires or is revoked, repeat email login and check that `/v2/auth/me` -returns the same user ID before continuing existing tasks. Do not automatically -replay a failed write after signing in; follow the Skill's recovery rules. +Follow the Skill's authentication steps, storing the returned token in +Instinct's API Key credential storage. Use the linked OpenAPI definition for +request and response schemas, and the Skill for task interactions and recovery. diff --git a/skills/pine-rest/SKILL.md b/skills/pine-rest/SKILL.md index c6739f4..ff21f59 100644 --- a/skills/pine-rest/SKILL.md +++ b/skills/pine-rest/SKILL.md @@ -13,7 +13,16 @@ A clear task request is authorization: do not ask a separate “start?” questi Use the [agent REST OpenAPI](https://www.19pine.ai/api/docs/agent-rest.openapi.json) for request and response schemas. Its server `/api` resolves on `https://www.19pine.ai`; routes below are relative to that server. 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. -Authenticate with the normal user's bearer from [Instinct setup](../../install/instinct.md), stored in the client's credential store. Send it only to Pine, not in prompts or logs. On a 401 for an expired or invalid token, repeat setup with the same account and verify its user ID before continuing; do not automatically replay writes. +## Authentication + +Use a normal user bearer token, not a partner API key or MCP OAuth token. If the API definition is unavailable, report that setup is incomplete rather than inventing a request. + +1. Ask for the user's Pine account email. Explain that verifying an email without an existing account creates one; use their existing account when intended. +2. Send `POST /v2/auth/email/request` with `{"email":"..."}` and retain `data.request_token`. Ask for the emailed code, then send `POST /v2/auth/email/verify` with `email`, `code`, and `request_token`. +3. Save `data.access_token` in secure credential storage and use `Authorization: Bearer ` for authenticated Pine requests. Send it only to Pine, not in prompts or logs. Do not print it or save it in the Skill. If secure storage is unavailable, ask the user to configure the credential securely instead. +4. Verify with `GET /v2/auth/me` and retain `data.user_id`. Setup does not create sessions, send task instructions, or make calls. + +Successful authentication renews the token's idle expiry (30 days in the production configuration). On a 401 for an expired or invalid token, repeat email login with the same account and verify its user ID before continuing existing tasks. Do not automatically replay a failed write after signing in; follow the recovery rules below. ## Start or continue work From dbb3f901e47cd58cdf226a6efeaf62fbdd28be52 Mon Sep 17 00:00:00 2001 From: Arvin Hsu Date: Thu, 5 Nov 2026 14:34:35 +0000 Subject: [PATCH 5/8] Support Socket.IO and REST in Pine skill --- README.md | 5 +- docs/socketio.md | 5 +- install/instinct.md | 13 ++-- skills/pine-rest/SKILL.md | 63 ---------------- skills/pine/SKILL.md | 75 +++++++++++++++++++ .../references/phone-tasks.md | 2 +- 6 files changed, 89 insertions(+), 74 deletions(-) delete mode 100644 skills/pine-rest/SKILL.md create mode 100644 skills/pine/SKILL.md rename skills/{pine-rest => pine}/references/phone-tasks.md (91%) diff --git a/README.md b/README.md index a565506..d47ab18 100644 --- a/README.md +++ b/README.md @@ -13,10 +13,11 @@ pip install pine-assistant # SDK only pip install pine-assistant[cli] # SDK + CLI ``` -## Instinct and REST agents +## Instinct and other agents Follow [Set up Pine in Instinct](install/instinct.md) to connect with a user token -and the [Pine REST skill](skills/pine-rest/SKILL.md), without installing Python. +and the [Pine skill](skills/pine/SKILL.md). The skill prefers Socket.IO when available +and uses REST in HTTP-only environments; Python is not required. ## Quick Start (Async) diff --git a/docs/socketio.md b/docs/socketio.md index 482b3b7..d469c06 100644 --- a/docs/socketio.md +++ b/docs/socketio.md @@ -3,8 +3,9 @@ > **Caution:** this page is a reference, not a supported contract. 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 full -protocol, contact us. +the server can also send events that this page does not describe. For the public connection and event contract, see the +[agent protocol](https://www.19pine.ai/api/docs/agent-protocol.md). +The managed-user authentication guidance below still applies to partners. ## Connect diff --git a/install/instinct.md b/install/instinct.md index 1248182..1d0a292 100644 --- a/install/instinct.md +++ b/install/instinct.md @@ -1,10 +1,11 @@ # Set up Pine in Instinct -Use REST with Instinct's API Key credential storage. Python, MCP, and native -Skill installation are not required. Read the [Pine REST skill](https://github.com/19PINE-AI/pine-assistant-python/blob/main/skills/pine-rest/SKILL.md) +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 -cannot save the files. +cannot save the files. Python and native Skill installation are not required. -Follow the Skill's authentication steps, storing the returned token in -Instinct's API Key credential storage. Use the linked OpenAPI definition for -request and response schemas, and the Skill for task interactions and recovery. +Follow the Skill's authentication steps, storing the returned user token in +Instinct's API Key credential storage. Follow its transport selection, task +interaction, and recovery instructions: prefer Socket.IO when the environment +can maintain a client and callbacks, and use REST directly when it only supports +HTTP requests. diff --git a/skills/pine-rest/SKILL.md b/skills/pine-rest/SKILL.md deleted file mode 100644 index ff21f59..0000000 --- a/skills/pine-rest/SKILL.md +++ /dev/null @@ -1,63 +0,0 @@ ---- -name: pine-rest -description: Connect to Pine AI over REST to delegate supported real-world tasks and check, continue, or stop existing Pine tasks. See the skill instructions for the integration's currently supported scope. ---- - -# Pine Assistant - -Pine AI is an assistant that carries out real-world tasks. This REST integration currently supports starting phone tasks only. Pine can search for public business phone numbers and do the preparation needed to complete those phone tasks. This is the integration's current release scope, not a limit on Pine's overall capabilities. When a user's goal can be handled by phone, treat it as a phone task without requiring them to explicitly say “call.” If they explicitly request a new task through email, browser operation, fax, or another non-phone method, explain that this integration does not yet support starting that kind of task; do not silently change it to a phone call. - -For a new or continuing phone task, read [Phone tasks](references/phone-tasks.md) before composing the task instruction or interpreting call results. Existing Pine tasks can still be queried, answered, or stopped using the available REST operations; do not reject an existing task merely because it used another execution method. Ordinary informational questions can be answered in this conversation without delegating to Pine. - -A clear task request is authorization: do not ask a separate “start?” question. Gather only information that is necessary to act. - -Use the [agent REST OpenAPI](https://www.19pine.ai/api/docs/agent-rest.openapi.json) for request and response schemas. Its server `/api` resolves on `https://www.19pine.ai`; routes below are relative to that server. 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. - -## Authentication - -Use a normal user bearer token, not a partner API key or MCP OAuth token. If the API definition is unavailable, report that setup is incomplete rather than inventing a request. - -1. Ask for the user's Pine account email. Explain that verifying an email without an existing account creates one; use their existing account when intended. -2. Send `POST /v2/auth/email/request` with `{"email":"..."}` and retain `data.request_token`. Ask for the emailed code, then send `POST /v2/auth/email/verify` with `email`, `code`, and `request_token`. -3. Save `data.access_token` in secure credential storage and use `Authorization: Bearer ` for authenticated Pine requests. Send it only to Pine, not in prompts or logs. Do not print it or save it in the Skill. If secure storage is unavailable, ask the user to configure the credential securely instead. -4. Verify with `GET /v2/auth/me` and retain `data.user_id`. Setup does not create sessions, send task instructions, or make calls. - -Successful authentication renews the token's idle expiry (30 days in the production configuration). On a 401 for an expired or invalid token, repeat email login with the same account and verify its user ID before continuing existing tasks. Do not automatically replay a failed write after signing in; follow the recovery rules below. - -## Start or continue work - -1. When the user is following up, or an existing task may match, list sessions with `ensure_copilot=false` and inspect plausible candidates. Reuse the matching session. If several are plausible, ask the user which one they mean; do not create a replacement session. -2. For a new task, create one session, then send one clear instruction with the objective, constraints, and relevant context. Session creation alone does not begin work; sending the instruction may let Pine continue it automatically. -3. Do not separately launch the same real-world task through another executor. Keep execution of the delegated task with Pine; include any useful research you have already gathered. - -Do not claim an external action happened or the task is complete from a session state, timestamp, or a `received`/`delivered` message receipt. A delivered message only confirms dispatch. A `delivery_failed` receipt does not establish that nothing was saved; inspect history before sending again. A session can remain processing after Pine has replied. - -## Read updates and respond - -After sending an instruction or answer, 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. - -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. Retain the latest `version` of duplicate messages. Replies appear only after persistence, so missing text after a state change calls for a later read, not resending the instruction. - -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. - -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. - -For an ordinary Pine question, collect the user's answer in this conversation and send it to the same session. Keep sensitive form values, especially L2/L3 values, out of unnecessary narration. - -## Forms and web actions - -Typed form, authorization, and location responses are not available through this REST integration. When Pine requests one, payment, account connection, phone verification, or another web intervention, direct the user to `https://www.19pine.ai/app/chat/{session_id}` with the actual session ID. An ordinary text message is not equivalent to completing a typed response. After the user finishes, query the original session again; do not resend the task instruction or create a new session. - -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 - -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. - -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. - -## Uncertain writes - -Creating sessions and sending messages are non-idempotent. Do not blindly retry when a write times out, has an unknown result, or reports a transport/server failure. For an uncertain creation, first list recent sessions; for an uncertain message, first read that session's history and reconcile the result. Ask for direction when recovery still cannot establish what happened. diff --git a/skills/pine/SKILL.md b/skills/pine/SKILL.md new file mode 100644 index 0000000..e2adc1b --- /dev/null +++ b/skills/pine/SKILL.md @@ -0,0 +1,75 @@ +--- +name: pine +description: Connect to Pine AI over Socket.IO or REST to delegate supported real-world tasks and check, continue, or stop existing Pine tasks. See the skill instructions for the integration's currently supported scope. +--- + +# Pine Assistant + +Pine AI is an assistant that carries out real-world tasks. This integration currently supports starting phone tasks only. Pine can search for public business phone numbers and do the preparation needed to complete those phone tasks. This is the integration's current release scope, not a limit on Pine's overall capabilities. When a user's goal can be handled by phone, treat it as a phone task without requiring them to explicitly say “call.” If they explicitly request a new task through email, browser operation, fax, or another non-phone method, explain that this integration does not yet support starting that kind of task; do not silently change it to a phone call. + +For a new or continuing phone task, read [Phone tasks](references/phone-tasks.md) before composing the task instruction or interpreting call results. Existing Pine tasks can still be queried, answered, or stopped using the available operations; do not reject an existing task merely because it used another execution method. Ordinary informational questions can be answered in this conversation without delegating to Pine. + +A clear task request is authorization: do not ask a separate “start?” question. Gather only information that is necessary to act. + +Use the [agent protocol](https://www.19pine.ai/api/docs/agent-protocol.md) for Socket.IO connection details and event payloads, and the [agent REST OpenAPI](https://www.19pine.ai/api/docs/agent-rest.openapi.json) for HTTP request and response schemas. Its server `/api` resolves on `https://www.19pine.ai`; routes below are relative to that server. 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. + +## Choose a transport + +Prefer Socket.IO when the execution environment can keep a client connected and receive callbacks. Use the Pine SDK if available, or a compatible Socket.IO client following the agent protocol; Python is not required. Wait for `ready`, join the selected session, and recover its history before sending or interpreting new work. Use REST for session management and other HTTP operations as needed. + +If the environment only supports HTTP requests, use REST directly. If Socket.IO fails, attempt bounded connection recovery, then use REST with the same account and session after reconciling history. Do not replay writes when switching transports. Authentication, billing, account restrictions, and rejected actions require their own resolution; switching transports does not bypass them. + +## Authentication + +Use a normal user bearer token, not a partner API key or MCP OAuth token. If the API definition is unavailable, report that setup is incomplete rather than inventing a request. + +1. Ask for the user's Pine account email. Explain that verifying an email without an existing account creates one; use their existing account when intended. +2. Send `POST /v2/auth/email/request` with `{"email":"..."}` and retain `data.request_token`. Ask for the emailed code, then send `POST /v2/auth/email/verify` with `email`, `code`, and `request_token`. +3. Save `data.access_token` in secure credential storage and use `Authorization: Bearer ` for authenticated HTTP requests and the protocol's token handshake for Socket.IO. Send it only to Pine, not in prompts or logs. Do not print it or save it in the Skill. If secure storage is unavailable, ask the user to configure the credential securely instead. +4. Verify with `GET /v2/auth/me` and retain `data.user_id`. Setup does not create sessions, send task instructions, or make calls. + +Successful authentication renews the token's idle expiry (30 days in the production configuration). On a 401 for an expired or invalid token, repeat email login with the same account and verify its user ID before continuing existing tasks. Do not automatically replay a failed write after signing in; follow the recovery rules below. + +## Start or continue work + +1. When the user is following up, or an existing task may match, list sessions with `ensure_copilot=false` and inspect plausible candidates. Reuse the matching session. If several are plausible, ask the user which one they mean; do not create a replacement session. +2. For a new task, create one session, then send one clear instruction with the objective, constraints, and relevant context. Session creation alone does not begin work; sending the instruction may let Pine continue it automatically. +3. Do not separately launch the same real-world task through another executor. Keep execution of the delegated task with Pine; include any useful research you have already gathered. + +Do not claim an external action happened or the task is complete from a session state, timestamp, or a `received`/`delivered` message receipt. A delivered message only confirms dispatch. A `delivery_failed` receipt does not establish that nothing was saved; inspect history before sending again. A session can remain processing after Pine has replied. + +## Read updates and respond + +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. + +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. + +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. + +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. + +For an ordinary Pine question, collect the user's answer in this conversation and send it to the same session. Keep sensitive form values, especially L2/L3 values, out of unnecessary narration. + +## Forms and web actions + +Prefer a verified typed form submission when the client supports it, such as the SDK's `submit_form_response`: recover the original form from authenticated history, retain its message/request IDs and field privacy levels, and submit the user's actual answers. Follow the documented event contract for other supported structured responses; do not assume the SDK implements every authorization or location interaction. + +When typed submission is unavailable, including over REST, send ordinary answers to form questions and choices as text in the same session. This includes normal contact details the user authorizes sharing. Read Pine's response and answer further clarification questions as needed; a structured event alone is not a reason to send the user to the web. Do not claim the typed form was completed merely because text was delivered. For sensitive fields requiring the protected form path, or when Pine still requires an unsupported interaction, use the Pine task page. + +Actual OAuth/account connection, payment, phone verification, and other actions requiring the web must be completed at `https://www.19pine.ai/app/chat/{session_id}` with the actual session ID. Text answers do not complete those actions. After the user finishes, query the original session again; do not resend the task instruction or create a new session. + +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 + +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. + +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. + +## Uncertain writes + +Creating sessions and sending messages or form responses are non-idempotent. Do not blindly retry when a write times out, has an unknown result, or reports a transport/server failure. For an uncertain creation, first list recent sessions; for an uncertain message or form response, first read that session's history and reconcile the result. Ask for direction when recovery still cannot establish what happened. diff --git a/skills/pine-rest/references/phone-tasks.md b/skills/pine/references/phone-tasks.md similarity index 91% rename from skills/pine-rest/references/phone-tasks.md rename to skills/pine/references/phone-tasks.md index f19a9c0..9d28e87 100644 --- a/skills/pine-rest/references/phone-tasks.md +++ b/skills/pine/references/phone-tasks.md @@ -12,7 +12,7 @@ Contact / phone number / search criteria: Relevant background and requirements: (if available) ``` -The goal and enough information to identify or find the contact are required. Use the current conversation first. For public businesses or organizations, pass a known number or enough information for Pine to find a public number. For private contacts, use a number provided by the user or retrieved from an authorized source the client can actually access. If neither is available, ask for the number; do not search publicly or guess it. The current Pine REST integration does not provide contact lookup, so do not promise to retrieve a number from a Pine address book. Include the country code when known, and clarify ambiguous dialing information when needed. +The goal and enough information to identify or find the contact are required. Use the current conversation first. For public businesses or organizations, pass a known number or enough information for Pine to find a public number. For private contacts, use a number provided by the user or retrieved from an authorized source the client can actually access. If neither is available, ask for the number; do not search publicly or guess it. The current Pine integration does not provide contact lookup, so do not promise to retrieve a number from a Pine address book. Include the country code when known, and clarify ambiguous dialing information when needed. Always carry over the user's known constraints and any relevant background. Omit an optional heading when it has no content. Ask about missing information only when it blocks progress; otherwise Pine can ask follow-up questions during the task. Do not invent personal facts, preferences, or authorization to fill the template. From 60b16722c2ffeddefa3433d53cd45f9865120da3 Mon Sep 17 00:00:00 2001 From: Arvin Hsu Date: Thu, 5 Nov 2026 15:13:37 +0000 Subject: [PATCH 6/8] Link Pine skill to client API contracts --- docs/socketio.md | 2 +- skills/pine/SKILL.md | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/socketio.md b/docs/socketio.md index d469c06..c97fb19 100644 --- a/docs/socketio.md +++ b/docs/socketio.md @@ -4,7 +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 -[agent protocol](https://www.19pine.ai/api/docs/agent-protocol.md). +[client AsyncAPI](https://www.19pine.ai/api/docs/client.asyncapi.json). The managed-user authentication guidance below still applies to partners. ## Connect diff --git a/skills/pine/SKILL.md b/skills/pine/SKILL.md index e2adc1b..3d3671e 100644 --- a/skills/pine/SKILL.md +++ b/skills/pine/SKILL.md @@ -11,11 +11,11 @@ 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 [agent protocol](https://www.19pine.ai/api/docs/agent-protocol.md) for Socket.IO connection details and event payloads, and the [agent REST OpenAPI](https://www.19pine.ai/api/docs/agent-rest.openapi.json) for HTTP request and response schemas. Its server `/api` resolves on `https://www.19pine.ai`; routes below are relative to that server. 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. Its server `/api` resolves on `https://www.19pine.ai`; routes below are relative to that server. 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. ## Choose a transport -Prefer Socket.IO when the execution environment can keep a client connected and receive callbacks. Use the Pine SDK if available, or a compatible Socket.IO client following the agent protocol; Python is not required. Wait for `ready`, join the selected session, and recover its history before sending or interpreting new work. Use REST for session management and other HTTP operations as needed. +Prefer Socket.IO when the execution environment can keep a client connected and receive callbacks. Use the Pine SDK if available, or a compatible Socket.IO client following the client AsyncAPI; Python is not required. Wait for `ready`, join the selected session, and recover its history before sending or interpreting new work. Use REST for session management and other HTTP operations as needed. If the environment only supports HTTP requests, use REST directly. If Socket.IO fails, attempt bounded connection recovery, then use REST with the same account and session after reconciling history. Do not replay writes when switching transports. Authentication, billing, account restrictions, and rejected actions require their own resolution; switching transports does not bypass them. From 15062af4dc6efef299501cd2e105cbfdaf93eff5 Mon Sep 17 00:00:00 2001 From: Arvin Hsu Date: Thu, 5 Nov 2026 17:04:03 +0000 Subject: [PATCH 7/8] docs: point Instinct integration guide to staging --- docs/socketio.md | 2 +- install/instinct.md | 2 ++ skills/pine/SKILL.md | 6 ++++-- 3 files changed, 7 insertions(+), 3 deletions(-) diff --git a/docs/socketio.md b/docs/socketio.md index c97fb19..662e6be 100644 --- a/docs/socketio.md +++ b/docs/socketio.md @@ -4,7 +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://www.19pine.ai/api/docs/client.asyncapi.json). +[client AsyncAPI (staging preview)](https://5t4g1ng.19pine.ai/api/docs/client.asyncapi.json). The managed-user authentication guidance below still applies to partners. ## Connect diff --git a/install/instinct.md b/install/instinct.md index 1d0a292..f9625b5 100644 --- a/install/instinct.md +++ b/install/instinct.md @@ -1,5 +1,7 @@ # Set up Pine in Instinct +This guide temporarily targets Pine staging at `https://5t4g1ng.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 cannot save the files. Python and native Skill installation are not required. diff --git a/skills/pine/SKILL.md b/skills/pine/SKILL.md index 3d3671e..25a1e46 100644 --- a/skills/pine/SKILL.md +++ b/skills/pine/SKILL.md @@ -11,7 +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://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. Its server `/api` resolves on `https://www.19pine.ai`; routes below are relative to that server. 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://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. Its server `/api` resolves on `https://5t4g1ng.19pine.ai`; routes below are relative to that server. 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. + +This setup temporarily targets staging. Use `https://5t4g1ng.19pine.ai` for HTTP, Socket.IO, and linked API documentation, overriding any production host in the contracts or SDK defaults. With the SDK, set `base_url` to this origin. ## Choose a transport @@ -58,7 +60,7 @@ Prefer a verified typed form submission when the client supports it, such as the When typed submission is unavailable, including over REST, send ordinary answers to form questions and choices as text in the same session. This includes normal contact details the user authorizes sharing. Read Pine's response and answer further clarification questions as needed; a structured event alone is not a reason to send the user to the web. Do not claim the typed form was completed merely because text was delivered. For sensitive fields requiring the protected form path, or when Pine still requires an unsupported interaction, use the Pine task page. -Actual OAuth/account connection, payment, phone verification, and other actions requiring the web must be completed at `https://www.19pine.ai/app/chat/{session_id}` with the actual session ID. Text answers do not complete those actions. After the user finishes, query the original session again; do not resend the task instruction or create a new session. +Actual OAuth/account connection, payment, phone verification, and other actions requiring the web must be completed at `https://5t4g1ng.19pine.ai/app/chat/{session_id}` with the actual session ID. Text answers do not complete those actions. After the user finishes, query the original session again; do not resend the task instruction or create a new session. 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. From af625b79143e1ba7559317910b654798d3ece707 Mon Sep 17 00:00:00 2001 From: Arvin Hsu Date: Thu, 5 Nov 2026 17:11:06 +0000 Subject: [PATCH 8/8] docs: keep production endpoints with staging contract links --- docs/socketio.md | 3 ++- install/instinct.md | 2 +- skills/pine/SKILL.md | 6 +++--- 3 files changed, 6 insertions(+), 5 deletions(-) diff --git a/docs/socketio.md b/docs/socketio.md index 662e6be..f9fbfdf 100644 --- a/docs/socketio.md +++ b/docs/socketio.md @@ -4,7 +4,8 @@ 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 (staging preview)](https://5t4g1ng.19pine.ai/api/docs/client.asyncapi.json). +[client AsyncAPI](https://5t4g1ng.19pine.ai/api/docs/client.asyncapi.json). +Only this documentation link temporarily uses staging; connections use production. The managed-user authentication guidance below still applies to partners. ## Connect diff --git a/install/instinct.md b/install/instinct.md index f9625b5..3f246ba 100644 --- a/install/instinct.md +++ b/install/instinct.md @@ -1,6 +1,6 @@ # Set up Pine in Instinct -This guide temporarily targets Pine staging at `https://5t4g1ng.19pine.ai`. +Connect to Pine production at `https://www.19pine.ai`. Only the linked API documentation temporarily uses staging; its links will move to production. 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 diff --git a/skills/pine/SKILL.md b/skills/pine/SKILL.md index 25a1e46..000ed4d 100644 --- a/skills/pine/SKILL.md +++ b/skills/pine/SKILL.md @@ -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. Its server `/api` resolves on `https://5t4g1ng.19pine.ai`; routes below are relative to that server. 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://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. -This setup temporarily targets staging. Use `https://5t4g1ng.19pine.ai` for HTTP, Socket.IO, and linked API documentation, overriding any production host in the contracts or SDK defaults. With the SDK, set `base_url` to this origin. +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"`. ## Choose a transport @@ -60,7 +60,7 @@ Prefer a verified typed form submission when the client supports it, such as the When typed submission is unavailable, including over REST, send ordinary answers to form questions and choices as text in the same session. This includes normal contact details the user authorizes sharing. Read Pine's response and answer further clarification questions as needed; a structured event alone is not a reason to send the user to the web. Do not claim the typed form was completed merely because text was delivered. For sensitive fields requiring the protected form path, or when Pine still requires an unsupported interaction, use the Pine task page. -Actual OAuth/account connection, payment, phone verification, and other actions requiring the web must be completed at `https://5t4g1ng.19pine.ai/app/chat/{session_id}` with the actual session ID. Text answers do not complete those actions. After the user finishes, query the original session again; do not resend the task instruction or create a new session. +Actual OAuth/account connection, payment, phone verification, and other actions requiring the web must be completed at `https://www.19pine.ai/app/chat/{session_id}` with the actual session ID. Text answers do not complete those actions. After the user finishes, query the original session again; do not resend the task instruction or create a new session. 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.