@llblab/pi-kit 0.1.0

package/node_modules/@llblab/pi-actors/dist/skills/music-player/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: music-player
+description: Use for starting, resuming, inspecting, and controlling one persistent local music playback actor from caller-approved files, directories, URLs, or playlists.
+---
+
+# Music Player
+
+Use this Skill for one local music playback service. For generic Recipe execution, singleton Run lifecycle, persistent-tool setup, or diagnosis, follow `actors`; this Skill owns only playback-specific selection and controls.
+
+## Interaction Routing
+
+When a Telegram-originated turn or explicit Telegram-control question makes repeated player controls relevant, prefer the maintained Telegram view described below over synthesizing one-shot prompt buttons. If `telegram_bind` is available, load and follow the active operating guidance that owns Generative Apps, then bind or invoke the capability-owned adapter; do not re-author it or move playback authority into the view. If the runtime is unavailable or binding fails, report that boundary and fall back to ordinary model-mediated controls.
+
+## Playback
+
+`music-player/playback` is a singleton async controlled service with the canonical address `run:music-player`. The Recipe is the sole lifecycle owner: it starts the service, supervises it, and stops playback when the Run closes. The service owns queue, backend, checkpoint, and playback state. `playback-client.mjs` is a pure actor-neutral RPC client; it never starts, adopts, supervises, or signals a service. The executable also supports explicit foreground `serve` for development or a caller-owned standalone host, but Actor and standalone ownership of one state directory are mutually exclusive.
+
+```text
+spawn recipe=music-player/playback values={"source":"~/Music","player":"auto"}
+message target=run:music-player action=pause
+message target=run:music-player action=next
+inspect target=run:music-player view=control
+```
+
+A repeated compatible spawn returns the healthy active singleton instead of launching a second player. A terminal or dead singleton restarts under the same Run id with a fresh fenced generation and restores its validated playback checkpoint when the source and configuration still match.
+
+## Controls
+
+Use only declared actions: `play`, `pause`, `resume`, `toggle`, `next`, `previous`, `seek`, `volume`, `stop`, and `status`.
+
+- `play` and `resume` continue the current checkpointed track selection.
+- `next` and `previous` update the checkpoint before the next backend launch.
+- `seek` accepts Control input `{ "percent": 0..100 }`, resolves the current track duration, and restarts a supported backend at that percentage while preserving track identity and paused/playing intent. It fails when duration or backend seeking is unavailable.
+- `volume` accepts Control input `{ "percent": 0..100 }` and sets any integer percentage. On Linux with WirePlumber, the helper resolves the exact current playback stream by process identity and changes its volume in place so the track continues; when no safe in-place control exists, it restarts the current track under the new volume while preserving paused/playing intent. UI adapters may expose coarse relative steps but must send the resolved absolute percentage.
+- `status` is read-only and exposes bounded machine-readable player state, including the current absolute volume and a duration-derived progress percentage projected at read time.
+- `stop` ends the live process without silently deleting the saved queue.
+
+External local views use the actor-neutral playback client against the canonical service state directory. They must not read or edit Run files, signal playback processes, construct Actor Control records, or import pi-actors internals. The client validates bounded commands, exact service generation, structured responses, and active endpoint ownership before returning success.
+
+## Maintained Telegram View
+
+> [!NOTE]
+> This Skill includes a ready Music Player Generative App at `genapps/music-player.mjs`. When `telegram_bind` is available and Telegram interaction is relevant, use it to copy and install the app as `music-player`; hot replacement keeps the same app name with `replace: true`.
+
+Bind with absolute `control`, `stateDir`, and `node` arguments. The adapter reports whether the Actor control surface is actually available. Every mutating button queues a canonical Actor Control through `playback.mjs` and waits for that exact record to become handled or failed, so terminal evidence remains visible in the Run inspector and failures reach Telegram; bounded status projection is read-only. The adapter neither imports extension internals nor starts playback. Its stopped-state Start button returns to Pi so the composition root can spawn `music-player/playback`, while active controls remain deterministic Generative App actions that bypass the model. `pi-telegram` owns only the generic Generative App runtime.
+
+## Sources And Backends
+
+- `source` must name caller-approved local music, a readable directory, a playlist file, a URL, or an explicit `|`-separated list. Do not broaden it to unrelated directories.
+- Directory and playlist resolution is owned by the playback helper; there is no separate public playlist Recipe.
+- `player=auto` selects an available supported backend. Do not install or substitute a player silently.
+- The checkpoint preserves source, resolved queue, current index/track, loop, volume, backend, and playback state. It does not promise within-track position restoration unless the selected backend can prove it.
+- A changed source rebuilds the queue. Missing or corrupt checkpoint data fails visibly or rebuilds only under the helper's explicit recovery contract; never claim continuity without evidence.
+
+## Stop Rules
+
+Stop if the source is missing, unreadable, contains no playable audio, or no supported backend is available. Do not claim playback from process start alone; confirm through Run evidence or `status`. Prefer the declared `stop` action for a responsive player. If the service is unresponsive, return to `actors` for bounded Run recovery rather than shell process control.

package/node_modules/@llblab/pi-actors/dist/skills/music-player/genapps/music-player.mjs

@@ -0,0 +1,360 @@
+import { basename, dirname, isAbsolute } from "node:path";
+
+const ACTIONS = new Set([
+  "play",
+  "pause",
+  "resume",
+  "toggle",
+  "next",
+  "previous",
+  "stop",
+]);
+
+function requireAdapter(argument) {
+  if (!argument || typeof argument !== "object" || Array.isArray(argument)) {
+    throw new Error("music-player init requires an object argument");
+  }
+  const control = typeof argument.control === "string" ? argument.control : "";
+  const stateDir = typeof argument.stateDir === "string" ? argument.stateDir : "";
+  const node = typeof argument.node === "string" ? argument.node : process.execPath;
+  if (!isAbsolute(control) || !control.endsWith("playback.mjs")) {
+    throw new Error("music-player control must be an absolute playback.mjs path");
+  }
+  if (!isAbsolute(stateDir)) {
+    throw new Error("music-player stateDir must be an absolute path");
+  }
+  if (!isAbsolute(node)) {
+    throw new Error("music-player node executable must be an absolute path");
+  }
+  return { control, node, stateDir };
+}
+
+function inline(value) {
+  return String(value ?? "").replaceAll("`", "'");
+}
+
+function normalizePlayback(status) {
+  const actorAvailable = status.actor_available === true;
+  if (!actorAvailable) {
+    return {
+      actorAvailable: false,
+      count: null,
+      index: null,
+      pid: "",
+      player: "",
+      progressPercent: null,
+      seekPercent: 0,
+      state: "inactive",
+      track: "",
+      updatedAt: typeof status.updated_at === "string" ? status.updated_at : "",
+      volume: null,
+    };
+  }
+  return {
+    actorAvailable: true,
+    state: typeof status.state === "string" ? status.state : "unknown",
+    index: Number.isInteger(status.index) ? status.index : null,
+    count: Number.isInteger(status.count) ? status.count : null,
+    track: typeof status.track === "string" ? status.track : "",
+    player: typeof status.player === "string" ? status.player : "",
+    volume: Number.isInteger(status.volume) ? status.volume : null,
+    seekPercent: Number.isInteger(status.seek_percent) ? status.seek_percent : 0,
+    progressPercent: Number.isInteger(status.progress_percent) ? status.progress_percent : null,
+    pid: typeof status.pid === "string" || typeof status.pid === "number"
+      ? String(status.pid)
+      : "",
+    updatedAt: typeof status.updated_at === "string" ? status.updated_at : "",
+  };
+}
+
+async function readPlayback(adapter, run) {
+  const result = await run({
+    command: adapter.node,
+    args: [adapter.control, "status", adapter.stateDir],
+    cwd: dirname(adapter.control),
+    timeoutMs: 5_000,
+  });
+  if (result.code !== 0) {
+    throw new Error(`music-player status failed: ${result.stderr.trim() || `exit ${result.code}`}`);
+  }
+  let status;
+  try {
+    status = JSON.parse(result.stdout);
+  } catch {
+    throw new Error("music-player status returned invalid JSON");
+  }
+  if (!status || typeof status !== "object" || Array.isArray(status)) {
+    throw new Error("music-player status returned an invalid object");
+  }
+  return normalizePlayback(status);
+}
+
+function withPlayback(state, playback) {
+  return { version: 1, adapter: state.adapter, playback };
+}
+
+function mainControls(playback) {
+  if (!playback.actorAvailable || playback.state === "stopped" || playback.state === "unknown") {
+    return [
+      [{ label: "▶ Start", prompt: "Start the music player", selected_style: "success" }],
+      [{ label: "🔄 Status", prompt: "music-player::status", selected_style: "primary" }],
+    ];
+  }
+  const primary = playback.state === "paused"
+    ? { label: "▶ Play", prompt: "music-player::resume", selected_style: "success" }
+    : { label: "⏸ Pause", prompt: "music-player::pause", selected_style: "primary" };
+  const percentages = [0, 15, 30, 45, 60, 75, 90];
+  const seek = percentages.map((percent) => ({
+    label: percent === 0 ? "P0" : String(percent),
+    prompt: `music-player::seek_percent(${percent})`,
+    selected_style: percent === 0 ? "primary" : "success",
+  }));
+  const volume = percentages.map((percent) => ({
+    label: percent === 0 ? "V0" : String(percent),
+    prompt: `music-player::volume(${percent})`,
+    selected_style: percent === 0 ? "primary" : "success",
+  }));
+  return [
+    seek,
+    volume,
+    [
+      { label: "⏮ Previous", prompt: "music-player::previous", selected_style: "primary" },
+      primary,
+      { label: "⏭ Next", prompt: "music-player::next", selected_style: "success" },
+    ],
+    [
+      { label: "⏹ Stop", prompt: "music-player::stop", selected_style: "danger" },
+      { label: "🔄 Status", prompt: "music-player::status", selected_style: "primary" },
+    ],
+  ];
+}
+
+function playbackLines(playback) {
+  const track = playback.track ? basename(playback.track) : "—";
+  const index = playback.index === null ? "—" : playback.index + 1;
+  const count = playback.count === null ? "—" : playback.count;
+  return [
+    `- **Actor:** \`${playback.actorAvailable ? "available" : "unavailable"}\``,
+    `- **State:** \`${inline(playback.state)}\``,
+    `- **Progress:** \`${playback.progressPercent === null ? "—" : `${playback.progressPercent}%`}\``,
+    `- **Volume:** \`${playback.volume === null ? "—" : `${playback.volume}%`}\``,
+    `- **Backend:** \`${inline(playback.player || "—")}\``,
+    `- **Queue:** \`${index}/${count}\``,
+    `- **Track:** \`${inline(track)}\``,
+  ];
+}
+
+function render(playback) {
+  return [
+    "**🎵 Music Player**",
+    "",
+    ...playbackLines(playback),
+    "",
+    `<!-- telegram_button ${JSON.stringify(mainControls(playback))} -->`,
+  ].join("\n");
+}
+
+async function waitForTransition(adapter, run, before, action) {
+  for (let attempt = 0; attempt < 20; attempt += 1) {
+    const playback = await readPlayback(adapter, run);
+    const changed = action === "stop"
+      ? playback.state === "stopped"
+      : action === "pause"
+        ? playback.state === "paused"
+        : action === "play" || action === "resume"
+          ? playback.state === "playing"
+          : action === "toggle"
+            ? playback.state !== before.state
+            : playback.index !== before.index || playback.track !== before.track;
+    if (changed) return playback;
+    await new Promise((resolve) => setTimeout(resolve, 100));
+  }
+  return await readPlayback(adapter, run);
+}
+
+function normalizeAbsoluteVolume(argument) {
+  const candidate =
+    argument && typeof argument === "object" && !Array.isArray(argument)
+      ? argument.percent
+      : argument;
+  if (!Number.isInteger(candidate) || candidate < 0 || candidate > 100) {
+    throw new Error("music-player volume requires an integer percent 0..100");
+  }
+  return candidate;
+}
+
+async function applyVolume(percent, context) {
+  const result = await context.run({
+    command: context.state.adapter.node,
+    args: [
+      context.state.adapter.control,
+      "volume",
+      context.state.adapter.stateDir,
+      String(percent),
+    ],
+    cwd: dirname(context.state.adapter.control),
+    timeoutMs: 5_000,
+  });
+  if (result.code !== 0) {
+    throw new Error(`music-player volume failed: ${result.stderr.trim() || `exit ${result.code}`}`);
+  }
+  let playback;
+  for (let attempt = 0; attempt < 20; attempt += 1) {
+    playback = await readPlayback(context.state.adapter, context.run);
+    if (playback.volume === percent) break;
+    await new Promise((resolve) => setTimeout(resolve, 100));
+  }
+  playback ??= await readPlayback(context.state.adapter, context.run);
+  return {
+    state: withPlayback(context.state, playback),
+    output: render(playback),
+    viewMode: "edit",
+  };
+}
+
+function normalizeSeekPercent(argument) {
+  if (!Number.isInteger(argument) || argument < 0 || argument > 100) {
+    throw new Error("music-player seek requires an integer percent 0..100");
+  }
+  return argument;
+}
+
+async function applySeek(percent, context) {
+  const result = await context.run({
+    command: context.state.adapter.node,
+    args: [
+      context.state.adapter.control,
+      "seek",
+      context.state.adapter.stateDir,
+      String(percent),
+    ],
+    cwd: dirname(context.state.adapter.control),
+    timeoutMs: 5_000,
+  });
+  if (result.code !== 0) {
+    throw new Error(`music-player seek failed: ${result.stderr.trim() || `exit ${result.code}`}`);
+  }
+  let playback;
+  for (let attempt = 0; attempt < 20; attempt += 1) {
+    playback = await readPlayback(context.state.adapter, context.run);
+    if (playback.seekPercent === percent && playback.pid) break;
+    await new Promise((resolve) => setTimeout(resolve, 100));
+  }
+  playback ??= await readPlayback(context.state.adapter, context.run);
+  return {
+    state: withPlayback(context.state, playback),
+    output: render(playback),
+    viewMode: "edit",
+  };
+}
+
+async function apply(action, context) {
+  if (!ACTIONS.has(action)) throw new Error(`unsupported music-player action: ${action}`);
+  const before = await readPlayback(context.state.adapter, context.run);
+  const result = await context.run({
+    command: context.state.adapter.node,
+    args: [context.state.adapter.control, action, context.state.adapter.stateDir],
+    cwd: dirname(context.state.adapter.control),
+    timeoutMs: 5_000,
+  });
+  if (result.code !== 0) {
+    throw new Error(`music-player ${action} failed: ${result.stderr.trim() || `exit ${result.code}`}`);
+  }
+  const playback = await waitForTransition(
+    context.state.adapter,
+    context.run,
+    before,
+    action,
+  );
+  return {
+    state: withPlayback(context.state, playback),
+    output: render(playback),
+    viewMode: "edit",
+  };
+}
+
+export async function init({ argument, run }) {
+  const adapter = requireAdapter(argument);
+  const playback = await readPlayback(adapter, run);
+  return {
+    state: { version: 1, adapter, playback },
+    output: render(playback),
+  };
+}
+
+export async function status({ state, run }) {
+  const playback = await readPlayback(state.adapter, run);
+  const changed = JSON.stringify(playback) !== JSON.stringify(state.playback);
+  return {
+    ...(changed ? { state: withPlayback(state, playback) } : {}),
+    output: render(playback),
+    viewMode: "edit",
+  };
+}
+
+export async function refresh({ state, run }) {
+  const playback = await readPlayback(state.adapter, run);
+  const changed = JSON.stringify(playback) !== JSON.stringify(state.playback);
+  return {
+    ...(changed ? { state: withPlayback(state, playback) } : {}),
+    output: render(playback),
+  };
+}
+
+export async function main({ state, run }) {
+  const playback = await readPlayback(state.adapter, run);
+  const changed = JSON.stringify(playback) !== JSON.stringify(state.playback);
+  return {
+    ...(changed ? { state: withPlayback(state, playback) } : {}),
+    output: render(playback),
+    viewMode: "edit",
+  };
+}
+
+export async function play(context) {
+  return await apply("resume", context);
+}
+
+export async function pause(context) {
+  return await apply("pause", context);
+}
+
+export async function resume(context) {
+  return await apply("resume", context);
+}
+
+export async function toggle(context) {
+  return await apply("toggle", context);
+}
+
+export async function next(context) {
+  return await apply("next", context);
+}
+
+export async function previous(context) {
+  return await apply("previous", context);
+}
+
+export async function seek_percent({ argument, ...context }) {
+  return await applySeek(normalizeSeekPercent(argument), context);
+}
+
+export async function volume({ argument, ...context }) {
+  return await applyVolume(normalizeAbsoluteVolume(argument), context);
+}
+
+export async function volume_delta({ argument, ...context }) {
+  if (!Number.isInteger(argument) || argument < -100 || argument > 100) {
+    throw new Error("music-player volume_delta requires an integer -100..100");
+  }
+  const playback = await readPlayback(context.state.adapter, context.run);
+  const current = playback.volume;
+  if (!Number.isInteger(current)) {
+    throw new Error("music-player current volume is unavailable");
+  }
+  return await applyVolume(Math.max(0, Math.min(100, current + argument)), context);
+}
+
+export async function stop(context) {
+  return await apply("stop", context);
+}

package/node_modules/@llblab/pi-actors/dist/skills/music-player/recipes/playback.json

@@ -0,0 +1,29 @@
+{
+  "async": true,
+  "singleton": true,
+  "args": [
+    "source:string",
+    "loop:bool",
+    "volume:int",
+    "player:enum(auto,mpv,afplay,ffplay,cvlc,play,wmp)",
+    "state_dir:path"
+  ],
+  "defaults": {
+    "loop": "true",
+    "volume": "70",
+    "player": "auto"
+  },
+  "control": [
+    "play",
+    "pause",
+    "resume",
+    "toggle",
+    "next",
+    "previous",
+    "seek",
+    "volume",
+    "stop",
+    "status"
+  ],
+  "template": "{skill_dir}/scripts/playback.mjs play {source} {loop} {volume} {player} {state_dir}"
+}

package/node_modules/@llblab/pi-actors/dist/skills/music-player/scripts/playback-client.mjs

@@ -0,0 +1,143 @@
+#!/usr/bin/env node
+
+/**
+ * Actor-neutral client for the local Music Player playback protocol.
+ *
+ * Reads portable JSON status and sends bounded generation-fenced commands to
+ * the playback service endpoint without reading pi-actors Run or Control state.
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { createConnection } from "node:net";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+const ACTIONS = new Set([
+  "play",
+  "resume",
+  "pause",
+  "toggle",
+  "next",
+  "previous",
+  "seek",
+  "volume",
+  "stop",
+  "status",
+]);
+
+function fail(message, code = 1) {
+  console.error(`music-player: ${message}`);
+  process.exit(code);
+}
+
+function expandPath(value) {
+  if (value === "~") return homedir();
+  if (value.startsWith("~/")) return join(homedir(), value.slice(2));
+  return value;
+}
+
+function readJson(path, fallback) {
+  try {
+    return JSON.parse(readFileSync(path, "utf8"));
+  } catch {
+    return fallback;
+  }
+}
+
+function parsePercent(value, label) {
+  if (!/^\d+$/.test(String(value))) {
+    fail(`${label} percent must be an integer 0..100`, 2);
+  }
+  const percent = Number(value);
+  if (percent < 0 || percent > 100) {
+    fail(`${label} percent must be an integer 0..100`, 2);
+  }
+  return percent;
+}
+
+function projectCurrentProgress(status, nowMs = Date.now()) {
+  const duration = Number(status.duration_seconds);
+  let position = Number(status.position_seconds);
+  const updatedAtMs = Number(status.position_updated_at_ms);
+  if (!Number.isFinite(position)) position = 0;
+  if (status.state === "playing" && Number.isFinite(updatedAtMs)) {
+    position += Math.max(0, nowMs - updatedAtMs) / 1000;
+  }
+  if (!Number.isFinite(duration) || duration <= 0) {
+    return { ...status, progress_percent: null };
+  }
+  position = Math.min(Math.max(position, 0), duration);
+  return {
+    ...status,
+    progress_percent: Math.round((position / duration) * 100),
+    position_seconds: position,
+    position_updated_at_ms: nowMs,
+  };
+}
+
+async function sendCommand(endpoint, action, input) {
+  const payload = `${JSON.stringify({
+    action,
+    ...(input !== undefined ? { input } : {}),
+    service_instance_id: endpoint.service_instance_id,
+  })}\n`;
+  const response = await new Promise((resolveResponse, rejectResponse) => {
+    const socket = createConnection(endpoint.path);
+    let content = "";
+    const timeout = setTimeout(() => {
+      socket.destroy();
+      rejectResponse(new Error("playback service command timed out"));
+    }, 5_000);
+    timeout.unref?.();
+    socket.setEncoding("utf8");
+    socket.on("connect", () => socket.write(payload));
+    socket.on("data", (chunk) => {
+      content += chunk;
+      if (Buffer.byteLength(content, "utf8") > 4096) {
+        socket.destroy(new Error("playback service response is too large"));
+      }
+    });
+    socket.on("error", rejectResponse);
+    socket.on("end", () => {
+      clearTimeout(timeout);
+      try {
+        resolveResponse(JSON.parse(content.trim()));
+      } catch {
+        rejectResponse(new Error("playback service returned invalid JSON"));
+      }
+    });
+  });
+  if (!response?.ok) {
+    throw new Error(response?.error || "playback service rejected the command");
+  }
+}
+
+const [action = "status", rawStateDir, ...actionArgs] = process.argv.slice(2);
+if (!ACTIONS.has(action) || !rawStateDir) {
+  fail("usage: playback-client.mjs <status|play|resume|pause|toggle|next|previous|seek|volume|stop> <state-dir> [action args]", 2);
+}
+const stateDir = expandPath(rawStateDir);
+if (action === "status") {
+  const status = readJson(join(stateDir, "player.json"), { state: "unknown" });
+  process.stdout.write(`${JSON.stringify(projectCurrentProgress(status))}\n`);
+  process.exit(0);
+}
+const endpointPath = join(stateDir, "playback-endpoint.json");
+if (!existsSync(endpointPath)) fail(`playback service is not active: ${stateDir}`, 3);
+const endpoint = readJson(endpointPath, {});
+if (
+  typeof endpoint.path !== "string" ||
+  !endpoint.path ||
+  typeof endpoint.service_instance_id !== "string" ||
+  !endpoint.service_instance_id
+) fail(`playback service endpoint is invalid: ${stateDir}`, 3);
+let input;
+if (action === "seek" || action === "volume") {
+  input = { percent: parsePercent(actionArgs[0], action) };
+}
+try {
+  await sendCommand(endpoint, action === "resume" ? "play" : action, input);
+  console.log(`music-player: command=${action} handled state_dir=${stateDir}`);
+} catch (error) {
+  fail(error instanceof Error ? error.message : String(error), 3);
+}