@piagent/platform 1.0.0

package/scripts/configure-mcp.sh

@@ -0,0 +1,301 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+usage() {
+  cat <<'USAGE'
+Usage:
+  scripts/configure-mcp.sh [options]
+
+Purpose:
+  Merge a safe MCP baseline into a standard MCP config file for Pi and other MCP clients.
+  Secrets are never written directly; configs reference environment variables.
+
+Options:
+  --scope <global|pi-global|project|pi-project>
+                                  Config target (default: global)
+  --project <path>                Project path for project/pi-project scopes (default: current directory)
+  --config <path>                 Explicit config path; overrides --scope/--project
+  --preset <minimal|docs|browser|github|design|design-local|web|core|popular|all>
+                                  MCP preset to merge (default: core)
+  --replace                       Replace existing definitions for servers in the preset
+  --dry-run                       Print the merged JSON without writing
+  --list                          Print available presets/servers
+  -h, --help
+
+Recommended presets:
+  core       Context7 docs + Chrome DevTools + GitHub
+  popular    core + Playwright + Figma remote MCP
+  all        popular + Figma desktop/local MCP
+
+Examples:
+  piagent-mcp --preset core --scope global --replace
+  piagent-mcp --preset popular --scope project --project /path/to/repo
+  piagent-mcp --preset design-local --scope project
+
+After writing config:
+  pi
+  /mcp
+  /mcp setup
+  /mcp reconnect
+USAGE
+}
+
+PLATFORM_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+SCOPE="global"
+PROJECT_PATH="$PWD"
+CONFIG_PATH=""
+PRESET="core"
+REPLACE=false
+DRY_RUN=false
+LIST=false
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --scope)
+      SCOPE="${2:-}"
+      shift 2
+      ;;
+    --project)
+      PROJECT_PATH="${2:-}"
+      shift 2
+      ;;
+    --config)
+      CONFIG_PATH="${2:-}"
+      shift 2
+      ;;
+    --preset)
+      PRESET="${2:-}"
+      shift 2
+      ;;
+    --replace)
+      REPLACE=true
+      shift
+      ;;
+    --dry-run)
+      DRY_RUN=true
+      shift
+      ;;
+    --list)
+      LIST=true
+      shift
+      ;;
+    -h|--help)
+      usage
+      exit 0
+      ;;
+    *)
+      echo "Unknown option: $1" >&2
+      usage >&2
+      exit 2
+      ;;
+  esac
+done
+
+if [[ -z "$PRESET" ]]; then
+  echo "FAIL: --preset cannot be empty" >&2
+  exit 2
+fi
+
+if [[ -z "$CONFIG_PATH" ]]; then
+  case "$SCOPE" in
+    global)
+      CONFIG_PATH="${XDG_CONFIG_HOME:-"${HOME}/.config"}/mcp/mcp.json"
+      ;;
+    pi-global)
+      CONFIG_PATH="${PI_CODING_AGENT_DIR:-"${HOME}/.pi/agent"}/mcp.json"
+      ;;
+    project)
+      CONFIG_PATH="$PROJECT_PATH/.mcp.json"
+      ;;
+    pi-project)
+      CONFIG_PATH="$PROJECT_PATH/.pi/mcp.json"
+      ;;
+    *)
+      echo "FAIL: unsupported scope: $SCOPE" >&2
+      usage >&2
+      exit 2
+      ;;
+  esac
+fi
+
+node --input-type=module - "$CONFIG_PATH" "$PRESET" "$REPLACE" "$DRY_RUN" "$LIST" <<'NODE'
+import fs from "node:fs";
+import path from "node:path";
+
+const [configPath, presetName, replaceRaw, dryRunRaw, listRaw] = process.argv.slice(2);
+const replace = replaceRaw === "true";
+const dryRun = dryRunRaw === "true";
+const listOnly = listRaw === "true";
+
+const baselineSettings = {
+  toolPrefix: "server",
+  directTools: false,
+  idleTimeout: 10,
+  outputGuard: true
+};
+
+const servers = {
+  context7: {
+    description: "Official Context7 MCP server for up-to-date library/framework docs.",
+    config: {
+      command: "npx",
+      args: ["-y", "@upstash/context7-mcp@3.2.4"],
+      env: {
+        CONTEXT7_API_KEY: "${CONTEXT7_API_KEY}"
+      },
+      lifecycle: "lazy",
+      directTools: false
+    }
+  },
+  "chrome-devtools": {
+    description: "Chrome DevTools MCP for runtime browser inspection, console logs, screenshots, and performance checks.",
+    config: {
+      command: "npx",
+      args: ["-y", "chrome-devtools-mcp@1.6.0", "--no-performance-crux"],
+      env: {
+        CHROME_DEVTOOLS_MCP_NO_USAGE_STATISTICS: "1",
+        CHROME_DEVTOOLS_MCP_NO_UPDATE_CHECKS: "1"
+      },
+      lifecycle: "lazy",
+      directTools: false
+    }
+  },
+  playwright: {
+    description: "Playwright MCP for browser automation and UI verification workflows.",
+    config: {
+      command: "npx",
+      args: ["-y", "@playwright/mcp@0.0.78"],
+      lifecycle: "lazy",
+      directTools: false
+    }
+  },
+  github: {
+    description: "Official GitHub MCP server via Docker. Requires Docker and GITHUB_PERSONAL_ACCESS_TOKEN when used.",
+    config: {
+      command: "docker",
+      args: [
+        "run",
+        "-i",
+        "--rm",
+        "-e",
+        "GITHUB_PERSONAL_ACCESS_TOKEN",
+        "-e",
+        "GITHUB_READ_ONLY=1",
+        "-e",
+        "GITHUB_LOCKDOWN_MODE=1",
+        "ghcr.io/github/github-mcp-server@sha256:2b0c48b070f61e9d3969269ead600f62d00fb237b60ac849ef3d166ee7de9ad3"
+      ],
+      env: {
+        GITHUB_PERSONAL_ACCESS_TOKEN: "${GITHUB_PERSONAL_ACCESS_TOKEN}"
+      },
+      lifecycle: "lazy",
+      directTools: false
+    }
+  },
+  figma: {
+    description: "Figma remote MCP server. Requires Figma OAuth from the MCP panel when first used.",
+    config: {
+      url: "https://mcp.figma.com/mcp",
+      auth: "oauth",
+      lifecycle: "lazy",
+      directTools: false
+    }
+  },
+  "figma-desktop": {
+    description: "Figma desktop/local MCP server. Requires Figma desktop Dev Mode MCP enabled.",
+    config: {
+      url: "http://127.0.0.1:3845/mcp",
+      lifecycle: "lazy",
+      directTools: false
+    }
+  }
+};
+
+const presets = {
+  minimal: [],
+  docs: ["context7"],
+  browser: ["chrome-devtools", "playwright"],
+  github: ["github"],
+  design: ["figma"],
+  "design-local": ["figma-desktop"],
+  web: ["context7", "chrome-devtools", "playwright"],
+  core: ["context7", "chrome-devtools", "github"],
+  popular: ["context7", "chrome-devtools", "playwright", "github", "figma"],
+  all: ["context7", "chrome-devtools", "playwright", "github", "figma", "figma-desktop"]
+};
+
+if (listOnly) {
+  console.log(JSON.stringify({
+    presets,
+    servers: Object.fromEntries(Object.entries(servers).map(([name, value]) => [name, value.description]))
+  }, null, 2));
+  process.exit(0);
+}
+
+if (!Object.hasOwn(presets, presetName)) {
+  console.error(`FAIL: unknown preset: ${presetName}`);
+  console.error(`Available presets: ${Object.keys(presets).join(", ")}`);
+  process.exit(2);
+}
+
+let current = {};
+if (fs.existsSync(configPath)) {
+  try {
+    current = JSON.parse(fs.readFileSync(configPath, "utf8"));
+  } catch (error) {
+    console.error(`FAIL: cannot parse existing MCP config: ${configPath}`);
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exit(1);
+  }
+}
+
+if (!current || typeof current !== "object" || Array.isArray(current)) current = {};
+if (!current.settings || typeof current.settings !== "object" || Array.isArray(current.settings)) current.settings = {};
+if (!current.mcpServers || typeof current.mcpServers !== "object" || Array.isArray(current.mcpServers)) current.mcpServers = {};
+
+current.settings = {
+  ...baselineSettings,
+  ...current.settings
+};
+
+const added = [];
+const kept = [];
+const replaced = [];
+for (const name of presets[presetName]) {
+  if (!Object.hasOwn(servers, name)) {
+    throw new Error(`Preset ${presetName} references missing server ${name}`);
+  }
+  if (Object.hasOwn(current.mcpServers, name)) {
+    if (replace) {
+      current.mcpServers[name] = servers[name].config;
+      replaced.push(name);
+    } else {
+      kept.push(name);
+    }
+  } else {
+    current.mcpServers[name] = servers[name].config;
+    added.push(name);
+  }
+}
+
+const output = `${JSON.stringify(current, null, 2)}\n`;
+const report = {
+  configPath,
+  preset: presetName,
+  dryRun,
+  replace,
+  added,
+  kept,
+  replaced,
+  serverCount: Object.keys(current.mcpServers).length
+};
+
+if (dryRun) {
+  console.log(JSON.stringify(report, null, 2));
+  console.log(output);
+} else {
+  fs.mkdirSync(path.dirname(configPath), { recursive: true });
+  fs.writeFileSync(configPath, output);
+  console.log(JSON.stringify(report, null, 2));
+}
+NODE

package/scripts/configure-model-scope.sh

@@ -0,0 +1,143 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+usage() {
+  cat <<'USAGE'
+Usage:
+  scripts/configure-model-scope.sh [options]
+
+Options:
+  --preset <full|codex|claude>       Model scope to write (default: full)
+  --default-model <provider/model[:thinking]>
+                                     Default model (default: openai-codex/gpt-5.5:xhigh)
+  --settings <path>                  Pi settings file (default: ~/.pi/agent/settings.json)
+  --dry-run                          Print resulting settings JSON without writing
+  -h, --help
+
+Purpose:
+  Configure Pi's native model selector/cycling settings:
+  - defaultProvider
+  - defaultModel
+  - defaultThinkingLevel
+  - enabledModels
+
+After this, users select models with Pi's built-in UI:
+  /model or Ctrl+L       selector
+  /scoped-models         edit cycling scope
+  Ctrl+P                 cycle scoped models
+  Shift+Tab              cycle thinking level
+USAGE
+}
+
+PRESET="full"
+DEFAULT_MODEL="openai-codex/gpt-5.5:xhigh"
+SETTINGS_PATH="${PI_CODING_AGENT_DIR:-"${HOME}/.pi/agent"}/settings.json"
+DRY_RUN=false
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --preset)
+      PRESET="${2:-}"
+      shift 2
+      ;;
+    --default-model)
+      DEFAULT_MODEL="${2:-}"
+      shift 2
+      ;;
+    --settings)
+      SETTINGS_PATH="${2:-}"
+      shift 2
+      ;;
+    --dry-run)
+      DRY_RUN=true
+      shift
+      ;;
+    -h|--help)
+      usage
+      exit 0
+      ;;
+    *)
+      echo "Unknown argument: $1" >&2
+      usage >&2
+      exit 2
+      ;;
+  esac
+done
+
+case "$PRESET" in
+  full|codex|claude) ;;
+  *)
+    echo "FAIL: --preset must be full, codex, or claude" >&2
+    exit 2
+    ;;
+esac
+
+node --input-type=module - "$SETTINGS_PATH" "$PRESET" "$DEFAULT_MODEL" "$DRY_RUN" <<'NODE'
+import fs from "node:fs";
+import path from "node:path";
+
+const [settingsPath, preset, defaultModelInput, dryRunRaw] = process.argv.slice(2);
+const dryRun = dryRunRaw === "true";
+
+const codexModels = [
+  "openai-codex/gpt-5.3-codex-spark:minimal",
+  "openai-codex/gpt-5.4-mini:minimal",
+  "openai-codex/gpt-5.4:xhigh",
+  "openai-codex/gpt-5.5:xhigh",
+  "openai-codex/gpt-5.6-luna:xhigh",
+  "openai-codex/gpt-5.6-sol:xhigh",
+  "openai-codex/gpt-5.6-terra:xhigh"
+];
+
+const claudeModels = [
+  "anthropic/claude-haiku-4-5:low",
+  "anthropic/claude-sonnet-4-5:high",
+  "anthropic/claude-sonnet-4-6:max",
+  "anthropic/claude-sonnet-5:xhigh",
+  "anthropic/claude-opus-4-5:xhigh",
+  "anthropic/claude-opus-4-6:max",
+  "anthropic/claude-opus-4-7:xhigh",
+  "anthropic/claude-opus-4-8:xhigh",
+  "anthropic/claude-fable-5:xhigh"
+];
+
+const enabledModels = preset === "codex"
+  ? codexModels
+  : preset === "claude"
+    ? claudeModels
+    : [...codexModels, ...claudeModels];
+
+function parseDefaultModel(input) {
+  const match = input.match(/^([^/]+)\/([^:]+)(?::(.+))?$/);
+  if (!match) {
+    throw new Error(`--default-model must look like provider/model[:thinking], got: ${input}`);
+  }
+  return {
+    provider: match[1],
+    model: match[2],
+    thinking: match[3] || "xhigh"
+  };
+}
+
+const parsedDefault = parseDefaultModel(defaultModelInput);
+const settings = fs.existsSync(settingsPath)
+  ? JSON.parse(fs.readFileSync(settingsPath, "utf8"))
+  : {};
+
+settings.defaultProvider = parsedDefault.provider;
+settings.defaultModel = parsedDefault.model;
+settings.defaultThinkingLevel = parsedDefault.thinking;
+settings.enabledModels = enabledModels;
+
+const output = `${JSON.stringify(settings, null, 2)}\n`;
+if (dryRun) {
+  process.stdout.write(output);
+} else {
+  fs.mkdirSync(path.dirname(settingsPath), { recursive: true });
+  fs.writeFileSync(settingsPath, output);
+  console.log(`Configured Pi model scope: ${settingsPath}`);
+  console.log(`  preset: ${preset}`);
+  console.log(`  default: ${parsedDefault.provider}/${parsedDefault.model}:${parsedDefault.thinking}`);
+  console.log(`  enabledModels: ${enabledModels.length}`);
+}
+NODE

package/scripts/configure-subagents.sh

@@ -0,0 +1,241 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+usage() {
+  cat <<'USAGE'
+Usage:
+  scripts/configure-subagents.sh [options]
+
+Purpose:
+  Configure pi-subagents with a safe, token-conscious baseline.
+
+Options:
+  --preset <minimal|safe|async|parallel>
+                                  Runtime preset (default: safe)
+  --config <path>                 Subagent config path (default: ~/.pi/agent/extensions/subagent/config.json)
+  --settings <path>               Pi settings path (default: ~/.pi/agent/settings.json)
+  --model-scope <none|piagent|codex|claude>
+                                  Optional subagent model allowlist written to settings (default: none)
+  --dry-run                       Print merged config/settings summary without writing
+  --list                          Print available presets
+  -h, --help
+
+Recommended:
+  piagent-subagents --preset safe
+
+After installing/configuring:
+  pi
+  /subagents-doctor
+  /subagents-models
+  /run scout "Map the auth flow"
+USAGE
+}
+
+PRESET="safe"
+CONFIG_PATH="${PI_CODING_AGENT_DIR:-"${HOME}/.pi/agent"}/extensions/subagent/config.json"
+SETTINGS_PATH="${PI_CODING_AGENT_DIR:-"${HOME}/.pi/agent"}/settings.json"
+MODEL_SCOPE="none"
+DRY_RUN=false
+LIST=false
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --preset)
+      PRESET="${2:-}"
+      shift 2
+      ;;
+    --config)
+      CONFIG_PATH="${2:-}"
+      shift 2
+      ;;
+    --settings)
+      SETTINGS_PATH="${2:-}"
+      shift 2
+      ;;
+    --model-scope)
+      MODEL_SCOPE="${2:-}"
+      shift 2
+      ;;
+    --dry-run)
+      DRY_RUN=true
+      shift
+      ;;
+    --list)
+      LIST=true
+      shift
+      ;;
+    -h|--help)
+      usage
+      exit 0
+      ;;
+    *)
+      echo "Unknown option: $1" >&2
+      usage >&2
+      exit 2
+      ;;
+  esac
+done
+
+node --input-type=module - "$CONFIG_PATH" "$SETTINGS_PATH" "$PRESET" "$MODEL_SCOPE" "$DRY_RUN" "$LIST" <<'NODE'
+import fs from "node:fs";
+import path from "node:path";
+
+const [configPath, settingsPath, presetName, modelScopeName, dryRunRaw, listRaw] = process.argv.slice(2);
+const dryRun = dryRunRaw === "true";
+const listOnly = listRaw === "true";
+
+const presets = {
+  minimal: {
+    toolDescriptionMode: "compact",
+    asyncByDefault: false,
+    asyncWidget: true,
+    forceTopLevelAsync: false,
+    waitTool: { enabled: true },
+    intercomBridge: { mode: "always" },
+    globalConcurrencyLimit: 4,
+    maxSubagentSpawnsPerSession: 16,
+    maxSubagentDepth: 1,
+    defaultSessionDir: "~/.pi/agent/sessions/subagent",
+    singleRunOutputBaseDir: "~/.pi/agent/subagent-outputs",
+    worktreeBaseDir: "~/.pi/agent/worktrees/pi-subagents",
+    scheduledRuns: { enabled: false, maxPending: 20, maxLatenessMs: 300000 },
+    parallel: { maxTasks: 4, concurrency: 2 },
+    completionBatch: { enabled: true, debounceMs: 150, maxWaitMs: 1000 }
+  },
+  safe: {
+    toolDescriptionMode: "compact",
+    asyncByDefault: false,
+    asyncWidget: true,
+    forceTopLevelAsync: false,
+    waitTool: { enabled: true },
+    intercomBridge: { mode: "always" },
+    globalConcurrencyLimit: 8,
+    maxSubagentSpawnsPerSession: 32,
+    maxSubagentDepth: 1,
+    defaultSessionDir: "~/.pi/agent/sessions/subagent",
+    singleRunOutputBaseDir: "~/.pi/agent/subagent-outputs",
+    worktreeBaseDir: "~/.pi/agent/worktrees/pi-subagents",
+    scheduledRuns: { enabled: false, maxPending: 20, maxLatenessMs: 300000 },
+    parallel: { maxTasks: 6, concurrency: 3 },
+    completionBatch: { enabled: true, debounceMs: 150, maxWaitMs: 1000, stragglerDebounceMs: 75, stragglerMaxWaitMs: 400, stragglerWindowMs: 2000 }
+  },
+  async: {
+    toolDescriptionMode: "compact",
+    asyncByDefault: true,
+    asyncWidget: true,
+    forceTopLevelAsync: false,
+    waitTool: { enabled: true },
+    intercomBridge: { mode: "always" },
+    globalConcurrencyLimit: 8,
+    maxSubagentSpawnsPerSession: 32,
+    maxSubagentDepth: 1,
+    defaultSessionDir: "~/.pi/agent/sessions/subagent",
+    singleRunOutputBaseDir: "~/.pi/agent/subagent-outputs",
+    worktreeBaseDir: "~/.pi/agent/worktrees/pi-subagents",
+    scheduledRuns: { enabled: false, maxPending: 20, maxLatenessMs: 300000 },
+    parallel: { maxTasks: 6, concurrency: 3 },
+    completionBatch: { enabled: true, debounceMs: 150, maxWaitMs: 1000, stragglerDebounceMs: 75, stragglerMaxWaitMs: 400, stragglerWindowMs: 2000 }
+  },
+  parallel: {
+    toolDescriptionMode: "compact",
+    asyncByDefault: false,
+    asyncWidget: true,
+    forceTopLevelAsync: false,
+    waitTool: { enabled: true },
+    intercomBridge: { mode: "always" },
+    globalConcurrencyLimit: 12,
+    maxSubagentSpawnsPerSession: 64,
+    maxSubagentDepth: 1,
+    defaultSessionDir: "~/.pi/agent/sessions/subagent",
+    singleRunOutputBaseDir: "~/.pi/agent/subagent-outputs",
+    worktreeBaseDir: "~/.pi/agent/worktrees/pi-subagents",
+    scheduledRuns: { enabled: false, maxPending: 20, maxLatenessMs: 300000 },
+    parallel: { maxTasks: 10, concurrency: 5 },
+    completionBatch: { enabled: true, debounceMs: 150, maxWaitMs: 1000, stragglerDebounceMs: 75, stragglerMaxWaitMs: 400, stragglerWindowMs: 2000 }
+  }
+};
+
+const modelScopes = {
+  none: null,
+  piagent: { enforce: true, allow: ["openai-codex/*", "anthropic/*"] },
+  codex: { enforce: true, allow: ["openai-codex/*"] },
+  claude: { enforce: true, allow: ["anthropic/*"] }
+};
+
+if (listOnly) {
+  console.log(JSON.stringify({
+    presets: Object.keys(presets),
+    modelScopes
+  }, null, 2));
+  process.exit(0);
+}
+
+if (!Object.hasOwn(presets, presetName)) {
+  console.error(`FAIL: unknown preset: ${presetName}`);
+  console.error(`Available presets: ${Object.keys(presets).join(", ")}`);
+  process.exit(2);
+}
+
+if (!Object.hasOwn(modelScopes, modelScopeName)) {
+  console.error(`FAIL: unknown model scope: ${modelScopeName}`);
+  console.error(`Available model scopes: ${Object.keys(modelScopes).join(", ")}`);
+  process.exit(2);
+}
+
+function readJson(file, fallback) {
+  if (!fs.existsSync(file)) return structuredClone(fallback);
+  try {
+    return JSON.parse(fs.readFileSync(file, "utf8"));
+  } catch (error) {
+    console.error(`FAIL: cannot parse JSON: ${file}`);
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exit(1);
+  }
+}
+
+function mergeObject(base, patch) {
+  const out = { ...base };
+  for (const [key, value] of Object.entries(patch)) {
+    if (value && typeof value === "object" && !Array.isArray(value) && base[key] && typeof base[key] === "object" && !Array.isArray(base[key])) {
+      out[key] = mergeObject(base[key], value);
+    } else {
+      out[key] = value;
+    }
+  }
+  return out;
+}
+
+const existingConfig = readJson(configPath, {});
+const mergedConfig = mergeObject(existingConfig && typeof existingConfig === "object" && !Array.isArray(existingConfig) ? existingConfig : {}, presets[presetName]);
+
+const existingSettings = readJson(settingsPath, {});
+const mergedSettings = existingSettings && typeof existingSettings === "object" && !Array.isArray(existingSettings) ? existingSettings : {};
+if (modelScopes[modelScopeName]) {
+  mergedSettings.subagents = mergedSettings.subagents && typeof mergedSettings.subagents === "object" && !Array.isArray(mergedSettings.subagents)
+    ? mergedSettings.subagents
+    : {};
+  mergedSettings.subagents.modelScope = modelScopes[modelScopeName];
+}
+
+const report = {
+  preset: presetName,
+  configPath,
+  settingsPath,
+  modelScope: modelScopeName,
+  dryRun,
+  config: mergedConfig,
+  settingsSubagents: mergedSettings.subagents ?? null
+};
+
+if (dryRun) {
+  console.log(JSON.stringify(report, null, 2));
+} else {
+  fs.mkdirSync(path.dirname(configPath), { recursive: true });
+  fs.writeFileSync(configPath, `${JSON.stringify(mergedConfig, null, 2)}\n`);
+  if (modelScopes[modelScopeName]) {
+    fs.mkdirSync(path.dirname(settingsPath), { recursive: true });
+    fs.writeFileSync(settingsPath, `${JSON.stringify(mergedSettings, null, 2)}\n`);
+  }
+  console.log(JSON.stringify(report, null, 2));
+}
+NODE