@vellumai/assistant 0.4.43 → 0.4.45

package/src/config/bundled-skills/notion-oauth-setup/SKILL.md

@@ -1,126 +0,0 @@
----
-name: notion-oauth-setup
-description: Create a Notion integration and OAuth credentials for Notion integration using browser automation
-compatibility: "Designed for Vellum personal assistants"
-metadata: {"emoji":"🔑","vellum":{"display-name":"Notion OAuth Setup","user-invocable":true,"includes":["browser","public-ingress"]}}
----
-
-You are helping your user create a Notion integration (OAuth app) so Vellum can connect to their Notion workspace. Walk through each step below using `browser_navigate`, `browser_snapshot`, `browser_screenshot`, `browser_click`, `browser_type`, and `browser_extract` tools.
-
-**Tone:** Be friendly and reassuring throughout. Narrate what you're doing in plain language so the user always knows what's happening. After each step, briefly confirm what was accomplished before moving on.
-
-## Prerequisites
-
-Before starting, check that `ingress.publicBaseUrl` is configured (Settings > Public Ingress, or `INGRESS_PUBLIC_BASE_URL` env var). If it is not set, load and execute the **public-ingress** skill first (`skill_load` with `skill: "public-ingress"`) to set up an ngrok tunnel and persist the public URL. The OAuth redirect URI depends on this value.
-
-## Before You Start
-
-Tell the user:
-- "I'll walk you through creating a Notion integration so Vellum can read and write pages and databases in your workspace. The whole process takes a few minutes."
-- "I'll be automating the Notion integrations page in the browser — you'll be able to see everything I'm doing."
-- "I'll ask for your approval before each major step, so nothing happens without your say-so."
-- "No sensitive credentials will be shown in the conversation."
-
-## Step 1: Navigate to Notion Integrations
-
-Tell the user: "First, let me open the Notion integrations page."
-
-Use `browser_navigate` to go to `https://www.notion.so/my-integrations`.
-
-Take a `browser_screenshot` to show the user what loaded, then take a `browser_snapshot` to check the page state:
-- **If a sign-in page appears:** Tell the user "Please sign in to your Notion account in the browser window. Let me know when you're done." Wait for their confirmation, then take another snapshot.
-- **If the integrations dashboard loads:** Tell the user "Notion integrations page is loaded. Let's create your integration!" and continue to Step 2.
-
-## Step 2: Create a New Integration
-
-**Ask for approval before proceeding.** Use `ui_show` with `surface_type: "confirmation"` and this message:
-
-> **Create a Notion Integration**
->
-> I'm about to create a new Notion integration called "Vellum Assistant". This integration will only have the capabilities you approve — it won't access any pages or databases until you explicitly share them with it or authorize it via OAuth.
-
-Wait for the user to approve. If they decline, explain that the integration is required for OAuth and offer to try again or cancel.
-
-Once approved:
-1. Click "New integration" (or the "+" button)
-2. Select "Public" as the integration type (required for OAuth)
-3. Enter integration name: "Vellum Assistant"
-4. Select the user's workspace
-5. Click "Submit" or "Create"
-
-Take a `browser_screenshot` to show the result.
-
-Tell the user: "Integration created! Now let's configure the OAuth settings."
-
-## Step 3: Configure OAuth Settings
-
-Navigate to the integration's "Distribution" or "OAuth Domain & URIs" tab.
-
-**Ask for approval before proceeding.** Use `ui_show` with `surface_type: "confirmation"` and this message:
-
-> **Configure OAuth Redirect URI**
->
-> I'm about to add the OAuth redirect URI to your Notion integration. This allows Notion to send the authorization code back to Vellum after you approve the connection.
-
-Wait for the user to approve.
-
-Once approved:
-1. Find the "Redirect URIs" field
-2. Enter `${ingress.publicBaseUrl}/webhooks/oauth/callback` (e.g. `https://abc123.ngrok-free.app/webhooks/oauth/callback`). Read the `ingress.publicBaseUrl` value from the assistant's workspace config (Settings > Public Ingress) or the `INGRESS_PUBLIC_BASE_URL` environment variable.
-3. Save the settings
-
-Take a `browser_snapshot` to confirm.
-
-Tell the user: "Redirect URI configured. Now let's get your OAuth credentials."
-
-## Step 4: Extract Client ID and Client Secret
-
-Stay on the integration settings page and navigate to the "Secrets" or "OAuth Clients" section.
-
-Use `browser_extract` to read:
-1. **OAuth client_id** — this is the integration's OAuth client ID
-2. **OAuth client_secret** — click "Show" or "Reveal" first, then extract the value
-
-**Important:** Notion requires a client secret for the token exchange (sent via HTTP Basic Auth). Both values are needed.
-
-Tell the user: "Credentials extracted! Now let's connect your Notion workspace."
-
-## Step 5: Connect Notion
-
-Tell the user: "Opening Notion authorization so you can grant Vellum access to your workspace. You'll see a Notion consent page — just click 'Allow access'."
-
-Use the `credential_store` tool to connect Notion via OAuth2:
-
-```
-action: "oauth2_connect"
-service: "integration:notion"
-client_id: "<the extracted OAuth client_id>"
-client_secret: "<the extracted OAuth client_secret>"
-auth_url: "https://api.notion.com/v1/oauth/authorize"
-token_url: "https://api.notion.com/v1/oauth/token"
-scopes: []
-extra_params: {"owner": "user"}
-token_endpoint_auth_method: "client_secret_basic"
-```
-
-This will open the Notion authorization page in the user's browser. Wait for the flow to complete.
-
-## Step 6: Celebrate!
-
-Once connected, tell the user:
-
-"**Notion is connected!** You're all set. You can now read and write pages and databases in your Notion workspace through Vellum. Try asking me to list your databases or read a specific page!"
-
-Summarize what was accomplished:
-- Created a Notion public integration called "Vellum Assistant"
-- Configured the OAuth redirect URI
-- Connected your Notion workspace with read and write access
-
-## Error Handling
-
-- **Page load failures:** Retry navigation once. If it still fails, tell the user and ask them to check their internet connection.
-- **"Public" integration type not available:** The user may need to enable public integrations in their workspace settings. Guide them to Workspace Settings > Integrations.
-- **Element not found for click/type:** Take a fresh `browser_snapshot` to re-assess the page layout. Notion's UI may have changed; adapt your selectors.
-- **User declines an approval gate:** Don't push back. Explain briefly why the step matters, offer to try again, or cancel gracefully.
-- **OAuth flow timeout or failure:** Tell the user what happened and offer to retry. The integration is already created, so they only need to re-run the connect step.
-- **Any unexpected state:** Take a `browser_screenshot` and `browser_snapshot`, describe what you see, and ask the user for guidance.

package/src/config/bundled-skills/oauth-setup/SKILL.md

@@ -1,143 +0,0 @@
----
-name: oauth-setup
-description: Connect any OAuth service — create app credentials and authorize via browser automation
-compatibility: "Designed for Vellum personal assistants"
-metadata: {"emoji":"🔑","vellum":{"display-name":"OAuth Setup","user-invocable":true,"includes":["browser"]}}
----
-
-You are helping the user connect an OAuth-based service to Vellum. This is a generic setup flow that works for any provider with a well-known OAuth config.
-
-**Tone:** Be friendly and reassuring throughout. Narrate what you're doing in plain language so the user always knows what's happening. After each step, briefly confirm what was accomplished before moving on.
-
-## Input
-
-You will be given a `service` name (e.g., "discord", "linear", "spotify"). If not provided, ask the user which service they want to connect.
-
-## Step 1: Read the service config
-
-Use `credential_store` with `action: "describe"` and `service: "<name>"` to get the well-known OAuth config. This returns:
-- `scopes` — permissions to request
-- `redirectUri` — the callback URL to register
-- `callbackTransport` — loopback or gateway
-- `requiresClientSecret` — whether a client secret is needed
-- `authUrl` / `tokenUrl` — OAuth endpoints
-
-It may also include a `setup` object with rich metadata:
-- `setup.displayName` — the provider's name
-- `setup.dashboardUrl` — where to create the app
-- `setup.appType` — what kind of app to create
-- `setup.requiresClientSecret` — whether a client secret is needed
-- `setup.notes` — provider-specific guidance
-
-If no config is found, tell the user this service doesn't have a pre-configured setup and offer to help them configure it manually via `oauth2_connect`.
-
-## Step 2: Choose the flow based on setup metadata
-
-### If `setup` metadata is present (rich flow)
-
-Continue to Step 3 (Rich Flow).
-
-### If `setup` metadata is absent (manual flow)
-
-The provider has OAuth config (endpoints, scopes) but no setup automation metadata. Guide the user through a manual app creation:
-
-1. Tell the user: "I have the OAuth endpoints and scopes for this service, but I don't have developer dashboard automation for it. You'll need to create an OAuth app manually."
-2. Provide the details they need:
-   - **Scopes to request:** list the `scopes` from the config
-   - **Redirect URI:** show the `redirectUri` value
-   - **Whether a client secret is required:** use the top-level `requiresClientSecret` field
-3. Ask the user to:
-   - Go to the provider's developer dashboard
-   - Create an OAuth app (name it "Vellum Assistant")
-   - Set the redirect URI
-   - Configure the required scopes
-   - Copy the Client ID (and Client Secret if required)
-4. Once they provide the credentials, skip to **Step 8: Connect**.
-
----
-
-## Rich Flow (when `setup` is present)
-
-### Step 3: Tell the user what's happening
-
-Tell the user:
-- "I'll walk you through creating a {setup.appType} so Vellum can connect to {setup.displayName}. The whole process takes a few minutes."
-- "I'll be automating the {setup.displayName} developer dashboard in the browser — you'll be able to see everything I'm doing."
-- "I'll ask for your approval before each major step, so nothing happens without your say-so."
-
-### Step 4: Navigate to the developer dashboard
-
-Use `browser_navigate` to go to `setup.dashboardUrl`.
-
-Take a `browser_screenshot` and `browser_snapshot`:
-- **If a sign-in page appears:** Tell the user to sign in and wait for confirmation.
-- **If the dashboard loads:** Continue to Step 5.
-
-### Step 5: Create an app
-
-**Ask for approval before proceeding.** Use `ui_show` with `surface_type: "confirmation"` explaining what you're about to create.
-
-Once approved:
-1. Find and click the "Create App" / "New Application" / "New Integration" button (adapt to the provider's UI)
-2. Name it "Vellum Assistant"
-3. Follow any guidance from `setup.notes`
-4. Complete the creation flow
-
-Take a `browser_screenshot` to confirm.
-
-### Step 6: Configure scopes/permissions
-
-**Ask for approval before proceeding.** List the `scopes` from the config and explain what each grants.
-
-Once approved, navigate to the OAuth/permissions section and add each scope. Follow `setup.notes` for any provider-specific guidance (e.g., "User Token Scopes" vs "Bot Token Scopes").
-
-Take a `browser_screenshot` after adding all scopes.
-
-### Step 7: Set redirect URL
-
-Check the `redirectUri` from the config:
-- If it mentions "not currently configured", `GATEWAY_BASE_URL`, or `INGRESS_PUBLIC_BASE_URL` — the user needs a public gateway URL configured. Check if one is set; if not, load the `public-ingress` skill first.
-- If it says "automatic" — skip this step entirely (no redirect URI needed).
-- Otherwise, enter the `redirectUri` exactly as provided.
-
-Take a `browser_snapshot` to confirm.
-
-### Step 7b: Extract credentials
-
-Navigate to the app's credentials/settings section.
-
-Use `browser_extract` to read:
-1. **Client ID** (or equivalent)
-2. **Client Secret** (if `requiresClientSecret` is true) — click "Show"/"Reveal" first if needed
-
----
-
-## Step 8: Connect
-
-Tell the user you're opening the authorization page.
-
-Use `credential_store` with:
-```
-action: "oauth2_connect"
-service: "<service name>"
-client_id: "<extracted client ID>"
-client_secret: "<extracted client secret>"  (if required)
-```
-
-Everything else (endpoints, scopes, params) is auto-filled from the well-known config. Wait for the flow to complete.
-
-## Step 9: Celebrate!
-
-Once connected, tell the user:
-- If `setup` is present: "**{setup.displayName} is connected!** You're all set."
-- If `setup` is absent: "**{service} is connected!** You're all set."
-
-Summarize what was accomplished.
-
-## Error Handling
-
-- **Page load failures:** Retry once. If it still fails, ask the user to check their connection.
-- **Element not found:** Take a fresh `browser_snapshot`. The provider's UI may have changed — adapt dynamically.
-- **User declines an approval gate:** Don't push back. Explain why it matters, offer to retry or cancel.
-- **OAuth flow timeout or failure:** Offer to retry. The app is already created, so only the connect step needs to be re-run.
-- **Any unexpected state:** Take a `browser_screenshot` and `browser_snapshot`, describe what you see, and ask for guidance.

package/src/config/bundled-skills/public-ingress/SKILL.md

@@ -1,258 +0,0 @@
----
-name: public-ingress
-description: Set up and manage ngrok-based public ingress for webhooks and OAuth callbacks via ingress.publicBaseUrl
-compatibility: "Designed for Vellum personal assistants"
-metadata: {"emoji":"🌍","vellum":{"display-name":"Public Ingress","user-invocable":true}}
----
-
-You are setting up and managing a public ingress tunnel so that external services (Telegram webhooks, OAuth callbacks, etc.) can reach the local Vellum gateway. This skill uses ngrok to create a secure tunnel and persists the public URL as `ingress.publicBaseUrl`.
-
-## Overview
-
-The Vellum gateway listens locally and needs a publicly reachable URL for:
-
-- Telegram webhook delivery
-- Google/Slack OAuth redirect callbacks
-- Any other inbound webhook traffic
-
-This skill installs ngrok, configures authentication, starts a tunnel, discovers the public URL, and saves it to the assistant's ingress config.
-
-## Step 1: Check Current Ingress Status
-
-First, check whether ingress is already configured:
-
-```bash
-assistant config get ingress.publicBaseUrl
-assistant config get ingress.enabled
-```
-
-Note: The local gateway target is `$INTERNAL_GATEWAY_BASE_URL` (e.g. `http://127.0.0.1:7830`).
-
-The commands return:
-
-- `ingress.publicBaseUrl` — currently configured public ingress URL (if any)
-- `ingress.enabled` — whether ingress is enabled
-
-If `publicBaseUrl` is already set and the tunnel is running (check via `curl -s http://127.0.0.1:4040/api/tunnels`), tell the user the current status and ask if they want to reconfigure or if this is sufficient.
-
-## Step 2: Install ngrok
-
-Check if ngrok is installed:
-
-```bash
-ngrok version
-```
-
-If not installed, install it:
-
-**macOS (Homebrew):**
-
-```bash
-brew install ngrok/ngrok/ngrok
-```
-
-**Linux (snap):**
-
-```bash
-sudo snap install ngrok
-```
-
-**Linux (apt — alternative):**
-
-```bash
-curl -sSL https://ngrok-agent.s3.amazonaws.com/ngrok.asc | sudo tee /etc/apt/trusted.gpg.d/ngrok.asc >/dev/null
-echo "deb https://ngrok-agent.s3.amazonaws.com buster main" | sudo tee /etc/apt/sources.list.d/ngrok.list
-sudo apt update && sudo apt install ngrok
-```
-
-After installation, verify with `ngrok version`.
-
-## Step 3: Authenticate ngrok
-
-Check if ngrok already has an auth token configured:
-
-```bash
-ngrok config check
-```
-
-If not authenticated:
-
-1. Tell the user: "You need an ngrok account to create tunnels. If you don't have one, sign up at https://dashboard.ngrok.com/signup — it's free."
-2. Once they have an account, use `credential_store` to securely collect their auth token. **Never ask the user to paste the token directly in chat.**
-
-   Use `credential_store` with:
-   - action: `prompt`
-   - service: `ngrok`
-   - field: `authtoken`
-   - label: `ngrok Auth Token`
-   - description: `Get your auth token from https://dashboard.ngrok.com/get-started/your-authtoken`
-   - usage_description: `ngrok authentication token for creating public tunnels`
-
-3. Once the credential is stored, retrieve it via `credential_store` and apply it to ngrok:
-
-   ```bash
-   credential_store action=get service=ngrok field=authtoken
-   ngrok config add-authtoken "<authtoken_from_credential_store>"
-   ```
-
-   If no value is returned, re-run `credential_store` with `action: "prompt"` and try again.
-
-Verify authentication succeeded by checking `ngrok config check` again.
-
-## Step 4: Start the Tunnel
-
-Before starting, check for an existing ngrok process to avoid duplicates:
-
-```bash
-curl -s http://127.0.0.1:4040/api/tunnels 2>/dev/null
-```
-
-If a tunnel is already running, check whether it points to the correct local target. If so, skip to Step 5. If it points elsewhere, stop it first:
-
-```bash
-pkill -f ngrok || true
-sleep 1
-```
-
-Start ngrok in the background, tunneling to the local gateway target:
-
-```bash
-nohup ngrok http "$INTERNAL_GATEWAY_BASE_URL" --log=stdout > /tmp/ngrok.log 2>&1 &
-echo $! > /tmp/ngrok.pid
-```
-
-Wait a few seconds for the tunnel to establish:
-
-```bash
-sleep 3
-```
-
-## Step 4b: Verify Port Alignment
-
-Before discovering the public URL, verify that ngrok is forwarding to the same port the gateway is actually listening on. A mismatch here causes silent failures — webhooks appear to be delivered but never reach the gateway.
-
-Query the ngrok tunnel's target port and the gateway's configured port, then compare them:
-
-```bash
-curl -s http://127.0.0.1:4040/api/tunnels | python3 -c "
-import sys, json, re
-
-data = json.load(sys.stdin)
-tunnels = data.get('tunnels', [])
-if not tunnels:
-    print('ERROR: no active ngrok tunnel found')
-    sys.exit(1)
-
-addr = tunnels[0].get('config', {}).get('addr', '')
-match = re.search(r':(\d+)$', addr)
-if not match:
-    print(f'ERROR: could not extract port from ngrok tunnel addr: {addr}')
-    sys.exit(1)
-
-print(match.group(1))
-"
-```
-
-```bash
-echo "$INTERNAL_GATEWAY_BASE_URL" | grep -oE '[0-9]+$'
-```
-
-Compare the two port numbers. If they differ, warn the user:
-
-> **Port mismatch detected:** ngrok is forwarding to port **X** but the gateway is listening on port **Y** (from `$INTERNAL_GATEWAY_BASE_URL`). Webhooks will not reach the gateway. Stop ngrok (`pkill -f ngrok`), then re-run this skill to start ngrok on the correct port.
-
-If the ports match, proceed silently to Step 5.
-
-## Step 5: Discover the Public URL
-
-Query the ngrok local API for the tunnel's public URL:
-
-```bash
-curl -s http://127.0.0.1:4040/api/tunnels | python3 -c "
-import sys, json
-data = json.load(sys.stdin)
-tunnels = data.get('tunnels', [])
-for t in tunnels:
-    url = t.get('public_url', '')
-    if url.startswith('https://'):
-        print(url)
-        sys.exit(0)
-for t in tunnels:
-    url = t.get('public_url', '')
-    if url:
-        print(url)
-        sys.exit(0)
-print('ERROR: no tunnel found')
-sys.exit(1)
-"
-```
-
-If no tunnel is found, check `/tmp/ngrok.log` for errors and report them to the user.
-
-## Step 6: Persist the Ingress Setting
-
-Save the discovered public URL and enable ingress:
-
-```bash
-assistant config set ingress.publicBaseUrl "<public-url>"
-assistant config set ingress.enabled true
-```
-
-Verify it was saved:
-
-```bash
-assistant config get ingress.publicBaseUrl
-assistant config get ingress.enabled
-```
-
-## Step 7: Report Completion
-
-Summarize the setup:
-
-- **Public URL:** `<the-url>` (this is your `ingress.publicBaseUrl`)
-- **Local gateway target:** `$INTERNAL_GATEWAY_BASE_URL`
-- **ngrok dashboard:** http://127.0.0.1:4040
-
-Provide useful follow-up commands:
-
-- **Check tunnel status:** `curl -s http://127.0.0.1:4040/api/tunnels | python3 -c "import sys,json; [print(t['public_url']) for t in json.load(sys.stdin)['tunnels']]"`
-- **View ngrok logs:** `cat /tmp/ngrok.log`
-- **Restart tunnel:** `pkill -f ngrok; sleep 1; nohup ngrok http "$INTERNAL_GATEWAY_BASE_URL" --log=stdout > /tmp/ngrok.log 2>&1 &`
-- **Stop tunnel:** `pkill -f ngrok`
-- **Rotate URL:** Stop and restart ngrok (free tier assigns a new URL each time; update `ingress.publicBaseUrl` afterward)
-
-**Important:** On ngrok's free tier, the public URL changes every time the tunnel restarts. After restarting, re-run this skill or manually update `ingress.publicBaseUrl` and any registered webhooks (e.g., Telegram).
-
-## Troubleshooting
-
-### ngrok not installed
-
-Run the install commands in Step 2. On macOS, make sure Homebrew is installed first (`brew --version`).
-
-### Auth token invalid or expired
-
-Sign in to https://dashboard.ngrok.com, copy a fresh token from the "Your Authtoken" page, and re-run Step 3.
-
-### ngrok API (port 4040) not responding
-
-The ngrok process may not be running. Check with `ps aux | grep ngrok`. If not running, start it per Step 4. If running but 4040 is unresponsive, check `/tmp/ngrok.log` for errors.
-
-### Gateway not reachable on local target
-
-Re-check the local gateway target with `echo "$INTERNAL_GATEWAY_BASE_URL"`. Run `curl -s "$INTERNAL_GATEWAY_BASE_URL/healthz"` to verify it is reachable. If the gateway is not running, start the assistant first.
-
-### "Too many connections" or tunnel limit errors
-
-ngrok's free tier allows one tunnel at a time. Stop any other ngrok tunnels before starting a new one.
-
-### ngrok port doesn't match gateway port
-
-**Symptom:** Webhooks return connection refused or timeouts even though both ngrok and the gateway appear to be running.
-
-**Cause:** ngrok is forwarding to a different port than the gateway is listening on. This can happen if the gateway port was changed after ngrok was started, or if ngrok was started manually with a hardcoded port.
-
-**Fix:** Stop ngrok (`pkill -f ngrok`), verify the gateway URL with `echo "$INTERNAL_GATEWAY_BASE_URL"`, then re-run this skill to start ngrok on the correct port.
-
-### ngrok automatically restarts with wrong port
-
-If after killing the ngrok process, it automatically re-spawns and is still attached to the incorrect port, check to see if there is a launch agent process configured to auto-restart it. This might exist at `~/Library/LaunchAgents/com.ngrok.tunnel.plist`. If so, it needs to be either removed or updated.

package/src/config/bundled-skills/reminder/SKILL.md

@@ -1,79 +0,0 @@
----
-name: reminder
-description: One-time time-based reminders that fire at a specific future time
-compatibility: "Designed for Vellum personal assistants"
-metadata: {"emoji":"🔔","vellum":{"display-name":"Reminder"}}
----
-
-Create, list, and cancel one-time reminders. Reminders fire at a specific future time and either notify the user or execute a message through the assistant.
-
-## Modes
-
-- **notify** (default) — shows a notification to the user when the reminder fires
-- **execute** — sends the reminder message to a background assistant conversation for autonomous handling
-
-## Routing
-
-Control how the reminder is delivered at trigger time with `routing_intent`:
-
-- **single_channel** — deliver to one best channel
-- **multi_channel** — deliver to a subset of channels
-- **all_channels** (default) — deliver to every available channel
-
-Optionally pass `routing_hints` (a JSON object) to influence routing decisions (e.g. preferred channels, exclusions). When omitted, defaults to `{}`.
-
-### Routing Defaults
-
-Use the following heuristics to pick `routing_intent`:
-
-- **Default to `all_channels`** for most reminders. Users setting reminders usually want to be notified wherever they are, and redundant notifications are less harmful than missed ones.
-- **Use `single_channel`** only when the user explicitly specifies a single channel (e.g. "remind me on Telegram") or the reminder is low-stakes and noise reduction matters.
-- **Check `user_message_channel`** from the turn context. If the user is currently active on a specific channel (e.g. `vellum`), always include that channel. Pass it as a routing hint:
-  ```
-  routing_hints: { preferred_channels: ["vellum"] }
-  routing_intent: "all_channels"
-  ```
-- **Never use `single_channel` as a passive default.** If you haven't thought about which channel to use, use `all_channels`.
-
-### Examples
-
-| Scenario | routing_intent | routing_hints |
-|---|---|---|
-| User sets reminder from desktop app | `all_channels` | `{ preferred_channels: ["vellum"] }` |
-| User says "remind me on Telegram" | `single_channel` | `{ preferred_channels: ["telegram"] }` |
-| User sets reminder from Telegram | `all_channels` | `{ preferred_channels: ["telegram"] }` |
-| No channel preference expressed | `all_channels` | `{}` |
-
-## Usage Notes
-
-- Use reminders ONLY for time-triggered notifications (e.g. "remind me at 3pm", "remind me in 2 hours").
-- For recurring automation, use schedules instead.
-- For task tracking ("add to my tasks", "add to my queue"), use task_list_add instead.
-- `fire_at` must be a strict ISO 8601 timestamp with timezone offset or Z (e.g. `2025-03-15T09:00:00-05:00` or `2025-03-15T09:00:00Z`). Ambiguous timestamps without timezone info will be rejected.
-- `label` is a short human-readable summary shown in the notification.
-
-### Anchored & Ambiguous Relative Time
-
-Phrases like "at the 45 minute mark", "at the top of the hour", "on the half-hour", "at noon", "20 minutes in", or "when I hit an hour" are **clock-position or anchored relative time** expressions. Do NOT treat them as offsets from now.
-
-**Resolution rules (in priority order):**
-
-1. **Session-anchored expressions** — if the user mentioned a start time earlier in conversation ("I got here at 9", "meeting started at 2:10"), interpret offset-style phrases ("the 45 minute mark", "20 minutes in", "when I hit an hour") as `start_time + offset`. This takes precedence because the conversational anchor overrides any wall-clock interpretation.
-
-2. **Clock-position expressions** — when no start time is in context, map directly to a wall-clock time:
-   - "top of the hour" / "on the hour" → next :00 (e.g. 10:00 AM)
-   - "the X minute mark" / "at :XX" → current hour's :XX; if already past, advance one hour
-   - "the half-hour mark" / "half past" → nearest upcoming :30
-   - "noon" / "midnight" → 12:00 PM or 12:00 AM today; if past, tomorrow
-   - "quarter past" / "quarter to" → :15 or :45 of current or next hour
-
-3. **Ask only if truly ambiguous** — if neither rule 1 nor rule 2 resolves, ask: "Do you mean [clock time] or [X minutes from now]?" Never silently default to "from now."
-
-**Examples:**
-- "meeting started at 2:10, remind me at the 45 minute mark" → 2:55 PM (start + 45 min)
-- "20 minutes in, I started at 2pm" → 2:20 PM (start + 20 min)
-- "at the 45 min mark" (no start time, now: 9:39) → 9:45 AM (wall-clock)
-- "at the 45 min mark" (no start time, now: 9:50) → 10:45 AM (wall-clock, next hour)
-- "top of the hour" (now: 9:39) → 10:00 AM
-- "at noon" → 12:00 PM today
-- "at the hour mark" with no start time → ask for clarification