pi-pstack-adapter 0.3.0

package/src/agents.ts

@@ -0,0 +1,69 @@
+import type { Diagnostic, GeneratedAgent } from "./types.ts";
+
+export const RUNTIME_AGENT_REGISTER_EVENT = "pi-subagents:runtime-agent-register:v1";
+
+export interface RuntimeRegistration {
+  dispose(): void;
+}
+
+interface RegisterRequest {
+  version: 1;
+  name: string;
+  definition: { description: string; systemPrompt: string; tools?: readonly string[] };
+  result?: { ok: true; registration: RuntimeRegistration } | { ok: false; error: Error };
+}
+
+export interface EventBus {
+  emit(event: string, payload: unknown): void;
+}
+
+export interface AgentRegistrationResult {
+  readonly registrations: readonly RuntimeRegistration[];
+  readonly diagnostics: readonly Diagnostic[];
+}
+
+/**
+ * Hands the converted upstream agents to whichever installed extension owns the
+ * pi-subagents runtime registration contract. No owner means no delegation provider.
+ */
+export function registerAgents(
+  bus: EventBus,
+  agents: readonly GeneratedAgent[],
+  namespace: string,
+): AgentRegistrationResult {
+  const registrations: RuntimeRegistration[] = [];
+  const diagnostics: Diagnostic[] = [];
+
+  for (const agent of agents) {
+    const request: RegisterRequest = {
+      version: 1,
+      name: agent.generatedName,
+      definition: {
+        description: `${agent.displayName}. ${agent.description}`,
+        systemPrompt: agent.systemPrompt,
+      },
+    };
+    bus.emit(RUNTIME_AGENT_REGISTER_EVENT, request);
+    if (!request.result) {
+      diagnostics.push({
+        level: "warning",
+        resource: `agent:${agent.upstreamName}`,
+        message: `No installed delegation provider accepted \`${agent.generatedName}\`, so pstack workflows cannot delegate to it.`,
+        action: `Install a provider that owns ${RUNTIME_AGENT_REGISTER_EVENT}, for example \`pi install npm:pi-subagents\`.`,
+      });
+      continue;
+    }
+    if (!request.result.ok) {
+      diagnostics.push({
+        level: "error",
+        resource: `agent:${agent.upstreamName}`,
+        message: `Registering \`${agent.generatedName}\` failed: ${request.result.error.message}`,
+        action: `Check for an agent name collision under the \`${namespace}\` namespace.`,
+      });
+      continue;
+    }
+    registrations.push(request.result.registration);
+  }
+
+  return { registrations, diagnostics };
+}

package/src/capabilities.ts

@@ -0,0 +1,85 @@
+import type { CapabilityId, CapabilityStatus } from "./types.ts";
+
+export interface ToolDescriptor {
+  readonly name: string;
+  readonly parameters?: unknown;
+  readonly sourceInfo?: { readonly source?: string };
+}
+
+interface CapabilityProbe {
+  readonly id: CapabilityId;
+  readonly toolName: string;
+  /** Parameter names the tool must accept for the capability to be usable. */
+  readonly requiredParameters: readonly string[];
+  readonly recommendation: string;
+}
+
+const PROBES: readonly CapabilityProbe[] = [
+  {
+    id: "delegation",
+    toolName: "subagent",
+    requiredParameters: ["agent", "task", "async", "model"],
+    recommendation: "Install a delegation provider that exposes named background agents with model selection, for example `pi install npm:pi-subagents`.",
+  },
+  {
+    id: "structured-question",
+    toolName: "ask_user",
+    requiredParameters: ["question", "options"],
+    recommendation: "Install a structured question provider, for example `pi install npm:pi-ask-user`.",
+  },
+];
+
+export function detectCapabilities(tools: readonly ToolDescriptor[]): CapabilityStatus[] {
+  return PROBES.map((probe) => {
+    const tool = tools.find((candidate) => candidate.name === probe.toolName);
+    if (!tool) {
+      return { id: probe.id, available: false, recommendation: probe.recommendation };
+    }
+    const properties = parameterNames(tool.parameters);
+    const missing = probe.requiredParameters.filter((name) => !properties.has(name));
+    if (missing.length > 0) {
+      return {
+        id: probe.id,
+        available: false,
+        provider: tool.sourceInfo?.source,
+        recommendation: `The \`${probe.toolName}\` tool is present but does not accept ${missing.join(", ")}. ${probe.recommendation}`,
+      };
+    }
+    return { id: probe.id, available: true, provider: tool.sourceInfo?.source, recommendation: probe.recommendation };
+  });
+}
+
+function parameterNames(parameters: unknown): Set<string> {
+  if (typeof parameters !== "object" || parameters === null) return new Set();
+  const properties = (parameters as { properties?: unknown }).properties;
+  if (typeof properties !== "object" || properties === null) return new Set();
+  return new Set(Object.keys(properties as Record<string, unknown>));
+}
+
+export interface PrerequisiteReport {
+  readonly ok: boolean;
+  readonly lines: readonly string[];
+}
+
+export function checkPrerequisites(
+  required: readonly CapabilityId[],
+  statuses: readonly CapabilityStatus[],
+  executables: readonly string[],
+  hasExecutable: (name: string) => boolean,
+  /** Session problems that stop every workflow, such as a missing Bash shell. */
+  blockers: readonly string[] = [],
+): PrerequisiteReport {
+  const lines: string[] = [...blockers];
+  for (const id of required) {
+    const status = statuses.find((candidate) => candidate.id === id);
+    if (!status || !status.available) {
+      lines.push(`Missing capability \`${id}\`. ${status?.recommendation ?? ""}`.trim());
+    }
+  }
+  for (const executable of executables) {
+    if (!hasExecutable(executable)) {
+      lines.push(`Missing executable \`${executable}\` on PATH. Install it before starting this workflow.`);
+    }
+  }
+  return { ok: lines.length === 0, lines };
+}

package/src/certified.ts

@@ -0,0 +1,13 @@
+/**
+ * The one upstream revision this adapter release was tested against.
+ * Adapter semantic versions move independently of these values.
+ */
+export const CERTIFIED = {
+  repo: "https://github.com/cursor/plugins",
+  ref: "main",
+  commit: "e43c7ee26e0038c6c1fa8380dd34ce86ff94cb2a",
+  pluginPath: "pstack",
+  pstackVersion: "0.15.9",
+  skillCount: 50,
+  agentCount: 2,
+} as const;

package/src/config.ts

@@ -0,0 +1,210 @@
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, isAbsolute, resolve } from "node:path";
+import { CERTIFIED } from "./certified.ts";
+import { DEFAULT_NAMESPACE, validateNamespace } from "./namespace.ts";
+import { expandHome } from "./paths.ts";
+import type { SourceSelection, Trust } from "./types.ts";
+
+export interface AdapterConfig {
+  readonly namespace: string;
+  readonly repo: string;
+  readonly ref: string;
+  readonly pluginPath: string;
+  /** Absolute path to a local pstack checkout, replacing the git source. */
+  readonly localPath?: string;
+  /** Commit recorded by a previous explicit setup. Startup never advances it. */
+  readonly pinnedCommit?: string;
+  readonly allowBootstrap: boolean;
+  readonly cacheDir?: string;
+  readonly models: Readonly<Record<string, string>>;
+  readonly sources: readonly string[];
+}
+
+export interface ConfigFile {
+  namespace?: string;
+  repo?: string;
+  ref?: string;
+  pluginPath?: string;
+  localPath?: string;
+  pinnedCommit?: string;
+  allowBootstrap?: boolean;
+  cacheDir?: string;
+  models?: Record<string, string>;
+}
+
+export interface ConfigLayer {
+  readonly label: string;
+  readonly path?: string;
+  readonly values: ConfigFile;
+}
+
+const NEGATIVE = new Set(["0", "false", "no", "off", ""]);
+
+const ENV = {
+  namespace: "PISTACK_NAMESPACE",
+  repo: "PISTACK_UPSTREAM_REPO",
+  ref: "PISTACK_UPSTREAM_REF",
+  localPath: "PISTACK_UPSTREAM_PATH",
+  pluginPath: "PISTACK_UPSTREAM_PLUGIN_PATH",
+  allowBootstrap: "PISTACK_ALLOW_BOOTSTRAP",
+  cacheDir: "PISTACK_CACHE_DIR",
+  models: "PISTACK_MODELS",
+} as const;
+
+export function readConfigFile(path: string): ConfigLayer | undefined {
+  let raw: string;
+  try {
+    raw = readFileSync(path, "utf8");
+  } catch {
+    return undefined;
+  }
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (error) {
+    throw new Error(`${path} is not valid JSON: ${(error as Error).message}`);
+  }
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+    throw new Error(`${path} must contain a JSON object.`);
+  }
+  return { label: path, path, values: parsed as ConfigFile };
+}
+
+/** Shallow patch. A `models` value replaces the stored map, so callers control removals. */
+export function updateConfigFile(path: string, patch: ConfigFile): ConfigFile {
+  const current = readConfigFile(path)?.values ?? {};
+  const next: ConfigFile = { ...current, ...patch };
+  for (const [key, value] of Object.entries(next)) {
+    if (value === undefined) delete (next as Record<string, unknown>)[key];
+  }
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, `${JSON.stringify(next, null, 2)}\n`, "utf8");
+  return next;
+}
+
+/** `role=provider/model,role2=provider/model2` */
+export function parseModelRoles(value: string): Record<string, string> {
+  const roles: Record<string, string> = {};
+  for (const pair of value.split(",")) {
+    const trimmed = pair.trim();
+    if (trimmed === "") continue;
+    const separator = trimmed.indexOf("=");
+    if (separator <= 0) {
+      throw new Error(`Invalid model role assignment ${JSON.stringify(trimmed)}. Use role=provider/model.`);
+    }
+    roles[trimmed.slice(0, separator).trim()] = trimmed.slice(separator + 1).trim();
+  }
+  return roles;
+}
+
+export function environmentLayer(env: NodeJS.ProcessEnv): ConfigLayer {
+  const values: ConfigFile = {};
+  if (env[ENV.namespace]) values.namespace = env[ENV.namespace];
+  if (env[ENV.repo]) values.repo = env[ENV.repo];
+  if (env[ENV.ref]) values.ref = env[ENV.ref];
+  if (env[ENV.localPath]) values.localPath = env[ENV.localPath];
+  if (env[ENV.pluginPath]) values.pluginPath = env[ENV.pluginPath];
+  if (env[ENV.cacheDir]) values.cacheDir = env[ENV.cacheDir];
+  if (env[ENV.allowBootstrap]) values.allowBootstrap = !NEGATIVE.has((env[ENV.allowBootstrap] as string).trim().toLowerCase());
+  if (env[ENV.models]) values.models = parseModelRoles(env[ENV.models] as string);
+  return { label: "environment", values };
+}
+
+export function mergeConfig(layers: readonly ConfigLayer[]): AdapterConfig {
+  const merged: ConfigFile = {};
+  const sources: string[] = [];
+  for (const layer of layers) {
+    let contributed = false;
+    for (const [key, value] of Object.entries(layer.values)) {
+      if (value === undefined) continue;
+      // `JSON.parse` yields `__proto__` as an own key, and a plain assignment would invoke the
+      // prototype setter, letting a config file reach fields the caller deliberately removed.
+      if (key === "__proto__" || key === "constructor" || key === "prototype") continue;
+      // Source selection follows layer precedence: a later layer naming a git source retires an
+      // earlier local checkout, and vice versa.
+      if (key === "repo" || key === "ref") merged.localPath = undefined;
+      if (key === "localPath") {
+        merged.repo = undefined;
+        merged.ref = undefined;
+      }
+      if (key === "models") {
+        merged.models = { ...merged.models, ...(value as Record<string, string>) };
+      } else {
+        (merged as Record<string, unknown>)[key] = value;
+      }
+      contributed = true;
+    }
+    if (contributed) sources.push(layer.label);
+  }
+
+  const localPath = merged.localPath
+    ? resolveLayerPath(merged.localPath, layers)
+    : undefined;
+
+  return {
+    namespace: validateNamespace(merged.namespace ?? DEFAULT_NAMESPACE),
+    repo: merged.repo ?? CERTIFIED.repo,
+    ref: merged.ref ?? CERTIFIED.ref,
+    pluginPath: merged.pluginPath ?? CERTIFIED.pluginPath,
+    localPath,
+    pinnedCommit: merged.localPath ? undefined : resolvePin(merged),
+    allowBootstrap: merged.allowBootstrap ?? false,
+    cacheDir: merged.cacheDir,
+    models: merged.models ?? {},
+    sources,
+  };
+}
+
+/**
+ * The certified commit is the default, not a floor. Naming a ref or a repository without a
+ * commit means the user asked for that ref, so the pin must get out of the way and trust
+ * must fall to `untested-*`.
+ */
+function resolvePin(merged: ConfigFile): string | undefined {
+  if (merged.pinnedCommit) return merged.pinnedCommit;
+  if (merged.ref) return undefined;
+  if (merged.repo && normalizeRepo(merged.repo) !== normalizeRepo(CERTIFIED.repo)) return undefined;
+  return CERTIFIED.commit;
+}
+
+function resolveLayerPath(value: string, layers: readonly ConfigLayer[]): string {
+  const expanded = expandHome(value);
+  if (isAbsolute(expanded)) return expanded;
+  const owner = [...layers].reverse().find((layer) => layer.values.localPath === value && layer.path);
+  return resolve(owner?.path ? dirname(owner.path) : process.cwd(), expanded);
+}
+
+export function selectionOf(config: AdapterConfig): SourceSelection {
+  if (config.localPath) return { kind: "local", path: config.localPath };
+  return { kind: "git", repo: config.repo, ref: config.pinnedCommit ?? config.ref };
+}
+
+export function trustOf(config: AdapterConfig): Trust {
+  if (config.localPath) return "local";
+  if (normalizeRepo(config.repo) !== normalizeRepo(CERTIFIED.repo)) return "untested-repo";
+  if (config.pinnedCommit === CERTIFIED.commit) return "tested";
+  return "untested-ref";
+}
+
+export function normalizeRepo(repo: string): string {
+  return repo
+    .trim()
+    .replace(/^git\+/, "")
+    .replace(/\/+$/, "")
+    .replace(/\.git$/, "")
+    .replace(/\/+$/, "")
+    .toLowerCase();
+}
+
+export function trustWarning(trust: Trust, config: AdapterConfig): string | undefined {
+  switch (trust) {
+    case "tested":
+      return undefined;
+    case "untested-ref":
+      return `pstack adapter is using an untested upstream ref (${config.pinnedCommit ?? config.ref}). This release certified ${CERTIFIED.commit}. Behavior is not verified.`;
+    case "untested-repo":
+      return `pstack adapter is using a custom repository (${config.repo}). Code from this source is outside the tested trust boundary and runs with your full permissions. Only continue if you trust it.`;
+    case "local":
+      return `pstack adapter is using a local checkout (${config.localPath}). Contents are unverified and not reproducible across machines.`;
+  }
+}

package/src/executables.ts

@@ -0,0 +1,150 @@
+import { spawnSync } from "node:child_process";
+import { randomBytes } from "node:crypto";
+import { accessSync, constants, existsSync } from "node:fs";
+import { delimiter, join } from "node:path";
+import { getShellConfig, SettingsManager } from "@earendil-works/pi-coding-agent";
+
+/** The shell Pi's `bash` tool runs commands with, as `getShellConfig()` reports it. */
+export interface ShellConfig {
+  readonly shell: string;
+  readonly args: readonly string[];
+  /** Legacy WSL `bash.exe` reads the command from stdin (`-s`) instead of `-c`. */
+  readonly commandTransport?: "argv" | "stdin";
+}
+
+/** Everything that decides what a command run by Pi's `bash` tool can find. */
+export interface BashToolContext {
+  readonly shell: ShellConfig;
+  /** Pi's `shellCommandPrefix`, which runs before every command. */
+  readonly prefix?: string;
+  readonly cwd: string;
+  readonly env: NodeJS.ProcessEnv;
+}
+
+export type ExecutableCheck = (name: string) => boolean;
+
+/**
+ * The context Pi's `bash` tool would run in for this session. Project settings count only in a
+ * trusted project, as in Pi itself, so an untrusted checkout cannot choose the executable or the
+ * prefix this spawns. Throws when Pi cannot resolve a Bash shell.
+ */
+export function bashToolContext(cwd: string, agentDir: string, projectTrusted: boolean): BashToolContext {
+  const settings = SettingsManager.create(cwd, agentDir, { projectTrusted });
+  return {
+    shell: getShellConfig(settings.getShellPath()),
+    prefix: settings.getShellCommandPrefix(),
+    cwd,
+    env: piShellEnv(agentDir),
+  };
+}
+
+/** Pi's `getShellEnv`, which is not exported: its own `bin` directory goes first on PATH. */
+function piShellEnv(agentDir: string): NodeJS.ProcessEnv {
+  const pathKey = Object.keys(process.env).find((key) => key.toLowerCase() === "path") ?? "PATH";
+  const current = process.env[pathKey] ?? "";
+  const binDir = join(agentDir, "bin");
+  const entries = current.split(delimiter).filter(Boolean);
+  return { ...process.env, [pathKey]: entries.includes(binDir) ? current : [binDir, current].filter(Boolean).join(delimiter) };
+}
+
+/** True when `command` is an executable file on this process's PATH. */
+export function onPath(command: string, platform: NodeJS.Platform = process.platform): boolean {
+  const paths = (process.env.PATH ?? "").split(delimiter).filter((entry) => entry !== "");
+  const extensions = platform === "win32" ? (process.env.PATHEXT ?? ".EXE;.CMD;.BAT").split(";") : [""];
+  for (const directory of paths) {
+    for (const extension of extensions) {
+      const candidate = join(directory, `${command}${extension}`);
+      if (!existsSync(candidate)) continue;
+      try {
+        accessSync(candidate, constants.X_OK);
+        return true;
+      } catch {
+        // Not executable by this user. Keep looking.
+      }
+    }
+  }
+  return false;
+}
+
+// `$1` is a per-run nonce. Only lines carrying it count, so output from Pi's `shellCommandPrefix`
+// cannot fake a result, and the closing `done` line proves the script ran to the end: a program
+// that exits 0 without being a shell, or a prefix that exits early, never prints it.
+const PROBE_SCRIPT =
+  'nonce=$1; shift; for name in "$@"; do command -v -- "$name" >/dev/null 2>&1 && printf "%s found %s\\n" "$nonce" "$name"; done; printf "%s done\\n" "$nonce"; exit 0';
+
+export type ShellProbe =
+  | { readonly kind: "ran"; readonly found: ReadonlySet<string> }
+  | { readonly kind: "failed"; readonly reason: string };
+
+/**
+ * Runs `command -v` for each name in the bash tool's context, with Pi's `shellCommandPrefix`
+ * first, exactly as the tool would run a command. It runs even with no names, because a shell
+ * that cannot run a command blocks every workflow. Names travel as positional arguments, never
+ * inside the script text.
+ */
+export function shellExecutables(context: BashToolContext, names: readonly string[]): ShellProbe {
+  const script = context.prefix ? `${context.prefix}\n${PROBE_SCRIPT}` : PROBE_SCRIPT;
+  // With `-c` the word after the script is `$0`; with `-s` the script arrives on stdin, and `--`
+  // stops bash from reading a name as an option.
+  const stdin = context.shell.commandTransport === "stdin";
+  const nonce = `pistack-probe-${randomBytes(12).toString("hex")}`;
+  const args = stdin
+    ? [...context.shell.args, "--", nonce, ...names]
+    : [...context.shell.args, script, "pistack-probe", nonce, ...names];
+  const result = spawnSync(context.shell.shell, args, {
+    cwd: context.cwd,
+    env: context.env,
+    input: stdin ? script : undefined,
+    encoding: "utf8",
+    timeout: 10_000,
+    windowsHide: true,
+  });
+  if (result.error) return { kind: "failed", reason: result.error.message };
+  if (result.status !== 0) {
+    const detail = (result.stderr ?? "").trim().split(/\r?\n/)[0];
+    return { kind: "failed", reason: `it exited ${result.status ?? result.signal}${detail ? `: ${detail}` : ""}` };
+  }
+  const lines = result.stdout.split(/\r?\n/);
+  if (!lines.includes(`${nonce} done`)) {
+    return { kind: "failed", reason: "it exited without running the probe command" };
+  }
+  const marker = `${nonce} found `;
+  const found = lines.filter((line) => line.startsWith(marker)).map((line) => line.slice(marker.length));
+  return { kind: "ran", found: new Set(found.filter((name) => names.includes(name))) };
+}
+
+export interface ExecutableReport {
+  readonly has: ExecutableCheck;
+  /** Set when Pi's bash shell resolved but could not run a command. */
+  readonly shellFailure?: string;
+}
+
+/**
+ * Skill bodies run their commands through Pi's `bash` tool, so executables are looked up there:
+ * with Pi's `shellCommandPrefix` and its `bin` directory on every platform, and on native Windows
+ * inside Git Bash, whose PATH adds `/usr/bin` and `/mingw64/bin` to the PATH Pi started with.
+ * Pass no context when the tool is inactive or its shell cannot be resolved; the shell
+ * diagnostics report that, and the PATH scan answers for the executables.
+ */
+export function probeExecutables(
+  names: readonly string[],
+  resolveContext: (() => BashToolContext) | undefined,
+  platform: NodeJS.Platform = process.platform,
+): ExecutableReport {
+  const scan: ExecutableCheck = (name) => onPath(name, platform);
+  if (!resolveContext) return { has: scan };
+  let context: BashToolContext;
+  try {
+    context = resolveContext();
+  } catch {
+    return { has: scan };
+  }
+  const probe = shellExecutables(context, names);
+  if (probe.kind === "failed") {
+    return {
+      has: scan,
+      shellFailure: `Pi's bash shell ${context.shell.shell} could not run a command, so pstack skills cannot run here: ${probe.reason}. Fix the shell or \`shellCommandPrefix\` in Pi settings, or set \`shellPath\` to a working Bash executable, then restart Pi.`,
+    };
+  }
+  return { has: (name) => probe.found.has(name) };
+}