@piagent/platform 1.0.0

package/packages/piagent-core/extensions/redaction-core.js

@@ -0,0 +1,4 @@
+export {
+  redactForStorage,
+  redactSensitiveText
+} from "../security/sensitive-data.js";

package/packages/piagent-core/extensions/runtime-evidence.js

@@ -0,0 +1,215 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { redactSensitiveText } from "../security/sensitive-data.js";
+
+export function normalizeEvidenceCommand(command) {
+  return String(command ?? "")
+    .replace(/\r\n/g, "\n")
+    .trim();
+}
+
+export function hashEvidenceCommand(command) {
+  return crypto
+    .createHash("sha256")
+    .update(normalizeEvidenceCommand(command))
+    .digest("hex");
+}
+
+export function commandMatchesVerifyPlan(command, verifyCommands) {
+  const normalized = normalizeEvidenceCommand(command);
+  if (!normalized || !Array.isArray(verifyCommands)) return false;
+  return verifyCommands.some((verifyCommand) => normalizeEvidenceCommand(verifyCommand) === normalized);
+}
+
+function normalizeCwd(cwd) {
+  return String(cwd ?? "").trim();
+}
+
+function parseTimeMs(value, fallback = Date.now()) {
+  if (typeof value === "number" && Number.isFinite(value)) return value;
+  const parsed = Date.parse(String(value ?? ""));
+  return Number.isFinite(parsed) ? parsed : fallback;
+}
+
+function numericExitCode(value) {
+  if (typeof value === "number" && Number.isInteger(value)) return value;
+  if (typeof value === "string" && /^-?\d+$/.test(value.trim())) return Number.parseInt(value, 10);
+  return undefined;
+}
+
+export function claimedExitMatchesObserved(exitCode, observed) {
+  const claimed = numericExitCode(exitCode);
+  if (claimed === undefined) return false;
+  if (typeof observed?.exitCode === "number") return observed.exitCode === claimed;
+  return observed?.isError === true ? claimed !== 0 : claimed === 0;
+}
+
+export function extractBashCommandFromToolResultEvent(event) {
+  if (!event || event.toolName !== "bash") return "";
+  const input = event.input;
+  if (input && typeof input.command === "string") return input.command;
+  if (input && typeof input === "object" && input.args && typeof input.args.command === "string") return input.args.command;
+  return "";
+}
+
+export function observedBashResultFromToolResultEvent(event, cwd, nowMs = Date.now()) {
+  const command = extractBashCommandFromToolResultEvent(event);
+  const normalizedCommand = normalizeEvidenceCommand(command);
+  if (!normalizedCommand) return undefined;
+  const commandHash = hashEvidenceCommand(normalizedCommand);
+  const exitCode = numericExitCode(event?.details?.exitCode ?? event?.details?.status ?? event?.exitCode);
+  const recordedAtMs = parseTimeMs(event?.timestamp, nowMs);
+  return {
+    cwd: normalizeCwd(cwd),
+    command: redactSensitiveText(command).text,
+    normalizedCommand: redactSensitiveText(normalizedCommand).text,
+    commandHash,
+    isError: event?.isError === true,
+    exitCode,
+    recordedAt: new Date(recordedAtMs).toISOString(),
+    recordedAtMs,
+    toolCallId: event?.toolCallId ?? event?.id
+  };
+}
+
+function canonicalObservedEntry(entry) {
+  const rawNormalizedCommand = normalizeEvidenceCommand(entry?.normalizedCommand ?? entry?.command);
+  const commandHash = entry?.commandHash || (rawNormalizedCommand ? hashEvidenceCommand(rawNormalizedCommand) : "");
+  if (!commandHash) return undefined;
+  const command = typeof entry?.command === "string" ? redactSensitiveText(entry.command).text : "";
+  const normalizedCommand = redactSensitiveText(rawNormalizedCommand).text;
+  const recordedAtMs = parseTimeMs(entry?.recordedAtMs ?? entry?.recordedAt);
+  return {
+    cwd: normalizeCwd(entry?.cwd),
+    command,
+    normalizedCommand,
+    commandHash,
+    isError: entry?.isError === true,
+    exitCode: numericExitCode(entry?.exitCode),
+    recordedAt: entry?.recordedAt ?? new Date(recordedAtMs).toISOString(),
+    recordedAtMs,
+    toolCallId: entry?.toolCallId
+  };
+}
+
+function observedCommandsMatch(entry, normalizedCommand, commandHash) {
+  if (entry.commandHash) return entry.commandHash === commandHash;
+  return normalizeEvidenceCommand(entry.normalizedCommand ?? entry.command) === normalizedCommand;
+}
+
+export function findMatchingObservedBashResult(entries, { cwd, command, notBefore, exitCode }) {
+  const normalizedCommand = normalizeEvidenceCommand(command);
+  const commandHash = hashEvidenceCommand(normalizedCommand);
+  const normalizedCwd = normalizeCwd(cwd);
+  const notBeforeMs = notBefore ? parseTimeMs(notBefore, 0) : 0;
+  if (!normalizedCommand) {
+    return { ok: false, reason: "Verify command is empty after normalization." };
+  }
+
+  for (let index = entries.length - 1; index >= 0; index -= 1) {
+    const entry = canonicalObservedEntry(entries[index]);
+    if (!entry) continue;
+    if (entry.cwd !== normalizedCwd) continue;
+    if (!observedCommandsMatch(entry, normalizedCommand, commandHash)) continue;
+    if (entry.recordedAtMs < notBeforeMs) continue;
+    if (!claimedExitMatchesObserved(exitCode, entry)) {
+      return {
+        ok: false,
+        reason: `Observed command status does not match claimed exitCode ${exitCode}.`,
+        entry
+      };
+    }
+    return { ok: true, entry };
+  }
+
+  return {
+    ok: false,
+    reason: "No matching bash tool_result observed for this command after task start."
+  };
+}
+
+function persistedObservedEntry(entry) {
+  const observed = canonicalObservedEntry(entry);
+  if (!observed) return undefined;
+  const command = typeof entry?.redactedCommand === "string"
+    ? redactSensitiveText(entry.redactedCommand).text
+    : observed.command;
+  return {
+    schemaVersion: 1,
+    cwd: observed.cwd,
+    commandHash: observed.commandHash,
+    command,
+    isError: observed.isError,
+    exitCode: observed.exitCode,
+    recordedAt: observed.recordedAt,
+    recordedAtMs: observed.recordedAtMs,
+    toolCallId: observed.toolCallId
+  };
+}
+
+export function readObservedBashResults(filePath, options = {}) {
+  if (!filePath || !fs.existsSync(filePath)) return [];
+  const maxEntries = Number.isInteger(options.maxEntries) ? options.maxEntries : 5000;
+  const text = fs.readFileSync(filePath, "utf8");
+  const entries = [];
+  for (const line of text.split(/\n/)) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    try {
+      const parsed = JSON.parse(trimmed);
+      const entry = canonicalObservedEntry(parsed);
+      if (entry) entries.push(entry);
+    } catch {
+      // Ignore a partially written/corrupt JSONL line. The ledger is advisory evidence,
+      // and the final gate remains fail-closed when no valid observation is available.
+    }
+  }
+  return entries.slice(-maxEntries);
+}
+
+function pruneObservedBashFile(filePath, maxPersistedEntries) {
+  if (!Number.isInteger(maxPersistedEntries) || maxPersistedEntries <= 0) return;
+  const entries = readObservedBashResults(filePath, { maxEntries: maxPersistedEntries });
+  const lines = entries.map((entry) => JSON.stringify(persistedObservedEntry(entry))).filter(Boolean);
+  fs.writeFileSync(filePath, `${lines.join("\n")}${lines.length ? "\n" : ""}`);
+}
+
+export function appendObservedBashResult(filePath, entry, options = {}) {
+  if (!filePath) return undefined;
+  const persisted = persistedObservedEntry(entry);
+  if (!persisted) return undefined;
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.appendFileSync(filePath, `${JSON.stringify(persisted)}\n`);
+  if (Number.isInteger(options.maxPersistedEntries)) {
+    pruneObservedBashFile(filePath, options.maxPersistedEntries);
+  }
+  return persisted;
+}
+
+export function createBashResultLedger(options = {}) {
+  const maxEntries = Number.isInteger(options.maxEntries) ? options.maxEntries : 300;
+  const entries = [];
+
+  function prune() {
+    while (entries.length > maxEntries) entries.shift();
+  }
+
+  return {
+    record(entry) {
+      const observed = canonicalObservedEntry(entry);
+      if (!observed) return undefined;
+      entries.push(observed);
+      prune();
+      return observed;
+    },
+
+    findMatching({ cwd, command, notBefore, exitCode }) {
+      return findMatchingObservedBashResult(entries, { cwd, command, notBefore, exitCode });
+    },
+
+    list() {
+      return entries.map((entry) => ({ ...entry }));
+    }
+  };
+}

package/packages/piagent-core/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@piagent/core",
+  "version": "1.0.0",
+  "type": "module",
+  "private": true,
+  "license": "MIT",
+  "description": "Pi agent package: guard extension, prompts, skills, and policy defaults.",
+  "homepage": "https://piagent.io.vn",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Vt-mmm/piagent.git",
+    "directory": "packages/piagent-core"
+  },
+  "keywords": [
+    "pi-package",
+    "coding-agent",
+    "agent-harness"
+  ],
+  "pi": {
+    "extensions": [
+      "extensions/piagent-guard.ts"
+    ],
+    "skills": [
+      "skills"
+    ],
+    "prompts": [
+      "prompts"
+    ],
+    "subagents": {
+      "agents": [
+        "subagents"
+      ]
+    }
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "0.81.1",
+    "typebox": "1.1.38"
+  },
+  "peerDependenciesMeta": {
+    "@earendil-works/pi-coding-agent": { "optional": true },
+    "typebox": { "optional": true }
+  },
+  "engines": {
+    "node": ">=22.19.0"
+  }
+}

package/packages/piagent-core/policies/base-policy.json

@@ -0,0 +1,249 @@
+{
+  "schemaVersion": 1,
+  "name": "piagent-base-policy",
+  "protectedPaths": [
+    ".git/**",
+    "**/auth.json",
+    "**/.env",
+    "**/.env.*",
+    "**/node_modules/**",
+    "**/dist/**",
+    ".pi/piagent-state/**",
+    ".pi/settings.json",
+    ".pi/piagent-profile.json",
+    ".pi/piagent-profile.lock.json",
+    ".pi/context-index.json"
+  ],
+  "shellProtectedPaths": [
+    ".git/**",
+    "**/auth.json",
+    "**/.env",
+    "**/.env.*",
+    ".pi/piagent-state/**",
+    ".pi/settings.json",
+    ".pi/piagent-profile.json",
+    ".pi/piagent-profile.lock.json",
+    ".pi/context-index.json"
+  ],
+  "blockedCommandPatterns": [
+    "rm -rf /",
+    "rm -rf ~",
+    "rm -rf $HOME",
+    "git reset --hard",
+    "git clean -fd",
+    "sudo ",
+    "chmod -R 777"
+  ],
+  "requireConfirmationPatterns": [
+    "deploy",
+    "release",
+    "publish",
+    "migration",
+    "terraform apply",
+    "kubectl apply",
+    "gh pr merge",
+    "git push"
+  ],
+  "defaultRequiredContext": [
+    "AGENTS.md",
+    "README.md"
+  ],
+  "permissionProfiles": {
+    "defaultMode": "workspace-write",
+    "allowedModes": [
+      "read-only",
+      "workspace-write",
+      "trusted-full-access"
+    ]
+  },
+  "execPolicy": {
+    "defaultMode": "enforce",
+    "bannedPrefixSuggestions": [
+      ["python"],
+      ["python3"],
+      ["node"],
+      ["node", "-e"],
+      ["bash"],
+      ["bash", "-lc"],
+      ["sh"],
+      ["sh", "-c"],
+      ["zsh"],
+      ["zsh", "-lc"],
+      ["git"],
+      ["sudo"],
+      ["env"]
+    ],
+    "rules": [
+      {
+        "id": "prompt-git-add-broad",
+        "action": "prompt",
+        "match": "regex",
+        "value": "(?:^|\\s)git\\s+(?:-C\\s+\\S+\\s+)?add\\s+(?:(?:--all|-A)(?:\\s+(?:\\.|:/))?|--\\s+(?:\\.|:/)|(?:\\.|:/))(?:\\s|$)",
+        "reason": "Broad git staging can include unrelated or sensitive changes; inspect git status/diff and confirm the exact scope first."
+      },
+      {
+        "id": "forbid-docker-volume-prune",
+        "action": "forbid",
+        "match": "contains",
+        "value": "docker volume prune",
+        "reason": "Volume prune can delete unrecoverable local data."
+      },
+      {
+        "id": "prompt-docker-compose-down-volume",
+        "action": "prompt",
+        "match": "regex",
+        "value": "docker\\s+compose\\s+down\\s+.*-v",
+        "reason": "docker compose down -v removes volumes."
+      },
+      {
+        "id": "prompt-database-migration",
+        "action": "prompt",
+        "match": "contains",
+        "value": "migrate",
+        "reason": "Database migrations require explicit human confirmation."
+      }
+    ]
+  },
+  "contextBudget": {
+    "defaultMode": "enforce",
+    "maxContextFileChars": 50000,
+    "maxMemoryFileChars": 20000,
+    "maxManifestFiles": 80,
+    "warnFragmentChars": 4000
+  },
+  "toolRegistry": {
+    "defaultMode": "advisory",
+    "alwaysAllowedTools": [
+      "piagent_context",
+      "piagent_permission_status",
+      "piagent_exec_policy_check",
+      "piagent_context_budget",
+      "piagent_tool_policy_check",
+      "piagent_task_gate_check",
+      "piagent_usage_snapshot",
+      "piagent_orchestration_policy",
+      "piagent_memory_status",
+      "piagent_memory_note",
+      "piagent_memory_search",
+      "piagent_memory_citation_record",
+      "piagent_context_index_status",
+      "piagent_context_index_record",
+      "piagent_context_index_search",
+      "piagent_profile_options",
+      "piagent_profile_apply",
+      "piagent_profile_tech_options",
+      "piagent_profile_tech_apply",
+      "piagent_profile_tech_context_record",
+      "piagent_project_onboarding_record",
+      "piagent_task_start",
+      "piagent_source_checkout",
+      "piagent_context_record",
+      "piagent_verify_record",
+      "piagent_trace_record"
+    ],
+    "toolCapabilities": {
+      "bash": ["shell"],
+      "shell": ["shell"],
+      "exec": ["shell"],
+      "read": ["filesystem-readonly"],
+      "grep": ["filesystem-readonly"],
+      "find": ["filesystem-readonly"],
+      "ls": ["filesystem-readonly"],
+      "write": ["filesystem-write"],
+      "edit": ["filesystem-write"],
+      "browser": ["browser"],
+      "github": ["github"]
+    }
+  },
+  "externalActionPolicy": {
+    "defaultMode": "enforce",
+    "providerKeywords": [
+      "github",
+      "gitlab",
+      "bitbucket",
+      "vercel",
+      "netlify",
+      "cloudflare",
+      "aws",
+      "gcp",
+      "azure",
+      "slack",
+      "teams",
+      "jira",
+      "linear",
+      "notion",
+      "figma",
+      "stripe",
+      "supabase",
+      "firebase"
+    ],
+    "writeVerbs": [
+      "add",
+      "approve",
+      "archive",
+      "assign",
+      "close",
+      "comment",
+      "create",
+      "delete",
+      "deploy",
+      "dispatch",
+      "merge",
+      "open",
+      "post",
+      "publish",
+      "push",
+      "release",
+      "remove",
+      "reopen",
+      "run",
+      "send",
+      "submit",
+      "trigger",
+      "update",
+      "upload",
+      "write"
+    ],
+    "safeVerbs": [
+      "fetch",
+      "find",
+      "get",
+      "inspect",
+      "list",
+      "read",
+      "search",
+      "show",
+      "view"
+    ]
+  },
+  "finalGate": {
+    "defaultMode": "enforce",
+    "requireTaskContract": true,
+    "requireContextManifest": true,
+    "requireVerifyEvidence": true,
+    "requireTrace": true,
+    "requirePassingVerify": true
+  },
+  "orchestrationPolicy": {
+    "defaultMode": "solo-first",
+    "maxConcurrentSubagents": 2,
+    "defaultReviewLenses": [
+      "correctness",
+      "tests",
+      "scope"
+    ],
+    "roleModelGuidance": {
+      "planner": "Use the strongest available model for decomposition, architecture, risk, and acceptance criteria.",
+      "worker": "Use the fastest reliable model for a bounded, already-planned single write set.",
+      "reviewer": "Use a model or thinking setting decorrelated from the worker when review quality matters.",
+      "watchdog": "Use a strong model only for final risk review, security, release, or high-impact changes."
+    },
+    "fieldGuide": {
+      "enabled": true,
+      "path": ".pi/memory/MEMORY.md",
+      "maxLines": 80,
+      "writePolicy": "explicit-only",
+      "readBeforeTask": true
+    }
+  }
+}

package/packages/piagent-core/prompts/be-to-fe.md

@@ -0,0 +1,82 @@
+---
+description: Implement frontend from backend spec/contract with backend read-only
+argument-hint: "<BE spec/change + FE outcome>"
+---
+
+Implement a frontend change from a backend spec, backend diff, or backend source contract without modifying backend source.
+
+Request:
+
+```text
+$ARGUMENTS
+```
+
+Use this for tasks like:
+
+- BE endpoint/DTO changed and FE must consume it.
+- BE feature spec must be surfaced in FE.
+- FE needs to map validation/errors/state from backend contract.
+- Backend source must be scouted but not edited.
+
+Mandatory flow:
+
+0. Call `piagent_context_preflight` with `workflow=be-to-fe`. If it recommends `fresh-session`, stop loading context in this session and tell the user to use `/fresh-be-to-fe <request>` unless this command already runs in a fresh session.
+1. Call `piagent_context` with `detail=full` and confirm profile/protected backend paths.
+2. Call `piagent_orchestration_policy`; keep the workflow solo-first unless bounded BE/FE scouting or review is worth the extra token/tool cost.
+3. Call `piagent_memory_status`; search memory or Field Guide for prior BE/FE mapping decisions if relevant, record citations with `piagent_memory_citation_record`, then verify against current BE/FE files.
+4. Read `.pi/project-context.md`. If pending, stop and ask for `/onboard-project`.
+5. Read required context from the active profile and call `piagent_context_budget` for BE/FE files that look large.
+6. Classify the task:
+   - BE scout: read-only.
+   - FE implementation: source-write.
+   - Auth/data migration/external provider: high-risk, ask before implementation.
+7. Decide whether bounded subagents are useful. If the bundled `pi-subagents` parent skill is available, use it for delegation patterns and safety boundaries. If `pi-subagents`/`subagent(...)` is available, prefer read-only delegation only when BE/FE mapping has independent lanes:
+   - `piagent-scout` maps backend contract read-only;
+   - `piagent-scout` maps frontend touchpoints read-only;
+   - builtin `context-builder` may create handoff context when the BE→FE mapping touches multiple journeys/forms/contracts;
+   - `piagent-planner` produces the FE implementation plan when the contract touches multiple layers;
+   - `piagent-reviewer` reviews diff/verification after implementation.
+   Continue single-agent if subagents are unavailable, the task is tiny, or requirements are unresolved.
+8. Scout backend contract read-only:
+   - controller/route/handler;
+   - request/response DTO/schema;
+   - validation/error model;
+   - backend tests;
+   - OpenAPI/spec/docs if available;
+   - migration/schema only when it affects API shape or UI constraints.
+9. Produce a contract snapshot before FE writes:
+
+   | Contract area | Backend evidence | FE implication |
+   |---|---|---|
+
+10. If backend contract is missing/contradictory, do not guess and do not edit BE. Record the gap in the final response or a project report if requested.
+11. Map FE touchpoints:
+   - API client/query/mutation layer;
+   - types/decoders;
+   - state/cache invalidation;
+   - route/page/component/form;
+   - tests/e2e.
+12. Before source writes, create a Task Implementation Contract with `piagent_task_start`, including review lenses and a compact workPlan.
+13. Record BE/FE context files with `piagent_context_record`.
+14. Before shell commands beyond simple read/list/test, call `piagent_exec_policy_check`.
+15. Implement FE only.
+16. Run the exact FE verify command from the profile/task through Pi bash and record the observed result with `piagent_verify_record`. Ad-hoc commands are advisory only and will not satisfy the passing gate.
+17. Record handoff with `piagent_trace_record`.
+18. Call `piagent_task_gate_check`; if it fails, report blocked/partial instead of done.
+
+For generic projects, use profile `be-readonly-fe` when the repo policy is “BE scout only, FE write allowed”.
+
+Do not ask the user to paste the mandatory flow. The platform prompt already contains it. If the user asks only for scout/audit, stay read-only and prefer `/scout` or `/fresh-scout`.
+
+Final output:
+
+- Backend files read and why.
+- Contract snapshot summary.
+- FE files changed.
+- Verify command/result.
+- Subagents used/not used and why.
+- Review lenses applied.
+- Task gate result.
+- Memory cited, if any.
+- Backend gaps, if any.
+- Residual risk.

package/packages/piagent-core/prompts/commit.md

@@ -0,0 +1,27 @@
+---
+description: Create a guarded local Git commit for reviewed project changes
+argument-hint: "[commit message or scope]"
+---
+
+Create a local Git commit for the current project changes.
+
+Request:
+
+```text
+$ARGUMENTS
+```
+
+Rules:
+
+1. This command creates a local commit only. Do not push, tag, publish, release, merge, or open external provider flows.
+2. Use normal shell Git commands so the piagent guard, protected paths, redaction, and confirmation gates remain active.
+3. Start with `git status --short` and `git diff --stat`. If there are no changes, stop with one short line.
+4. Inspect the relevant diff before staging. Do not stage files that look unrelated to the requested commit.
+5. Prefer explicit path staging such as `git add README.md packages/piagent-core/prompts/commit.md`.
+6. Do not use broad staging (`git add .`, `git add -A`, `git add --all`, `git add -- .`, `git add :/`) unless the human operator explicitly confirms that broad staging is intended.
+7. Refuse to stage protected or local-secret material such as `.env`, `.env.*`, `auth.json`, `.pi/settings.json`, `.pi/piagent-profile.json`, `.pi/piagent-profile.lock.json`, session files, caches, keys, or credentials.
+8. If `$ARGUMENTS` contains a usable commit message, use it. Otherwise derive a concise Conventional Commit message from the inspected diff.
+9. Run a lightweight verification before committing. At minimum use `git diff --check`; if source, policy, prompts, or package metadata changed, run the relevant project verification command.
+10. After committing, report only the commit hash, message, files committed, verification result, and whether anything remains uncommitted.
+
+Output at most 8 short lines. Keep it action-first and avoid long explanations.

package/packages/piagent-core/prompts/discuss.md

@@ -0,0 +1,35 @@
+---
+description: Clarify an unclear task before planning or implementation
+argument-hint: "<rough idea>"
+---
+
+Clarify this request before implementation:
+
+```text
+$ARGUMENTS
+```
+
+Operating rules:
+
+1. Call `piagent_context` first when available.
+2. Call `piagent_memory_status`; use memory only to avoid repeated context questions, not as authority.
+3. Read `.pi/project-context.md` if available; if it is still pending, recommend `/onboard-project` before implementation.
+4. Inspect relevant files/docs before asking; do not ask what can be answered from the project.
+5. Identify the next unresolved decision, dependency, constraint, or risk.
+6. Ask at most 3 focused questions per round.
+7. For each question, include:
+   - recommended/default answer
+   - short reason
+   - impact if the user chooses differently
+8. Resolve prerequisite decisions before dependent decisions.
+9. Stop when the task is clear enough to produce a bounded plan.
+10. Do not edit files and do not implement.
+
+Final output when clear:
+
+- agreed decisions
+- remaining open questions, if any
+- implementation approach
+- required context
+- verify commands
+- recommended next command: `/plan` or `/task`