@agentxm/workspace-state 0.28.11 → 0.28.13

package/dist/src/workspace/settings-reader.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Settings reader: the selected scope's desired-state document and the
+ * settings-derived facts commands consult — merged source hosts, owner,
+ * publication default, release-age policy, configured agents, instruction
+ * and Knowledge discovery configuration, and the per-type entry maps.
+ *
+ * Every member keeps `FileSystem` and `Path` in `R`; the live layer captures
+ * only the workspace location and the shared source cache.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as ServiceMap from "effect/Context";
+import * as Effect from "effect/Effect";
+import type * as FileSystem from "effect/FileSystem";
+import * as Layer from "effect/Layer";
+import * as Option from "effect/Option";
+import type * as Path from "effect/Path";
+import * as Ref from "effect/Ref";
+import type { ExtensionVisibility } from "@agentxm/extension-model/unstable/extensions/common";
+import type { Handle } from "@agentxm/extension-model/unstable/extensions/handle";
+import type { InstallableExtensionType } from "@agentxm/extension-model/unstable/extensions/installable-types";
+import type { ScopedReleaseAgeExcludePattern } from "@agentxm/extension-model/unstable/extensions/release-age";
+import { type ResolvedKnowledgeDiscoveryConfig } from "../knowledge/discovery-config.js";
+import type { InstructionsConfigValue, MinimumReleaseAge, Settings, SourceHostConfig } from "../settings/index.js";
+import { type SettingsEntriesOf } from "./entry-accessors.js";
+import { WorkspaceLocation, type WorkspaceLocationService } from "./location.js";
+import type { WorkspaceSettingsReadFailure } from "./service-interface.js";
+import { WorkspaceStateShared } from "./shared.js";
+type Read<A> = Effect.Effect<A, WorkspaceSettingsReadFailure, FileSystem.FileSystem | Path.Path>;
+export interface SettingsReaderService {
+    /** The selected scope's settings, defaulting when the file is absent. */
+    readonly settings: Read<Settings>;
+    /** Merged sources from project, user-scope, and built-in defaults. Cached per workspace lifetime. */
+    readonly configuredSources: Read<ReadonlyArray<SourceHostConfig>>;
+    readonly sourceByName: (name: string) => Read<Option.Option<SourceHostConfig>>;
+    readonly registrySourceHosts: Read<ReadonlyArray<Extract<SourceHostConfig, {
+        type: "registry";
+    }>>>;
+    /** Owner: project settings, then user-scope settings, then none. */
+    readonly owner: Read<Option.Option<Handle>>;
+    /** Repository publication default for this exact workspace scope. */
+    readonly publishDefaultVisibility: Read<Option.Option<ExtensionVisibility>>;
+    /** minimumReleaseAge: project settings, then user-scope settings, then the default. */
+    readonly minimumReleaseAge: Read<MinimumReleaseAge>;
+    /** minimumReleaseAgeExclude with the same precedence; an explicit [] wins. */
+    readonly minimumReleaseAgeExclude: Read<ReadonlyArray<ScopedReleaseAgeExcludePattern>>;
+    readonly configuredAgents: Read<ReadonlyArray<string>>;
+    readonly instructionsConfig: Read<Option.Option<InstructionsConfigValue>>;
+    readonly knowledgeDiscoveryConfig: Read<ResolvedKnowledgeDiscoveryConfig>;
+    /** The configured entries of one type, defaulting to `{}`. */
+    readonly entries: <T extends InstallableExtensionType>(type: T) => Read<SettingsEntriesOf<T>>;
+}
+declare const SettingsReader_base: ServiceMap.ServiceClass<SettingsReader, "@agentxm/workspace-state/SettingsReader", SettingsReaderService>;
+export declare class SettingsReader extends SettingsReader_base {
+}
+export declare const makeSettingsReader: (location: WorkspaceLocationService, sourcesCache: Ref.Ref<Option.Option<ReadonlyArray<SourceHostConfig>>>) => SettingsReaderService;
+export declare const SettingsReaderLive: Layer.Layer<SettingsReader, never, WorkspaceLocation | WorkspaceStateShared>;
+export {};
+//# sourceMappingURL=settings-reader.d.ts.map

package/dist/src/workspace/settings-reader.js

@@ -0,0 +1,109 @@
+/**
+ * Settings reader: the selected scope's desired-state document and the
+ * settings-derived facts commands consult — merged source hosts, owner,
+ * publication default, release-age policy, configured agents, instruction
+ * and Knowledge discovery configuration, and the per-type entry maps.
+ *
+ * Every member keeps `FileSystem` and `Path` in `R`; the live layer captures
+ * only the workspace location and the shared source cache.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as ServiceMap from "effect/Context";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Option from "effect/Option";
+import * as Ref from "effect/Ref";
+import { resolveKnowledgeDiscoveryConfig, } from "../knowledge/discovery-config.js";
+import { DEFAULT_MINIMUM_RELEASE_AGE } from "../settings/index.js";
+import { settingsEntries } from "./entry-accessors.js";
+import { WorkspaceLocation } from "./location.js";
+import { WorkspaceStateShared } from "./shared.js";
+import { readSettingsOrDefault } from "./state-cells.js";
+export class SettingsReader extends ServiceMap.Service()("@agentxm/workspace-state/SettingsReader") {
+}
+/**
+ * Three-layer merge: project sources, then user-scope sources, then built-in
+ * sources. Name-based deduplication: earlier layers win.
+ */
+const mergeSources = (projectSources, globalSources, builtInSources) => {
+    const projectNames = new Set(projectSources.map((s) => s.name));
+    const filteredGlobal = globalSources.filter((s) => !projectNames.has(s.name));
+    const projectGlobalNames = new Set([...projectNames, ...filteredGlobal.map((s) => s.name)]);
+    return [
+        ...projectSources,
+        ...filteredGlobal,
+        ...builtInSources.filter((s) => !projectGlobalNames.has(s.name)),
+    ];
+};
+export const makeSettingsReader = (location, sourcesCache) => {
+    const settings = readSettingsOrDefault(location, location.runtimeDir);
+    const userSettings = readSettingsOrDefault(location, location.userRuntimeDir, "user");
+    const projectSettings = readSettingsOrDefault(location, location.projectRuntimeDir, "project");
+    const configuredSources = Effect.gen(function* () {
+        const cached = yield* Ref.get(sourcesCache);
+        if (Option.isSome(cached))
+            return cached.value;
+        const merged = mergeSources((yield* projectSettings).sources ?? [], (yield* userSettings).sources ?? [], location.builtInSources);
+        yield* Ref.set(sourcesCache, Option.some(merged));
+        return merged;
+    }).pipe(Effect.withSpan("SettingsReader.configuredSources"));
+    return {
+        settings,
+        configuredSources,
+        sourceByName: (name) => configuredSources.pipe(Effect.map((sources) => Option.fromUndefinedOr(sources.find((s) => s.name === name)))),
+        registrySourceHosts: configuredSources.pipe(Effect.map((sources) => sources.filter((s) => s.type === "registry"))),
+        owner: Effect.gen(function* () {
+            const project = yield* projectSettings;
+            if (project.owner)
+                return Option.some(project.owner);
+            const user = yield* userSettings;
+            if (user.owner)
+                return Option.some(user.owner);
+            return Option.none();
+        }),
+        publishDefaultVisibility: settings.pipe(Effect.map((value) => Option.fromUndefinedOr(value.publish?.defaultVisibility))),
+        minimumReleaseAge: Effect.gen(function* () {
+            const scoped = yield* settings;
+            if (scoped.minimumReleaseAge !== undefined)
+                return scoped.minimumReleaseAge;
+            if (location.scope === "project") {
+                const user = yield* userSettings;
+                if (user.minimumReleaseAge !== undefined)
+                    return user.minimumReleaseAge;
+            }
+            return DEFAULT_MINIMUM_RELEASE_AGE;
+        }).pipe(Effect.withSpan("SettingsReader.minimumReleaseAge")),
+        minimumReleaseAgeExclude: Effect.gen(function* () {
+            const scoped = yield* settings;
+            if (scoped.minimumReleaseAgeExclude !== undefined) {
+                return scoped.minimumReleaseAgeExclude.map((pattern) => ({
+                    pattern,
+                    scope: location.scope,
+                }));
+            }
+            if (location.scope === "project") {
+                const user = yield* userSettings;
+                if (user.minimumReleaseAgeExclude !== undefined) {
+                    return user.minimumReleaseAgeExclude.map((pattern) => ({
+                        pattern,
+                        scope: "user",
+                    }));
+                }
+            }
+            return [];
+        }).pipe(Effect.withSpan("SettingsReader.minimumReleaseAgeExclude")),
+        configuredAgents: settings.pipe(Effect.map((value) => value.agents ?? []), Effect.withSpan("SettingsReader.configuredAgents")),
+        instructionsConfig: settings.pipe(Effect.map((value) => Option.fromUndefinedOr(value.instructionFiles)), Effect.withSpan("SettingsReader.instructionsConfig")),
+        knowledgeDiscoveryConfig: settings.pipe(Effect.map((value) => resolveKnowledgeDiscoveryConfig({
+            ...(value.knowledgeConfig?.instructions === false ? { instructions: false } : {}),
+        })), Effect.withSpan("SettingsReader.knowledgeDiscoveryConfig")),
+        entries: (type) => settings.pipe(Effect.map((value) => settingsEntries[type].entries(value)), Effect.withSpan("SettingsReader.entries")),
+    };
+};
+export const SettingsReaderLive = Layer.effect(SettingsReader, Effect.gen(function* () {
+    const location = yield* WorkspaceLocation;
+    const shared = yield* WorkspaceStateShared;
+    return makeSettingsReader(location, shared.sourcesCache);
+}));
+//# sourceMappingURL=settings-reader.js.map

package/dist/src/workspace/settings-writer.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Settings writer: every settings-only mutation of the selected scope —
+ * owner, source hosts, instruction-file configuration, agent membership, and
+ * one configured entry at a time. Each write protects the settings file with
+ * the active transaction, publishes atomically, and is serialized by the
+ * workspace's mutation mutex.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as ServiceMap from "effect/Context";
+import * as Effect from "effect/Effect";
+import type * as FileSystem from "effect/FileSystem";
+import * as Layer from "effect/Layer";
+import type * as Path from "effect/Path";
+import type * as Semaphore from "effect/Semaphore";
+import type { Handle } from "@agentxm/extension-model/unstable/extensions/handle";
+import type { InstallableExtensionType } from "@agentxm/extension-model/unstable/extensions/installable-types";
+import { type InstructionsConfigValue, type SourceHostConfig } from "../settings/index.js";
+import { type SettingsEntryByType } from "./entry-accessors.js";
+import { InvalidAgentId, SettingsEntryMissing } from "./errors.js";
+import { type WorkspaceLayout } from "./layout.js";
+import { WorkspaceLocation, type WorkspaceLocationService } from "./location.js";
+import type { WorkspaceSettingsMutationFailure } from "./service-interface.js";
+import { WorkspaceStateShared } from "./shared.js";
+type Write<A = void, E = never> = Effect.Effect<A, WorkspaceSettingsMutationFailure | E, FileSystem.FileSystem | Path.Path>;
+export interface SettingsWriterService {
+    /** Record the owner in the selected scope's settings and in the resolved layout. */
+    readonly setOwner: (owner: Handle) => Write<WorkspaceLayout>;
+    /** Append a source to the selected scope's settings and drop the merged-source cache. */
+    readonly addConfiguredSource: (source: SourceHostConfig) => Write;
+    /** Set instruction-file config. `false` is explicit manual mode. */
+    readonly setInstructionsConfig: (config: InstructionsConfigValue) => Write;
+    /** Append an agent ID when absent. Fails typed when the ID is not configurable. */
+    readonly addConfiguredAgent: (agentId: string) => Write<void, InvalidAgentId>;
+    /** Remove an agent ID when present. Fails typed when the ID is not configurable. */
+    readonly removeConfiguredAgent: (agentId: string) => Write<void, InvalidAgentId>;
+    /** Create or overwrite one configured entry. */
+    readonly setEntry: <T extends InstallableExtensionType>(type: T, name: string, entry: SettingsEntryByType[T]) => Write;
+    /**
+     * Update one configured entry. A missing skill or MCP server entry fails
+     * typed; a missing entry of any other type is a no-op.
+     */
+    readonly updateEntry: <T extends InstallableExtensionType>(type: T, name: string, update: (entry: SettingsEntryByType[T]) => SettingsEntryByType[T]) => Write<void, SettingsEntryMissing>;
+    /** Remove one configured entry. No-op when absent. */
+    readonly removeEntry: (type: InstallableExtensionType, name: string) => Write;
+}
+declare const SettingsWriter_base: ServiceMap.ServiceClass<SettingsWriter, "@agentxm/workspace-state/SettingsWriter", SettingsWriterService>;
+export declare class SettingsWriter extends SettingsWriter_base {
+}
+export declare const makeSettingsWriter: (location: WorkspaceLocationService, mutex: Semaphore.Semaphore, invalidateSources: Effect.Effect<void>) => SettingsWriterService;
+export declare const SettingsWriterLive: Layer.Layer<SettingsWriter, never, WorkspaceLocation | WorkspaceStateShared>;
+export {};
+//# sourceMappingURL=settings-writer.d.ts.map

package/dist/src/workspace/settings-writer.js

@@ -0,0 +1,90 @@
+/**
+ * Settings writer: every settings-only mutation of the selected scope —
+ * owner, source hosts, instruction-file configuration, agent membership, and
+ * one configured entry at a time. Each write protects the settings file with
+ * the active transaction, publishes atomically, and is serialized by the
+ * workspace's mutation mutex.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as ServiceMap from "effect/Context";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Option from "effect/Option";
+import * as Ref from "effect/Ref";
+import * as Schema from "effect/Schema";
+import { ConfigurableAgentIdSchema } from "@agentxm/extension-model/unstable/extensions";
+import { writeSettingsAtPath, } from "../settings/index.js";
+import { settingsEntries } from "./entry-accessors.js";
+import { InvalidAgentId, SettingsEntryMissing } from "./errors.js";
+import { withLayoutOwner } from "./layout.js";
+import { WorkspaceLocation } from "./location.js";
+import { WorkspaceStateShared } from "./shared.js";
+import { readSettingsOrDefault } from "./state-cells.js";
+export class SettingsWriter extends ServiceMap.Service()("@agentxm/workspace-state/SettingsWriter") {
+}
+/** Entry types whose update of a missing entry is a typed failure. */
+const missingEntryFailure = (type, name) => type === "skill" || type === "mcp-server"
+    ? Option.some(new SettingsEntryMissing({ entryType: type, name }))
+    : Option.none();
+export const makeSettingsWriter = (location, mutex, invalidateSources) => {
+    const current = readSettingsOrDefault(location, location.runtimeDir);
+    const write = (settings) => writeSettingsAtPath(location.settingsPath, settings);
+    const serialized = mutex.withPermits(1);
+    const validAgentId = (agentId) => Schema.decodeUnknownEffect(ConfigurableAgentIdSchema)(agentId).pipe(Effect.mapError((cause) => new InvalidAgentId({ agentId, cause })));
+    return {
+        setOwner: (owner) => serialized(Effect.gen(function* () {
+            yield* write({ ...(yield* current), owner });
+            return yield* Ref.updateAndGet(location.layout, (layout) => withLayoutOwner(layout, owner));
+        })).pipe(Effect.withSpan("SettingsWriter.setOwner")),
+        addConfiguredSource: (source) => serialized(Effect.gen(function* () {
+            const settings = yield* current;
+            yield* write({ ...settings, sources: [...(settings.sources ?? []), source] });
+            yield* invalidateSources;
+        })).pipe(Effect.withSpan("SettingsWriter.addConfiguredSource")),
+        setInstructionsConfig: (config) => serialized(Effect.flatMap(current, (settings) => write({ ...settings, instructionFiles: config }))).pipe(Effect.withSpan("SettingsWriter.setInstructionsConfig")),
+        addConfiguredAgent: (agentId) => serialized(Effect.gen(function* () {
+            const validId = yield* validAgentId(agentId);
+            const settings = yield* current;
+            const agents = settings.agents ?? [];
+            if (agents.includes(validId))
+                return;
+            yield* write({ ...settings, agents: [...agents, validId] });
+        })),
+        removeConfiguredAgent: (agentId) => serialized(Effect.gen(function* () {
+            const validId = yield* validAgentId(agentId);
+            const settings = yield* current;
+            const agents = settings.agents ?? [];
+            if (!agents.includes(validId))
+                return;
+            yield* write({
+                ...settings,
+                agents: agents.filter((configured) => configured !== validId),
+            });
+        })),
+        setEntry: (type, name, entry) => serialized(Effect.flatMap(current, (settings) => write(settingsEntries[type].set(settings, name, entry)))).pipe(Effect.withSpan("SettingsWriter.setEntry")),
+        updateEntry: (type, name, update) => serialized(Effect.gen(function* () {
+            const settings = yield* current;
+            const accessor = settingsEntries[type];
+            const existing = accessor.entry(settings, name);
+            if (Option.isNone(existing)) {
+                const failure = missingEntryFailure(type, name);
+                return Option.isSome(failure) ? yield* failure.value : undefined;
+            }
+            yield* write(accessor.set(settings, name, update(existing.value)));
+        })).pipe(Effect.withSpan("SettingsWriter.updateEntry")),
+        removeEntry: (type, name) => serialized(Effect.gen(function* () {
+            const settings = yield* current;
+            const accessor = settingsEntries[type];
+            if (accessor.entries(settings)[name] === undefined)
+                return;
+            yield* write(accessor.remove(settings, name));
+        })).pipe(Effect.withSpan("SettingsWriter.removeEntry")),
+    };
+};
+export const SettingsWriterLive = Layer.effect(SettingsWriter, Effect.gen(function* () {
+    const location = yield* WorkspaceLocation;
+    const shared = yield* WorkspaceStateShared;
+    return makeSettingsWriter(location, shared.mutex, Ref.set(shared.sourcesCache, Option.none()));
+}));
+//# sourceMappingURL=settings-writer.js.map

package/dist/src/workspace/setup-scope-support.js

@@ -4,7 +4,7 @@
  * @experimental This API is unstable and may change without notice.
  */
 import { CONFIGURABLE_AGENTS_BY_ID, } from "@agentxm/extension-model/unstable/agent-capabilities";
-import { userScopeRefusal } from "./scope-refusal.js";
+import { userScopeRefusal } from "@agentxm/agent-integration";
 import { EXTENSION_TYPE_TABLE, extensionTypeLabels, extensionTypes, } from "@agentxm/extension-model/unstable/extensions/common";
 const isConfigurableAgentId = (id) => Object.hasOwn(CONFIGURABLE_AGENTS_BY_ID, id);
 const nativeSupportsScope = (native, scope) => native.availability.via !== "none" && "scopes" in native && native.scopes.includes(scope);

package/dist/src/workspace/shared.d.ts

@@ -0,0 +1,24 @@
+/**
+ * State shared by the narrow workspace services of one workspace lifetime:
+ * the in-process mutation mutex every writer serializes on, and the merged
+ * source-host cache the settings reader fills and the settings writer
+ * invalidates. Provided by the live composition; not part of the public API.
+ */
+import * as ServiceMap from "effect/Context";
+import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
+import * as Ref from "effect/Ref";
+import * as Semaphore from "effect/Semaphore";
+import type { SourceHostConfig } from "../settings/index.js";
+export interface WorkspaceStateSharedService {
+    /** Serializes every settings and lockfile mutation of one runtime. */
+    readonly mutex: Semaphore.Semaphore;
+    /** Merged sources, cached per workspace lifetime until a source is added. */
+    readonly sourcesCache: Ref.Ref<Option.Option<ReadonlyArray<SourceHostConfig>>>;
+}
+declare const WorkspaceStateShared_base: ServiceMap.ServiceClass<WorkspaceStateShared, "@agentxm/workspace-state/WorkspaceStateShared", WorkspaceStateSharedService>;
+export declare class WorkspaceStateShared extends WorkspaceStateShared_base {
+}
+export declare const makeWorkspaceStateShared: Effect.Effect<WorkspaceStateSharedService>;
+export {};
+//# sourceMappingURL=shared.d.ts.map

package/dist/src/workspace/shared.js

@@ -0,0 +1,20 @@
+/**
+ * State shared by the narrow workspace services of one workspace lifetime:
+ * the in-process mutation mutex every writer serializes on, and the merged
+ * source-host cache the settings reader fills and the settings writer
+ * invalidates. Provided by the live composition; not part of the public API.
+ */
+import * as ServiceMap from "effect/Context";
+import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
+import * as Ref from "effect/Ref";
+import * as Semaphore from "effect/Semaphore";
+export class WorkspaceStateShared extends ServiceMap.Service()("@agentxm/workspace-state/WorkspaceStateShared") {
+}
+export const makeWorkspaceStateShared = Effect.gen(function* () {
+    return {
+        mutex: yield* Semaphore.make(1),
+        sourcesCache: yield* Ref.make(Option.none()),
+    };
+});
+//# sourceMappingURL=shared.js.map

package/dist/src/workspace/state-cells.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Settings and lockfile cells: the scoped read model's two authoritative
+ * documents, read for either runtime directory the workspace knows about.
+ * Every narrow state service reads through these two functions, so the
+ * read-model configuration and agent-root resolution are composed in exactly
+ * one place and `FileSystem`/`Path` stay in `R`.
+ */
+import * as Effect from "effect/Effect";
+import type * as FileSystem from "effect/FileSystem";
+import * as Option from "effect/Option";
+import * as Path from "effect/Path";
+import { type AbsolutePath } from "@agentxm/extension-model/unstable/path-types";
+import type { WorkspaceScope } from "@agentxm/extension-model/unstable/workspace-scope";
+import type { Lockfile } from "../lockfile/schema.js";
+import { type Settings } from "../settings/index.js";
+import type { LockfileReadError, SettingsReadError } from "./read-model/errors.js";
+import { type WorkspaceReadModel } from "./read-model/service.js";
+import type { WorkspaceLockfileReadFailure, WorkspaceSettingsReadFailure, WorkspaceStateReadFailure } from "./service-interface.js";
+/** The runtime directories a workspace's settings sources can live in. */
+export interface StateCellPaths {
+    readonly scope: WorkspaceScope;
+    readonly projectRoot: AbsolutePath;
+    readonly userHome: AbsolutePath;
+    readonly projectRuntimeDir: string;
+    readonly userRuntimeDir: string;
+}
+/** The settings document of one runtime directory, when present. */
+export declare const readSettingsCell: (cells: StateCellPaths, dir: string, sharedScope?: WorkspaceScope) => Effect.Effect<Option.Option<Settings>, WorkspaceSettingsReadFailure, FileSystem.FileSystem | Path.Path>;
+/** The settings document of one runtime directory, defaulting when absent. */
+export declare const readSettingsOrDefault: (cells: StateCellPaths, dir: string, sharedScope?: WorkspaceScope) => Effect.Effect<Settings, WorkspaceSettingsReadFailure, FileSystem.FileSystem | Path.Path>;
+/** The lockfile of one runtime directory, empty when absent. */
+export declare const readLockfileCell: (cells: StateCellPaths, dir: string, sharedScope?: WorkspaceScope) => Effect.Effect<Lockfile, WorkspaceLockfileReadFailure, FileSystem.FileSystem | Path.Path>;
+/** Run one read against the selected scope's read model. */
+export declare const readScopedModel: <A>(cells: StateCellPaths, runtimeDir: string, f: (scoped: WorkspaceReadModel) => Effect.Effect<A, SettingsReadError | LockfileReadError>) => Effect.Effect<A, WorkspaceStateReadFailure, FileSystem.FileSystem | Path.Path>;
+//# sourceMappingURL=state-cells.d.ts.map

package/dist/src/workspace/state-cells.js

@@ -0,0 +1,42 @@
+/**
+ * Settings and lockfile cells: the scoped read model's two authoritative
+ * documents, read for either runtime directory the workspace knows about.
+ * Every narrow state service reads through these two functions, so the
+ * read-model configuration and agent-root resolution are composed in exactly
+ * one place and `FileSystem`/`Path` stay in `R`.
+ */
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Option from "effect/Option";
+import * as Path from "effect/Path";
+import { makeAbsolutePath } from "@agentxm/extension-model/unstable/path-types";
+import { LOCKFILE_VERSION } from "../lockfile/index.js";
+import { createDefaultSettings } from "../settings/index.js";
+import { AgentRootResolverLive } from "./read-model/agent-root-resolver.js";
+import { makeWorkspaceReadModel, WorkspaceReadModelConfig, } from "./read-model/service.js";
+const createEmptyLockfile = () => ({
+    lockfileVersion: LOCKFILE_VERSION,
+    skills: {},
+});
+const scopeForDir = (cells, dir, sharedScope = cells.scope) => dir === cells.userRuntimeDir && dir === cells.projectRuntimeDir
+    ? sharedScope
+    : dir === cells.userRuntimeDir
+        ? "user"
+        : "project";
+const readModelFor = (cells, scope) => Effect.gen(function* () {
+    const path = yield* Path.Path;
+    return yield* makeWorkspaceReadModel(scope).pipe(Effect.provide(Layer.mergeAll(Layer.succeed(WorkspaceReadModelConfig, {
+        projectRoot: cells.projectRoot,
+        userHome: cells.userHome,
+        allowedRoot: makeAbsolutePath(path, "/"),
+    }), AgentRootResolverLive)));
+});
+/** The settings document of one runtime directory, when present. */
+export const readSettingsCell = (cells, dir, sharedScope) => readModelFor(cells, scopeForDir(cells, dir, sharedScope)).pipe(Effect.flatMap((readModel) => readModel.state.settings));
+/** The settings document of one runtime directory, defaulting when absent. */
+export const readSettingsOrDefault = (cells, dir, sharedScope) => readSettingsCell(cells, dir, sharedScope).pipe(Effect.map(Option.getOrElse(() => createDefaultSettings())));
+/** The lockfile of one runtime directory, empty when absent. */
+export const readLockfileCell = (cells, dir, sharedScope) => readModelFor(cells, scopeForDir(cells, dir, sharedScope)).pipe(Effect.flatMap((readModel) => readModel.state.lockfile), Effect.map(Option.getOrElse(createEmptyLockfile)));
+/** Run one read against the selected scope's read model. */
+export const readScopedModel = (cells, runtimeDir, f) => readModelFor(cells, scopeForDir(cells, runtimeDir)).pipe(Effect.flatMap(f));
+//# sourceMappingURL=state-cells.js.map

package/dist/src/workspace/subagent-paths.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Centralized subagent path computation.
+ *
+ * Provides types and a pure function for computing subagent directory paths
+ * based on source type (registry vs non-registry).
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import { type ExtensionPathSource } from "./extension-paths.js";
+import type { AbsolutePath } from "@agentxm/extension-model/unstable/path-types";
+import type { WorkspaceLayout } from "./layout.js";
+/**
+ * Minimal structural discriminant for determining subagent path layout.
+ *
+ * Every acquired ref carries enough source coordinates to derive its
+ * source-qualified canonical path.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export type SubagentPathSource = ExtensionPathSource;
+/**
+ * Computed paths for an installed subagent directory.
+ *
+ * - `canonicalPath`: root of the installed subagent
+ * - `subagentSrcPath`: where actual subagent source files live
+ *
+ * Native packages use `<canonicalPath>/src`; portable acquired formats use
+ * the source-qualified package root directly when supported.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export interface SubagentDirPaths {
+    readonly canonicalPath: AbsolutePath;
+    readonly subagentSrcPath: AbsolutePath;
+}
+/**
+ * Content filename for subagent instructions.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export declare const subagentContentFilename: (name: string) => string;
+/**
+ * Content path for subagent instructions.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export declare const subagentContentPath: (join: (...paths: string[]) => string, root: string, name: string) => AbsolutePath;
+export declare const computeSubagentPathsForLayout: (join: (...paths: string[]) => string, layout: WorkspaceLayout, source: SubagentPathSource, sanitizedName: string) => SubagentDirPaths;
+//# sourceMappingURL=subagent-paths.d.ts.map

package/dist/src/workspace/subagent-paths.js

@@ -0,0 +1,26 @@
+/**
+ * Centralized subagent path computation.
+ *
+ * Provides types and a pure function for computing subagent directory paths
+ * based on source type (registry vs non-registry).
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import { computeExtensionPathsForLayout, extensionContentFilename, extensionContentPath, } from "./extension-paths.js";
+/**
+ * Content filename for subagent instructions.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export const subagentContentFilename = extensionContentFilename;
+/**
+ * Content path for subagent instructions.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export const subagentContentPath = (join, root, name) => extensionContentPath(join, root, name);
+export const computeSubagentPathsForLayout = (join, layout, source, sanitizedName) => {
+    const paths = computeExtensionPathsForLayout(join, layout, source, "subagents", sanitizedName);
+    return { canonicalPath: paths.canonicalPath, subagentSrcPath: paths.extensionSrcPath };
+};
+//# sourceMappingURL=subagent-paths.js.map

package/dist/src/workspace/test-stubs.js

@@ -190,15 +190,6 @@ export const makeBaseWorkspaceMock = (axmDir = "/tmp/axm", overrides) => {
         }));
         return { complete: true, nodes, mcpSourceClosures: [], problems: [] };
     });
-    const runTransaction = (args) => Effect.gen(function* () {
-        const value = yield* args.transition;
-        yield* args.validate(value);
-        return value;
-    });
-    // The mock acquires nothing: unit tests share literal workspace paths, and
-    // a real lock would contend across parallel test files. Tests exercising
-    // real transition semantics override this with the real acquirer.
-    const acquireTransition = () => Effect.succeed(Option.none());
     const entryFrom = (read) => (name) => read().pipe(Effect.map((entries) => Option.fromUndefinedOr(entries[name])));
     const lockedSkills = serviceOverrides.getLockedSkills ?? (() => Effect.succeed({}));
     const lockedMcpServers = serviceOverrides.getLockedMcpServers ?? (() => Effect.succeed({}));
@@ -222,8 +213,6 @@ export const makeBaseWorkspaceMock = (axmDir = "/tmp/axm", overrides) => {
             authoredRoot: (type) => decodeAbsolutePathSync(path.resolve(baseDir, type === "mcp-server" ? "mcps" : `${type}s`)),
         },
         records,
-        runTransaction,
-        acquireTransition,
         getLockfileState: () => Effect.succeed("ok"),
         getDesiredStateGraph: getSynthesizedDesiredStateGraph,
         getConfiguredSources: () => Effect.succeed([]),

package/dist/src/workspace/workspace-records.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Workspace records: the read model's inventory and lifecycle-tagged rows
+ * for every installable extension type, over the selected scope.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as ServiceMap from "effect/Context";
+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 type { InstallableExtensionType } from "@agentxm/extension-model/unstable/extensions/installable-types";
+import { DesiredStateReader, type DesiredStateReaderService } from "./desired-state-reader.js";
+import { WorkspaceLocation, type WorkspaceLocationService } from "./location.js";
+import type { ExtensionInventory } from "./read-model/extensions/inventory.js";
+import type { ReadModelRecordRow } from "./read-model-record-types.js";
+import type { WorkspaceStateReadFailure } from "./service-interface.js";
+type Read<A> = Effect.Effect<A, WorkspaceStateReadFailure, FileSystem.FileSystem | Path.Path>;
+export interface WorkspaceRecordsService {
+    /** Deterministic inventory across every installable extension type or one selected type. */
+    readonly getInventory: (options: {
+        readonly type?: InstallableExtensionType;
+    }) => Read<ExtensionInventory>;
+    /** Read-only physical inventory for one extension type. */
+    readonly getExtensionInventory: (type: InstallableExtensionType, options: {
+        readonly agents?: ReadonlyArray<string>;
+    }) => Read<ExtensionInventory>;
+    /**
+     * Every read-model row for one extension type, tagged with its lifecycle
+     * (`configured` / `implicit` / `unmanaged`). Total over
+     * `InstallableExtensionType` and non-throwing.
+     */
+    readonly rows: (type: InstallableExtensionType) => Read<ReadonlyArray<ReadModelRecordRow>>;
+}
+declare const WorkspaceRecords_base: ServiceMap.ServiceClass<WorkspaceRecords, "@agentxm/workspace-state/WorkspaceRecords", WorkspaceRecordsService>;
+export declare class WorkspaceRecords extends WorkspaceRecords_base {
+}
+export declare const makeWorkspaceRecords: (location: WorkspaceLocationService, desiredState: DesiredStateReaderService) => WorkspaceRecordsService;
+export declare const WorkspaceRecordsLive: Layer.Layer<WorkspaceRecords, never, WorkspaceLocation | DesiredStateReader>;
+export {};
+//# sourceMappingURL=workspace-records.d.ts.map

package/dist/src/workspace/workspace-records.js

@@ -0,0 +1,43 @@
+/**
+ * Workspace records: the read model's inventory and lifecycle-tagged rows
+ * for every installable extension type, over the selected scope.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as ServiceMap from "effect/Context";
+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 { DesiredStateReader } from "./desired-state-reader.js";
+import { WorkspaceLocation } from "./location.js";
+import { makeReadModelRecordReaders } from "./read-model-record-readers.js";
+import { readScopedModel } from "./state-cells.js";
+export class WorkspaceRecords extends ServiceMap.Service()("@agentxm/workspace-state/WorkspaceRecords") {
+}
+export const makeWorkspaceRecords = (location, desiredState) => {
+    // The record readers take the platform path service and scoped reads with
+    // the platform already discharged; bind both at each call so `FileSystem`
+    // and `Path` stay requirements of every member rather than captures.
+    const withReaders = (use) => Effect.gen(function* () {
+        const fs = yield* FileSystem.FileSystem;
+        const path = yield* Path.Path;
+        const provide = (effect) => effect.pipe(Effect.provideService(FileSystem.FileSystem, fs), Effect.provideService(Path.Path, path));
+        const readers = makeReadModelRecordReaders({
+            baseDir: location.baseDir,
+            path,
+            readScopedContext: (f) => provide(readScopedModel(location, location.runtimeDir, f)),
+            getDesiredStateGraph: () => provide(desiredState.graph()),
+        });
+        return yield* use(readers);
+    });
+    return {
+        getInventory: (options) => withReaders((readers) => readers.getInventory(options)),
+        getExtensionInventory: (type, options) => withReaders((readers) => readers.getExtensionInventory(type, options)),
+        rows: (type) => withReaders((readers) => readers.getReadModelRecordRows(type)),
+    };
+};
+export const WorkspaceRecordsLive = Layer.effect(WorkspaceRecords, Effect.gen(function* () {
+    return makeWorkspaceRecords(yield* WorkspaceLocation, yield* DesiredStateReader);
+}));
+//# sourceMappingURL=workspace-records.js.map