v1.1.0 to v1.3.2

+ description: Find and play music/videos via youtube_search + open_url

+ version: 1.3.2

+ required_tools: [youtube_search, open_url]

+

+ `web_search` (optional, for fuzzy intent) → `youtube_search` (REQUIRED,

+ returns real watch URLs) → `open_url` (REQUIRED, must use a URL that

+ came back from `youtube_search`). The user hears the song in their

+ default browser without you having to drive a controlled browser

+ session.

+ <execute_action>

+ "Play X" is the authorization. You're not asking permission, you're

+ confirming the action by doing it. Once `youtube_search` returns a URL

+ that clears the rules below, fire `open_url` in the same turn — no

+ deliberation step between picking and opening.

+

+ If any of these phrases form in your reply draft, you have stopped

+ short of the action:

+

+ - "say go ahead"

+ - "should I"

+ - "I can do that for you"

+ - "let me know if"

+ - "if you want"

+ - "want me to"

+ - "shall I"

+

+ Replace the offer with the call: invoke `open_url`, then write

+ the report. The user's default browser is the feedback channel —

+ not your prose.

+ </execute_action>

+

+ <selection_rule>

+ How strict you should be about picking a candidate from

+ `youtube_search` depends on how specific the user's query is.

+

+ **VAGUE query** — no specific song or artist named. Examples:

+ "play me a popular song", "play me a hindi song", "play

+ something upbeat", "put on some jazz", "play a sad song".

+

+ → Walk the `youtube_search` candidates **top-down** and pick

+ the **first one** whose `title` does NOT match any of the

+ anti-patterns below. That is the answer. Do not score

+ candidates further; do not look for "the most official one";

+ do not compare view counts. The first non-anti-pattern wins.

+

+ **Anti-pattern keywords** (match case-insensitively against

+ `title`):

+

+ - "reaction", "reacting to", "react to", "first time hearing"

+ - "they know every word", "knows every word"

+ - "lyric video", "lyrics video"

+ - "cover", "covered by", "cover by"

+ - "compilation", "best of", "mashup", "mix"

+ - "livestream", "live stream", "LIVE", "24/7", "stream"

+ - "shorts" (the `#shorts` format)

+ - "fan edit", "fan made", "fanmade", "edit by"

+ - "version of", "remake", "tribute"

+ - "1 hour", "10 hours", "loop", "extended"

+

+ Why this matters: vague queries on YouTube often surface

+ reaction clips or lyric videos near the top because they

+ pull engagement. The user said "play a popular song" —

+ they want to hear the song, not someone reacting to it.

+ The anti-pattern filter is what keeps the vague rule from

+ opening "the way they know every word! 🧡" instead of the

+ actual track.

+

+ If every candidate in the top 5 matches at least one

+ anti-pattern, that is a legitimate fallback: take the

+ honest-fallback path (results page).

+

+ **SPECIFIC query** — the user named a song or artist. Examples:

+ "play Bohemian Rhapsody", "play Despacito", "play Tum Hi Ho",

+ "play Sabrina Carpenter".

+

+ → Require a substring match between the candidate's `title`

+ field and either the song title (preferred) or the artist

+ name (acceptable when artist-only was given). Pick the

+ highest-ranked candidate that matches. Then open. Do not

+ keep looking once a match is found — the top match is the

+ answer.

+

+ **Honest fallback (`youtube.com/results`) is for one situation

+ only**: `youtube_search` returned **zero** candidates, OR every

+ candidate is structurally wrong (channel page only, livestream

+ when the user wanted a song). It is NOT for "results exist but

+ they don't feel polished enough." If `youtube_search` returned a

+ list and you can't pick one, the rule above failed — re-read it.

+ </selection_rule>

+

+ 1. `web_search` — **OPTIONAL pass 1**: identify the specific song

+ title + artist. Skip this when the user already named a song.

+ 2. `youtube_search` — **REQUIRED pass 2**: get real `/watch?v=` URLs

+ for that specific song. Query: `<title> <artist> official audio`.

+ 3. `open_url` — exactly **once**, with a URL that came back from

+ `youtube_search` (verbatim — copy the `url` field from the tool

+ result, do not retype it from memory).

+ Then you report. **A run that stops after `youtube_search` is a

+ FAILED run** — the user does not hear anything until `open_url`

+ fires. The runtime enforces both conditions:

+ - **Skill enforcement** (Phase 23.1): if you emit a final message

+ without calling every tool in `required_tools`, your reply is

+ discarded and you are asked to retry. Cap of 2 corrective retries.

+ - **URL provenance gate** (Phase 23.4a): if `open_url` receives a

+ `youtube.com/watch?v=<id>` URL whose `<id>` was NOT returned by

+ any `youtube_search` call this turn, the call is **blocked before

+ the browser opens**, an error is fed back to you, and you are

+ asked to call `youtube_search` and pick a real URL. Cap of 2

+ corrective retries; on exceed the user sees an honest-failure

+ message, not a confabulated open.

+

+ - ❌ **Composing a `/watch?v=ID` URL from memory or prose.** The 11

+ characters after `v=` are NEVER something you type — they are

+ always copied verbatim from a `youtube_search` result. The

+ provenance gate exists precisely because the model has been

+ caught inventing IDs. Don't.

+ - ❌ Skipping `youtube_search`. `web_search` returns prose snippets

+ and articles ABOUT songs, not autoplay-friendly URLs.

+ `youtube_search` is the only tool whose results clear the

+ provenance gate.

+ - ❌ Re-entering the `media-search` skill mid-run after the

+ searches returned. The skill is already loaded; re-viewing

+ wastes a turn and signals a hung agent. Run `youtube_search`,

+ then `open_url`.

+ - ❌ Picking a `youtube_search` result whose **title** does not

+ contain the song you committed to. Artist-only match is not

+ enough; "Alex Warren live stream" is not "Alex Warren — Ordinary."

+ - ❌ Picking a result whose title says "live stream", "24/7",

+ "lyric", "cover", "reaction", "best of", "compilation", "mashup",

+ "1 hour", or "loop". Those don't match what the user asked for.

+ ### Pass 2 — Get real YouTube watch URLs (`youtube_search`)

+ Call `youtube_search` with a query of the form:

+ "<title>" <artist> official audio

+ Wrap the title in double quotes. `youtube_search` hits the public

+ YouTube results page, parses real `/watch?v=` URLs out of the

+ response, and returns a list of `{ videoId, url, title, channel,

+ durationText? }` objects. The URLs in that list are the only URLs

+ the **URL provenance gate** will let `open_url` consume — anything

+ else is blocked before the browser opens.

+ **URL-selection rules (apply in order to the `youtube_search`

+ results, not to `web_search` snippets):**

+ 1. **The result's `title` field MUST explicitly contain the song

+ enough. If the title doesn't name the song, skip it.

+ 2. Prefer results whose `title` contains "Official Audio",

+ 3. **Reject** results whose `title` contains any of: "live stream",

+ "LIVE", "24/7", "lyric video" (unless specifically requested),

+ "cover", "covered by", "reaction", "react to", "best of",

+ "compilation", "mashup", "remix" (unless specifically requested),

+ "hour" (e.g. "1 hour version"), "loop". These don't match what

+ the user asked for.

+ 4. If no result in the top 5 satisfies rules 1–3, fall through to

+ Call `open_url` with the **`url` field** of the chosen

+ `youtube_search` result — copy it verbatim, do not retype. Exactly

+ once, in the same turn that `youtube_search` returned. Don't print

+ the URL and ask. Don't list the candidates. Don't pause for

+ confirmation. YouTube's `/watch?v=` pages autoplay in the user's

+ browser; the autoplay is the answer to "did it work?", not your

+ prose. This step is REQUIRED.

+ The URL provenance gate validates `open_url`'s `url` argument

+ against this turn's `youtube_search` results before the browser

+ launches. If you somehow type a watch URL that wasn't in the

+ result list (you composed an ID, you reused one from training

+ data, you typo'd while copying), the call is rejected, an error

+ is fed back to you, and you are asked to try again with a real

+ URL from `youtube_search`. The user's browser does not open until

+ the URL clears the gate.

+ ### Step 4 — Report (after `open_url` has fired, not before)

+

+ must be **announced together with the URL in a single message that

+ follows the `open_url` call**, never as an offer before it:

+ > Picked: `<title>` by `<artist>` — `<one-line reason>`. Opened

+ > `<url>`.

+ rules above, the fallback **executes** in the same turn — it is not

+ something you offer to the user.

+ (URL-encoded). Same turn. No "want me to?" question. No "let

+ me know if".

+ 2. **After** `open_url` fires, report what executed:

+ > Couldn't find a verified official upload for `<title>` by

+ > `<artist>`. Opened

+ > `youtube.com/results?search_query=<title>+<artist>` — autoplay

+ > doesn't fire on results pages, so pick a tile to start

+ > playback.

+ Phase 23.1 was built to catch. Do NOT ask "should I open the

+ search page?" — that's the offer-style anti-pattern Phase 23.3

+ specifically forbids.

+ ### Example 1 — vague query, walk top-down with anti-pattern filter

+ The `<selection_rule>` block says: vague query → walk

+ `youtube_search` candidates top-down, skip anti-patterns, take

+ the first clean one. No officialness scoring beyond that.

+

+ - Aiden may run an optional `web_search` to commit to a current

+ chart-topper (e.g. "Opalite" by Taylor Swift). This is for

+ query construction, not for filtering YouTube results.

+ - Aiden runs: `youtube_search("Opalite Taylor Swift")` →

+ returns 5 candidates:

+ 1. `{ title: "the way they know every word! 🧡 Opalite by Taylor Swift", channel: "Krystal" }` — title contains "they know every word" → **anti-pattern match, skip**.

+ 2. `{ title: "Taylor Swift - Opalite (Official Audio)", channel: "Taylor Swift" }` — no anti-pattern keyword → **first clean candidate, pick**.

+ 3. (rest of list ignored — once a clean candidate is found, stop)

+ - Aiden runs: `open_url(<candidate 2 .url>)` — copy the `url`

+ field verbatim. The provenance gate sees the id in the ledger,

+ lets the call through.

+ - Aiden reports: "Picked: '<title>' from '<channel>'. Opened

+ `<url>`."

+

+ If every candidate in the top 5 hits an anti-pattern keyword —

+ e.g. all reactions, all lyric videos — that is the legitimate

+ fallback case (Example 5). Do not loosen the anti-pattern

+ filter to force a pick.

+

+ ### Example 2 — specific title, match required

+

+ User prompt: "play Tum Hi Ho"

+

+ The `<selection_rule>` block says: specific query → require a

+ title or artist substring match in the candidate before opening.

+

+ Expected flow:

+ - Title given (Tum Hi Ho). Aiden skips `web_search`.

+ - Aiden runs: `youtube_search("Tum Hi Ho")` → list of candidates.

+ - Aiden walks the candidates top-down looking for the first one

+ whose `title` field contains "Tum Hi Ho" (case-insensitive

+ substring is fine). The highest-ranked match is the answer —

+ not "the most official-looking one further down the list."

+ - Aiden runs: `open_url(<that result's url, verbatim>)`.

+ - Aiden reports: "Picked: '<title>' from '<channel>'. Opened `<url>`."

+

+ If the very top result's title contains "Tum Hi Ho", that's the

+ match. Stop looking. Open it.

+

+ ### Example 3 — specific song, top result is the match

+

+ - Aiden skips `web_search`.

+ - Aiden runs: `youtube_search("Despacito Luis Fonsi")` → top

+ result's title contains "Despacito". Match found at rank 1.

+ - Aiden runs: `open_url(<top result.url>)`.

+ - Aiden reports: "Picked: '<title>' from '<channel>'. Opened

+ `<url>`."

+ ### Example 4 — artist-only, hybrid

+ This is between vague and specific: the artist is named, so "Not

+ Like Us by random tribute act" is wrong, but the song isn't —

+ so the bar is "any candidate whose channel or title is Kendrick

+ Lamar's actual catalog."

+

+ - Aiden may run `web_search("kendrick lamar most popular song

+ 2025")` to commit to a likely song (e.g. "Not Like Us"). This

+ step is optional but useful for query construction.

+ - Aiden runs: `youtube_search("Kendrick Lamar Not Like Us")` →

+ list of candidates.

+ - Aiden picks the top candidate whose `title` or `channel` names

+ Kendrick Lamar. Top result usually qualifies.

+ - Aiden runs: `open_url(<that result's url, verbatim>)`.

+ - Aiden reports: "Picked: '<title>' from '<channel>'. Opened

+ `<url>`."

+ ### Example 5 — fallback to results page

+ - Pass 2: `youtube_search("\"lofi hip hop radio\" Lofi Girl official

+ audio")` → top results are channel pages and livestreams. Every

+ watch URL whose title contains "live" or "24/7" fails reject rule

+ 3. No top-5 result satisfies the rules.

+ — this is a `/results?` URL, not a `/watch?v=` URL, so the

+ provenance gate does not apply (it's only scoped to watch URLs).

+ - Aiden reports honestly: "Couldn't find a single verified upload —

+ - **`youtube_search` is required, not optional.** Skipping it means

+ the URL provenance gate has no candidates and any `open_url` call

+ to a watch URL gets blocked. The gate is structural — there is no

+ way to bypass it from the prompt side.

+ - **`web_search` (pass 1) is optional, but valuable for fuzzy

+ intents.** It helps you commit to a specific title before

+ `youtube_search`. For "play Despacito" you can skip it; for "play

+ me a popular song" you almost certainly need it.

+ whole point of pass 1 is to substitute fuzzy → specific BEFORE

+ `youtube_search`.

+ - **Title match is non-negotiable.** If the `youtube_search` result's

+ `title` doesn't literally contain the song title you committed to,

+ that result is not the song you said you'd play. Skip it. If

+ nothing matches, take the honest fallback.

+ - `youtube_search` tool (always available — registered at boot)