{"record":{"id":"f45dcc45b059ecca","repo":"jackwener/OpenCLI","slug":"session-required","errorCode":"session_required","errorMessage":"Browser session is required.","messagePattern":"Browser session is required\\.","errorType":"error_code","errorClass":"CommandFailure","httpStatus":null,"severity":"error","filePath":"extension/src/background.ts","lineNumber":400,"sourceCode":"  lifecycle?: LeaseLifecycle;\n};\nconst sessionOverrides = new Map<string, SessionOverrides>();\n\nfunction setSessionOverride(key: string, patch: SessionOverrides): void {\n  sessionOverrides.set(key, { ...sessionOverrides.get(key), ...patch });\n}\n\n/** Commands currently executing per lease — idle release is deferred while > 0. */\nconst activeCommandCounts = new Map<string, number>();\nconst LEASE_KEY_SEPARATOR = '\\u0000';\n\nfunction getLeaseKey(session: string, surface: BrowserSurface): string {\n  return `${surface}${LEASE_KEY_SEPARATOR}${encodeURIComponent(session)}`;\n}\n\nfunction getSessionName(session?: string): string {\n  const raw = session?.trim();\n  if (!raw) throw new CommandFailure(\n    'session_required',\n    'Browser session is required.',\n    'Pass a browser session name, e.g. opencli browser <session> <command>.',\n  );\n  return raw;\n}\n\nfunction getCommandSurface(cmd: Pick<Command, 'surface' | 'session'>): BrowserSurface {\n  return cmd.surface === 'adapter' ? 'adapter' : 'browser';\n}\n\nfunction getSurfaceFromKey(key: string): BrowserSurface {\n  return key.split(LEASE_KEY_SEPARATOR, 1)[0] === 'adapter' ? 'adapter' : 'browser';\n}\n\nfunction getSessionFromKey(key: string): string {\n  const idx = key.indexOf(LEASE_KEY_SEPARATOR);\n  if (idx === -1) return key;","sourceCodeStart":382,"sourceCodeEnd":418,"githubUrl":"https://github.com/jackwener/OpenCLI/blob/49907e53dc3ade5c223ff0c4c2c2785687cec4e6/extension/src/background.ts#L382-L418","documentation":"getSessionName validates that a browser session name was supplied to extension/background command routing; an empty, whitespace-only, or missing session string throws CommandFailure with code 'session_required'. The extension multiplexes multiple named browser sessions, so every lease/container operation must name its target session.","triggerScenarios":"Invoking an extension browser command via 'opencli browser <session> <command>' with the session token omitted or only whitespace, so the router calls getSessionName(undefined/'' /'   ').","commonSituations":"Typing 'opencli browser status' instead of 'opencli browser mysession status'; scripts that interpolated an empty session variable; callers migrating from single-session versions of the CLI.","solutions":["Include a session name in the command: opencli browser <session> <command>","Check your script for an empty SESSION variable being interpolated","List existing sessions to pick a valid name before running the command"],"exampleFix":"// before\nawait runBrowserCommand({ args: ['status'] });\n// after\nconst session = process.env.OPENCLI_SESSION;\nif (!session?.trim()) throw new Error('OPENCLI_SESSION is not set');\nawait runBrowserCommand({ args: [session, 'status'] });","handlingStrategy":"validation","validationCode":"const session = args[0];\nif (typeof session !== 'string' || !session.trim()) {\n  throw new Error('Usage: opencli browser <session> <command>');\n}","typeGuard":"const hasSession = (s) => typeof s === 'string' && s.trim().length > 0;","tryCatchPattern":"try {\n  await run(cmdArgs);\n} catch (e) {\n  if (e.code === 'session_required') {\n    console.error('A browser session name is required: opencli browser <session> <command>');\n  } else throw e;\n}","preventionTips":["Always pass the session name positionally after 'browser' in commands","Interpolate session from a validated env var, not raw unset variables","Add a usage assertion in wrapper scripts before invoking the CLI"],"tags":["argument","session","cli-usage","validation"],"backgroundTag":"missing-required-argument","analyzedSha":"49907e53dc3ade5c223ff0c4c2c2785687cec4e6","analyzedAt":"2026-08-29T08:14:47.543Z","schemaVersion":2},"datasetVersion":"2026-08-29T12:17:43.993Z"}