pi-pstack-adapter 0.3.0 → 0.4.0

package/src/capabilities.ts

@@ -1,9 +1,18 @@
-import type { CapabilityId, CapabilityStatus } from "./types.ts";
+import {
+  DEFAULT_DELEGATION,
+  type DelegationHost,
+  callableTool,
+  delegationHost,
+  parameterNames,
+  resolveDelegation,
+} from "./delegation.ts";
+import type { CapabilityId, CapabilityStatus, DelegationProvider } from "./types.ts";
 
 export interface ToolDescriptor {
   readonly name: string;
+  readonly exposure?: string;
   readonly parameters?: unknown;
-  readonly sourceInfo?: { readonly source?: string };
+  readonly sourceInfo?: { readonly source?: string; readonly path?: string };
 }
 
 interface CapabilityProbe {
@@ -14,13 +23,10 @@ interface CapabilityProbe {
   readonly recommendation: string;
 }
 
+const DELEGATION_RECOMMENDATION =
+  "Run Pi inside T3 Code, whose `delegate_task` tool starts child agents, or install a delegation provider with named background agents and model selection, for example `pi install npm:pi-subagents`.";
+
 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",
@@ -29,31 +35,50 @@ const PROBES: readonly CapabilityProbe[] = [
   },
 ];
 
-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 };
-  });
+export function detectCapabilities(
+  tools: readonly ToolDescriptor[],
+  preferred: DelegationProvider = DEFAULT_DELEGATION,
+  host: DelegationHost = delegationHost(),
+): CapabilityStatus[] {
+  return [detectDelegation(tools, preferred, host), ...PROBES.map((probe) => detectTool(tools, probe))];
 }
 
-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>));
+/** The first usable backend in preference order satisfies `delegation`. */
+function detectDelegation(
+  tools: readonly ToolDescriptor[],
+  preferred: DelegationProvider,
+  host: DelegationHost,
+): CapabilityStatus {
+  const resolution = resolveDelegation(tools, preferred, host);
+  if (resolution.kind === "unavailable") {
+    return { id: "delegation", available: false, recommendation: [...resolution.problems, DELEGATION_RECOMMENDATION].join(" ") };
+  }
+  return {
+    id: "delegation",
+    available: true,
+    provider: resolution.backend.id === "t3" ? resolution.backend.label : resolution.tool.sourceInfo?.source ?? resolution.backend.label,
+    backend: resolution.backend.id,
+    tools: [resolution.backend.tool, ...resolution.companions],
+    recommendation: DELEGATION_RECOMMENDATION,
+  };
+}
+
+function detectTool(tools: readonly ToolDescriptor[], probe: CapabilityProbe): CapabilityStatus {
+  const tool = callableTool(tools, 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 };
 }
 
 export interface PrerequisiteReport {

package/src/certified.ts

@@ -5,9 +5,9 @@
 export const CERTIFIED = {
   repo: "https://github.com/cursor/plugins",
   ref: "main",
-  commit: "e43c7ee26e0038c6c1fa8380dd34ce86ff94cb2a",
+  commit: "dbf49813a39c1a5389c5e28cb8e4c1c2379e2454",
   pluginPath: "pstack",
-  pstackVersion: "0.15.9",
-  skillCount: 50,
+  pstackVersion: "0.15.23",
+  skillCount: 53,
   agentCount: 2,
 } as const;

package/src/config.ts

@@ -3,7 +3,8 @@ 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";
+import { DEFAULT_DELEGATION, DELEGATION_PROVIDERS, isDelegationProvider } from "./delegation.ts";
+import type { DelegationProvider, SourceSelection, Trust } from "./types.ts";
 
 export interface AdapterConfig {
   readonly namespace: string;
@@ -17,6 +18,8 @@ export interface AdapterConfig {
   readonly allowBootstrap: boolean;
   readonly cacheDir?: string;
   readonly models: Readonly<Record<string, string>>;
+  /** The delegation backend tried first. The other one is the fallback. */
+  readonly delegation: DelegationProvider;
   readonly sources: readonly string[];
 }
 
@@ -30,6 +33,7 @@ export interface ConfigFile {
   allowBootstrap?: boolean;
   cacheDir?: string;
   models?: Record<string, string>;
+  delegation?: string;
 }
 
 export interface ConfigLayer {
@@ -49,6 +53,7 @@ const ENV = {
   allowBootstrap: "PISTACK_ALLOW_BOOTSTRAP",
   cacheDir: "PISTACK_CACHE_DIR",
   models: "PISTACK_MODELS",
+  delegation: "PISTACK_DELEGATION",
 } as const;
 
 export function readConfigFile(path: string): ConfigLayer | undefined {
@@ -107,6 +112,7 @@ export function environmentLayer(env: NodeJS.ProcessEnv): ConfigLayer {
   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);
+  if (env[ENV.delegation]) values.delegation = (env[ENV.delegation] as string).trim().toLowerCase();
   return { label: "environment", values };
 }
 
@@ -151,6 +157,7 @@ export function mergeConfig(layers: readonly ConfigLayer[]): AdapterConfig {
     allowBootstrap: merged.allowBootstrap ?? false,
     cacheDir: merged.cacheDir,
     models: merged.models ?? {},
+    delegation: validateDelegation(merged.delegation, layers),
     sources,
   };
 }
@@ -167,6 +174,15 @@ function resolvePin(merged: ConfigFile): string | undefined {
   return CERTIFIED.commit;
 }
 
+function validateDelegation(value: string | undefined, layers: readonly ConfigLayer[]): DelegationProvider {
+  if (value === undefined) return DEFAULT_DELEGATION;
+  if (isDelegationProvider(value)) return value;
+  const owner = [...layers].reverse().find((layer) => layer.values.delegation === value);
+  throw new Error(
+    `${owner?.label ?? "config"} sets \`delegation\` to ${JSON.stringify(value)}. Use one of ${DELEGATION_PROVIDERS.map((id) => `"${id}"`).join(", ")}, or remove it to prefer "${DEFAULT_DELEGATION}".`,
+  );
+}
+
 function resolveLayerPath(value: string, layers: readonly ConfigLayer[]): string {
   const expanded = expandHome(value);
   if (isAbsolute(expanded)) return expanded;

package/src/delegation.ts

@@ -0,0 +1,143 @@
+import { posix, win32 } from "node:path";
+import type { DelegationProvider } from "./types.ts";
+
+/** T3 Code sets this to the path of the Pi extension that owns the `mcp__t3-code__` tools. */
+export const T3_BRIDGE_ENV = "T3_PI_MCP_EXTENSION_PATH";
+
+/** The pi-subagents tool a delegation skill calls. */
+export const SUBAGENT_TOOL = "subagent";
+/** The pi-subagents loader that exposes a registered but inactive `subagent` tool. */
+export const SUBAGENT_LOADER = "subagents_enable";
+
+/**
+ * T3 Code's Pi bridge registers its MCP tools under this public prefix. It also registers a
+ * `mcp__t3_code__` copy with hidden exposure to reserve the name, which the model cannot call.
+ */
+export const T3_TOOL_PREFIX = "mcp__t3-code__";
+export const T3_DELEGATE_TOOL = `${T3_TOOL_PREFIX}delegate_task`;
+export const T3_STATUS_TOOL = `${T3_TOOL_PREFIX}task_status`;
+export const T3_CAPABILITIES_TOOL = `${T3_TOOL_PREFIX}orchestrator_capabilities`;
+
+export interface DelegationBackend {
+  readonly id: DelegationProvider;
+  readonly label: string;
+  /** The tool that starts a child. Its presence decides whether the backend exists. */
+  readonly tool: string;
+  /** Tools a delegating workflow also needs, activated alongside `tool` when registered. */
+  readonly companions: readonly string[];
+  /** Parameter names `tool` must accept for the backend to be usable. */
+  readonly requiredParameters: readonly string[];
+}
+
+export const DELEGATION_BACKENDS: Readonly<Record<DelegationProvider, DelegationBackend>> = {
+  "t3": {
+    id: "t3",
+    label: "T3 Code",
+    tool: T3_DELEGATE_TOOL,
+    companions: [T3_CAPABILITIES_TOOL, T3_STATUS_TOOL],
+    requiredParameters: ["task", "target", "mode"],
+  },
+  "pi-subagents": {
+    id: "pi-subagents",
+    label: "pi-subagents",
+    tool: SUBAGENT_TOOL,
+    companions: [],
+    requiredParameters: ["agent", "task", "async", "model"],
+  },
+};
+
+export const DELEGATION_PROVIDERS: readonly DelegationProvider[] = ["t3", "pi-subagents"];
+export const DEFAULT_DELEGATION: DelegationProvider = "t3";
+
+export function isDelegationProvider(value: unknown): value is DelegationProvider {
+  return typeof value === "string" && (DELEGATION_PROVIDERS as readonly string[]).includes(value);
+}
+
+/** The preferred backend first, then the fallback. */
+export function delegationOrder(preferred: DelegationProvider): readonly DelegationBackend[] {
+  return [preferred, ...DELEGATION_PROVIDERS.filter((id) => id !== preferred)].map((id) => DELEGATION_BACKENDS[id]);
+}
+
+export interface ToolPresence {
+  readonly name: string;
+  readonly exposure?: string;
+  readonly parameters?: unknown;
+  readonly sourceInfo?: { readonly source?: string; readonly path?: string };
+}
+
+/** A hidden registration only reserves a name, so it does not count as a callable tool. */
+export function callableTool<T extends ToolPresence>(tools: readonly T[], name: string): T | undefined {
+  return tools.find((tool) => tool.name === name && tool.exposure !== "hidden");
+}
+
+export interface DelegationHost {
+  /** `T3_PI_MCP_EXTENSION_PATH`, set only when T3 Code launched this Pi process. */
+  readonly t3BridgePath?: string;
+  readonly platform?: NodeJS.Platform;
+}
+
+export function delegationHost(env: NodeJS.ProcessEnv = process.env): DelegationHost {
+  return { t3BridgePath: env[T3_BRIDGE_ENV] || undefined, platform: process.platform };
+}
+
+export type DelegationResolution =
+  | {
+      readonly kind: "resolved";
+      readonly backend: DelegationBackend;
+      readonly tool: ToolPresence;
+      /** Companion tools that pass the same ownership check as `tool`. */
+      readonly companions: readonly string[];
+    }
+  | { readonly kind: "unavailable"; readonly problems: readonly string[] };
+
+/**
+ * The first usable backend in preference order. Detection and activation both use this, so the
+ * status report always names the backend a workflow actually gets. A T3 tool counts only when
+ * T3 Code's own bridge registered it, because any extension or MCP server can claim the name.
+ */
+export function resolveDelegation(
+  tools: readonly ToolPresence[],
+  preferred: DelegationProvider,
+  host: DelegationHost,
+): DelegationResolution {
+  const problems: string[] = [];
+  for (const backend of delegationOrder(preferred)) {
+    const tool = callableTool(tools, backend.tool);
+    if (!tool) continue;
+    if (backend.id === "t3" && !fromT3Bridge(tool, host)) {
+      problems.push(
+        `The \`${backend.tool}\` tool was not registered by T3 Code's bridge, so the adapter ignores it. T3 Code sets ${T3_BRIDGE_ENV} to the bridge it launches.`,
+      );
+      continue;
+    }
+    const properties = parameterNames(tool.parameters);
+    const missing = backend.requiredParameters.filter((name) => !properties.has(name));
+    if (missing.length > 0) {
+      problems.push(`The \`${backend.tool}\` tool is present but does not accept ${missing.join(", ")}.`);
+      continue;
+    }
+    const companions = backend.companions.filter((name) => {
+      const companion = callableTool(tools, name);
+      return companion !== undefined && (backend.id !== "t3" || fromT3Bridge(companion, host));
+    });
+    return { kind: "resolved", backend, tool, companions };
+  }
+  return { kind: "unavailable", problems };
+}
+
+function fromT3Bridge(tool: ToolPresence, host: DelegationHost): boolean {
+  const owner = tool.sourceInfo?.path;
+  if (!host.t3BridgePath || !owner) return false;
+  const platform = host.platform ?? process.platform;
+  const paths = platform === "win32" ? win32 : posix;
+  // Windows paths are case-insensitive, so compare them after resolving both sides.
+  const key = (value: string) => (platform === "win32" ? paths.resolve(value).toLowerCase() : paths.resolve(value));
+  return key(owner) === key(host.t3BridgePath);
+}
+
+export 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>));
+}