pi-widget-host 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,20 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+This project follows semantic versioning.
+
+## [0.2.0] - 2026-06-15
+
+### Added
+
+- Shared-slot host extension with `/widget-host:setup`, `/widget-host:status`, `/widget-host:policy`, `/widget-host:providers`, `/widget-host:mute`, and `/widget-host:unmute`.
+- User-global host config under `~/.pi/agent/pi-widget-host-config.json`.
+- `globalThis` registry protocol for provider publish/list/remove/subscribe flows.
+- Built-in demo provider with silent empty slot behavior.
+- Preset-first time block policy plus event boost for `playing-now` and `matchday`.
+- Protocol and package docs for the Host-only MVP.
+
+### Changed
+
+- Replaced template placeholders and removed template-only skill, prompt, and theme resources.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Keisu
+
+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

@@ -0,0 +1,136 @@
+# Pi Widget Host
+
+[![CI](https://github.com/eiei114/pi-widget-host/actions/workflows/ci.yml/badge.svg)](https://github.com/eiei114/pi-widget-host/actions/workflows/ci.yml)
+[![Publish](https://github.com/eiei114/pi-widget-host/actions/workflows/publish.yml/badge.svg)](https://github.com/eiei114/pi-widget-host/actions/workflows/publish.yml)
+[![npm version](https://img.shields.io/npm/v/pi-widget-host.svg)](https://www.npmjs.com/package/pi-widget-host)
+[![npm downloads](https://img.shields.io/npm/dm/pi-widget-host.svg)](https://www.npmjs.com/package/pi-widget-host)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Pi package](https://img.shields.io/badge/pi-package-purple.svg)](https://pi.dev/packages)
+[![Trusted Publishing](https://img.shields.io/badge/npm-Trusted%20Publishing-blue.svg)](docs/release.md)
+
+> Shared-slot host for managing one prompt-top Pi widget across multiple providers.
+
+## What this is
+
+`pi-widget-host` owns one shared widget slot in Pi and picks a single winner from registered providers.
+
+v1 is a **Host-only MVP**:
+
+- user-global config under `~/.pi/agent/`
+- preset-first time-block policy
+- `globalThis` registry protocol for future provider packages
+- built-in demo provider for setup and dogfooding
+- silent empty slot when nothing should render
+
+## Features
+
+- `/widget-host:setup` guided first-run flow
+- `/widget-host:status`, `/widget-host:policy`, `/widget-host:providers`
+- `/widget-host:mute` and `/widget-host:unmute`
+- event boost for `playing-now` and `matchday`
+- known host tags: `music`, `sports`, `playing-now`, `matchday`, `idle`
+
+## Install
+
+Published package:
+
+```bash
+pi install npm:pi-widget-host
+```
+
+GitHub install:
+
+```bash
+pi install git:github.com/eiei114/pi-widget-host
+```
+
+Local dev:
+
+```bash
+pi -e .
+```
+
+## Quick start
+
+Run the host locally, then open these commands:
+
+```txt
+/widget-host:setup
+/widget-host:status
+/widget-host:providers
+```
+
+`/widget-host:setup` asks whether to enable the built-in demo provider and which preset policy to save.
+
+## Commands
+
+- `/widget-host:setup` — save initial preset and optionally enable the demo provider
+- `/widget-host:status` — report setup status, preset, and active provider
+- `/widget-host:policy` — show or change the saved preset
+- `/widget-host:providers` — inspect known provider entries and effective state
+- `/widget-host:mute` — mute one provider in host config
+- `/widget-host:unmute` — unmute one provider in host config
+
+Commands take no inline arguments. Input is collected with Pi UI prompts.
+
+## Registry protocol
+
+Future provider packages can publish to the host without importing this package at runtime.
+
+- backing: `globalThis`
+- symbol: `Symbol.for("pi-widget-host.registry.v1")`
+- required fields: `providerId`, `available`, `lines`, `updatedAt`
+- optional fields: `priority`, `tags`, `mode`, `ttlMs`
+
+See [`docs/protocol.md`](docs/protocol.md).
+
+## Built-in demo provider
+
+The built-in demo provider exists to prove the host loop first:
+
+- setup enables it explicitly
+- it publishes through the same registry protocol as future packages
+- it renders provider-owned lines through the shared host slot
+- if muted, disabled, or filtered out by policy, the slot disappears
+
+## Package contents
+
+| Path | Purpose |
+|---|---|
+| `extensions/` | Pi extension entrypoint and command registration |
+| `lib/` | config store, registry protocol, policy evaluation, demo provider |
+| `docs/` | supporting docs such as release and protocol notes |
+
+## Development
+
+```bash
+npm install
+npm run ci
+```
+
+## Release
+
+This package uses npm Trusted Publishing.
+
+```bash
+npm version patch
+git push
+```
+
+See [`docs/release.md`](docs/release.md).
+
+## Security
+
+Pi packages execute with your local permissions. Review extensions before installing third-party packages.
+
+For vulnerability reporting, see [`SECURITY.md`](SECURITY.md).
+
+## Links
+
+- npm: https://www.npmjs.com/package/pi-widget-host
+- GitHub: https://github.com/eiei114/pi-widget-host
+- Issues: https://github.com/eiei114/pi-widget-host/issues
+
+## License
+
+MIT

package/docs/protocol.md

@@ -0,0 +1,53 @@
+# Registry protocol
+
+`pi-widget-host` exposes a process-local provider registry on `globalThis`.
+
+## Symbol
+
+```ts
+Symbol.for("pi-widget-host.registry.v1")
+```
+
+## Registry shape
+
+```ts
+type ProviderEntry = {
+  providerId: string;
+  available: boolean;
+  lines: string[];
+  updatedAt: string;
+  priority?: number;
+  tags?: string[];
+  mode?: string;
+  ttlMs?: number;
+};
+
+type WidgetHostRegistry = {
+  version: 1;
+  set(entry: ProviderEntry): void;
+  remove(providerId: string): void;
+  list(): ProviderEntry[];
+  subscribe(listener: () => void): () => void;
+};
+```
+
+## Required fields
+
+- `providerId`
+- `available`
+- `lines`
+- `updatedAt`
+
+## Optional fields
+
+- `priority`
+- `tags`
+- `mode`
+- `ttlMs`
+
+## Notes
+
+- unknown tags are ignored safely by the host
+- `ttlMs` + `updatedAt` drive stale exclusion
+- providers render final lines themselves; the host only picks a winner
+- the host can mute providers from config without uninstalling the package

package/docs/release.md

@@ -0,0 +1,57 @@
+# Release
+
+This package uses npm Trusted Publishing with GitHub Actions OIDC.
+
+Do not add `NPM_TOKEN` or long-lived npm tokens to GitHub Secrets.
+
+## One-time npm setup
+
+On npmjs.com, configure Trusted Publishing for this package:
+
+- Publisher: GitHub Actions
+- Repository: this GitHub repository
+- Workflow filename: `publish.yml`
+
+## Publish
+
+```bash
+npm version patch
+git push
+```
+
+On `main`, `.github/workflows/auto-release.yml` checks `package.json` version. If `v<version>` does not exist yet, it creates the tag, creates the GitHub Release, then explicitly dispatches `.github/workflows/publish.yml` for that tag.
+
+The `v*.*.*` tag also triggers `.github/workflows/publish.yml`, which runs CI and publishes to npm when tags are pushed manually.
+Publishing also runs when a GitHub Release is published, and can be run manually from GitHub Actions with `workflow_dispatch`.
+
+The workflow skips `name@version` if that exact package version already exists on npm.
+
+## Workflow guardrail
+
+Do not ship a new Pi OSS package or version bump with only `package.json` changes.
+The repository must include the release workflow pair:
+
+- `.github/workflows/auto-release.yml` creates `v<version>` tags and GitHub Releases from `main` version bumps.
+- `.github/workflows/publish.yml` publishes to npm through Trusted Publishing.
+
+Important: tags or releases created by `GITHUB_TOKEN` do not reliably fan out into another workflow through normal `push.tags` or `release.published` triggers. The template keeps publishing reliable by having `auto-release.yml` explicitly dispatch `publish.yml` after creating the tag/release. If you change the release flow, keep one explicit handoff path: `workflow_dispatch` from auto-release, `repository_dispatch`, or `workflow_run` on the auto-release workflow.
+
+## GitHub Actions requirements
+
+- `permissions: id-token: write`
+- `permissions: actions: write` on auto-release so it can dispatch `publish.yml`
+- `auto-release.yml` must call `gh workflow run publish.yml --ref "$TAG" -f ref="$TAG"`, or `publish.yml` must have an equivalent explicit handoff trigger such as `workflow_run`
+- GitHub-hosted runner
+- Node.js 24, so the release job uses a current npm CLI for Trusted Publishing
+- No `NPM_TOKEN`
+- `npm publish` from the configured workflow file
+
+## First release checklist
+
+- [ ] `package.json` name is final
+- [ ] `repository.url` points to the real GitHub repository
+- [ ] npm Trusted Publisher is configured
+- [ ] `npm run ci` passes
+- [ ] `npm pack --dry-run` contains only intended files
+- [ ] CHANGELOG.md has the release date
+

package/extensions/index.ts

@@ -0,0 +1,258 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { readHostConfig, updateHostConfig, writeHostConfig } from "../lib/config.ts";
+import { stopDemoProviderHeartbeat, syncBuiltInDemoProvider } from "../lib/demo-provider.ts";
+import { DEFAULT_PRESET_ID, describePreset, evaluateProviderEntries, getPreset, getRemainingTtlMs, PRESET_OPTIONS } from "../lib/policy.ts";
+import { getWidgetHostRegistry, listProviderEntries, removeProviderEntry } from "../lib/registry.ts";
+import { DEMO_PROVIDER_ID, WIDGET_ID, type HostConfig, type PolicyEvaluationResult, type ProviderState } from "../lib/types.ts";
+
+type NotifyLevel = "info" | "warning" | "error";
+
+interface HostUiBridge {
+  setWidget: (id: string, lines: string[] | undefined) => void;
+  notify: (message: string, level: NotifyLevel) => void;
+  setStatus: (key: string, value: string | undefined) => void;
+  select: (prompt: string, options: string[]) => Promise<string | undefined>;
+}
+
+let uiBridge: HostUiBridge | undefined;
+let registryDispose: (() => void) | undefined;
+let staleTimer: NodeJS.Timeout | undefined;
+
+function bindUi(ctx: { hasUI: boolean; ui: HostUiBridge }): void {
+  if (!ctx.hasUI) return;
+  uiBridge = ctx.ui;
+}
+
+function clearStaleTimer(): void {
+  if (!staleTimer) return;
+  clearTimeout(staleTimer);
+  staleTimer = undefined;
+}
+
+function summarizeProvider(state: ProviderState): string {
+  const tags = state.knownTags.length > 0 ? state.knownTags.join(",") : "none";
+  const detail = state.reasons.length > 0 ? ` | ${state.reasons.join("; ")}` : "";
+  return `${state.providerId} [${state.effectiveStatus}] prio=${state.effectivePriority} tags=${tags}${detail}`;
+}
+
+function summarizeStatus(config: HostConfig, result: PolicyEvaluationResult): string {
+  const active = result.activeProvider?.providerId ?? "none";
+  return [
+    `Setup: ${config.setupComplete ? "done" : "not yet"}`,
+    `Preset: ${result.preset.label} (${result.timeBlock})`,
+    `Demo provider: ${config.demoProviderEnabled ? "enabled" : "disabled"}`,
+    `Active provider: ${active}`,
+  ].join("\n");
+}
+
+function summarizeProviders(result: PolicyEvaluationResult): string {
+  if (result.providerStates.length === 0) {
+    return `Providers (${result.timeBlock}): none registered`;
+  }
+
+  return [`Providers (${result.timeBlock}):`, ...result.providerStates.map((state) => `- ${summarizeProvider(state)}`)].join("\n");
+}
+
+async function refreshHostWidget(ctx?: { hasUI: boolean; ui: HostUiBridge }): Promise<{ config: HostConfig; result: PolicyEvaluationResult }> {
+  if (ctx) bindUi(ctx);
+
+  const config = await readHostConfig();
+  await syncBuiltInDemoProvider(config);
+
+  const result = evaluateProviderEntries(listProviderEntries(), config, new Date());
+  uiBridge?.setWidget(WIDGET_ID, result.activeProvider?.lines);
+  uiBridge?.setStatus("widget-host", `${result.preset.label} | active: ${result.activeProvider?.providerId ?? "none"}`);
+
+  clearStaleTimer();
+  const nextTtlMs = result.providerStates
+    .map((state) => getRemainingTtlMs(state, Date.now()))
+    .filter((value): value is number => typeof value === "number" && value > 0)
+    .sort((a, b) => a - b)[0];
+
+  if (typeof nextTtlMs === "number") {
+    staleTimer = setTimeout(() => {
+      void refreshHostWidget().catch(() => undefined);
+    }, Math.max(nextTtlMs + 25, 25));
+  }
+
+  return { config, result };
+}
+
+function ensureRegistryWatcher(): void {
+  if (registryDispose) return;
+  registryDispose = getWidgetHostRegistry().subscribe(() => {
+    void refreshHostWidget().catch(() => undefined);
+  });
+}
+
+async function selectPreset(ctx: { ui: Pick<HostUiBridge, "select"> }, prompt: string): Promise<string | undefined> {
+  const labels = PRESET_OPTIONS.map((preset) => `${preset.label} — ${preset.description}`);
+  const picked = await ctx.ui.select(prompt, labels);
+  if (!picked) return undefined;
+  const index = labels.indexOf(picked);
+  return index >= 0 ? PRESET_OPTIONS[index]?.id : undefined;
+}
+
+function ensureInteractive(ctx: { hasUI: boolean }): boolean {
+  if (ctx.hasUI) return true;
+  uiBridge?.notify("widget-host commands need Pi UI mode.", "warning");
+  return false;
+}
+
+export default function widgetHostExtension(pi: ExtensionAPI) {
+  pi.on("session_start", async (_event, ctx) => {
+    if (!ctx.hasUI) return;
+    bindUi(ctx as { hasUI: boolean; ui: HostUiBridge });
+    ensureRegistryWatcher();
+    await refreshHostWidget(ctx as { hasUI: boolean; ui: HostUiBridge });
+  });
+
+  pi.on("session_shutdown", async () => {
+    clearStaleTimer();
+    registryDispose?.();
+    registryDispose = undefined;
+    stopDemoProviderHeartbeat();
+    removeProviderEntry(DEMO_PROVIDER_ID);
+    uiBridge = undefined;
+  });
+
+  pi.registerCommand("widget-host:setup", {
+    description: "Configure pi-widget-host and optionally enable the built-in demo provider.",
+    handler: async (_args, ctx) => {
+      if (!ensureInteractive(ctx)) return;
+      bindUi(ctx as { hasUI: boolean; ui: HostUiBridge });
+      ensureRegistryWatcher();
+
+      const current = await readHostConfig();
+      const demoChoice = await ctx.ui.select("widget-host setup | built-in demo provider", [
+        "Enable demo provider",
+        "Keep host silent",
+      ]);
+      if (!demoChoice) return;
+
+      const presetId = await selectPreset(ctx as { ui: Pick<HostUiBridge, "select"> }, "widget-host setup | choose a preset");
+      if (!presetId) return;
+
+      const next = await writeHostConfig({
+        ...current,
+        setupComplete: true,
+        demoProviderEnabled: demoChoice === "Enable demo provider",
+        presetId,
+      });
+
+      await syncBuiltInDemoProvider(next);
+      const { result } = await refreshHostWidget(ctx as { hasUI: boolean; ui: HostUiBridge });
+      ctx.ui.notify(`Saved setup. ${summarizeStatus(next, result)}`, "info");
+    },
+  });
+
+  pi.registerCommand("widget-host:status", {
+    description: "Show current host setup, preset, and active provider state.",
+    handler: async (_args, ctx) => {
+      bindUi(ctx as { hasUI: boolean; ui: HostUiBridge });
+      ensureRegistryWatcher();
+      const { config, result } = await refreshHostWidget(ctx as { hasUI: boolean; ui: HostUiBridge });
+      if (ctx.hasUI) {
+        ctx.ui.notify(summarizeStatus(config, result), "info");
+      }
+    },
+  });
+
+  pi.registerCommand("widget-host:policy", {
+    description: "Inspect or change the saved preset-first host policy.",
+    handler: async (_args, ctx) => {
+      if (!ensureInteractive(ctx)) return;
+      bindUi(ctx as { hasUI: boolean; ui: HostUiBridge });
+      ensureRegistryWatcher();
+
+      const current = await readHostConfig();
+      const currentPreset = getPreset(current.presetId || DEFAULT_PRESET_ID);
+      const action = await ctx.ui.select(`widget-host policy | current: ${currentPreset.label}`, ["Show policy", "Change preset"]);
+      if (!action) return;
+
+      if (action === "Show policy") {
+        ctx.ui.notify(describePreset(currentPreset), "info");
+        return;
+      }
+
+      const presetId = await selectPreset(ctx as { ui: Pick<HostUiBridge, "select"> }, "widget-host policy | choose a preset");
+      if (!presetId) return;
+
+      const next = await updateHostConfig((config) => ({
+        ...config,
+        setupComplete: true,
+        presetId,
+      }));
+
+      const { result } = await refreshHostWidget(ctx as { hasUI: boolean; ui: HostUiBridge });
+      ctx.ui.notify(`Policy saved: ${getPreset(next.presetId).label}. Active provider: ${result.activeProvider?.providerId ?? "none"}`, "info");
+    },
+  });
+
+  pi.registerCommand("widget-host:providers", {
+    description: "List known providers and their effective host state.",
+    handler: async (_args, ctx) => {
+      bindUi(ctx as { hasUI: boolean; ui: HostUiBridge });
+      ensureRegistryWatcher();
+      const { result } = await refreshHostWidget(ctx as { hasUI: boolean; ui: HostUiBridge });
+      if (ctx.hasUI) {
+        ctx.ui.notify(summarizeProviders(result), "info");
+      }
+    },
+  });
+
+  pi.registerCommand("widget-host:mute", {
+    description: "Mute one registered provider in the global host config.",
+    handler: async (_args, ctx) => {
+      if (!ensureInteractive(ctx)) return;
+      bindUi(ctx as { hasUI: boolean; ui: HostUiBridge });
+      ensureRegistryWatcher();
+
+      const { result } = await refreshHostWidget(ctx as { hasUI: boolean; ui: HostUiBridge });
+      const candidates = result.providerStates.filter((state) => !state.isMuted).map((state) => `${state.providerId} — ${state.effectiveStatus}`);
+      if (candidates.length === 0) {
+        ctx.ui.notify("No unmuted providers available.", "warning");
+        return;
+      }
+
+      const picked = await ctx.ui.select("widget-host mute | choose provider", candidates);
+      if (!picked) return;
+      const providerId = picked.split(" — ")[0]?.trim();
+      if (!providerId) return;
+
+      await updateHostConfig((config) => ({
+        ...config,
+        mutedProviderIds: [...new Set([...config.mutedProviderIds, providerId])],
+      }));
+
+      const { result: next } = await refreshHostWidget(ctx as { hasUI: boolean; ui: HostUiBridge });
+      ctx.ui.notify(`Muted ${providerId}. Active provider: ${next.activeProvider?.providerId ?? "none"}`, "info");
+    },
+  });
+
+  pi.registerCommand("widget-host:unmute", {
+    description: "Unmute one provider in the global host config.",
+    handler: async (_args, ctx) => {
+      if (!ensureInteractive(ctx)) return;
+      bindUi(ctx as { hasUI: boolean; ui: HostUiBridge });
+      ensureRegistryWatcher();
+
+      const { config } = await refreshHostWidget(ctx as { hasUI: boolean; ui: HostUiBridge });
+      if (config.mutedProviderIds.length === 0) {
+        ctx.ui.notify("No muted providers stored in config.", "warning");
+        return;
+      }
+
+      const providerId = await ctx.ui.select("widget-host unmute | choose provider", config.mutedProviderIds);
+      if (!providerId) return;
+
+      await updateHostConfig((nextConfig) => ({
+        ...nextConfig,
+        mutedProviderIds: nextConfig.mutedProviderIds.filter((id) => id !== providerId),
+      }));
+
+      const { result } = await refreshHostWidget(ctx as { hasUI: boolean; ui: HostUiBridge });
+      ctx.ui.notify(`Unmuted ${providerId}. Active provider: ${result.activeProvider?.providerId ?? "none"}`, "info");
+    },
+  });
+}

package/lib/config.ts

@@ -0,0 +1,52 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname } from "node:path";
+import { DEFAULT_PRESET_ID, getPreset } from "./policy.ts";
+import { resolveConfigPath, type HostConfig } from "./types.ts";
+
+export function createDefaultConfig(): HostConfig {
+  return {
+    schemaVersion: 1,
+    setupComplete: false,
+    demoProviderEnabled: false,
+    presetId: DEFAULT_PRESET_ID,
+    mutedProviderIds: [],
+  };
+}
+
+function normalizeConfig(input: unknown): HostConfig {
+  const value = typeof input === "object" && input !== null ? (input as Partial<HostConfig>) : {};
+  const presetId = typeof value.presetId === "string" ? getPreset(value.presetId).id : DEFAULT_PRESET_ID;
+  const mutedProviderIds = Array.isArray(value.mutedProviderIds)
+    ? [...new Set(value.mutedProviderIds.filter((item): item is string => typeof item === "string" && item.trim().length > 0))]
+    : [];
+
+  return {
+    schemaVersion: 1,
+    setupComplete: value.setupComplete === true,
+    demoProviderEnabled: value.demoProviderEnabled === true,
+    presetId,
+    mutedProviderIds,
+  };
+}
+
+export async function readHostConfig(): Promise<HostConfig> {
+  try {
+    const content = await readFile(resolveConfigPath(), "utf8");
+    return normalizeConfig(JSON.parse(content));
+  } catch {
+    return createDefaultConfig();
+  }
+}
+
+export async function writeHostConfig(config: HostConfig): Promise<HostConfig> {
+  const normalized = normalizeConfig(config);
+  const path = resolveConfigPath();
+  await mkdir(dirname(path), { recursive: true });
+  await writeFile(path, `${JSON.stringify(normalized, null, 2)}\n`, "utf8");
+  return normalized;
+}
+
+export async function updateHostConfig(mutator: (config: HostConfig) => HostConfig): Promise<HostConfig> {
+  const current = await readHostConfig();
+  return writeHostConfig(mutator(current));
+}

package/lib/demo-provider.ts

@@ -0,0 +1,84 @@
+import { readHostConfig } from "./config.ts";
+import { detectTimeBlock } from "./policy.ts";
+import { publishProviderEntry, removeProviderEntry } from "./registry.ts";
+import { DEMO_PROVIDER_ID, type HostConfig, type ProviderEntry } from "./types.ts";
+
+const HEARTBEAT_MS = 30_000;
+const ENTRY_TTL_MS = 90_000;
+
+let heartbeat: NodeJS.Timeout | undefined;
+
+function baseTagsForBlock(block: ReturnType<typeof detectTimeBlock>): string[] {
+  switch (block) {
+    case "morning":
+      return ["music", "idle"];
+    case "day":
+      return ["sports", "idle"];
+    case "evening":
+      return ["music", "sports"];
+    case "night":
+    default:
+      return ["idle", "music"];
+  }
+}
+
+function readEventTags(): string[] {
+  const tags: string[] = [];
+  if (["1", "true", "yes"].includes(String(process.env.PI_WIDGET_HOST_DEMO_PLAYING_NOW ?? "").toLowerCase())) {
+    tags.push("playing-now");
+  }
+  if (["1", "true", "yes"].includes(String(process.env.PI_WIDGET_HOST_DEMO_MATCHDAY ?? "").toLowerCase())) {
+    tags.push("matchday");
+  }
+  return tags;
+}
+
+export function buildDemoProviderEntry(config: HostConfig, now = new Date()): ProviderEntry {
+  const block = detectTimeBlock(now);
+  const tags = [...new Set([...baseTagsForBlock(block), ...readEventTags()])];
+
+  return {
+    providerId: DEMO_PROVIDER_ID,
+    available: true,
+    updatedAt: now.toISOString(),
+    priority: 15,
+    ttlMs: ENTRY_TTL_MS,
+    tags,
+    mode: block,
+    lines: [`Widget Host Demo | ${block}`, `preset=${config.presetId} | tags=${tags.join(",")}`],
+  };
+}
+
+async function heartbeatTick(): Promise<void> {
+  const config = await readHostConfig();
+  if (!config.demoProviderEnabled) {
+    removeProviderEntry(DEMO_PROVIDER_ID);
+    stopDemoProviderHeartbeat();
+    return;
+  }
+  publishProviderEntry(buildDemoProviderEntry(config));
+}
+
+function ensureHeartbeat(): void {
+  if (heartbeat) return;
+  heartbeat = setInterval(() => {
+    void heartbeatTick().catch(() => undefined);
+  }, HEARTBEAT_MS);
+}
+
+export async function syncBuiltInDemoProvider(config: HostConfig): Promise<void> {
+  if (!config.demoProviderEnabled) {
+    removeProviderEntry(DEMO_PROVIDER_ID);
+    stopDemoProviderHeartbeat();
+    return;
+  }
+
+  publishProviderEntry(buildDemoProviderEntry(config));
+  ensureHeartbeat();
+}
+
+export function stopDemoProviderHeartbeat(): void {
+  if (!heartbeat) return;
+  clearInterval(heartbeat);
+  heartbeat = undefined;
+}

package/lib/policy.ts

@@ -0,0 +1,157 @@
+import { type HostConfig, type HostTimeBlock, type KnownHostTag, type PolicyEvaluationResult, type PolicyPreset, type ProviderEntry, type ProviderState } from "./types.ts";
+
+export const DEFAULT_PRESET_ID = "always-demo";
+export const KNOWN_HOST_TAGS: readonly KnownHostTag[] = ["music", "sports", "playing-now", "matchday", "idle"] as const;
+
+export const PRESET_OPTIONS: readonly PolicyPreset[] = [
+  {
+    id: DEFAULT_PRESET_ID,
+    label: "Always demo",
+    description: "Keep the demo provider eligible in every time block.",
+    blocks: {
+      morning: { preferredTags: ["music", "idle"] },
+      day: { preferredTags: ["sports", "idle"] },
+      evening: { preferredTags: ["music", "sports"] },
+      night: { preferredTags: ["idle", "music"] },
+    },
+  },
+  {
+    id: "focus-day",
+    label: "Focus day",
+    description: "Show the shared slot during morning, day, and evening. Stay silent at night.",
+    blocks: {
+      morning: { preferredTags: ["music", "idle"] },
+      day: { preferredTags: ["sports", "idle"] },
+      evening: { preferredTags: ["music", "sports"] },
+      night: { allowedProviderIds: [] },
+    },
+  },
+  {
+    id: "night-owl",
+    label: "Night owl",
+    description: "Stay quiet during work hours and show the shared slot in evening and night.",
+    blocks: {
+      morning: { allowedProviderIds: [] },
+      day: { allowedProviderIds: [] },
+      evening: { preferredTags: ["music", "sports"] },
+      night: { preferredTags: ["idle", "music"] },
+    },
+  },
+];
+
+export function getPreset(id: string | undefined): PolicyPreset {
+  return PRESET_OPTIONS.find((preset) => preset.id === id) ?? PRESET_OPTIONS[0]!;
+}
+
+export function detectTimeBlock(now = new Date()): HostTimeBlock {
+  const hour = now.getHours();
+  if (hour >= 5 && hour < 11) return "morning";
+  if (hour >= 11 && hour < 17) return "day";
+  if (hour >= 17 && hour < 22) return "evening";
+  return "night";
+}
+
+export function getRemainingTtlMs(entry: Pick<ProviderEntry, "updatedAt" | "ttlMs">, nowMs = Date.now()): number | undefined {
+  if (typeof entry.ttlMs !== "number" || entry.ttlMs <= 0) return undefined;
+  const updatedAtMs = Date.parse(entry.updatedAt);
+  if (!Number.isFinite(updatedAtMs)) return undefined;
+  return updatedAtMs + entry.ttlMs - nowMs;
+}
+
+export function isEntryStale(entry: Pick<ProviderEntry, "updatedAt" | "ttlMs">, now = new Date()): boolean {
+  const remaining = getRemainingTtlMs(entry, now.getTime());
+  return typeof remaining === "number" ? remaining <= 0 : false;
+}
+
+function tagScore(knownTags: KnownHostTag[], preferredTags: readonly KnownHostTag[] | undefined): number {
+  if (!preferredTags || preferredTags.length === 0) return 0;
+  const scores = preferredTags
+    .map((tag, index) => (knownTags.includes(tag) ? Math.max(40 - index * 10, 10) : 0))
+    .filter((value) => value > 0);
+  return scores.length > 0 ? Math.max(...scores) : 0;
+}
+
+function eventBoost(knownTags: KnownHostTag[]): number {
+  let boost = 0;
+  if (knownTags.includes("playing-now")) boost += 100;
+  if (knownTags.includes("matchday")) boost += 80;
+  return boost;
+}
+
+function normalizeKnownTags(tags: string[] | undefined): KnownHostTag[] {
+  const known = new Set<KnownHostTag>();
+  for (const tag of tags ?? []) {
+    if ((KNOWN_HOST_TAGS as readonly string[]).includes(tag)) {
+      known.add(tag as KnownHostTag);
+    }
+  }
+  return [...known];
+}
+
+export function describePreset(preset: PolicyPreset): string {
+  const lines = [`Preset: ${preset.label}`, preset.description, "Blocks:"];
+  for (const block of ["morning", "day", "evening", "night"] as const) {
+    const policy = preset.blocks[block];
+    const allowed = policy.allowedProviderIds && policy.allowedProviderIds.length > 0 ? policy.allowedProviderIds.join(", ") : "silent";
+    const tags = policy.preferredTags && policy.preferredTags.length > 0 ? policy.preferredTags.join(", ") : "none";
+    lines.push(`- ${block}: allowed=${allowed}; preferred tags=${tags}`);
+  }
+  return lines.join("\n");
+}
+
+export function evaluateProviderEntries(entries: readonly ProviderEntry[], config: HostConfig, now = new Date()): PolicyEvaluationResult {
+  const preset = getPreset(config.presetId);
+  const timeBlock = detectTimeBlock(now);
+  const blockPolicy = preset.blocks[timeBlock];
+
+  const providerStates = entries.map<ProviderState>((entry) => {
+    const knownTags = normalizeKnownTags(entry.tags);
+    const isMuted = config.mutedProviderIds.includes(entry.providerId);
+    const isStale = isEntryStale(entry, now);
+    const hasLines = Array.isArray(entry.lines) && entry.lines.length > 0;
+    const isAllowed = blockPolicy.allowedProviderIds === undefined || blockPolicy.allowedProviderIds.includes(entry.providerId);
+    const reasons: string[] = [];
+
+    if (!entry.available) reasons.push("provider reported unavailable");
+    if (!hasLines) reasons.push("no render lines");
+    if (!isAllowed) reasons.push("blocked by current preset");
+    if (isMuted) reasons.push("muted in host config");
+    if (isStale) reasons.push("stale ttl");
+
+    const effectivePriority = (entry.priority ?? 0) + tagScore(knownTags, blockPolicy.preferredTags) + eventBoost(knownTags);
+
+    let effectiveStatus: ProviderState["effectiveStatus"] = "eligible";
+    if (isMuted) {
+      effectiveStatus = "muted";
+    } else if (isStale) {
+      effectiveStatus = "stale";
+    } else if (!entry.available || !hasLines || !isAllowed) {
+      effectiveStatus = "unavailable";
+    }
+
+    return {
+      ...entry,
+      effectivePriority,
+      effectiveStatus,
+      knownTags,
+      reasons,
+      isMuted,
+      isStale,
+    };
+  });
+
+  const winner = providerStates
+    .filter((state) => state.effectiveStatus === "eligible")
+    .sort((left, right) => right.effectivePriority - left.effectivePriority || left.providerId.localeCompare(right.providerId))[0];
+
+  if (winner) {
+    winner.effectiveStatus = "active";
+  }
+
+  return {
+    timeBlock,
+    preset,
+    providerStates,
+    activeProvider: winner,
+  };
+}

package/lib/registry.ts

@@ -0,0 +1,89 @@
+import { REGISTRY_SYMBOL, type ProviderEntry } from "./types.ts";
+
+type Listener = () => void;
+
+export interface WidgetHostRegistry {
+  version: 1;
+  set: (entry: ProviderEntry) => void;
+  remove: (providerId: string) => void;
+  list: () => ProviderEntry[];
+  subscribe: (listener: Listener) => () => void;
+  clear: () => void;
+}
+
+function normalizeEntry(entry: ProviderEntry): ProviderEntry {
+  return {
+    providerId: entry.providerId.trim(),
+    available: entry.available === true,
+    lines: Array.isArray(entry.lines) ? entry.lines.map((line) => String(line)) : [],
+    updatedAt: new Date(entry.updatedAt).toISOString(),
+    priority: typeof entry.priority === "number" ? entry.priority : 0,
+    tags: Array.isArray(entry.tags) ? [...new Set(entry.tags.map((tag) => String(tag).trim()).filter(Boolean))] : [],
+    mode: typeof entry.mode === "string" && entry.mode.trim().length > 0 ? entry.mode.trim() : undefined,
+    ttlMs: typeof entry.ttlMs === "number" && entry.ttlMs > 0 ? entry.ttlMs : undefined,
+  };
+}
+
+function sameEntry(left: ProviderEntry | undefined, right: ProviderEntry): boolean {
+  return JSON.stringify(left) === JSON.stringify(right);
+}
+
+function createRegistry(): WidgetHostRegistry {
+  const entries = new Map<string, ProviderEntry>();
+  const listeners = new Set<Listener>();
+  const notify = () => {
+    for (const listener of listeners) {
+      listener();
+    }
+  };
+
+  return {
+    version: 1,
+    set(entry) {
+      const normalized = normalizeEntry(entry);
+      const previous = entries.get(normalized.providerId);
+      if (sameEntry(previous, normalized)) return;
+      entries.set(normalized.providerId, normalized);
+      notify();
+    },
+    remove(providerId) {
+      if (!entries.delete(providerId)) return;
+      notify();
+    },
+    list() {
+      return [...entries.values()].map((entry) => ({ ...entry, lines: [...entry.lines], tags: [...(entry.tags ?? [])] }));
+    },
+    subscribe(listener) {
+      listeners.add(listener);
+      return () => {
+        listeners.delete(listener);
+      };
+    },
+    clear() {
+      if (entries.size === 0) return;
+      entries.clear();
+      notify();
+    },
+  };
+}
+
+export function getWidgetHostRegistry(): WidgetHostRegistry {
+  const root = globalThis as typeof globalThis & Record<symbol, WidgetHostRegistry | undefined>;
+  const existing = root[REGISTRY_SYMBOL];
+  if (existing) return existing;
+  const registry = createRegistry();
+  root[REGISTRY_SYMBOL] = registry;
+  return registry;
+}
+
+export function publishProviderEntry(entry: ProviderEntry): void {
+  getWidgetHostRegistry().set(entry);
+}
+
+export function removeProviderEntry(providerId: string): void {
+  getWidgetHostRegistry().remove(providerId);
+}
+
+export function listProviderEntries(): ProviderEntry[] {
+  return getWidgetHostRegistry().list();
+}

package/lib/types.ts

@@ -0,0 +1,66 @@
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+export const PACKAGE_NAME = "pi-widget-host";
+export const WIDGET_ID = PACKAGE_NAME;
+export const DEMO_PROVIDER_ID = `${PACKAGE_NAME}.demo`;
+export const REGISTRY_SYMBOL = Symbol.for("pi-widget-host.registry.v1");
+
+export type HostTimeBlock = "morning" | "day" | "evening" | "night";
+export type KnownHostTag = "music" | "sports" | "playing-now" | "matchday" | "idle";
+
+export interface ProviderEntry {
+  providerId: string;
+  available: boolean;
+  lines: string[];
+  updatedAt: string;
+  priority?: number;
+  tags?: string[];
+  mode?: string;
+  ttlMs?: number;
+}
+
+export interface BlockPolicy {
+  allowedProviderIds?: string[];
+  preferredTags?: KnownHostTag[];
+}
+
+export interface PolicyPreset {
+  id: string;
+  label: string;
+  description: string;
+  blocks: Record<HostTimeBlock, BlockPolicy>;
+}
+
+export interface HostConfig {
+  schemaVersion: 1;
+  setupComplete: boolean;
+  demoProviderEnabled: boolean;
+  presetId: string;
+  mutedProviderIds: string[];
+}
+
+export interface ProviderState extends ProviderEntry {
+  effectiveStatus: "active" | "eligible" | "muted" | "stale" | "unavailable";
+  effectivePriority: number;
+  knownTags: KnownHostTag[];
+  reasons: string[];
+  isMuted: boolean;
+  isStale: boolean;
+}
+
+export interface PolicyEvaluationResult {
+  timeBlock: HostTimeBlock;
+  preset: PolicyPreset;
+  providerStates: ProviderState[];
+  activeProvider?: ProviderState;
+}
+
+export function resolveAgentDir(): string {
+  const override = process.env.PI_WIDGET_HOST_AGENT_DIR?.trim();
+  return override ? override : join(homedir(), ".pi", "agent");
+}
+
+export function resolveConfigPath(): string {
+  return join(resolveAgentDir(), `${PACKAGE_NAME}-config.json`);
+}

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "pi-widget-host",
+  "version": "0.2.0",
+  "description": "Host package for managing one shared Pi widget slot across multiple providers with preset policies and a built-in demo provider.",
+  "type": "module",
+  "license": "MIT",
+  "author": "Keisu",
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "widget",
+    "host",
+    "display-policy"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/eiei114/pi-widget-host.git"
+  },
+  "bugs": {
+    "url": "https://github.com/eiei114/pi-widget-host/issues"
+  },
+  "homepage": "https://github.com/eiei114/pi-widget-host#readme",
+  "files": [
+    "extensions/",
+    "lib/",
+    "docs/",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "node --import tsx --test tests/*.test.ts",
+    "ci": "npm run typecheck && npm test && npm run pack:check",
+    "pack:check": "npm pack --dry-run"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "pi": {
+    "extensions": [
+      "./extensions/index.ts"
+    ]
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*"
+  },
+  "peerDependenciesMeta": {
+    "@earendil-works/pi-coding-agent": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@earendil-works/pi-coding-agent": "latest",
+    "@types/node": "^25.9.1",
+    "tsx": "^4.20.6",
+    "typescript": "^6.0.3"
+  }
+}