@agentxm/workspace-configuration 0.28.11 → 0.28.13

package/dist/src/membership/configure-agents.js

@@ -0,0 +1,395 @@
+/**
+ * Configured-agent membership: which coding agents this workspace configures,
+ * and the change a request makes to that set.
+ *
+ * Membership is a set of decisions, not a list of writes. Adding names the
+ * agents a request actually configures — the ids it gave plus what detection
+ * found, minus the ones already configured and the ones whose vendor retired
+ * them unless the request named them itself. Removing names the agents that
+ * leave and the projection state the workspace must be reconciled to once
+ * they have. Either change settles atomically: the recorded set and the agent
+ * outputs realized for it move together or not at all.
+ *
+ * Realizing installed extensions for a new membership, and cleaning up the
+ * outputs a departing agent owned, are reconciliation work. The application
+ * plans those steps through the reconciliation feature and hands them to
+ * `previewOrApply` as ordinary plan steps, so this feature never depends on a
+ * peer feature and the whole change still settles as one closure.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
+import * as Schema from "effect/Schema";
+import { detectAgentsForScope } from "@agentxm/agent-integration";
+import { AGENTS } from "@agentxm/extension-model/unstable/agents/registry";
+import { CONFIGURABLE_AGENT_IDS } from "@agentxm/extension-model/unstable/agents/types";
+import { OperationJournal, observeUnit, prepareExecutionCandidate, ResolvePlanInteraction, resolveExecutionCandidate, } from "@agentxm/workspace-operations";
+import { UNIVERSAL_AGENT_ID, expectedProjectionNames, observeInstructionProjection, resolveInstructionsConfig, } from "@agentxm/workspace-projection";
+import { ConfiguredAgentOutcomesProvider, WorkspaceMutations, } from "@agentxm/workspace-state";
+import { FootprintRecorder, WorkspaceTransactionScope } from "@agentxm/workspace-transactions";
+import { WorkspaceConfigurationFailed, workspaceChangeFailedToStepFailure, } from "../errors.js";
+import { agentLifecycle, isRetiredAgent, lifecycleWarning } from "./agent-lifecycle.js";
+import { makeAtomicMembershipSteps } from "./atomic-membership.js";
+import { dedupe, validateAgentIds } from "./validate-agent-ids.js";
+/** Stable workspace-relative path of the settings file membership is recorded in. */
+const settingsDisplayPath = (scope) => scope === "project" ? "axm.json" : ".axm/workspace/axm.json";
+const membershipArtifact = (scope, agentId, change) => ({
+    path: settingsDisplayPath(scope),
+    scope,
+    agents: [agentId],
+    change,
+    fileCount: 1,
+    targets: [{ path: settingsDisplayPath(scope), change, agentIds: [agentId] }],
+});
+const unchanged = (reason, message, retiredDetected = []) => ({ _tag: "Unchanged", reason, message, retiredDetected });
+/**
+ * Settle which agents an add request configures.
+ *
+ * Explicitly named ids are validated first, so a typo is refused before
+ * detection runs. Detection contributes what it found minus the agents whose
+ * vendor retired them: a retired agent is a deliberate choice, never a
+ * consequence of having it installed.
+ */
+export const prepareAddConfiguredAgents = (request) => Effect.gen(function* () {
+    const workspace = yield* WorkspaceMutations;
+    if (request.ids.length === 0 && !request.detected) {
+        return yield* new WorkspaceConfigurationFailed({
+            category: "usage",
+            detail: "Provide one or more agent IDs, or pass --detected.",
+            suggestions: [
+                { description: "List supported IDs.", cmd: "axm agents list --available" },
+                { description: "Configure detected agents.", cmd: "axm agents add --detected" },
+            ],
+        });
+    }
+    const requested = yield* validateAgentIds(request.ids);
+    const configured = yield* workspace.getConfiguredAgents();
+    const configuredSet = new Set(configured);
+    const detected = request.detected
+        ? yield* observeUnit({ id: "detect-agents", label: "coding agent detection" }, detectAgentsForScope(workspace.baseDir, workspace.scope).pipe(Effect.map((agents) => agents.map((agent) => agent.id))))
+        : [];
+    const detectedConfigurable = yield* validateAgentIds(detected);
+    const requestedSet = new Set(requested);
+    const retiredDetected = detectedConfigurable.flatMap((id) => isRetiredAgent(id) && !requestedSet.has(id)
+        ? [
+            {
+                agentId: id,
+                detail: `${lifecycleWarning(id) ?? `${id} is retired.`} It was not added automatically; run \`axm agents add ${id}\` to opt in.`,
+            },
+        ]
+        : []);
+    const autoDetected = detectedConfigurable.filter((id) => !isRetiredAgent(id) || requestedSet.has(id));
+    const agentIds = dedupe([...requested, ...autoDetected]).filter((id) => !configuredSet.has(id));
+    if (agentIds.length === 0) {
+        return unchanged(retiredDetected.length > 0 && requested.length === 0
+            ? "no-active-detected"
+            : "already-configured", retiredDetected.length > 0 && requested.length === 0
+            ? "No active detected agents to configure"
+            : "All requested agents are already configured", retiredDetected);
+    }
+    // Warn rather than block: the workspace may still need a retired agent
+    // configured, but the person must know the vendor stopped maintaining it.
+    const lifecycleWarnings = agentIds.flatMap((agentId) => {
+        const warning = lifecycleWarning(agentId);
+        return warning === undefined ? [] : [`${agentId}: ${warning}`];
+    });
+    return {
+        _tag: "AddConfiguredAgents",
+        agentIds,
+        configuredAgents: [...configured, ...agentIds],
+        retiredDetected,
+        lifecycleWarnings,
+        acceptWarnings: request.acceptWarnings ?? false,
+        scope: workspace.scope,
+    };
+});
+const addAgentStep = (scope, agentId) => ({
+    label: `Add ${agentId}`,
+    readiness: "ready",
+    artifact: membershipArtifact(scope, agentId, "updated"),
+    run: Effect.gen(function* () {
+        const workspace = yield* WorkspaceMutations;
+        yield* workspace
+            .addConfiguredAgent(agentId)
+            .pipe(Effect.mapError(workspaceChangeFailedToStepFailure));
+        return {
+            result: "success",
+            message: `Configured ${agentId}`,
+            artifact: membershipArtifact(scope, agentId, "updated"),
+        };
+    }),
+});
+/** Aggregate a filtered artifact's change from the targets that survived. */
+const aggregateArtifactChange = (targets, fallback) => {
+    if (targets.length === 0)
+        return fallback;
+    if (targets.some((target) => target.change === "created"))
+        return "created";
+    if (targets.some((target) => target.change === "updated"))
+        return "updated";
+    if (targets.some((target) => target.change === "removed"))
+        return "removed";
+    return "unchanged";
+};
+const materializationArtifact = (scope, agentIds) => ({
+    path: "managed agent artifacts",
+    scope,
+    agents: agentIds,
+    change: "updated",
+    targets: agentIds.map((agentId) => ({
+        path: `${agentId} managed agent artifacts`,
+        change: "updated",
+        agentIds: [agentId],
+    })),
+});
+/**
+ * A reconciliation step planned for the whole workspace reports every agent
+ * it touches. Adding agents only claims the arriving ones, so each artifact
+ * is narrowed to the targets that belong to them.
+ */
+const narrowToArrivingAgents = (artifact, agentIds) => {
+    if (artifact.targets === undefined || artifact.targets.length === 0)
+        return artifact;
+    const targets = artifact.targets.filter((target) => target.agentIds === undefined ||
+        target.agentIds.length === 0 ||
+        target.agentIds.some((agentId) => agentIds.includes(agentId)));
+    if (targets.length === 0)
+        return artifact;
+    const agents = artifact.agents?.filter((agentId) => agentIds.includes(agentId));
+    return {
+        ...artifact,
+        path: targets[0]?.path ?? artifact.path,
+        ...(agents === undefined || agents.length === 0 ? {} : { agents }),
+        change: aggregateArtifactChange(targets, artifact.change),
+        targets,
+    };
+};
+const attributeToArrivingAgents = (scope, agentIds, step) => {
+    if (step.readiness === "error")
+        return step;
+    const artifact = step.artifact === undefined
+        ? materializationArtifact(scope, agentIds)
+        : narrowToArrivingAgents(step.artifact, agentIds);
+    return {
+        ...step,
+        artifact,
+        run: Effect.gen(function* () {
+            const result = yield* step.run;
+            if (result.result === "error")
+                return result;
+            return result.artifact === undefined
+                ? { ...result, artifact: materializationArtifact(scope, agentIds) }
+                : { ...result, artifact: narrowToArrivingAgents(result.artifact, agentIds) };
+        }),
+    };
+};
+const addPlan = (candidate, steps) => ({
+    _tag: "Plan",
+    name: "Add coding agents",
+    description: Option.some(`Configure ${candidate.agentIds.join(", ")} and materialize installed extensions`),
+    presentation: {
+        verb: { imperative: "configure", past: "Configured", gerund: "Configuring" },
+        subject: { singular: "agent", plural: "agents" },
+    },
+    ...(candidate.lifecycleWarnings.length === 0
+        ? {}
+        : {
+            riskConditions: [
+                {
+                    level: "override-required",
+                    id: "retired-agent-lifecycle-warnings",
+                    policy: "accept-warnings",
+                    requiredFlag: "--accept-warnings",
+                    detail: candidate.lifecycleWarnings.join("; "),
+                },
+            ],
+        }),
+    jobs: [{ concurrency: 1, executionPolicy: "best-effort", steps }],
+});
+/**
+ * Preview or apply a settled add. The membership writes and the supplied
+ * reconciliation steps run inside one workspace transaction, and the
+ * transaction only settles once the workspace reports the arriving agents as
+ * configured.
+ */
+export const previewOrApplyAddConfiguredAgents = (candidate, execution, reconciliation) => Effect.gen(function* () {
+    const materialization = (reconciliation?.steps ?? []).map((step) => attributeToArrivingAgents(candidate.scope, candidate.agentIds, step));
+    const steps = [
+        ...candidate.agentIds.map((agentId) => addAgentStep(candidate.scope, agentId)),
+        ...materialization,
+    ];
+    const atomicSteps = yield* makeAtomicMembershipSteps({
+        steps,
+        transition: { kind: "add", agentIds: candidate.agentIds },
+    });
+    const prepared = yield* prepareExecutionCandidate(addPlan(candidate, atomicSteps));
+    return yield* resolveExecutionCandidate(prepared, execution);
+});
+/**
+ * Settle which agents a remove request takes out of membership, and the
+ * reconciliation state their outputs are cleaned up against.
+ *
+ * Removing every named agent when none of them is configured is a reported
+ * no-op; removing a mixture is a refusal, because the request described a
+ * workspace that does not exist. Cleaning up owned projections needs a
+ * complete desired graph — without one, AXM cannot tell its own output from
+ * a person's file, so it refuses rather than guess.
+ */
+export const prepareRemoveConfiguredAgents = (request) => Effect.gen(function* () {
+    const workspace = yield* WorkspaceMutations;
+    const agentIds = yield* validateAgentIds(request.ids);
+    const configured = yield* workspace.getConfiguredAgents();
+    const configuredSet = new Set(configured);
+    const missing = agentIds.filter((id) => !configuredSet.has(id));
+    if (missing.length === agentIds.length) {
+        return unchanged("already-absent", "All requested agents are already absent");
+    }
+    if (missing.length > 0) {
+        return yield* new WorkspaceConfigurationFailed({
+            category: "validation",
+            detail: `Agent is not configured: ${missing.join(", ")}`,
+            suggestions: [{ description: "Inspect configured agents.", cmd: "axm agents list" }],
+        });
+    }
+    const graph = yield* workspace.getDesiredStateGraph();
+    if (!graph.complete) {
+        return yield* new WorkspaceConfigurationFailed({
+            category: "validation",
+            detail: "Cannot safely clean agent projections while desired workspace state is incomplete",
+            suggestions: [{ description: "Inspect workspace facts.", cmd: "axm lint" }],
+        });
+    }
+    const departing = new Set(agentIds);
+    const remaining = configured.filter((agentId) => !departing.has(agentId));
+    return {
+        _tag: "RemoveConfiguredAgents",
+        agentIds,
+        configuredAgents: remaining,
+        reconciliation: {
+            desiredAgentIds: new Set([UNIVERSAL_AGENT_ID, ...remaining]),
+            expectedNames: expectedProjectionNames(graph),
+        },
+        baseDir: workspace.baseDir,
+        scope: workspace.scope,
+    };
+});
+const removeAgentStep = (scope, agentId) => ({
+    label: `Remove ${agentId}`,
+    readiness: "ready",
+    artifact: membershipArtifact(scope, agentId, "updated"),
+    run: Effect.gen(function* () {
+        const workspace = yield* WorkspaceMutations;
+        yield* workspace
+            .removeConfiguredAgent(agentId)
+            .pipe(Effect.mapError(workspaceChangeFailedToStepFailure));
+        return {
+            result: "success",
+            message: `Removed ${agentId}`,
+            artifact: membershipArtifact(scope, agentId, "updated"),
+        };
+    }),
+});
+const removePlan = (candidate, steps) => ({
+    _tag: "Plan",
+    name: "Remove coding agents",
+    description: Option.some(`Remove ${candidate.agentIds.join(", ")} and clean up managed artifacts`),
+    presentation: {
+        verb: { imperative: "remove", past: "Removed", gerund: "Removing" },
+        subject: { singular: "agent", plural: "agents" },
+    },
+    jobs: [{ concurrency: 1, executionPolicy: "best-effort", steps }],
+});
+/**
+ * Preview or apply a settled removal. The cleanup steps the application
+ * planned run before the membership writes and inside the same transaction,
+ * so a cleanup that cannot complete leaves the agent configured.
+ */
+export const previewOrApplyRemoveConfiguredAgents = (candidate, execution, reconciliation) => Effect.gen(function* () {
+    const steps = [
+        ...(reconciliation?.steps ?? []),
+        ...candidate.agentIds.map((agentId) => removeAgentStep(candidate.scope, agentId)),
+    ];
+    const atomicSteps = yield* makeAtomicMembershipSteps({
+        steps,
+        transition: { kind: "remove", agentIds: candidate.agentIds },
+    });
+    const prepared = yield* prepareExecutionCandidate(removePlan(candidate, atomicSteps));
+    return yield* resolveExecutionCandidate(prepared, execution);
+});
+// -----------------------------------------------------------------------------
+// List
+// -----------------------------------------------------------------------------
+const ConfiguredAgentRowSchema = Schema.Struct({
+    id: Schema.String,
+    name: Schema.String,
+    configured: Schema.Boolean,
+    detected: Schema.Boolean,
+    /** Instruction-projection health for a configured agent; `-` when not configured. */
+    instructions: Schema.String,
+    /** Whether the vendor still maintains the agent: active, deprecated, retired. */
+    lifecycle: Schema.String,
+});
+export const ConfiguredAgentInventorySchema = Schema.Struct({
+    items: Schema.Array(ConfiguredAgentRowSchema),
+    configured: Schema.Array(Schema.String),
+    detected: Schema.Array(Schema.String),
+    available: Schema.Array(Schema.String),
+    count: Schema.Number,
+});
+/**
+ * Report configured, detected, and available coding agents.
+ *
+ * The default view answers "what is in play here": the agents this workspace
+ * configures and the ones present on the machine. `universal` is materialized
+ * for every workspace and is never reported as a membership choice.
+ */
+export const listConfiguredAgents = (request = {}) => Effect.gen(function* () {
+    const workspace = yield* WorkspaceMutations;
+    const configured = yield* workspace.getConfiguredAgents();
+    const detected = yield* detectAgentsForScope(workspace.baseDir, workspace.scope).pipe(Effect.map((agents) => agents.map((agent) => agent.id)));
+    const configuredSet = new Set(configured);
+    const detectedSet = new Set(detected);
+    const instructionsConfig = yield* workspace.getInstructionsConfig();
+    const instructionHealth = Option.isSome(instructionsConfig) && instructionsConfig.value !== false
+        ? yield* observeInstructionProjection({
+            workspaceRoot: workspace.baseDir,
+            scope: workspace.scope,
+            configuredAgents: configured,
+            config: resolveInstructionsConfig(instructionsConfig.value),
+        }).pipe(Effect.map(({ status }) => new Map(status.items.map((item) => [item.agentId, item.health]))))
+        : new Map();
+    const baseIds = request.available === true || request.detected === true
+        ? CONFIGURABLE_AGENT_IDS
+        : CONFIGURABLE_AGENT_IDS.filter((id) => configuredSet.has(id) || detectedSet.has(id));
+    const items = baseIds
+        .filter((id) => request.detected !== true || detectedSet.has(id))
+        .map((id) => ({
+        id,
+        name: AGENTS[id].name,
+        configured: configuredSet.has(id),
+        detected: detectedSet.has(id),
+        instructions: configuredSet.has(id) ? (instructionHealth.get(id) ?? "manual") : "-",
+        lifecycle: agentLifecycle(id).state,
+    }));
+    return {
+        items,
+        configured: configured.filter((id) => id !== UNIVERSAL_AGENT_ID),
+        detected,
+        available: [...CONFIGURABLE_AGENT_IDS],
+        count: items.length,
+    };
+});
+/** The configured-agent membership use case. */
+export const ConfigureAgents = {
+    add: {
+        prepare: prepareAddConfiguredAgents,
+        previewOrApply: previewOrApplyAddConfiguredAgents,
+    },
+    remove: {
+        prepare: prepareRemoveConfiguredAgents,
+        previewOrApply: previewOrApplyRemoveConfiguredAgents,
+    },
+    list: listConfiguredAgents,
+};
+//# sourceMappingURL=configure-agents.js.map

package/dist/src/membership/validate-agent-ids.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Which coding-agent identifiers a membership or capability request may name.
+ *
+ * The configurable catalog is the whole answer: `universal` is materialized
+ * for every workspace and is never a membership choice, a hosted agent is
+ * installed through its vendor rather than through workspace configuration,
+ * and anything else is refused before a change is planned, naming the nearest
+ * supported id when one is close enough to be a typo.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as Effect from "effect/Effect";
+import { WorkspaceConfigurationFailed } from "../errors.js";
+export declare const dedupe: (values: ReadonlyArray<string>) => ReadonlyArray<string>;
+export declare const validateAgentIds: (ids: ReadonlyArray<string>) => Effect.Effect<ReadonlyArray<string>, WorkspaceConfigurationFailed>;
+//# sourceMappingURL=validate-agent-ids.d.ts.map

package/dist/src/membership/validate-agent-ids.js

@@ -0,0 +1,85 @@
+/**
+ * Which coding-agent identifiers a membership or capability request may name.
+ *
+ * The configurable catalog is the whole answer: `universal` is materialized
+ * for every workspace and is never a membership choice, a hosted agent is
+ * installed through its vendor rather than through workspace configuration,
+ * and anything else is refused before a change is planned, naming the nearest
+ * supported id when one is close enough to be a typo.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as Effect from "effect/Effect";
+import { HOSTED_AGENTS_BY_ID, HOSTED_AGENT_IDS, } from "@agentxm/extension-model/unstable/agent-capabilities";
+import { CONFIGURABLE_AGENT_IDS } from "@agentxm/extension-model/unstable/agents/types";
+import { WorkspaceConfigurationFailed } from "../errors.js";
+const configurableAgentIds = new Set(CONFIGURABLE_AGENT_IDS);
+const hostedAgentIds = new Set(HOSTED_AGENT_IDS);
+const isHostedAgentId = (id) => hostedAgentIds.has(id);
+const numberAt = (values, index) => values[index] ?? 0;
+const editDistance = (left, right) => {
+    const previous = Array.from({ length: right.length + 1 }, (_value, index) => index);
+    for (let leftIndex = 0; leftIndex < left.length; leftIndex += 1) {
+        const current = [leftIndex + 1];
+        for (let rightIndex = 0; rightIndex < right.length; rightIndex += 1) {
+            const substitutionCost = left[leftIndex] === right[rightIndex] ? 0 : 1;
+            current[rightIndex + 1] = Math.min(numberAt(current, rightIndex) + 1, numberAt(previous, rightIndex + 1) + 1, numberAt(previous, rightIndex) + substitutionCost);
+        }
+        previous.splice(0, previous.length, ...current);
+    }
+    return previous[right.length] ?? left.length;
+};
+const nearestAgentId = (input) => {
+    let best;
+    for (const id of CONFIGURABLE_AGENT_IDS) {
+        const distance = editDistance(input, id);
+        if (best === undefined || distance < best.distance) {
+            best = { id, distance };
+        }
+    }
+    if (best === undefined)
+        return undefined;
+    return best.distance <= Math.max(3, Math.floor(input.length / 2)) ? best.id : undefined;
+};
+export const dedupe = (values) => Array.from(new Set(values));
+export const validateAgentIds = (ids) => Effect.gen(function* () {
+    for (const id of ids) {
+        if (id === "universal") {
+            return yield* new WorkspaceConfigurationFailed({
+                category: "validation",
+                detail: "`universal` is always materialized automatically and cannot be added or removed.",
+                suggestions: [{ description: "Choose one of the configurable coding-agent IDs." }],
+            });
+        }
+        if (isHostedAgentId(id)) {
+            const agent = HOSTED_AGENTS_BY_ID[id];
+            return yield* new WorkspaceConfigurationFailed({
+                category: "validation",
+                detail: `${agent.name} is a hosted agent and cannot be added to local workspace configuration. ${agent.installTarget.instructions}`,
+                suggestions: [
+                    {
+                        description: `Open the ${agent.name} skill installation guide.`,
+                        url: agent.installTarget.docs,
+                    },
+                ],
+            });
+        }
+        if (!configurableAgentIds.has(id)) {
+            const nearest = nearestAgentId(id);
+            return yield* new WorkspaceConfigurationFailed({
+                category: "validation",
+                detail: `Unknown agent ID: ${id}`,
+                suggestions: [
+                    nearest === undefined
+                        ? { description: "Inspect supported agent IDs.", cmd: "axm agents list --available" }
+                        : {
+                            description: `Did you mean "${nearest}"?`,
+                            cmd: `axm agents add ${nearest}`,
+                        },
+                ],
+            });
+        }
+    }
+    return dedupe(ids);
+});
+//# sourceMappingURL=validate-agent-ids.js.map

package/dist/src/{initialization-interaction.d.ts → setup/initialization-interaction.d.ts}

@@ -2,7 +2,7 @@ import * as Effect from "effect/Effect";
 import * as Layer from "effect/Layer";
 import * as ServiceMap from "effect/Context";
 import type { AgentDescriptor } from "@agentxm/extension-model/unstable/agents/types";
-import type { WorkspaceConfigurationFailed } from "./errors.js";
+import type { WorkspaceConfigurationFailed } from "../errors.js";
 import type { WorkspaceScope } from "@agentxm/extension-model/unstable/workspace-scope";
 import type { SetupScopeSupportCategory } from "@agentxm/workspace-state";
 declare const WorkspaceInitializationCancelled_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 & {

package/dist/src/{initialization.d.ts → setup/initialization.d.ts}

@@ -10,10 +10,10 @@ import * as FileSystem from "effect/FileSystem";
 import * as Path from "effect/Path";
 import * as Effect from "effect/Effect";
 import { type ConfigurableAgentId } from "@agentxm/extension-model/unstable/agents/types";
-import { WorkspaceConfigurationFailed } from "./errors.js";
+import { WorkspaceConfigurationFailed } from "../errors.js";
 import { type Settings } from "@agentxm/workspace-state";
 import type { WorkspaceMutationsOptions } from "@agentxm/workspace-state";
-import { type WorkspaceLocation } from "@agentxm/workspace-state";
+import { type LocatedWorkspace } from "@agentxm/workspace-state";
 export interface SetupAgentCandidate {
     readonly id: ConfigurableAgentId;
     readonly name: string;
@@ -127,24 +127,24 @@ export declare const initializeProjectWorkspace: (localDir: string, options: Wor
                     readonly [x: string]: string;
                 };
                 readonly url?: string | undefined;
+                readonly command?: string | undefined;
+                readonly kind?: "sourced" | undefined;
                 readonly headers?: {
                     readonly [x: string]: string;
                 } | undefined;
-                readonly command?: string | undefined;
                 readonly args?: readonly string[] | undefined;
-                readonly kind?: "sourced" | undefined;
             } | {
                 readonly enabled: boolean;
+                readonly kind: "inline";
                 readonly env: {
                     readonly [x: string]: string;
                 };
-                readonly kind: "inline";
                 readonly url?: string | undefined;
                 readonly source?: undefined;
+                readonly command?: string | undefined;
                 readonly headers?: {
                     readonly [x: string]: string;
                 } | undefined;
-                readonly command?: string | undefined;
                 readonly args?: readonly string[] | undefined;
             };
         };
@@ -159,7 +159,7 @@ export declare const initializeProjectWorkspace: (localDir: string, options: Wor
     };
     agentCandidates: readonly SetupAgentCandidate[];
     confirmed: boolean;
-}, WorkspaceConfigurationFailed | import("./initialization-interaction.js").WorkspaceInitializationCancelled | import("@agentxm/workspace-state").SettingsWriteError | import("@agentxm/workspace-state").LockfileWriteError | import("@agentxm/extension-workspace").InstructionMaintenanceFailure, FileSystem.FileSystem | Path.Path>;
+}, WorkspaceConfigurationFailed | import("@agentxm/workspace-state").SettingsWriteError | import("@agentxm/workspace-state").LockfileWriteError | import("./initialization-interaction.js").WorkspaceInitializationCancelled | import("@agentxm/workspace-projection").InstructionMaintenanceFailure, FileSystem.FileSystem | Path.Path>;
 interface WorkspaceInitializationState {
     readonly settings: Settings;
     readonly initialized: boolean;
@@ -174,7 +174,7 @@ interface WorkspaceInitializationState {
  *
  * @param workspaceRoot - Path to the user workspace root
  */
-export declare const ensureUserWorkspaceInitialized: (workspaceRoot: string, options: WorkspaceMutationsOptions) => Effect.Effect<WorkspaceInitializationState, WorkspaceConfigurationFailed | import("./initialization-interaction.js").WorkspaceInitializationCancelled | import("@agentxm/workspace-state").WorkspaceSnapshotError | import("@agentxm/workspace-state").SettingsWriteError | import("@agentxm/workspace-state").LockfileWriteError, FileSystem.FileSystem | Path.Path>;
+export declare const ensureUserWorkspaceInitialized: (workspaceRoot: string, options: WorkspaceMutationsOptions) => Effect.Effect<WorkspaceInitializationState, WorkspaceConfigurationFailed | import("@agentxm/workspace-state").SettingsWriteError | import("@agentxm/workspace-transactions").WorkspaceSnapshotError | import("@agentxm/workspace-state").LockfileWriteError | import("./initialization-interaction.js").WorkspaceInitializationCancelled, FileSystem.FileSystem | Path.Path>;
 /**
  * Ensure project workspace is initialized, returning local settings.
  *
@@ -184,14 +184,14 @@ export declare const ensureUserWorkspaceInitialized: (workspaceRoot: string, opt
  * @param options - WorkspaceMutations options
  * @returns Effect yielding local Settings
  */
-export declare const ensureProjectWorkspaceInitialized: (localDir: string, options: WorkspaceMutationsOptions) => Effect.Effect<WorkspaceInitializationState, WorkspaceConfigurationFailed | import("./initialization-interaction.js").WorkspaceInitializationCancelled | import("@agentxm/workspace-state").SettingsWriteError | import("@agentxm/workspace-state").LockfileWriteError | import("@agentxm/extension-workspace").InstructionMaintenanceFailure, FileSystem.FileSystem | Path.Path>;
+export declare const ensureProjectWorkspaceInitialized: (localDir: string, options: WorkspaceMutationsOptions) => Effect.Effect<WorkspaceInitializationState, WorkspaceConfigurationFailed | import("@agentxm/workspace-state").SettingsWriteError | import("@agentxm/workspace-state").LockfileWriteError | import("./initialization-interaction.js").WorkspaceInitializationCancelled | import("@agentxm/workspace-projection").InstructionMaintenanceFailure, FileSystem.FileSystem | Path.Path>;
 export declare const bootstrapWorkspace: (options: WorkspaceMutationsOptions) => Effect.Effect<{
-    location: WorkspaceLocation;
+    location: LocatedWorkspace;
     settings: Settings;
     initialized: boolean;
     wouldInitialize: boolean;
     cancelled: boolean;
     agentCandidates: ReadonlyArray<SetupAgentCandidate>;
-}, WorkspaceConfigurationFailed | import("./initialization-interaction.js").WorkspaceInitializationCancelled | import("@agentxm/workspace-state").SettingsWriteError | import("@agentxm/workspace-state").LockfileWriteError | import("@agentxm/extension-workspace").InstructionMaintenanceFailure, FileSystem.FileSystem | Path.Path>;
+}, WorkspaceConfigurationFailed | import("@agentxm/workspace-state").SettingsWriteError | import("@agentxm/workspace-state").LockfileWriteError | import("./initialization-interaction.js").WorkspaceInitializationCancelled | import("@agentxm/workspace-projection").InstructionMaintenanceFailure, FileSystem.FileSystem | Path.Path>;
 export {};
 //# sourceMappingURL=initialization.d.ts.map

package/dist/src/{initialization.js → setup/initialization.js}

@@ -16,7 +16,7 @@ import { CONFIGURABLE_AGENTS_BY_ID } from "@agentxm/extension-model/unstable/age
 import { detectAgentScopeResults } from "@agentxm/agent-integration";
 import { AGENTS } from "@agentxm/extension-model/unstable/agents/registry";
 import { isConfigurableAgentId, } from "@agentxm/extension-model/unstable/agents/types";
-import { WorkspaceConfigurationFailed } from "./errors.js";
+import { WorkspaceConfigurationFailed } from "../errors.js";
 import { isGitManaged } from "@agentxm/extension-sources";
 import { LOCKFILE_NAME } from "@agentxm/extension-model/unstable/workspace-files";
 import { LOCKFILE_VERSION, writeLockfileAtPath } from "@agentxm/workspace-state";
@@ -27,10 +27,10 @@ import { makeWorkspaceReadModel, WorkspaceReadModelConfig } from "@agentxm/works
 import { WorkspaceInitializationInteraction, } from "./initialization-interaction.js";
 import { locateWorkspace, resolveUserHome } from "@agentxm/workspace-state";
 import { setupScopeSupport } from "@agentxm/workspace-state";
-import { protectWorkspacePath } from "@agentxm/workspace-state";
+import { protectWorkspacePath } from "@agentxm/workspace-transactions";
 import { LOCK_FILENAME } from "@agentxm/workspace-state";
 import { SETTINGS_FILENAME } from "@agentxm/extension-model/unstable/workspace-files";
-import { resolveInstructionTarget, syncInstructions } from "@agentxm/extension-workspace";
+import { resolveInstructionTarget, syncInstructions } from "@agentxm/workspace-projection";
 const SELECT_AGENTS_PROMPT_MISSING = new WorkspaceConfigurationFailed({
     category: "usage",
     detail: "Interactive prompt required: Select agents to configure",