@herbertgao/pi-extensions 2026.8.2 → 2026.8.4

package/node_modules/pi-footer/src/widgets/tokens/output-tokens.ts

@@ -0,0 +1,18 @@
+import { defineWidget } from "../types.js";
+import { formatTokenCount, tokenFormatStyleProperty } from "../utils/token-format.js";
+
+export const OutputTokensWidget = defineWidget({
+  type: "output-tokens",
+  label: "Output Tokens",
+  category: "Tokens",
+  description: "Output token total",
+  dependencies: ["metrics"],
+  baseOptions: ["raw", "hideWhenZero", "icon"],
+  baseOptionDefaults: {},
+  properties: [tokenFormatStyleProperty()],
+  icons: { emoji: "⬇️", nerd: "󰧚", text: "out" },
+  defaultStyle: { fg: "white", bg: "default", bold: false },
+  render({ ctx, options, renderWidget }) {
+    return renderWidget(formatTokenCount(ctx.metrics.outputTokens, options.tokenFormatStyle));
+  },
+});

package/node_modules/pi-footer/src/widgets/tokens/tokens.ts

@@ -0,0 +1,20 @@
+import { defineWidget } from "../types.js";
+import { formatTokenCount, tokenFormatStyleProperty } from "../utils/token-format.js";
+
+export const TokensWidget = defineWidget({
+  type: "tokens",
+  label: "Input/Output Tokens",
+  category: "Tokens",
+  description: "Input and output token totals",
+  dependencies: ["metrics"],
+  baseOptions: ["raw", "icon"],
+  baseOptionDefaults: {},
+  properties: [tokenFormatStyleProperty()],
+  icons: { emoji: "🔢", nerd: "󰓹", text: "tok" },
+  defaultStyle: { fg: "cyan", bg: "default", bold: false },
+  render({ ctx, options, renderWidget }) {
+    return renderWidget(
+      `↑${formatTokenCount(ctx.metrics.inputTokens, options.tokenFormatStyle)} ↓${formatTokenCount(ctx.metrics.outputTokens, options.tokenFormatStyle)}`,
+    );
+  },
+});

package/node_modules/pi-footer/src/widgets/tokens/total-speed.ts

@@ -0,0 +1,25 @@
+import { defineWidget } from "../types.js";
+import { formatTokenSpeed, tokenFormatStyleProperty } from "../utils/token-format.js";
+
+export const TotalSpeedWidget = defineWidget({
+  type: "total-speed",
+  label: "Total Speed",
+  category: "Tokens",
+  description: "Average total tokens per minute",
+  dependencies: ["metrics"],
+  baseOptions: ["raw", "hideWhenZero", "icon"],
+  baseOptionDefaults: {},
+  properties: [tokenFormatStyleProperty()],
+  icons: { emoji: "⚡", nerd: "↕", text: "tok/min" },
+  defaultStyle: { fg: "brightGreen", bg: "default", bold: false },
+  render({ ctx, options, renderWidget }) {
+    return renderWidget(
+      formatTokenSpeed(
+        ctx.metrics.totalTokens,
+        ctx.metrics.firstTimestampMs,
+        ctx.metrics.lastTimestampMs,
+        options.tokenFormatStyle,
+      ),
+    );
+  },
+});

package/node_modules/pi-footer/src/widgets/tokens/total-tokens.ts

@@ -0,0 +1,18 @@
+import { defineWidget } from "../types.js";
+import { formatTokenCount, tokenFormatStyleProperty } from "../utils/token-format.js";
+
+export const TotalTokensWidget = defineWidget({
+  type: "total-tokens",
+  label: "Total Tokens",
+  category: "Tokens",
+  description: "Total token count",
+  dependencies: ["metrics"],
+  baseOptions: ["raw", "hideWhenZero", "icon"],
+  baseOptionDefaults: {},
+  properties: [tokenFormatStyleProperty()],
+  icons: { emoji: "🔢", nerd: "󰓹", text: "tok" },
+  defaultStyle: { fg: "cyan", bg: "default", bold: false },
+  render({ ctx, options, renderWidget }) {
+    return renderWidget(formatTokenCount(ctx.metrics.totalTokens, options.tokenFormatStyle));
+  },
+});

package/node_modules/pi-footer/src/widgets/types.ts

@@ -0,0 +1,181 @@
+import type { Theme } from "@earendil-works/pi-coding-agent";
+
+import type { ColorLevel } from "../colors.js";
+import type { GetExtensionStatuses } from "../extension-statuses.js";
+import type {
+  IconMode,
+  StatuslineData,
+  WidgetEntry,
+  WidgetOptions,
+  WidgetStyle,
+} from "../types.js";
+
+export interface WidgetIconSet {
+  emoji: string;
+  nerd: string;
+  text: string;
+}
+
+export type PropertyKind = "boolean" | "number" | "choice" | "text";
+
+export interface ChoiceOption<TId extends string = string> {
+  id: TId;
+  label: string;
+  list: string;
+}
+
+export type WidgetPropertyDefault = string | number | boolean;
+
+// Edit-action discriminant for properties that open a dedicated editor flow. Extend as needed.
+export type WidgetEditAction = "external-status-key";
+
+export interface WidgetProperty {
+  id: string;
+  label: string;
+  kind: PropertyKind;
+  description: string;
+  default: WidgetPropertyDefault;
+  showWhen?: {
+    property: string;
+    equals: string | number | boolean;
+  };
+  options?: {
+    min?: number;
+    max?: number;
+    choices?: readonly ChoiceOption[];
+    label?: string;
+    showInFields?: boolean;
+    showInWidgets?: boolean;
+    showInColors?: boolean;
+    listProperty?: string;
+    quoteValue?: boolean;
+    editAction?: WidgetEditAction;
+  };
+}
+
+export type WidgetBaseOption = "raw" | "hideWhenEmpty" | "hideWhenZero" | "text" | "icon";
+
+export interface WidgetRenderOptions extends WidgetStyle {
+  icons?: WidgetIconSet;
+  preservedTrimStyles?: string;
+  stripIncomingStyles?: boolean;
+}
+
+// The widget dependency set is the materialized snapshot (StatuslineData) plus the one live
+// accessor that must never enter the snapshot — see F1 / pi live-accessor rule.
+export type WidgetDependencyValues = StatuslineData & {
+  getExtensionStatuses: GetExtensionStatuses | undefined;
+};
+
+export type WidgetDependency = keyof WidgetDependencyValues;
+
+export interface BaseWidgetContext {
+  iconMode: IconMode;
+  minimalist: boolean;
+  colorLevel: ColorLevel;
+  theme?: Theme;
+  requestRender?: () => void;
+}
+
+export type WidgetContext<TDeps extends readonly WidgetDependency[] = readonly []> =
+  BaseWidgetContext & Pick<WidgetDependencyValues, TDeps[number]>;
+
+export type WidgetInstanceOptions<TOptions extends object> = WidgetOptions & TOptions;
+
+export interface Widget<TOptions extends object = {}> {
+  readonly entry: WidgetEntry;
+  readonly id: string;
+  readonly type: WidgetEntry["type"];
+  enabled: boolean;
+  options: WidgetInstanceOptions<TOptions>;
+
+  render(ctx: WidgetContext): string | undefined;
+  toggle(enabled?: boolean): void;
+  update(options: Partial<WidgetInstanceOptions<TOptions>>): void;
+  toEntry(): WidgetEntry;
+}
+
+type BaseOptionsToObject<TBaseOptions extends readonly WidgetBaseOption[]> = Required<
+  Pick<WidgetOptions, TBaseOptions[number]>
+>;
+
+type WidgetChoiceValue<TProperty> = TProperty extends {
+  readonly kind: "choice";
+  readonly options: { readonly choices: readonly (infer TChoice)[] };
+}
+  ? TChoice extends { readonly id: infer TId extends string }
+    ? TId
+    : string
+  : string;
+
+type WidgetPropertyValue<TProperty extends Pick<WidgetProperty, "kind">> =
+  TProperty["kind"] extends "boolean"
+    ? boolean
+    : TProperty["kind"] extends "number"
+      ? number
+      : TProperty["kind"] extends "choice"
+        ? WidgetChoiceValue<TProperty>
+        : string;
+
+type PropertiesToObject<TProperties extends readonly WidgetProperty[]> = {
+  [TProperty in TProperties[number] as TProperty["id"]]: WidgetPropertyValue<TProperty>;
+};
+
+export type OptionsFor<TSpec extends Pick<WidgetSpec, "baseOptions" | "properties">> =
+  WidgetOptions &
+    BaseOptionsToObject<TSpec["baseOptions"]> &
+    PropertiesToObject<TSpec["properties"]> &
+    WidgetStyle;
+
+export type ContextFor<TSpec extends Pick<WidgetSpec, "dependencies">> = BaseWidgetContext &
+  Pick<WidgetDependencyValues, TSpec["dependencies"][number]>;
+
+export interface TypedWidgetRenderArgs<
+  TSpec extends Pick<WidgetSpec, "dependencies" | "baseOptions" | "properties">,
+> {
+  readonly ctx: ContextFor<TSpec>;
+  readonly options: OptionsFor<TSpec>;
+  readonly renderWidget: (
+    value: string | undefined,
+    renderOptions?: WidgetRenderOptions,
+  ) => string | undefined;
+}
+
+export interface WidgetSpec<
+  TType extends string = string,
+  TCategory extends string = string,
+  TDependencies extends readonly WidgetDependency[] = readonly WidgetDependency[],
+  TBaseOptions extends readonly WidgetBaseOption[] = readonly WidgetBaseOption[],
+  TProperties extends readonly WidgetProperty[] = readonly WidgetProperty[],
+> {
+  readonly type: TType;
+  readonly label: string;
+  readonly category: TCategory;
+  readonly description: string;
+  readonly dependencies: TDependencies;
+  readonly baseOptions: TBaseOptions;
+  readonly baseOptionDefaults?: Partial<WidgetOptions>;
+  readonly properties: TProperties;
+  readonly icons: WidgetIconSet;
+  readonly defaultStyle: WidgetStyle;
+  readonly createOptionDefaults?: () => Partial<WidgetOptions>;
+  render(
+    args: TypedWidgetRenderArgs<{
+      readonly dependencies: TDependencies;
+      readonly baseOptions: TBaseOptions;
+      readonly properties: TProperties;
+    }>,
+  ): string | undefined;
+}
+
+export function defineWidget<
+  const TType extends string,
+  const TCategory extends string,
+  const TDependencies extends readonly WidgetDependency[],
+  const TBaseOptions extends readonly WidgetBaseOption[],
+  const TProperties extends readonly WidgetProperty[],
+>(
+  spec: WidgetSpec<TType, TCategory, TDependencies, TBaseOptions, TProperties>,
+): WidgetSpec<TType, TCategory, TDependencies, TBaseOptions, TProperties> {
+  return spec;
+}

package/node_modules/pi-footer/src/widgets/utils/colors.ts

@@ -0,0 +1,11 @@
+import type { ColorName } from "../../colors.js";
+
+export function colorPair(
+  fg: ColorName | undefined,
+  bg: ColorName | undefined,
+): { fg?: ColorName; bg?: ColorName } {
+  return {
+    ...(fg === undefined ? {} : { fg }),
+    ...(bg === undefined ? {} : { bg }),
+  };
+}

package/node_modules/pi-footer/src/widgets/utils/context.ts

@@ -0,0 +1,112 @@
+import { normalizeColor, type ConditionalColorFields } from "../../colors.js";
+import type { WidgetOptions } from "../../types.js";
+import { colorPair } from "./colors.js";
+
+export function contextPercent(tokens: number | undefined, maxTokens: number | undefined) {
+  if (tokens === undefined || maxTokens === undefined || maxTokens <= 0) return undefined;
+  return Math.min(100, Math.max(0, (tokens / maxTokens) * 100));
+}
+
+interface ContextColorOptions extends WidgetOptions, ConditionalColorFields {
+  contextConditionalColors: boolean;
+  contextWarningPercent: number;
+  contextDangerPercent: number;
+}
+
+export function contextColors(
+  options: ContextColorOptions,
+  contextTokens: number | undefined,
+  contextMaxTokens: number | undefined,
+) {
+  if (!options.contextConditionalColors) return colorPair(options.fg, options.bg);
+  const percent = contextPercent(contextTokens, contextMaxTokens);
+  if (percent === undefined) return colorPair(options.fg, options.bg);
+
+  if (percent >= options.contextDangerPercent) {
+    return colorPair(
+      normalizeColor(options.dangerFg) ?? options.fg,
+      normalizeColor(options.dangerBg) ?? options.bg,
+    );
+  }
+
+  if (percent >= options.contextWarningPercent) {
+    return colorPair(
+      normalizeColor(options.warningFg) ?? options.fg,
+      normalizeColor(options.warningBg) ?? options.bg,
+    );
+  }
+
+  return colorPair(options.fg, options.bg);
+}
+
+export function contextColorProperties() {
+  return [
+    {
+      id: "contextConditionalColors",
+      label: "Conditional colors",
+      kind: "boolean",
+      description: "Use warning/danger colors based on context usage",
+      default: false,
+      options: {
+        label: "with-colors",
+        showInWidgets: true,
+        showInColors: true,
+        listProperty: "",
+      },
+    },
+    {
+      id: "contextWarningPercent",
+      label: "Warning zone threshold",
+      kind: "number",
+      description: "Context usage percentage for warning colors",
+      default: 70,
+      showWhen: { property: "contextConditionalColors", equals: true },
+      options: { min: 0, max: 100, showInWidgets: false, showInColors: false },
+    },
+    {
+      id: "contextDangerPercent",
+      label: "Danger zone threshold",
+      kind: "number",
+      description: "Context usage percentage for danger colors",
+      default: 90,
+      showWhen: { property: "contextConditionalColors", equals: true },
+      options: { min: 0, max: 100, showInWidgets: false, showInColors: false },
+    },
+    {
+      id: "warningFg",
+      label: "Warning foreground",
+      kind: "text",
+      description: "Warning foreground",
+      default: "yellow",
+      showWhen: { property: "contextConditionalColors", equals: true },
+      options: { showInFields: false, showInWidgets: false, showInColors: false },
+    },
+    {
+      id: "warningBg",
+      label: "Warning background",
+      kind: "text",
+      description: "Warning background",
+      default: "default",
+      showWhen: { property: "contextConditionalColors", equals: true },
+      options: { showInFields: false, showInWidgets: false, showInColors: false },
+    },
+    {
+      id: "dangerFg",
+      label: "Danger foreground",
+      kind: "text",
+      description: "Danger foreground",
+      default: "red",
+      showWhen: { property: "contextConditionalColors", equals: true },
+      options: { showInFields: false, showInWidgets: false, showInColors: false },
+    },
+    {
+      id: "dangerBg",
+      label: "Danger background",
+      kind: "text",
+      description: "Danger background",
+      default: "default",
+      showWhen: { property: "contextConditionalColors", equals: true },
+      options: { showInFields: false, showInWidgets: false, showInColors: false },
+    },
+  ] as const;
+}

package/node_modules/pi-footer/src/widgets/utils/session.ts

@@ -0,0 +1,19 @@
+export function formatTime(timestamp: number | undefined): string {
+  if (timestamp === undefined) return "";
+  return new Date(timestamp).toLocaleTimeString([], { hour: "2-digit", minute: "2-digit" });
+}
+
+function formatDuration(ms: number): string {
+  if (!Number.isFinite(ms) || ms <= 0) return "0m";
+  const totalMinutes = Math.max(1, Math.floor(ms / 60_000));
+  const hours = Math.floor(totalMinutes / 60);
+  const minutes = totalMinutes % 60;
+  if (hours === 0) return `${minutes}m`;
+  return minutes === 0 ? `${hours}h` : `${hours}h ${minutes}m`;
+}
+
+export function formatElapsed(first: number | undefined, last: number | undefined): string {
+  if (first === undefined) return "0m";
+  const end = last === undefined || last < first ? Date.now() : last;
+  return formatDuration(end - first);
+}

package/node_modules/pi-footer/src/widgets/utils/token-format.ts

@@ -0,0 +1,78 @@
+export function formatCount(value: number) {
+  if (value < 1000) return `${value}`;
+  if (value < 1000000) return `${trimFixed(value / 1000, 1)}k`;
+  return `${trimFixed(value / 1000000, 1)}m`;
+}
+
+export function formatPiTokenCount(value: number) {
+  if (value < 1000) return `${value}`;
+  if (value < 10000) return `${(value / 1000).toFixed(1)}k`;
+  if (value < 1000000) return `${Math.round(value / 1000)}k`;
+  if (value < 10000000) return `${(value / 1000000).toFixed(1)}M`;
+  return `${Math.round(value / 1000000)}M`;
+}
+
+function trimFixed(value: number, digits: number) {
+  return value.toFixed(digits).replace(/\.0$/, "");
+}
+const TOKEN_FORMAT_STYLES = {
+  default: {
+    label: "Default",
+    list: "Default",
+    format: formatCount,
+  },
+  compact: {
+    label: "Compact",
+    list: "Compact",
+    format: formatPiTokenCount,
+  },
+} as const;
+
+export type TokenFormatStyle = keyof typeof TOKEN_FORMAT_STYLES;
+
+const TOKEN_FORMAT_STYLE_VALUES = Object.keys(TOKEN_FORMAT_STYLES) as TokenFormatStyle[];
+
+const TOKEN_FORMAT_CHOICES = TOKEN_FORMAT_STYLE_VALUES.map((style) => ({
+  id: style,
+  label: TOKEN_FORMAT_STYLES[style].label,
+  list: TOKEN_FORMAT_STYLES[style].list,
+}));
+
+export function formatTokenCount(value: number, style: TokenFormatStyle) {
+  return TOKEN_FORMAT_STYLES[style].format(value);
+}
+
+export function formatTokenSpeed(
+  tokens: number,
+  first: number | undefined,
+  last: number | undefined,
+  tokenFormatStyle: TokenFormatStyle,
+) {
+  if (
+    first === undefined ||
+    last === undefined ||
+    !Number.isFinite(first) ||
+    !Number.isFinite(last) ||
+    last <= first
+  ) {
+    return "0/min";
+  }
+  const minutes = Math.max((last - first) / 60000, 1 / 60);
+  return `${formatTokenCount(Math.round(tokens / minutes), tokenFormatStyle)}/min`;
+}
+
+export function tokenFormatStyleProperty() {
+  return {
+    id: "tokenFormatStyle",
+    label: "Token format",
+    kind: "choice",
+    description: "Token display format",
+    default: "default",
+    options: {
+      choices: TOKEN_FORMAT_CHOICES,
+      showInWidgets: true,
+      showInColors: false,
+      listProperty: "format",
+    },
+  } as const;
+}

package/node_modules/pi-mcp-adapter/CHANGELOG.md

@@ -7,6 +7,25 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.23.0] - 2026-08-11
+
+### Added
+- Added interactive callback URL pasting to `/mcp-auth` for OAuth flows running on remote or headless machines. Thanks @trevorleibert-mixpanel for PR #330.
+
+### Fixed
+- Stopped load-time MCP initialization from printing a TUI startup error when Pi action methods are not bound yet. Thanks @21307369 for issue #327.
+- Kept interactive OAuth authorization URLs clickable as a single terminal hyperlink. Thanks @rfccg for PR #329.
+
+## [2.22.0] - 2026-08-11
+
+### Added
+- Added the `pi-mcp-adapter/oauth` subpath for URL-bound OAuth token reuse by cooperating Pi extensions. Thanks @ThePhoenixCoding for issue #323.
+- Added `oauth.logoUri` for OAuth Dynamic Client Registration, with validation that requires an absolute HTTP(S) URL. Thanks @grinich for PR #321.
+
+### Fixed
+- Materialized binary MCP resources as private temporary files before model-facing output, with bounded per-session cleanup. Thanks @zenworr and @shaworr for PR #324.
+- Named OAuth callback pages and dynamic client registrations after rebranded Pi hosts, while preserving stock Pi defaults and avoiding guessed client homepages. Thanks @grinich for PR #320.
+
 ## [2.21.2] - 2026-08-09
 
 ### Fixed

package/node_modules/pi-mcp-adapter/README.md

@@ -153,6 +153,17 @@ A supplied `config` is a complete, isolated snapshot. It is not merged with file
 
 With `configPath` and no `config`, the adapter keeps normal file merge behavior, and that path takes precedence over argv and `--mcp-config`. The default export keeps the normal file-based behavior. OAuth credentials are stored in the operating system credential store and keyed by the configured server name; URL binding prevents credentials from being accepted for a different server URL. `settings.oauthDir` and `MCP_OAUTH_DIR` are used only as legacy plaintext import locations for older `tokens.json` files, not as credential namespaces. CSRF state and PKCE verifiers are flow-local, so concurrent authorization flows do not share transient secrets.
 
+Cooperating Pi extensions can use `pi-mcp-adapter/oauth` to reuse URL-bound OAuth tokens without deep-importing private files:
+
+```ts
+import { getMcpOAuthTokensForUrl, updateMcpOAuthTokensForUrl } from "pi-mcp-adapter/oauth";
+
+const tokens = await getMcpOAuthTokensForUrl("jira", "https://jira.example.com/mcp");
+updateMcpOAuthTokensForUrl("jira", "https://jira.example.com/mcp", { accessToken: "..." });
+```
+
+The public subpath exposes only token read/update helpers plus a status helper. The async read path uses the adapter's refresh logic before it returns tokens. The helpers keep secure-store storage, URL binding, refresh persistence, chunk handling, legacy import, and fail-closed credential-store errors. They do not expose client registration secrets, PKCE verifiers, or OAuth state.
+
 ### Runtime status snapshots
 
 Extensions can subscribe to the adapter's versioned shared event-bus channel instead of parsing `/mcp` or `mcp({})` output:
@@ -203,7 +214,8 @@ In the configuration examples below, `30000` is illustrative only. If `requestTi
 | `oauth.scope` | Requested OAuth scopes |
 | `oauth.redirectUri` | Exact localhost redirect URI for browser OAuth, including port and path, for providers that pre-register callbacks |
 | `oauth.clientName` | Client display name advertised during Dynamic Client Registration fallback |
-| `oauth.clientUri` | Client homepage URI advertised during Dynamic Client Registration fallback |
+| `oauth.clientUri` | Client homepage URI advertised during Dynamic Client Registration fallback. Defaults to `piConfig.clientUri` from the host's manifest when set, and is omitted rather than guessed under a rebranded host |
+| `oauth.logoUri` | Client logo URL advertised during Dynamic Client Registration fallback (RFC 7591 `logo_uri`). Must be an absolute `http(s)` URL — consent screens fetch it server-side, so local paths render nothing. Omitted from the registration request when unset |
 | `oauth.skipIssuerMetadataValidation` | `true` disables the OAuth authorization-server metadata issuer check for this server. This weakens OAuth mix-up protection and should only be used for known-misconfigured internal servers while their metadata is being fixed. |
 | `bearerToken` / `bearerTokenEnv` | Token or env var name; `bearerToken` supports `${VAR}` and `$env:VAR` interpolation. A leading `!` in `bearerToken` runs a command when the HTTP server connects; use `!!` for a literal leading `!`. |
 | `lifecycle` | `"lazy"` (default), `"eager"`, `"keep-alive"`, or `"lazy-keep-alive"` |
@@ -253,7 +265,9 @@ The adapter owns only its client socket and closes that connection when the Pi r
 
 ### Remote/headless OAuth
 
-If Pi is running on a remote server and cannot open a local browser, start OAuth through the proxy tool. Persistent OAuth still requires an available OS credential store; on headless Linux that usually means an unlocked Secret Service/libsecret keyring. The adapter fails closed instead of falling back to plaintext credentials when the secure store is unavailable.
+If Pi is running on a remote server, `/mcp-auth <server>` prints the authorization URL and opens a callback input. Open the URL in your local browser. After approval, the browser may fail to load the localhost callback page because localhost refers to your workstation; copy the full URL from its address bar and paste it into Pi. The input closes automatically instead when the browser can reach Pi's callback directly.
+
+The same flow is available through the proxy tool for non-interactive clients. Persistent OAuth still requires an available OS credential store; on headless Linux that usually means an unlocked Secret Service/libsecret keyring. The adapter fails closed instead of falling back to plaintext credentials when the secure store is unavailable.
 
 On Linux, if credential access fails because Pi inherited a revoked session keyring, the adapter uses a best-effort recovery path through `keyctl session - node <packaged helper>` so explicit re-authentication can write fresh credentials without killing a long-lived tmux server. This path requires `keyctl` and `node` on `PATH`; missing, locked, or otherwise unavailable credential stores still fail closed.
 
@@ -372,9 +386,10 @@ Oversized MCP tool/resource results are guarded by default so a single huge resp
 
 - Inline text output is capped at **50 KiB / 2,000 lines** (matching Pi's built-in `bash` guard). Larger output is truncated to a head preview and the full text is saved to a temp file whose path is included in the result, so the agent can `read`/`grep` it.
 - **Image content blocks pass through unchanged** — only text output is guarded. Images are delivered to the provider as native image content.
+- Binary resource blobs up to **10 MiB** are decoded to private temp files and replaced with file references. Each session is limited to **100 MiB** and **10,000 files**. The files are removed at session teardown.
 - In proxy mode, `details.mcpResult` is kept raw when its JSON is **≤ 16 KiB**; larger results are replaced with a compact summary (block counts, sizes, key previews) and the raw JSON is saved to a temp file. Direct tools keep their lean details and never carry `mcpResult`.
 
-Tune the limits with the object form:
+Tune the text and details limits with the object form:
 
 ```json
 {
@@ -384,7 +399,7 @@ Tune the limits with the object form:
 }
 ```
 
-Set `"outputGuard": false` — or the env kill switch `MCP_OUTPUT_GUARD=0` — to disable the guard and restore raw output behavior. Saved temp files are created with mode `0600` under the system temp directory and are not cleaned up automatically; note that spilled MCP output may contain sensitive data.
+Set `"outputGuard": false` — or the env kill switch `MCP_OUTPUT_GUARD=0` — to disable text and details guarding. Binary resource materialization and its safety limits remain active. Output-guard spill files are created with mode `0600` under the system temp directory and are not cleaned up automatically; note that spilled MCP output may contain sensitive data.
 
 ### MCP Scripting
 

package/node_modules/pi-mcp-adapter/agent-dir.ts

@@ -1,3 +1,4 @@
+import { readFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join, resolve } from "node:path";
 
@@ -18,3 +19,42 @@ export function getAgentDir(): string {
 export function getAgentPath(...segments: string[]): string {
   return join(getAgentDir(), ...segments);
 }
+
+/**
+ * What the host calls itself.
+ *
+ * pi supports rebranding through `piConfig.name` in the package.json that its
+ * `getPackageDir()` resolves, and distributions built on pi (arc, tau, …) point
+ * `PI_PACKAGE_DIR` at their own manifest. Read that manifest directly rather
+ * than importing pi: this package deliberately depends on pi-ai and pi-tui
+ * only, and `getAgentDir()` above reads its env var the same self-contained way.
+ *
+ * Falls back to "pi", which is what pi's own APP_NAME resolves to.
+ */
+function readPiConfig(): { name?: unknown; clientUri?: unknown } | undefined {
+  const dir = process.env.PI_PACKAGE_DIR?.trim()
+  if (!dir) return undefined
+  try {
+    const manifest = JSON.parse(readFileSync(join(resolve(dir), "package.json"), "utf8")) as {
+      piConfig?: { name?: unknown; clientUri?: unknown }
+    }
+    return manifest.piConfig
+  } catch {
+    return undefined
+  }
+}
+
+export function getAppName(): string {
+  const name = readPiConfig()?.name
+  return typeof name === "string" && name.trim() ? name.trim() : "pi"
+}
+
+/**
+ * Home page the host declares for itself, via `piConfig.clientUri` in the same
+ * manifest that carries `piConfig.name`. Only the distribution knows its own
+ * URL, so this is the one place it can come from without guessing.
+ */
+export function getAppClientUri(): string | undefined {
+  const uri = readPiConfig()?.clientUri
+  return typeof uri === "string" && uri.trim() ? uri.trim() : undefined
+}

package/node_modules/pi-mcp-adapter/commands.ts

@@ -25,6 +25,10 @@ import { loadOnboardingState, markSetupCompleted as persistSetupCompleted, markS
 import { openPath, resolveServerUrl, sanitizeTerminalText } from "./utils.ts";
 import { isAbortError } from "./runtime-owner.ts";
 
+function terminalHyperlink(label: string, url: string): string {
+  return `\u001B]8;;${sanitizeTerminalText(url)}\u001B\\${sanitizeTerminalText(label)}\u001B]8;;\u001B\\`;
+}
+
 export async function showStatus(state: McpExtensionState, ctx: ExtensionContext): Promise<void> {
   if (!ctx.hasUI) return;
 
@@ -273,11 +277,17 @@ export async function authenticateServer(
       ...(authStorageOptions.baseDir ? { authStorageOptions } : {}),
       onAuthorizationUrl: (authorizationUrl) => {
         ui.notify(
-          `Open this URL to authenticate ${serverName}:\n\n${authorizationUrl}\n\n` +
-          "After approving, return to Pi; the local callback will complete automatically.",
+          `Open this URL to authenticate ${serverName}:\n\n${terminalHyperlink(authorizationUrl, authorizationUrl)}\n\n` +
+          "After approving, Pi will complete automatically if the browser can reach its localhost callback. " +
+          "On a remote machine, copy the full localhost URL from the browser address bar and paste it into Pi.",
           "info"
         );
       },
+      onAuthorizationInput: (_authorizationUrl, inputSignal) => ui.input(
+        `Complete ${serverName} OAuth`,
+        "Paste the full callback URL, or wait for automatic completion",
+        { signal: inputSignal },
+      ),
       ...(signal ? { signal } : {}),
       ...(runtime ? { runtime } : {}),
     });