@aipper/aiws 0.0.49 → 0.0.51

package/dist/lib/pi-force-policy.js

@@ -0,0 +1,187 @@
+/**
+ * Pure force-policy for Pi subagent-first (TOOLING-002L / pi-force-subagent).
+ * No I/O. Used by unit tests and by `.pi/extensions/aiws.ts` (copy or import).
+ */
+/** Approved inline escape-hatch phrases (current user message only). */
+export const HATCH_PHRASES = [
+    "直接改",
+    "do it inline",
+    "你直接改",
+    "别派 sub-agent",
+    "main session 写就行",
+    "不用 sub-agent",
+    "no sub-agent",
+];
+/** Allowed Agent subagent_type values for implement/review dispatch. */
+export const ALLOWED_SUBAGENT_TYPES = ["aiws-worker", "aiws-reviewer"];
+/** Tool names treated as mutating writes when deny is active. */
+export const DENIED_WRITE_TOOLS = ["write", "edit", "Write", "Edit"];
+/**
+ * Path prefixes (posix-style, relative to project root) allowed for main-session
+ * writes without hatch. Match is prefix after normalize (no leading ./).
+ */
+export const MAIN_WRITE_ALLOW_PREFIXES = [
+    ".aiws/changes/",
+    ".aiws/plan/",
+    ".aiws/goals/",
+];
+/** Subpaths under .aiws/changes that are allowed without hatch. */
+const CHANGES_ALLOWED_SEGMENTS = [
+    "/evidence/",
+    "/analysis/",
+    "/review/",
+];
+/**
+ * Detect hatch in the **current** user message only (caller must pass only that text).
+ */
+export function detectHatch(currentUserMessage) {
+    if (!currentUserMessage)
+        return false;
+    const text = currentUserMessage;
+    for (const phrase of HATCH_PHRASES) {
+        if (text.includes(phrase))
+            return true;
+    }
+    return false;
+}
+/**
+ * Normalize a path for allowlist checks: backslash→slash, strip leading ./ and /
+ */
+export function normalizeRelPath(filePath) {
+    let p = filePath.replace(/\\/g, "/").trim();
+    while (p.startsWith("./"))
+        p = p.slice(2);
+    while (p.startsWith("/"))
+        p = p.slice(1);
+    return p;
+}
+/**
+ * Whether a write target is on the main-session governance allowlist (no hatch required).
+ */
+export function isMainWriteAllowlisted(filePath) {
+    const p = normalizeRelPath(filePath);
+    if (p.startsWith(".aiws/plan/") || p === ".aiws/plan")
+        return true;
+    if (p.startsWith(".aiws/goals/") || p === ".aiws/goals")
+        return true;
+    if (!p.startsWith(".aiws/changes/"))
+        return false;
+    for (const seg of CHANGES_ALLOWED_SEGMENTS) {
+        if (p.includes(seg))
+            return true;
+    }
+    // allow changes root meta files sometimes used by orchestrator
+    // e.g. .aiws/changes/<id>/tasks.md is NOT allowlisted (worker territory)
+    return false;
+}
+/**
+ * Decide if main session may invoke a write-like tool for path.
+ */
+export function decideMainWrite(opts) {
+    const name = opts.toolName;
+    const isWrite = DENIED_WRITE_TOOLS.includes(name) ||
+        /^(write|edit)$/i.test(name);
+    if (!isWrite) {
+        return { allow: true, reason: "non-write tool" };
+    }
+    if (opts.hatchActive) {
+        return { allow: true, reason: "hatch active on current user message" };
+    }
+    const path = opts.filePath ?? "";
+    if (path && isMainWriteAllowlisted(path)) {
+        return { allow: true, reason: "governance path allowlist" };
+    }
+    if (!path) {
+        return {
+            allow: false,
+            reason: "main-session write denied without hatch and without allowlisted path (missing path)",
+            code: "MAIN_WRITE_DENIED",
+        };
+    }
+    return {
+        allow: false,
+        reason: `main-session write denied for path without hatch: ${normalizeRelPath(path)}. Use Agent(subagent_type=aiws-worker) or hatch phrase + evidence/inline-escape-hatch.md`,
+        code: "MAIN_WRITE_DENIED",
+    };
+}
+/**
+ * Whitelist subagent types for implement/review. Unknown types must not fall through
+ * to pi-subagents general-purpose silently.
+ */
+export function decideAgentType(subagentType) {
+    const t = (subagentType ?? "").trim().toLowerCase();
+    if (!t) {
+        return {
+            allow: false,
+            reason: "subagent_type required; use aiws-worker or aiws-reviewer",
+            code: "AGENT_TYPE_REQUIRED",
+        };
+    }
+    const allowed = ALLOWED_SUBAGENT_TYPES.map((x) => x.toLowerCase());
+    if (allowed.includes(t)) {
+        return { allow: true, reason: `allowed type: ${t}` };
+    }
+    return {
+        allow: false,
+        reason: `subagent_type "${subagentType}" not in whitelist (aiws-worker|aiws-reviewer). pi-subagents may fallback to general-purpose — AIWS rejects this.`,
+        code: "AGENT_TYPE_DENIED",
+    };
+}
+/**
+ * Text for session_start system prompt injection.
+ */
+export function buildForcePolicyPromptBlock() {
+    return [
+        "<aiws-pi-force-policy>",
+        "Pi force policy (AIWS owns; runtime spawn is @tintinweb/pi-subagents):",
+        "1. Subagent-first: implement via Agent({ subagent_type: \"aiws-worker\" }); review via aiws-reviewer.",
+        "2. Type whitelist only: aiws-worker | aiws-reviewer. Never general-purpose for implementation.",
+        "3. Without hatch: do NOT write/edit business code. Only governance paths under .aiws/changes/**/{evidence,analysis,review}/**, .aiws/plan/**, .aiws/goals/**.",
+        "4. Hatch phrases (CURRENT user message only): " + HATCH_PHRASES.join(" | "),
+        "   → if used, write changes/<id>/evidence/inline-escape-hatch.md first.",
+        "5. No silent fallback: delegate fail → write evidence/delegate-failure.md and STOP.",
+        "6. Deprecated: aiws_subagent (ctx.newSession). Prefer pi-subagents Agent tool.",
+        "Spec: packages/spec/docs/pi-subagent-first.md",
+        "</aiws-pi-force-policy>",
+    ].join("\n");
+}
+/**
+ * Deprecation message when aiws_subagent is invoked.
+ */
+export function aiwsSubagentDeprecationMessage(prompt) {
+    return [
+        "[aiws] aiws_subagent is DEPRECATED as primary runtime.",
+        "Install and use @tintinweb/pi-subagents:",
+        '  Agent({ subagent_type: "aiws-worker" | "aiws-reviewer", prompt: "..." })',
+        "Then get_subagent_result / steer_subagent as needed.",
+        "See packages/spec/docs/pi-subagent-first.md",
+        prompt
+            ? `Your prompt was not executed via deprecated path. Re-dispatch with Agent:\n---\n${prompt.slice(0, 2000)}`
+            : "Usage was empty. Provide a prompt to Agent tool instead.",
+    ].join("\n");
+}
+/**
+ * Suggested content for evidence/delegate-failure.md
+ */
+export function formatDelegateFailureEvidence(opts) {
+    const at = opts.at ?? new Date().toISOString();
+    return [
+        "# Delegate failure (no silent main-session fallback)",
+        "",
+        `- **at**: ${at}`,
+        opts.changeId ? `- **change**: ${opts.changeId}` : null,
+        opts.attemptedType ? `- **attempted_type**: ${opts.attemptedType}` : null,
+        `- **error**: ${opts.error}`,
+        "",
+        "## Policy",
+        "",
+        "Do **not** implement business code in the main session without hatch.",
+        "Fix the delegate path (install pi-subagents, correct type, retry) or stop.",
+        "",
+        "Spec: packages/spec/docs/pi-subagent-first.md",
+        "",
+    ]
+        .filter((x) => x !== null)
+        .join("\n");
+}
+//# sourceMappingURL=pi-force-policy.js.map

package/dist/lib/pi-force-policy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pi-force-policy.js","sourceRoot":"","sources":["../../src/lib/pi-force-policy.ts"],"names":[],"mappings":"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"}

package/dist/lib/pi-force-policy.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/lib/pi-force-policy.test.js

@@ -0,0 +1,99 @@
+import { describe, it, expect } from "vitest";
+import { detectHatch, isMainWriteAllowlisted, decideMainWrite, decideAgentType, normalizeRelPath, buildForcePolicyPromptBlock, aiwsSubagentDeprecationMessage, formatDelegateFailureEvidence, HATCH_PHRASES, } from "./pi-force-policy.js";
+describe("detectHatch", () => {
+    it("returns false for empty/null", () => {
+        expect(detectHatch(null)).toBe(false);
+        expect(detectHatch("")).toBe(false);
+        expect(detectHatch(undefined)).toBe(false);
+    });
+    it("matches each approved phrase", () => {
+        for (const p of HATCH_PHRASES) {
+            expect(detectHatch(`please ${p} now`)).toBe(true);
+        }
+    });
+    it("does not match unrelated text", () => {
+        expect(detectHatch("用 subagent 实现功能")).toBe(false);
+        expect(detectHatch("继续")).toBe(false);
+    });
+});
+describe("normalizeRelPath / isMainWriteAllowlisted", () => {
+    it("normalizes slashes and ./", () => {
+        expect(normalizeRelPath(".aiws\\plan\\x.md")).toBe(".aiws/plan/x.md");
+        expect(normalizeRelPath("./.aiws/plan/x.md")).toBe(".aiws/plan/x.md");
+    });
+    it("allows evidence/analysis/review under changes", () => {
+        expect(isMainWriteAllowlisted(".aiws/changes/pi-force-subagent/evidence/delegate-failure.md")).toBe(true);
+        expect(isMainWriteAllowlisted(".aiws/changes/x/analysis/notes.md")).toBe(true);
+        expect(isMainWriteAllowlisted(".aiws/changes/x/review/spec-review.md")).toBe(true);
+    });
+    it("allows plan and goals", () => {
+        expect(isMainWriteAllowlisted(".aiws/plan/2026-07-23.md")).toBe(true);
+        expect(isMainWriteAllowlisted(".aiws/goals/g1.state.json")).toBe(true);
+    });
+    it("denies business and change meta without segment", () => {
+        expect(isMainWriteAllowlisted("packages/aiws/src/cli.ts")).toBe(false);
+        expect(isMainWriteAllowlisted(".aiws/changes/x/tasks.md")).toBe(false);
+        expect(isMainWriteAllowlisted("src/app.vue")).toBe(false);
+    });
+});
+describe("decideMainWrite", () => {
+    it("allows non-write tools", () => {
+        expect(decideMainWrite({ toolName: "read", hatchActive: false }).allow).toBe(true);
+    });
+    it("denies write to business path without hatch", () => {
+        const d = decideMainWrite({
+            toolName: "write",
+            filePath: "packages/aiws/src/cli.ts",
+            hatchActive: false,
+        });
+        expect(d.allow).toBe(false);
+        if (!d.allow)
+            expect(d.code).toBe("MAIN_WRITE_DENIED");
+    });
+    it("allows write with hatch", () => {
+        expect(decideMainWrite({
+            toolName: "edit",
+            filePath: "packages/aiws/src/cli.ts",
+            hatchActive: true,
+        }).allow).toBe(true);
+    });
+    it("allows write to evidence without hatch", () => {
+        expect(decideMainWrite({
+            toolName: "write",
+            filePath: ".aiws/changes/pi-force-subagent/evidence/x.md",
+            hatchActive: false,
+        }).allow).toBe(true);
+    });
+});
+describe("decideAgentType", () => {
+    it("allows worker and reviewer case-insensitively", () => {
+        expect(decideAgentType("aiws-worker").allow).toBe(true);
+        expect(decideAgentType("AIWS-Reviewer").allow).toBe(true);
+    });
+    it("denies general-purpose and empty", () => {
+        const g = decideAgentType("general-purpose");
+        expect(g.allow).toBe(false);
+        if (!g.allow)
+            expect(g.code).toBe("AGENT_TYPE_DENIED");
+        expect(decideAgentType("").allow).toBe(false);
+    });
+});
+describe("prompt helpers", () => {
+    it("buildForcePolicyPromptBlock mentions whitelist and hatch", () => {
+        const b = buildForcePolicyPromptBlock();
+        expect(b).toContain("aiws-worker");
+        expect(b).toContain("hatch");
+        expect(b).toContain("pi-subagent-first");
+    });
+    it("aiwsSubagentDeprecationMessage points to Agent", () => {
+        const m = aiwsSubagentDeprecationMessage("do stuff");
+        expect(m).toContain("DEPRECATED");
+        expect(m).toContain("aiws-worker");
+    });
+    it("formatDelegateFailureEvidence includes error", () => {
+        const e = formatDelegateFailureEvidence({ error: "timeout", changeId: "pi-force-subagent" });
+        expect(e).toContain("timeout");
+        expect(e).toContain("pi-force-subagent");
+    });
+});
+//# sourceMappingURL=pi-force-policy.test.js.map

package/dist/lib/pi-force-policy.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pi-force-policy.test.js","sourceRoot":"","sources":["../../src/lib/pi-force-policy.test.ts"],"names":[],"mappings":"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"}

package/dist/lib/pi-plugins-doctor.d.ts

@@ -0,0 +1,150 @@
+/**
+ * Pi user-level plugins doctor (TOOLING-002L / PB-010 / pi-plugin-doctor).
+ * Pure classify + format; I/O helpers injectable for tests.
+ */
+export type PluginTier = "required" | "recommended_a" | "recommended_b" | "forbidden";
+export interface ManifestPlugin {
+    id: string;
+    package: string;
+    version?: string;
+    tier?: PluginTier | string;
+    severity?: "conflict" | "forbidden" | string;
+    reason?: string;
+}
+export interface PiPluginsManifest {
+    version: number;
+    scope: string;
+    source_protocol: string;
+    install_template: string;
+    required: ManifestPlugin[];
+    recommended_a: ManifestPlugin[];
+    recommended_b: ManifestPlugin[];
+    forbidden: ManifestPlugin[];
+}
+export interface InstalledPackage {
+    /** bare or scoped name without version */
+    name: string;
+    version?: string;
+    raw?: string;
+}
+export type DetectSource = "pi_list" | "settings" | "none" | "injected";
+export interface DoctorClassifyInput {
+    manifest: PiPluginsManifest;
+    installed: InstalledPackage[];
+    piCliAvailable: boolean;
+    detectSource: DetectSource;
+}
+export interface DoctorFinding {
+    package: string;
+    version?: string;
+    tier: string;
+    kind: "missing_required" | "missing_recommended" | "conflict" | "forbidden_present" | "ok_required";
+    installCmd?: string;
+    reason?: string;
+}
+export interface DoctorReport {
+    piCliAvailable: boolean;
+    detectSource: DetectSource;
+    installedNames: string[];
+    missingRequired: DoctorFinding[];
+    missingRecommendedA: DoctorFinding[];
+    missingRecommendedB: DoctorFinding[];
+    conflicts: DoctorFinding[];
+    forbiddenPresent: DoctorFinding[];
+    okRequired: DoctorFinding[];
+    /** true when required all present and no conflicts */
+    ok: boolean;
+    /** CLI doctor exit should be non-zero when !ok or pi missing for strict mode */
+    exitCode: number;
+}
+export declare const DEFAULT_MANIFEST: PiPluginsManifest;
+/** Normalize package name for set membership (lowercase, strip version suffix). */
+export declare function normalizePackageName(raw: string): string;
+export declare function installCommandFor(plugin: ManifestPlugin, template?: string): string;
+/**
+ * Loose parse of `pi list` / package listing text.
+ * Accepts lines like:
+ * - @tintinweb/pi-subagents@0.14.2
+ * - npm:@tintinweb/pi-subagents@0.14.2
+ * - pi-powerbar 0.1.0
+ * - "name": "@tintinweb/pi-subagents"
+ * Skips URLs, filesystem paths, and section headers ("User packages:").
+ */
+export declare function parseInstalledFromText(text: string): InstalledPackage[];
+export declare function parseInstalledFromSettings(settingsJson: unknown): InstalledPackage[];
+/**
+ * Classify installed packages against manifest.
+ * Special case: forbidden id `pi-subagents` means unscoped only — do not match `@tintinweb/pi-subagents`.
+ */
+export declare function classifyPiPlugins(input: DoctorClassifyInput): DoctorReport;
+/**
+ * Unscoped `pi-subagents` must not match `@tintinweb/pi-subagents`.
+ * Presence of unscoped name alone is enough for conflict (even if tintinweb also installed).
+ */
+export declare function isForbiddenPresent(set: Set<string>, forbiddenPackage: string): boolean;
+export declare function formatDoctorReport(report: DoctorReport, opts?: {
+    header?: string;
+}): string;
+export declare function loadManifestFromSpec(): Promise<PiPluginsManifest>;
+export declare function normalizeManifest(data: Partial<PiPluginsManifest> | null | undefined): PiPluginsManifest;
+export declare function detectInstalledPackages(opts?: {
+    homeDir?: string;
+    runPiList?: () => Promise<{
+        ok: boolean;
+        text: string;
+    }>;
+}): Promise<{
+    installed: InstalledPackage[];
+    piCliAvailable: boolean;
+    detectSource: DetectSource;
+}>;
+export declare function runPiPluginsDoctor(opts?: {
+    homeDir?: string;
+    manifest?: PiPluginsManifest;
+    installed?: InstalledPackage[];
+    runPiList?: () => Promise<{
+        ok: boolean;
+        text: string;
+    }>;
+}): Promise<{
+    report: DoctorReport;
+    text: string;
+}>;
+/** Official Pi agent package (global CLI `pi`). Not auto-installed by AIWS. */
+export declare const PI_CODING_AGENT_PACKAGE = "@mariozechner/pi-coding-agent";
+/** Copy-paste install hints when `pi` is missing (detect only; never run by default). */
+export declare function formatPiCliInstallHints(): string;
+/**
+ * Detect whether Pi CLI is runnable. Inject `probe` for tests.
+ * Default: `pi --version` (or empty argv that succeeds on some builds).
+ */
+export declare function checkPiCliAvailable(opts?: {
+    probe?: () => Promise<{
+        ok: boolean;
+    }>;
+}): Promise<boolean>;
+export interface InstallRequiredResult {
+    attempted: string[];
+    results: Array<{
+        cmd: string;
+        code: number;
+        stderr: string;
+    }>;
+    /** True when install was not attempted because Pi CLI is missing. */
+    piCliMissing: boolean;
+    message?: string;
+}
+/**
+ * Install required packages only (user scope). Never silent from callers without explicit flag.
+ * Hard gate: if `pi` is not available, do not call `pi install`; return piCliMissing + hints.
+ */
+export declare function installRequiredPiPlugins(opts?: {
+    manifest?: PiPluginsManifest;
+    runInstall?: (args: string[]) => Promise<{
+        code: number;
+        stdout: string;
+        stderr: string;
+    }>;
+    /** Inject for tests; default uses checkPiCliAvailable */
+    checkPi?: () => Promise<boolean>;
+}): Promise<InstallRequiredResult>;