pi-feats 0.1.1

package/extensions/profiles.ts

@@ -0,0 +1,439 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Box, render, Text } from "ink";
+import React from "react";
+import { existsSync } from "node:fs";
+import { copyFile, mkdir, readFile, readdir, rm, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { basename, join, resolve } from "node:path";
+import { spawn } from "node:child_process";
+import { ensureNonoAvailable, ensureProfileSandbox, isSandboxEnabled, migrateLegacySandboxRuntime, sandboxedCommand } from "./lib/profile-sandbox.ts";
+import { profileEnvironment } from "./lib/profile-env.ts";
+import { handleRemoteCli, REMOTE_COMMAND_NAMES } from "./lib/remote-hosts.ts";
+
+type ProfilePolicy = {
+  enabledTools?: string[];
+  enabledSkills?: string[];
+  enabledProfileSkills?: string[];
+  enabledExtensions?: string[];
+  skillSources?: { shared?: boolean; profile?: boolean };
+};
+
+type ProfileSettings = Record<string, unknown> & { profile?: ProfilePolicy };
+
+const defaultAgentDir = join(homedir(), ".pi", "agent");
+const rootAgentDir = () => process.env.PI_PROFILE_ROOT ?? defaultAgentDir;
+const profilesDir = () => join(rootAgentDir(), "profiles");
+const profileDir = (name: string) => join(profilesDir(), name);
+const validProfileName = (name: string) => /^[a-zA-Z][a-zA-Z0-9_-]{0,63}$/.test(name);
+const reservedProfileNames = new Set([
+  "add", "create", "delete", "disable", "enable", "extensions", "guardrails", "list", "open", "packages", "profile", "pulse", "remove", "rename", "resume", "sessions", "skills", "tools", "validate",
+  ...REMOTE_COMMAND_NAMES,
+]);
+
+function fail(message: string): never {
+  process.stderr.write(`Profile error: ${message}\n`);
+  process.exit(1);
+}
+
+type GuardrailRow = { name: string; stage: string; mode: string; order: number; file: string; enabled?: boolean };
+
+async function renderGuardrailTable(guardrails: GuardrailRow[]): Promise<void> {
+  const columns: Array<[string, number]> = [["STATUS", 8], ["STAGE", 8], ["ORDER", 5], ["MODE", 9], ["NAME", 13], ["FILE", 18]];
+  const clip = (value: string, width: number) => value.length <= width ? value : `${value.slice(0, width - 1)}…`;
+  const cell = (value: string, width: number) => clip(value, width).padEnd(width);
+  const line = `┼${columns.map(([, width]) => "─".repeat(width + 2)).join("┼")}┼`;
+  const top = line.replaceAll("┼", "┬").replace(/^┬/, "┌").replace(/┬$/, "┐");
+  const bottom = line.replaceAll("┼", "┴").replace(/^┴/, "└").replace(/┴$/, "┘");
+  const row = (values: string[]) => `│ ${values.map((value, index) => cell(value, columns[index][1])).join(" │ ")} │`;
+  const entries = guardrails.length
+    ? guardrails.sort((a, b) => a.stage.localeCompare(b.stage) || a.order - b.order || a.name.localeCompare(b.name)).map((guardrail) => React.createElement(Text, { key: guardrail.name, color: guardrail.enabled === false ? "gray" : "white" }, row([guardrail.enabled === false ? "disabled" : "enabled", guardrail.stage, String(guardrail.order), guardrail.mode, guardrail.name, guardrail.file])))
+    : [React.createElement(Text, { key: "empty", color: "gray" }, row(["—", "—", "—", "—", "No guardrails configured", "—"]))];
+  const app = render(React.createElement(Box, { flexDirection: "column" },
+    React.createElement(Text, { color: "gray" }, top),
+    React.createElement(Text, { color: "cyan", bold: true }, row(columns.map(([name]) => name))),
+    React.createElement(Text, { color: "gray" }, line),
+    ...entries,
+    React.createElement(Text, { color: "gray" }, bottom),
+  ), { stdout: process.stdout, stdin: process.stdin, exitOnCtrlC: false, patchConsole: false });
+  await new Promise((resolveRender) => setTimeout(resolveRender, 25));
+  app.unmount();
+}
+
+async function handleGuardrailsCli(profile: string, args: string[]): Promise<void> {
+  const directory = profile === "default" ? rootAgentDir() : profileDir(profile);
+  const configPath = join(directory, "guardrails.json");
+  let config: { guardrails: GuardrailRow[] };
+  try { config = JSON.parse(await readFile(configPath, "utf8")); }
+  catch (error) { fail(`could not read ${configPath}: ${error instanceof Error ? error.message : String(error)}`); }
+  if (!Array.isArray(config.guardrails)) fail(`${configPath} must contain a guardrails array.`);
+  const action = args[1] ?? "list";
+  if (action === "list") return renderGuardrailTable(config.guardrails);
+  if (action === "validate") {
+    for (const guardrail of config.guardrails) {
+      if (!/^[a-z][a-z0-9-]{0,63}$/.test(guardrail.name) || !["input", "pre_tool", "post_tool", "output"].includes(guardrail.stage) || !["transform", "evaluate", "reflect"].includes(guardrail.mode) || !Number.isInteger(guardrail.order) || basename(guardrail.file) !== guardrail.file || !guardrail.file.endsWith(".md")) fail(`invalid guardrail '${guardrail.name}'.`);
+      if (!existsSync(join(rootAgentDir(), "guardrails", guardrail.file))) fail(`guardrail prompt does not exist: ${guardrail.file}`);
+    }
+    return writeStdout("Guardrails are valid.\n");
+  }
+  if (action !== "enable" && action !== "disable") fail("usage: pi guardrails list | enable <name> | disable <name> | validate");
+  const name = args[2];
+  const guardrail = config.guardrails.find((item) => item.name === name);
+  if (!guardrail) fail(`guardrail '${name ?? ""}' is not configured.`);
+  guardrail.enabled = action === "enable";
+  await writeFile(configPath, `${JSON.stringify(config, null, 2)}\n`);
+  await writeStdout(`Guardrail '${guardrail.name}' ${action}d.\n`);
+}
+
+async function writeStdout(text: string) {
+  await new Promise<void>((resolveWrite, reject) => {
+    process.stdout.write(text, (error) => error ? reject(error) : resolveWrite());
+  });
+}
+
+async function readJson(path: string): Promise<ProfileSettings> {
+  try {
+    return JSON.parse(await readFile(path, "utf8")) as ProfileSettings;
+  } catch (error) {
+    throw new Error(`could not read ${path}: ${error instanceof Error ? error.message : String(error)}`);
+  }
+}
+
+function sharedResources(root: string, policy: ProfilePolicy = {}, localSkillsDir?: string) {
+  // Extensions are loaded through Pi package settings. Do not materialize paths
+  // from the native extensions directory: a Git package lives outside it.
+  return {
+    skills: [
+      ...(policy.skillSources?.profile === true && localSkillsDir ? (!policy.enabledProfileSkills || policy.enabledProfileSkills.includes("*") ? [localSkillsDir] : policy.enabledProfileSkills.map((name) => join(localSkillsDir, name)).filter(existsSync)) : []),
+      ...(policy.skillSources?.shared !== false ? (!policy.enabledSkills || policy.enabledSkills.includes("*") ? [join(root, "skills")] : policy.enabledSkills.map((name) => join(root, "skills", name)).filter(existsSync)) : []),
+    ],
+    prompts: [join(root, "prompts")],
+    themes: [join(root, "themes")],
+  };
+}
+
+function packageInstallPath(root: string, source: string): string | undefined {
+  if (source.startsWith("npm:")) {
+    const spec = source.slice(4);
+    const versionAt = spec.lastIndexOf("@");
+    const packageName = versionAt > (spec.startsWith("@") ? spec.indexOf("/") : -1) ? spec.slice(0, versionAt) : spec;
+    const path = join(root, "npm", "node_modules", packageName);
+    return existsSync(join(path, "package.json")) ? path : undefined;
+  }
+  if (!source.startsWith("git:") && !/^(?:https?|ssh|git):\/\//.test(source)) return undefined;
+  let remote = source.replace(/^git:/, "");
+  const refAt = remote.lastIndexOf("@");
+  if (refAt > remote.lastIndexOf("/")) remote = remote.slice(0, refAt);
+  remote = remote.replace(/^(?:https?|git):\/\//, "").replace(/^ssh:\/\/git@/, "").replace(/^git@/, "").replace(/^([^/:]+):/, "$1/").replace(/\.git$/, "");
+  const path = join(root, "git", remote);
+  return existsSync(join(path, "package.json")) ? path : undefined;
+}
+
+async function rootRuntimeSources(root: string, base: ProfileSettings): Promise<string[]> {
+  const sources = new Set<string>();
+  const add = (source: unknown) => {
+    if (typeof source !== "string") return;
+    const packagePath = packageInstallPath(root, source);
+    const path = packagePath ?? (source.startsWith(".") ? resolve(root, source) : source);
+    if (existsSync(path)) sources.add(path);
+  };
+  if (Array.isArray(base.packages)) for (const entry of base.packages) add(typeof entry === "object" && entry !== null ? (entry as { source?: unknown }).source : entry);
+  if (Array.isArray(base.extensions)) for (const entry of base.extensions) add(entry);
+  // Pi auto-discovers these for the default profile. Add them explicitly when
+  // re-executing a named profile, where that profile's extensions directory is
+  // intentionally empty.
+  try {
+    for (const entry of await readdir(join(root, "extensions"), { withFileTypes: true })) {
+      const path = join(root, "extensions", entry.name);
+      if (entry.isFile() && [".ts", ".js"].some((extension) => entry.name.endsWith(extension))) add(path);
+      else if (entry.isDirectory() && (existsSync(join(path, "index.ts")) || existsSync(join(path, "index.js")))) add(path);
+    }
+  } catch {}
+  return [...sources];
+}
+
+function profileSettings(root: string, base: ProfileSettings, localSkillsDir: string): ProfileSettings {
+  const { packages: _packages, extensions: _extensions, ...profileBase } = base;
+  return {
+    ...profileBase,
+    ...sharedResources(root, { enabledTools: ["*"], enabledSkills: ["*"], enabledProfileSkills: ["*"], skillSources: { shared: true, profile: false } }, localSkillsDir),
+    defaultTools: ["read", "bash", "powershell", "edit", "write", "grep", "find", "ls"],
+    profile: {
+      enabledTools: ["*"],
+      enabledSkills: ["*"],
+      enabledProfileSkills: ["*"],
+      skillSources: { shared: true, profile: false },
+    },
+  };
+}
+
+type ProfileRow = { name: string; path: string };
+
+function ProfileTable({ profiles }: { profiles: ProfileRow[] }) {
+  const terminalWidth = Math.max(60, process.stdout.columns ?? 80);
+  const nameWidth = Math.min(24, Math.max(12, Math.floor((terminalWidth - 7) * 0.28)));
+  const pathWidth = terminalWidth - nameWidth - 7;
+  const clip = (value: string, width: number) => value.length <= width ? value : `${value.slice(0, width - 1)}…`;
+  const cell = (value: string, width: number) => clip(value, width).padEnd(width);
+  const line = `┼${"─".repeat(nameWidth + 2)}┼${"─".repeat(pathWidth + 2)}┼`;
+  const top = line.replaceAll("┼", "┬").replace(/^┬/, "┌").replace(/┬$/, "┐");
+  const bottom = line.replaceAll("┼", "┴").replace(/^┴/, "└").replace(/┴$/, "┘");
+  const row = (name: string, path: string) => `│ ${cell(name, nameWidth)} │ ${cell(path, pathWidth)} │`;
+
+  return React.createElement(
+    Box,
+    { flexDirection: "column" },
+    React.createElement(Text, { color: "gray" }, top),
+    React.createElement(Text, { color: "cyan", bold: true }, row("PROFILE", "PATH")),
+    React.createElement(Text, { color: "gray" }, line),
+    ...profiles.map((profile) => React.createElement(Text, { color: "white", key: profile.name }, row(profile.name, profile.path))),
+    React.createElement(Text, { color: "gray" }, bottom),
+  );
+}
+
+async function listProfiles() {
+  const root = rootAgentDir();
+  const profiles: ProfileRow[] = [{ name: "default", path: root }];
+  if (existsSync(profilesDir())) {
+    for (const entry of await readdir(profilesDir(), { withFileTypes: true })) {
+      if (entry.isDirectory() && existsSync(join(profilesDir(), entry.name, "settings.json"))) {
+        profiles.push({ name: entry.name, path: profileDir(entry.name) });
+      }
+    }
+  }
+  const app = render(React.createElement(ProfileTable, { profiles }), {
+    stdout: process.stdout,
+    stdin: process.stdin,
+    exitOnCtrlC: false,
+    patchConsole: false,
+  });
+  await new Promise((resolveRender) => setTimeout(resolveRender, 25));
+  app.unmount();
+}
+
+async function removeProfileRuntimeArtifacts(destination: string) {
+  // These locations belonged to the former per-profile extension bootstrap.
+  // A profile is a workspace, never a package or extension installation root.
+  await Promise.all(["extensions", "git", "npm", "node_modules"].map((name) => rm(join(destination, name), { recursive: true, force: true })));
+}
+
+async function createProfile(name: string) {
+  if (!validProfileName(name)) fail("invalid name; use letters, numbers, hyphens, or underscores (max. 64 characters).");
+  if (name === "default") fail("default is the primary profile and cannot be created.");
+  if (reservedProfileNames.has(name.toLowerCase())) fail(`'${name}' is reserved as a Pi command and cannot be used as a profile name.`);
+  await ensureNonoAvailable();
+  const root = rootAgentDir();
+  const destination = profileDir(name);
+  if (existsSync(destination)) fail(`profile '${name}' already exists.`);
+
+  await mkdir(join(destination, "sessions"), { recursive: true });
+  const baseSettingsPath = join(root, "settings.json");
+  const base = existsSync(baseSettingsPath) ? await readJson(baseSettingsPath) : {};
+  await writeFile(join(destination, "settings.json"), `${JSON.stringify({ ...profileSettings(root, base, join(destination, "skills")), sandbox: true }, null, 2)}\n`);
+  await ensureProfileSandbox(destination, resolve(process.argv[1]));
+  await writeFile(join(destination, "SOUL.md"), "");
+  await writeFile(join(destination, "guardrails.json"), "{\n  \"guardrails\": []\n}\n");
+
+  const authPath = join(root, "auth.json");
+  if (existsSync(authPath)) await copyFile(authPath, join(destination, "auth.json"));
+
+  const modelsPath = join(root, "models.json");
+  if (existsSync(modelsPath)) {
+    await symlink(modelsPath, join(destination, "models.json"));
+  }
+
+  await writeStdout(`Profile '${name}' created at ${destination}\n`);
+}
+
+async function deleteProfile(name: string, force: boolean) {
+  if (!validProfileName(name) || name === "default") fail("default cannot be deleted.");
+  const destination = profileDir(name);
+  if (!existsSync(join(destination, "settings.json"))) fail(`profile '${name}' does not exist.`);
+  if (!force) fail("deletion requires --force: pi profile delete <name> --force");
+  await rm(destination, { recursive: true, force: false });
+  await writeStdout(`Profile '${name}' deleted.\n`);
+}
+
+async function handleProfileCommand(args: string[]) {
+  const action = args[1];
+  if (action === "list" && args.length === 2) return listProfiles();
+  if (action === "create" && args.length === 3) return createProfile(args[2]);
+  if (action === "delete" && (args.length === 3 || (args.length === 4 && args[3] === "--force"))) {
+    return deleteProfile(args[2], args[3] === "--force");
+  }
+  if (action === "resume" && args.length === 3) return reexecWithProfile(args[2], ["--resume"]);
+  if (action === "open" && args.length === 4) return reexecWithProfile(args[2], ["--session", args[3]]);
+  // Accept the natural profile-first forms too. This is particularly useful
+  // for remote operation, where a session ID is copied from `sessions list`.
+  if (action && !reservedProfileNames.has(action.toLowerCase())) {
+    if (args[2] === "resume" && args.length === 3) return reexecWithProfile(action, ["--resume"]);
+    if ((args[2] === "resume" || args[2] === "open") && args.length === 4) return reexecWithProfile(action, ["--session", args[3]]);
+    return reexecWithProfile(action, args.slice(2));
+  }
+  fail("usage: pi profile <name> [pi arguments] | pi profile list | pi profile create <name> | pi profile delete <name> --force | pi profile resume <name> | pi profile open <name> <session-id>");
+}
+
+// Pi exposes its complete argv to extensions. Re-executed profiles prepend
+// runtime-only flags, so command dispatch must ignore those pairs instead of
+// assuming the subcommand is always argv[0].
+function commandArgs(raw: string[]): string[] {
+  const result: string[] = [];
+  for (let index = 0; index < raw.length; index += 1) {
+    const value = raw[index];
+    if (value === "--extension" || value === "--session-dir") { index += 1; continue; }
+    if (value.startsWith("--extension=") || value.startsWith("--session-dir=")) continue;
+    result.push(value);
+  }
+  return result;
+}
+
+function extractResumeCommand(args: string[]) {
+  if (args[0] === "resume" && args.length === 2) {
+    return { profile: "default", sessionId: args[1] };
+  }
+  const requestedProfile = extractProfile(args);
+  if (requestedProfile && requestedProfile.args[0] === "resume" && requestedProfile.args.length === 2) {
+    return { profile: requestedProfile.name, sessionId: requestedProfile.args[1] };
+  }
+  return undefined;
+}
+
+function extractProfile(args: string[]) {
+  for (let index = 0; index < args.length; index += 1) {
+    if (args[index] === "--profile") {
+      const name = args[index + 1];
+      if (!name) fail("--profile requires a name.");
+      return { name, args: [...args.slice(0, index), ...args.slice(index + 2)] };
+    }
+    if (args[index].startsWith("--profile=")) {
+      const name = args[index].slice("--profile=".length);
+      if (!name) fail("--profile requires a name.");
+      return { name, args: [...args.slice(0, index), ...args.slice(index + 1)] };
+    }
+  }
+  return undefined;
+}
+
+async function syncProfileResources(name: string) {
+  if (name === "default") return;
+  const settingsPath = join(profileDir(name), "settings.json");
+  const root = rootAgentDir();
+  const settings = await readJson(settingsPath);
+  // Packages and extensions belong to the default runtime. Profiles only own
+  // workspace state and resource policy; rootRuntimeSources() injects the
+  // shared runtime when this profile is launched.
+  delete settings.packages;
+  delete settings.extensions;
+  if (settings.profile) delete settings.profile.enabledExtensions;
+  Object.assign(settings, sharedResources(root, settings.profile, join(profileDir(name), "skills")));
+  await writeFile(settingsPath, `${JSON.stringify(settings, null, 2)}\n`);
+  await removeProfileRuntimeArtifacts(profileDir(name));
+}
+
+async function reexecWithProfile(name: string, args: string[]) {
+  if (name !== "default" && (!validProfileName(name) || !existsSync(join(profileDir(name), "settings.json")))) {
+    fail(`profile '${name}' does not exist.`);
+  }
+  const root = rootAgentDir();
+  const target = name === "default" ? root : profileDir(name);
+  if (name !== "default") await migrateLegacySandboxRuntime(target);
+  await syncProfileResources(name);
+  const baseSettingsPath = join(root, "settings.json");
+  const rootSettings = existsSync(baseSettingsPath) ? await readJson(baseSettingsPath) : {};
+  // The default runtime owns extensions and packages. Named profiles receive
+  // their already installed local paths, never npm:/git: specs. The default
+  // profile already loads these resources from its own settings.
+  const runtimeSources = name === "default" ? [] : await rootRuntimeSources(root, rootSettings);
+  const extensionArgs = runtimeSources.flatMap((source) => ["--extension", source]);
+  const sessionArgs = name === "default" ? [] : ["--session-dir", join(target, "sessions")];
+  const piArgs = [resolve(process.argv[1]), ...extensionArgs, ...sessionArgs, ...args];
+  // The default profile is intentionally never sandboxed. Named profiles run
+  // directly in their own persistent directory; nono enforces their policy.
+  const sandbox = await isSandboxEnabled(target, name === "default");
+  const childEnv = {
+    ...await profileEnvironment(target),
+    PI_CODING_AGENT_DIR: target,
+    PI_PROFILE_ROOT: root,
+    PI_PROFILE_REEXEC: "1",
+    PI_ACTIVE_PROFILE: name,
+  };
+  if (name === "default") delete childEnv.PI_CODING_AGENT_SESSION_DIR;
+  else childEnv.PI_CODING_AGENT_SESSION_DIR = join(target, "sessions");
+  const launch = sandbox
+    ? sandboxedCommand(await ensureProfileSandbox(target, resolve(process.argv[1]), runtimeSources), target, process.execPath, piArgs)
+    : { command: process.execPath, args: piArgs };
+  const child = spawn(launch.command, launch.args, {
+    cwd: sandbox ? target : process.cwd(),
+    stdio: "inherit",
+    env: childEnv,
+  });
+  const code = await new Promise<number>((resolveExit, reject) => {
+    child.once("error", reject);
+    child.once("exit", (exitCode) => resolveExit(exitCode ?? 1));
+  });
+  process.exit(code);
+}
+
+export default async function (pi: ExtensionAPI) {
+  // Capture the profile directory when this runtime is built. This also lets SDK
+  // consumers host multiple profile runtimes in one process without later
+  // process.env changes leaking between agent turns.
+  const activeAgentDir = process.env.PI_CODING_AGENT_DIR ?? defaultAgentDir;
+  pi.registerFlag("profile", {
+    description: "Start Pi using a named profile",
+    type: "string",
+  });
+
+  const args = commandArgs(process.argv.slice(2));
+  if (await handleRemoteCli(args, rootAgentDir())) process.exit(0);
+  const resume = extractResumeCommand(args);
+  if (resume) {
+    await reexecWithProfile(resume.profile, ["--session", resume.sessionId]);
+  }
+
+  if (args[0] === "profile") {
+    await handleProfileCommand(args);
+    process.exit(0);
+  }
+
+  const requestedProfile = extractProfile(args);
+  const guardrailArgs = requestedProfile?.args ?? args;
+  // A profile re-exec has already consumed the `profile <name>` prefix. Keep
+  // its active profile for commands dispatched in that child process.
+  const selectedProfile = requestedProfile?.name ?? process.env.PI_ACTIVE_PROFILE ?? "default";
+  if (guardrailArgs[0] === "guardrails") {
+    await handleGuardrailsCli(selectedProfile, guardrailArgs);
+    process.exit(0);
+  }
+  if (guardrailArgs[0] === "pulse") {
+    const { handlePulseCli } = await import("./pulse/index.ts");
+    await handlePulseCli(guardrailArgs, selectedProfile);
+    process.exit(0);
+  }
+  if (process.env.PI_PROFILE_REEXEC !== "1") {
+    await reexecWithProfile(requestedProfile?.name ?? "default", requestedProfile?.args ?? args);
+  }
+
+  pi.on("session_start", async () => {
+    if (process.env.PI_PROFILE_DISCOVER_TOOLS === "1") {
+      // Used by the host API gateway. Extensions are already loaded at this
+      // point, so this reports their tools without ever evaluating them there.
+      await writeStdout(`${JSON.stringify({ tools: pi.getAllTools().map((tool) => tool.name) })}\n`);
+      process.exit(0);
+    }
+    const settings = await readJson(join(activeAgentDir, "settings.json")).catch(() => ({}));
+    const enabledTools = settings.profile?.enabledTools;
+    if (!enabledTools || enabledTools.includes("*")) return;
+    const allowed = new Set(enabledTools);
+    pi.setActiveTools(pi.getAllTools().filter((tool) => allowed.has(tool.name)).map((tool) => tool.name));
+  });
+
+  pi.on("before_agent_start", async (event) => {
+    const sections: string[] = [];
+    const soulPath = join(activeAgentDir, "SOUL.md");
+    if (existsSync(soulPath)) { const soul = (await readFile(soulPath, "utf8")).trim(); if (soul) sections.push(`<profile_soul path="${soulPath}">\n${soul}\n</profile_soul>`); }
+    const handoff = process.env.PI_APPLICATION_HANDOFF?.trim();
+    if (handoff) sections.push(`<application_handoff>\nThe following is trusted pending context from the previous Application session. Use it only when it is relevant to the current user message. Do not mention this handoff unless needed to answer the user.\n\n${handoff}\n</application_handoff>`);
+    if (!sections.length) return;
+    return { systemPrompt: `${event.systemPrompt}\n\n${sections.join("\n\n")}` };
+  });
+}

package/extensions/pulse/index.ts

@@ -0,0 +1,62 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import { existsSync, openSync } from "node:fs";
+import { mkdir, readdir, readFile, unlink, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { spawn } from "node:child_process";
+import { PulseStore } from "./store.ts";
+
+const root = () => process.env.PI_PROFILE_ROOT ?? process.env.PI_CODING_AGENT_DIR ?? join(homedir(), ".pi", "agent");
+const dbPath = () => join(root(), "pulse.db"); const statePath = () => join(root(), "pulse-tick.state.json"); const logPath = () => join(root(), "pulse-tick.log");
+type State = { pid: number; startedAt: string };
+const alive = (pid: number) => { try { process.kill(pid, 0); return true; } catch { return false; } };
+async function json<T>(path: string): Promise<T | undefined> { try { return JSON.parse(await readFile(path, "utf8")) as T; } catch { return undefined; } }
+async function write(path: string, value: unknown) { await mkdir(root(), { recursive: true }); await writeFile(path, `${JSON.stringify(value, null, 2)}\n`, { mode: 0o600 }); }
+async function sessionFile(profile: string, id: string): Promise<{ file: string; cwd: string } | undefined> {
+  const directory = join(root(), profile === "default" ? "sessions" : join("profiles", profile, "sessions"));
+  const visit = async (path: string): Promise<string | undefined> => { for (const entry of await readdir(path, { withFileTypes: true }).catch(() => [])) { const candidate = join(path, entry.name); if (entry.isDirectory()) { const match = await visit(candidate); if (match) return match; } else if (entry.isFile() && entry.name.endsWith(`_${id}.jsonl`)) return candidate; } };
+  const file = await visit(directory); if (!file) return undefined;
+  const header = JSON.parse((await readFile(file, "utf8")).split("\n", 1)[0]) as { cwd?: string };
+  return { file, cwd: header.cwd || process.cwd() };
+}
+function table(profile?: string) { const rows = new PulseStore(dbPath()).list(profile); const columns: Array<[string, number]> = [["STATUS", 8], ["TYPE", 9], ["NAME", 20], ["SCHEDULE", 20], ["THREAD SESSION", 24], ["NEXT RUN", 20], ["LAST RUN", 20]]; const clip = (v: string, n: number) => v.length > n ? `${v.slice(0, n - 1)}…` : v; const row = (values: string[]) => `│ ${values.map((v, i) => clip(v, columns[i][1]).padEnd(columns[i][1])).join(" │ ")} │`; const line = `┼${columns.map(([, n]) => "─".repeat(n + 2)).join("┼")}┼`; console.log(line.replaceAll("┼", "┬").replace(/^┬/, "┌").replace(/┬$/, "┐")); console.log(row(columns.map(([n]) => n))); console.log(line); for (const item of rows) { const color = item.enabled ? "\x1b[32m" : "\x1b[38;2;245;194;215m"; console.log(`${color}${row([item.enabled ? "enabled" : "disabled", item.type, item.name, item.schedule, item.thread_session_id, item.nextRunAt ?? "—", item.lastRunAt ?? "—"])}\x1b[0m`); } if (!rows.length) console.log(row(["—", "—", "No pulses configured", "—", "—", "—", "—"])); console.log(line.replaceAll("┼", "┴").replace(/^┴/, "└").replace(/┴$/, "┘")); }
+async function start() { const current = await json<State>(statePath()); if (current && alive(current.pid)) return console.log(`Pulse tick is already running (PID ${current.pid}).`); await unlink(statePath()).catch(() => {}); const fd = openSync(logPath(), "a"); const child = spawn("sh", ["-c", "tail -f /dev/null | \"$@\"", "pi-pulse-tick", process.execPath, process.argv[1], "pulse", "tick"], { cwd: process.cwd(), detached: true, stdio: ["ignore", fd, fd], env: { ...process.env, PI_PULSE_TICK: "1" } }); child.unref(); await write(statePath(), { pid: child.pid!, startedAt: new Date().toISOString() }); console.log(`Pulse tick started (PID ${child.pid}).`); }
+async function stop() { const current = await json<State>(statePath()); if (!current || !alive(current.pid)) { await unlink(statePath()).catch(() => {}); return console.log("Pulse tick is not running."); } try { process.kill(-current.pid, "SIGTERM"); } catch { process.kill(current.pid, "SIGTERM"); } await unlink(statePath()).catch(() => {}); console.log("Pulse tick stopped."); }
+async function status() { const state = await json<State>(statePath()); const store = new PulseStore(dbPath()); const enabled = store.list().filter((item) => item.enabled).length; console.log(!state || !alive(state.pid) ? `Pulse tick: stopped (${enabled} enabled pulses)` : `Pulse tick: running (PID ${state.pid}, ${enabled} enabled pulses, since ${state.startedAt})`); }
+async function tick() { const store = new PulseStore(dbPath()); const execute = async () => { for (const pulse of store.due()) { const run = store.begin(pulse); try { const handoff = pulse.type === "heartbeat" ? store.handoff(pulse.id) : ""; const message = `[Pulse: ${pulse.name}]\n${pulse.prompt}${handoff ? `\n\nPrevious heartbeat state (private):\n${handoff}` : ""}`; const target = pulse.thread_session_id ? await sessionFile(pulse.profile, pulse.thread_session_id) : undefined; if (pulse.thread_session_id && !target) throw new Error(`Thread session '${pulse.thread_session_id}' was not found for profile '${pulse.profile}'.`); const result = await new Promise<string>((resolve, reject) => { const child = spawn(process.execPath, [process.argv[1], "profile", pulse.profile, ...(target ? ["--session", target.file] : ["--no-session"]), "--print", message], { cwd: target?.cwd ?? process.cwd(), env: { ...process.env, PI_PULSE_TICK: "1" }, stdio: ["ignore", "pipe", "pipe"] }); let output = "", error = ""; child.stdout.on("data", (data) => output += String(data)); child.stderr.on("data", (data) => error += String(data)); child.once("exit", (code) => code === 0 ? resolve(output.trim()) : reject(new Error(error.trim() || `Pi exited with ${code}`))); child.once("error", reject); }); const state = pulse.type === "heartbeat" ? result.slice(-8000) : undefined; store.complete(pulse, run, result, state); } catch (error) { store.fail(pulse, run, error instanceof Error ? error.message : String(error)); } } }; await execute(); const timer = setInterval(() => { void execute(); }, 15_000); await new Promise<void>((resolve) => { const close = () => { clearInterval(timer); resolve(); }; process.once("SIGTERM", close); process.once("SIGINT", close); }); }
+export async function handlePulseCli(args: string[], selectedProfile?: string): Promise<boolean> { if (args[0] !== "pulse") return false; const profileIndex = args.indexOf("--profile"); const profile = selectedProfile ?? (profileIndex >= 0 ? args[profileIndex + 1] : undefined); if (args[1] === "tick" && process.env.PI_PULSE_TICK === "1") { await tick(); return true; } switch (args[1]) { case "start": await start(); break; case "stop": await stop(); break; case "status": await status(); break; case "list": table(profile); break; case "enable": case "disable": { const name = args[2]; if (!name) throw new Error("Usage: pi pulse enable|disable <name>"); new PulseStore(dbPath()).setEnabled(name, args[1] === "enable", profile); console.log(`Pulse '${name}' ${args[1]}d.`); break; } default: console.error("Usage: pi pulse start | stop | status | list | enable <name> | disable <name>"); process.exitCode = 1; } return true; }
+export default async function (pi: ExtensionAPI) {
+  if (await handlePulseCli(process.argv.slice(2))) process.exit();
+  pi.on("before_agent_start", async (event) => ({ systemPrompt: `${event.systemPrompt}\n\nWhen the user asks to schedule, automate, remind, run future work, or manage an existing schedule, use the schedule tool. Do not ask for a thread or session ID: creation binds the schedule to this conversation automatically.` }));
+  pi.registerTool({
+    name: "schedule",
+    label: "Manage schedule",
+    description: "Create, list, edit, enable, disable, or delete cron jobs, heartbeats, reminders, and future schedules. Use this whenever the user asks to schedule or manage scheduled work.",
+    parameters: Type.Object({
+      action: Type.Union([Type.Literal("create"), Type.Literal("list"), Type.Literal("update"), Type.Literal("enable"), Type.Literal("disable"), Type.Literal("delete")]),
+      name: Type.Optional(Type.String({ description: "Schedule name. Required except when listing." })),
+      description: Type.Optional(Type.String({ description: "Human-readable purpose, required for create." })),
+      schedule: Type.Optional(Type.String({ description: "Five-field UTC cron expression or @once:<ISO-8601>. Required for create." })),
+      prompt: Type.Optional(Type.String({ description: "Markdown instructions, required for create." })),
+    }),
+    async execute(_id, params, _signal, _update, ctx) {
+      try {
+        const profile = process.env.PI_ACTIVE_PROFILE ?? "default", store = new PulseStore(dbPath());
+        if (params.action === "list") { const pulses = store.list(profile); return { content: [{ type: "text", text: JSON.stringify(pulses) }], details: { pulses } }; }
+        if (!params.name) throw new Error("A schedule name is required.");
+        if (params.action === "create") {
+          if (!params.description || !params.schedule || !params.prompt) throw new Error("Create requires name, description, schedule, and prompt.");
+          const threadSessionId = ctx.sessionManager.getSessionId(); if (!threadSessionId) throw new Error("A persistent conversation session is required to create a schedule.");
+          const pulse = store.create({ name: params.name, description: params.description, schedule: params.schedule, prompt: params.prompt, profile, thread_session_id: threadSessionId }); await start();
+          return { content: [{ type: "text", text: JSON.stringify(pulse) }], details: pulse };
+        }
+        if (params.action === "enable" || params.action === "disable") { const pulse = store.setEnabled(params.name, params.action === "enable", profile); return { content: [{ type: "text", text: JSON.stringify(pulse) }], details: pulse }; }
+        if (params.action === "delete") { store.delete(params.name, profile); return { content: [{ type: "text", text: `Schedule '${params.name}' deleted.` }], details: {} }; }
+        const current = store.get(params.name, profile); if (!current) throw new Error("Schedule not found.");
+        const pulse = store.update(params.name, profile, { description: params.description ?? current.description, schedule: params.schedule ?? current.schedule, prompt: params.prompt ?? current.prompt, thread_session_id: current.thread_session_id });
+        return { content: [{ type: "text", text: JSON.stringify(pulse) }], details: pulse };
+      } catch (error) { return { content: [{ type: "text", text: `Unable to manage schedule: ${error instanceof Error ? error.message : String(error)}` }], details: {}, isError: true }; }
+    },
+  });
+}

package/extensions/pulse/store.ts

@@ -0,0 +1,105 @@
+import { DatabaseSync } from "node:sqlite";
+import { randomUUID } from "node:crypto";
+import { mkdirSync } from "node:fs";
+import { dirname } from "node:path";
+
+export type PulseType = "cron" | "heartbeat";
+export type Pulse = { id: string; name: string; description: string; type: PulseType; schedule: string; prompt: string; thread_session_id: string; result: string | null; profile: string; enabled: boolean; nextRunAt: string | null; lastRunAt: string | null };
+export type PulseHistory = Pulse & { startedAt: string; finishedAt: string | null; status: string; error: string | null }; 
+type Row = Record<string, unknown>;
+const iso = (date = new Date()) => date.toISOString();
+
+function fieldMatches(field: string, value: number, min: number, max: number): boolean {
+  return field.split(",").some((part) => {
+    const [range, stepText] = part.split("/"); const step = stepText ? Number(stepText) : 1;
+    if (!Number.isInteger(step) || step < 1) return false;
+    const values = range === "*" ? [min, max] : range.split("-").map(Number);
+    if (values.length > 2 || values.some((item) => !Number.isInteger(item)) || values[0] < min || values[values.length - 1] > max) return false;
+    const [from, to] = values.length === 1 ? [values[0], values[0]] : values;
+    return value >= from && value <= to && (value - from) % step === 0;
+  });
+}
+export function validSchedule(schedule: string): boolean {
+  if (/^@once:\d{4}-\d{2}-\d{2}T/.test(schedule)) return !Number.isNaN(Date.parse(schedule.slice(6)));
+  const fields = schedule.trim().split(/\s+/); if (fields.length !== 5) return false;
+  return [[0, 59], [0, 23], [1, 31], [1, 12], [0, 6]].every(([min, max], index) => fields[index].split(",").every((part) => {
+    const match = part.match(/^(\*|\d+(?:-\d+)?)(?:\/(\d+))?$/); if (!match) return false;
+    const step = match[2] ? Number(match[2]) : 1; if (!Number.isInteger(step) || step < 1) return false;
+    if (match[1] === "*") return true; const values = match[1].split("-").map(Number);
+    return values.every((value) => Number.isInteger(value) && value >= min && value <= max) && (values.length === 1 || values[0] <= values[1]);
+  }));
+}
+export function nextRun(schedule: string, after = new Date()): Date | null {
+  if (schedule.startsWith("@once:")) { const date = new Date(schedule.slice(6)); return date > after ? date : null; }
+  if (!validSchedule(schedule)) return null;
+  const [minute, hour, day, month, weekDay] = schedule.trim().split(/\s+/);
+  const candidate = new Date(after); candidate.setUTCSeconds(0, 0); candidate.setUTCMinutes(candidate.getUTCMinutes() + 1);
+  for (let count = 0; count < 527_040; count++, candidate.setUTCMinutes(candidate.getUTCMinutes() + 1)) {
+    if (fieldMatches(minute, candidate.getUTCMinutes(), 0, 59) && fieldMatches(hour, candidate.getUTCHours(), 0, 23) && fieldMatches(day, candidate.getUTCDate(), 1, 31) && fieldMatches(month, candidate.getUTCMonth() + 1, 1, 12) && fieldMatches(weekDay, candidate.getUTCDay(), 0, 6)) return new Date(candidate);
+  }
+  return null;
+}
+export function pulseType(schedule: string): PulseType {
+  if (schedule.startsWith("@once:")) return "cron";
+  const [minute = "", hour = ""] = schedule.trim().split(/\s+/);
+  // Classify from the declared interval, not from how a cron implementation
+  // wraps an oversized step inside a single field (e.g. */1000).
+  const minuteStep = minute.match(/^\*\/(\d+)$/);
+  if (minuteStep) return Number(minuteStep[1]) < 240 ? "heartbeat" : "cron";
+  const hourStep = hour.match(/^\*\/(\d+)$/);
+  if (hourStep && minute === "0") return Number(hourStep[1]) < 4 ? "heartbeat" : "cron";
+  const first = nextRun(schedule, new Date("2026-01-01T00:00:00Z")), second = first ? nextRun(schedule, first) : null;
+  return first && second && second.getTime() - first.getTime() < 4 * 60 * 60 * 1000 ? "heartbeat" : "cron";
+}
+function heartbeatAllowed(schedule: string): boolean { return pulseType(schedule) === "heartbeat"; }
+
+export class PulseStore {
+  private db: DatabaseSync;
+  constructor(path: string) {
+    mkdirSync(dirname(path), { recursive: true }); this.db = new DatabaseSync(path); this.db.exec("PRAGMA journal_mode=WAL; PRAGMA foreign_keys=ON;");
+    this.db.exec(`CREATE TABLE IF NOT EXISTS pulses (id TEXT PRIMARY KEY, name TEXT NOT NULL UNIQUE, description TEXT NOT NULL, type TEXT NOT NULL CHECK(type IN ('cron','heartbeat')), schedule TEXT NOT NULL, prompt TEXT NOT NULL, thread_session_id TEXT NOT NULL, result TEXT);
+      CREATE TABLE IF NOT EXISTS pulse_control (pulse_id TEXT PRIMARY KEY REFERENCES pulses(id) ON DELETE CASCADE, profile TEXT NOT NULL, enabled INTEGER NOT NULL DEFAULT 1, next_run_at TEXT, last_run_at TEXT, updated_at TEXT NOT NULL);
+      CREATE TABLE IF NOT EXISTS pulse_state (pulse_id TEXT PRIMARY KEY REFERENCES pulses(id) ON DELETE CASCADE, handoff TEXT NOT NULL DEFAULT '', updated_at TEXT NOT NULL);
+      CREATE TABLE IF NOT EXISTS pulse_runs (id TEXT PRIMARY KEY, pulse_id TEXT NOT NULL REFERENCES pulses(id) ON DELETE CASCADE, started_at TEXT NOT NULL, finished_at TEXT, status TEXT NOT NULL, response TEXT, error TEXT);`);
+    // Migrate databases created before the denormalized latest result column.
+    const columns = this.db.prepare("PRAGMA table_info(pulses)").all() as Row[];
+    if (!columns.some((column) => column.name === "result")) this.db.exec("ALTER TABLE pulses ADD COLUMN result TEXT");
+    this.db.exec("UPDATE pulses SET result=(SELECT response FROM pulse_runs WHERE pulse_id=pulses.id AND status='success' ORDER BY finished_at DESC LIMIT 1) WHERE result IS NULL");
+    // Keep records created before the schedule-based classifier in sync.
+    for (const row of this.db.prepare("SELECT id, schedule, type FROM pulses").all() as Row[]) { const type = pulseType(String(row.schedule)); if (row.type !== type) this.db.prepare("UPDATE pulses SET type=? WHERE id=?").run(type, row.id); }
+  }
+  private pulse(row: Row): Pulse { return { id: String(row.id), name: String(row.name), description: String(row.description), type: row.type as PulseType, schedule: String(row.schedule), prompt: String(row.prompt), thread_session_id: String(row.thread_session_id), result: row.result == null ? null : String(row.result), profile: String(row.profile), enabled: Boolean(row.enabled), nextRunAt: row.next_run_at ? String(row.next_run_at) : null, lastRunAt: row.last_run_at ? String(row.last_run_at) : null }; }
+  list(profile?: string): Pulse[] { const query = `SELECT p.*, c.profile, c.enabled, c.next_run_at, c.last_run_at FROM pulses p JOIN pulse_control c ON c.pulse_id=p.id${profile ? " WHERE c.profile=?" : ""} ORDER BY p.name`; return this.db.prepare(query).all(...(profile ? [profile] : [])) .map((row) => this.pulse(row as Row)); }
+  get(name: string, profile?: string): Pulse | undefined { return this.list(profile).find((item) => item.name === name); }
+  history(profile: string): PulseHistory[] { return this.db.prepare(`SELECT p.*, c.profile, c.enabled, c.next_run_at, c.last_run_at, r.started_at AS startedAt, r.finished_at AS finishedAt, r.status, r.error FROM pulses p JOIN pulse_control c ON c.pulse_id=p.id JOIN pulse_runs r ON r.id=(SELECT id FROM pulse_runs WHERE pulse_id=p.id AND finished_at IS NOT NULL ORDER BY started_at DESC LIMIT 1) WHERE c.profile=? AND p.schedule LIKE '@once:%' ORDER BY r.started_at DESC`).all(profile).map((row) => { const record = row as Row; return { ...this.pulse(record), startedAt: String(record.startedAt), finishedAt: record.finishedAt == null ? null : String(record.finishedAt), status: String(record.status), error: record.error == null ? null : String(record.error) }; }); }
+  create(input: Omit<Pulse, "id" | "enabled" | "nextRunAt" | "lastRunAt" | "type" | "result">): Pulse {
+    if (!/^[A-Za-z][A-Za-z0-9_-]{0,63}$/.test(input.name)) throw new Error("Invalid pulse name.");
+    if (!validSchedule(input.schedule)) throw new Error("Invalid schedule. Use a five-field UTC cron expression or @once:<ISO-8601>.");
+    const type = pulseType(input.schedule), id = randomUUID(), next = nextRun(input.schedule)?.toISOString() ?? null;
+    this.db.prepare("INSERT INTO pulses (id, name, description, type, schedule, prompt, thread_session_id, result) VALUES (?, ?, ?, ?, ?, ?, ?, NULL)").run(id, input.name, input.description, type, input.schedule, input.prompt, input.thread_session_id);
+    this.db.prepare("INSERT INTO pulse_control VALUES (?, ?, 1, ?, NULL, ?)").run(id, input.profile, next, iso());
+    if (type === "heartbeat") this.db.prepare("INSERT INTO pulse_state VALUES (?, '', ?)").run(id, iso());
+    return this.get(input.name, input.profile)!;
+  }
+  setEnabled(name: string, enabled: boolean, profile?: string): Pulse {
+    const pulse = this.get(name, profile); if (!pulse) throw new Error("Pulse not found.");
+    const next = enabled ? nextRun(pulse.schedule)?.toISOString() ?? null : null;
+    this.db.prepare("UPDATE pulse_control SET enabled=?, next_run_at=?, updated_at=? WHERE pulse_id=?").run(enabled ? 1 : 0, next, iso(), pulse.id);
+    return this.get(name, profile)!;
+  }
+  update(name: string, profile: string | undefined, input: Pick<Pulse, "description" | "schedule" | "prompt" | "thread_session_id">): Pulse {
+    const pulse = this.get(name, profile); if (!pulse) throw new Error("Pulse not found.");
+    if (!validSchedule(input.schedule)) throw new Error("Invalid schedule. Use a five-field UTC cron expression or @once:<ISO-8601>.");
+    const type = pulseType(input.schedule);
+    this.db.prepare("UPDATE pulses SET description=?, type=?, schedule=?, prompt=?, thread_session_id=? WHERE id=?").run(input.description, type, input.schedule, input.prompt, input.thread_session_id, pulse.id);
+    this.db.prepare("UPDATE pulse_control SET next_run_at=?, updated_at=? WHERE pulse_id=?").run(pulse.enabled ? nextRun(input.schedule)?.toISOString() ?? null : null, iso(), pulse.id);
+    return this.get(name, profile)!;
+  }
+  delete(name: string, profile?: string): void { const pulse = this.get(name, profile); if (!pulse) throw new Error("Pulse not found."); this.db.prepare("DELETE FROM pulses WHERE id=?").run(pulse.id); }
+  due(now = iso()): Pulse[] { return this.db.prepare("SELECT p.*, c.profile, c.enabled, c.next_run_at, c.last_run_at FROM pulses p JOIN pulse_control c ON c.pulse_id=p.id WHERE c.enabled=1 AND c.next_run_at IS NOT NULL AND c.next_run_at<=? ORDER BY c.next_run_at").all(now).map((row) => this.pulse(row as Row)); }
+  begin(pulse: Pulse): string { const id = randomUUID(); this.db.prepare("INSERT INTO pulse_runs VALUES (?, ?, ?, NULL, 'running', NULL, NULL)").run(id, pulse.id, iso()); return id; }
+  complete(pulse: Pulse, runId: string, response: string, handoff?: string): void { const next = nextRun(pulse.schedule)?.toISOString() ?? null; this.db.prepare("UPDATE pulse_runs SET finished_at=?, status='success', response=? WHERE id=?").run(iso(), response, runId); this.db.prepare("UPDATE pulses SET result=? WHERE id=?").run(response, pulse.id); this.db.prepare("UPDATE pulse_control SET last_run_at=?, next_run_at=?, updated_at=? WHERE pulse_id=?").run(iso(), next, iso(), pulse.id); if (pulse.type === "heartbeat" && handoff !== undefined) this.db.prepare("UPDATE pulse_state SET handoff=?, updated_at=? WHERE pulse_id=?").run(handoff, iso(), pulse.id); }
+  fail(pulse: Pulse, runId: string, error: string): void { this.db.prepare("UPDATE pulse_runs SET finished_at=?, status='error', error=? WHERE id=?").run(iso(), error, runId); this.db.prepare("UPDATE pulse_control SET next_run_at=?, updated_at=? WHERE pulse_id=?").run(nextRun(pulse.schedule, new Date(Date.now() + 60_000))?.toISOString() ?? null, iso(), pulse.id); }
+  handoff(id: string): string { return String((this.db.prepare("SELECT handoff FROM pulse_state WHERE pulse_id=?").get(id) as Row | undefined)?.handoff ?? ""); }
+  retarget(profile: string, from: string, to: string): void { this.db.prepare("UPDATE pulses SET thread_session_id=? WHERE id IN (SELECT pulse_id FROM pulse_control WHERE profile=?) AND thread_session_id=?").run(to, profile, from); }
+}