@piagent/platform 1.0.0

package/schemas/task-contract.schema.json

@@ -0,0 +1,314 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/Vt-mmm/piagent/schemas/task-contract.schema.json",
+  "title": "Pi Agent Task Implementation Contract",
+  "type": "object",
+  "required": [
+    "taskId",
+    "summary",
+    "riskLane",
+    "expectedOutput",
+    "acceptanceCriteria",
+    "scope",
+    "outOfScope",
+    "protectedPaths",
+    "requiredContext",
+    "contextManifest",
+    "memoryCitations",
+    "verifyCommands",
+    "changedFiles",
+    "verifyEvidence",
+    "trace"
+  ],
+  "properties": {
+    "taskId": {
+      "type": "string",
+      "minLength": 1
+    },
+    "summary": {
+      "type": "string",
+      "minLength": 10
+    },
+    "riskLane": {
+      "enum": [
+        "tiny",
+        "normal",
+        "high-risk"
+      ]
+    },
+    "expectedOutput": {
+      "type": "string",
+      "minLength": 10
+    },
+    "acceptanceCriteria": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "minLength": 1
+      },
+      "minItems": 1
+    },
+    "scope": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "minLength": 1
+      },
+      "minItems": 1
+    },
+    "outOfScope": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "minLength": 1
+      }
+    },
+    "protectedPaths": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "minLength": 1
+      }
+    },
+    "requiredContext": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "minLength": 1
+      }
+    },
+    "contextManifest": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": [
+          "path",
+          "reason"
+        ],
+        "properties": {
+          "path": {
+            "type": "string"
+          },
+          "reason": {
+            "type": "string"
+          }
+        },
+        "additionalProperties": true
+      }
+    },
+    "memoryCitations": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": [
+          "path",
+          "reason"
+        ],
+        "properties": {
+          "path": {
+            "type": "string",
+            "minLength": 1
+          },
+          "reason": {
+            "type": "string",
+            "minLength": 1
+          }
+        },
+        "additionalProperties": false
+      }
+    },
+    "mcpCapabilities": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "verifyCommands": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "minLength": 1
+      }
+    },
+    "workPlan": {
+      "type": "array",
+      "description": "Optional solo-first task tree for parent/subagent coordination.",
+      "maxItems": 12,
+      "items": {
+        "type": "object",
+        "required": [
+          "id",
+          "title",
+          "role",
+          "mode",
+          "status"
+        ],
+        "properties": {
+          "id": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 40
+          },
+          "title": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 160
+          },
+          "role": {
+            "enum": [
+              "parent",
+              "piagent-scout",
+              "piagent-planner",
+              "piagent-worker",
+              "piagent-reviewer",
+              "piagent-oracle"
+            ]
+          },
+          "mode": {
+            "enum": [
+              "read-only",
+              "single-writer",
+              "review"
+            ]
+          },
+          "status": {
+            "enum": [
+              "pending",
+              "in-progress",
+              "done",
+              "skipped"
+            ]
+          },
+          "dependsOn": {
+            "type": "array",
+            "items": {
+              "type": "string",
+              "minLength": 1,
+              "maxLength": 40
+            }
+          }
+        },
+        "additionalProperties": false
+      }
+    },
+    "reviewLenses": {
+      "type": "array",
+      "description": "Explicit review lenses for the task, used instead of blanket swarm review.",
+      "uniqueItems": true,
+      "items": {
+        "enum": [
+          "correctness",
+          "tests",
+          "scope",
+          "security",
+          "docs",
+          "release",
+          "package"
+        ]
+      }
+    },
+    "orchestration": {
+      "type": "object",
+      "description": "Resolved solo-first orchestration policy captured when the task starts.",
+      "properties": {
+        "mode": {
+          "enum": [
+            "solo-first",
+            "bounded-subagents",
+            "parallel-readonly"
+          ]
+        },
+        "subagents": {
+          "enum": [
+            "not-used",
+            "optional",
+            "used"
+          ]
+        },
+        "reason": {
+          "type": "string",
+          "minLength": 1
+        },
+        "fieldGuidePath": {
+          "type": "string",
+          "minLength": 1
+        },
+        "modelRoles": {
+          "type": "object",
+          "properties": {
+            "planner": { "type": "string" },
+            "worker": { "type": "string" },
+            "reviewer": { "type": "string" },
+            "watchdog": { "type": "string" }
+          },
+          "additionalProperties": false
+        }
+      },
+      "additionalProperties": false
+    },
+    "changedFiles": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "verifyEvidence": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": [
+          "command",
+          "exitCode",
+          "summary"
+        ],
+        "properties": {
+          "command": {
+            "type": "string"
+          },
+          "exitCode": {
+            "type": "integer"
+          },
+          "summary": {
+            "type": "string"
+          },
+          "observed": {
+            "type": "boolean",
+            "description": "True only when the verify command was matched against an observed bash tool_result after task start."
+          },
+          "observedAt": {
+            "type": "string",
+            "description": "Timestamp of the matching bash tool_result observation."
+          },
+          "isError": {
+            "type": "boolean",
+            "description": "Observed Pi tool_result isError flag."
+          },
+          "matchedProfileCommand": {
+            "type": "boolean",
+            "description": "True only when the observed verify command exactly matches one of task.verifyCommands."
+          }
+        },
+        "additionalProperties": true
+      }
+    },
+    "trace": {
+      "type": "object",
+      "required": [
+        "outcome"
+      ],
+      "properties": {
+        "outcome": {
+          "enum": [
+            "pending",
+            "completed",
+            "blocked",
+            "partial",
+            "failed"
+          ]
+        }
+      },
+      "additionalProperties": true
+    }
+  },
+  "additionalProperties": true
+}

package/scripts/audit-runtime-host.sh

@@ -0,0 +1,78 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+
+if [[ "${1:-}" == "-h" || "${1:-}" == "--help" ]]; then
+  echo "Usage: scripts/audit-runtime-host.sh"
+  echo "Audit the exact Pi host and pinned optional add-ons used by the installer; requires registry access."
+  exit 0
+fi
+if [[ $# -gt 0 ]]; then
+  echo "Unknown argument: $1" >&2
+  exit 2
+fi
+
+require_exact_peer() {
+  local name="$1"
+  local value
+  value="$(node -e 'const fs=require("node:fs"); const p=JSON.parse(fs.readFileSync(process.argv[1], "utf8")); process.stdout.write(p.peerDependencies?.[process.argv[2]] ?? "");' "$ROOT/package.json" "$name")"
+  if [[ ! "$value" =~ ^[0-9]+\.[0-9]+\.[0-9]+([+-][0-9A-Za-z.-]+)?$ ]]; then
+    echo "FAIL: peer dependency $name must use an exact version." >&2
+    exit 1
+  fi
+  printf '%s' "$value"
+}
+
+PI_CODING_VERSION="$(require_exact_peer "@earendil-works/pi-coding-agent")"
+PI_AI_VERSION="$(require_exact_peer "@earendil-works/pi-ai")"
+TYPEBOX_VERSION="$(require_exact_peer "typebox")"
+PI_MCP_ADAPTER_VERSION="2.11.0"
+PI_SUBAGENTS_VERSION="0.35.1"
+PI_WEB_ACCESS_VERSION="0.13.0"
+
+if [[ "$PI_CODING_VERSION" != "$PI_AI_VERSION" ]]; then
+  echo "FAIL: Pi Coding Agent and Pi AI host versions must match." >&2
+  exit 1
+fi
+
+AUDIT_ROOT="$(mktemp -d "${TMPDIR:-/tmp}/piagent-runtime-audit.XXXXXX")"
+cleanup() {
+  node --input-type=module - "$AUDIT_ROOT" <<'NODE'
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+const target = path.resolve(process.argv[2]);
+const tempRoot = fs.realpathSync(os.tmpdir());
+const targetParent = fs.realpathSync(path.dirname(target));
+if (targetParent !== tempRoot || !/^piagent-runtime-audit\.[A-Za-z0-9]+$/.test(path.basename(target))) {
+  throw new Error(`refusing to remove unexpected audit directory: ${target}`);
+}
+fs.rmSync(target, { recursive: true, force: true });
+NODE
+}
+trap cleanup EXIT
+
+node --input-type=module - "$AUDIT_ROOT/package.json" <<'NODE'
+import fs from "node:fs";
+const target = process.argv[2];
+fs.writeFileSync(target, `${JSON.stringify({ name: "piagent-runtime-audit", version: "0.0.0", private: true }, null, 2)}\n`);
+NODE
+
+echo "Auditing Pi host ${PI_CODING_VERSION} and pinned add-ons at severity high and above..."
+(
+  cd "$AUDIT_ROOT"
+  npm install --package-lock-only --ignore-scripts --no-audit --no-fund \
+    "@earendil-works/pi-coding-agent@${PI_CODING_VERSION}" \
+    "@earendil-works/pi-ai@${PI_AI_VERSION}" \
+    "typebox@${TYPEBOX_VERSION}" \
+    "pi-mcp-adapter@${PI_MCP_ADAPTER_VERSION}" \
+    "pi-subagents@${PI_SUBAGENTS_VERSION}" \
+    "pi-web-access@${PI_WEB_ACCESS_VERSION}" >/dev/null
+  # npm audit exits non-zero when it finds anything, so its status says nothing
+  # about whether the finding is one this project has accepted. The policy check
+  # decides that, and its exit status is the one that counts.
+  npm audit --json > audit.json || true
+  node "$ROOT/scripts/check-runtime-advisories.mjs" < audit.json
+)

package/scripts/bootstrap-local.sh

@@ -0,0 +1,25 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+PLATFORM_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+PI_AGENT_DIR="${PI_CODING_AGENT_DIR:-"${HOME}/.pi/agent"}"
+MCP_CONFIG_DIR="${XDG_CONFIG_HOME:-"${HOME}/.config"}/mcp"
+
+mkdir -p "$PI_AGENT_DIR/extensions" "$PI_AGENT_DIR/prompts" "$PI_AGENT_DIR/skills"
+mkdir -p "$MCP_CONFIG_DIR"
+
+echo "Pi Agent Platform"
+echo "platform: $PLATFORM_ROOT"
+echo "pi agent dir: $PI_AGENT_DIR"
+echo
+echo "Run these commands when ready:"
+echo
+echo "  bash \"$PLATFORM_ROOT/scripts/install-global.sh\" --package-source \"$PLATFORM_ROOT\" --with-mcp --mcp-preset core --with-herdr"
+echo "  pi"
+echo "  /login"
+echo
+echo "Then link a project:"
+echo
+echo "  bash \"$PLATFORM_ROOT/scripts/init-project.sh\" /path/to/project --profile generic --package-source git:github.com/Vt-mmm/piagent@vX.Y.Z"
+echo "  cd /path/to/project"
+echo "  pi"