qlogicagent 2.13.4 → 2.13.5

package/dist/runtime/memory/recall-category-filter.js

@@ -0,0 +1,215 @@
+// ============================================================
+// P6: Recall Category Filter — scenario-aware category prioritization
+// for memory.before_recall hooks.
+//
+// Detects the user's query intent (coding, conversation, config, etc.)
+// and maps it to preferred memory categories. Hooks use these
+// preferences to boost/filter recalled memories for higher relevance.
+//
+// Scenarios:
+//   - coding → lesson, pattern (debugging, architecture, conventions)
+//   - conversation → preference, fact (user profile, project context)
+//   - config/deploy → fact, decision (ports, versions, architecture choices)
+//   - learning → lesson, pattern, skill-learning (accumulated insights)
+//
+// Reference: CC findRelevantMemories uses recentTools to exclude
+//            tool docs; we use query intent for category boosting.
+// ============================================================
+// ── Scenario Detection ──────────────────────────────────────
+/**
+ * Signal patterns for each scenario. Each pattern contributes to
+ * the scenario's confidence score.
+ */
+const SCENARIO_SIGNALS = {
+    coding: [
+        /(?:bug|error|fix|debug|报错|修复|编译|compile|build|lint)/i,
+        /(?:implement|refactor|重构|实现|代码|code|function|method|class)/i,
+        /(?:test|测试|vitest|jest|断言|assert)/i,
+        /(?:type(?:script)?|接口|interface|generic|泛型)/i,
+        /(?:import|export|module|依赖|package|npm|pnpm)/i,
+        /(?:git|commit|branch|merge|rebase|PR|MR)/i,
+    ],
+    config: [
+        /(?:deploy|部署|运维|docker|container|kubernetes|k8s)/i,
+        /(?:port|端口|config|配置|env|环境变量|.env)/i,
+        /(?:server|service|daemon|进程|systemd|nginx|redis)/i,
+        /(?:版本|version|upgrade|migrate|迁移)/i,
+        /(?:domain|域名|ssl|cert|证书|DNS)/i,
+    ],
+    conversation: [
+        /(?:你好|hi|hello|hey|请问|问一下)/i,
+        /(?:我(?:喜欢|偏好|习惯|想)|prefer|I (?:like|want|need))/i,
+        /(?:帮我|help me|能不能|可以吗|would you)/i,
+        /(?:style|风格|format|格式|命名|naming)/i,
+    ],
+    learning: [
+        /(?:best practice|最佳实践|pattern|模式|惯例|convention)/i,
+        /(?:怎么做|how to|how do|what's the|推荐|recommend)/i,
+        /(?:为什么|why|原因|reason|explain|解释)/i,
+        /(?:lesson|经验|教训|gotcha|pitfall|坑)/i,
+    ],
+    decision: [
+        /(?:should|应该|选择|choose|decision|决定|trade-?off|权衡)/i,
+        /(?:vs|versus|对比|compare|区别|difference)/i,
+        /(?:architecture|架构|方案|approach|strategy)/i,
+        /(?:pros|cons|优缺点|利弊|好处|坏处)/i,
+    ],
+    general: [], // Fallback — no signals
+};
+/**
+ * Category preferences per scenario.
+ * Ordered by relevance priority (first = highest).
+ */
+const SCENARIO_CATEGORY_MAP = {
+    coding: {
+        preferred: ["lesson", "pattern", "fact"],
+        deprioritized: ["preference"],
+    },
+    config: {
+        preferred: ["fact", "decision", "lesson"],
+        deprioritized: ["preference", "skill-learning"],
+    },
+    conversation: {
+        preferred: ["preference", "fact"],
+        deprioritized: ["pattern", "skill-learning"],
+    },
+    learning: {
+        preferred: ["lesson", "pattern", "skill-learning"],
+        deprioritized: ["preference"],
+    },
+    decision: {
+        preferred: ["decision", "fact", "lesson"],
+        deprioritized: ["skill-learning", "preference"],
+    },
+    general: {
+        preferred: [],
+        deprioritized: [],
+    },
+};
+// ── Main Entry Point ────────────────────────────────────────
+/**
+ * Detect the query scenario and return category preferences.
+ *
+ * Uses pattern matching on the user query to infer intent.
+ * Returns "general" (no filtering) when confidence is below threshold.
+ *
+ * @param query - User query text
+ * @returns Category hint with preferred/deprioritized categories
+ */
+export function detectRecallCategories(query) {
+    if (!query || query.length < 5) {
+        return { scenario: "general", preferred: [], deprioritized: [], confidence: 0 };
+    }
+    // Score each scenario
+    const scores = [];
+    for (const [scenario, patterns] of Object.entries(SCENARIO_SIGNALS)) {
+        if (scenario === "general")
+            continue;
+        const matchCount = patterns.filter(p => p.test(query)).length;
+        if (matchCount > 0) {
+            // Normalize: more patterns matched = higher confidence
+            const score = Math.min(1.0, matchCount / 2); // 2+ matches → full confidence
+            scores.push({ scenario, score });
+        }
+    }
+    // No matches → general
+    if (scores.length === 0) {
+        return { scenario: "general", preferred: [], deprioritized: [], confidence: 0 };
+    }
+    // Pick highest-scoring scenario
+    scores.sort((a, b) => b.score - a.score);
+    const winner = scores[0];
+    // Low confidence → don't filter
+    if (winner.score < 0.5) {
+        return { scenario: "general", preferred: [], deprioritized: [], confidence: winner.score };
+    }
+    const mapping = SCENARIO_CATEGORY_MAP[winner.scenario];
+    return {
+        scenario: winner.scenario,
+        preferred: mapping.preferred,
+        deprioritized: mapping.deprioritized,
+        confidence: winner.score,
+    };
+}
+// ── Scoring Adjustment ──────────────────────────────────────
+/**
+ * Apply category boost/penalty to a recall score.
+ *
+ * Used by recall hooks to adjust memory scores based on category alignment.
+ *
+ * @param baseScore - Original relevance score (0.0-1.0)
+ * @param memoryCategory - Category of the memory entry (if known)
+ * @param hint - Category hint from detectRecallCategories()
+ * @returns Adjusted score
+ */
+export function applyCategoryBoost(baseScore, memoryCategory, hint) {
+    if (!memoryCategory || hint.scenario === "general")
+        return baseScore;
+    // Preferred category: boost by 20%
+    if (hint.preferred.includes(memoryCategory)) {
+        return Math.min(1.0, baseScore * 1.2);
+    }
+    // Deprioritized category: penalize by 30%
+    if (hint.deprioritized.includes(memoryCategory)) {
+        return baseScore * 0.7;
+    }
+    // Neutral: no change
+    return baseScore;
+}
+/**
+ * Filter and re-rank a list of recalled memories based on category preferences.
+ *
+ * @param memories - Raw recalled memories with optional category
+ * @param hint - Category hint from detectRecallCategories()
+ * @param minScore - Minimum adjusted score to keep (default: 0)
+ * @returns Re-ranked memories (highest adjusted score first)
+ */
+export function filterByCategory(memories, hint, minScore = 0) {
+    if (hint.scenario === "general" || memories.length === 0)
+        return memories;
+    return memories
+        .map(m => ({
+        original: m,
+        adjustedScore: applyCategoryBoost(m.score ?? 0.5, m.category, hint),
+    }))
+        .filter(({ adjustedScore }) => adjustedScore >= minScore)
+        .sort((a, b) => b.adjustedScore - a.adjustedScore)
+        .map(({ original }) => original);
+}
+// ── Filename → Category Inference (shared utility) ──────────
+/** Prefix → category mapping for MEMDIR files. */
+const FILENAME_PREFIXES = {
+    "lesson": "lesson",
+    "debug": "lesson",
+    "gotcha": "lesson",
+    "fix": "lesson",
+    "preference": "preference",
+    "style": "preference",
+    "pattern": "pattern",
+    "convention": "pattern",
+    "practice": "pattern",
+    "fact": "fact",
+    "config": "fact",
+    "architecture": "fact",
+    "env": "fact",
+    "deploy": "fact",
+    "decision": "decision",
+    "choice": "decision",
+    "skill": "skill-learning",
+    "workflow": "skill-learning",
+};
+/**
+ * Infer memory category from filename prefix convention.
+ * E.g. "lesson-docker.md" → "lesson", "fact-ports.md" → "fact"
+ *
+ * Exported for use by recall hooks.
+ */
+export function inferCategoryFromFilename(filename) {
+    const name = filename.replace(/\.md$/, "").toLowerCase();
+    for (const [prefix, category] of Object.entries(FILENAME_PREFIXES)) {
+        if (name.startsWith(prefix + "-") || name.startsWith(prefix + "_") || name === prefix) {
+            return category;
+        }
+    }
+    return null;
+}

package/dist/runtime/permission-model.d.ts

@@ -0,0 +1,19 @@
+import type { PermissionMode, PermissionPromptCategory } from "./ports/permission-contracts.js";
+export interface PermissionPromptOption {
+    optionId: string;
+    name: string;
+    kind: "allow_once" | "allow_always" | "reject_once" | "reject_always";
+    scope?: "once" | "directory";
+}
+export interface PermissionModeDescriptor {
+    id: PermissionMode;
+    label: string;
+    summary: string;
+    description: string;
+}
+export interface PermissionModelContract {
+    modes: PermissionModeDescriptor[];
+    promptOptions: Record<PermissionPromptCategory, PermissionPromptOption[]>;
+}
+export declare function promptOptionsForCategory(category: PermissionPromptCategory): PermissionPromptOption[];
+export declare function buildPermissionModel(): PermissionModelContract;

package/dist/runtime/permission-model.js

@@ -0,0 +1,24 @@
+const MODES = [
+    { id: "default", label: "默认", summary: "工作区", description: "工作区内自动；跨区/高危确认。" },
+    { id: "auto", label: "自动", summary: "常规", description: "常规操作自动；高危确认。" },
+    { id: "full_access", label: "完全访问", summary: "全放行", description: "本轮全部自动，不再确认。" },
+];
+const PROMPT_CATEGORIES = ["cross_workspace", "high_risk_delete", "high_risk_egress", "destructive"];
+export function promptOptionsForCategory(category) {
+    if (category === "cross_workspace") {
+        return [
+            { optionId: "allow", name: "允许一次", kind: "allow_once", scope: "once" },
+            { optionId: "allow_dir", name: "本会话允许此目录", kind: "allow_always", scope: "directory" },
+            { optionId: "deny", name: "拒绝", kind: "reject_once" },
+        ];
+    }
+    const allowName = category === "high_risk_delete" ? "仍要删除" : category === "high_risk_egress" ? "仍要发送" : "允许一次";
+    return [
+        { optionId: "allow", name: allowName, kind: "allow_once", scope: "once" },
+        { optionId: "deny", name: "拒绝", kind: "reject_once" },
+    ];
+}
+export function buildPermissionModel() {
+    const promptOptions = Object.fromEntries(PROMPT_CATEGORIES.map((c) => [c, promptOptionsForCategory(c)]));
+    return { modes: MODES, promptOptions };
+}

package/dist/runtime/permission-model.test.d.ts

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

package/dist/runtime/permission-model.test.js

@@ -0,0 +1,32 @@
+import { describe, expect, it } from "vitest";
+import { buildPermissionModel, promptOptionsForCategory } from "./permission-model.js";
+describe("permission model", () => {
+    it("exposes three modes with labels/summary/description", () => {
+        const m = buildPermissionModel();
+        expect(m.modes.map((x) => x.id)).toEqual(["default", "auto", "full_access"]);
+        const def = m.modes.find((x) => x.id === "default");
+        expect(def.summary).toBe("工作区");
+        expect(def.description).toBe("工作区内自动；跨区/高危确认。");
+    });
+    it("cross_workspace options include allow_dir (allow_always, directory scope)", () => {
+        const opts = promptOptionsForCategory("cross_workspace");
+        expect(opts.map((o) => o.optionId)).toEqual(["allow", "allow_dir", "deny"]);
+        const dir = opts.find((o) => o.optionId === "allow_dir");
+        expect(dir.kind).toBe("allow_always");
+        expect(dir.scope).toBe("directory");
+    });
+    it("high-risk options are allow-once + deny only (no memory)", () => {
+        for (const c of ["high_risk_delete", "high_risk_egress", "destructive"]) {
+            const opts = promptOptionsForCategory(c);
+            expect(opts.map((o) => o.optionId)).toEqual(["allow", "deny"]);
+            expect(opts.every((o) => o.kind !== "allow_always")).toBe(true);
+        }
+        expect(promptOptionsForCategory("high_risk_delete")[0].name).toBe("仍要删除");
+    });
+    it("model.promptOptions covers every category", () => {
+        const m = buildPermissionModel();
+        for (const c of ["cross_workspace", "high_risk_delete", "high_risk_egress", "destructive"]) {
+            expect(m.promptOptions[c].length).toBeGreaterThan(0);
+        }
+    });
+});

package/dist/runtime/pet/hatch-pet-runner.d.ts

@@ -0,0 +1,18 @@
+export interface HatchPetResult {
+    ok: boolean;
+    stdout: string;
+    stderr: string;
+    code: number | null;
+}
+/** A python executable that can import Pillow, or null if none is available. Cached. */
+export declare function resolveHatchPetPython(): Promise<string | null>;
+/** The vendored hatch-pet/scripts directory, or null if missing. Cached. */
+export declare function resolveHatchPetScriptsDir(): string | null;
+/** True when both a Pillow-capable python and the vendored scripts are present. */
+export declare function isHatchPetAvailable(): Promise<boolean>;
+/** Run a vendored hatch-pet script. Throws if python/scripts are unavailable or the script is unknown. */
+export declare function runHatchPetScript(script: string, args: string[], opts?: {
+    timeoutMs?: number;
+}): Promise<HatchPetResult>;
+/** Test seam: reset memoized python/scripts resolution. */
+export declare function _resetHatchPetRunnerCache(): void;

package/dist/runtime/pet/hatch-pet-runner.js

@@ -0,0 +1,120 @@
+/**
+ * Hatch-Pet runner — spawns the vendored OpenAI Codex Hatch-Pet Python pipeline
+ * scripts (Apache-2.0, under vendor/hatch-pet) for the Petdex forge.
+ *
+ * Spawns are ASYNC (never spawnSync): a synchronous child would block the Node
+ * event loop for the whole script, freezing qlogicagent's stdio RPC channel —
+ * the exact failure mode fixed in the session-write/dispatch hardening. Python
+ * resolution is verified (the Windows Store `python.exe` alias is a no-op stub,
+ * so we only trust an executable that can actually `import PIL`) and cached.
+ *
+ * Only Pillow is required (the scripts' single third-party dependency).
+ */
+import { spawn } from "node:child_process";
+import { existsSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+const moduleDir = dirname(fileURLToPath(import.meta.url));
+let cachedPython;
+let cachedScriptsDir;
+function spawnCapture(exe, args, timeoutMs) {
+    return new Promise((resolve) => {
+        let stdout = "";
+        let stderr = "";
+        let settled = false;
+        const finish = (result) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            resolve(result);
+        };
+        const child = spawn(exe, args, { windowsHide: true });
+        const timer = setTimeout(() => {
+            child.kill("SIGKILL");
+            finish({ ok: false, stdout, stderr: `${stderr}\n[hatch-pet] timed out after ${timeoutMs}ms`, code: null });
+        }, timeoutMs);
+        timer.unref?.();
+        child.stdout?.on("data", (chunk) => { stdout += chunk.toString(); });
+        child.stderr?.on("data", (chunk) => { stderr += chunk.toString(); });
+        child.on("error", (err) => finish({ ok: false, stdout, stderr: `${stderr}${err instanceof Error ? err.message : String(err)}`, code: null }));
+        child.on("close", (code) => finish({ ok: code === 0, stdout, stderr, code }));
+    });
+}
+function pythonCandidates() {
+    const candidates = [];
+    const configured = process.env.QLOGICAGENT_PYTHON?.trim();
+    if (configured)
+        candidates.push(configured);
+    candidates.push("python3", "python", "py");
+    return candidates;
+}
+async function canImportPillow(exe) {
+    const result = await spawnCapture(exe, ["-c", "import PIL; import sys; sys.stdout.write('hatchpet-ok')"], 10_000);
+    return result.code === 0 && result.stdout.includes("hatchpet-ok");
+}
+/** A python executable that can import Pillow, or null if none is available. Cached. */
+export async function resolveHatchPetPython() {
+    if (cachedPython !== undefined)
+        return cachedPython;
+    for (const exe of pythonCandidates()) {
+        if (await canImportPillow(exe)) {
+            cachedPython = exe;
+            return exe;
+        }
+    }
+    cachedPython = null;
+    return null;
+}
+/** The vendored hatch-pet/scripts directory, or null if missing. Cached. */
+export function resolveHatchPetScriptsDir() {
+    if (cachedScriptsDir !== undefined)
+        return cachedScriptsDir;
+    const candidates = [];
+    const configured = process.env.QLOGICAGENT_HATCHPET_DIR?.trim();
+    if (configured)
+        candidates.push(join(configured, "scripts"), configured);
+    // Walk up from this module: dist/cli.js -> dist/vendor/hatch-pet/scripts (bundled),
+    // or src/runtime/pet -> <repo>/vendor/hatch-pet/scripts (dev/test).
+    let dir = moduleDir;
+    for (let i = 0; i < 7; i++) {
+        candidates.push(join(dir, "vendor", "hatch-pet", "scripts"));
+        const parent = dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    for (const candidate of candidates) {
+        if (existsSync(join(candidate, "compose_atlas.py"))) {
+            cachedScriptsDir = candidate;
+            return candidate;
+        }
+    }
+    cachedScriptsDir = null;
+    return null;
+}
+/** True when both a Pillow-capable python and the vendored scripts are present. */
+export async function isHatchPetAvailable() {
+    return (await resolveHatchPetPython()) !== null && resolveHatchPetScriptsDir() !== null;
+}
+/** Run a vendored hatch-pet script. Throws if python/scripts are unavailable or the script is unknown. */
+export async function runHatchPetScript(script, args, opts = {}) {
+    const python = await resolveHatchPetPython();
+    if (!python) {
+        throw new Error("Petdex generation requires Python with Pillow; none found (set QLOGICAGENT_PYTHON to a python that can `import PIL`)");
+    }
+    const scriptsDir = resolveHatchPetScriptsDir();
+    if (!scriptsDir) {
+        throw new Error("Vendored hatch-pet scripts not found (set QLOGICAGENT_HATCHPET_DIR)");
+    }
+    const scriptPath = join(scriptsDir, script);
+    if (!existsSync(scriptPath)) {
+        throw new Error(`Unknown hatch-pet script: ${script}`);
+    }
+    return spawnCapture(python, [scriptPath, ...args], opts.timeoutMs ?? 120_000);
+}
+/** Test seam: reset memoized python/scripts resolution. */
+export function _resetHatchPetRunnerCache() {
+    cachedPython = undefined;
+    cachedScriptsDir = undefined;
+}

package/dist/runtime/pet/hatch-pet-runner.test.d.ts

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

package/dist/runtime/pet/hatch-pet-runner.test.js

@@ -0,0 +1,28 @@
+import { beforeEach, describe, expect, it } from "vitest";
+import { _resetHatchPetRunnerCache, isHatchPetAvailable, resolveHatchPetScriptsDir, runHatchPetScript, } from "./hatch-pet-runner.js";
+describe("hatch-pet-runner", () => {
+    beforeEach(() => _resetHatchPetRunnerCache());
+    it("resolves the vendored hatch-pet scripts directory", () => {
+        const dir = resolveHatchPetScriptsDir();
+        expect(dir).toBeTruthy();
+        expect(dir).toMatch(/hatch-pet[\\/]scripts$/);
+    });
+    it("runs a vendored script when a Pillow-capable python exists, else reports unavailable", async () => {
+        const available = await isHatchPetAvailable();
+        if (!available) {
+            // No Pillow-capable python here: the runner must report unavailability,
+            // never crash — the forge degrades gracefully on this signal.
+            expect(available).toBe(false);
+            return;
+        }
+        const result = await runHatchPetScript("validate_atlas.py", ["--help"]);
+        expect(result.ok).toBe(true);
+        expect(result.stdout).toContain("usage: validate_atlas.py");
+    });
+    it("rejects an unknown script name", async () => {
+        const available = await isHatchPetAvailable();
+        if (!available)
+            return;
+        await expect(runHatchPetScript("does_not_exist.py", [])).rejects.toThrow(/Unknown hatch-pet script/);
+    });
+});

package/dist/runtime/pet/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Pet module — barrel export.
+ * Pure domain logic (types/soul/growth/reaction/petdex contract) comes from
+ * @xiaozhiclaw/pet-core; host keeps IO services + the shared reaction engine.
+ * Forge prompts live in the vendored Hatch-Pet Python pipeline, not in TS.
+ */
+export type { PetStats, PetSoul, PetBreed } from "@xiaozhiclaw/pet-core";
+export { PetGrowthEngine } from "@xiaozhiclaw/pet-core";
+export type { GrowthEvent, MoltResult, PetDisplayTrait } from "@xiaozhiclaw/pet-core";
+export { PETDEX_ANIMATION_IDS, petdexImageDataUrl, toPetdexAssetSummary } from "@xiaozhiclaw/pet-core";
+export type { PetdexAnimationId, PetdexValidationReport } from "@xiaozhiclaw/pet-core";
+export type { ReactionPool, LLMReactionContext, ReactionStyle } from "@xiaozhiclaw/pet-core";
+export { PetSoulService } from "./pet-soul-service.js";
+export { petReactionEngine } from "./pet-reaction-engine.js";
+export { PetProfileService, type PetProfile, type PetPreferences, type PetdexPetAsset, type PetdexPetAssetSummary, type JourneySnapshot } from "./pet-profile-service.js";
+export { createPetdexAssetFromSpritesheet, listBuiltinPetdexAssetIds, listBuiltinPetdexAssets, writePetdexAssetPackage } from "./petdex-asset.js";
+export { forgePetdexAsset, forgePetdexAssetPackage, readGeneratedPetdexImage } from "./petdex-forge-service.js";
+export { loadPetFile, validatePetManifest, type PetManifest, type PetFileBundle } from "./pet-file-loader.js";

package/dist/runtime/pet/index.js

@@ -0,0 +1,9 @@
+export { PetGrowthEngine } from "@xiaozhiclaw/pet-core";
+export { PETDEX_ANIMATION_IDS, petdexImageDataUrl, toPetdexAssetSummary } from "@xiaozhiclaw/pet-core";
+// Host adapters / IO / shared singleton
+export { PetSoulService } from "./pet-soul-service.js";
+export { petReactionEngine } from "./pet-reaction-engine.js";
+export { PetProfileService } from "./pet-profile-service.js";
+export { createPetdexAssetFromSpritesheet, listBuiltinPetdexAssetIds, listBuiltinPetdexAssets, writePetdexAssetPackage } from "./petdex-asset.js";
+export { forgePetdexAsset, forgePetdexAssetPackage, readGeneratedPetdexImage } from "./petdex-forge-service.js";
+export { loadPetFile, validatePetManifest } from "./pet-file-loader.js";

package/dist/runtime/pet/pet-community-assets.d.ts

@@ -0,0 +1,13 @@
+import type { CommunityInstallResolution } from "../community/community-consent-client.js";
+export interface InstalledCommunityPetResource {
+    kind: "pet";
+    status: "installed";
+    resourceId: string;
+    version: string;
+    checksum: string;
+    installDir: string;
+    name: string;
+    sanitized: boolean;
+}
+export declare function installCommunityPetResource(install: CommunityInstallResolution): Promise<InstalledCommunityPetResource>;
+export declare function assertPetInstall(install: CommunityInstallResolution): void;

package/dist/runtime/pet/pet-community-assets.js

@@ -0,0 +1,106 @@
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import { getOwnerProfileDir } from "../infra/agent-paths.js";
+import { hasPetAgentBoundaryViolationText } from "@xiaozhiclaw/pet-core";
+const SHA256_HEX_RE = /^[a-f0-9]{64}$/;
+const AGENT_INFLUENCE_FIELDS = new Set([
+    "agentInstructions",
+    "systemPrompt",
+    "tools",
+    "permissions",
+    "memoryPolicy",
+    "planningPolicy",
+    "retrievalPolicy",
+    "capabilities",
+    "abilities",
+]);
+export async function installCommunityPetResource(install) {
+    assertPetInstall(install);
+    const manifest = install.manifest;
+    const sanitized = sanitizePetManifestSummary(manifest);
+    const installDir = path.join(getOwnerProfileDir(), "pets", "community", install.id);
+    await fs.mkdir(installDir, { recursive: true });
+    await fs.writeFile(path.join(installDir, "manifest.json"), `${JSON.stringify({
+        resourceId: install.id,
+        version: install.version,
+        checksum: install.checksum,
+        name: sanitized.name,
+        persona: sanitized.persona,
+        traits: sanitized.traits,
+        assets: sanitized.assets,
+        sanitized: sanitized.sanitized,
+        installedAt: new Date().toISOString(),
+    }, null, 2)}\n`, "utf8");
+    return {
+        kind: "pet",
+        status: "installed",
+        resourceId: install.id,
+        version: install.version,
+        checksum: install.checksum,
+        installDir,
+        name: sanitized.name,
+        sanitized: sanitized.sanitized,
+    };
+}
+export function assertPetInstall(install) {
+    if (install.type !== "pet" || install.kind !== "asset") {
+        throw new Error("Community pet install requires a pet asset resource.");
+    }
+    if (install.sourceTier !== "official" && install.reviewStatus !== "approved") {
+        throw new Error("Community pet install requires approved review.");
+    }
+    if (install.effectiveRiskTier !== "R0") {
+        throw new Error("Community pet install requires R0 effective risk.");
+    }
+    if (!SHA256_HEX_RE.test(install.checksum)) {
+        throw new Error("Community pet package checksum must be a sha256 hex digest.");
+    }
+    const manifest = asRecord(install.manifest);
+    if (!manifest || manifest.schema_version !== 15 || manifest.kind !== "asset") {
+        throw new Error("Community pet install requires a v15 asset manifest.");
+    }
+    for (const field of Object.keys(manifest)) {
+        if (AGENT_INFLUENCE_FIELDS.has(field)) {
+            throw new Error("unsafe pet asset manifest contains agent instruction fields.");
+        }
+    }
+    for (const asset of readAssets(manifest)) {
+        assertSafeAssetPath(asset.path);
+    }
+}
+function sanitizePetManifestSummary(manifest) {
+    const rawName = stringValue(manifest.name) || "Community Pet";
+    const rawPersona = stringValue(manifest.persona) || "A display-only community pet.";
+    const rawTraits = Array.isArray(manifest.traits) ? manifest.traits.filter((item) => typeof item === "string") : [];
+    const name = hasPetAgentBoundaryViolationText(rawName) ? "Community Pet" : rawName;
+    const persona = hasPetAgentBoundaryViolationText(rawPersona) ? "A display-only community pet." : rawPersona;
+    const traits = rawTraits.map((trait) => hasPetAgentBoundaryViolationText(trait) ? "display-only" : trait);
+    return {
+        name,
+        persona,
+        traits,
+        assets: readAssets(manifest),
+        sanitized: name !== rawName || persona !== rawPersona || traits.some((trait, index) => trait !== rawTraits[index]),
+    };
+}
+function readAssets(manifest) {
+    if (!Array.isArray(manifest.assets))
+        return [];
+    return manifest.assets
+        .map((asset) => asRecord(asset))
+        .filter((asset) => !!asset)
+        .map((asset) => ({ kind: stringValue(asset.kind), path: stringValue(asset.path) }))
+        .filter((asset) => asset.kind && asset.path);
+}
+function assertSafeAssetPath(assetPath) {
+    const normalized = path.posix.normalize(assetPath.replace(/\\/g, "/"));
+    if (!normalized || normalized === "." || normalized.startsWith("../") || path.posix.isAbsolute(normalized)) {
+        throw new Error("unsafe pet asset path.");
+    }
+}
+function stringValue(value) {
+    return typeof value === "string" ? value.trim() : "";
+}
+function asRecord(value) {
+    return value && typeof value === "object" && !Array.isArray(value) ? value : null;
+}

package/dist/runtime/pet/pet-file-loader.d.ts

@@ -0,0 +1,5 @@
+import { type PetdexAssetManifest, type PetdexAssetPackage, type PetdexAssetValidation } from "@xiaozhiclaw/pet-core";
+export type PetManifest = PetdexAssetManifest;
+export type PetFileBundle = PetdexAssetPackage;
+export declare function loadPetFile(filePath: string): Promise<PetFileBundle>;
+export declare function validatePetManifest(manifest: unknown, spritesheet?: Buffer): PetdexAssetValidation;

package/dist/runtime/pet/pet-file-loader.js

@@ -0,0 +1,11 @@
+import { validatePetdexAssetManifest, } from "@xiaozhiclaw/pet-core";
+import { loadPetdexAssetPackage } from "./petdex-asset.js";
+export async function loadPetFile(filePath) {
+    return loadPetdexAssetPackage(filePath);
+}
+export function validatePetManifest(manifest, spritesheet) {
+    if (!spritesheet) {
+        throw new Error("Petdex manifest validation requires spritesheet.webp bytes");
+    }
+    return validatePetdexAssetManifest(manifest, spritesheet);
+}

package/dist/runtime/pet/pet-growth-engine.d.ts

@@ -0,0 +1,2 @@
+export { PetGrowthEngine } from "@xiaozhiclaw/pet-core";
+export type { GrowthEvent, MoltResult, PetDisplayTrait } from "@xiaozhiclaw/pet-core";

package/dist/runtime/pet/pet-growth-engine.js

@@ -0,0 +1 @@
+export { PetGrowthEngine } from "@xiaozhiclaw/pet-core";