synabun 1.3.0 → 2.0.0-beta

package/mcp-server/src/tools/youtube/dedup.ts

@@ -0,0 +1,57 @@
+/**
+ * YouTube trailer dedup — shared key logic.
+ *
+ * Every uploaded trailer is recorded as a SynaBun memory in the `youtube-videos`
+ * category, tagged with canonical, exact-match keys. youtube_source reads those
+ * keys (via sqlite.getPostedTrailerKeys) and drops any candidate that matches —
+ * so the model never even sees an already-posted trailer. This replaces the old
+ * fuzzy `recall` dedup, which returned only the top-K most-similar memories and
+ * let repeats slip through as the posted set grew.
+ *
+ * Key scheme (a candidate/upload is the same trailer if ANY key matches):
+ *   igdb:<igdbId>     exact IGDB game id            (IGDB/auto candidates)
+ *   appid:<appid>     exact Steam appid             (IGDB/auto/steam candidates)
+ *   ytid:<videoId>    exact source trailer video id (case-sensitive)
+ *   name:<normalized> game name, lowercased+stripped (cross-backend safety net —
+ *                     YouTube-search candidates carry no igdb/appid, so the name
+ *                     key is what catches a game already posted via IGDB, etc.)
+ */
+
+/** The dedup ledger category — one memory per uploaded trailer. */
+export const TRAILER_CATEGORY = 'youtube-videos';
+
+/** Lowercase + strip every non-alphanumeric char. "Hollow Knight: Silksong" → "hollowknightsilksong". */
+export function normalizeGameName(name?: string | null): string {
+  if (!name) return '';
+  return String(name).toLowerCase().normalize('NFKD').replace(/[^a-z0-9]+/g, '');
+}
+
+type TrailerIdentity = {
+  game?: string | null;
+  igdbId?: number | null;
+  appid?: number | null;
+  ytTrailerIds?: Array<string | null | undefined>;
+  sourceTrailerId?: string | null;
+};
+
+/** Canonical dedup keys for a youtube_source candidate. */
+export function candidateDedupKeys(c: TrailerIdentity): string[] {
+  const keys: string[] = [];
+  if (c.igdbId != null) keys.push(`igdb:${c.igdbId}`);
+  if (c.appid != null) keys.push(`appid:${c.appid}`);
+  for (const y of c.ytTrailerIds || []) if (y) keys.push(`ytid:${y}`);
+  const n = normalizeGameName(c.game);
+  if (n.length >= 3) keys.push(`name:${n}`);
+  return keys;
+}
+
+/** Tags written to the ledger memory on upload (dedup keys + human-readable labels). */
+export function ledgerTags(id: TrailerIdentity): string[] {
+  const tags = ['yt-posted', 'youtube', 'trailer'];
+  if (id.igdbId != null) tags.push(`igdb:${id.igdbId}`);
+  if (id.appid != null) tags.push(`appid:${id.appid}`);
+  if (id.sourceTrailerId) tags.push(`ytid:${id.sourceTrailerId}`);
+  const n = normalizeGameName(id.game);
+  if (n.length >= 3) tags.push(`name:${n}`);
+  return tags;
+}

package/mcp-server/src/tools/youtube/download.ts

@@ -0,0 +1,41 @@
+/**
+ * youtube_download — fetch a trailer to disk. Prefers a direct Steam mp4 URL
+ * (a plain HTTPS download of the publisher's own promo asset); falls back to
+ * yt-dlp for YouTube-only trailers. Delegates to /api/youtube/download.
+ */
+
+import { z } from 'zod';
+import * as ni from '../../services/neural-interface.js';
+import { text } from '../response.js';
+
+export const youtubeDownloadSchema = {
+  steamMp4Url: z.string().optional().describe('Direct Steam mp4 URL (from youtube_source steamMovies[].mp4). Preferred — no yt-dlp/ffmpeg required.'),
+  ytId: z.string().optional().describe('YouTube video id to download via yt-dlp (fallback for YouTube-only trailers).'),
+  url: z.string().optional().describe('Explicit video URL to download via yt-dlp.'),
+  appid: z.number().optional().describe('Steam appid — used only to name the output file.'),
+  filename: z.string().optional().describe('Base output filename (without extension). Defaults derived from ytId/appid.'),
+  quality: z.string().optional().describe('yt-dlp -f format string. Default: best video+audio ≤1080p, merged to mp4.'),
+  useCookies: z.boolean().optional().describe('Cookie fallback for the yt-dlp path. The server downloads cookieless first and only retries with browser cookies if YouTube demands auth (age/region/members-gated). Defaults on; pass false to hard-disable.'),
+};
+
+export const youtubeDownloadDescription =
+  'Download a trailer file. Prefers steamMp4Url (direct publisher asset, lowest copyright risk); otherwise yt-dlp on ytId/url. ' +
+  'Returns { filePath, bytes, source }. Pass filePath to youtube_upload. ' +
+  '[requires yt-dlp + ffmpeg on the host for the YouTube fallback path].';
+
+export async function handleYoutubeDownload(args: {
+  steamMp4Url?: string;
+  ytId?: string;
+  url?: string;
+  appid?: number;
+  filename?: string;
+  quality?: string;
+  useCookies?: boolean;
+}) {
+  if (!args.steamMp4Url && !args.ytId && !args.url) {
+    return text('Provide steamMp4Url (preferred), ytId, or url.');
+  }
+  const r = await ni.youtubeDownload(args);
+  if (r.error) return text(`Download failed: ${r.error}`);
+  return text(JSON.stringify({ filePath: r.filePath, bytes: r.bytes, source: r.source }, null, 2));
+}

package/mcp-server/src/tools/youtube/helpers.ts

@@ -0,0 +1,183 @@
+/**
+ * YouTube Studio — shared helpers.
+ *
+ * Studio (studio.youtube.com) is a Polymer / web-component app with heavy
+ * shadow DOM, so these tools prefer Playwright-native interactions
+ * (ni.click/fill/type/upload — Playwright's CSS engine pierces open shadow
+ * roots) over raw `document.querySelector` walking. Selectors favour stable,
+ * locale-independent Studio ids (`#create-icon`, `#title-textarea`,
+ * `#next-button`, `#done-button`, `tp-yt-paper-radio-button[name="PUBLIC"]`)
+ * with a `textHint` fallback for auto-heal.
+ */
+
+import * as ni from '../../services/neural-interface.js';
+
+export const STUDIO_BASE = 'https://studio.youtube.com';
+export const WATCH_BASE = 'https://www.youtube.com';
+
+export type Resolved = { sessionId: string; tabId?: string };
+
+export async function wait(ms: number): Promise<void> {
+  return new Promise((r) => setTimeout(r, ms));
+}
+
+export async function resolve(
+  sessionId?: string,
+  tabId?: string,
+  autoCreate = true,
+): Promise<Resolved | { error: string }> {
+  const r = await ni.resolveSession(sessionId, autoCreate ? { url: STUDIO_BASE } : undefined, tabId, { platform: true });
+  if ('error' in r) return r;
+  return { sessionId: r.sessionId, tabId: r.tabId };
+}
+
+/** Returns an error string if the session is bounced to a Google sign-in page. */
+export async function ensureAuth(r: Resolved): Promise<string | null> {
+  const res = await ni.evaluate(r.sessionId, `location.href`, r.tabId);
+  const url = String(res.result || '');
+  if (/accounts\.google\.com|\/signin|ServiceLogin/i.test(url)) {
+    return 'Not authenticated. Sign into the YouTube/Google account that owns the channel in the open browser panel, then retry.';
+  }
+  return null;
+}
+
+/**
+ * Poll a JS predicate every `interval` ms until truthy. `script` MUST evaluate
+ * to a JSON-serializable value; truthy → success, falsy → keep polling.
+ */
+export async function pollFor<T = unknown>(
+  r: Resolved,
+  script: string,
+  timeoutMs = 30000,
+  interval = 400,
+): Promise<T | null> {
+  const start = Date.now();
+  let last: T | null = null;
+  while (Date.now() - start < timeoutMs) {
+    const res = await ni.evaluate(r.sessionId, script, r.tabId);
+    if (!res.error) {
+      const v = res.result as T;
+      if (v) return v;
+      last = v;
+    }
+    await wait(interval);
+  }
+  return last;
+}
+
+/** Navigate with a one-time retry when the same browser session remains usable. */
+export async function safeNavigate(
+  r: Resolved,
+  url: string,
+): Promise<{ error?: string; sessionInvalidated?: boolean }> {
+  let res = await ni.navigate(r.sessionId, url, r.tabId);
+  if (res.error && !res.sessionInvalidated && /Timeout/i.test(res.error)) {
+    await wait(600);
+    res = await ni.navigate(r.sessionId, url, r.tabId);
+  }
+  return res;
+}
+
+/**
+ * Shadow-DOM-piercing text reader. Returns the visible text of the whole
+ * document (including open shadow roots) — used by pollFor predicates to detect
+ * Studio state transitions ("Upload complete", "Checks complete", etc.) that a
+ * plain `document.body.innerText` misses inside web components.
+ */
+export const DEEP_TEXT_SCRIPT = `(() => {
+  const out = [];
+  const walk = (root) => {
+    if (!root) return;
+    const els = root.querySelectorAll('*');
+    for (const el of els) {
+      if (el.shadowRoot) walk(el.shadowRoot);
+    }
+    const t = root.textContent;
+    if (t) out.push(t);
+  };
+  try { walk(document); } catch {}
+  return (document.body ? document.body.innerText : '') + ' ' + out.join(' ');
+})()`;
+
+/** Click a Studio element by Playwright selector, with a textHint auto-heal fallback. */
+export async function clickStudio(
+  r: Resolved,
+  selector: string,
+  textHint?: string,
+  nthMatch?: number,
+): Promise<{ ok: boolean; error?: string }> {
+  const res = await ni.click(r.sessionId, selector, nthMatch, r.tabId, textHint);
+  if (res.error) return { ok: false, error: res.error };
+  return { ok: true };
+}
+
+/**
+ * Fill a Studio text field. Playwright `fill` works on inputs, textareas AND
+ * `[contenteditable]` (Studio title/description are contenteditable `#textbox`
+ * nodes), clearing first. Falls back to click+type if fill rejects.
+ */
+export async function fillStudio(
+  r: Resolved,
+  selector: string,
+  value: string,
+  textHint?: string,
+): Promise<{ ok: boolean; error?: string }> {
+  const res = await ni.fill(r.sessionId, selector, value, undefined, r.tabId, textHint);
+  if (!res.error) return { ok: true };
+  // Fallback: focus then type (some contenteditable wrappers reject fill()).
+  const click = await ni.click(r.sessionId, selector, undefined, r.tabId, textHint);
+  if (click.error) return { ok: false, error: res.error };
+  const typed = await ni.type(r.sessionId, selector, value, undefined, r.tabId, textHint, 'insert');
+  if (typed.error) return { ok: false, error: typed.error };
+  return { ok: true };
+}
+
+/** Read the current video id from a Studio /video/<id>/edit URL, if present. */
+export async function currentVideoId(r: Resolved): Promise<string | null> {
+  const res = await ni.evaluate(
+    r.sessionId,
+    `(() => { const m = location.href.match(/\\/video\\/([A-Za-z0-9_-]{6,})\\//); return m ? m[1] : null; })()`,
+    r.tabId,
+  );
+  if (res.error) return null;
+  return (res.result as string | null) || null;
+}
+
+/**
+ * Fallback video-id resolver: open the Studio content grid (newest upload first)
+ * and return the top item's video id, piercing Studio's shadow DOM. Used by
+ * youtube_upload when the post-publish share dialog doesn't expose the id — right
+ * after an upload the just-published video is the most recent row, so the top id
+ * is it. Navigates away from the upload dialog, so only call once publishing is
+ * confirmed complete.
+ */
+export async function resolveLatestUploadedVideoId(r: Resolved): Promise<string | null> {
+  const cidRes = await ni.evaluate(
+    r.sessionId,
+    `(() => { const m = location.href.match(/\\/channel\\/(UC[\\w-]+)/); return m ? m[1] : null; })()`,
+    r.tabId,
+  );
+  const cid = (cidRes.result as string | null) || null;
+  const url = cid ? `${STUDIO_BASE}/channel/${cid}/videos/upload` : `${STUDIO_BASE}/channel/videos/upload`;
+  const nav = await safeNavigate(r, url);
+  if (nav.error) return null;
+  // Poll briefly — the grid lazy-loads.
+  return await pollFor<string>(
+    r,
+    `(() => {
+      const ids = [];
+      const walk = (root) => {
+        if (!root) return;
+        root.querySelectorAll('*').forEach((el) => { if (el.shadowRoot) walk(el.shadowRoot); });
+        root.querySelectorAll('a[href*="/video/"]').forEach((a) => {
+          const m = (a.getAttribute('href') || '').match(/\\/video\\/([A-Za-z0-9_-]{6,})\\//);
+          if (m) ids.push(m[1]);
+        });
+      };
+      try { walk(document); } catch {}
+      return ids[0] || null;
+    })()`,
+    8000,
+    600,
+  );
+}

package/mcp-server/src/tools/youtube/media.ts

@@ -0,0 +1,109 @@
+/**
+ * youtube_thumbnail — upload a custom thumbnail image to a video.
+ * youtube_endscreen — apply an end-screen template to a video.
+ * Both operate on the Studio video editor pages.
+ */
+
+import { z } from 'zod';
+import * as ni from '../../services/neural-interface.js';
+import { text } from '../response.js';
+import { STUDIO_BASE, resolve, ensureAuth, wait, pollFor, safeNavigate, clickStudio, type Resolved } from './helpers.js';
+
+const tabId = z.string().optional().describe('Target a specific tab. Auto-resolved if omitted.');
+
+// ── youtube_thumbnail ─────────────────────────────────────────
+
+export const youtubeThumbnailSchema = {
+  videoId: z.string().describe('YouTube video id.'),
+  filePath: z.string().describe('Absolute path to the thumbnail image (JPG/PNG, ≤2MB, 1280×720 recommended).'),
+  sessionId: z.string().optional(),
+  tabId,
+};
+
+export const youtubeThumbnailDescription =
+  'Upload a custom thumbnail to a video via its Studio edit page (uses the hidden thumbnail file input). Saves on completion. [mutating].';
+
+export async function handleYoutubeThumbnail(args: { videoId: string; filePath: string; sessionId?: string; tabId?: string }) {
+  const r = await resolve(args.sessionId, args.tabId);
+  if ('error' in r) return text(r.error);
+
+  const nav = await safeNavigate(r, `${STUDIO_BASE}/video/${args.videoId}/edit`);
+  if (nav.error) return text(`Navigation failed: ${nav.error}`);
+  const authErr = await ensureAuth(r);
+  if (authErr) return text(authErr);
+  const ready = await ni.waitFor(r.sessionId, { selector: '#title-textarea', state: 'visible', timeout: 20000 }, r.tabId);
+  if (ready.error) return text(`Edit page did not load: ${ready.error}`);
+  await wait(600);
+
+  // The thumbnail uploader uses <input id="file-loader" type="file">. Fall back
+  // to any file input inside the thumbnail editor if the id shifts.
+  let up = await ni.upload(r.sessionId, '#file-loader', [args.filePath], undefined, r.tabId);
+  if (up.error) {
+    up = await ni.upload(r.sessionId, 'ytcp-video-thumbnail-editor input[type="file"]', [args.filePath], undefined, r.tabId);
+  }
+  if (up.error) return text(`Thumbnail upload failed: ${up.error}. The video may still be processing, or it is too large.`);
+  await wait(1200);
+
+  const save = await clickStudio(r, '#save', 'Save');
+  if (!save.ok) return text(`Thumbnail set but could not click Save: ${save.error}.`);
+  const saved = await pollFor(r, `(() => /saved|Salvo|Changes saved/i.test(document.body.innerText) ? true : null)()`, 12000, 500);
+  return text(JSON.stringify({ videoId: args.videoId, thumbnail: 'uploaded', saved: !!saved }, null, 2));
+}
+
+// ── youtube_endscreen ─────────────────────────────────────────
+
+export const youtubeEndscreenSchema = {
+  videoId: z.string().describe('YouTube video id.'),
+  template: z.enum(['default', 'last_video_subscribe', 'import'] as const).optional().describe(
+    "Which end-screen layout to apply. 'default' = first built-in template; 'last_video_subscribe' = best-for-retention; 'import' = copy from your most recent video.",
+  ),
+  sessionId: z.string().optional(),
+  tabId,
+};
+
+export const youtubeEndscreenDescription =
+  'Apply an end-screen template to a video (links to a related video/playlist + a subscribe element) via the Studio end-screen editor, then save. [mutating]. End-screen editing is canvas-based and may need a manual touch-up.';
+
+export async function handleYoutubeEndscreen(args: {
+  videoId: string;
+  template?: 'default' | 'last_video_subscribe' | 'import';
+  sessionId?: string;
+  tabId?: string;
+}) {
+  const r = await resolve(args.sessionId, args.tabId);
+  if ('error' in r) return text(r.error);
+
+  const nav = await safeNavigate(r, `${STUDIO_BASE}/video/${args.videoId}/end_screens`);
+  if (nav.error) return text(`Navigation failed: ${nav.error}`);
+  const authErr = await ensureAuth(r);
+  if (authErr) return text(authErr);
+  await pollFor(r, `(() => /end screen|Tela final|Apply (a )?template|Aplicar modelo|Import|Importar/i.test(document.body.innerText) ? true : null)()`, 20000, 500);
+  await wait(800);
+
+  if (args.template === 'import') {
+    const imp = await clickStudio(r, '#import-button', 'Import from video');
+    if (imp.ok) {
+      await wait(900);
+      // Pick the first video in the import picker.
+      await clickStudio(r, 'ytve-import-video-row', undefined, 0);
+      await wait(600);
+      await clickStudio(r, '#import-button-in-dialog', 'Import');
+    }
+  } else {
+    // Apply a built-in template. The template gallery items are paper-items;
+    // 'last_video_subscribe' is typically the 2nd template, 'default' the 1st.
+    const applied = await clickStudio(r, '#templates-button', 'Apply template');
+    if (applied.ok) await wait(800);
+    const idx = args.template === 'last_video_subscribe' ? 1 : 0;
+    await clickStudio(r, 'ytve-template-picker-item, tp-yt-paper-item', undefined, idx);
+    await wait(700);
+  }
+
+  const save = await clickStudio(r, '#save-button', 'Save');
+  if (!save.ok) {
+    const alt = await clickStudio(r, '#save', 'Save');
+    if (!alt.ok) return text(`Applied an end-screen layout but could not click Save: ${save.error}. Finish in the browser panel.`);
+  }
+  const saved = await pollFor(r, `(() => /saved|Salvo|Changes saved/i.test(document.body.innerText) ? true : null)()`, 12000, 500);
+  return text(JSON.stringify({ videoId: args.videoId, endscreen: args.template || 'default', saved: !!saved }, null, 2));
+}

package/mcp-server/src/tools/youtube/metadata.ts

@@ -0,0 +1,112 @@
+/**
+ * youtube_metadata — edit metadata on an existing/just-uploaded video via the
+ * Studio video edit page (/video/<id>/edit): title, description, tags, category.
+ * Visibility/scheduling is handled by youtube_schedule.
+ */
+
+import { z } from 'zod';
+import * as ni from '../../services/neural-interface.js';
+import { text } from '../response.js';
+import { STUDIO_BASE, resolve, ensureAuth, wait, pollFor, safeNavigate, clickStudio, fillStudio, type Resolved } from './helpers.js';
+
+const tabId = z.string().optional().describe('Target a specific tab. Auto-resolved if omitted.');
+
+export const youtubeMetadataSchema = {
+  videoId: z.string().describe('YouTube video id to edit.'),
+  title: z.string().optional().describe('New title (≤100 chars).'),
+  description: z.string().optional().describe('New description (replaces existing).'),
+  tags: z.array(z.string()).optional().describe('Tags/keywords (replaces existing; revealed under "Show more").'),
+  category: z.string().optional().describe('Category name, e.g. "Gaming". Set via the Show-more category dropdown.'),
+  madeForKids: z.boolean().optional().describe('COPPA audience flag.'),
+  sessionId: z.string().optional(),
+  tabId,
+};
+
+export const youtubeMetadataDescription =
+  'Edit an existing video\'s metadata on its Studio edit page: title, description, tags, category, made-for-kids. Saves on completion. [mutating]. Use youtube_schedule for visibility/publish-time.';
+
+async function openEdit(r: Resolved, videoId: string): Promise<string | null> {
+  const nav = await safeNavigate(r, `${STUDIO_BASE}/video/${videoId}/edit`);
+  if (nav.error) return `Navigation failed: ${nav.error}`;
+  const authErr = await ensureAuth(r);
+  if (authErr) return authErr;
+  const ready = await ni.waitFor(r.sessionId, { selector: '#title-textarea', state: 'visible', timeout: 20000 }, r.tabId);
+  if (ready.error) return `Edit page did not load for ${videoId}: ${ready.error}`;
+  await wait(600);
+  return null;
+}
+
+export async function handleYoutubeMetadata(args: {
+  videoId: string;
+  title?: string;
+  description?: string;
+  tags?: string[];
+  category?: string;
+  madeForKids?: boolean;
+  sessionId?: string;
+  tabId?: string;
+}) {
+  if (!args.title && !args.description && !args.tags && !args.category && args.madeForKids === undefined) {
+    return text('Nothing to update — provide at least one of: title, description, tags, category, madeForKids.');
+  }
+  const r = await resolve(args.sessionId, args.tabId);
+  if ('error' in r) return text(r.error);
+
+  const openErr = await openEdit(r, args.videoId);
+  if (openErr) return text(openErr);
+
+  const changed: string[] = [];
+
+  if (args.title) {
+    const ok = await fillStudio(r, '#title-textarea #textbox', args.title.slice(0, 100), 'Add a title that describes your video');
+    if (ok.ok) changed.push('title');
+  }
+  if (args.description) {
+    const ok = await fillStudio(r, '#description-textarea #textbox', args.description, 'Tell viewers about your video');
+    if (ok.ok) changed.push('description');
+  }
+
+  // Tags + category live under "Show more".
+  if (args.tags?.length || args.category) {
+    await clickStudio(r, '#toggle-button', 'Show more');
+    await wait(700);
+  }
+  if (args.tags?.length) {
+    // Clear, then commit each tag with its own comma — a comma-joined blob only
+    // tokenizes the last tag.
+    await ni.fill(r.sessionId, '#tags-container #text-input', '', undefined, r.tabId, 'Tags').catch(() => {});
+    let anyTag = false;
+    for (const tag of args.tags) {
+      const tg = tag.trim();
+      if (!tg) continue;
+      const typed = await ni.type(r.sessionId, '#tags-container #text-input', `${tg},`, undefined, r.tabId, 'Tags', 'insert');
+      if (typed.error) break;
+      anyTag = true;
+      await wait(150);
+    }
+    if (anyTag) { await ni.pressKey(r.sessionId, 'Enter', r.tabId); changed.push('tags'); }
+  }
+  if (args.category) {
+    const dd = await clickStudio(r, '#category-container', 'Category');
+    if (dd.ok) {
+      await wait(600);
+      const opt = await clickStudio(r, `tp-yt-paper-item:has-text("${args.category}")`, args.category);
+      if (opt.ok) changed.push('category');
+      await wait(300);
+    }
+  }
+  if (args.madeForKids !== undefined) {
+    const kidsName = args.madeForKids ? 'VIDEO_MADE_FOR_KIDS_MFK' : 'VIDEO_MADE_FOR_KIDS_NOT_MFK';
+    const ok = await clickStudio(r, `tp-yt-paper-radio-button[name="${kidsName}"]`);
+    if (ok.ok) changed.push('madeForKids');
+    await wait(300);
+  }
+
+  // Save.
+  const save = await clickStudio(r, '#save', 'Save');
+  if (!save.ok) return text(`Updated [${changed.join(', ') || 'nothing'}] but could not click Save: ${save.error}.`);
+  // Locale-tolerant: match the "saved" success stems across en + pt-BR.
+  const saved = await pollFor(r, `(() => /saved|Salv|Changes saved|Alteraç|Atualizad/i.test(document.body.innerText) ? true : null)()`, 12000, 500);
+
+  return text(JSON.stringify({ videoId: args.videoId, updated: changed, saved: !!saved }, null, 2));
+}

package/mcp-server/src/tools/youtube/navigate.ts

@@ -0,0 +1,81 @@
+/**
+ * youtube_navigate — open a YouTube Studio section. Studio is channel-scoped
+ * (/channel/<UC…>/…); we resolve the active channel id from the URL after
+ * landing on the Studio root, then build section URLs (locale-independent).
+ * Tools: youtube_navigate
+ */
+
+import { z } from 'zod';
+import * as ni from '../../services/neural-interface.js';
+import { text } from '../response.js';
+import { STUDIO_BASE, resolve, ensureAuth, wait, pollFor, safeNavigate, type Resolved } from './helpers.js';
+
+const tabId = z.string().optional().describe('Target a specific tab. Auto-resolved if omitted.');
+
+const SECTIONS = ['dashboard', 'content', 'analytics', 'playlists', 'comments', 'subtitles', 'copyright', 'earn', 'customization'] as const;
+type Section = typeof SECTIONS[number];
+
+const SECTION_PATH: Record<Section, string> = {
+  dashboard: '',
+  content: '/videos/upload',
+  analytics: '/analytics/tab-overview/period-default',
+  playlists: '/playlists',
+  comments: '/comments/inbox',
+  subtitles: '/translations',
+  copyright: '/copyright',
+  earn: '/monetization',
+  customization: '/editing/channel',
+};
+
+/** Read the active Studio channel id (UC…) from the URL, if present. */
+export async function channelId(r: Resolved): Promise<string | null> {
+  const res = await ni.evaluate(
+    r.sessionId,
+    `(() => { const m = location.href.match(/\\/channel\\/(UC[\\w-]+)/); return m ? m[1] : null; })()`,
+    r.tabId,
+  );
+  if (res.error) return null;
+  return (res.result as string | null) || null;
+}
+
+/** Cache the resolved channel id per session — Studio's active channel doesn't
+ *  change within a session, so re-polling the root on every navigate is waste. */
+const channelIdCache = new Map<string, string>();
+
+export const youtubeNavigateSchema = {
+  section: z.enum(SECTIONS).describe('Studio section to open.'),
+  sessionId: z.string().optional().describe('Browser session ID. Auto-resolved or auto-created.'),
+  tabId,
+};
+
+export const youtubeNavigateDescription =
+  'Open a YouTube Studio section (dashboard, content, analytics, playlists, comments, subtitles, copyright, earn, customization). ' +
+  'Auto-creates a browser session on studio.youtube.com using the signed-in Google account. Call before other youtube_* browser tools.';
+
+export async function handleYoutubeNavigate(args: { section: Section; sessionId?: string; tabId?: string }) {
+  const r = await resolve(args.sessionId, args.tabId);
+  if ('error' in r) return text(r.error);
+
+  // Land on the Studio root first so the channel id resolves (Studio redirects
+  // studio.youtube.com → /channel/<id>). Use the cached id when we already have it.
+  let cid = channelIdCache.get(r.sessionId) || await channelId(r);
+  if (!cid) {
+    const nav = await safeNavigate(r, STUDIO_BASE);
+    if (nav.error) return text(`Navigation failed: ${nav.error}`);
+    const authErr = await ensureAuth(r);
+    if (authErr) return text(authErr);
+    await pollFor(r, `(() => /\\/channel\\/UC/.test(location.href) ? true : null)()`, 15000, 400);
+    cid = await channelId(r);
+  }
+  if (!cid) return text('Could not resolve the active channel. Make sure you are signed into a Google account that owns a YouTube channel.');
+  channelIdCache.set(r.sessionId, cid);
+
+  const url = `${STUDIO_BASE}/channel/${cid}${SECTION_PATH[args.section]}`;
+  const nav = await safeNavigate(r, url);
+  if (nav.error) return text(`Navigation failed: ${nav.error}`);
+  const authErr = await ensureAuth(r);
+  if (authErr) return text(authErr);
+  await wait(1000);
+
+  return text(`Opened Studio ${args.section} for channel ${cid} (${url}).`);
+}