@gkzhb/pi-roles 0.2.4-beta.1

package/dist/index.js

@@ -0,0 +1,957 @@
+// src/schemas.ts
+import { Type } from "typebox";
+var ThinkingLevelSchema = Type.Union(
+  [
+    Type.Literal("off"),
+    Type.Literal("minimal"),
+    Type.Literal("low"),
+    Type.Literal("medium"),
+    Type.Literal("high"),
+    Type.Literal("xhigh")
+  ],
+  { description: "Reasoning effort level. 'off' for non-reasoning models." }
+);
+var IntercomModeSchema = Type.Union(
+  [
+    Type.Literal("off"),
+    Type.Literal("receive"),
+    Type.Literal("send"),
+    Type.Literal("both")
+  ],
+  { description: "Per-role intercom mode. Defaults to global intercomMode setting when omitted." }
+);
+var RoleScopeSchema = Type.Union(
+  [Type.Literal("user"), Type.Literal("project"), Type.Literal("both")],
+  { description: "Which scopes to search when discovering roles." }
+);
+var RoleSourceSchema = Type.Union(
+  [Type.Literal("project"), Type.Literal("user"), Type.Literal("built-in")],
+  { description: "Origin of a discovered role file." }
+);
+var RoleFrontmatterSchema = Type.Object(
+  {
+    /** Unique identifier; must match the filename without `.md`. */
+    name: Type.String({ minLength: 1, description: "Role identifier; matches the filename." }),
+    /** One-line description shown in /role list and pickers. */
+    description: Type.String({
+      minLength: 1,
+      description: "Short human-readable description of what the role is for."
+    }),
+    /**
+     * Model identifier in `provider/id` or `id` form. Resolved against Pi's
+     * model registry at apply time. If the model isn't available, we warn
+     * and keep the session's current model.
+     */
+    model: Type.Optional(Type.String({ description: "Model id; e.g. 'anthropic/claude-opus-4-7'." })),
+    /** Reasoning level. Clamped to model capabilities by Pi. */
+    thinking: Type.Optional(ThinkingLevelSchema),
+    /**
+     * Tool list as a raw, comma-separated string. Empty string means "no
+     * tools". Use the `mcp:server-name` syntax for MCP tools (requires
+     * pi-mcp-adapter at runtime). Parse and tri-state semantics live in
+     * `roles.ts`. We accept `null` because YAML's `tools:` (no value)
+     * deserializes to that.
+     */
+    tools: Type.Optional(
+      Type.Union([Type.String(), Type.Null()], {
+        description: "Comma-separated tool names. Empty/null = no tools. Use mcp:server-name for MCP tools."
+      })
+    ),
+    /** Per-role intercom mode override. Falls back to global `intercomMode`. */
+    intercom: Type.Optional(IntercomModeSchema),
+    /**
+     * Name of a parent role to inherit from. Resolved against the same scope
+     * the child was loaded from, then user, then built-in. Cycles are a hard
+     * error.
+     */
+    extends: Type.Optional(
+      Type.String({ minLength: 1, description: "Parent role name to inherit from." })
+    )
+  },
+  {
+    additionalProperties: true,
+    description: "Role frontmatter. Unknown fields are tolerated for forward compatibility; check warnings."
+  }
+);
+var PiRolesSettingsSchema = Type.Object(
+  {
+    /** "user" | "project" | "both". Default: "both". */
+    roleScope: Type.Optional(RoleScopeSchema),
+    /**
+     * Default role name applied when no --role / PI_ROLE is supplied.
+     * Default: "role-assistant" (the built-in fallback).
+     * If set to a missing role, we warn and use the built-in role-assistant.
+     */
+    defaultRole: Type.Optional(Type.String({ minLength: 1 })),
+    /**
+     * Keep the currently active role when creating a normal new conversation.
+     * Default: false, so new conversations resolve defaultRole as usual.
+     * Does not apply to --reset, reload, resume, or process restarts.
+     */
+    preserveRoleOnNewSession: Type.Optional(Type.Boolean()),
+    /** Default intercom mode for roles that don't set `intercom:`. Default: "off". */
+    intercomMode: Type.Optional(IntercomModeSchema),
+    /**
+     * Model used to summarize the first user message into the session-name
+     * intent. Default: a small/cheap model when one is available, falling
+     * back to the session's current model.
+     */
+    titleModel: Type.Optional(Type.String({ minLength: 1 })),
+    /** Whether to surface a warning when an mcp:* tool can't be resolved. Default: true. */
+    warnOnMissingMcp: Type.Optional(Type.Boolean())
+  },
+  {
+    additionalProperties: true,
+    description: "pi-roles section of Pi's settings.json."
+  }
+);
+var ActiveRoleStateSchema = Type.Object(
+  {
+    name: Type.String(),
+    /** Source of the LEAF role file when it was applied. */
+    source: RoleSourceSchema,
+    /** Path of the LEAF role file. */
+    path: Type.String(),
+    /** Cached session-intent summary for the title. May be empty pre-first-message. */
+    intent: Type.Optional(Type.String()),
+    /** Unix ms timestamp; for diagnostics only. */
+    appliedAt: Type.Number()
+  },
+  { additionalProperties: false }
+);
+var ACTIVE_ROLE_ENTRY_TYPE = "pi-roles:active-role";
+var ROLE_NOTIFICATION_MESSAGE_TYPE = "pi-roles:notification";
+var STATUS_KEY = "pi-roles";
+var BUILTIN_ROLE_ASSISTANT_NAME = "role-assistant";
+var INTENT_PLACEHOLDER = "Intent not defined";
+
+// src/debug.ts
+import { appendFileSync } from "fs";
+var ENABLED = process.env.PI_ROLES_DEBUG && process.env.PI_ROLES_DEBUG.length > 0;
+var LOG_PATH = process.env.PI_ROLES_DEBUG_PATH || "/tmp/pi-roles-debug.log";
+function now() {
+  return (/* @__PURE__ */ new Date()).toISOString();
+}
+function debugLog(label, message, extra) {
+  if (!ENABLED) return;
+  try {
+    const line = extra !== void 0 ? `[${now()}] [${label}] ${message} | extra=${JSON.stringify(extra)}
+` : `[${now()}] [${label}] ${message}
+`;
+    appendFileSync(LOG_PATH, line);
+  } catch {
+  }
+}
+
+// src/apply.ts
+function parseModelId(raw) {
+  const idx = raw.indexOf("/");
+  if (idx <= 0 || idx === raw.length - 1) return { id: raw };
+  return { provider: raw.slice(0, idx), id: raw.slice(idx + 1) };
+}
+function findModelInRegistry(registry, raw) {
+  const { provider, id } = parseModelId(raw);
+  if (provider) {
+    return { model: registry.find(provider, id), ambiguous: false };
+  }
+  const matches = registry.getAll().filter((m) => m.id === id);
+  return { model: matches[0], ambiguous: matches.length > 1 };
+}
+function effectiveIntercomMode(role, globalDefault) {
+  return role.intercom ?? globalDefault ?? "off";
+}
+function filterToolsForRuntime(directive, availableToolNames, intercomMode, intercomAvailable, warnOnMissingMcp) {
+  const warnings = [];
+  if (directive.kind === "inherit") {
+    return { kind: "inherit", warnings };
+  }
+  const kept = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const name of directive.names) {
+    if (seen.has(name)) continue;
+    seen.add(name);
+    if (name.startsWith("mcp:")) {
+      if (availableToolNames.has(name)) {
+        kept.push(name);
+      } else if (warnOnMissingMcp) {
+        warnings.push(
+          `Tool "${name}" is not registered (pi-mcp-adapter may not be installed or the server is not configured). Skipping.`
+        );
+      }
+      continue;
+    }
+    if (!availableToolNames.has(name)) {
+      warnings.push(
+        `Tool "${name}" is not registered. Passing through; another extension may register it later.`
+      );
+    }
+    kept.push(name);
+  }
+  if (intercomMode !== "off" && intercomAvailable && !seen.has("intercom")) {
+    kept.push("intercom");
+  }
+  return { kind: "set", names: kept, warnings };
+}
+function composeSessionName(intent, roleName) {
+  const trimmed = (intent ?? "").trim();
+  const intentPart = trimmed.length > 0 ? trimmed : INTENT_PLACEHOLDER;
+  return `${intentPart} - ${roleName}`;
+}
+function composeFooterStatus(roleName, intent) {
+  return composeSessionName(intent, roleName);
+}
+async function applyRole(role, applyCtx, options = {}) {
+  const { pi, ctx } = applyCtx;
+  const warnings = [];
+  if (role.model) {
+    const lookup = findModelInRegistry(ctx.modelRegistry, role.model);
+    if (!lookup.model) {
+      debugLog("apply", `model not found: ${role.model}`);
+      warnings.push(
+        `Model "${role.model}" not found in registry. Keeping current model.`
+      );
+    } else {
+      if (lookup.ambiguous) {
+        warnings.push(
+          `Model id "${role.model}" matches multiple providers; using "${lookup.model.provider}/${lookup.model.id}". Use provider/id to disambiguate.`
+        );
+      }
+      const ok = await pi.setModel(lookup.model);
+      if (!ok) {
+        debugLog("apply", `setModel refused: ${lookup.model.provider}/${lookup.model.id}`);
+        warnings.push(
+          `Model "${lookup.model.provider}/${lookup.model.id}" has no API key configured. Keeping current model.`
+        );
+      }
+    }
+  }
+  if (role.thinking !== void 0) {
+    pi.setThinkingLevel(role.thinking);
+  }
+  const intercomMode = effectiveIntercomMode(role, applyCtx.intercomMode);
+  const allTools = pi.getAllTools();
+  const availableNames = new Set(allTools.map((t) => t.name));
+  const intercomAvailable = availableNames.has("intercom");
+  const filtered = filterToolsForRuntime(
+    role.tools,
+    availableNames,
+    intercomMode,
+    intercomAvailable,
+    applyCtx.warnOnMissingMcp
+  );
+  warnings.push(...filtered.warnings);
+  if (filtered.kind === "set") {
+    pi.setActiveTools(filtered.names);
+  }
+  if (intercomMode !== "off" && !intercomAvailable) {
+    warnings.push(
+      `Role requests intercom mode "${intercomMode}" but the intercom tool is not registered. Install pi-intercom to enable.`
+    );
+  }
+  if (ctx.hasUI) {
+    ctx.ui.setStatus(STATUS_KEY, composeFooterStatus(role.name, options.preservedIntent));
+  }
+  pi.setSessionName(composeSessionName(options.preservedIntent, role.name));
+  const state = {
+    name: role.name,
+    source: role.source,
+    path: role.path,
+    intent: options.preservedIntent,
+    appliedAt: Date.now()
+  };
+  pi.appendEntry(ACTIVE_ROLE_ENTRY_TYPE, state);
+  if (!options.silent) {
+    const display = warnings.length === 0 ? `Switched to role ${role.name}` : `Switched to role ${role.name} (${warnings.length} warning${warnings.length === 1 ? "" : "s"})`;
+    pi.sendMessage({
+      customType: ROLE_NOTIFICATION_MESSAGE_TYPE,
+      content: display,
+      display: true,
+      details: { name: role.name, source: role.source, warnings }
+    });
+  }
+  return { warnings, state };
+}
+async function resetSession(ctx) {
+  await ctx.waitForIdle();
+  return ctx.newSession();
+}
+
+// src/intercom.ts
+var INTERCOM_TOOL_NAME = "intercom";
+function isIntercomAvailable(pi) {
+  return pi.getAllTools().some((t) => t.name === INTERCOM_TOOL_NAME);
+}
+function intercomPromptAddendum(mode, sessionName) {
+  if (mode === "off") return "";
+  const id = sessionName && sessionName.length > 0 ? sessionName : "(unnamed session)";
+  switch (mode) {
+    case "receive":
+      return [
+        "## intercom (receive mode)",
+        `This session is targetable as "${id}". Other sessions may send you messages via the \`intercom\` tool. Respond promptly when targeted; do not initiate outbound intercom messages unless the user explicitly asks.`
+      ].join("\n");
+    case "send":
+      return [
+        "## intercom (send mode)",
+        `You may send messages to other pi sessions via the \`intercom\` tool when coordination is needed. Identify yourself as "${id}". Use sparingly \u2014 only when another session genuinely needs the information.`
+      ].join("\n");
+    case "both":
+      return [
+        "## intercom (both modes)",
+        `This session is "${id}". You may send messages to other sessions via the \`intercom\` tool, and you may be targeted by them. Respond promptly when targeted; initiate outbound messages only when coordination is genuinely needed.`
+      ].join("\n");
+  }
+}
+
+// src/roles.ts
+import { readdirSync, readFileSync, statSync } from "fs";
+import { homedir } from "os";
+import { dirname, join, resolve } from "path";
+import { fileURLToPath } from "url";
+import { parse as parseYaml } from "yaml";
+import { Value } from "typebox/value";
+var RoleResolutionError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "RoleResolutionError";
+  }
+};
+function findProjectRolesDir(start) {
+  let dir = resolve(start);
+  while (true) {
+    const candidate = join(dir, ".pi", "roles");
+    if (isDir(candidate)) return candidate;
+    const parent = dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+function userRolesDir() {
+  return join(homedir(), ".pi", "agent", "roles");
+}
+function builtInRolesDir() {
+  const here = dirname(fileURLToPath(import.meta.url));
+  return resolve(here, "..", "resources", "roles");
+}
+function isDir(path) {
+  try {
+    return statSync(path).isDirectory();
+  } catch {
+    return false;
+  }
+}
+function listRoleFiles(dir) {
+  if (!isDir(dir)) return [];
+  return readdirSync(dir).filter((name) => name.endsWith(".md") && !name.startsWith(".")).map((name) => join(dir, name));
+}
+function discoverRoles(cwd, scope) {
+  const buckets = [];
+  if (scope === "project" || scope === "both") {
+    const projectDir = findProjectRolesDir(cwd);
+    buckets.push({ source: "project", files: projectDir ? listRoleFiles(projectDir) : [] });
+  }
+  if (scope === "user" || scope === "both") {
+    buckets.push({ source: "user", files: listRoleFiles(userRolesDir()) });
+  }
+  buckets.push({ source: "built-in", files: listRoleFiles(builtInRolesDir()) });
+  const roles = [];
+  const shadowed = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const bucket of buckets) {
+    for (const file of bucket.files) {
+      const raw = loadRoleFile(file, bucket.source);
+      if (seen.has(raw.frontmatter.name)) {
+        shadowed.push({ name: raw.frontmatter.name, source: bucket.source, path: file });
+        continue;
+      }
+      seen.add(raw.frontmatter.name);
+      roles.push(raw);
+    }
+  }
+  return { roles, shadowed };
+}
+var FRONTMATTER_RE = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/;
+function loadRoleFile(path, source) {
+  const text = readFileSync(path, "utf8");
+  return parseRoleSource(text, path, source);
+}
+function parseRoleSource(text, path, source) {
+  const match = FRONTMATTER_RE.exec(text);
+  if (!match) {
+    throw new RoleResolutionError(
+      `${path}: missing or malformed frontmatter. Expected '---' delimited YAML at the top of the file.`
+    );
+  }
+  const yamlBlock = match[1] ?? "";
+  const body = (match[2] ?? "").trim();
+  let parsed;
+  try {
+    parsed = parseYaml(yamlBlock);
+  } catch (err) {
+    const detail = err instanceof Error ? err.message : String(err);
+    debugLog("roles", `YAML parse error in ${path}`, detail);
+    throw new RoleResolutionError(`${path}: invalid YAML in frontmatter \u2014 ${detail}`);
+  }
+  if (parsed == null || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw new RoleResolutionError(`${path}: frontmatter must be a YAML mapping.`);
+  }
+  if (!Value.Check(RoleFrontmatterSchema, parsed)) {
+    const errors = [...Value.Errors(RoleFrontmatterSchema, parsed)];
+    const first = errors[0];
+    const where = first ? first.instancePath || "(root)" : "(root)";
+    const why = first ? first.message : "schema validation failed";
+    throw new RoleResolutionError(`${path}: invalid frontmatter at ${where} \u2014 ${why}`);
+  }
+  const frontmatter = parsed;
+  const expectedName = basenameWithoutExt(path);
+  if (frontmatter.name !== expectedName) {
+    throw new RoleResolutionError(
+      `${path}: frontmatter 'name' is "${frontmatter.name}" but filename implies "${expectedName}". They must match.`
+    );
+  }
+  return { source, path, frontmatter, body };
+}
+function basenameWithoutExt(path) {
+  const base = path.split(/[\\/]/).pop() ?? path;
+  return base.replace(/\.md$/, "");
+}
+function normalizeTools(value) {
+  if (value === void 0) return { kind: "inherit" };
+  if (value === null) return { kind: "set", names: [] };
+  const names = value.split(",").map((s) => s.trim()).filter((s) => s.length > 0);
+  return { kind: "set", names };
+}
+function resolveRole(name, all) {
+  const byName = /* @__PURE__ */ new Map();
+  for (const r of all) byName.set(r.frontmatter.name, r);
+  const leaf = byName.get(name);
+  if (!leaf) {
+    debugLog("roles", `role not found: ${name}`);
+    throw new RoleResolutionError(
+      `Role "${name}" not found. Run /role list to see available roles.`
+    );
+  }
+  const chain = [];
+  const seen = /* @__PURE__ */ new Set();
+  let cursor = leaf;
+  while (cursor) {
+    if (seen.has(cursor.frontmatter.name)) {
+      const cyclePath = [...chain.map((r) => r.frontmatter.name), cursor.frontmatter.name];
+      throw new RoleResolutionError(
+        `Cycle detected in 'extends' chain: ${cyclePath.join(" -> ")}`
+      );
+    }
+    seen.add(cursor.frontmatter.name);
+    chain.push(cursor);
+    const parentName = cursor.frontmatter.extends;
+    if (!parentName) break;
+    const parent = byName.get(parentName);
+    if (!parent) {
+      debugLog("roles", `extends not found: ${cursor.frontmatter.name} -> ${parentName}`);
+      throw new RoleResolutionError(
+        `Role "${cursor.frontmatter.name}" extends "${parentName}", but no such role was found.`
+      );
+    }
+    cursor = parent;
+  }
+  const ordered = [...chain].reverse();
+  let description;
+  let model;
+  let thinking;
+  let intercom;
+  let tools = { kind: "inherit" };
+  const bodies = [];
+  for (const role of ordered) {
+    const fm = role.frontmatter;
+    if (fm.description) description = fm.description;
+    if (fm.model !== void 0) model = fm.model;
+    if (fm.thinking !== void 0) thinking = fm.thinking;
+    if (fm.intercom !== void 0) intercom = fm.intercom;
+    const directive = normalizeTools(fm.tools);
+    if (directive.kind === "set") tools = directive;
+    if (role.body.length > 0) bodies.push(role.body);
+  }
+  const finalDescription = description ?? leaf.frontmatter.description;
+  return {
+    name: leaf.frontmatter.name,
+    description: finalDescription,
+    model,
+    thinking,
+    tools,
+    intercom,
+    body: bodies.join("\n\n---\n\n"),
+    source: leaf.source,
+    path: leaf.path,
+    // chain[] is leaf-first per the field contract.
+    extendsChain: chain.map((r) => r.frontmatter.name)
+  };
+}
+function findBuiltInAssistant(roles) {
+  return roles.find(
+    (r) => r.frontmatter.name === BUILTIN_ROLE_ASSISTANT_NAME && r.source === "built-in"
+  );
+}
+
+// src/settings.ts
+import { existsSync, readFileSync as readFileSync2 } from "fs";
+import { homedir as homedir2 } from "os";
+import { dirname as dirname2, join as join2, resolve as resolve2 } from "path";
+import { Value as Value2 } from "typebox/value";
+var NAMESPACE = "pi-roles";
+function findProjectSettingsFile(start) {
+  let dir = resolve2(start);
+  while (true) {
+    const candidate = join2(dir, ".pi", "settings.json");
+    if (existsSync(candidate)) return candidate;
+    const parent = dirname2(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+function userSettingsFile() {
+  return join2(homedir2(), ".pi", "agent", "settings.json");
+}
+function readNamespace(path) {
+  if (!path || !existsSync(path)) return {};
+  let parsed;
+  try {
+    parsed = JSON.parse(readFileSync2(path, "utf8"));
+  } catch {
+    debugLog("settings", `failed to parse ${path}`);
+    return {};
+  }
+  if (!parsed || typeof parsed !== "object") return {};
+  const raw = parsed[NAMESPACE];
+  if (!raw || typeof raw !== "object") return {};
+  if (!Value2.Check(PiRolesSettingsSchema, raw)) return {};
+  return raw;
+}
+function loadSettings(cwd) {
+  const user = readNamespace(userSettingsFile());
+  const project = readNamespace(findProjectSettingsFile(cwd));
+  return { ...user, ...project };
+}
+
+// src/title.ts
+import {
+  complete
+} from "@mariozechner/pi-ai";
+var TITLE_SYSTEM_PROMPT = [
+  "You generate a short session title from the user's first message in a chat session.",
+  "",
+  "Rules:",
+  "- 5 to 10 words. Capture the user's intent \u2014 what they want done.",
+  "- Use noun phrases or short imperatives.",
+  '- No quotes. No prefixes like "Title:". No trailing punctuation. No newlines.',
+  '- Be specific. Prefer "Debug websocket reconnect bug" over "Debug a bug".',
+  "- Output ONLY the title text. No explanation."
+].join("\n");
+var MAX_WORDS = 10;
+function extractTitle(raw) {
+  if (!raw) return "";
+  const firstLine = raw.split(/\r?\n/).find((l) => l.trim().length > 0);
+  if (!firstLine) return "";
+  let s = firstLine.trim();
+  const quotePairs = [
+    ['"', '"'],
+    ["'", "'"],
+    ["\u201C", "\u201D"],
+    ["\u2018", "\u2019"],
+    ["`", "`"]
+  ];
+  for (const [open, close] of quotePairs) {
+    if (s.length > open.length + close.length && s.startsWith(open) && s.endsWith(close)) {
+      s = s.slice(open.length, s.length - close.length).trim();
+      break;
+    }
+  }
+  s = s.replace(/[.!?,;]+$/u, "").trim();
+  s = s.replace(/\s+/g, " ");
+  const words = s.split(" ");
+  if (words.length > MAX_WORDS) {
+    s = words.slice(0, MAX_WORDS).join(" ");
+    s = s.replace(/[.!?,;]+$/u, "").trim();
+  }
+  return s;
+}
+function extractTitleFromMessage(message) {
+  const text = message.content.filter((b) => b.type === "text").map((b) => b.text).join(" ");
+  return extractTitle(text);
+}
+function resolveTitleModel(ctx, configured) {
+  if (configured && configured.length > 0) {
+    const lookup = findModelInRegistry(ctx.modelRegistry, configured);
+    if (lookup.model) return lookup.model;
+  }
+  return ctx.model;
+}
+async function generateAndApplyTitle(args) {
+  const { prompt, state, pi, ctx, configuredTitleModel } = args;
+  const completeFn = args.completeFn ?? complete;
+  debugLog("title", "generateAndApplyTitle entered", {
+    hasIntent: !!state.intent,
+    inFlight: state.titleInFlight,
+    hasActiveRole: !!state.activeRole,
+    promptLen: prompt?.length ?? 0,
+    configuredTitleModel,
+    ctxModelId: ctx?.model?.id
+  });
+  if (state.intent) {
+    debugLog("title", "guard: intent already set");
+    return;
+  }
+  if (state.titleInFlight) {
+    debugLog("title", "guard: titleInFlight");
+    return;
+  }
+  if (!state.activeRole) {
+    debugLog("title", "guard: no activeRole");
+    return;
+  }
+  const trimmed = prompt.trim();
+  if (!trimmed) {
+    debugLog("title", "guard: empty prompt");
+    return;
+  }
+  const model = resolveTitleModel(ctx, configuredTitleModel);
+  if (!model) {
+    debugLog("title", "guard: no model resolved");
+    return;
+  }
+  state.titleInFlight = true;
+  try {
+    const auth = await ctx.modelRegistry.getApiKeyAndHeaders(model);
+    if (!auth.ok) {
+      debugLog("title", "title model authentication unavailable", { error: auth.error });
+      if (!state.titleErrorShown && ctx.hasUI) {
+        ctx.ui.notify(`pi-roles: title model authentication failed (${auth.error}).`, "warning");
+        state.titleErrorShown = true;
+      }
+      return;
+    }
+    debugLog("title", "calling complete", {
+      modelId: model?.id,
+      modelProvider: model?.provider ?? model?.api?.provider,
+      configuredTitleModel,
+      usedFallback: !configuredTitleModel || configuredTitleModel.length === 0,
+      hasApiKey: !!auth.apiKey,
+      headerNames: auth.headers ? Object.keys(auth.headers) : [],
+      promptLen: trimmed.length
+    });
+    const message = await completeFn(
+      model,
+      {
+        systemPrompt: TITLE_SYSTEM_PROMPT,
+        messages: [{ role: "user", content: trimmed, timestamp: Date.now() }]
+      },
+      // `complete` does not consult Pi's ModelRegistry. Passing resolved
+      // auth here is essential for custom providers whose API key comes from
+      // a models.json env reference rather than pi-ai's built-in env map.
+      { apiKey: auth.apiKey, headers: auth.headers }
+    );
+    debugLog("title", "complete returned", {
+      stopReason: message?.stopReason,
+      errorMessage: message?.errorMessage,
+      usage: message?.usage,
+      contentBlockCount: message?.content?.length ?? 0,
+      contentBlockTypes: message?.content?.map((b) => b.type),
+      fullMessageKeys: message ? Object.keys(message) : [],
+      fullMessage: message
+    });
+    const stopReason = message?.stopReason;
+    if (stopReason === "error") {
+      const errMsg = message?.errorMessage ?? "unknown error";
+      debugLog("title", "complete stopReason=error", { errorMessage: errMsg });
+      if (!state.titleErrorShown && ctx.hasUI) {
+        ctx.ui.notify(
+          `pi-roles: title model failed (${errMsg}). Set settings.titleModel to a model with credentials.`,
+          "warning"
+        );
+        state.titleErrorShown = true;
+      }
+      return;
+    }
+    const intent = extractTitleFromMessage(message);
+    if (!intent) return;
+    if (state.intent) return;
+    if (!state.activeRole) return;
+    state.intent = intent;
+    pi.setSessionName(composeSessionName(intent, state.activeRole.name));
+    if (ctx.hasUI) {
+      ctx.ui.setStatus(STATUS_KEY, composeFooterStatus(state.activeRole.name, intent));
+    }
+    const persisted = {
+      name: state.activeRole.name,
+      source: state.activeRole.source,
+      path: state.activeRole.path,
+      intent,
+      appliedAt: Date.now()
+    };
+    pi.appendEntry(ACTIVE_ROLE_ENTRY_TYPE, persisted);
+  } catch (err) {
+    const e = err;
+    debugLog("title", "generateAndApplyTitle failed", {
+      name: e?.name,
+      message: e?.message ?? String(err),
+      stack: e?.stack,
+      status: e?.status ?? e?.statusCode,
+      code: e?.code,
+      cause: e?.cause ? String(e.cause) : void 0,
+      modelId: model?.id,
+      modelProvider: model?.provider ?? model?.api?.provider
+    });
+    if (!state.titleErrorShown && ctx.hasUI) {
+      ctx.ui.notify(
+        `pi-roles: title generation failed (${e?.message ?? String(err)}). Set settings.titleModel to a model with credentials.`,
+        "warning"
+      );
+      state.titleErrorShown = true;
+    }
+  } finally {
+    state.titleInFlight = false;
+  }
+}
+
+// src/index.ts
+var FLAG_NAME = "role";
+var ENV_VAR = "PI_ROLE";
+var SUBCOMMANDS = ["list", "current", "reload"];
+function index_default(pi) {
+  const state = {
+    activeRole: null,
+    pendingRoleAfterReset: null,
+    roles: [],
+    shadowed: [],
+    settings: {},
+    intent: void 0,
+    titleInFlight: false,
+    titleErrorShown: false
+  };
+  const refreshFromDisk = (cwd) => {
+    state.settings = loadSettings(cwd);
+    const discovery = discoverRoles(cwd, state.settings.roleScope ?? "both");
+    state.roles = discovery.roles;
+    state.shadowed = discovery.shadowed;
+  };
+  pi.registerFlag(FLAG_NAME, {
+    type: "string",
+    description: "Launch as the named pi-roles role (e.g. --role architect)."
+  });
+  pi.registerMessageRenderer(ROLE_NOTIFICATION_MESSAGE_TYPE, () => {
+    return void 0;
+  });
+  pi.on("session_start", async (event, ctx) => {
+    refreshFromDisk(ctx.cwd);
+    const restored = findRestoredState(ctx);
+    debugLog("index", `session_start reason=${event.reason}`, restored ? { name: restored.name, intent: restored.intent } : void 0);
+    let targetName;
+    let preservedIntent;
+    let silent = false;
+    if (state.pendingRoleAfterReset) {
+      targetName = state.pendingRoleAfterReset;
+      state.pendingRoleAfterReset = null;
+    } else if ((event.reason === "reload" || event.reason === "resume") && restored) {
+      targetName = restored.name;
+      preservedIntent = restored.intent;
+      silent = true;
+    } else {
+      targetName = event.reason === "new" ? pickNewSessionRoleName(state.activeRole, pi, state.settings, state.roles) : pickInitialRoleName(pi, state.settings, state.roles);
+      silent = event.reason === "startup";
+    }
+    state.intent = preservedIntent;
+    await applyResolved(pi, ctx, state, targetName, { silent, preservedIntent });
+  });
+  pi.on("before_agent_start", async (event, ctx) => {
+    debugLog("index", "before_agent_start fired", {
+      hasActiveRole: !!state.activeRole,
+      hasIntent: !!state.intent,
+      inFlight: state.titleInFlight,
+      promptLen: event?.prompt?.length ?? 0,
+      ctxModelId: ctx?.model?.id
+    });
+    if (state.activeRole && !state.intent && !state.titleInFlight && event.prompt && event.prompt.trim().length > 0) {
+      debugLog("index", "triggering title generation", { promptPreview: event.prompt.slice(0, 80), model: state.settings.titleModel });
+      void generateAndApplyTitle({
+        prompt: event.prompt,
+        state,
+        pi,
+        ctx,
+        configuredTitleModel: state.settings.titleModel
+      });
+    }
+    return composeSystemPrompt(state, pi);
+  });
+  pi.registerCommand("role", {
+    description: "Switch session role. /role list | current | reload | <name> [--reset]",
+    getArgumentCompletions: (prefix) => roleCompletions(prefix, state.roles),
+    handler: async (args, ctx) => {
+      refreshFromDisk(ctx.cwd);
+      const tokens = args.trim().split(/\s+/).filter(Boolean);
+      const sub = tokens[0];
+      if (!sub || sub === "list") {
+        return handleList(ctx, state);
+      }
+      if (sub === "current") {
+        return handleCurrent(ctx, state);
+      }
+      if (sub === "reload") {
+        return handleReload(pi, ctx, state);
+      }
+      const wantsReset = tokens.includes("--reset");
+      const name = sub;
+      if (wantsReset) {
+        state.pendingRoleAfterReset = name;
+        const result = await resetSession(ctx);
+        if (result.cancelled) {
+          state.pendingRoleAfterReset = null;
+          ctx.ui.notify(`Role switch to "${name}" cancelled.`, "info");
+        }
+        return;
+      }
+      await applyResolved(pi, ctx, state, name, { silent: false, preservedIntent: state.intent });
+    }
+  });
+}
+function composeSystemPrompt(state, pi) {
+  if (!state.activeRole) return void 0;
+  const body = state.activeRole.body;
+  const mode = effectiveIntercomMode(state.activeRole, state.settings.intercomMode);
+  const addendum = mode !== "off" && isIntercomAvailable(pi) ? intercomPromptAddendum(mode, pi.getSessionName()) : "";
+  const parts = [body, addendum].filter((p) => p.length > 0);
+  if (parts.length === 0) return void 0;
+  return { systemPrompt: parts.join("\n\n") };
+}
+function pickNewSessionRoleName(activeRole, pi, settings, roles) {
+  if (settings.preserveRoleOnNewSession && activeRole) return activeRole.name;
+  return pickInitialRoleName(pi, settings, roles);
+}
+function pickInitialRoleName(pi, settings, roles) {
+  const flagValue = pi.getFlag(FLAG_NAME);
+  if (typeof flagValue === "string" && flagValue.length > 0) return flagValue;
+  const env = process.env[ENV_VAR];
+  if (env && env.length > 0) return env;
+  const configured = settings.defaultRole;
+  if (configured && roles.some((r) => r.frontmatter.name === configured)) {
+    return configured;
+  }
+  return BUILTIN_ROLE_ASSISTANT_NAME;
+}
+function findRestoredState(ctx) {
+  let entries;
+  try {
+    entries = ctx.sessionManager.getEntries();
+  } catch {
+    return void 0;
+  }
+  for (let i = entries.length - 1; i >= 0; i--) {
+    const e = entries[i];
+    if (e && e.type === "custom" && e.customType === ACTIVE_ROLE_ENTRY_TYPE) {
+      return e.data ?? void 0;
+    }
+  }
+  return void 0;
+}
+async function applyResolved(pi, ctx, state, name, options) {
+  let resolved;
+  try {
+    resolved = resolveRole(name, state.roles);
+  } catch (err) {
+    const message = err instanceof RoleResolutionError ? err.message : String(err);
+    debugLog("index", `applyResolved fallback: ${message}`);
+    if (ctx.hasUI) {
+      ctx.ui.notify(`pi-roles: ${message} Falling back to ${BUILTIN_ROLE_ASSISTANT_NAME}.`, "warning");
+    }
+    const fallback = findBuiltInAssistant(state.roles);
+    if (!fallback) {
+      return;
+    }
+    resolved = resolveRole(BUILTIN_ROLE_ASSISTANT_NAME, state.roles);
+  }
+  const result = await applyRole(
+    resolved,
+    {
+      pi,
+      ctx,
+      warnOnMissingMcp: state.settings.warnOnMissingMcp ?? true,
+      intercomMode: state.settings.intercomMode
+    },
+    options
+  );
+  state.activeRole = resolved;
+  state.intent = result.state.intent;
+  debugLog("index", `applied role=${resolved.name}`, { intent: result.state.intent, warnings: result.warnings });
+  if (ctx.hasUI && result.warnings.length > 0 && !options.silent) {
+    for (const w of result.warnings) ctx.ui.notify(`pi-roles: ${w}`, "warning");
+  }
+}
+async function handleList(ctx, state) {
+  if (state.roles.length === 0) {
+    ctx.ui.notify(
+      "pi-roles: no roles found. Create one in .pi/roles/ or ~/.pi/agent/roles/.",
+      "info"
+    );
+    return;
+  }
+  const lines = state.roles.slice().sort((a, b) => a.frontmatter.name.localeCompare(b.frontmatter.name)).map((r) => {
+    const marker = state.activeRole?.name === r.frontmatter.name ? "* " : "  ";
+    return `${marker}${r.frontmatter.name} [${r.source}] \u2014 ${r.frontmatter.description}`;
+  });
+  const shadowed = state.shadowed.map(
+    (s) => `  ${s.name} [${s.source}] (shadowed) \u2014 ${s.path}`
+  );
+  const all = shadowed.length > 0 ? ["Available roles:", ...lines, "", "Shadowed (lower-priority duplicates):", ...shadowed] : ["Available roles:", ...lines];
+  ctx.ui.notify(all.join("\n"), "info");
+}
+async function handleCurrent(ctx, state) {
+  if (!state.activeRole) {
+    ctx.ui.notify("pi-roles: no role active.", "info");
+    return;
+  }
+  const r = state.activeRole;
+  const chain = r.extendsChain.length > 1 ? ` (extends: ${r.extendsChain.slice(1).join(" \u2192 ")})` : "";
+  ctx.ui.notify(`pi-roles: ${r.name}${chain} \u2014 ${r.description}
+${r.path}`, "info");
+}
+async function handleReload(pi, ctx, state) {
+  const previous = state.activeRole?.name ?? pickInitialRoleName(pi, state.settings, state.roles);
+  await applyResolved(pi, ctx, state, previous, {
+    silent: false,
+    preservedIntent: state.intent
+  });
+}
+function roleCompletions(prefix, roles) {
+  const needle = prefix.toLowerCase();
+  const items = [];
+  for (const sub of SUBCOMMANDS) {
+    if (sub.toLowerCase().startsWith(needle)) {
+      items.push({ value: sub, label: sub, description: subcommandDescription(sub) });
+    }
+  }
+  for (const r of roles) {
+    if (r.frontmatter.name.toLowerCase().startsWith(needle)) {
+      items.push({
+        value: r.frontmatter.name,
+        label: r.frontmatter.name,
+        description: `${r.source} \u2014 ${r.frontmatter.description}`
+      });
+    }
+  }
+  return items.length > 0 ? items : null;
+}
+function subcommandDescription(sub) {
+  switch (sub) {
+    case "list":
+      return "Show all available roles.";
+    case "current":
+      return "Show the active role.";
+    case "reload":
+      return "Re-read the active role file from disk.";
+  }
+}
+export {
+  composeSystemPrompt,
+  index_default as default,
+  pickInitialRoleName,
+  pickNewSessionRoleName,
+  roleCompletions
+};