@agentxm/workspace-state 0.28.4-bootstrap.0

package/dist/src/workspace/read-model/discovery/skills.js

@@ -0,0 +1,263 @@
+/**
+ * Skill discovery algorithm (3-phase: direct match, priority scan, recursive fallback).
+ *
+ * The `skillsInDir` function is used by source providers (local, git-hosting)
+ * to discover skills within a directory structure.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as FileSystem from "effect/FileSystem";
+import * as Path from "effect/Path";
+import { AGENTS } from "@agentxm/extension-model/unstable/agents/registry";
+import { AGENT_IDS } from "@agentxm/extension-model/unstable/agents/types";
+import { parsePluginManifests } from "./plugin-manifests.js";
+import { parseSkillMd } from "@agentxm/registry-protocol/unstable/content/skill-content";
+import * as Array from "effect/Array";
+import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
+import { SkillDiscoveryRootInvalid } from "../errors.js";
+import { DISCOVERY_MAX_DEPTH, DISCOVERY_SKIPPED_DIRECTORIES, } from "@agentxm/extension-model/unstable/discovery-walk";
+import { envOption } from "../../../utils/environment.js";
+/**
+ * Build a DiscoveredSkill from a skill and its directory path.
+ */
+const makeDiscoveredSkill = (skill, fullPath) => ({
+    type: "skill",
+    skill,
+    location: `file://${fullPath}`,
+});
+// -----------------------------------------------------------------------------
+// Constants
+// -----------------------------------------------------------------------------
+/**
+ * Exact filename for skill definition files.
+ */
+const SKILL_FILENAME = "SKILL.md";
+/**
+ * Canonical skill container directories for Phase 2 priority scan.
+ */
+const STATIC_PRIORITY_DIRECTORIES = [
+    "skills",
+    "skills/.curated",
+    "skills/.experimental",
+    "skills/.system",
+];
+/**
+ * Derive the full Phase 2 priority directory list.
+ *
+ * Composition:
+ * 1. `.` (searchPath root) — always first, highest priority
+ * 2. Non-agent static dirs: skills, skills/.curated, skills/.experimental, skills/.system
+ * 3. Agent dirs: unique primary and additional read paths from the AgentDescriptor registry
+ */
+export const getPriorityDirectories = () => {
+    const agentDirs = Array.dedupe(AGENT_IDS.flatMap((id) => {
+        const skills = AGENTS[id].skills;
+        return skills === undefined
+            ? []
+            : [skills.dir, ...skills.additionalReadPaths.map(({ path }) => path)];
+    }));
+    return Array.dedupe([".", ...STATIC_PRIORITY_DIRECTORIES, ...agentDirs]);
+};
+// -----------------------------------------------------------------------------
+// Internal Skill Filtering
+// -----------------------------------------------------------------------------
+const isInternalSkill = (skill) => Option.match(skill.metadata, {
+    onNone: () => false,
+    onSome: (metadata) => metadata["internal"] === "true",
+});
+const shouldIncludeSkill = (skill, options, installInternalSkills) => {
+    if (!isInternalSkill(skill))
+        return true;
+    const envVal = Option.getOrUndefined(installInternalSkills);
+    return options.includeInternal || envVal === "1" || envVal === "true";
+};
+// -----------------------------------------------------------------------------
+// Phase Helpers
+// -----------------------------------------------------------------------------
+/**
+ * Try to find and parse a SKILL.md in a given directory.
+ * Returns Option.some(Skill) if found and valid, Option.none() otherwise.
+ * All errors are silently swallowed.
+ */
+const tryParseSkillInDir = (dir) => Effect.gen(function* () {
+    const fs = yield* FileSystem.FileSystem;
+    const path = yield* Path.Path;
+    const entries = yield* fs.readDirectory(dir).pipe(Effect.option);
+    if (Option.isNone(entries))
+        return Option.none();
+    if (!entries.value.includes(SKILL_FILENAME))
+        return Option.none();
+    const fullPath = path.join(dir, SKILL_FILENAME);
+    const content = yield* fs.readFileString(fullPath).pipe(Effect.option);
+    if (Option.isNone(content))
+        return Option.none();
+    return parseSkillMd(content.value, path.basename(dir));
+});
+const discoverSkillInDir = (dir, options, installInternalSkills) => Effect.gen(function* () {
+    const skill = yield* tryParseSkillInDir(dir);
+    if (Option.isNone(skill))
+        return { foundSkillDir: false, skills: [] };
+    if (!shouldIncludeSkill(skill.value, options, installInternalSkills)) {
+        return { foundSkillDir: true, skills: [] };
+    }
+    return {
+        foundSkillDir: true,
+        skills: [makeDiscoveredSkill(skill.value, dir)],
+    };
+});
+/**
+ * Scan one level of children in a directory for skills.
+ * Each immediate subdirectory is checked for a SKILL.md.
+ */
+const scanDirectory = (dir, options, installInternalSkills) => Effect.gen(function* () {
+    const fs = yield* FileSystem.FileSystem;
+    const path = yield* Path.Path;
+    const entries = yield* fs.readDirectory(dir).pipe(Effect.option);
+    if (Option.isNone(entries))
+        return [];
+    return yield* Effect.forEach(entries.value, (entry) => Effect.gen(function* () {
+        const fullPath = path.join(dir, entry);
+        const stat = yield* fs.stat(fullPath).pipe(Effect.option);
+        if (Option.isNone(stat) || stat.value.type !== "Directory")
+            return [];
+        const discovered = yield* discoverSkillInDir(fullPath, options, installInternalSkills);
+        return discovered.skills;
+    }), { concurrency: "unbounded" }).pipe(Effect.map((results) => Array.flatten(results)));
+});
+/**
+ * Scan canonical skill containers. Each direct child may be either a skill
+ * directory or a category that contains skill directories one level deeper.
+ */
+const scanSkillContainerDirectory = (dir, options, installInternalSkills) => Effect.gen(function* () {
+    const fs = yield* FileSystem.FileSystem;
+    const path = yield* Path.Path;
+    const entries = yield* fs.readDirectory(dir).pipe(Effect.option);
+    if (Option.isNone(entries))
+        return [];
+    return yield* Effect.forEach(entries.value, (entry) => Effect.gen(function* () {
+        if (DISCOVERY_SKIPPED_DIRECTORIES.has(entry))
+            return [];
+        const fullPath = path.join(dir, entry);
+        const stat = yield* fs.stat(fullPath).pipe(Effect.option);
+        if (Option.isNone(stat) || stat.value.type !== "Directory")
+            return [];
+        const discovered = yield* discoverSkillInDir(fullPath, options, installInternalSkills);
+        if (discovered.foundSkillDir)
+            return discovered.skills;
+        const childEntries = yield* fs.readDirectory(fullPath).pipe(Effect.option);
+        if (Option.isNone(childEntries))
+            return [];
+        return yield* Effect.forEach(childEntries.value, (childEntry) => Effect.gen(function* () {
+            if (DISCOVERY_SKIPPED_DIRECTORIES.has(childEntry))
+                return [];
+            const childPath = path.join(fullPath, childEntry);
+            const childStat = yield* fs.stat(childPath).pipe(Effect.option);
+            if (Option.isNone(childStat) || childStat.value.type !== "Directory")
+                return [];
+            const childDiscovered = yield* discoverSkillInDir(childPath, options, installInternalSkills);
+            return childDiscovered.skills;
+        }), { concurrency: "unbounded" }).pipe(Effect.map((results) => Array.flatten(results)));
+    }), { concurrency: "unbounded" }).pipe(Effect.map((results) => Array.flatten(results)));
+});
+const scanPriorityDirectory = (priorityDir, fullDir, options, installInternalSkills) => priorityDir === "."
+    ? scanDirectory(fullDir, options, installInternalSkills)
+    : scanSkillContainerDirectory(fullDir, options, installInternalSkills);
+/**
+ * Recursive DFS scan with depth limit.
+ * Skips well-known non-skill directories.
+ */
+const recursiveScan = (dir, options, depth, installInternalSkills) => Effect.gen(function* () {
+    if (depth > DISCOVERY_MAX_DEPTH)
+        return [];
+    const fs = yield* FileSystem.FileSystem;
+    const path = yield* Path.Path;
+    const entries = yield* fs.readDirectory(dir).pipe(Effect.option);
+    if (Option.isNone(entries))
+        return [];
+    return yield* Effect.forEach(entries.value, (entry) => Effect.gen(function* () {
+        if (DISCOVERY_SKIPPED_DIRECTORIES.has(entry))
+            return [];
+        const fullPath = path.join(dir, entry);
+        const stat = yield* fs.stat(fullPath).pipe(Effect.option);
+        if (Option.isNone(stat) || stat.value.type !== "Directory")
+            return [];
+        const discovered = yield* discoverSkillInDir(fullPath, options, installInternalSkills);
+        if (discovered.foundSkillDir)
+            return discovered.skills;
+        // Recurse into subdirectories
+        const subResults = yield* recursiveScan(fullPath, options, depth + 1, installInternalSkills);
+        return subResults;
+    }), { concurrency: "unbounded" }).pipe(Effect.map((results) => Array.flatten(results)));
+});
+// -----------------------------------------------------------------------------
+// 3-Phase Discovery
+// -----------------------------------------------------------------------------
+/**
+ * Discover skills in a directory using a 3-phase algorithm:
+ *
+ * Phase 1 — Direct match: check if search root itself contains SKILL.md
+ * Phase 2 — Priority directory scan: scan well-known directories one level deep
+ * Phase 3 — Recursive fallback: bounded DFS when prior phases find nothing or fullDepth is true
+ *
+ * Skills are deduplicated by name (first-found wins). Internal skills are
+ * filtered unless opted in.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export const skillsInDir = (basePath, subPath, options) => Effect.gen(function* () {
+    const fs = yield* FileSystem.FileSystem;
+    const path = yield* Path.Path;
+    const installInternalSkills = yield* envOption("INSTALL_INTERNAL_SKILLS");
+    // Compute effective search root
+    const searchRoot = Option.match(subPath, {
+        onNone: () => basePath,
+        onSome: (p) => path.join(basePath, p),
+    });
+    // Verify the search root exists and is a directory
+    const stat = yield* fs
+        .stat(searchRoot)
+        .pipe(Effect.mapError((error) => new SkillDiscoveryRootInvalid({ searchRoot, problem: "inaccessible", cause: error })));
+    if (stat.type !== "Directory") {
+        return yield* new SkillDiscoveryRootInvalid({ searchRoot, problem: "not-directory" });
+    }
+    // ── Phase 1: Direct Match ──────────────────────────────────────────
+    const rootSkill = yield* tryParseSkillInDir(searchRoot);
+    const phase1Skills = Option.isSome(rootSkill) &&
+        shouldIncludeSkill(rootSkill.value, options, installInternalSkills)
+        ? [makeDiscoveredSkill(rootSkill.value, searchRoot)]
+        : [];
+    if (phase1Skills.length > 0 && !options.fullDepth) {
+        return phase1Skills;
+    }
+    // ── Phase 2: Priority Directory Scan ───────────────────────────────
+    // Collect manifest-declared directories to append to priority scan
+    const manifestDirs = yield* parsePluginManifests(searchRoot);
+    // Build full list of directories to scan: derived priority dirs + manifest dirs
+    const priorityDirs = getPriorityDirectories();
+    const priorityFullDirs = priorityDirs.map((priorityDir) => priorityDir === "." ? searchRoot : path.join(searchRoot, priorityDir));
+    // Deduplicate manifest dirs against static priority dirs
+    const manifestDirsToAdd = manifestDirs.filter((d) => !priorityFullDirs.includes(d));
+    const priorityEntries = [
+        ...priorityDirs.map((priorityDir) => ({
+            priorityDir,
+            fullDir: priorityDir === "." ? searchRoot : path.join(searchRoot, priorityDir),
+        })),
+        ...manifestDirsToAdd.map((fullDir) => ({ priorityDir: ".", fullDir })),
+    ];
+    const phase2Skills = yield* Effect.forEach(priorityEntries, ({ priorityDir, fullDir }) => scanPriorityDirectory(priorityDir, fullDir, options, installInternalSkills), { concurrency: "unbounded" }).pipe(Effect.map((results) => Array.flatten(results)));
+    // ── Phase 3: Recursive Fallback ────────────────────────────────────
+    const shouldRunPhase3 = (phase1Skills.length === 0 && phase2Skills.length === 0) || options.fullDepth;
+    const phase3Skills = shouldRunPhase3
+        ? yield* recursiveScan(searchRoot, options, 0, installInternalSkills)
+        : [];
+    // Deduplicate by name (first-found wins across phases)
+    const seen = new Set();
+    return [...phase1Skills, ...phase2Skills, ...phase3Skills].filter(({ skill: { name } }) => {
+        if (seen.has(name))
+            return false;
+        seen.add(name);
+        return true;
+    });
+});
+//# sourceMappingURL=skills.js.map

package/dist/src/workspace/read-model/discovery/subagents.d.ts

@@ -0,0 +1,37 @@
+/**
+ * WorkspaceReadModel discovery capability for agent subagent files.
+ */
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as Path from "effect/Path";
+import { SubagentScanFailed } from "../errors.js";
+export interface DetectedSubagentFile {
+    /** File path relative to the project directory */
+    readonly path: string;
+}
+export interface AgentSubagentSummary {
+    /** Agent identifier */
+    readonly agentId: string;
+    /** Agent display name */
+    readonly agentName: string;
+    /** Subagent directory path relative to project */
+    readonly subagentDir: string;
+    /** Detected subagent files */
+    readonly files: ReadonlyArray<DetectedSubagentFile>;
+}
+export declare const scanAgentSubagentFiles: (agentId: string, projectDir: string) => Effect.Effect<{
+    path: string;
+}[] | readonly [{
+    readonly path: string;
+}], SubagentScanFailed, FileSystem.FileSystem | Path.Path> | Effect.Effect<readonly DetectedSubagentFile[], never, never>;
+export declare const scanAllSubagentFiles: (projectDir: string) => Effect.Effect<{
+    agentId: "adal" | "aider-desk" | "amp" | "antigravity" | "antigravity-cli" | "augment" | "claude-code" | "cline" | "codearts-agent" | "codebuddy" | "codemaker" | "codestudio" | "codex" | "command-code" | "continue" | "cortex" | "crush" | "cursor" | "deepagents" | "devin" | "dexto" | "droid" | "firebender" | "forgecode" | "gemini-cli" | "github-copilot-cli" | "goose" | "grok-cli" | "hermes" | "ibm-bob" | "iflow-cli" | "junie" | "lingma" | "kilo" | "kimi-cli" | "kiro-cli" | "kode" | "mcpjam" | "minimax-code" | "mistral-vibe" | "mux" | "neovate" | "openclaw" | "opencode" | "openhands" | "ona" | "pi" | "pochi" | "qoder" | "qoder-cn" | "qwen-code" | "replit" | "roo" | "rovodev" | "tabnine-cli" | "trae-cn" | "trae" | "warp" | "windsurf" | "zencoder" | "zed" | "zenflow" | "universal";
+    agentName: string;
+    subagentDir: string;
+    files: {
+        path: string;
+    }[] | readonly [{
+        readonly path: string;
+    }];
+}[], SubagentScanFailed, FileSystem.FileSystem | Path.Path>;
+//# sourceMappingURL=subagents.d.ts.map

package/dist/src/workspace/read-model/discovery/subagents.js

@@ -0,0 +1,48 @@
+/**
+ * WorkspaceReadModel discovery capability for agent subagent files.
+ */
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as Path from "effect/Path";
+import { SubagentScanFailed } from "../errors.js";
+import { AGENTS } from "@agentxm/extension-model/unstable/agents/registry";
+const isKnownAgentId = (id) => Object.hasOwn(AGENTS, id);
+const scanKnownAgentSubagentFiles = (agent, projectDir) => Effect.gen(function* () {
+    const subagents = agent.subagents;
+    if (subagents === undefined)
+        return [];
+    const fs = yield* FileSystem.FileSystem;
+    const p = yield* Path.Path;
+    const subagentPath = p.resolve(projectDir, subagents.dir);
+    const exists = yield* fs.exists(subagentPath);
+    if (!exists)
+        return [];
+    if (subagents.isFile === true) {
+        return [{ path: subagents.dir }];
+    }
+    const entries = yield* fs.readDirectory(subagentPath);
+    const files = yield* Effect.filter(entries, (entry) => Effect.gen(function* () {
+        const stat = yield* fs.stat(p.join(subagentPath, entry));
+        return stat.type === "File";
+    }), { concurrency: "unbounded" });
+    return yield* Effect.forEach(files, (file) => Effect.succeed({
+        path: p.join(subagents.dir, file),
+    }), { concurrency: "unbounded" });
+}).pipe(Effect.mapError((error) => new SubagentScanFailed({ agentName: agent.name, cause: error })));
+export const scanAgentSubagentFiles = (agentId, projectDir) => isKnownAgentId(agentId)
+    ? scanKnownAgentSubagentFiles(AGENTS[agentId], projectDir)
+    : Effect.succeed([]);
+export const scanAllSubagentFiles = (projectDir) => Effect.gen(function* () {
+    const agentsWithSubagents = Object.values(AGENTS).filter((agent) => agent.subagents !== undefined);
+    const results = yield* Effect.forEach(agentsWithSubagents, (agent) => Effect.gen(function* () {
+        const files = yield* scanKnownAgentSubagentFiles(agent, projectDir);
+        return {
+            agentId: agent.id,
+            agentName: agent.name,
+            subagentDir: agent.subagents?.dir ?? "",
+            files,
+        };
+    }), { concurrency: "unbounded" });
+    return results.filter((result) => result.files.length > 0);
+});
+//# sourceMappingURL=subagents.js.map

package/dist/src/workspace/read-model/errors.d.ts

@@ -0,0 +1,93 @@
+/** Per-source tagged error families for WorkspaceReadModel source-backed cells. */
+declare const SettingsIoError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "SettingsIoError";
+} & Readonly<A>;
+/** Settings file IO failure (unreadable, permission denied, lower-level error). */
+export declare class SettingsIoError extends SettingsIoError_base<{
+    readonly path: string;
+    readonly cause: unknown;
+}> {
+}
+declare const SettingsParseError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "SettingsParseError";
+} & Readonly<A>;
+/** Settings JSON parse failure; `raw` carries the unparsed text. */
+export declare class SettingsParseError extends SettingsParseError_base<{
+    readonly path: string;
+    readonly raw: string;
+    readonly cause: unknown;
+}> {
+}
+declare const SettingsDecodeError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "SettingsDecodeError";
+} & Readonly<A>;
+/** Settings schema decode failure; `raw` carries the parsed value. */
+export declare class SettingsDecodeError extends SettingsDecodeError_base<{
+    readonly path: string;
+    readonly issues: ReadonlyArray<string>;
+    readonly raw: unknown;
+}> {
+}
+/** Settings-read failure union (IO, parse, decode). */
+export type SettingsReadError = SettingsIoError | SettingsParseError | SettingsDecodeError;
+declare const LockfileIoError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "LockfileIoError";
+} & Readonly<A>;
+/** Lockfile IO failure. */
+export declare class LockfileIoError extends LockfileIoError_base<{
+    readonly path: string;
+    readonly cause: unknown;
+}> {
+}
+declare const LockfileParseError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "LockfileParseError";
+} & Readonly<A>;
+/** Lockfile YAML parse failure; `raw` carries the unparsed text. */
+export declare class LockfileParseError extends LockfileParseError_base<{
+    readonly path: string;
+    readonly raw: string;
+    readonly cause: unknown;
+}> {
+}
+declare const LockfileDecodeError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "LockfileDecodeError";
+} & Readonly<A>;
+/** Lockfile schema decode failure; `raw` carries the parsed value. */
+export declare class LockfileDecodeError extends LockfileDecodeError_base<{
+    readonly path: string;
+    readonly issues: ReadonlyArray<string>;
+    readonly raw: unknown;
+}> {
+}
+/** Lockfile-read failure union (IO, parse, decode). */
+export type LockfileReadError = LockfileIoError | LockfileParseError | LockfileDecodeError;
+declare const WorkspaceRootEscape_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "WorkspaceRootEscape";
+} & Readonly<A>;
+/** Provider-construction error: workspace root escapes the configured allowed root. */
+export declare class WorkspaceRootEscape extends WorkspaceRootEscape_base<{
+    readonly workspaceRoot: string;
+    readonly allowedRoot: string;
+}> {
+}
+declare const SkillDiscoveryRootInvalid_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "SkillDiscoveryRootInvalid";
+} & Readonly<A>;
+/** The skill discovery search root is missing, inaccessible, or not a directory. */
+export declare class SkillDiscoveryRootInvalid extends SkillDiscoveryRootInvalid_base<{
+    readonly searchRoot: string;
+    readonly problem: "inaccessible" | "not-directory";
+    readonly cause?: unknown;
+}> {
+}
+declare const SubagentScanFailed_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "SubagentScanFailed";
+} & Readonly<A>;
+/** Scanning an agent's subagent files failed. */
+export declare class SubagentScanFailed extends SubagentScanFailed_base<{
+    readonly agentName: string;
+    readonly cause: unknown;
+}> {
+}
+export {};
+//# sourceMappingURL=errors.d.ts.map

package/dist/src/workspace/read-model/errors.js

@@ -0,0 +1,30 @@
+/** Per-source tagged error families for WorkspaceReadModel source-backed cells. */
+import * as Data from "effect/Data";
+/** Settings file IO failure (unreadable, permission denied, lower-level error). */
+export class SettingsIoError extends Data.TaggedError("SettingsIoError") {
+}
+/** Settings JSON parse failure; `raw` carries the unparsed text. */
+export class SettingsParseError extends Data.TaggedError("SettingsParseError") {
+}
+/** Settings schema decode failure; `raw` carries the parsed value. */
+export class SettingsDecodeError extends Data.TaggedError("SettingsDecodeError") {
+}
+/** Lockfile IO failure. */
+export class LockfileIoError extends Data.TaggedError("LockfileIoError") {
+}
+/** Lockfile YAML parse failure; `raw` carries the unparsed text. */
+export class LockfileParseError extends Data.TaggedError("LockfileParseError") {
+}
+/** Lockfile schema decode failure; `raw` carries the parsed value. */
+export class LockfileDecodeError extends Data.TaggedError("LockfileDecodeError") {
+}
+/** Provider-construction error: workspace root escapes the configured allowed root. */
+export class WorkspaceRootEscape extends Data.TaggedError("WorkspaceRootEscape") {
+}
+/** The skill discovery search root is missing, inaccessible, or not a directory. */
+export class SkillDiscoveryRootInvalid extends Data.TaggedError("SkillDiscoveryRootInvalid") {
+}
+/** Scanning an agent's subagent files failed. */
+export class SubagentScanFailed extends Data.TaggedError("SubagentScanFailed") {
+}
+//# sourceMappingURL=errors.js.map

package/dist/src/workspace/read-model/extensions/actual-helpers.d.ts

@@ -0,0 +1,4 @@
+export declare const filterMapOccurrences: <TOccurrence extends {
+    readonly type: string;
+}, A>(occurrences: ReadonlyArray<TOccurrence>, type: TOccurrence["type"], map: (occurrence: TOccurrence) => A) => ReadonlyArray<A>;
+//# sourceMappingURL=actual-helpers.d.ts.map

package/dist/src/workspace/read-model/extensions/actual-helpers.js

@@ -0,0 +1,4 @@
+import * as Array from "effect/Array";
+import * as Option from "effect/Option";
+export const filterMapOccurrences = (occurrences, type, map) => Array.getSomes(occurrences.map((occurrence) => occurrence.type === type ? Option.some(map(occurrence)) : Option.none()));
+//# sourceMappingURL=actual-helpers.js.map

package/dist/src/workspace/read-model/extensions/hook.d.ts

@@ -0,0 +1,104 @@
+/**
+ * Hook subject module: declared/resolved/actual payloads, scanner composition,
+ * and projections via the shared helper.
+ *
+ * Declared hooks come from `settings.hooks`; resolved hooks come from
+ * `axm-lock.yaml` `hooks`. Actual occurrences come exclusively from the
+ * canonical-extensions scanner (`type === "hook"`), which enumerates
+ * project-authored `hooks/<name>/src`, project-acquired
+ * `agent_extensions/<source>/<source-full-name>`, and user-scope packages.
+ *
+ * The hook installer also writes agent-side derived artifacts — managed hook
+ * groups inside agent settings files and the advisory-rule fallback region.
+ * Those are renderings of an installed hook, not separate materializations, so
+ * they are deliberately NOT occurrences: the family derives `actual` from the
+ * canonical scanner alone and an agent-side rendering never produces an
+ * unmanaged row.
+ */
+import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
+import { type ExtensionName } from "@agentxm/extension-model/unstable/extensions/common";
+import type { HookLockEntry, Lockfile } from "../../../lockfile/schema.js";
+import type { HookEntry, Settings } from "../../../settings/schema.js";
+import type { Diagnostics } from "../diagnostics.js";
+import type { LockfileReadError, SettingsReadError } from "../errors.js";
+import type { CanonicalExtensionOccurrence } from "../scanners/types.js";
+import type { ActivationState, ExtensionKey, InstallationOrigin, InstalledPackRef, Scope } from "../types.js";
+export type HookDetectionOrigin = {
+    readonly _tag: "canonical-axm-hook";
+} | {
+    readonly _tag: "external-axm-hook";
+};
+export interface DeclaredHook {
+    readonly name: ExtensionName;
+    readonly entry: HookEntry;
+}
+export type DeclaredHooks = ReadonlyArray<DeclaredHook>;
+export interface ResolvedHook {
+    readonly name: ExtensionName;
+    readonly lockEntry: HookLockEntry;
+}
+export type ResolvedHooks = ReadonlyArray<ResolvedHook>;
+export interface ActualHook {
+    readonly key: ExtensionKey<"hook">;
+    readonly origin: HookDetectionOrigin;
+    readonly contentRoot: string;
+    readonly packageRoot: string | null;
+}
+export type ActualHooks = ReadonlyArray<ActualHook>;
+export interface HookPackMember {
+    readonly name: ExtensionName;
+    readonly providingPack: InstalledPackRef;
+}
+export interface InstalledHook {
+    readonly key: ExtensionKey<"hook">;
+    readonly installationOrigin: InstallationOrigin<DeclaredHook, HookPackMember>;
+    readonly activation: ActivationState;
+    readonly resolved: Option.Option<ResolvedHook>;
+    readonly actual: ReadonlyArray<ActualHook>;
+    readonly providingPacks: ReadonlyArray<InstalledPackRef>;
+}
+export interface UnmanagedHook {
+    readonly key: ExtensionKey<"hook">;
+    readonly actual: ActualHook;
+}
+/**
+ * Hook scanners. Hook packages materialize only in canonical package roots,
+ * so the canonical scanner is the sole input; agent-side managed hook groups are
+ * renderings of an installed hook rather than independent materializations.
+ */
+export interface HookScanners {
+    readonly canonical: Effect.Effect<ReadonlyArray<CanonicalExtensionOccurrence>>;
+}
+export interface HookScopedLoaders {
+    readonly settings: Effect.Effect<Option.Option<Settings>, SettingsReadError>;
+    readonly lockfile: Effect.Effect<Option.Option<Lockfile>, LockfileReadError>;
+}
+export interface InstalledPackForHooks {
+    readonly ref: InstalledPackRef;
+    readonly hooks: ReadonlyArray<HookPackMember>;
+}
+export interface HookExtensionsApiDeps {
+    readonly scope: Scope;
+    readonly loaders: HookScopedLoaders;
+    readonly scanners: HookScanners;
+    readonly installedPacks: Effect.Effect<ReadonlyArray<InstalledPackForHooks>, SettingsReadError | LockfileReadError>;
+    readonly diagnostics: Diagnostics;
+}
+export interface HookExtensionsApi {
+    readonly declared: Effect.Effect<Option.Option<DeclaredHooks>, SettingsReadError>;
+    readonly resolved: Effect.Effect<Option.Option<ResolvedHooks>, LockfileReadError>;
+    readonly actual: Effect.Effect<ActualHooks>;
+    readonly installed: Effect.Effect<ReadonlyArray<InstalledHook>, SettingsReadError | LockfileReadError>;
+    readonly byName: (name: string) => Effect.Effect<Option.Option<InstalledHook>, SettingsReadError | LockfileReadError>;
+    readonly declaredByName: (name: string) => Effect.Effect<Option.Option<DeclaredHook>, SettingsReadError>;
+    readonly active: Effect.Effect<ReadonlyArray<InstalledHook>, SettingsReadError | LockfileReadError>;
+    readonly unmanaged: Effect.Effect<ReadonlyArray<UnmanagedHook>, SettingsReadError | LockfileReadError>;
+}
+/**
+ * Build the hook subject API. Returns an `Effect` because the projection
+ * cell is wrapped in `Effect.cached` so the four derived cells share one
+ * in-flight execution per scope, mirroring `state.ts`.
+ */
+export declare const makeHookExtensionsApi: (deps: HookExtensionsApiDeps) => Effect.Effect<HookExtensionsApi>;
+//# sourceMappingURL=hook.d.ts.map