pstack-dsh 0.2.3

package/src/client/poteto-defaults.ts

@@ -0,0 +1,37 @@
+import type { PstackRole } from '../roles.ts'
+
+// Upstream 0.15 recommendations are display copy, never runtime route defaults.
+const GROK = 'grok-4.6-fast-xhigh'
+const SOL = 'gpt-5.6-sol-max'
+const FABLE = 'claude-fable-5-1-thinking-max'
+const PANEL = `${FABLE}, ${SOL}, ${GROK}, claude-opus-5-thinking-xhigh`
+
+export const POTETO_DEFAULT_SLUGS = {
+  feature: GROK,
+  refactoring: GROK,
+  'bug-fix': FABLE,
+  'perf-issue': FABLE,
+  hillclimb: FABLE,
+  'judgment-and-prose': FABLE,
+  'hardest-tasks': FABLE,
+  'how-explorer': GROK,
+  'how-explainer': FABLE,
+  'why-investigators': GROK,
+  'why-synthesizer': FABLE,
+  'reflect-tooling': SOL,
+  'reflect-judgment': FABLE,
+  'swarm-workers': GROK,
+  'independent-verifier': '',
+  'poteto-agent': '',
+  'comment-sicko': '',
+  'how-critics': '',
+  'arena-runners': PANEL,
+  'arena-cross-judge-pool': PANEL,
+  'architect-runners': PANEL,
+  'interrogate-reviewers': PANEL,
+} as const satisfies Record<PstackRole, string>
+
+export function potetoNoteCopy(role: PstackRole, prefix: string): string {
+  const slugs = POTETO_DEFAULT_SLUGS[role]
+  return slugs.length === 0 ? '' : `${prefix}${slugs}`
+}

package/src/frontmatter.ts

@@ -0,0 +1,73 @@
+const NAME_RE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/
+
+export interface SkillFrontmatter {
+  name: string
+  description: string
+  whenToUse?: string
+  modelInvocable: boolean
+  userInvocable: boolean
+}
+
+export interface ParsedSkill {
+  frontmatter: SkillFrontmatter
+  content: string
+}
+
+function unquote(value: string): string {
+  const trimmed = value.trim()
+  if (
+    (trimmed.startsWith('"') && trimmed.endsWith('"'))
+    || (trimmed.startsWith("'") && trimmed.endsWith("'"))
+  ) {
+    return trimmed.slice(1, -1)
+  }
+  return trimmed
+}
+
+function parseBool(value: string | undefined, fallback: boolean): boolean {
+  if (value === undefined) return fallback
+  const normalized = unquote(value).trim().toLowerCase()
+  if (['true', 'yes', 'on', '1'].includes(normalized)) return true
+  if (['false', 'no', 'off', '0'].includes(normalized)) return false
+  throw new Error(`invalid boolean "${value}"`)
+}
+
+/**
+ * Minimal YAML frontmatter reader for SKILL.md.
+ * Official keys: name, description, whenToUse, disable-model-invocation, user-invocable.
+ * `packages/skill/skill-filesystem/README.md`.
+ */
+export function parseSkillMarkdown(text: string, fallbackName: string): ParsedSkill | undefined {
+  if (!text.startsWith('---')) return undefined
+  const end = text.indexOf('\n---', 3)
+  if (end < 0) return undefined
+  const raw = text.slice(4, end)
+  const body = text.slice(end + 4).replace(/^\s*\n/, '')
+  const fields: Record<string, string> = {}
+  for (const line of raw.split('\n')) {
+    const match = /^([A-Za-z0-9_-]+):\s*(.*)$/.exec(line)
+    if (!match) continue
+    fields[match[1]!] = match[2] ?? ''
+  }
+  let name = unquote(fields.name ?? fallbackName)
+  if (name === 'Poteto Mode') name = 'poteto-mode'
+  if (!NAME_RE.test(name)) return undefined
+  const description = unquote(fields.description ?? '')
+  if (description.length === 0) return undefined
+  try {
+    const disableModel = parseBool(fields['disable-model-invocation'], false)
+    const userInvocable = parseBool(fields['user-invocable'], true)
+    return {
+      frontmatter: {
+        name,
+        description,
+        ...fields.whenToUse ? { whenToUse: unquote(fields.whenToUse) } : {},
+        modelInvocable: !disableModel,
+        userInvocable,
+      },
+      content: body.trimStart(),
+    }
+  } catch {
+    return undefined
+  }
+}

package/src/home.ts

@@ -0,0 +1,13 @@
+import { homedir } from 'node:os'
+import { join, resolve } from 'node:path'
+
+/** Official precedence: `$DSH_HOME`, then `~/.dsh`. `packages/util/home-paths/README.md`. */
+export function resolveDshHome(env: NodeJS.ProcessEnv = process.env): string {
+  const fromEnv = env.DSH_HOME?.trim()
+  if (fromEnv) return resolve(fromEnv)
+  return join(homedir(), '.dsh')
+}
+
+export function dshHomeDisplay(env: NodeJS.ProcessEnv = process.env): string {
+  return env.DSH_HOME?.trim() ? '$DSH_HOME' : '~/.dsh'
+}

package/src/http-trust.ts

@@ -0,0 +1,38 @@
+import type { IncomingMessage, ServerResponse } from 'node:http'
+
+/** Loopback + same-origin. Copied shape from dsh-oauth-login `src/auth-routes.ts`. */
+export function trustedRequest(req: IncomingMessage): boolean {
+  const remote = req.socket.remoteAddress
+  if (remote !== '127.0.0.1' && remote !== '::1' && remote !== '::ffff:127.0.0.1') return false
+  if (req.headers['sec-fetch-site'] === 'cross-site') return false
+  const host = req.headers.host
+  if (host === undefined) return false
+  const origin = req.headers.origin
+  if (origin === undefined) return true
+  try {
+    return new URL(origin).host === new URL(`http://${host}`).host
+  } catch {
+    return false
+  }
+}
+
+export function json(res: ServerResponse, status: number, value: unknown): void {
+  res.writeHead(status, {
+    'content-type': 'application/json; charset=utf-8',
+    'cache-control': 'no-store',
+    'x-content-type-options': 'nosniff',
+  })
+  res.end(JSON.stringify(value))
+}
+
+export async function readJson(req: IncomingMessage, maxBytes = 262144): Promise<unknown> {
+  const chunks: Buffer[] = []
+  let size = 0
+  for await (const chunk of req) {
+    size += chunk.length
+    if (size > maxBytes) throw new Error('request body too large')
+    chunks.push(chunk as Buffer)
+  }
+  if (chunks.length === 0) return {}
+  return JSON.parse(Buffer.concat(chunks).toString('utf8')) as unknown
+}

package/src/ids.ts

@@ -0,0 +1,39 @@
+/** Startup line `dshx verify-boot` looks for. */
+export const BOOT_MARKER = '[my-plugins/pstack-dsh] loaded'
+
+/** Cordis plugin / Loader row id. */
+export const PLUGIN_ID = 'pstack-dsh'
+
+/** Bundled skill provider name on `ctx.skills`. */
+export const SKILL_PROVIDER_NAME = 'pstack-dsh'
+
+/** Overlay file under `$DSH_HOME`. */
+export const OVERLAY_FILENAME = 'pstack-dsh.json'
+
+/** DSH-owned OAuth store from dsh-oauth-login. Never ~/.pi / ~/.codex / ~/.claude / grok CLI. */
+export const OAUTH_AUTH_FILENAME = '.dsh-oauth-auth.json'
+export const OAUTH_AUTH_LEGACY_FILENAME = '.pi-login-auth.json'
+
+/** Antigravity OAuth store from dsh-antigravity-oauth. */
+export const ANTIGRAVITY_AUTH_FILENAME = '.dsh-antigravity-oauth.json'
+export const ANTIGRAVITY_PROVIDER = 'agy-google-antigravity'
+
+/** Official DeepSeek adapter. `packages/llm/llm-deepseek/src/index.ts` `PROVIDER`, `DEFAULT_API_KEY_ENV`. */
+export const DEEPSEEK_API_KEY_ENV = 'DEEPSEEK_API_KEY'
+export const DEEPSEEK_PROVIDER = 'deepseek-official'
+
+/** Model-facing tool names this plugin registers. */
+export const TOOL_CATALOG = 'pstack_catalog'
+export const TOOL_SPAWN = 'pstack_spawn'
+export const TOOL_OVERLAY_READ = 'pstack_overlay_read'
+export const TOOL_OVERLAY_WRITE = 'pstack_overlay_write'
+
+/** Default in-process spawn provider. `packages/bundle/base/cordis.patch.yml` `providerName: spawn`. */
+export const SPAWN_PROVIDER = 'spawn'
+
+/** Settings nav id. Official slot `settings.section` (`packages/client/ui-settings/src/client/contract/slots.ts`). */
+export const SETTINGS_SECTION_ID = 'pstack'
+
+/** Same-origin Web routes. Pattern: dsh-oauth-login `src/auth-routes.ts`. */
+export const SETTINGS_SNAPSHOT_PATH = '/plugins/pstack-dsh/settings'
+export const SETTINGS_SAVE_PATH = '/plugins/pstack-dsh/settings'

package/src/index.ts

@@ -0,0 +1,85 @@
+/**
+ * pstack-dsh: DeepSeek Harness port of official pstack.
+ * Function/namespace plugin: named apply, no default export.
+ */
+
+import type { Context } from '@deepseek-ai/cordis'
+import type {} from '@deepseek-ai/dsh-agent'
+import type {} from '@deepseek-ai/dsh-host-webserver'
+import { ReasoningEffortId } from '@deepseek-ai/dsh-llm'
+import type {} from '@deepseek-ai/dsh-skill'
+import { defineTool } from '@deepseek-ai/dsh-tools'
+import { snapshotJsonValue, type JsonValue } from '@deepseek-ai/dsh-util-values'
+import { PLUGIN_ID, SPAWN_PROVIDER } from './ids.ts'
+import { Config, type Config as PluginConfig } from './plugin-config.ts'
+import { createSkillProvider } from './skills-provider.ts'
+import { RoleEffortMap } from './request-overlay.ts'
+import {
+  catalogTool,
+  overlayReadTool,
+  overlayWriteTool,
+  spawnTool,
+  type ToolHost,
+} from './tools.ts'
+import { registerPstackSettingsRoutes } from './settings-routes.ts'
+
+export const name = PLUGIN_ID
+export const inject = ['tools', 'skills']
+export { Config }
+export type { PluginConfig as ConfigType }
+
+const JSON_OUTPUT = {
+  schema: { type: 'json' as const },
+  render: (_args: unknown, value: JsonValue) => [{ type: 'text' as const, text: JSON.stringify(value, null, 2) }],
+}
+
+function asHost(ctx: Context, config: PluginConfig | undefined, roles: RoleEffortMap): ToolHost {
+  return {
+    get llm() { return ctx.get('llm') as ToolHost['llm'] },
+    get credentials() { return ctx.get('credentials') as ToolHost['credentials'] },
+    get settings() { return ctx.get('settings') as ToolHost['settings'] },
+    get subagents() { return ctx.get('subagents') as ToolHost['subagents'] },
+    spawnProvider: config?.spawnProvider ?? SPAWN_PROVIDER,
+    roles,
+  }
+}
+
+function registerOne(ctx: Context, tool: ReturnType<typeof catalogTool>): void {
+  ctx.tools.register(defineTool({
+    name: tool.name,
+    description: tool.description,
+    parameters: tool.parameters,
+    output: JSON_OUTPUT,
+    async execute(args: Record<string, unknown>, exec: { signal?: AbortSignal; agent?: { id: string } }): Promise<JsonValue> {
+      const snapshot = snapshotJsonValue(await tool.execute(args, exec))
+      if (snapshot === undefined) throw new TypeError(`pstack tool ${tool.name} returned a non-JSON value`)
+      return snapshot as JsonValue
+    },
+  }))
+}
+
+export function apply(ctx: Context, config?: PluginConfig): void {
+  console.log('[my-plugins/pstack-dsh] loaded')
+  const roles = new RoleEffortMap()
+  const host = asHost(ctx, config, roles)
+  registerOne(ctx, catalogTool(host))
+  registerOne(ctx, overlayReadTool(host))
+  registerOne(ctx, overlayWriteTool(host))
+  registerOne(ctx, spawnTool(host))
+  ctx.skills.registerProvider(() => createSkillProvider())
+  ctx.inject(['webServer', 'connection'], webCtx => {
+    registerPstackSettingsRoutes(webCtx, host)
+  })
+
+  ctx.on('agent/request', async (payload, next) => {
+    const base = await next()
+    const binding = roles.lookup(payload.agent.id)
+    if (binding === undefined) return base
+    return {
+      ...base,
+      ...binding.provider ? { provider: binding.provider } : {},
+      ...binding.model ? { model: binding.model } : {},
+      ...binding.reasoningEffort ? { reasoningEffort: ReasoningEffortId(binding.reasoningEffort) } : {},
+    }
+  })
+}

package/src/overlay-model.ts

@@ -0,0 +1,139 @@
+import { ALL_ROLES, isPanelRole, isPstackRole, type PstackRole } from './roles.ts'
+import type { LiveRoute } from './catalog-types.ts'
+
+export const OVERLAY_VERSION = 1 as const
+
+export interface OverlayRoute {
+  readonly provider: string
+  readonly model: string
+  /** Adapter-owned effort id for this exact route. Omit when the route has no effort field. */
+  readonly reasoningEffort?: string
+}
+
+export interface OverlayRole {
+  /** Child inherits the parent conversation route and effort. */
+  readonly inherit: boolean
+  /** One spawn per entry. Empty when inherit is true. */
+  readonly routes: OverlayRoute[]
+}
+
+export interface Overlay {
+  readonly version: typeof OVERLAY_VERSION
+  readonly roles: Record<string, OverlayRole>
+}
+
+export function emptyOverlay(): Overlay {
+  const roles: Record<string, OverlayRole> = {}
+  for (const role of ALL_ROLES) {
+    roles[role] = { inherit: true, routes: [] }
+  }
+  return { version: OVERLAY_VERSION, roles }
+}
+
+export function routeKey(provider: string, model: string): string {
+  return `${provider}::${model}`
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+function parseRoute(raw: unknown, path: string): OverlayRoute {
+  if (!isRecord(raw)) throw new Error(`${path} must be an object`)
+  const provider = raw.provider
+  const model = raw.model
+  if (typeof provider !== 'string' || provider.length === 0) {
+    throw new Error(`${path}.provider must be a non-empty string`)
+  }
+  if (typeof model !== 'string' || model.length === 0) {
+    throw new Error(`${path}.model must be a non-empty string`)
+  }
+  const effort = raw.reasoningEffort
+  if (effort !== undefined && (typeof effort !== 'string' || effort.length === 0)) {
+    throw new Error(`${path}.reasoningEffort must be a non-empty string when set`)
+  }
+  const extra = Object.keys(raw).filter(key => key !== 'provider' && key !== 'model' && key !== 'reasoningEffort')
+  if (extra.length > 0) throw new Error(`${path} has unknown fields: ${extra.join(', ')}`)
+  return effort === undefined
+    ? { provider, model }
+    : { provider, model, reasoningEffort: effort }
+}
+
+function parseRole(raw: unknown, role: string): OverlayRole {
+  if (!isRecord(raw)) throw new Error(`roles.${role} must be an object`)
+  const extra = Object.keys(raw).filter(key => key !== 'inherit' && key !== 'routes')
+  if (extra.length > 0) throw new Error(`roles.${role} has unknown fields: ${extra.join(', ')}`)
+  const inherit = raw.inherit === true
+    || raw.inherit === 'true'
+    || raw.inherit === 'inherit-parent'
+    || raw.inherit === 'auto'
+  const routesRaw = raw.routes
+  const routes = Array.isArray(routesRaw)
+    ? routesRaw.map((entry, index) => parseRoute(entry, `roles.${role}.routes[${index}]`))
+    : []
+  if (inherit) return { inherit: true, routes: [] }
+  if (routes.length === 0) return { inherit: true, routes: [] }
+  if (!isPanelRole(role) && routes.length !== 1) {
+    throw new Error(`roles.${role} is a scalar role and may have at most one route`)
+  }
+  return { inherit: false, routes }
+}
+
+export function parseOverlay(text: string): Overlay {
+  let value: unknown
+  try {
+    value = JSON.parse(text) as unknown
+  } catch {
+    throw new Error('pstack-dsh overlay is not valid JSON')
+  }
+  if (!isRecord(value)) throw new Error('pstack-dsh overlay must be an object')
+  if (value.version !== OVERLAY_VERSION) {
+    throw new Error(`pstack-dsh overlay version ${String(value.version)} is unsupported`)
+  }
+  const extra = Object.keys(value).filter(key => key !== 'version' && key !== 'roles')
+  if (extra.length > 0) throw new Error(`pstack-dsh overlay has unknown fields: ${extra.join(', ')}`)
+  const rolesRaw = value.roles
+  if (!isRecord(rolesRaw)) throw new Error('pstack-dsh overlay.roles must be an object')
+  const roles: Record<string, OverlayRole> = {}
+  for (const role of ALL_ROLES) {
+    const entry = rolesRaw[role]
+    roles[role] = entry === undefined ? { inherit: true, routes: [] } : parseRole(entry, role)
+  }
+  for (const key of Object.keys(rolesRaw)) {
+    if (!isPstackRole(key)) throw new Error(`unknown pstack role "${key}"`)
+  }
+  return { version: OVERLAY_VERSION, roles }
+}
+
+export function validateOverlayAgainstCatalog(overlay: Overlay, routes: readonly LiveRoute[]): string[] {
+  const errors: string[] = []
+  const live = new Map(routes.filter(route => route.selectable).map(route => [routeKey(route.provider, route.model), route]))
+  for (const role of ALL_ROLES) {
+    if (role === 'how-critics') continue
+    const assignment = overlay.roles[role] ?? { inherit: true, routes: [] }
+    if (assignment.inherit) continue
+    for (const [index, entry] of assignment.routes.entries()) {
+      const found = live.get(routeKey(entry.provider, entry.model))
+      if (found === undefined) {
+        errors.push(`${role}[${index}]: ${entry.provider}/${entry.model} is not a logged-in live route`)
+        continue
+      }
+      if (entry.reasoningEffort === undefined) continue
+      if (found.efforts.length === 0) {
+        errors.push(`${role}[${index}]: ${entry.provider}/${entry.model} has no effort field; omit reasoningEffort`)
+        continue
+      }
+      if (!found.efforts.some(effort => effort.id === entry.reasoningEffort)) {
+        errors.push(
+          `${role}[${index}]: effort "${entry.reasoningEffort}" is not accepted by ${entry.provider}/${entry.model} (live: ${found.efforts.map(effort => effort.id).join(', ')})`,
+        )
+      }
+    }
+  }
+  return errors
+}
+
+export function resolveRole(overlay: Overlay, role: string): OverlayRole {
+  const key = role as PstackRole
+  return overlay.roles[key] ?? { inherit: true, routes: [] }
+}

package/src/overlay.ts

@@ -0,0 +1,40 @@
+import { readFile } from 'node:fs/promises'
+import { join } from 'node:path'
+import { writeFileAtomic } from '@deepseek-ai/dsh-atomic-write'
+import { OVERLAY_FILENAME } from './ids.ts'
+import { resolveDshHome } from './home.ts'
+import { emptyOverlay, parseOverlay, type Overlay } from './overlay-model.ts'
+
+export {
+  OVERLAY_VERSION,
+  emptyOverlay,
+  parseOverlay,
+  routeKey,
+  resolveRole,
+  validateOverlayAgainstCatalog,
+} from './overlay-model.ts'
+export type { Overlay, OverlayRole, OverlayRoute } from './overlay-model.ts'
+
+export function overlayPath(dshHome = resolveDshHome()): string {
+  return join(dshHome, OVERLAY_FILENAME)
+}
+
+export async function readOverlay(dshHome = resolveDshHome()): Promise<{ path: string; overlay: Overlay; missing: boolean }> {
+  const path = overlayPath(dshHome)
+  try {
+    const text = await readFile(path, 'utf8')
+    return { path, overlay: parseOverlay(text), missing: false }
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') {
+      return { path, overlay: emptyOverlay(), missing: true }
+    }
+    throw error
+  }
+}
+
+export async function writeOverlay(overlay: Overlay, dshHome = resolveDshHome()): Promise<string> {
+  const path = overlayPath(dshHome)
+  const body = `${JSON.stringify(overlay, null, 2)}\n`
+  await writeFileAtomic(path, body, { mode: 0o600, dirMode: 0o700 })
+  return path
+}

package/src/persona.ts

@@ -0,0 +1,38 @@
+import { readFile } from 'node:fs/promises'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { normalizeRole } from './roles.ts'
+
+export function defaultAgentsRoot(): string {
+  return join(dirname(fileURLToPath(import.meta.url)), '..', 'agents')
+}
+
+function stripFrontmatter(text: string): string {
+  if (!text.startsWith('---')) return text
+  const end = text.indexOf('\n---', 3)
+  if (end < 0) return text
+  return text.slice(end + 4).replace(/^\s*\n/, '')
+}
+
+/**
+ * Persona for a pstack role. Official spawn persona shadows deployment persona
+ * (`SubagentStartRequest.persona`, `packages/subagent/subagent/src/types.ts`).
+ */
+export async function loadPersona(role: string, agentsRoot = defaultAgentsRoot()): Promise<string | undefined> {
+  const key = normalizeRole(role)
+  const files = key === 'comment-sicko'
+    ? ['comment-sicko.md']
+    : key === 'poteto-agent'
+      ? ['poteto-agent.md']
+      : [`${key}.md`, 'poteto-agent.md']
+  for (const file of files) {
+    try {
+      const text = await readFile(join(agentsRoot, file), 'utf8')
+      const body = stripFrontmatter(text).trim()
+      if (body.length > 0) return body
+    } catch {
+      continue
+    }
+  }
+  return undefined
+}

package/src/plugin-config.ts

@@ -0,0 +1,29 @@
+/**
+ * Standard Schema v1 Config. Loader validates before apply.
+ * Avoids a hard schemastery import so the package still typechecks without DSH.
+ */
+
+export interface Config {
+  /** In-process subagent provider name. Default `spawn`. */
+  spawnProvider?: string
+}
+
+export const Config = {
+  '~standard': {
+    version: 1 as const,
+    vendor: 'pstack-dsh',
+    validate(value: unknown) {
+      if (value === undefined || value === null) {
+        return { value: { spawnProvider: 'spawn' } }
+      }
+      if (typeof value !== 'object' || Array.isArray(value)) {
+        return { issues: [{ message: 'config must be an object' }] }
+      }
+      const spawnProvider = (value as { spawnProvider?: unknown }).spawnProvider
+      if (spawnProvider !== undefined && (typeof spawnProvider !== 'string' || spawnProvider.length === 0)) {
+        return { issues: [{ message: 'spawnProvider must be a non-empty string' }] }
+      }
+      return { value: { spawnProvider: spawnProvider ?? 'spawn' } }
+    },
+  },
+}

package/src/request-overlay.ts

@@ -0,0 +1,40 @@
+export class RoleEffortMap {
+  private readonly bySession = new Map<string, { role: string; reasoningEffort?: string; provider?: string; model?: string }>()
+
+  remember(sessionId: string, binding: { role: string; reasoningEffort?: string; provider?: string; model?: string }): void {
+    this.bySession.set(sessionId, binding)
+  }
+
+  forget(sessionId: string): void {
+    this.bySession.delete(sessionId)
+  }
+
+  lookup(sessionId: string) {
+    return this.bySession.get(sessionId)
+  }
+}
+
+export interface CallConfig {
+  provider: string
+  model: string
+  reasoningEffort?: string
+  temperature?: number
+  maxTokens?: number
+  stop?: string[]
+}
+
+/**
+ * Apply overlay effort/route on the child request waterfall.
+ * Official home is `LlmCallConfig.reasoningEffort` (`packages/llm/llm/src/call-config.ts`),
+ * not a spawn-tool field. `agent/request` is the replacement waterfall
+ * (`packages/core/agent/src/runtime-types.ts`).
+ */
+export function applyRoleConfig(base: CallConfig, binding: { reasoningEffort?: string; provider?: string; model?: string } | undefined): CallConfig {
+  if (binding === undefined) return base
+  return {
+    ...base,
+    ...binding.provider ? { provider: binding.provider } : {},
+    ...binding.model ? { model: binding.model } : {},
+    ...binding.reasoningEffort ? { reasoningEffort: binding.reasoningEffort } : {},
+  }
+}

package/src/roles.ts

@@ -0,0 +1,55 @@
+/**
+ * pstack role keys used by playbooks and Settings → pstack.
+ * These are pstack names, not Cursor slugs and not grok-build `subagent_type` values.
+ */
+
+export const SCALAR_ROLES = [
+  'feature',
+  'refactoring',
+  'bug-fix',
+  'perf-issue',
+  'hillclimb',
+  'judgment-and-prose',
+  'hardest-tasks',
+  'how-explorer',
+  'how-explainer',
+  'why-investigators',
+  'why-synthesizer',
+  'reflect-tooling',
+  'reflect-judgment',
+  'swarm-workers',
+  'independent-verifier',
+  'poteto-agent',
+  'comment-sicko',
+] as const
+
+export const PANEL_ROLES = [
+  'how-critics',
+  'arena-runners',
+  'arena-cross-judge-pool',
+  'architect-runners',
+  'interrogate-reviewers',
+] as const
+
+export const ALL_ROLES = [...SCALAR_ROLES, ...PANEL_ROLES] as const
+
+export type ScalarRole = (typeof SCALAR_ROLES)[number]
+export type PanelRole = (typeof PANEL_ROLES)[number]
+export type PstackRole = (typeof ALL_ROLES)[number]
+
+export function isPstackRole(value: string): value is PstackRole {
+  return (ALL_ROLES as readonly string[]).includes(value)
+}
+
+export function isPanelRole(value: string): value is PanelRole {
+  return (PANEL_ROLES as readonly string[]).includes(value)
+}
+
+/** Alias accepted from Cursor-era skills. */
+export function normalizeRole(raw: string): string {
+  const trimmed = raw.trim()
+  if (trimmed === 'Comment Sicko' || trimmed === 'comment sicko') return 'comment-sicko'
+  if (trimmed === 'poteto-agent' || trimmed === 'Poteto Agent') return 'poteto-agent'
+  if (trimmed === 'generalPurpose' || trimmed === 'general-purpose') return 'poteto-agent'
+  return trimmed
+}