pi-pstack-adapter 0.3.0 → 0.5.0

package/src/status.ts

@@ -1,10 +1,12 @@
 import { CERTIFIED } from "./certified.ts";
 import { CAPABILITY_LABELS, MODEL_ROLES, TIER_ORDER } from "./registry.ts";
 import type { AdapterConfig } from "./config.ts";
-import { trustWarning } from "./config.ts";
+import { splitModelSpec, trustWarning } from "./config.ts";
+import { DELEGATION_BACKENDS, delegationOrder } from "./delegation.ts";
 import type { PrerequisiteReport } from "./capabilities.ts";
 import type {
   CapabilityStatus,
+  DelegationProvider,
   Diagnostic,
   GeneratedSkill,
   GenerationResult,
@@ -46,13 +48,18 @@ export function renderStatus(input: StatusInput): string {
   lines.push(`| certified commit | ${CERTIFIED.commit} |`);
   lines.push(`| trust | ${source.trust} |`);
   lines.push(`| checkout | ${source.checkoutDir} |`);
+  lines.push(`| plugin directory | ${source.pluginDir} |`);
   lines.push(`| generated resources | ${input.generation.outDir} |`);
+  lines.push(`| generated skills | ${input.generation.skillsDir} |`);
+  lines.push(`| agent prompts | ${input.generation.agentPromptsDir} |`);
   lines.push(`| cache root | ${input.cacheRoot} |`);
   lines.push(`| cache state | ${input.bootstrapped ? "downloaded this session" : "reused, no network needed"} |`);
   lines.push(`| namespace | ${config.namespace} |`);
   lines.push(`| config layers | ${config.sources.length > 0 ? config.sources.join(", ") : "built-in defaults"} |`);
   lines.push(`| platform | ${input.platformName} (${input.platform}) |`);
   lines.push(`| Poteto Mode | ${input.modeActive ? "active" : "off"} |`);
+  lines.push(`| delegation order | ${delegationOrder(config.delegation).map((backend) => backend.id).join(", then ")} |`);
+  lines.push(`| delegation | ${describeDelegation(input.capabilities)} |`);
   lines.push("");
 
   const warning = trustWarning(source.trust, config);
@@ -81,14 +88,17 @@ export function renderStatus(input: StatusInput): string {
 
   lines.push(`## Model roles`);
   lines.push("");
-  lines.push(`| role | model |`);
-  lines.push(`| --- | --- |`);
-  for (const role of MODEL_ROLES) {
-    lines.push(`| ${role} | ${config.models[role] ?? "inherit (parent session model)"} |`);
-  }
+  lines.push(`| role | model | thinking |`);
+  lines.push(`| --- | --- | --- |`);
   const extra = Object.keys(config.models).filter((role) => !MODEL_ROLES.includes(role)).sort();
-  for (const role of extra) {
-    lines.push(`| ${role} | ${config.models[role]} |`);
+  for (const role of [...MODEL_ROLES, ...extra]) {
+    const configured = config.models[role];
+    if (configured === undefined) {
+      lines.push(`| ${role} | inherit (parent session model) | inherit (parent session thinking) |`);
+      continue;
+    }
+    const spec = splitModelSpec(configured);
+    lines.push(`| ${role} | ${spec.model} | ${spec.thinking ?? "backend default"} |`);
   }
   lines.push("");
 
@@ -124,6 +134,13 @@ export function renderStatus(input: StatusInput): string {
   return lines.join("\n");
 }
 
+function describeDelegation(capabilities: readonly CapabilityStatus[]): string {
+  const backend = capabilities.find((capability) => capability.id === "delegation")?.backend;
+  if (!backend) return "none available";
+  const { label, tool } = DELEGATION_BACKENDS[backend];
+  return `${backend} (${label}, \`${tool}\`)`;
+}
+
 function describeSelection(input: StatusInput): string {
   const { config } = input;
   if (config.localPath) return `local checkout ${config.localPath}`;
@@ -153,6 +170,8 @@ export function renderCheck(
   skill: GeneratedSkill,
   entry: RegistryEntry,
   report: PrerequisiteReport,
+  /** The resolved `delegation` capability, named for a workflow that delegates. */
+  delegation?: CapabilityStatus,
 ): string {
   const parts = [`\`/skill:${skill.generatedName}\` is tier **${skill.tier}**.`];
   if (entry.note) parts.push(entry.note);
@@ -166,12 +185,36 @@ export function renderCheck(
   } else if (skill.tier !== "unsupported") {
     parts.push("Prerequisites satisfied. Start the workflow.");
   }
+  if (skill.capabilities.includes("delegation")) {
+    parts.push(
+      delegation?.backend ? delegationInstruction(delegation.backend, delegation.tools) : "No delegation tool is usable in this session, so do not delegate.",
+    );
+  }
   if (skill.tier === "experimental" && report.ok) {
     parts.push("Tier `experimental` means parts of this workflow have no Pi equivalent. Expect gaps.");
   }
   return parts.join("\n\n");
 }
 
+function delegationInstruction(backend: DelegationProvider, tools: readonly string[] | undefined): string {
+  const { tool, companions } = DELEGATION_BACKENDS[backend];
+  const vetted = tools ?? [tool];
+  const lines = [
+    `Delegate only with \`${tool}\` (${backend}). The adapter resolved this backend for the session, so do not use any other delegation tool.`,
+  ];
+  if (companions.length > 0) {
+    const usable = companions.filter((name) => vetted.includes(name));
+    const unusable = companions.filter((name) => !vetted.includes(name));
+    if (usable.length > 0) lines.push(`You may also call ${usable.map((name) => `\`${name}\``).join(", ")}.`);
+    if (unusable.length > 0) {
+      lines.push(
+        `Do not call ${unusable.map((name) => `\`${name}\``).join(", ")}, even if it is in your tools: the adapter could not confirm it belongs to this backend. Wait for children to report back instead.`,
+      );
+    }
+  }
+  return lines.join(" ");
+}
+
 /** Platforms a release certifies. Windows means native Windows with Pi's Git Bash `bash` tool. */
 export function platformSupport(platform: string): PlatformSupport {
   return platform === "linux" || platform === "darwin" || platform === "win32" ? "supported" : "experimental";

package/src/types.ts

@@ -22,6 +22,9 @@ export type SupportTier =
 
 export type CapabilityId = "delegation" | "structured-question";
 
+/** Where a delegating workflow starts its children. */
+export type DelegationProvider = "t3" | "pi-subagents";
+
 export interface RegistryEntry {
   readonly tier: SupportTier;
   readonly capabilities: readonly CapabilityId[];
@@ -85,6 +88,8 @@ export interface GenerationResult {
   readonly skillsDir: string;
   readonly skills: readonly GeneratedSkill[];
   readonly agents: readonly GeneratedAgent[];
+  /** One `<generatedName>.md` system prompt per agent, for providers without named agents. */
+  readonly agentPromptsDir: string;
   readonly diagnostics: readonly Diagnostic[];
 }
 
@@ -92,6 +97,10 @@ export interface CapabilityStatus {
   readonly id: CapabilityId;
   readonly available: boolean;
   readonly provider?: string;
+  /** The delegation backend that satisfies `delegation`, when one does. */
+  readonly backend?: DelegationProvider;
+  /** Every tool of that backend the adapter vetted: the delegation tool, then its companions. */
+  readonly tools?: readonly string[];
   readonly recommendation: string;
 }
 

package/src/upstream.ts

@@ -1,6 +1,6 @@
 import { execFile } from "node:child_process";
-import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
-import { join, resolve } from "node:path";
+import { existsSync, mkdirSync, readFileSync, realpathSync, rmSync, writeFileSync } from "node:fs";
+import { isAbsolute, join, relative, resolve, sep } from "node:path";
 import { promisify } from "node:util";
 import { MANIFEST_RELATIVE_PATH } from "./manifest.ts";
 import { cacheRoot, checkoutDir, stateFile, validateContainedPath } from "./paths.ts";
@@ -119,17 +119,19 @@ export async function resolveSource(options: ResolveOptions): Promise<ResolvedSo
   const git = options.git ?? systemGit;
   const selection = selectionOf(config);
   const trust = trustOf(config);
+  // Validate before either branch touches the filesystem, so a local checkout cannot be
+  // escaped through the plugin path any more than a Git one can.
+  const pluginPath = validateContainedPath(config.pluginPath, "the upstream plugin path");
 
   if (selection.kind === "local") {
     const checkout = resolve(selection.path);
-    const pluginDir = locatePluginDir(checkout, config.pluginPath);
+    const pluginDir = locatePluginDir(checkout, pluginPath);
     const head = await git(["rev-parse", "HEAD"], checkout);
     return { selection, trust, commit: head.code === 0 ? head.stdout.trim() : "", checkoutDir: checkout, pluginDir };
   }
 
   const repo = validateRepo(config.repo);
   const wanted = validateRef(selection.ref);
-  const pluginPath = validateContainedPath(config.pluginPath, "the upstream plugin path");
   const root = cacheRoot(config.cacheDir);
   const dir = checkoutDir(root, repo);
 
@@ -337,7 +339,19 @@ async function expect(result: Promise<GitResult>, what: string): Promise<GitResu
 
 function locatePluginDir(checkout: string, pluginPath: string): string {
   const nested = join(checkout, pluginPath);
-  if (existsSync(join(nested, MANIFEST_RELATIVE_PATH))) return nested;
+  if (existsSync(join(nested, MANIFEST_RELATIVE_PATH))) {
+    // The plugin path is textually contained, but a symbolic link inside the checkout could
+    // still lead outside it. Compare resolved paths so the link target decides.
+    const root = realpathSync(checkout);
+    const target = realpathSync(nested);
+    const inside = relative(root, target);
+    if (inside === ".." || inside.startsWith(`..${sep}`) || isAbsolute(inside)) {
+      throw new Error(
+        `Refusing the upstream plugin path ${JSON.stringify(pluginPath)}. It resolves to ${target}, outside the checkout ${root}. Point it at a real directory inside the checkout.`,
+      );
+    }
+    return nested;
+  }
   if (existsSync(join(checkout, MANIFEST_RELATIVE_PATH))) return checkout;
   throw new Error(
     `No pstack manifest under ${checkout}. Expected ${join(pluginPath, MANIFEST_RELATIVE_PATH)} or ${MANIFEST_RELATIVE_PATH}.`,