@agentxm/workspace-state 0.28.4-bootstrap.0

package/dist/src/workspace/read-model/__fixtures__/occurrences.js

@@ -0,0 +1,134 @@
+/**
+ * Test fixture builders for scanner occurrences.
+ *
+ * Per the Wave 1A scanner contract, every `CanonicalExtensionOccurrence` and
+ * `AgentDirOccurrence` carries `pathSegments`, `subjectFile`, and
+ * `subjectFileExists` in addition to its identifying fields. These factories
+ * compute those derived fields from minimal inputs so test sites supply only
+ * the discriminators they care about.
+ *
+ * `McpConfigOccurrence` carries a discriminated physical surface. Shared
+ * observations omit agent identity; agent-native observations retain it.
+ */
+import * as Option from "effect/Option";
+import * as Schema from "effect/Schema";
+import { decodeExtensionNameSync, } from "@agentxm/extension-model/unstable/extensions/common";
+import { decodeHandleSync } from "@agentxm/extension-model/unstable/extensions/handle";
+import { AbsolutePathSchema, } from "@agentxm/extension-model/unstable/path-types";
+// ---------------------------------------------------------------------------
+// Path helpers (POSIX, since fixtures synthesize POSIX paths)
+// ---------------------------------------------------------------------------
+const POSIX_SEP = "/";
+const splitSegments = (absolute) => absolute.split(POSIX_SEP);
+const join = (parent, child) => parent.endsWith(POSIX_SEP) ? `${parent}${child}` : `${parent}${POSIX_SEP}${child}`;
+const decodeFixtureAbsolutePath = Schema.decodeUnknownSync(AbsolutePathSchema);
+const normalizeFileBackedName = (name) => {
+    const normalized = name
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .slice(0, 64)
+        .replace(/-+$/g, "");
+    return normalized === "" ? "unnamed" : normalized;
+};
+// ---------------------------------------------------------------------------
+// Subject file mapping (must match scanners/canonical-extensions.ts /
+// scanners/agent-dir.ts)
+// ---------------------------------------------------------------------------
+const subjectFileNameForExtensionType = (type, name) => {
+    switch (type) {
+        case "skill":
+            return "SKILL.md";
+        case "subagent":
+            return `${name}.md`;
+        default:
+            return null;
+    }
+};
+const subjectFileNameForAgentDir = (type, name) => {
+    switch (type) {
+        case "skill":
+            return "SKILL.md";
+        case "subagent":
+            return `${name}.md`;
+    }
+};
+/**
+ * Build a `CanonicalExtensionOccurrence` with the new structural fields
+ * populated. `pathSegments` is computed from `contentLocation` (POSIX split).
+ * `subjectFile` is `Some(<dir>/<name>.md)` for skill/subagent; `None` for
+ * mcp-server/rule/hook/knowledge/pack. `subjectFileExists` defaults to `true` when
+ * the subject has a canonical primary file; pass `false` to model absence.
+ */
+export const makeCanonicalOccurrence = (input) => {
+    const subjectFileName = subjectFileNameForExtensionType(input.type, input.name);
+    const contentLocation = decodeFixtureAbsolutePath(input.contentLocation);
+    const subjectFile = subjectFileName === null
+        ? Option.none()
+        : Option.some(decodeFixtureAbsolutePath(join(input.contentLocation, subjectFileName)));
+    const subjectFileExists = input.subjectFileExists ?? (subjectFileName === null ? false : true);
+    return {
+        _tag: "canonical-extension",
+        scope: input.scope,
+        type: input.type,
+        origin: input.origin,
+        name: decodeExtensionNameSync(input.name),
+        owner: input.owner === null ? null : decodeHandleSync(input.owner),
+        contentLocation,
+        pathSegments: splitSegments(input.contentLocation),
+        subjectFile,
+        subjectFileExists,
+    };
+};
+/**
+ * Build an `AgentDirOccurrence` with the new structural fields populated.
+ * `pathSegments` is computed from `contentLocation` (POSIX split).
+ * `subjectFile` is `<contentLocation>/<canonical-file>` for directory
+ * occurrences and the `contentLocation` itself for single-file subagent
+ * surfaces. `subjectFileExists` defaults to `true`.
+ */
+export const makeAgentDirOccurrence = (input) => {
+    const resolvedName = input.singleFile === true ? normalizeFileBackedName(input.name) : input.name;
+    const subjectFileName = subjectFileNameForAgentDir(input.type, resolvedName);
+    const contentLocation = decodeFixtureAbsolutePath(input.contentLocation);
+    const subjectFile = input.singleFile === true
+        ? Option.some(contentLocation)
+        : subjectFileName === null
+            ? Option.none()
+            : Option.some(decodeFixtureAbsolutePath(join(input.contentLocation, subjectFileName)));
+    const subjectFileExists = input.subjectFileExists ?? true;
+    return {
+        _tag: "agent-dir",
+        scope: input.scope,
+        type: input.type,
+        agentId: input.agentId,
+        name: resolvedName,
+        contentLocation,
+        pathSegments: splitSegments(input.contentLocation),
+        subjectFile,
+        subjectFileExists,
+    };
+};
+export const makeWorkspaceMcpConfigOccurrence = (input) => ({
+    _tag: "mcp-config",
+    scope: input.scope,
+    surface: { _tag: "shared" },
+    name: decodeExtensionNameSync(input.name),
+    contentLocation: decodeFixtureAbsolutePath(input.contentLocation),
+    config: input.config ?? {},
+});
+export const makeAgentMcpConfigOccurrence = (input) => ({
+    _tag: "mcp-config",
+    scope: input.scope,
+    surface: { _tag: "agent", agentId: input.agentId },
+    name: decodeExtensionNameSync(input.name),
+    contentLocation: decodeFixtureAbsolutePath(input.contentLocation),
+    config: input.config ?? {},
+});
+export const makeAgentSettingsOccurrence = (input) => ({
+    _tag: "agent-settings",
+    scope: input.scope,
+    agentId: input.agentId,
+    contentLocation: decodeFixtureAbsolutePath(input.contentLocation),
+});
+//# sourceMappingURL=occurrences.js.map

package/dist/src/workspace/read-model/__fixtures__/scenario-harness.d.ts

@@ -0,0 +1,99 @@
+/**
+ * Scenario-test harness for the workspace read-model capability.
+ *
+ * Each scenario file under `__tests__/scenarios/` consumes this harness:
+ *
+ * - `runScenario(spec, body)` builds both scopes via
+ *   {@link makeWorkspaceReadModel} against the in-memory fixture FS, exposes
+ *   them through a thin `ctx.scope(scope)` selector so scenarios can yield
+ *   from either scope, and runs `body` with the result.
+ * - `expectFirst(arr)` asserts the array is non-empty and returns its first
+ *   element, replacing the silent `if (entry === undefined) return` pattern.
+ * - `expectDiagnostics(ctx, scope, predicate)` reads the scoped diagnostics
+ *   buffer once and asserts at least one warning matches `predicate`.
+ * - `tagsOf(cause)` extracts the tagged-error `_tag` set from an `Effect.Cause`
+ *   so the ≤3-tag assertion in 10.2 stays compact.
+ *
+ * The harness is a leading-underscore module so vitest does not pick it up as
+ * a test file.
+ */
+import * as Cause from "effect/Cause";
+import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
+import * as Result from "effect/Result";
+import type { WorkspaceReadModelTestOptions } from "./test-layer.js";
+import type { FixtureSpec, PathEscapeError } from "./builder.js";
+import type { Warning } from "../diagnostics.js";
+import type { WorkspaceRootEscape } from "../errors.js";
+import { type WorkspaceReadModel } from "../service.js";
+import type { Scope } from "../types.js";
+/**
+ * Scenario-side wrapper exposing both scopes through a `scope(scope)`
+ * selector. Both scopes are pre-built via {@link makeWorkspaceReadModel} so
+ * scenarios can yield from either scope freely. The selector returns a
+ * memoized {@link WorkspaceReadModel} per scope.
+ */
+export interface WorkspaceReadModelScenarioCtx {
+    readonly scope: (scope: Scope) => WorkspaceReadModel;
+}
+/**
+ * Default workspace and user-home roots used by scenario specs. Tests may
+ * override per-spec by passing different values when constructing a
+ * `FixtureSpec`.
+ */
+export declare const SCENARIO_WORKSPACE_ROOT = "/scenario/workspace";
+export declare const SCENARIO_USER_HOME = "/scenario/home";
+/**
+ * Build per-scope read models against the supplied fixture spec, provide them
+ * to `body`, and run the resulting effect. Both scopes are constructed
+ * eagerly so the body can yield from either scope without re-running the
+ * factory.
+ *
+ * The body's `E` channel is preserved through to the harness's return type
+ * so scenario tests can `yield*` source-backed cells (which fail with
+ * `SettingsReadError` / `LockfileReadError`) directly without wrapping every
+ * call site in `Effect.result`.
+ */
+export declare const runScenario: <A, E = never>(spec: FixtureSpec, body: (ctx: WorkspaceReadModelScenarioCtx) => Effect.Effect<A, E>, options?: WorkspaceReadModelTestOptions) => Effect.Effect<A, E | WorkspaceRootEscape | PathEscapeError>;
+/**
+ * Assert that `arr` is non-empty and return its first element. Replaces the
+ * silent `if (entry === undefined) return` pattern that lets a misshapen
+ * array silently pass a test.
+ */
+export declare const expectFirst: <T>(arr: ReadonlyArray<T>, message?: string) => T;
+/**
+ * Assert that `option` is `Option.Some` and return its inner value. Replaces
+ * the `expect(Option.isSome(opt)).toBe(true); if (!Option.isSome(opt)) return;`
+ * pattern that loses the failure message and lets misshapen values silently
+ * pass a test.
+ */
+export declare const expectSome: <T>(option: Option.Option<T>, message?: string) => T;
+/**
+ * Assert that `result` is a `Result.Success` and return its success value.
+ * Replaces `expect(result._tag).toBe("Success"); if (result._tag === ...)`
+ * narrowing chains.
+ */
+export declare const expectSuccess: <A, E>(result: Result.Result<A, E>, message?: string) => A;
+/**
+ * Assert that `result` is a `Result.Failure` and return its failure value.
+ * Replaces `expect(result._tag).toBe("Failure"); if (result._tag === ...)`
+ * narrowing chains.
+ */
+export declare const expectFailure: <A, E>(result: Result.Result<A, E>, message?: string) => E;
+/**
+ * Extract the set of tagged-error `_tag` values reachable inside a `Cause`.
+ * Used for the ≤3-tag-per-cell quality constraint assertion.
+ */
+export declare const tagsOf: <E>(cause: Cause.Cause<E>) => ReadonlySet<string>;
+/**
+ * Read the scoped diagnostics buffer once and assert at least one warning
+ * matches `predicate`. Returns the matching warnings so callers can chain
+ * additional assertions.
+ */
+export declare const expectDiagnostics: (ctx: WorkspaceReadModelScenarioCtx, scope: Scope, predicate: (warning: Warning) => boolean) => Effect.Effect<ReadonlyArray<Warning>>;
+/**
+ * Snapshot the scoped diagnostics buffer without asserting. Useful when a
+ * scenario wants to verify the absence of a warning class.
+ */
+export declare const readDiagnostics: (ctx: WorkspaceReadModelScenarioCtx, scope: Scope) => Effect.Effect<ReadonlyArray<Warning>>;
+//# sourceMappingURL=scenario-harness.d.ts.map

package/dist/src/workspace/read-model/__fixtures__/scenario-harness.js

@@ -0,0 +1,142 @@
+/**
+ * Scenario-test harness for the workspace read-model capability.
+ *
+ * Each scenario file under `__tests__/scenarios/` consumes this harness:
+ *
+ * - `runScenario(spec, body)` builds both scopes via
+ *   {@link makeWorkspaceReadModel} against the in-memory fixture FS, exposes
+ *   them through a thin `ctx.scope(scope)` selector so scenarios can yield
+ *   from either scope, and runs `body` with the result.
+ * - `expectFirst(arr)` asserts the array is non-empty and returns its first
+ *   element, replacing the silent `if (entry === undefined) return` pattern.
+ * - `expectDiagnostics(ctx, scope, predicate)` reads the scoped diagnostics
+ *   buffer once and asserts at least one warning matches `predicate`.
+ * - `tagsOf(cause)` extracts the tagged-error `_tag` set from an `Effect.Cause`
+ *   so the ≤3-tag assertion in 10.2 stays compact.
+ *
+ * The harness is a leading-underscore module so vitest does not pick it up as
+ * a test file.
+ */
+import * as Cause from "effect/Cause";
+import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
+import * as Result from "effect/Result";
+import { WorkspaceReadModelTest } from "./test-layer.js";
+import { makeWorkspaceReadModel } from "../service.js";
+/**
+ * Default workspace and user-home roots used by scenario specs. Tests may
+ * override per-spec by passing different values when constructing a
+ * `FixtureSpec`.
+ */
+export const SCENARIO_WORKSPACE_ROOT = "/scenario/workspace";
+export const SCENARIO_USER_HOME = "/scenario/home";
+/**
+ * Build per-scope read models against the supplied fixture spec, provide them
+ * to `body`, and run the resulting effect. Both scopes are constructed
+ * eagerly so the body can yield from either scope without re-running the
+ * factory.
+ *
+ * The body's `E` channel is preserved through to the harness's return type
+ * so scenario tests can `yield*` source-backed cells (which fail with
+ * `SettingsReadError` / `LockfileReadError`) directly without wrapping every
+ * call site in `Effect.result`.
+ */
+export const runScenario = (spec, body, options) => Effect.gen(function* () {
+    const project = yield* makeWorkspaceReadModel("project");
+    const user = yield* makeWorkspaceReadModel("user");
+    const ctx = {
+        scope: (scope) => (scope === "project" ? project : user),
+    };
+    return yield* body(ctx);
+}).pipe(Effect.provide(WorkspaceReadModelTest(spec, options)));
+/**
+ * Assert that `arr` is non-empty and return its first element. Replaces the
+ * silent `if (entry === undefined) return` pattern that lets a misshapen
+ * array silently pass a test.
+ */
+export const expectFirst = (arr, message) => {
+    const value = arr[0];
+    if (value === undefined) {
+        throw new Error(message ?? "expectFirst: array is empty");
+    }
+    return value;
+};
+/**
+ * Assert that `option` is `Option.Some` and return its inner value. Replaces
+ * the `expect(Option.isSome(opt)).toBe(true); if (!Option.isSome(opt)) return;`
+ * pattern that loses the failure message and lets misshapen values silently
+ * pass a test.
+ */
+export const expectSome = (option, message) => {
+    if (!Option.isSome(option)) {
+        throw new Error(message ?? "expectSome: option is None");
+    }
+    return option.value;
+};
+/**
+ * Assert that `result` is a `Result.Success` and return its success value.
+ * Replaces `expect(result._tag).toBe("Success"); if (result._tag === ...)`
+ * narrowing chains.
+ */
+export const expectSuccess = (result, message) => {
+    if (!Result.isSuccess(result)) {
+        throw new Error(message ?? `expectSuccess: result is Failure`);
+    }
+    return result.success;
+};
+/**
+ * Assert that `result` is a `Result.Failure` and return its failure value.
+ * Replaces `expect(result._tag).toBe("Failure"); if (result._tag === ...)`
+ * narrowing chains.
+ */
+export const expectFailure = (result, message) => {
+    if (!Result.isFailure(result)) {
+        throw new Error(message ?? `expectFailure: result is Success`);
+    }
+    return result.failure;
+};
+const hasStringTag = (value) => {
+    if (typeof value !== "object" || value === null)
+        return false;
+    if (!("_tag" in value))
+        return false;
+    // After the `in` narrowing, `value._tag` exists with type `unknown`.
+    // Compare its dynamic type without an assertion.
+    const tagValue = value._tag;
+    return typeof tagValue === "string";
+};
+/**
+ * Extract the set of tagged-error `_tag` values reachable inside a `Cause`.
+ * Used for the ≤3-tag-per-cell quality constraint assertion.
+ */
+export const tagsOf = (cause) => {
+    const tags = new Set();
+    for (const reason of cause.reasons) {
+        if (!Cause.isFailReason(reason))
+            continue;
+        const candidate = reason.error;
+        if (hasStringTag(candidate)) {
+            tags.add(candidate._tag);
+        }
+    }
+    return tags;
+};
+/**
+ * Read the scoped diagnostics buffer once and assert at least one warning
+ * matches `predicate`. Returns the matching warnings so callers can chain
+ * additional assertions.
+ */
+export const expectDiagnostics = (ctx, scope, predicate) => Effect.gen(function* () {
+    const warnings = yield* ctx.scope(scope).diagnostics;
+    const matches = warnings.filter(predicate);
+    if (matches.length === 0) {
+        throw new Error("expected at least one warning matching predicate");
+    }
+    return matches;
+});
+/**
+ * Snapshot the scoped diagnostics buffer without asserting. Useful when a
+ * scenario wants to verify the absence of a warning class.
+ */
+export const readDiagnostics = (ctx, scope) => ctx.scope(scope).diagnostics;
+//# sourceMappingURL=scenario-harness.js.map

package/dist/src/workspace/read-model/__fixtures__/test-layer.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Workspace read-model test layer.
+ *
+ * Provides {@link WorkspaceReadModelConfig}, {@link AgentRootResolver},
+ * `FileSystem`, and `Path` against fixture-built deps. Test bodies call
+ * {@link makeWorkspaceReadModel} directly to obtain a per-scope read model.
+ *
+ * The layer accepts an optional `options.allowedRoot`; when omitted, the
+ * filesystem root (`/`) is used so any `workspaceRoot` / `userHome` from the
+ * spec is allowed. Tests that want to verify root-escape failure pass an
+ * `allowedRoot` outside the spec's `workspaceRoot`.
+ *
+ * Tests that need to inject filesystem-level faults (e.g. simulate read
+ * failures) provide `options.wrapFileSystem` to wrap the fixture's
+ * `FileSystem` before it is composed into the layer.
+ */
+import * as FileSystem from "effect/FileSystem";
+import * as Layer from "effect/Layer";
+import * as Path from "effect/Path";
+import { AgentRootResolver } from "../agent-root-resolver.js";
+import { AgentPresenceProbe, type AgentPresenceProbeService } from "../agent-presence.js";
+import { WorkspaceReadModelConfig } from "../service.js";
+import { type FixtureSpec, type PathEscapeError } from "./builder.js";
+/**
+ * Optional layer-construction options for {@link WorkspaceReadModelTest}.
+ *
+ * - `allowedRoot` — workspace-root containment boundary used by
+ *   {@link makeWorkspaceReadModel} to validate `projectRoot` and `userHome`.
+ *   Defaults to the filesystem root so tests opt into root-escape behaviour
+ *   explicitly.
+ * - `wrapFileSystem` — optional adapter applied to the fixture's
+ *   `FileSystem` before it is provided. Tests that simulate IO faults (e.g.
+ *   read failures on specific paths) wrap the underlying filesystem here
+ *   without forking the test layer.
+ * - `probe` — optional agent-presence probe factory over the fixture's
+ *   `FileSystem` and `Path`. Defaults to detecting no agents; hosts with a
+ *   real detection implementation inject one here.
+ */
+export interface WorkspaceReadModelTestOptions {
+    readonly allowedRoot?: string;
+    readonly wrapFileSystem?: (fs: FileSystem.FileSystem) => FileSystem.FileSystem;
+    readonly probe?: (fs: FileSystem.FileSystem, path: Path.Path) => AgentPresenceProbeService;
+}
+/**
+ * Test layer for the workspace read model. Composes the fixture-built
+ * `FileSystem` / `Path` with {@link WorkspaceReadModelConfig} and
+ * {@link AgentRootResolver}, the dependencies callers need to invoke
+ * {@link makeWorkspaceReadModel}.
+ *
+ * The error channel covers:
+ *
+ *   - `PathEscapeError` — fixture builder rejection (escapes the
+ *     synthesized tree). Tests that need to assert this branch pass a
+ *     spec with a `..`-laden tree entry.
+ *
+ * Workspace-root escape (`WorkspaceRootEscape`) surfaces from
+ * {@link makeWorkspaceReadModel} itself, not the layer.
+ */
+export declare const WorkspaceReadModelTest: (spec: FixtureSpec, options?: WorkspaceReadModelTestOptions) => Layer.Layer<FileSystem.FileSystem | Path.Path | WorkspaceReadModelConfig | AgentRootResolver | AgentPresenceProbe, PathEscapeError>;
+//# sourceMappingURL=test-layer.d.ts.map

package/dist/src/workspace/read-model/__fixtures__/test-layer.js

@@ -0,0 +1,57 @@
+/**
+ * Workspace read-model test layer.
+ *
+ * Provides {@link WorkspaceReadModelConfig}, {@link AgentRootResolver},
+ * `FileSystem`, and `Path` against fixture-built deps. Test bodies call
+ * {@link makeWorkspaceReadModel} directly to obtain a per-scope read model.
+ *
+ * The layer accepts an optional `options.allowedRoot`; when omitted, the
+ * filesystem root (`/`) is used so any `workspaceRoot` / `userHome` from the
+ * spec is allowed. Tests that want to verify root-escape failure pass an
+ * `allowedRoot` outside the spec's `workspaceRoot`.
+ *
+ * Tests that need to inject filesystem-level faults (e.g. simulate read
+ * failures) provide `options.wrapFileSystem` to wrap the fixture's
+ * `FileSystem` before it is composed into the layer.
+ */
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as Layer from "effect/Layer";
+import * as Path from "effect/Path";
+import { makeAbsolutePath } from "@agentxm/extension-model/unstable/path-types";
+import { AgentRootResolver, AgentRootResolverLive } from "../agent-root-resolver.js";
+import { AgentPresenceProbe } from "../agent-presence.js";
+import { WorkspaceReadModelConfig } from "../service.js";
+import { buildFixture } from "./builder.js";
+/**
+ * Test layer for the workspace read model. Composes the fixture-built
+ * `FileSystem` / `Path` with {@link WorkspaceReadModelConfig} and
+ * {@link AgentRootResolver}, the dependencies callers need to invoke
+ * {@link makeWorkspaceReadModel}.
+ *
+ * The error channel covers:
+ *
+ *   - `PathEscapeError` — fixture builder rejection (escapes the
+ *     synthesized tree). Tests that need to assert this branch pass a
+ *     spec with a `..`-laden tree entry.
+ *
+ * Workspace-root escape (`WorkspaceRootEscape`) surfaces from
+ * {@link makeWorkspaceReadModel} itself, not the layer.
+ */
+export const WorkspaceReadModelTest = (spec, options = {}) => Layer.unwrap(Effect.gen(function* () {
+    const deps = yield* buildFixture(spec);
+    const fs = options.wrapFileSystem === undefined ? deps.fs : options.wrapFileSystem(deps.fs);
+    const fsLayer = Layer.succeed(FileSystem.FileSystem, fs);
+    const pathLayer = Layer.succeed(Path.Path, deps.path);
+    const allowedRoot = options.allowedRoot ?? "/";
+    const configLayer = Layer.succeed(WorkspaceReadModelConfig, {
+        projectRoot: makeAbsolutePath(deps.path, deps.workspaceRoot),
+        userHome: makeAbsolutePath(deps.path, deps.userHome),
+        allowedRoot: makeAbsolutePath(deps.path, allowedRoot),
+    });
+    const probeLayer = Layer.succeed(AgentPresenceProbe, options.probe?.(fs, deps.path) ?? {
+        detect: () => Effect.succeed(new Set()),
+    });
+    return Layer.mergeAll(fsLayer, pathLayer, configLayer, probeLayer, AgentRootResolverLive.pipe(Layer.provide(pathLayer)));
+}));
+//# sourceMappingURL=test-layer.js.map

package/dist/src/workspace/read-model/agent-presence.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Agent-presence probe port.
+ *
+ * The read model records which agents are present on the machine as a
+ * scoped fact. Detection itself is agent-surface integration, so the state
+ * layer declares only this optional port; the application composes an
+ * implementation backed by agent detection. An absent probe degrades to an
+ * empty presence set, matching the read model's existing failure
+ * degradation.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as Effect from "effect/Effect";
+import * as ServiceMap from "effect/Context";
+import type { AgentId } from "@agentxm/extension-model/unstable/agents/types";
+import type { WorkspaceScope } from "@agentxm/extension-model/unstable/workspace-scope";
+declare const AgentPresenceUnavailable_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: "AgentPresenceUnavailable";
+} & Readonly<A>;
+/** Presence detection failed; the read model degrades to an empty set. */
+export declare class AgentPresenceUnavailable extends AgentPresenceUnavailable_base<{
+    readonly message: string;
+}> {
+}
+export interface AgentPresenceProbeService {
+    readonly detect: (root: string, scope: WorkspaceScope) => Effect.Effect<ReadonlySet<AgentId>, AgentPresenceUnavailable>;
+}
+declare const AgentPresenceProbe_base: ServiceMap.ServiceClass<AgentPresenceProbe, "@agentxm/workspace-state/workspace/read-model/agent-presence/AgentPresenceProbe", AgentPresenceProbeService>;
+export declare class AgentPresenceProbe extends AgentPresenceProbe_base {
+}
+export {};
+//# sourceMappingURL=agent-presence.d.ts.map

package/dist/src/workspace/read-model/agent-presence.js

@@ -0,0 +1,21 @@
+/**
+ * Agent-presence probe port.
+ *
+ * The read model records which agents are present on the machine as a
+ * scoped fact. Detection itself is agent-surface integration, so the state
+ * layer declares only this optional port; the application composes an
+ * implementation backed by agent detection. An absent probe degrades to an
+ * empty presence set, matching the read model's existing failure
+ * degradation.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as Data from "effect/Data";
+import * as Effect from "effect/Effect";
+import * as ServiceMap from "effect/Context";
+/** Presence detection failed; the read model degrades to an empty set. */
+export class AgentPresenceUnavailable extends Data.TaggedError("AgentPresenceUnavailable") {
+}
+export class AgentPresenceProbe extends ServiceMap.Service()("@agentxm/workspace-state/workspace/read-model/agent-presence/AgentPresenceProbe") {
+}
+//# sourceMappingURL=agent-presence.js.map

package/dist/src/workspace/read-model/agent-root-resolver.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Cross-scope agent-root resolver service.
+ *
+ * Wraps the {@link AgentRootResolverState} and the snapshot of warnings
+ * emitted by {@link detectAgentRootCollisions}. Sharing one resolver across
+ * the per-scope factory ensures the heuristic-fallback warning fires at most
+ * once per agent across both scopes and both `mcp-config` / `agent-settings`
+ * scanners. Collision detection runs once at layer construction and exposes
+ * its warnings as an eager snapshot the project-scope read model seeds into
+ * its diagnostics buffer.
+ */
+import * as ServiceMap from "effect/Context";
+import * as Layer from "effect/Layer";
+import * as Path from "effect/Path";
+import { type Warning } from "./diagnostics.js";
+import { type AgentRootResolverState } from "./scanners/agent-root.js";
+/** Public shape of the {@link AgentRootResolver} service. */
+export interface AgentRootResolverShape {
+    /** Shared resolver state passed to scanners that resolve agent roots. */
+    readonly state: AgentRootResolverState;
+    /**
+     * Snapshot of `scanner-config` warnings produced by
+     * {@link detectAgentRootCollisions} at layer construction. The project
+     * scope seeds these into its diagnostics buffer; the user scope does not.
+     */
+    readonly collisionWarnings: ReadonlyArray<Warning>;
+}
+declare const AgentRootResolver_base: ServiceMap.ServiceClass<AgentRootResolver, "@agentxm/workspace-state/workspace/read-model/agent-root-resolver/AgentRootResolver", AgentRootResolverShape>;
+/** Service tag for the cross-scope agent-root resolver. */
+export declare class AgentRootResolver extends AgentRootResolver_base {
+}
+/**
+ * Live layer for {@link AgentRootResolver}. Allocates the shared state and
+ * runs collision detection once when the layer is built.
+ */
+export declare const AgentRootResolverLive: Layer.Layer<AgentRootResolver, never, Path.Path>;
+export {};
+//# sourceMappingURL=agent-root-resolver.d.ts.map

package/dist/src/workspace/read-model/agent-root-resolver.js

@@ -0,0 +1,35 @@
+/**
+ * Cross-scope agent-root resolver service.
+ *
+ * Wraps the {@link AgentRootResolverState} and the snapshot of warnings
+ * emitted by {@link detectAgentRootCollisions}. Sharing one resolver across
+ * the per-scope factory ensures the heuristic-fallback warning fires at most
+ * once per agent across both scopes and both `mcp-config` / `agent-settings`
+ * scanners. Collision detection runs once at layer construction and exposes
+ * its warnings as an eager snapshot the project-scope read model seeds into
+ * its diagnostics buffer.
+ */
+import * as ServiceMap from "effect/Context";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Path from "effect/Path";
+import * as Ref from "effect/Ref";
+import { AGENTS } from "@agentxm/extension-model/unstable/agents/registry";
+import { makeDiagnostics } from "./diagnostics.js";
+import { detectAgentRootCollisions, makeAgentRootResolverState, } from "./scanners/agent-root.js";
+/** Service tag for the cross-scope agent-root resolver. */
+export class AgentRootResolver extends ServiceMap.Service()("@agentxm/workspace-state/workspace/read-model/agent-root-resolver/AgentRootResolver") {
+}
+/**
+ * Live layer for {@link AgentRootResolver}. Allocates the shared state and
+ * runs collision detection once when the layer is built.
+ */
+export const AgentRootResolverLive = Layer.effect(AgentRootResolver, Effect.gen(function* () {
+    const path = yield* Path.Path;
+    const state = makeAgentRootResolverState();
+    const ref = yield* Ref.make([]);
+    yield* detectAgentRootCollisions(path, Object.values(AGENTS), makeDiagnostics(ref));
+    const collisionWarnings = yield* Ref.get(ref);
+    return AgentRootResolver.of({ state, collisionWarnings });
+}).pipe(Effect.withSpan("workspace.read-model.agent-root-resolver.build")));
+//# sourceMappingURL=agent-root-resolver.js.map

package/dist/src/workspace/read-model/agents/index.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Catalog-derived agent projections and the scoped agent read-model API.
+ *
+ * All agents share the same declared, actual, and detected projectors. The
+ * canonical capability catalog carries genuine per-agent variance, so adding
+ * an agent does not require a placeholder module or registry edit here.
+ */
+import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
+import { type AgentDescriptor, type AgentId, type ConfigurableAgentId } from "@agentxm/extension-model/unstable/agents/types";
+import type { SettingsReadError } from "../errors.js";
+import type { Scope } from "../types.js";
+import { type ActualAgent, type AgentModule, type AgentScannerObservations, type DeclaredAgent, type DeclaredSettingsShape, type DetectedAgent } from "./types.js";
+export type { ActualAgent, AgentModule, AgentScannerObservations, AgentSubjectType, DeclaredAgent, DeclaredSettingsShape, DetectedAgent, DetectionStatus, } from "./types.js";
+export { defineAgentModule } from "./types.js";
+/** Every configurable catalog agent, in canonical order. */
+export declare const registeredAgentModules: ReadonlyArray<AgentModule<ConfigurableAgentId>>;
+/** Build the common projector module for one catalog agent. */
+export declare const getAgentModule: <TId extends ConfigurableAgentId>(id: TId) => AgentModule<TId>;
+/** Public shape of `ctx.scope(scope).agents`. */
+export interface ScopedAgentsApi {
+    readonly list: Effect.Effect<ReadonlyArray<AgentId>>;
+    readonly known: Effect.Effect<ReadonlyArray<AgentDescriptor>>;
+    readonly byId: (id: string) => Option.Option<AgentDescriptor>;
+    readonly declared: (id: AgentId) => Effect.Effect<Option.Option<DeclaredAgent>, SettingsReadError>;
+    readonly actual: (id: AgentId) => Effect.Effect<Option.Option<ActualAgent>>;
+    readonly detected: Effect.Effect<ReadonlyArray<DetectedAgent>>;
+}
+/** Dependency-closed inputs captured by the scoped agent API. */
+export interface ScopedAgentsApiDeps {
+    readonly scope: Scope;
+    readonly settings: Effect.Effect<Option.Option<DeclaredSettingsShape>, SettingsReadError>;
+    readonly presence: Effect.Effect<ReadonlySet<AgentId>>;
+    readonly observations: Effect.Effect<AgentScannerObservations>;
+}
+/** Build the agent portion of a scoped workspace read model. */
+export declare const makeScopedAgentsApi: (deps: ScopedAgentsApiDeps) => ScopedAgentsApi;
+//# sourceMappingURL=index.d.ts.map