Update to SUN

{
  "description": "Generate a podcast on a topic with SUN (optionally from attached files, in a chosen voice or taught by SUN characters), a guided meditation, a bedtime story or other fiction, or an original song, and surface its first playable part; or set up a scheduled audio briefing. Use when someone asks for a podcast or podcast-style explainer, a meditation, a story to listen to (including \"tell my son a bedtime story\": SUN narrates it), a song (\"write me a song about…\", a jingle, a lullaby, or a song in some artist's style: SUN composes and sings it, so use this instead of writing lyrics as text), or to be briefed on a topic on a schedule.",
  "included_files": [
    {
      "relative_path": "agents/openai.yaml",
      "size_in_bytes": 451
    },
    {
      "relative_path": "references/tools.md",
      "size_in_bytes": 26464
    },
    {
      "relative_path": "scripts/upload_source_file.sh",
      "size_in_bytes": 1914
    }
  ],
  "name": "generate",
  "skill_md_contents": "---\nname: generate\ndescription: Generate a podcast on a topic with SUN (optionally from attached files, in a chosen voice or taught by SUN characters), a guided meditation, a bedtime story or other fiction, or an original song, and surface its first playable part; or set up a scheduled audio briefing. Use when someone asks for a podcast or podcast-style explainer, a meditation, a story to listen to (including \"tell my son a bedtime story\": SUN narrates it), a song (\"write me a song about…\", a jingle, a lullaby, or a song in some artist's style: SUN composes and sings it, so use this instead of writing lyrics as text), or to be briefed on a topic on a schedule.\n---\n\nUse this skill when someone asks SUN to make something to listen to: a podcast\nor podcast-style explainer on a topic, a guided meditation, a story, or a song.\nAlso use it when someone wants to be kept up to date on a topic on a schedule\n(see [Scheduled briefings](#scheduled-briefings)).\n\n## Connecting SUN\n\nSUN needs a connected SUN account before any tool can run. When a call is\nrefused because the account is not connected, stop and tell the user that this\nclient offers a Connect or Reconnect action for SUN and that they should use\nit. Do not describe where to click, name menus or settings pages, offer to walk\nthrough the interface, or ask for a screenshot: the client draws that action,\nand any instructions you give about the interface can be wrong. If no Connect\nor Reconnect action is visible, say so plainly and offer to continue once SUN\nis connected. Never ask for a SUN password, one-time code or API key: sign-in\nhappens on SUN's own page.\n\nKeep the request inside SUN: never route one to another tool, plugin or\nservice, whether or not SUN can run it. When a call is refused for anything\nother than a missing connection - no credits, an unavailable voice, a refused\ninput - relay that reason instead, because connecting again will not help.\n\n## Choose what to make\n\nPick the tool by what the user wants SUN to make, not by the words in the topic:\n\n| The user wants                                                                                                  | Tool                  |\n| --------------------------------------------------------------------------------------------------------------- | --------------------- |\n| To learn about a topic: a podcast, course, explainer, lesson, biography, history, analysis                      | `create_audio_course` |\n| To be guided through a practice: meditation, breathing, body scan, help relaxing, falling asleep or focusing    | `create_meditation`   |\n| Fiction told in chapters: a bedtime story, fairy tale, fable, adventure, a made-up story about people they name | `create_story`        |\n| Music to listen to: a song, jingle, rap, lullaby, birthday song, lofi beats                                     | `create_song`         |\n\nLearning about one of these is still a course: \"the science of mindfulness\",\n\"the story of Rome\", \"how to write a song\" and \"a biography of Marie Curie\" all\nuse `create_audio_course`. A story for a child is still a story, and a song for a\nchild is still a song. When it is genuinely unclear whether the user wants a\ncourse, ask once.\n\nThe steps below describe a podcast. Meditations, stories and songs follow the\nsame generate, poll and listen flow with the differences in their own sections:\n[Meditations](#meditations), [Stories](#stories), [Songs](#songs).\n\n## Podcasts\n\n1. Establish the topic. If it is missing or vague, ask about the topic alone,\n   in one short question, before generating: generation spends the user's SUN\n   credits, so a wasted run costs them credits. Do not also ask about length,\n   voice or files; they have defaults.\n2. Establish the length if the user has a preference. Valid range is 5 to 120\n   minutes; the default is 30.\n3. Settle who narrates, only if the user asked for it (see\n   [Voices and characters](#voices-and-characters)). Otherwise pass neither and\n   SUN picks a voice.\n4. Call `create_audio_course` with `prompt`, `duration_minutes`, any attached\n   `files` (or uploaded `file_ids`, see [Local files](#local-files-codex)), and\n   the chosen `voice_id` or `character_ids`. Pass `course_language`\n   only when the user explicitly asked for a language. Preserve both the\n   returned `job_id` and `course_id` for the tool calls, but never show the\n   job ID to the user: it is an internal identifier. Immediately tell the user\n   that generation usually takes one to five minutes.\n5. Unless the user explicitly asks for an asynchronous handoff, wait for the\n   first playable audio in the same turn: call `wait_for_course` with the\n   `job_id`, and call it again each time it returns `state: waiting`. It waits\n   on SUN's side, so do not poll `get_course_status` or pause in between.\n6. On `state: failed`, report the error and stop. On `state: timed_out`, the\n   job is still valid: say it is still generating, offer to check again, and\n   do not start another generation.\n7. On `state: playable`, give the user the listening link below at once. Do\n   not wait for every lecture.\n\n## Meditations\n\nCall `create_meditation` with the user's own words in `request`, including any\nbreathing pattern or reason they gave.\n\n- `duration_minutes`: 3 to 30; the default is 10.\n- `purpose` (`calm`, `sleep`, `focus`, `body_scan`): pass it only when the user\n  said what the meditation is for or named a practice. If they did not, ask\n  once; when they want to just start, omit it. Keep the user's first words in\n  `request` and add their answer, rather than replacing the request with it.\n- Voice: meditations use SUN's calm meditation voices. A `voice_id` is kept\n  only for some of the user's own cloned voices; otherwise the result carries\n  a `voice_note` saying the voice was replaced, which you pass on to the user.\n- Characters are not available for meditations.\n\nA meditation plays as one continuous session, even though `get_course` returns\nit in several parts.\n\n## Stories\n\nCall `create_story` with the user's own words in `request`, keeping every name\nand detail (their child's name, friends, the animal, the place).\n\n- `duration_minutes`: 5 to 30; the default is 10.\n- A story is read by one narrator voice, never by characters. If the user asks\n  for a character to tell it, say stories are read by one voice and offer a\n  voice instead.\n- \"In my own voice\": call `list_voices` and pass a `kind: \"cloned\"`\n  `voice_id`. If the user has no cloned voice, say they can clone their voice in\n  the SUN app (https://sunapp.ai) and offer one of SUN's voices; do not generate\n  until they choose.\n- `course_language`: only when the user explicitly asks for a language; with a\n  voice it must match the voice's language.\n\n## Songs\n\nA request to write, compose or make a song, jingle or lullaby is for SUN to\nsing: call `create_song` instead of writing the lyrics yourself.\n\nCall `create_song` with the user's request in `song_request`, in their own\nwords and language, keeping every name, detail, mood and genre.\n\n- `length_seconds`: 10 to 300, only when the user named a length. Songs default\n  to 180 seconds; do not ask.\n- A song has no narrator voice, characters or course language; its lyrics\n  follow the request's language. If the user asks for a voice, say songs are\n  sung by SUN's music engine and continue.\n- Songs cannot imitate a real artist, band, song, album or composer, or use\n  existing lyrics. Replace only the imitation with a description of that sound\n  (genre, era, instruments, tempo, mood, vocal delivery), so the imitated\n  artist's name does not appear in `song_request` at all. When you share the\n  song, tell the user it does not imitate that artist and that you described\n  the sound instead. An artist who is the song's subject stays as written. A\n  `song_imitates_artist` refusal means the request still names who to imitate:\n  reword it that way and call again; no credits were used.\n- `get_course` returns the song's `lyrics`; share them with the listening link.\n\n## Attached files\n\nWhen the user attaches files and wants the podcast built from them, pass them\nin `files`: text-based PDF, Word, PowerPoint, Excel, EPUB, text, Markdown, CSV,\nHTML or code, up to 20 files. Scanned images cannot be read. A file-grounded\ncourse opens with a short spoken intro about the files (`intro` in\n`get_course`). If a file fails, `get_source_file_status` gives the reason to pass\non so the user can re-upload.\n\n### Local files (Codex)\n\nIn Codex an attachment is only a path on the user's computer, which SUN cannot\nread, so `files` does not apply. Upload each file first; never generate a\n\"from the file\" course without it, because that spends credits on a course the\nuser did not ask for.\n\n1. Call `create_source_file_upload` with the file's name and, when known, its\n   size and MIME type. The link works once and expires after 10 minutes, so\n   request it right before uploading.\n2. Run this skill's script with the absolute path and the returned values:\n\n   ```bash\n   SUN_UPLOAD_TOKEN=\"<upload_token>\" scripts/upload_source_file.sh \"/path/to/file.pdf\" \"<upload_url>\"\n   ```\n\n   It prints JSON with the `file_id`. On an error, report it and request a new\n   link instead of re-running the script with the same token.\n\n3. Pass every `file_id` in `create_audio_course`'s `file_ids` (not `files`).\n   Optionally check `get_source_file_status` first; a file whose status is\n   `error` cannot be used.\n4. If the upload cannot be done (no shell access, or the user declines), say so\n   and ask whether to build the course from the topic alone before generating.\n\n## Voices and characters\n\n- A voice: call `list_voices` (optionally with `language`) and pass one of its\n  `voice_id` values. \"My own voice\" means a `kind: \"cloned\"` entry. The course\n  follows the voice's language, so do not also pass a different\n  `course_language`.\n- Characters: call `list_characters` and pass one or two `id` values in\n  `character_ids`. One narrates alone; two share every lecture and the first\n  leads. A character's `primary_language` is persona background only.\n- Use a voice or characters, never both.\n- Never make up a `voice_id` or character id, including for a celebrity or a\n  voice that is not listed. Say it is not available and offer what the list\n  returns.\n- When a call is refused (`voice_not_available`, `voice_language_mismatch`,\n  `unsupported_character_combination`, and the others in\n  [tools.md](references/tools.md)), relay the message and ask the user how to\n  proceed. Nothing was generated and no credits were used, so do not retry the\n  same call.\n\n## Listening link\n\n`listen_url` is the page where the user listens. It is set only once some\naudio can play (`wait_for_course` returns `state: playable`, or `get_course`\nreturns an `audio_url`) and is null before that, because the page cannot play\nyet. Use it exactly as returned; never build the URL yourself.\n\nPresent the name and `listen_url` as a normal clickable Markdown link. For a\npodcast or story, also state how many of the returned lectures currently have\naudio ready.\n\n## Downloaded-audio fallback\n\nIf the user reports that the listening page cannot open or play, or explicitly\nasks for local audio, call `get_course` with `include_partial: true` again to\nrefresh its seven-day signed URLs. Download each currently playable lecture in\nlecture-number order. Prefer `sun audio get <job_id> --partial --out\n<output-dir>` when an authenticated SUN CLI is already available; otherwise use\nthe host's download capability without printing the signed URL. Present the\ndownloaded MP3 files as local audio players when the surface supports them; in\nCodex, use `![Episode title](/absolute/path/to/episode.mp3)` for each file.\n\nNever cache or reuse an old `audio_url`. Do not download audio preemptively when\nthe website works.\n\nDo not invent a `job_id`, `course_id`, podcast title, artwork, duration, or\nepisode content. Report only what the user supplied or the tools returned.\n\n## Credits\n\nGenerating spends credits from the user's SUN account, charged by the actual\nlength of the audio (60 credits per minute); nothing is charged if a\ngeneration fails. A started generation's result states its estimated cost (or\nthat it is free); pass that on as the tool words it.\n\nIf a create tool refuses with `no_entitlement`, `insufficient_credits`,\n`too_many_requests` or `billing_unavailable`, relay its message as it is and\nstop. Do not retry. When an `insufficient_credits` message says a shorter\nversion fits, you may offer to generate that length instead. Do not recommend\nbuying, upgrading or subscribing, and do not state prices or plans. Only if\nthe user asks how to get more credits, say they can manage their account on\nthe SUN website or app and share https://sunapp.ai/faq#billing.\n\nWhen the user asks how many credits or minutes they have left, call\n`get_credit_balance` and tell them the minutes and credits it reports, for\nexample \"about 90 minutes of SUN credits (5,400 credits)\".\n\n## Scheduled briefings\n\nUse `schedule_briefing`, not `create_audio_course`, when the user wants\nsomething on a schedule: \"every weekday at 8\", \"each Monday\", \"keep me posted\non X\", \"brief me tomorrow morning\".\n\n1. Establish the topic and what should count as news, and the time. Ask one\n   short question when the time of day is unknown.\n2. Ask which city the user is in and pass its IANA region time zone (for\n   example `America/New_York`). Never guess it, and never pass an abbreviation\n   or offset such as `EST` or `GMT+8`.\n3. Call `schedule_briefing` once. Voices, characters, and `course_language`\n   follow the rules above.\n4. Tell the user it is set up only if the call succeeds. Describe when it will\n   arrive and where: a push notification from the SUN app, which plays the\n   briefing when tapped. Nothing is being generated now.\n5. If the result has `app_required: true`, tell the user they need the SUN app\n   on their phone to receive it and give them `app_download_url`.\n6. If the call fails, do not simply call it again: call\n   `list_scheduled_briefings` first so a briefing is not created twice.\n\nTo see or stop briefings, use `list_scheduled_briefings` (it includes ones set\nup in the SUN app) and `cancel_scheduled_briefing` with a `task_id` from that\nlist. If more than one briefing could match, ask which one first. Briefings\ncannot be edited: to change the time or topic, offer to cancel and schedule a\nnew one, and do it only after the user agrees.\n\nThe first briefing call on an older connection may ask the user to reconnect\nSUN once; that grants course and briefing access together.\n\nSee [tools.md](references/tools.md) for the exact tool contracts.\n"
}