@thoth-agents/pi-thoth-theme 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,29 @@
+MIT License
+
+Copyright (c) 2026 thoth-agents contributors
+Copyright (c) 2026 QuangThai
+Copyright (c) 2025 huynhgiabuu
+Copyright (c) 2026 Michael
+Copyright (c) 2025 Mario Zechner
+
+Includes code adapted from pi-omp-theme (QuangThai), the primary source, and
+pi-pretty (huynhgiabuu). pi-atelier (Michael) and gentle-shell (Mario Zechner)
+are reference-only projects; their code is not included in this package.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,116 @@
-# Temporary Holding Version
+# @thoth-agents/pi-thoth-theme
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Modular Thoth styling for Pi, with a gold-on-black Egyptian dark theme.
+
+Requires Pi `>=0.99.0` and Node `>=22.19.0`. Development Pi SDK/TUI
+dependencies are pinned to `1.0.2` in the root workspace lockfile.
+
+## Install
+
+From the thoth-agents repository root:
+
+```sh
+pi install ./pi-packages/pi-thoth-theme
+```
+
+Select the `thoth` theme in Pi's theme settings. Theme selection is independent
+of the module toggles below.
+
+## Modules
+
+- **Status line**: a responsive footer below the input showing cumulative
+  session cost (including subagents), main-session input/output totals, cache hit
+  percentage and output speed in `tok/s`. Input includes uncached, cache-read and
+  cache-write tokens; the hit percentage is cache-read divided by total input
+  (`—` when total input is zero). Subagent tokens are excluded. Narrow widths
+  drop speed, then cache, then tokens before truncating cost. Editor-border
+  metadata is decorated in place without claiming the custom editor slot.
+- **Tools**: boxed calls and results for `read`, `bash`, `powershell`, `ls`,
+  `grep`, `find`, `edit` and `write`, with Nerd Font icons or ASCII
+  alternatives. `bash` and `powershell` show a live elapsed time while running. Execution and
+  parameters delegate to Pi's built-in tools; Pi's native output toggle still
+  collapses and expands results. Registered non-built-in tools keep their own
+  renderers when their package matches `tools.respectPackages` (including
+  thoth-agents and thoth-mem by default). Other tools get a generic frame with
+  the tool name, a one-line argument summary, a collapsed text preview, error
+  styling and a live elapsed footer. Images keep Pi's native rendering.
+  Tool renderers require Pi `>=1.0.1`; they are runtime-guarded and inert on
+  older supported Pi versions.
+- **Welcome**: a header with the Thoth logo, Pi version, loaded resources and
+  tool providers, and recent sessions. Resource and session details load
+  best-effort through public APIs.
+
+## Render KIT
+
+Provides the Render KIT v1 contract defined by `@thoth-agents/pi-core` for
+first-party tools, custom messages and above-editor widgets. The kit shares this
+package's frames, theme roles, collapse hints and working/elapsed indicators.
+Producers discover it at render time, so extension load order does not matter;
+they do not depend on this package and keep native Pi rendering when it is absent.
+
+The theme registers the kit on `session_start` only in interactive UI sessions
+with `tools.enabled: true`, and withdraws only its own registration on
+`session_shutdown`. Headless children neither replace nor withdraw the parent
+kit, and their lifecycle does not stop the parent's indicators. Theme selection
+alone does not enable the kit when tool styling is disabled.
+
+## Configuration
+
+Edit `~/.pi/agent/pi-thoth-theme.json` (or
+`$PI_CODING_AGENT_DIR/pi-thoth-theme.json` when that environment variable is set):
+
+```json
+{
+  "icons": "nerd",
+  "statusLine": {
+    "enabled": true,
+    "subscriptionProviders": ["claude-bridge"]
+  },
+  "inputBox": { "enabled": true },
+  "tools": {
+    "enabled": true,
+    "respectPackages": ["thoth-agents", "@thoth-agents/*", "thoth-mem"]
+  },
+  "welcome": { "enabled": true }
+}
+```
+
+`icons` accepts `"nerd"` (default) or `"ascii"`. Each module's `enabled` key
+accepts a boolean and defaults to `true`. Set it to `false` to leave Pi's native
+behavior on that surface. `statusLine.subscriptionProviders` accepts an array of
+provider identifier strings (defaults to `["claude-bridge"]`) to mark
+subscription-backed usage with `(sub)` in the status line cost segment.
+
+`inputBox.enabled` defaults to `true` and requires `statusLine.enabled` to be
+`true`. It frames the native editor in a rounded `muted` (sand) box with side borders,
+a dim `type or / for commands` placeholder, and top-left ready or native working
+status (including elapsed seconds). Git branch and working directory appear on
+the top border; model, thinking effort and context usage appear on the bottom.
+Native scroll indicators are preserved. The status line always stays in its
+separate footer row below the box. Narrow widths use the native editor geometry.
+Disable `inputBox` to keep the native editor and the same footer.
+
+`tools.respectPackages` accepts an array of non-empty package-name strings.
+The default is `["thoth-agents", "@thoth-agents/*", "thoth-mem"]`. Entries match
+exact package names or a trailing `/*` scope wildcard: `@scope/*` matches
+`@scope/anything`, but not `@scopex/anything`. No other globs are supported.
+A user list **fully replaces** the default; `[]` gives every registered
+non-built-in tool a generic frame, even if it supplies its own renderers.
+Invalid values (including any empty, whitespace-only or non-string entry) use
+the full default list. Package names come from the nearest `package.json`
+walking upward from the tool's source directory. Built-ins always use the
+themed frames; tools absent from Pi's registry keep their own renderers.
+
+Configuration is read at extension load; use `/reload` after edits. Missing,
+malformed or invalid values use defaults. Pi settings are never read for
+package configuration.
+
+**A Nerd Font is required for the default icons.** Configure your terminal to
+use one, or set `"icons": "ascii"` for plain-text alternatives.
+
+## Attribution
+
+MIT; see [LICENSE](LICENSE). Includes code adapted from the primary upstream,
+[pi-omp-theme](https://github.com/QuangThai/pi-omp-theme) by QuangThai, and
+pi-pretty by huynhgiabuu. pi-atelier by Michael and gentle-shell by Mario Zechner
+are references only, not bundled code.

package/package.json

@@ -1,6 +1,66 @@
 {
   "name": "@thoth-agents/pi-thoth-theme",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "private": false,
+  "description": "Modular Thoth theme, status line, tool styling, and welcome header for Pi.",
+  "license": "MIT",
+  "type": "module",
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "pi",
+    "theme"
+  ],
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ],
+    "themes": [
+      "./themes"
+    ]
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/EremesNG/thoth-agents.git",
+    "directory": "pi-packages/pi-thoth-theme"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "src/**/*.ts",
+    "!src/**/*.test.ts",
+    "themes/**",
+    "README.md",
+    "LICENSE"
+  ],
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": ">=0.99.0",
+    "@earendil-works/pi-tui": ">=0.99.0",
+    "typebox": "*"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "typebox": "^1.3.4",
+    "typescript": "^5.8.0",
+    "vitest": "^4.1.9",
+    "@earendil-works/pi-coding-agent": "1.0.2",
+    "@earendil-works/pi-tui": "1.0.2",
+    "@earendil-works/pi-ai": "1.0.2",
+    "@rolldown/binding-wasm32-wasi": "^1.2.4"
+  },
+  "upstream": {
+    "repository": "https://github.com/QuangThai/pi-omp-theme",
+    "role": "primary source"
+  },
+  "dependencies": {
+    "@thoth-agents/pi-core": "^0.1.0"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  }
 }

package/src/index.ts

@@ -0,0 +1,53 @@
+import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
+import {
+  type RenderKitToken,
+  registerRenderKit,
+  withdrawRenderKit,
+} from '@thoth-agents/pi-core';
+import { createRenderKit } from './render-kit/index.ts';
+import { loadConfig } from './shared/config.ts';
+import { frames, icon } from './shared/icons.ts';
+import { registerStatusLine } from './status-line/index.ts';
+import { createToolRendererResolver, registerTools } from './tools/index.ts';
+import { registerWelcome } from './welcome/index.ts';
+
+export default function thothTheme(pi: ExtensionAPI): void {
+  const config = loadConfig();
+  const owner = {};
+  const cwd = process.cwd();
+  const resolveToolRenderers = config.tools.enabled
+    ? createToolRendererResolver(pi, config, cwd)
+    : undefined;
+  let kitToken: RenderKitToken | undefined;
+  if (resolveToolRenderers) {
+    registerTools(pi, config, cwd, owner, resolveToolRenderers);
+  }
+
+  pi.on('session_shutdown', (_event, ctx) => {
+    if (!ctx.hasUI || kitToken === undefined) return;
+    withdrawRenderKit(kitToken);
+    kitToken = undefined;
+  });
+
+  pi.on('session_start', (_event, ctx) => {
+    if (!ctx.hasUI) return;
+    if (config.tools.enabled) {
+      kitToken = registerRenderKit(
+        createRenderKit(owner, resolveToolRenderers, config.icons),
+        owner,
+      );
+    }
+    if (!ctx.ui) return;
+    if (config.statusLine.enabled) {
+      if (config.inputBox?.enabled !== false) {
+        ctx.ui.setWorkingIndicator?.({
+          frames: [...frames('workingFrames', config.icons)],
+          intervalMs: 200,
+        });
+        ctx.ui.setWorkingMessage?.(`working${icon('ellipsis', config.icons)}`);
+      }
+      registerStatusLine(pi, ctx, config);
+    }
+    if (config.welcome.enabled) registerWelcome(pi, ctx, config);
+  });
+}

package/src/input-box/decorate.ts

@@ -0,0 +1,304 @@
+import {
+  type TuiMouseEvent,
+  type TuiMouseEventResult,
+  truncateToWidth,
+  visibleWidth,
+} from '@earendil-works/pi-tui';
+import type { IconMode } from '../shared/config.ts';
+import {
+  type ActiveThemeLike,
+  formatBranchSegment,
+  formatContextSegments,
+  formatCwdSegments,
+  formatModelSegments,
+} from '../status-line/layout.ts';
+import type {
+  StatusSnapshot,
+  StatusSnapshotProvider,
+} from '../status-line/snapshot.ts';
+import {
+  inputLabelWidth,
+  renderInputBottom,
+  renderInputTop,
+  renderPlaceholder,
+  scrollLabel,
+  wrapContentRow,
+} from './frame.ts';
+import { type BreathingFrame, createBreathingFrame } from './gradient.ts';
+import type { WorkingState } from './state.ts';
+
+export const MIN_INPUT_BOX_WIDTH = 16;
+
+interface EditorLike {
+  render(width: number): string[];
+  renderTopBorder(width: number, hiddenLineCount: number): string;
+  renderBottomBorder(width: number, hiddenLineCount: number): string;
+  getText(): string;
+  getPaddingX(): number;
+  handleMouse(event: TuiMouseEvent): TuiMouseEventResult | undefined;
+  borderColor(text: string): string;
+  workingStatusIndicator?: unknown;
+}
+
+export interface InputBoxDeps {
+  theme: ActiveThemeLike;
+  working: WorkingState;
+  /** Omission retains Unicode glyphs; may be a live getter. */
+  readonly iconMode?: IconMode;
+  /** Shared live data; optional for standalone decorator consumers. */
+  getStatusSnapshot?: StatusSnapshotProvider;
+}
+
+export interface EditorDecoration {
+  getStatusSnapshot(): Readonly<StatusSnapshot> | undefined;
+  dispose(): void;
+}
+
+const decoratedEditors = new WeakSet<object>();
+const decorations = new WeakMap<object, EditorDecoration>();
+const methodNames = [
+  'render',
+  'renderTopBorder',
+  'renderBottomBorder',
+  'getText',
+  'getPaddingX',
+  'handleMouse',
+  'borderColor',
+] as const;
+
+// Do not read editor.render: the background-task Proxy getter dynamically calls
+// target.render, which would recurse after replacing that same target method.
+function method<Name extends keyof EditorLike>(
+  editor: object,
+  name: Name,
+): EditorLike[Name] | undefined {
+  for (
+    let owner: object | null = editor;
+    owner;
+    owner = Reflect.getPrototypeOf(owner)
+  ) {
+    const descriptor = Reflect.getOwnPropertyDescriptor(owner, name);
+    if (descriptor)
+      return typeof descriptor.value === 'function'
+        ? descriptor.value
+        : undefined;
+  }
+  return undefined;
+}
+
+export function isEditorLike(editor: unknown): editor is EditorLike {
+  if (!editor || typeof editor !== 'object') return false;
+  if (decoratedEditors.has(editor)) return true;
+  try {
+    return methodNames.every((name) => method(editor, name) !== undefined);
+  } catch {
+    return false;
+  }
+}
+
+export function decorateEditor(
+  editor: unknown,
+  deps: InputBoxDeps,
+): EditorDecoration | undefined {
+  if (!isEditorLike(editor)) return undefined;
+  if (decoratedEditors.has(editor)) return decorations.get(editor);
+  const names = [
+    'render',
+    'renderTopBorder',
+    'renderBottomBorder',
+    'handleMouse',
+    'borderColor',
+  ] as const;
+  if (
+    !Reflect.isExtensible(editor) ||
+    names.some(
+      (name) =>
+        Reflect.getOwnPropertyDescriptor(editor, name)?.configurable === false,
+    )
+  )
+    return undefined;
+  const originals = Object.fromEntries(
+    methodNames.map((name) => [name, method(editor, name)]),
+  ) as unknown as EditorLike;
+  const descriptors = new Map(
+    names.map((name) => [name, Reflect.getOwnPropertyDescriptor(editor, name)]),
+  );
+  let active = true;
+  let outerWidth: number | undefined;
+  let fallback = false;
+  let top: string | undefined;
+  let bottom: string | undefined;
+  let renderFrame: BreathingFrame | undefined;
+  // Mouse hit-testing follows the last render's boxed or native geometry.
+  let boxRendered = false;
+  const muted = (text: string) => deps.theme.fg?.('muted', text) ?? text;
+
+  function nativeRender(receiver: EditorLike, width: number): string[] {
+    fallback = true;
+    try {
+      return originals.render.call(receiver, width);
+    } finally {
+      fallback = false;
+    }
+  }
+
+  const patches: PropertyDescriptorMap = {
+    render: {
+      configurable: true,
+      writable: true,
+      value(this: EditorLike, width: number): string[] {
+        boxRendered = false;
+        if (!active || width < MIN_INPUT_BOX_WIDTH)
+          return nativeRender(this, width);
+        const boxWidth = Math.floor(width);
+        const innerWidth = boxWidth - 2;
+        const maxPadding = Math.max(0, Math.floor((innerWidth - 1) / 2));
+        const paddingX = Math.min(originals.getPaddingX.call(this), maxPadding);
+        const contentWidth = Math.max(1, innerWidth - paddingX * 2);
+        const layoutWidth = Math.max(1, contentWidth - (paddingX ? 0 : 1));
+        // Native word wrapping recurses on a wide grapheme at width 1. Keep
+        // its original geometry when the box plus current padding is unsafe.
+        if (layoutWidth < 2) return nativeRender(this, width);
+        // Share one time/color sample with the native status and every border.
+        const frame = deps.working.isWorking
+          ? createBreathingFrame(Date.now())
+          : undefined;
+        renderFrame = frame;
+        outerWidth = boxWidth;
+        top = undefined;
+        bottom = undefined;
+        let lines: string[];
+        try {
+          lines = originals.render.call(this, outerWidth - 2);
+        } finally {
+          outerWidth = undefined;
+          renderFrame = undefined;
+        }
+        const bottomIndex =
+          bottom === undefined ? -1 : lines.indexOf(bottom, 1);
+        if (top === undefined || lines[0] !== top || bottomIndex < 2)
+          return nativeRender(this, width);
+        const text = originals.getText.call(this);
+        lines = lines.map((line, index) => {
+          if (index === 0 || index === bottomIndex) return line;
+          if (index > bottomIndex)
+            return ` ${truncateToWidth(line, width - 2, '', true)} `;
+          return wrapContentRow(
+            renderPlaceholder(line, width - 2, deps.theme, text),
+            width,
+            deps.theme,
+            frame,
+          );
+        });
+        boxRendered = true;
+        return lines;
+      },
+    },
+    renderTopBorder: {
+      configurable: true,
+      writable: true,
+      value(this: EditorLike, width: number, hidden: number): string {
+        if (
+          outerWidth === undefined ||
+          (hidden > 0 &&
+            visibleWidth(scrollLabel('up', hidden, deps.iconMode)) >
+              outerWidth - 6)
+        )
+          return originals.renderTopBorder.call(this, width, hidden);
+        const status = deps.working.status(
+          this.workingStatusIndicator,
+          inputLabelWidth(outerWidth, hidden, deps.iconMode),
+          muted,
+          renderFrame,
+          deps.iconMode,
+        );
+        const data = active ? deps.getStatusSnapshot?.() : undefined;
+        const options = { mode: deps.iconMode, theme: deps.theme };
+        top = renderInputTop(
+          outerWidth,
+          deps.theme,
+          {
+            left: [status, data ? formatBranchSegment(data, options) : ''],
+            right: data ? formatCwdSegments(data, options) : [],
+          },
+          hidden,
+          renderFrame,
+          deps.iconMode,
+        );
+        return top;
+      },
+    },
+    renderBottomBorder: {
+      configurable: true,
+      writable: true,
+      value(this: EditorLike, width: number, hidden: number): string {
+        if (
+          outerWidth === undefined ||
+          (hidden > 0 &&
+            visibleWidth(scrollLabel('down', hidden, deps.iconMode)) >
+              outerWidth - 6)
+        )
+          return originals.renderBottomBorder.call(this, width, hidden);
+        const data = active ? deps.getStatusSnapshot?.() : undefined;
+        const options = { mode: deps.iconMode, theme: deps.theme };
+        bottom = renderInputBottom(
+          outerWidth,
+          deps.theme,
+          {
+            left: data ? formatModelSegments(data, options) : [],
+            right: data ? formatContextSegments(data, options) : [],
+          },
+          hidden,
+          renderFrame,
+          deps.iconMode,
+        );
+        return bottom;
+      },
+    },
+    handleMouse: {
+      configurable: true,
+      writable: true,
+      value(
+        this: EditorLike,
+        event: TuiMouseEvent,
+      ): TuiMouseEventResult | undefined {
+        const translated =
+          active && boxRendered
+            ? { ...event, x: event.x - 1, width: event.width - 2 }
+            : event;
+        return originals.handleMouse.call(this, translated);
+      },
+    },
+    borderColor: {
+      configurable: true,
+      get: () => (fallback ? originals.borderColor : muted),
+      set: () => {},
+    },
+  };
+  Object.defineProperties(editor, patches);
+  const decoration: EditorDecoration = {
+    getStatusSnapshot: () => (active ? deps.getStatusSnapshot?.() : undefined),
+    dispose() {
+      if (!active) return;
+      active = false;
+      for (const name of names) {
+        const current = Reflect.getOwnPropertyDescriptor(editor, name);
+        const patch = patches[name];
+        if (
+          current?.value !== patch.value ||
+          current?.get !== patch.get ||
+          current?.set !== patch.set
+        )
+          continue;
+        const descriptor = descriptors.get(name);
+        if (descriptor) Object.defineProperty(editor, name, descriptor);
+        else Reflect.deleteProperty(editor, name);
+      }
+      decoratedEditors.delete(editor);
+      decorations.delete(editor);
+    },
+  };
+  decoratedEditors.add(editor);
+  decorations.set(editor, decoration);
+  return decoration;
+}